DEV Community: Mica

Accessible and Functional Quantity Spinbutton Pattern

Mica — Wed, 13 May 2026 10:35:07 +0000

Hey! This is Mica writing, a human not an AI agent (nothing against them, not discrimination of any kind is allowed here). Just a brief disclaimer before starting: this post was non AI-generated (I am not going to lie, I tried to use it for some research but since the errors I found were not properly documented the AI invented answers, lol) because I felt the urgent need to start using my brain and hands to craft something from scratch. If you are a human, let's connect, at the end you will find the ways to reach me. I am on a doom scrolling detox so you won't find me on instagram or twitter now. So, I have a question: Is there anybody out there?

Introduction

If you work on an e-commerce, a booking (hotels, flights, trains, etc) platform, a restaurant reservation system maybe you are familiar with the quantity spinbutton component. It is a common UI pattern that allows users to select a quantity of items they want to purchase or book. It is configured by two buttons and one input; one button for increasing the quantity, another button to decrease the quantity and an input where the user is able to type the desired amount or increase/decrease the quantity using the Up Arrow or Down Arrow accordingly. Sounds simple, and yes it is, but it is also a critical flow in the user journey. If it's badly implemented, you can not only be potentially losing sales (translation: losing money, which is important) but also creating a frustrating experience for users with disabilities (which should be more important than money, but those are my morals and ethics, lol). My goal in this article is setting a clear basis of a non-negotiable structure and behavior of the quantity spinbutton pattern and from there, explore different variations depending on the use case.

Disclaimer: This is not a written-in-stone guide, I can make mistakes, so please let me know if you disagree with something.

Expected behaviors

Keyboard

Key	Action
Up Arrow	Increases the value by its step value
Down Arrow	Decreases the value by its step value
Home	If the spinbutton has a minimum value, sets the value to its minimum
End	If the spinbutton has a maximum value, sets the value to its maximum
Command or Fn + Right Arrow	Substitute for Apple's keyboards that do not have a End key to set the value to its maximum
Command or Fn + Left Arrow	Substitute for Apple's keyboards that do not have a End key to set the value to its minimum

Screen Readers

NVDA Navigation

You can download NVDA here and it's only available for the Windows operating system. It is compatible with Chrome, Firefox and Edge browsers.
Long story short, an NVDA modifier key is needed to navigate using this screen reader. The modifier key can be Insert key (by default) or it can be remapped to the Caps Lock in the settings. Two modes for different purposes can be found:

Browse Mode: Browse mode is used when reading documents or web pages.
Focus Mode: Focus mode is used when the user enters a form or other fields that require user input.

NVDA automatically switches between Browse and Focus modes, but the user can toggle them using Insert + Space Bar.
| Command | Task |
|--------|-----|
| Down Arrow (Browse Mode) | Read next item |
| Enter or Space Bar | Activate button |
| Down Arrow (Focus Mode) | Decrement by step |
| Up Arrow (Focus Mode) | Increment by step |
| Home | Jump to aria-valuemin (via your custom handler) |
| End | Jump to aria-valuemax (via your custom handler) |
| Tab | Commit value, leave the field, return to browse mode |

VoiceOver Navigation

If you are a macOS user, VoiceOver comes built into the operating system of your MacBook. It's compatible with the Safari browser.
VoiceOver uses the Control and Option keys before each command. This combination is called VO and these keys can be locked/unlocked by pressing Control + Option + ;(semicolon) all together.

Command	Task
Tab/Shift + Tab	Go to next/previous focusable item (link, button, input, etc.)
VO + Space Bar	Activate a link or form control
VO + Right Arrow	Move VO cursor to next element (not limited to focusable items)
VO + Left Arrow	Move VO cursor to previous element
VO + Shift + Down Arrow	Once the VO cursor is on the spinbutton, this combination enters the spinbutton
Up Arrow	Once inside the spinbutton, increment by step
Down Arrow	Once inside the spinbutton, decrement by step
Home	Jump to aria-valuemin (via your custom handler)
End	Jump to aria-valuemax (via your custom handler)

Gestures VoiceOver - iOS

If you are an iOS user, VoiceOver is the screen reader by default on the operating system of your iPhone. It's compatible with the Safari browser. Unlike VoiceOver on macOS, VoiceOver on iOS, the navigation is controlled by finger gestures.

Gesture	Task
Swipe next	Read next item
Swipe left	Read previous item
Double-tap	Activate (link, button)
Swipe up	If the VO cursor is over the spinbutton, increase the value
Swipe down	If the VO cursor is over the spinbutton, decrease the value

Gestures Talkback - Android

If you are an Android user, TalkBack is the default screen reader on the operating system of your mobile. It's compatible with Chrome, Firefox and Edge. Like VoiceOver for iOS, the navigation is controlled by gestures with the fingers.

Gesture	Task
Swipe next	Read next item
Swipe left	Read previous item
Double-tap	Activate (link, button)
Swipe up	If the VO cursor is over the spinbutton, increase the value
Swipe down	If the VO cursor is over the spinbutton, decrease the value

Pattern A: APG (ARIA Authoring Practices Guide) Spinbutton by W3C

Currently everyone is following the APG (ARIA Authoring Practices Guide) as if it were the bible and not as what it is: a guide, a very useful guide, btw, THE guide. Everything written there is considered a commandment written in stone by non-accessibility experts (the people behind W3C are doing an amazing work and I only have gratitude and admiration towards them) and this might be a problem. The intention is good but the execution is not. When you first land on the APG Spin Button Pattern, the first thing you see is an alert with the following warning:

The code in this example is not intended for production environments. Before using it for any purpose, read this to understand why.

and then a list of reasons why you should be critical of the pattern provided. In this case, the most important one is:

Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

So, what does this mean? Well, a couple of important things:

Always be critical of everything (a rule for life, tho)
Keep in mind the necessities and limitations of your product/business, and (more importantly) comply with the regulations and legislation in order to guarantee freedom of navigation through your product for users with disabilities.
There is always (well, almost 80% always) an HTML equivalent.

After this brief introduction to the APG, I would like to dive into its Spinbutton pattern. W3C (The World Wide Web Consortium) presents us a solution using the WAI-ARIA role="spinbutton" on the input tag instead of using the native HTML solutions provided by the tag itself, the buttons are removed from the focus flow because they have a tabindex="-1" but they are still operable via mouse and by using screen readers. Only the tag with the role="spinbutton" is not fully semantic by itself and we will need to add the keyboard and screen reader functionalities programmatically and make it semantic by adding properties and states to the input element.

In the accessibility field we have a mantra: No ARIA is better than Bad ARIA. You should be extra careful when using ARIA because, if it is not used correctly, you will end up creating more issues than solving them. Again, the intention is good but the outcome is more barriers. Last month, WebAIM org launched its annual report for 2026 about the state of accessibility in over 1 million pages: The WebAIM Million. The report shows that in 2026, accessibility errors increased by 10.1% according to the WCAG 2.2 Level A/AA conformance failures and concluded with the following reflection:

The 2026 WebAIM Million analysis found notable increases in both the number of detected accessibility errors and number of pages with WCAG conformance failures, reversing a trend of gradual accessibility improvements in recent years. A primary concern is the significant increase in home page complexity and ARIA code, both of which correlate to increased detectable errors. These trends likely reflect broader shifts in web development including increased reliance on 3rd party frameworks and libraries and automated or AI-assisted coding practices (“vibe coding”). Home pages are getting larger and more technologically complex at an alarming rate, making accessibility more difficult to achieve and maintain. A key takeaway from this year's report is improving accessibility at scale will require both better practices and simpler systems. Alternatively, complex systems need to do a better job of focusing on accessibility fundamentals.

It's not a surprise that creating components using AI without questioning the output will end up creating more barriers for users with disabilities, and sloppier websites overall. Also, the lack of native and accessible examples on the web makes the AI coding agents return inaccessible components, but okay not everything is the fault of the AI, to be honest.

Functional Example – APG

you can find the functional example here

APG code

<input 
  id="add-to-bag"
  role="spinbutton"
  type="text"
  inputMode="numeric"
  pattern="[0-9]*"
  autoComplete="off"
  spellCheck="false"
  aria-valuemin={MIN}
  aria-valuemax={MAX}
  aria-valuenow={isValid ? numeric : undefined}
  aria-valuetext={value}
  aria-invalid={!isValid || undefined}
  aria-describedby={isValid ? 'help-add-to-bag' : 'help-add-to-bag error-add-to-bag'}
  value={value}
  onChange={handleChange}
  onKeyDown={handleKeyDown}
/>

id: to relate the <input /> with the <label> element
role="spinbutton": this is a WAI-ARIA role that allows the user to increase and decrease a value within a given range. This role can be used on <input> or on a non-semantic element such as <div>. The APG pattern for the spinbutton component proposes the <input> with a type="text" making the development more challenging. The expected keyboard behavior for a spinbutton is being able to increment or decrement the value by pressing the up/down arrow accordingly. Since this is not a native interaction of the role="spinbutton" or of the <input type="text" />, we have to programmatically cover these behaviors. The spinbutton element with type text generally comes with two buttons (one for decrement and the other to increment the value) that should be excluded from the navigation flow by adding tabIndex={-1}.
type="text": implies that the spinbutton will receive a value of type text, which is a pain because it means that we have to transform the type text to type number later.
inputMode="numeric": since the input is type text, we have to make the browsers know which virtual keyboard they will have to display. This is vital for mobile navigation because without the value numeric the virtual keyboard display to enter a value will be a QWERTY instead of a numeric input keyboard.
pattern="[0-9]*": again, since the input is type="text", we have to use a regex to only admit values of type number. (This attribute was not on the APG example, but I cannot help myself).
autocomplete="off": it is used on inputs that take a text or numeric value as input to prevent the browser from automatically entering a value into this field. (again, my take, not on APG example).
aria-valuemin="[NUMBER]": sets the minimum value allowed for the spinbutton. The default is 0, if no value is passed.
aria-valuemax="[NUMBER]": sets the maximum value allowed for the spinbutton. The default is 100, if no value is passed.
aria-valuenow="[number]": here things start to get interesting. By definition, this attribute defines the current value for a range widget (meter, scrollbar, slider and spinbutton). Since we are not using a semantic solution, this value should be updated programmatically. Also, this value is intended for numeric values and APG provides an example where the spinbutton is being considered as a text, so we have to also transform the value from type string to type number. This is not everything! Since the spinbutton is not correctly typed, the announcement of the current value will be done as a percent by VoiceOver (macOS and iOS) announces it as a percent, TalkBack on Pixel 10 does not announce it at all, and NVDA announces it correctly. You can test it on the APG example.
aria-invalid="[boolean]": indicates that the current value is invalid.
aria-describedby="[IDREF]": this attribute is used to establish a relationship between widgets or groups and the text that describes them.

Conclusion for the APG Spinbutton Pattern

To articulate a conclusion for this pattern, I drew on Core Accessibility API Mappings 1.2 which is a guide that specifies how WAI-ARIA roles, states, and properties are expected to be exposed by user agents (browsers, in this case) via platform accessibility APIs.

Since a spinbutton is considered a range widget, it's implicitly expected to receive a value of type number even though the APG pattern tells us otherwise. By implementing a role spinbutton in a text input, we will be going against the nature of the role, which leads us to do extra work to make it work correctly.
The pattern is good but we can make it better, with some browser limitations (the party can never be enjoyed in peace), with the native HTML solution as we will see below.

