Implementing Accessibility (A11y) in Semi Design: Guidelines and Best Practices

Semi Design’s open‑source UI library emphasizes accessibility (A11y) after recognizing that over 12 million visually impaired users in China could be excluded if accessibility is ignored.

What is A11y? A11y stands for Accessibility, aiming to provide equal experiences for all users, including temporary or situational impairments such as post‑surgery vision loss or glare.

Understanding User Needs covers four major disability categories—visual, auditory, motor, and cognitive—detailing characteristics of blind, low‑vision, color‑blind, hearing‑impaired, motor‑impaired, and cognitively challenged users and the assistive tools they rely on.

Implementation

Color

Contrast ratios must meet WCAG 2.0: at least 4.5:1 for normal text and 3:1 for large text, with exceptions for disabled text. Interactive components need a focus state with a minimum 3:1 contrast against adjacent colors. The A11y theme package addresses contrast issues, especially for problematic orange hues.

Do Not Use Color Alone

Important information should be conveyed with icons, text, or underlines in addition to color, ensuring low‑vision and color‑blind users can understand alerts and chart differences.

Keyboard and Focus

Keyboard navigation is crucial. Common shortcuts include Tab for moving focus, Shift+Tab for reverse navigation, Enter and Space to activate controls, and Esc to close dialogs. Focus management rules cover initial focus placement, reversible navigation, and returning focus after a modal is closed.

Semantic Markup

Semi components use ARIA attributes to expose role, state, and hierarchy information to screen readers, enabling users to understand element purpose, status, and position within lists.

Media

Images must include descriptive alt text; videos and audio require subtitles or transcripts for hearing‑impaired users.

Animation

Animations should not flash more than three times per second to avoid triggering seizures; flashing content must be low‑contrast and minimal.

Layout

Layouts should be clear, concise, and maintain linear reading order, remaining readable at 200% zoom to support screen magnifiers and cognitive users.

Practical Tips for Designers and Developers

Validate that color is not the sole visual cue using high‑contrast mode plugins.

Use focus‑order tools (e.g., Figma’s A11y‑Focus Orderer) and set tabIndex appropriately.

Handle focus loss in controlled components (e.g., ensure Esc closes a Popover and returns focus).

Provide alt text for images and icons, avoiding duplicate narration.

Leverage native screen‑reader shortcuts (e.g., macOS VoiceOver) for testing.

Future work will migrate from WCAG 2.0 to WCAG 3.0 and adopt the APCA contrast model, which better handles problematic hues like orange.