Pattern B: Native HTML solution

Unfortunately, nothing is perfect; the native HTML solution for spinbutton is tempting because it works well in most cases BUT has a few limitations that aren't HTML-related but browser-related, buuuh.

Browsers have different engines to create what we colloquially know as Accessibility Tree. This tree is just an object with nodes. Every node includes information about the HTML elements and attributes. Finally, this object is being exposed to the Accessibility APIs of every operating system so they can translate the information and make it readable to assistive technologies. Here is where the things get complicated because every browser engine sometimes interprets things differently. Below, you can find a list of the browser engines for the different browsers and the Accessibility APIs they support.

Blink: this is the browser engine for Chrome, Edge, Opera and Brave (all browsers based on Chromium) which means all the browsers are going to have the same Accessibility Tree as the one we can see on the following image:

Supported on the following Accessibility APIs:

Windows: IAccessible, IAccessible2 and UIAutomation
Mac: NSAccessibility (funny thing here is that Blink creates a more accurate and complete node than WebKit and VoiceOver announces the spinbutton better on Chrome, as we are going to read later)
Linux: ATK
Android: AccessibilityNodeInfo and AccessibilityNodeProvider. I opened a ticket for this operating system because it is not exposing the spinbutton correctly preventing the user from having an accessible experience. The ticket to Android can be seen here
- Gecko: this is the browser engine for Firefox. The Accessibility Tree it creates, in my opinion, is the most complete and it is compatible with the following Accessibility APIs:
Windows: IAccessible, IAccessible2 and UIAutomation
Mac: mozAccessible
Linux: ATK
- WebKit: this is the browser engine for Safari in macOS and iOS. Here is where our problems start. The engine does not recognize the element as a spinbutton but as a role="textbox" if we don't explicitly pass the role="spinbutton" to the <input type="text" />. This is an issue because the VoiceOver screen reader in both devices, desktop and mobile, will prevent the user from having an accessible experience, the same issue that I faced on Android. Again, I ended up opening a ticket to Apple about this behavior. The ticket to Apple can be seen here

Functional Example – HTML

The native functional example can be found here

HTML native code

<input 
  id="add-to-bag-native"
  type="number"
  role="spinbutton"
  autoComplete="off"
  min={MIN}
  max={MAX}
  step={STEP}
  value={value}
/>

id: same thing as in the APG pattern
type="number": this is what natively converts an input into a spinbutton and restricts it to numeric values. It natively supports supports increasing and decreasing the value by: pressing the native controls that come with the input type="number" (see/read/perceive the image below), pressing Up Arrow or Down Arrow, or swiping (on mobile with the screen readers on).

The appearance of these arrows inside the input comes by default and we can override it if we provide another mechanism to substitute the buttons themselves; we already did that with the custom buttons to increase and decrease the value, so we are good to go.

  input[type="number"] {
    appearance: textfield;
  }

  input[type="number"]::-webkit-outer-spin-button,
  input[type="number"]::-webkit-inner-spin-button {
    -webkit-appearance: none;
    margin: 0;
  }

appearance: textfield;, we need it to strip the native spinbutton styling in Firefox
::-webkit-outer-spin-button and ::-webkit-inner-spin-button are pseudo-selectors that only Blink and WebKit recognize and the -webkit-appearance: none property strips the native spinbutton styling in Chrome and Safari.
- role="spinbutton": well, having in mind all the compatibility issues we have in different browsers, I found out that if you only pass the WAI-ARIA role="spinbutton" magically they all disappear. So, there is no harm in adding it to prevent headaches in the future. This post was built for this moment, you can thank me.
- autoComplete="off": just the same as in the APG example
- min={NUMBER}: the minimum value to accept for this input and should be less than or equal to the maximum value. If a value that isn't a valid number is specified, then the input has no minimum.
- max={NUMBER}: the maximum value to accept for this input and should be greater than or equal to the minimum value.
- step={NUMBER}: defines the allowed interval between valid values. The default is 1 and only accepts integers.
- value={NUMBER}: a number representing the value of the number entered into the input

Conclusion for the HTML native solution

If you want to have a functional, accessible and widely supported across browsers spinbutton component, I recommend using my solution and to always go to the native solutions and, if you do not feel comfortable enough, talk to your trustworthy accessibility expert. This native example with the workaround of adding a WAI-ARIA role="spinbutton" to force its semantic value on some browser engines was tested on:

Chrome (version 148) + macOS (Tahoe version 26.4.1) + VoiceOver
Chrome (version 148) + iOS (version 26.4.1)/ iPhone pro 15 + VoiceOver
Chrome (version 148) + Windows 11 + NVDA
Chrome (version 148) + Android/Pixel 10 (version 16) + TalkBack
Firefox (version 150) + Windows 11 + NVDA
Firefox (version 150) + macOS (Tahoe version 26.4.1)
Safari (version 26.4) + macOS (Tahoe version 26.4.1) + VoiceOver
Safari (version 26.4) + iOS (version 26.4.1) + VoiceOver

What I did not cover but it's important to mention: the Home and End keyboard shortcuts mentioned on the Keyboard section are not provided natively so you have to cover them programmatically. Also, some keyboards, such as Apple's keyboards (always Apple) do not have keys for Home and End and they are substituted by the combination Command or or Fn + Right/Left Arrows so you have to cover this combination as well. It's just a function of a 9-line function, nothing too exceptional, you should contemplate it.

  const handleKeyDown = (ev: KeyboardEvent<HTMLInputElement>) => {
    if (ev.key === 'End' || (ev.metaKey && ev.key === 'ArrowRight')) {
      ev.preventDefault()
      setValue(MAX)
    } else if (ev.key === 'Home' || (ev.metaKey && ev.key === 'ArrowLeft')) {
      ev.preventDefault()
      setValue(MIN)
    }
  }

Final Thoughts

Having a semantic, functional and accessible spinbutton on your e-commerce will not only contribute to improving the overall internet experience to everyone but it will leverage your product and increase your sales. A win-win for all parties involved; you get the money, the user, no matter how he/she/they are navigating, gets the product.
According to WHO more than 2.5 billion people need one or more assistive products to to meet their daily needs, and one of those needs is the right to navigate freely through the web. You do not really know who is navigating through your website behind the screen, could be a human with different needs or now an AI AGENT (!!!!). Omg, a new party entered the game and should be contemplated too. Nowadays, some users are relying on autonomous purchase bots, voice shopping assistants or AI browsing agents. These AI assistants base their navigation on the web in the same way as any other assistive technology: they consume the data provided by the Accessibility Tree. Amazing.

Well, we learned that: a new player entered the game (AI assistants), the native HTML solution is always the best option (might be buggy but it's the browser's fault) and you should always be critical and test everything you are building.

You can find me on:

email: micaela.avigliano@gmail.com
linkedin: https://www.linkedin.com/in/micaelaavigliano/

Accessible Pretext demo

Mica — Tue, 31 Mar 2026 13:07:24 +0000

What I did

I took the demo for a editorial engine built with pretext by Cheng Lou and I made it fully accessible, with semantic HTML structure, keyboard operability, screen reader support, and prefers-reduced-motion compliance. The result is a high-performance text layout demo that meets WCAG 2.2 success criteria while not compromising aesthetics and performance. The orbs are still draggable with the mouse but I also added the possibility of moving them using the keyboard.

The app uses a dual rendering system. At normal zoom, pretext powers a visual stage where text lines are individually positioned and wrap dynamically around the orbs as circular obstacles. Underneath, a native HTML <article> with CSS column-count remains in the DOM for screen readers, copy/paste, and find-in-page. At high zoom (≥150%) or narrow viewports (<500px), the pretext stage is removed entirely and the native HTML article becomes the visible layout, ensuring text is always fully readable, selectable, and copyable. A pretext-rendered drop cap provides the decorative initial letter in the visual stage, while CSS ::first-letter handles it in the native fallback.

Pretext library usage

Pretext powers the orb animation system. The following APIs are available in the project:

API	Purpose	Where used
`prepareWithSegments()`	Measures and caches word widths for text blocks	Body text preparation on font load
`layoutNextLine()`	Lays out one line of text at a given max width	Core layout loop — wraps text around orb obstacles
`layoutWithLines()`	Lays out all lines of a prepared text block	Headline fitting to available width/height
`walkLineRanges()`	Iterates line ranges without allocating line objects	Text measurement utilities

Accessibility improvements

Semantic HTML structure

The app uses proper HTML5 landmarks and semantic elements:

<header>: Fixed bar with controls and interaction hints
<main>: Primary content area
<article lang="es">: Full readable text as native HTML; lang="es" switches screen readers to Spanish pronunciation
<section>: Orb container with descriptive aria-label, exposed as a named region
<footer>: Performance stats and credits
<kbd>: Keyboard shortcuts styled as keycaps. aria-hidden prevents SR double-announcement; sr-only siblings provide the readable text
<cite>: Book title attribution
<nav>: Keyboard shortcuts and credits navigation

Keyboard accessibility

Every interactive element is operable without a mouse:

Action	Key	With VoiceOver
Toggle global pause	`Esc`	`Esc`
Navigate to orbs	`Tab`	`Tab`
Move focused orb	`Arrow keys`	`Option + Arrow keys`
Pause/resume individual orb	`Space`	`Space`

Orbs are native <button> elements. aria-roledescription="draggable orb" augments the role announcement so the user understands these are not ordinary buttons. Each orb's aria-label is dynamic and encodes its position in the set, the available interactions, and its current pause state.

Screen reader orb interaction discovery

When a VoiceOver user tabs to an orb, they hear: "Golden orb, 1 of 5. Use Option plus arrow keys to move. Press Space to pause." The instruction lives inside the aria-label because VoiceOver captures plain arrow keys for its own navigation; the page tells the user which key combination it can receive (Option + Arrow) instead of attempting to override the screen reader. When the orb is paused, the label changes to "Press Space to resume."

Screen reader support

aria-live="polite": Announces orb selection, pause/resume, and state changes without interrupting the user
aria-pressed: Toggle buttons communicate their on/off state
aria-label: Every interactive element has a descriptive, dynamic label

`prefers-reduced-motion` support

When the user's OS or browser has reduced motion enabled:

All orb animation stops, orbs render at their initial positions, static
CSS scroll-snap-type and scroll-behavior: smooth are disabled
CSS transitions and animations are suppressed globally via animation-duration: 0.01ms !important
A toggle button allows users to override this preference in-app

Pause control

Global pause (button or Esc): Stops all orbs. Paused orbs freeze in their document position and don't move when the user scrolls.
Individual pause (click or Space on a focused orb): Only that orb stops. Other orbs keep moving. This allows users to control exactly which elements are in motion.
The global pause button reflects the aggregate state. If all orbs are individually paused, it shows "Play"; if all are moving, it shows "Pause".

Text content and layout

Dual rendering: pretext stage + native HTML

Implementation details behind the dual layout described above:

Pretext visual stage (aria-hidden="true"): Each line is an absolutely positioned <div> laid out by layoutNextLine(), wrapping around orbs as circular obstacles. The stage's height is computed from the lowest line position.
Native HTML article: When the pretext stage is active, the <article lang="es"> is visually hidden with position: absolute; left: -9999px (not display: none, so AT still reads it).
A useNativeLayout state derived from window.outerWidth / window.innerWidth decides which mode is active.

Viewport	Columns (both modes)
> 1000px	3 columns
641-1000px	2 columns
≤ 640px	1 column

Text wrapping around orbs

In the pretext stage, each orb's position and radius are converted to a circular obstacle via orbToObstacle(). The layout engine (layoutAllText()) feeds these obstacles to layoutNextLine(), which shortens or shifts lines to flow around the orbs in real time as they move.

Headline fitting

The headline is dynamically sized using fitHeadline(), which uses pretext's layoutWithLines() to find the largest font size that fits the headline within the available width and a max height (35% of viewport, or 20% on short screens). Each headline line is rendered as a separate absolutely positioned element.

Drop cap

In the pretext stage, the first character of the first paragraph is rendered as a positioned <div> spanning 3 body lines in height. The layout engine reserves a rectangular region for the drop cap and flows the first paragraph's text around it. In native mode, CSS ::first-letter provides the same effect.

Dynamic header clearance

The article's padding-top uses a CSS custom property --header-h set by a ResizeObserver on the fixed header. In the pretext stage, the top gutter is computed as Math.max(GUTTER, headerHeight + 8). This ensures content is never hidden behind the header at any zoom level or viewport size.

Mobile and responsive behavior

Orbs and pretext stage hidden on small screens and high zoom

At the 500px / 150%-zoom threshold, React conditionally unmounts the orb <section> and the pretext stage entirely (not display: none), and useNativeLayout also halts the renderFrame loop so no layout work runs in the background.

Zoom detection uses window.outerWidth / window.innerWidth: when the user zooms in, innerWidth shrinks while outerWidth stays constant, giving the actual zoom ratio.

Collapsible header at high zoom

At 200%+ zoom or viewports below 500px, the header switches to a compact mode where all controls and keyboard shortcuts collapse behind a native <details>/<summary> toggle, preventing the fixed header from consuming the viewport at high magnification.

A ResizeObserver on the header keeps the --header-h CSS custom property in sync as it expands or collapses, so article content always clears it without overlap.

Mobile header and footer

On screens below 640px:

The header collapses to a single toggle (same <details>/<summary> mechanism as high zoom)
The footer stacks vertically (stats centered, credits below)
Button text and hint font sizes reduce for touch targets
Text reflows to a single readable column

Scroll snapping

html { scroll-snap-type: y proximity; scroll-behavior: smooth; } snaps near-alignments without trapping keyboard scroll (Space, Page Down, arrows keep working because the type is proximity, not mandatory). Under prefers-reduced-motion: reduce, both properties fall back to auto / none.

WCAG success criteria

Criterion	Level	Status	Notes
1.3.1 Info and Relationships	A	Pass	Semantic HTML conveys structure programmatically
1.3.2 Meaningful Sequence	A	Pass	DOM order matches visual reading order
1.3.4 Orientation	AA	Pass	Layout adapts to portrait and landscape
1.4.1 Use of Color	A	Pass	Pause state uses opacity + SR announcement, not color alone
1.4.3 Contrast (Minimum)	AA	Pass	All text meets 4.5:1 ratio
1.4.4 Resize Text	AA	Pass	Native HTML reflows at 200% zoom; orbs removed at 150%+ to prevent obstruction
1.4.10 Reflow	AA	Pass	CSS columns reflow to single column at 320px width, no horizontal scroll
1.4.11 Non-text Contrast	AA	Pass	Focus indicators meet 3:1 against adjacent colors
2.1.1 Keyboard	A	Pass	All functionality available via keyboard
2.1.2 No Keyboard Trap	A	Pass	`scroll-snap-type: proximity` (not `mandatory`), no focus traps
2.2.2 Pause, Stop, Hide	A	Pass	Global and per-orb pause controls, `Esc` shortcut
2.3.3 Animation from Interactions	AAA	Pass	`prefers-reduced-motion` respected, manual toggle available
2.4.1 Bypass Blocks	A	Pass	Landmark navigation via `<header>`, `<main>`, `<footer>`
2.4.3 Focus Order	A	Pass	Tab order follows logical document structure
3.1.1 Language of Page	A	Pass	`lang="en"` on `<html>`, `lang="es"` on Spanish text
3.1.2 Language of Parts	AA	Pass	Spanish text scoped with `lang="es"`
4.1.2 Name, Role, Value	A	Pass	Buttons have labels, toggles have `aria-pressed`, live regions announce changes

Tech stack

Claude calculations, editing and README writing.
React 19
TypeScript 5.9
Vite 8
@chenglou/pretext 0.0.3
Atkinson Hyperlegible, font designed by the Braille Institute for maximum readability

Linkedin
Github**

Accessibility: 2026 predictions

Mica — Sat, 03 Jan 2026 10:44:51 +0000

I have been in the field for almost 6 years and talking (or writing) about accessibility had always been tough in the tech area but NOW it is insufferable.

Nowadays, accessibility it is a hot topic, everyone want to get profit from it and be compliant (which is okay, taking in consideration the European Accessibility Act entering the game). Internet is full of bullshit post generated with AI, talking about the same shit over and over again that nobody reads because they are just empty words with no actual substance.

This is not a anti-AI post. I consider it a valuable tool to boost our job. But, what happen when we forget our human condition in order to gain money and forget that we are building product not only for AI search robots but for HUMANS?

Stop using overlays for accessibility.
Stop using AI for writing posts, use it just for corrections.
Use your hands and your brain.
Think before writing.
Start talking with actual accessibility web professionals.
Talk with actual users with disabilities.

Not everything is money and speed. Behind the computer there are people. Do not forget that.

pd: the title is just a clickbait for my post-rage lol

Accessible components: Pagination

Mica — Tue, 29 Oct 2024 16:58:05 +0000

Today, we're going to look at how to create pagination from scratch and make it accessible and reusable. I hope it’s helpful, and please leave your comments at the end of the post!

Github: https://github.com/micaavigliano/accessible-pagination
Proyecto: https://accessible-pagination.netlify.app/

Custom hook to fetch data

const useFetch = <T,>(url: string, currentPage: number = 0, pageSize: number = 20) => {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<boolean>(false);

  useEffect(() => {
    const fetchData = async() => {
      setLoading(true);
      setError(false);

      try {
        const response = await fetch(url);
        if (!response.ok) {
          throw new Error('network response failed')
        }
        const result: T = await response.json() as T;
        setData(result)
      } catch (error) {
        setError(true)
      } finally {
        setLoading(false);
      }
    };

    fetchData()
  }, [url, currentPage, pageSize]);

  return {
    data,
    loading,
    error,
  }
};

We'll create a custom hook with a generic type. This will allow us to specify the expected data type when using this hook.
We'll expect three parameters: one for the URL from which we'll fetch the data, currentPage, which is the page we're on (default is 0), and pageSize, which is the number of items per page (default is 20, but you can change this value).
In our state const [data, setData] = useState<T | null>(null);, we use the generic type T since, as we use it for different data requests, we'll be expecting different data types.

Pagination

To make pagination accessible, we need to consider the following points:

Focus should move through all interactive elements of the pagination and have a visible indicator.
To ensure good interaction with screen readers, we must correctly use regions, properties, and states.
Pagination should be grouped within a <nav> tag and contain an aria-label identifying it specifically as pagination.
Each item within the pagination should have an aria-setsize and an aria-posinset. Now, what are these for? Well, aria-setsize is used to calculate the total number of items within the pagination list. The screen reader will announce it as follows:

aria-posinset is used to calculate the position of the item within the total number of items in the pagination. The screen reader will announce it as follows:

Each item should have an aria-label to indicate which page we’ll go to if we click on that button.
Include buttons to go to the next/previous item, and each of these buttons should have its corresponding aria-label.
If our pagination contains an ellipsis, it should be correctly marked with an aria-label.
Every time we go to a new page, the screen reader should announce which page we are on and how many new items there are, as follows:

To achieve this, we’re going to code it as follows:

const [statusMessage, setStatusMessage] = useState<string>("");

useEffect(() => {
    window.scrollTo({ top: 0, behavior: 'smooth' });
    if (!loading) {
      setStatusMessage(`Page ${currentPage} loaded. Displaying ${data?.near_earth_objects.length || 0} items.`);
    }
  }, [currentPage, loading]);

When the page finishes loading, we’ll set a new message with our currentPage and the length of the new array we’re loading.

Alright! Now let’s take a look at how the code is structured in the pagination.tsx file.

The component will require five props.

interface PaginationProps {
  currentPage: number;
  totalPages: number;
  nextPage: () => void;
  prevPage: () => void;
  goToPage: (page: number) => void;
}

currentPage refers to the current page. We’ll manage it within the component where we want to use pagination as follows: const [currentPage, setCurrentPage] = useState<number>(1);
totalPages refers to the total number of items to display that the API contains.
nextPage is a function that will allow us to go to the next page and update our currentPage state as follows:

const handlePageChange = (newPage: number) => {
    setCurrentPage(newPage); 
  };

  const nextPage = () => {
    if (currentPage < totalPages) {
      handlePageChange(currentPage + 1);
    }
  };

prevPage is a function that will allow us to go to the page before our current page and update our currentPage state.

const prevPage = () => {
    if (currentPage > 1) {
      handlePageChange(currentPage - 1);
    }
  };

goToPage is a function that will need a numeric parameter and is the function each item will use to navigate to the desired page. We’ll make it work as follows:

const handlePageChange = (newPage: number) => {
    setCurrentPage(newPage); 
};

To bring our pagination to life, we need one more step: creating the array that we’ll iterate through in our list! For that, we should follow these steps:

Create a function; I’ll call it getPageNumbers in this case.
Create variables for the first and last items in the list.
Create a variable for the left-side ellipsis. I’ve decided to place my ellipsis after the fourth item in the list.
Create a variable for the right-side ellipsis. I’ve decided to place my ellipsis just before the last three items in the list.
Create a function that returns an array with 5 centered items: the current page, two previous items, and two subsequent items. If needed, we’ll exclude the first and last pages. const pagesAroundCurrent = [currentPage - 2, currentPage - 1, currentPage, currentPage + 1, currentPage + 2].filter(page => page > firstPage && page < lastPage);
For our final variable, we’ll create an array that contains all the previously created variables.
Finally, we’ll filter out null elements and return the array. This array is what we’ll iterate through to get the list of items in our pagination as follows:

<ol className='flex gap-3'>
          {pageNumbers.map((number) => {
            if (number === 'left-ellipsis' || number === 'right-ellipsis') {
              return (
                <span key={number} className='relative top-5' aria-label='ellipsis'>
                  ...
                </span>
              );
            }
            return (
              <li aria-setsize={totalPages} aria-posinset={typeof number === 'number' ? number : undefined} key={`page-${number}`}>
                <button
                  onClick={() => goToPage(Number(number))}
                  className={currentPage === Number(number) ? 'underline underline-offset-3 border-zinc-300' : ''}
                  aria-label={`go to page ${number}`}
                  aria-current={currentPage === Number(number) && 'page'}
                >
                  {number}
                </button>
              </li>
            );
          })}
        </ol>

And that’s how to create a reusable and accessible pagination! Personally, I learned how to build pagination from scratch the hard way because I had to implement it in a live coding session. I hope my experience helps you in your career and that you can implement it and even improve it!

You can follow me:
linkedin: https://www.linkedin.com/in/micaelaavigliano/

Best regards,
Mica <3

Componentes accesibles: Paginación

Mica — Tue, 29 Oct 2024 16:29:19 +0000

Hoy vamos a ver cómo crear una paginación de cero y hacerla accesible y reutilizable. Espero que les sirva y me dejen sus comentarios al final del post!

Github: https://github.com/micaavigliano/accessible-pagination
Proyecto: https://accessible-pagination.netlify.app/

Custom hook to fetch data

const useFetch = <T,>(url: string, currentPage: number = 0, pageSize: number = 20) => {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<boolean>(false);

  useEffect(() => {
    const fetchData = async() => {
      setLoading(true);
      setError(false);

      try {
        const response = await fetch(url);
        if (!response.ok) {
          throw new Error('network response failed')
        }
        const result: T = await response.json() as T;
        setData(result)
      } catch (error) {
        setError(true)
      } finally {
        setLoading(false);
      }
    };

    fetchData()
  }, [url, currentPage, pageSize]);

  return {
    data,
    loading,
    error,
  }
};

Vamos a generar un custom hook con un generic type. Esto nos va a permitir especificar el tipo de dato esperado cuando se usa este hook
Vamos a esperar 3 parámetros. Uno para url de donde vamos a fetchear la data, currentPage que es la página donde estamos y por default es 0 y pageSize que es el número de items que vamos a tener por página y por default es 20 (pueden cambiarle este valor).
En nuestro estado const [data, setData] = useState<T | null>(null); le pasamos el generic type T ya que a medida que lo usemos para diferentes peticiones de data vamos a esperar diferentes tipos de datos.

Paginación

Para que una paginación sea accesible debemos tener en cuenta los siguientes puntos:

El foco debe moverse por todos los elementos interactivos de la páginación y tener un indicador visible
para asegurar una buena interacción con los lectores de pantalla debemos utilizar correctamente las regiones, propiedades y estados de manera correcta
La páginación debe estar agrupada dentro de un tag y contener un aria-label que la identifique como una paginación per se.
Cada item dentro de la paginación debe contener un aria-setsize y un aria-pointset. Ahora, ¿para qué sirven? Bueno, aria-setsize sirve para calcular el total de items dentro de la lista de la paginación. El lector de pantalla lo anunciará de la siguiente manera:

aria-pointset sirve para calcular la posición del item dentro de la totalidad de items en la páginación. El lector de pantalla lo anunciará de la siguiente manera:

Cada item debe tener un aria-label para poder identificar a qué página vamos a ir si presionamos sobre ese botón.
Tener botones para ir al siguiente/previo elemento y cada uno de estos botones debe tener su aria-label correspondiente
Si nuestra paginación contiene una ellipsis, la misma debe tener correctamente marcada con un aria-label
Cada vez que vamos a una nueva página, el screen reader debe anunciar en qué página estamos y cuántos items nuevos hay de la siguiente manera.

Para poder llegar a esto vamos a codearlo de la siguiente manera:

const [statusMessage, setStatusMessage] = useState<string>("");

useEffect(() => {
    window.scrollTo({ top: 0, behavior: 'smooth' });
    if (!loading) {
      setStatusMessage(`Page ${currentPage} loaded. Displaying ${data?.near_earth_objects.length || 0} items.`);
    }
  }, [currentPage, loading]);

Cuando la página deje de cargar, vamos a setear un nuevo mensaje con nuestra currentPage y la longitud del nuevo array que estamos cargando.

Ahora sí! Pasemos a ver cómo esta estructurado el código en el archivo pagination.tsx

El componente va a requerir de cinco props

interface PaginationProps {
  currentPage: number;
  totalPages: number;
  nextPage: () => void;
  prevPage: () => void;
  goToPage: (page: number) => void;
}

currentPage se va a referir a la página actual. Esta misma la vamos a manejar con estamos en el componente donde deseemos utilizar la paginación de la siguiente manera: const [currentPage, setCurrentPage] = useState<number>(1);
totalPages se refiere al total de items a mostrar que contiene la API
nextPage esta función nos permitirá ir a la siguiente página y actualizar nuestro estado currentPage de la siguiente manera:

const handlePageChange = (newPage: number) => {
    setCurrentPage(newPage); 
  };

  const nextPage = () => {
    if (currentPage < totalPages) {
      handlePageChange(currentPage + 1);
    }
  };

prevPage esta función nos permitirá ir a la página previa a nuestra página actual y actualizar nuestro estado currentPage

const prevPage = () => {
    if (currentPage > 1) {
      handlePageChange(currentPage - 1);
    }
  };

goToPage esta función va a necesitar un parámetro numérico y es la función que cada item va a tener para poder ir a la página deseada. Vamos a hacerla funcionar de la siguiente manera:

const handlePageChange = (newPage: number) => {
    setCurrentPage(newPage); 
};

Para que nuestra paginación cobre vida nos falta un paso más, ¡crear el array que vamos a iterar en nuestra lista! Para eso debemos seguir los siguientes pasos:

Crear una función, en este caso la llamaré getPageNumbers
Crear variables para el primer y el último item del listado.
Crea una variable para la elipsis del lado izquierdo. Por decisión propia, mi elipsis se va a ubicar luego del cuarto elemento de la lista.
Crear una variable para la elipsis del lado derecho. Por decisión propia, mi elipsis se va a ubicar previo a tres items en la lista.
Crear una función que nos devuelva un array donde estén centrados siempre 5 items, la página actual, dos items previos y dos items subsiguientes. En caso de necesitamos, vamos a excluir a la primera y última página const pagesAroundCurrent = [currentPage - 2, currentPage - 1, currentPage, currentPage + 1, currentPage + 2].filter(page => page > firstPage && page < lastPage);
Para nuestra última variable, vamos a crear un array que contenga todas las variables previamente creadas.
Por último, vamos a filtrar los elementos null y devolver el array.

Este array es el que vamos a recorrer para obtener el listado de items en nuestra paginación de la siguiente manera:

<ol className='flex gap-3'>
          {pageNumbers.map((number) => {
            if (number === 'left-ellipsis' || number === 'right-ellipsis') {
              return (
                <span key={number} className='relative top-5' aria-label='ellipsis'>
                  ...
                </span>
              );
            }
            return (
              <li aria-setsize={totalPages} aria-posinset={typeof number === 'number' ? number : undefined} key={`page-${number}`}>
                <button
                  onClick={() => goToPage(Number(number))}
                  className={currentPage === Number(number) ? 'underline underline-offset-3 border-zinc-300' : ''}
                  aria-label={`go to page ${number}`}
                  aria-current={currentPage === Number(number) && 'page'}
                >
                  {number}
                </button>
              </li>
            );
          })}
        </ol>

Y hasta acá cómo realizar una paginación reutilizable y accesible! Personalmente, aprendí a realizar una páginación de cero a los golpes porque tuve que implementarla en un live coding, espero que mi experiencia le sea de ayuda para su carrera y puedan implementar y ¡hasta mejorarla!

Saludos,
Mica<3

Accordion accessible y reutilizable solo con la etiqueta details y css

Mica — Mon, 04 Mar 2024 17:51:42 +0000

Bienvenides a una nueva entrada de mi sección dedicada a realizar componentes reutilizables y, sobre todo, accesibles. En esta ocasión vamos a aprender cómo utilizar la etiqueta HTML details para realizar un accordion o acordión.

Repositorio: https://github.com/micaavigliano/accordion
Proyecto: https://accordion-accessible.netlify.app/

Para que nuestro accordion sea accesible debemos tener en cuenta los siguientes puntos:

cuando el foco esta en el header del accordion debe poder colapsarse y expandirse presionando las teclas enter o space
al presionar tab el foco se mueve al siguiente accordion o al siguiente elemento interactivo dentro del accordion
al presionar shift + tab el foco se mueve al elemente interactivo anterior
el screen reader o lector de pantalla debe anunciar el estado del elemento, es decir, si esta colapsado o expandido. También debe anunciar su nombre accesible.

La etiqueta details nos ayudará a pasar todos estos puntos, ya que de por sí es accesible de manera nativa.

¿Cómo utilizamos la etiqueta `details`?

La etiqueta details es una etiqueta nativa de HTML de estructura que se utiliza para crear un elemento que puedo ser expandido o colapsado. Dentro de esta etiqueta vamos a encontrar la etiqueta summary que se utiliza como encabezado que actúa como el control para expandir o colapsar el contenido. Por último, el contenido a mostrar se coloca después de la etiqueta summary y podrá ser cualquier elemento válido de HTML.

<details>
  <summary>Mostrar más</summary>
  <p>contenido</p>
</details>

Ahora que ya aprendimos cómo se conforma y para qué sirve la etiqueta details vamos a realizar nuestro componente reutilizable.

Primero, vamos a hablar sobre las propiedades que el componente va a recibir:

interface AccordionProps {
  title: string;
  children: ReactNode | string;
  icon: ReactNode | string;
  name?: string;
}

title será nuestro encabezado dentro de la etiqueta summary.
children será el contenido a mostrar. Puede recibir un string o un ReactNode.
icon va a ser el ícono que va a suplantar el ícono nativo que contiene el elemento details.
name es opcional y será el valor que va a contener el atributo name del cual hablaremos a continuación.

Atributo `name`

La etiqueta details acepta el atributo name y se utiliza para, si hay más de una etiqueta details, que los elementos se comporten como un grupo. Es decir, si un accordion esta abierto y se abre otro, automáticamente el anterior se cierra.

Cómo sacar la flecha nativa del componente

Para poder sacar la flecha nativa tenemos que tener dos reglas en cuenta primero con el selector summary vamos a colocar el list-style: none para eliminar la flecha en algunos navegadores.

details summary {
  cursor: pointer;
  position: relative;
  list-style: none;
}

Para eliminar la flecha en navegadores como Chrome y Safari vamos a utilizar la propiedad -webkit-details-marker

details summary::-webkit-details-marker {
  display: none;
}

¿Cómo anuncian los lectores de pantalla la etiqueta `details`?

1) cuando el elemento esta colapsado

2) cuando el elemento esta expandido

y, ¡Listo! Ya con todos estos cambios y cero javascript tenemos un Accordion funcionando y 100% accesible.

Espero que esta información les sirva y comentenme si hay algo en particular que les gustaría aprender sobre accesibilidad o si hay algún componente en particular que les llama la atención para poder trabajar en esta sección.

Muchas gracias por leerme siempre <3

Focus Management: how to improve the accessibility and usability of our components

Mica — Wed, 17 Jan 2024 18:46:56 +0000

A little bit tired of always seeing the typical introductory courses about accessibility, I decided to start by the end. So this is why I am going to talk about Focus Management.

Before starting to talk about Focus Management and accessibility we should focus on our product’s usability. One of the WCAG 2.2 main principles is that the application should be operable. This principle allows us to think about the user experience of those keyboard’s users. Some examples of navigation in general could be: navigation using a screen reader (NVDA, Jaws, VoiceOver, etc). The focus and the screen readers use the Accessibility API, which can be found in all operative systems and in the browsers (DOM). Why is this important? Basically, because the assistive technologies are going to navigate the same way as the focus does. A practical example of that is when a modal is opened and there is no focus trap, the focus will get lost and this might lead to frustrations and confusions. If you want to know more about the Accessibility API you can click on this link: Core Accessibility API Mappings 1.1.

So, for this post I came up with the idea of creating a typical but not so covered case of what happens when we open and close a modal. I am going to develop it using React with Typescript and explain step by step what I am doing. You can check out the code here Github repository and the explanation on the following link https://focus-management.netlify.app/ .

Let’s do it!

useDataFetching hook

First of all, let's create out fetching data's hook ti display the users (I really love this hook and I hope it would be useful for you all)

import { useState, useEffect, useCallback } from "react";

const useDataFetching = (url: string) => {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState<boolean>(false);
  const [error, setError] = useState<boolean>(false);

  const fetchData = useCallback(async () => {
    setLoading(true);
    setError(false);

    try {
      const response = await fetch(url);
      const result = await response.json();
      setData(result);
    } catch (err) {
      setError(true);
    }
    setLoading(false);
  }, []);

  useEffect(() => {
    fetchData();
  }, [fetchData]);

  return { data, loading, error };
};

export default useDataFetching;

CardContainer.tsx

import React from "react";
import useFetch from "../hooks/useFetch";
import Card from "../component/Card";

const CardContainer = () => {
  const { data, loading } = useFetch(
    "https://63bedcf7f5cfc0949b634fc8.mockapi.io/users"
  );

  if (loading)
    return (
      <p role="status">
        Loading...
      </p>
    );

  return (
    <div className="container">
      <Card item={data} />
    </div>
  );
};

export default CardContainer;

In this component, we are going to use the useFetch() hook so we can retrieve the data. An important part of our loading component is that we are going to pass it two attributes: role and aria-live.

What is this for?
The role="status" in this case we have to use it to announce to the Accessibility API that that zone of our application is a "live region", which means that the state will change and that change will have to be announced to the user. By default the role="status" will have the attribute aria-live="polite". This attribute announces to assistive technology that, in a non-intrusive way and as soon as there is a spot, it SHOULD announce the content that is inside the live region. If you want to know more about the live region roles you can go to the follow link: https://www.w3.org/TR/wai-aria-1.1/#dfn-live-region

Component Card.tsx

Here is where we are going to place the logic to open the modal and manage the focus when we close it.

const handleClick = (id: number) => {
    setItemId(id);
    setModalOpen(true);
};

The handleClick function will allow is to pass it an id and set it on the setItemId and also open the modal. What is what we search by storing the id of every item in an state? Well, it will let us validate that the id of the item and the stored id matched, and if they match the open is opened. This is necessary because we can validate that every item is unique so we can inject the data in every item in a unique way.

const closeModal = () => {
    setModalOpen(false);
};

The closeModal function is for closing the modal by pressing the esc key or clicking over the close button

<button
  onClick={() => handleClick(data.id!)}
  data-item-id={data.id}
  aria-label={`more info about ${data.name}`}
  className="more-info"
>
  More info
</button>
{modalOpen && itemId === data.id && (
  <Modal
   isOpen={modalOpen}
   title={data.name}
   onClose={closeModal}
  >
   <>
    <div className="modal-content">
      <p>
        Website: <a href={data.website}>{data.website}</a>
      </p>
    </div>
    <div className="desc-container">
      <p>{data.description}</p>
    </div>
   </>
  </Modal>
 )}

Now, let's go to the useEffect:

useEffect(() => {
  if (!modalOpen) {
    const buttonToFocus = document.querySelector(
      `button[data-item-id="${itemId}"]`
    );

    if (buttonToFocus instanceof HTMLElement) {
      buttonToFocus.focus();
    }
  }
}, [modalOpen, itemId]);

Here we are going to check if the modal it is visible or not. If it's closed, we are going to grab the button according to its specific attribute button[data-item-id="${itemId}"]. Finally, we check if the button is an element with buttonToFocus instanceof HTMLElement so we can call to the focus() method.
The interaction with the focus should be: when the modal is opened, the focus should placed in the dialog. When we close it, the focus should go back to the more information button.

Componente Modal.tsx

const onKeyDown = (event: React.KeyboardEvent) => {
  if (event.key === "Escape" && onClose) {
    onClose();
  }
};

With the onKeyDown() function, we listen for which key is pressed. If the pressed key is "Escape" and the onClose function exists, we will close the modal. This function allows us to comply with the G21 technique, which emphasizes the importance of ensuring that users do not get trapped in any part of our app and providing them with an escape mechanism. If you want to read more about this technique and criterion 2.1.2 (no keyboard trap), you can do so at the following link: https://www.w3.org/TR/WCAG20-TECHS/G21.html

Now, let's continue with our Modal.tsx component. We are going to create the modal within a createPortal(), my favorite method provided by React.

What is createPortal() used for?
As I mentioned earlier, createPortal() is a method provided by React that is used to create portals. Portals are used to render child elements into a DOM node that exists outside the main component hierarchy. This method is particularly useful for creating modals, tooltips, or any other component that doesn't need to be constantly rendered within the main component structure.
createPortal() takes two arguments: the element to render and the DOM element where you want to inject it.

Example of how the main hierarchy looks without the modal:

Example of how the main hierarchy looks with the modal:

To conclude, createPortal() enhances the accessibility of our applications by preventing assistive technologies from announcing hidden content or unnecessary navigations in our DOM.

Let's continue with the logic in our Modal component.

useEffect(() => {
    if (isOpen) {
      const interactiveElement =
        modalRef.current?.querySelector("[tabindex='-1']");
      if (interactiveElement) {
        if (interactiveElement instanceof HTMLElement) {
          interactiveElement.focus();
        }
      }
    }
  }, [isOpen]);

This hook will help us focus on the modal as soon as it opens. In this case, the first element to receive focus will always be our dialog, as it is necessary for assistive technologies to announce its role and title. Announcing the title is achieved by establishing a relationship between the aria-labelledby and the id we pass to our title.

It is crucial to have control over the focus in all interactive elements to ensure that the interaction and usability of our application are accessible to everyone, regardless of their method of navigating through it. This also ensures free navigation on the web in general.

With this final explanation, I conclude my first post in this series on accessible components. My goal is to raise awareness about accessibility and demonstrate that we, as frontend developers, can enhance the experience for many people without it being an extra effort. We just need the tools and sensitivity to learn and incorporate them.

I hope this has been helpful, and any doubts, questions, or suggestions for improvement in the future are welcome. I'll leave my social media links where you can reach out to me for anything!

Linkedin: https://www.linkedin.com/in/micaelaavigliano/
Github: https://github.com/micaavigliano

Thanks for reading this far!!!🫰

How to create an accessible tooltip using React

Mica — Mon, 15 Jan 2024 01:51:55 +0000

Happy 2024, everyone!!! I hope you had a great starting. On this side, we're going to celebrate the beginning of the year with a new entry for this wonderful series of accessible components. This time, I'm going to share with you how to create an accessible dynamic tooltip and how to use the clipboard API in JavaScript. Let's get started because things are getting exciting!

Project repository: https://github.com/micaavigliano/accessible-tooltip
Project link: https://accessible-tooltip.netlify.app/

First and foremost, let's discuss a bit about what we want to achieve to make our clipboard copy button accessible. We need:

1) The button to receive focus and have an accessible name.
2) The copy button to have a tooltip that appears when the user hovers over it or when it receives focus.
3) The tooltip content to be dynamic, and that this content is announced by the screen reader each time it changes.
4) The content we want to copy should indeed be copied to the clipboard.
5) The copy component should be reusable and can be either static text or an input.
6) The tooltip should close when the user presses the Esc key.

Our specifications are clear and straightforward. Let's start coding!

Tooltip.tsx

interface TooltipProps {
  text: string;
  children: ReactNode;
  direction: "top" | "bottom" | "left" | "right";
  id: string;
}

Text: It will be the text that our tooltip will contain.
Children: The element that will contain the tooltip.
Direction: The direction in which we want our tooltip to appear.
ID: An ID to relate it to the aria-describedby attribute that the children will have.

Let's start breaking down the component:

We'll need to set a state to manage the visibility of the tooltip:

const [showTooltip, setShowTooltip] = useState<boolean>(false);

Next, let's create two functions to handle this state: tooltipOn and tooltipOff:

const tooltipOn = () => {
  setShowTooltip(true);
};

const tooltipOff = () => {
  setShowTooltip(false);
};

These functions will be passed to our container element to show the tooltip when hovered using the onMouseEnter function, hide the tooltip when the mouse leaves that element with onMouseLeave, display the tooltip again when the element receives focus with onFocus, and hide the tooltip when focus leaves that element with onBlur. Additionally, to ensure our tooltip is 100% functional and accessible, we will create a function to make it disappear when the user presses the Escape key.

const closeTooltip = (ev: KeyboardEvent) => {
    if (ev.key === "Escape") {
      setShowTooltip(false);
    }
};

and handle the event in a useEffect

 useEffect(() => {
    document.addEventListener("keydown", closeTooltip);

    return () => {
      document.removeEventListener("keydown", closeTooltip);
    };
  }, []);

Let's see how our component is going to look:

<div
   className="relative inline-block justify-center text-center"
   onMouseEnter={tooltipOn}
   onMouseLeave={tooltipOff}
   onFocus={tooltipOn}
   onBlur={tooltipOff}
>
  {showTooltip && (
    <div
      className={`bg-black text-white text-center rounded p-3 absolute z-10 transition-opacity duration-300 ease-in-out w-fit outline outline-offset-0 ${
      direction === "top" ? "bottom-[calc(100%+1px)] left-10 transform translate-x-[-60%] mb-2"
              : ""
          }
          ${
            direction === "bottom"
              ? "top-[calc(100%+1px)] left-10 transform translate-x-[-60%] mt-2"
              : ""
          }
          ${
            direction === "left"
              ? "-left-100 top-1/2 transform -translate-y-1/2 mr-2"
              : ""
          }
          ${
            direction === "right"
              ? "-right-100 top-1/2 transform -translate-y-1/2 ml-2"
              : ""
          }`}
          data-placement={direction}
          role="tooltip"
          id={id}
          style={getTooltipStyle()}
        >
          {text}
        </div>
      )}
      {children}
    </div>

To make our Tooltip accessible, we'll need to pass it a series of attributes:

role="tooltip": While semantically it may not represent a significant change, it does so in reference terms by helping screen readers identify and associate the tooltip with its related element. What do I mean by this? Well, any element that contains role="tooltip" must be related to another element that contains aria-labelledby (in this case, the children should have it). This is because the tooltip provides additional information about the element.
id: The ID of the element to be related through aria-describedby.
data-placement: It will receive the direction property, which will be the direction of our tooltip.

CopyToClipboard.tsx

Now, let's move on to one of the most enjoyable components I've had the pleasure of creating. I don't know why, I just grew very fond of it.

Let's start with its properties; in this case, we have one optional and one mandatory:

interface ICopyToClipboard {
  text?: string;
  type: "text" | "input";
}

Text: The text that our component will receive in the case of being of type text.
Type: It can only take two values, either text or input. Text will be a static value, while input will be a dynamic one.

In this case, our copy button will be wrapped in the Tooltip component. The button will have an onClick attribute that will receive the handleCopyText function, which we'll discuss a little later, and the aria-labelledby attribute to relate it to our tooltip.

<Tooltip text={copyText} direction={"bottom"} id={"copyid"}>
 <button onClick={handleCopyText} aria-labelledby="copyid">
  <ContentCopy />
 </button>
</Tooltip>

Let's move on to the handleCopyText function.

We need to create a state to manage the text: const [copyText, setCopyText] = useState<string>("Copy to clipboard");
To continue with the handleCopyText function, we have to understand what the clipboard API is. The clipboard API allows us to interact with the clipboard of an operating system. It contains methods and functions to access and manipulate the information stored on the clipboard (copy, paste, and cut). In this case, we will make use of the writeText() method. This method takes a required text parameter and returns a promise. If the operation is successful, the then() method will be executed, changing the value of our copyText state. After 5 seconds, the text will revert to "Copy to clipboard". In this case, the writeText method parameter will receive either text or inputValue, depending on which is not null. This is because if we pass type="input" to our component, we won't be providing a default static text.

const handleCopyText = () => {
    navigator.clipboard.writeText(text || inputValue).then(() => {
      setCopyText("Copiado");
      setTimeout(() => {
        setCopyText("Copiar al portapapeles");
      }, 5000);
    });
  };

And... there you have it! As simple as that, we now have our accessible text copy button with an accessible tooltip as well. Finally, I'd like to show you how the screen reader announces the content of our tooltip:

Initial state:

Clicked the copy button

Back to initial state after 5 seconds

Now, I hope you enjoyed this component as much as I did, and please share if you've ever come across a tooltip and thought it could be made accessible. Finally, here's the list of resources I used to gather information:

MDN web docs tooltips: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role
MDN web Clipboard API: https://developer.mozilla.org/es/docs/Web/API/Clipboard_API

Tooltip Accessible: como crear un copy to clipboard button

Mica — Tue, 09 Jan 2024 21:08:41 +0000

¡FELIZ AÑO NUEVO! Feliz 2024, para todos. Espero que este año lo comiencen con todo, por este lado vamos a celebrar este comienzo de año con una nueva entrada para esta maravillosa serie de componentes accesibles. En esta ocasión les voy a compartir cómo hacer un tooltip dinámico accesible y cómo utilizar la API clipboard en javascript. Comencemos que la cosa se esta poniendo buena!

repo del proyecto: https://github.com/micaavigliano/accessible-tooltip
link al proyecto: https://accessible-tooltip.netlify.app/

Primero y principal vamos a comentar un poco sobre qué es lo que queremos lograr en para que nuestro botón para copiar al portapapeles sea accesible necesitamos:

1) que el botón reciba foto y tenga un nombre accesible
2) que el botón para copiar tenga un tooltip que aparezca cuando el usuario hace hover sobre el o cuando recibe foco.
3) que el contenido del tooltip sea dinámico y que a su vez ese contenido sea anunciado por el screen reader cada vez que cambia.
4) que efectivamente el contenido que queramos copiar se copie en el portapapeles.
5) el componente para copiar debe ser reutilizable y puede ser un texto estático o un input.
6) el tooltip debe cerrarse cuando el usuario presiona la tecla Esc

Nuestras especificaciones son claras y sencillas. Comencemos a codear.

Tooltip.tsx

Primero comencemos con nuestro componente reutilizable Tooltip. Este componente va a recibir cuatro props obligatorias las cuales van a ser las siguientes

interface TooltipProps {
  text: string;
  children: ReactNode;
  direction: "top" | "bottom" | "left" | "right";
  id: string;
}

text: va a ser el texto que va a contener nuestro tooltip
children: el elemento que va a contener el tooltip
direction: para donde queremos que nuestro tooltip vaya
id: un id para poder relacionarlo con el aria-describedby que va a tener el children

comencemos a desglogar el componente:

vamos a necesitar setear un estado para manejar la visualización del tooltip
const [showTooltip, setShowTooltip] = useState<boolean>(false);
vamos a crear dos funciones para manejar este estado: tooltipOn y tooltipOff

const tooltipOn = () => {
    setShowTooltip(true);
};

const tooltipOff = () => {
    setShowTooltip(false);
};

Estas funciones se la vamos a pasar a nuestro elemento contenedor para que muestre el tooltip cuando le hacen hover con la función onMouseEnter, que esconda el tooltip cuando no le hacen hover a ese elemento con onMouseLeave, cuando el elemento reciba foco con onFocus se muestre nuevamente el tooltip y que cuando el foco se vaya de ese elemento el tooltip se esconda también con onBlur.
También para que nuestro tooltip sea 100% funcional y accesible vamos a crear una función para que desaparezca cuando el usuario presiona la tecla Esc

const closeTooltip = (ev: KeyboardEvent) => {
    if (ev.key === "Escape") {
      setShowTooltip(false);
    }
};

y manejar el evento en un useEffect

  useEffect(() => {
    document.addEventListener("keydown", closeTooltip);

    return () => {
      document.removeEventListener("keydown", closeTooltip);
    };
  }, []);

Veamos como va a quedar nuestro componente:

<div
      className="relative inline-block justify-center text-center"
      onMouseEnter={tooltipOn}
      onMouseLeave={tooltipOff}
      onFocus={tooltipOn}
      onBlur={tooltipOff}
    >
      {showTooltip && (
        <div
          className={`bg-black text-white text-center rounded p-3 absolute z-10 transition-opacity duration-300 ease-in-out w-fit outline outline-offset-0 ${
            direction === "top"
              ? "bottom-[calc(100%+1px)] left-10 transform translate-x-[-60%] mb-2"
              : ""
          }
          ${
            direction === "bottom"
              ? "top-[calc(100%+1px)] left-10 transform translate-x-[-60%] mt-2"
              : ""
          }
          ${
            direction === "left"
              ? "-left-100 top-1/2 transform -translate-y-1/2 mr-2"
              : ""
          }
          ${
            direction === "right"
              ? "-right-100 top-1/2 transform -translate-y-1/2 ml-2"
              : ""
          }`}
          data-placement={direction}
          role="tooltip"
          id={id}
          style={getTooltipStyle()}
        >
          {text}
        </div>
      )}
      {children}
    </div>

Para que nuestro Tooltip sea accesible vamos a tener que pasarle una serie de atributos:

role="tooltip": en si no semánticamente no representa un gran cambio, sí lo hace en términos referenciales ya que que ayuda a los lectores de pantalla a identificar y asociar el mensaje emergente con su elemento relacionado. ¿A qué me refiero con esto? Bueno, todo elemento que contenga un role="tooltip" debe estar relacionado con otro elemento que contenga un aria-labelledby (en este caso, el children debe contenerlo). Esto se debe a que el tooltip provee información extra del elemento.
id: id del elemento a relacionar mediante el aria-describedby
data-placement: va a recibir la propiedad direction que va a ser la dirección de nuestro toolip

CopyToClipboard.tsx

Ahora sí, pasamos a uno de los componentes más divertidos que me haya tocado hacer. No sé porqué, simplemente le tomé mucho cariño.

Comencemos con sus propiedades, en este caso tenemos una opcional y una obligatoria:

interface ICopyToClipboard {
  text?: string;
  type: "text" | "input";
}

text: texto que va a recibir nuestro componente en caso de ser type text
type: solo puede recibir dos valores o text o input. text va a ser un valor estático mientras que input un valor dinámico

Nuestro botón de copiar en este caso va a estar envuelto en el componente Tooltip. El botón va a tener un atributo onClick que va a recibir la función handleCopyText, de la cual vamos a hablar un poquito más adelante, y el atributo aria-labelledby para poder relacionarlo con nuestro tooltip.

<Tooltip text={copyText} direction={"bottom"} id={"copyid"}>
 <button onClick={handleCopyText} aria-labelledby="copyid">
  <ContentCopy />
 </button>
</Tooltip>

Pasemos a la función handleCopyText

debemos crear un estado para manejar el texto const [copyText, setCopyText] = useState<string>("Copiar al portapapeles");
Para continuar con la función handleCopyText tenemos que entender qué es la API clipboard. La API clipboard nos interactuar con el portapapeles de un sistema operativo. Contiene métodos y funciones para acceder y manipular la información almacenada en el portapapeles (copiar, pegar y cortar). En este caso vamos a ser uso del método writeText(). Este método contiene un parámetro obligatorio de tipo texto y va a devolver una promesa. Si la operación es exitosa, el método then() se ejecutará y cambiará el valor de nuestro estado copyText, luego al cabo de 5 segundos el texto volverá a ser Copiar al portapapeles. En este caso el parámetro del writeText va a recibir text O inputValue en caso de alguno ser null va a ir por el siguiente. Esto se debe a que si le pasamos type="input" a nuestro componente no le vamos a pasar por default un texto estático.

const handleCopyText = () => {
    navigator.clipboard.writeText(text || inputValue).then(() => {
      setCopyText("Copiado");
      setTimeout(() => {
        setCopyText("Copiar al portapapeles");
      }, 5000);
    });
  };

Yy... ¡Listo! Tan simple como eso ya tenemos nuestro botón para copiar text accesible y con un tooltip también accesible. Por último, me gustaría compartirles como el screen reader anuncia el contenido de nuestro tooltip:

Estado inicial
Clickeado el botón de copiar

Vuelta al valor inicial luego de 5 segundos

Ahora sí, espero que hayan disfrutado tanto como yo de este componente y me compartan si alguna vez se toparon con algún tooltip y si pensaron que se podía hacer accesible.
Por último les dejo el listado de recursos que utilicé para obtener información

MDN web docs tooltips: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role
MDN web Clipboard API: https://developer.mozilla.org/es/docs/Web/API/Clipboard_API

✨Tabs accesibles✨

Mica — Tue, 12 Dec 2023 18:00:00 +0000

En este post vamos a aprender cómo hacer Tabs accesibles y reutilizables utilizando React y Javascript. Los tabs van a tener activación automática, es decir, que apenas reciben foco con las arrow keys izquierda y derecha. Para esto, primero tenemos que saber cómo deberían funcionar los tabs para que sean accesibles según W3.

Antes de comenzar les comparto el enlace a mi repo de github y al demo de la aplicación para probarla.

Github: https://github.com/micaavigliano/tab-a11y
Demo: https://accessible-tabs.netlify.app/

Tab: cuando el foco esta en el tablist ubica el foco en el siguiente elemento interactivo
Shift + Tab: cuando el foco esta en el tablist ubica el foco en el elemento interactivo anterior
Cuando el foco esta en el tablist:
- Arrow key izquierda: mueve el foco al elemento interactivo anterior. Si el foco esta en el primer elemento interactivo, el foco se ubica en el último tab.
- Arrow key derecha: mueve el foco al elemento interactivo siguiente. Si el foco esta en el último elemento interactivo, el foco se ubica en el primer tab.
- Espacio o Enter: activa el tab si no esta activado
- Home: el foco va al primer tab interactivo
- End: el foco va al último tab interactivo

Ahora que ya conocemos cómo debe se debe navegar con el teclado vamos a pasar al código y a cómo el screen reader lee este componente.

1) Primero vamos a crear el componente Tab

const Tab: React.FC<ITab> = ({ name, id, setActive, active }) => {
  const btnRef = useRef<HTMLButtonElement | null>(null);

  useEffect(() => {
    if (id === active && btnRef.current) {
      btnRef.current.focus();
    }
  }, [id, active]);

  return (
    <button
      ref={btnRef}
      role="tab"
      type="button"
      id={`tab-${id}`}
      aria-controls={`tabpanel-${id}`}
      className={`${
        id === active ? "bg-pink-200" : "bg-transparent"
      } py-2 px-4`}
      onClick={() => setActive(id)}
      aria-selected={id === active ? true : false}
    >
      {name}
    </button>
  );
};

Desglosemos nuestro componente

role="tab": indica que el elemento va a ser un tab
aria-controls: propiedad que identifica que este elemento va a controlar
aria-selected: estado que se utiliza para saber si un elemento seleccionable está seleccionado o no.

En este componente vamos a crear una referencia del butón para poder ubicar el foco que este activo cuando naveguemos a través del tablist utilizando las arrow keys y el id del tab coincida con la prop active. Esto lo lograremos ya que el useRef nos permite crear una referencia mutable que persiste durante todo el ciclo de vida de un componente.

2) Ahora vamos a crear el componente que va a contener al tabpanel

const TabPanel: React.FC<ITabPanel> = ({ content, id, active, name }) => {
  return (
    <>
      {id === active && (
        <div
          role="tabpanel"
          className={`w-9/12 border-solid border-2 border-black h-40 text-left p-2 overflow-auto`}
          id={`tabpanel-${id}`}
          aria-labelledby={`tab-${id}`}
          tabIndex={0}
        >
          <h3>{name}</h3>
          {content}
        </div>
      )}
    </>
  );
};

desglosemos nuestro tabpanel

role="tabpanel": indica que el elemento contenedor es un tabpanel. Se oculta hasta que el aria-control coincida con su id.
id={tabpanel-${id}}: id para poder relacionar el container con el aria-control
tabIndex={0}: permite que el tabpanel entré a la secuencia de Tab de la página y le permite a las tecnologías asistivas poder navegar dentro del tabpanel
El tabpanel solamente se va a mostrar si el active number y el id coinciden

3) Ahora sí, vamos a crear nuestro tablist y la funcionalidad para poder navegar

const TabList: React.FC<ITablist> = ({ items }) => {
  const [active, setActive] = useState<number>(
    items.length > 0 ? items[0].id : 0
  );
  const tabRef = useRef<HTMLDivElement | null>(null);

  const handleKeyDown = useCallback(
    (event: KeyboardEvent) => {
      const focusedElement = document.activeElement as HTMLElement;
      const isButtonFocused = focusedElement?.getAttribute("role") === "tab";
      const isInsideTabPanel = focusedElement?.closest('[role="tabpanel"]');

      if (tabRef.current && isButtonFocused && !isInsideTabPanel) {
        if (event.key === "ArrowRight") {
          setActive((prevIndex) =>
            prevIndex < items.length ? prevIndex + 1 : 1
          );
        } else if (event.key === "ArrowLeft") {
          setActive((prevIndex) =>
            prevIndex > 1 ? prevIndex - 1 : items.length
          );
        } else if (event.key === "Home") {
          setActive(1);
        } else if (event.key === "End") {
          setActive(items.length);
        }
      }
    },
    [items.length]
  );

  useEffect(() => {
    document.addEventListener("keydown", handleKeyDown);

    return () => {
      document.removeEventListener("keydown", handleKeyDown);
    };
  }, [items.length, active, handleKeyDown]);

  return (
    <>
      <h1 id="tablist-1" className="pb-12">
        Tabs accesibles
      </h1>
      <div
        role="tablist"
        aria-labelledby="tablist-1"
        className="flex flex-row divide-x divide-solid divide-pink-300"
        ref={tabRef}
      >
        {items.map((item) => (
          <Tab
            id={item.id}
            name={item.name}
            active={active}
            setActive={setActive}
            key={item.id}
          />
        ))}
      </div>
      {items.map((item) => (
        <TabPanel
          content={item.content}
          id={item.id}
          active={active}
          name={item.name}
          key={item.id}
        />
      ))}
    </>
  );
};

Primero vamos a crear un estado active para poder manejar dónde se encuentra nuestro foco activo
luego, vamos a crear una referencia del tablist con const tabRef = useRef<HTMLDivElement | null>(null); para poder menajar el foco. A través de la función handleKeyDown que va a recibir un evento del tipo EventKeyboard para poder controlar el comportamiento de las teclas presionadas. La función handleKeyDown es un callback para guardarla en caché y optimizar el rendimiento, ya que la misma se va a utilizar dentro del useEffect es para poder utilizar los addeventlistener y el cleanup para desmontarlo cuando cambian las dependencias del useEffect. Dentro de la función vamos a tener dos validaciones: isButtonFocused y isInsideTabPanel.

a. Para que estas validaciones funcionen primero tenemos que guardar en una constante el elemento activo de la siguiente manera: const focusedElement = document.activeElement as HTMLElement
b. la validación constisButtonFocused= focusedElement?.getAttribute("role") === "tab"; nos va a devolver true o false si el elemento focuseado contiene el role tab
c. la validación const isInsideTabPanel = focusedElement?.closest('[role="tabpanel"]'); nos tiene que devolver null porque tenemos que chequear que el foco no se encuentre dentro del tabpanel.
d. en nuestro if vamos a validar: que exista la referencia con el tabRef.current, que isButtonFocused sea true y que isInsideTabPanel sea null. Si se cumplen estás tres condiciones, podemos manejar el foco con las arrow keys izquierda y derecha, home y end.
e. entremos a la función, y nos encontramos con ciertas condiciones si la el event.key es igual a ArrowRight nuestro setActive se va a incrementar, en cambio si el event.key es igual a ArrowLeft nuestro setActive va a decrementar. Ahora, si presionamos la tecla home nuestro foco se va a ubicar en el primer item del array, y si presionamos la tecla end el foco se posicionará en el último item de nuestro array.

Para finalizar con el post me gustaría dejar algunos ejemplos de cómo lee el screen reader VoiceOver nuestro tab.

cuando navegamos en el tablist. Nos va a dar el contexto de la posición que ocupa esa tab en el array de tabs y cuántas en total hay. También gracias a nuestro estado aria-selected la persona usuaria de tecnologías asistivas va a saber si ese tab esta seleccionado o no

Es importante que nuestro tabpanel contenga un tabindex={0} para poder colocarlo dentro de la secuencia de navegación y que las tecnologías asistivas puedan anunciarlos como podemos ver en la captura de pantalla. También recordemos que por este motivo es importante relacionar el tab con el tabpanel mediante un id y un aria-labelledby.

Con esta última explicación doy por finalizada la entrega de entrega de componentes accesibles de esta semana! Recuerden que si tienen alguna duda, consulta o sugerencia me pueden dejar un comentario y mensajito por privado que apenas puedas los contesto todos. Por último, me interesa mucho saber si alguna de estás soluciones les sirvió para su día a día o si alguna vez se encontraron con estos retos de accesibilidad.
También quiero aprovechar y agradecer el apoyo que me dieron y las sugerencias que me dan para poder seguir entregando contenido de calidad. Esta iniciativa no solo nació con la idea de ayudar a otros, sino que también surgió para yo seguir siendo mejor desarrolladora día a día.

Les dejo mis redes sociales por si quieren estar al tanto de las nuevas entregas:

Linkedin: https://www.linkedin.com/in/micaelaavigliano/
Github: https://github.com/micaavigliano

Muchas gracias por leer la cuarta entrada!🩷

✨Validación de contraseñas accessible✨

Mica — Tue, 05 Dec 2023 19:15:32 +0000

En esta entrada vamos a aprender como hacer una validación de contraseñas accesible.
El repo de Github podes encontrarlo en el siguiente link: https://github.com/micaavigliano/password-a11y
El demo de la applicación podes probarlo en el siguiente link: https://password-a11y.vercel.app/

Primero que nada, debemos crear nuestro input accesible

<form onSubmit={handleSubmit} id="form-id" className="pb-2 pt-6">
  <label htmlFor="password-input-id">Contraseña</label>
  <div
    className="rounded-full border-solid border-2 border-white px-3 py-1 flex flex-row justify-between"
    aria-label="this component include an input and a button to see the password"
  >
    <input
      type={seePassword ? "text" : "password"}
      onChange={(e) => {
        const newPassword = e.target.value;
        if (newPassword !== "") {
          setPassword(newPassword);
        } else if (newPassword === "") {
          setIsDirty(null);
        }
      }}
      placeholder="Escribí tu contraseña"
      autoComplete="new-password"
      className="text-white bg-transparent placeholder:text-slate-400 w-11/12"
      id="password-input-id"
      aria-describedby="password-requirement"
      required
      ref={inputRef}
    />
    <p
      id="password-requirement"
      className="absolute w-1 h-1 -m-1 overflow-hidden clip-hidden"
    >
      tu contraseña debe incluir {passwordRequirements}
    </p>
    <button
      onClick={() => {
        setSeePassword(!seePassword);
      }}
      role="switch"
      aria-checked={seePassword}
      aria-label={
        seePassword ? `esconder contraseña` : `mostrar contraseña`
      }
      className="hover:shadow-lg hover:bg-pink-300 hover:text-black"
    >
      {seePassword ? <VisibilityOff /> : <Visibility />}
    </button>
  </div>
</form>

1) Para que nuestro input sea accesible debemos asociarlo con su label. Para que esto suceda debemos asociar el atributo htmlFor con el id del input. Al hacer esto, logramos cumplir con cuatro estandares de accesibilidad de la WCAG 2.2:

Info and Relationships (nivel A): se enfoca en asegurar que la información este claramente asociada a su contexto y estructura.
Name, Role, Value (nivel A): se enfoca que los elementos interactivos tengan nombres descriptivos, roles claros y valores significativos asociados a ellos. Esto ayuda a que las tecnologías asistivas sepan interpretarlos fácilmente.
Non-text Content (nivel A): se enfoca en proporcionar alternativas textuales a contenido no textual (imagenes, inputs, gráficos, etc). Esto ayuda a que las tecnologías asistivas sepan interpretarlos fácilmente.
Labels or Instructions (nivel A): se enfoca en asegurar que los formularios y controles interactivos tengan instrucciones claras.

2) agregar atributo autocomplete con el valor "new-password" para que el browser sepa que no se debe sugerir ni autocompletar el input con ninguna contraseña previa que el usuario haya utilizado previamente. Por otro lado, también permite notificarle a la tecnología asistiva que utilice el usuario que ese input esta "asegurado"

3) En este caso, el atributo type va a variar entre text y password. Esto se debe a que vamos a tener un botón para poder visualizar la contraseña. Este mecanismo es de vital importancia en los inputs de contraseña ya que los screen readers NO anuncian la contraseña cuando tienen un type="password" pero sí lo hacen cuando tienen un type="text", por este motivo el botón para visualizar la contraseña va a modificar el estado de visualización.

ejemplo anuncio con type="password"

ejemplo de anuncio con type="text"

Pasemos a entender la funcionalidad de este input

1) Aquí vamos a encontrar el atributo aria-describedby con el valor password-requirement. El aria-describedby nos permite proporcionar información mucho más detallada o adicional relacionada a un elemento. En formularios se utiliza para asociar mensajes de validación o instrucciones adicionales a campos específicos, lo que sería nuestro caso.
Este atributo lo asociaremos mediante un atributo id al siguiente elemento:

<p
  id="password-requirement"
  className="absolute w-1 h-1 -m-1 overflow-hidden clip-hidden"
>
  tu contraseña debe incluir {passwordRequirements}
</p>

Este elemento nos renderizará los requerimientos necesarios (en este caso en particular, pueden variar según las necesidades del input) para generar una contraseña segura y robusta. Por otro lado, nos va a permitir avisarle a la tecnología asistiva que hay información extra asociada a ese input y debe ser anunciada. En este caso va a anunciarlo de la siguiente manera:

2) También vamos a crear una referencia para que el elemento en cuestión sea lo primero que reciba foco apenas se renderiza la aplicación. De esta manera, el screen reader puede anunciar inmediatamente los requerimientos necesarios para generar una contraseña.

useEffect(() => {
  inputRef.current?.focus();
}, []);

Funcionalidad botón para mostrar/esconder contraseña

1) Es necesario que este botón tenga un atributo role con el valor switch para anunciar que es un elemento que puede ser alternado entre dos valores. En conjunto al role="switch" tendremos que colocar un aria-checked.

2) Es de vital importancia actualizar el contenido del aria-label para que el usuario tenga contexto de cuál es la acción del botón.

Validación en tiempo real de los requisitos

Si el usuario de tecnologías asistivas quiere volver a escuchar los requisitos puede simplemente presionar Control-Option-Command-Slash en VoiceOver o Control+alt+n en NVDA. A su vez, nosotros podemos proveer un mecanismo en tiempo real para que sepa cuántos requisitos lleva validados de la siguiente manera:

const [total, setTotal] = useState(requirement.length);
const checkIfAllAreChecked = useCallback(
  (requirement: Requirement[]) => {
    let fulfilledRequirements = 0;
    if (Array.isArray(requirement)) {
      requirement.forEach((req: Requirement) => {
        const matchResult = password?.match(req.matchRegex);
        setIsDirty(true);
        //cada vez que un resultado matchea con nuestro regex va a incrementar nuestro counter
        if (matchResult) {
          fulfilledRequirements++;
        }
     });
     setTotal(requirement.length - fulfilledRequirements);
    }
  },
 [password, setIsDirty]
);
{...}
<div
  role="status"
  aria-live="polite"
  aria-atomic="true"
  className="absolute w-1 h-1 -m-1 overflow-hidden clip-hidden"
  id={idInput}
>
  {total === 0 ? (
    <p>tu contraseña esta lista!</p>
  ) : (
    <p>
      {total} requisitos de {requirement.length}
    </p>
  )}
</div>

El mensaje se anunciará de la siguiente manera:

Para que esto pueda ser anunciado como una actualización debemos utilizar el role="status", en conjunto de dos atributos aria-live y aria-atomic.
El atributo aria-live="polite" sirve para saber cómo y cuando anunciar las actualizaciones a los usuarios a través de los lectores de pantalla. En este caso, el valor polite indica que las actualizaciones se anunciarán una vez que el usuario haya terminado su actividad actual. Esto significa que el lector de pantalla esperará para anunciar la actualización.
El atributo aria-atomic="true" sirve para indicarle al lector de pantalla que el contenido debe ser anunciado por completo.

Con esta breve explicación doy por finalizado este post! No obstante, no se olviden de que en el repo van a encontrar el código completo y cualquier duda o recomendación para futuros posts me las pueden hacer por privado por cualquiera de estos medios:

Linkedin: https://www.linkedin.com/in/micaelaavigliano/
Github: https://github.com/micaavigliano

Muchas gracias por leer la tercera entrada!🩷

Focus trap: como mantener el foco dentro de un modal

Mica — Mon, 27 Nov 2023 23:52:33 +0000

Primero que nada, ¡MUCHAS GRACIAS POR LEER MI POST ANTERIOR! Me siento muy contenta y orgullosa de la repercusión positiva que tuvo.

Ahora sí, podemos proceder con la continuación de mi primer post sobre el manejo del foco en nuestras aplicaciones. Ya aprendimos cómo se debe comportar el foco cuando se abre y se cierra un modal, cómo crear con un modal accesible con reactPortal, por qué esto es importante para los usuarios que navegan a través del teclado o tecnologías asistivas y a qué criterios de accesibilidad corresponden estás mejoras. Si no pudiste leerlo, te lo comparto nuevamente en el siguiente link: https://dev.to/micaavigliano/focus-management-como-mejorar-la-accesibilidad-y-usabilidad-de-nuestros-componentes-50nb, y para acceder al ejemplo productivo en el siguiente enlace: https://focus-management.netlify.app/. Allí podrán encontrar la primera parte de la explicación.

En este capítulo vamos a aprender cómo mantener o atrapar el foco dentro de un modal. Esta practica esta ligada al criterio 2.1.2 (No keyboard trap) que habla que todos nuestros componentes deben poder ser navegados enteramente con el teclado y, por ende, disponer de una vía de escape también con el teclado. Volveré a retomar el concepto de "vías de escape" más adelante.

¿Cuáles son los comandos que sirven para navegar con teclado por un modal?

tecla Tab: moverse hacía adelante entre los elementos interactivos
teclas Shift + Tab: moverse hacía atrás entre los elementos interactivos
tecla Esc: vía de escape para cerrar el modal

Recordemos que tener un buen manejo del foco también mejorará la interacción de las tecnologías asistivas con nuestros componentes.

¡Desglosemos el código!

1) Creamos una referencia del modal para poder manipular el DOM

  const modalRef = useRef<HTMLDialogElement>(null);

2) Le pasamos la referencia al modal

<dialog ref={modalRef} aria-labelledby="modal-id" aria-modal={true}>
      <div className="container-modal" onKeyUp={onKeyDown} tabIndex={-1}>
        <div className="container-info">
          <h2 className="title-modal" id="modal-id">
            {title}
          </h2>
          <button
            onClick={onClose}
            className="btn-modal"
            aria-label="close modal"
          >
            x
          </button>
        </div>
        <div className="children-container">{children}</div>
      </div>
    </dialog>

3) Vamos a necesitar generar una relación entre el dialog con el title. Para esto utilizamos aria-labelledby esto nos permite proveerle un nombre accesible a nuestro modal para que las tecnologías asistivas. Esto mismo se podría lograr utilizando un aria-label, pero como en este caso ya tenemos un elemento title nos conviene utilizar el recurso de aria-labelledby para evitar redundancias.

4) Creamos la función handleFocus

const handleFocus = (event: KeyboardEvent) => {
  const refElement = modalRef?.current;

    if (refElement) {
      const focusableElem = Array.from(
        refElement.querySelectorAll<HTMLElement>(
          'a, button, [tabindex]:not([tabindex="-1"])'
        )
      ).filter((el) => !el.hasAttribute("disabled")) as HTMLElement[];

      const firstFocusableElem = focusableElem[0];
      const lastFocusableElem = focusableElem[focusableElem.length - 1];
      const isTabPressed = event.key === "Tab";

      if (!isTabPressed) {
        return;
      }

      if (event.shiftKey) {
        if (document.activeElement === firstFocusableElem) {
          lastFocusableElem.focus();
          event.preventDefault();
        }
      } else if (document.activeElement === lastFocusableElem) {
        firstFocusableElem.focus();
        event.preventDefault();
      }
    }
  };

si modalRef.current existe, vamos a generar un array de elementos interactivos. Vamos a filtrar que no ninguno contiene el atributo disabled.
luego, vamos a guardar el primer elemento interactivo en una constante y el último elemento interactivo en otra.
Por último, en otra constante chequeamos si la tecla Tab fue presionada o no. Esto devuelve un booleano. Si devuelve false, se termina la función. Si devuelve, true la función sigue su curso.
Si la función sigue, primero vamos a chequear si el evento fue presionado junto a la tecla Shift. Si esta validación es correcta vamos a chequear si el elemento activo es el primer elemento interactivo (recordemos que la combinación Shift + Tab vamos a ir al elemento anterior) vamos a ir al último elemento interactivo. Si el evento no fue presionado junto a la tecla Shift y el elemento interactivo es el último, el primer elemento interactivo en el array va a ser el que reciba foco.

5) El último paso es crear un useEffect que se ejecutará luego de la primera renderización y va a chequear si nuestra referencia existe y si esta existe se agrega un event listener para el evento keydown en el elemento modal. Cuando ocurre un evento keydown en este elemento, se llamará a la función handleFocus. Por último, se ejecuta el cleanup para poder eliminar el event listener cuando se desmonta el componente o se vuelve a ejecutar la función.

Ya con estos pasos estamos en condiciones de poder utilizar nuestro focus trap y hacer nuestros modales 100% accesibles e interactivos.

Espero que les haya servido y como siempre me pueden contactar por cualquier medio si tienen consultas o dudas. También me gustaría si me pueden dejar en los comentarios temas que les gustaría que toquemos más adelante sobre accesibilidad y desarrollo.

Linkedin: https://www.linkedin.com/in/micaelaavigliano/
Github: https://github.com/micaavigliano

Gracias por llegar hasta acá!!!🫰

DEV Community: Mica

Accessible and Functional Quantity Spinbutton Pattern

Introduction

Expected behaviors

Keyboard

Screen Readers

NVDA Navigation

VoiceOver Navigation

Gestures VoiceOver - iOS

Gestures Talkback - Android

Pattern A: APG (ARIA Authoring Practices Guide) Spinbutton by W3C

Functional Example – APG

APG code

Conclusion for the APG Spinbutton Pattern

Pattern B: Native HTML solution

Functional Example – HTML

HTML native code

Conclusion for the HTML native solution

Final Thoughts

Accessible Pretext demo

What I did

Pretext library usage

Accessibility improvements

Semantic HTML structure

Keyboard accessibility

Screen reader orb interaction discovery

Screen reader support

prefers-reduced-motion support

Pause control

Text content and layout

Dual rendering: pretext stage + native HTML

Text wrapping around orbs

Headline fitting

Drop cap

Dynamic header clearance

Mobile and responsive behavior

Orbs and pretext stage hidden on small screens and high zoom

Collapsible header at high zoom

Mobile header and footer

Scroll snapping

WCAG success criteria

Tech stack

Accessibility: 2026 predictions

Accessible components: Pagination

Custom hook to fetch data

Pagination

Componentes accesibles: Paginación

Custom hook to fetch data

Paginación

Accordion accessible y reutilizable solo con la etiqueta details y css

¿Cómo utilizamos la etiqueta details?

Atributo name

Cómo sacar la flecha nativa del componente

¿Cómo anuncian los lectores de pantalla la etiqueta details?

Focus Management: how to improve the accessibility and usability of our components

useDataFetching hook

CardContainer.tsx

Component Card.tsx

Componente Modal.tsx

How to create an accessible tooltip using React

Tooltip.tsx

CopyToClipboard.tsx

Tooltip Accessible: como crear un copy to clipboard button

Tooltip.tsx

CopyToClipboard.tsx

✨Tabs accesibles✨

✨Validación de contraseñas accessible✨

Focus trap: como mantener el foco dentro de un modal

`prefers-reduced-motion` support

¿Cómo utilizamos la etiqueta `details`?

Atributo `name`

¿Cómo anuncian los lectores de pantalla la etiqueta `details`?