Accessibility

Accessibility is a product requirementLink to section

Accessibility is not a finishing step.

It is part of how your product behaves for real users:

• keyboard users
• screen reader users
• low-vision users
• users on mobile or slow networks

A product that is not accessible is harder to use for everyone.

What PyColors expectsLink to section

PyColors UI primitives are built to support accessibility.

But primitives are not enough.

You must ensure:

• correct semantics
• proper labeling
• predictable focus behavior
• accessible interactions
• meaningful feedback

Accessibility happens at the composition level, not only inside components.

The 4 pillarsLink to section

Semantics firstLink to section

Always use the correct HTML element.

GoodLink to section

<button>Save</button>
<a href="/docs">Docs</a>
<input type="email" />

BadLink to section

<div onClick={handleClick}>Save</div>

Labels and textLink to section

Every interactive element needs a clear label.

InputsLink to section

<label htmlFor="email">Email</label>
<input id="email" type="email" />

Icon buttonsLink to section

<button aria-label="Open settings">
  <SettingsIcon />
</button>

Do not rely only on icons.

Keyboard navigationLink to section

Users must be able to:

• tab through elements
• trigger actions with Enter or Space
• close overlays with Escape

ChecklistLink to section

• all interactive elements are focusable
• focus order follows visual order
• no keyboard traps
• visible focus state

Focus managementLink to section

Focus should move logically.

Example: dialogLink to section

• open → focus moves inside
• close → focus returns to trigger

This is critical for accessibility.

Color and contrastLink to section

Do not rely on color alone.

BadLink to section

• red = error
• green = success

BetterLink to section

• icon + text + color

Ensure sufficient contrast between:

• text and background
• UI elements and surfaces

Feedback and stateLink to section

Users must understand:

• loading
• success
• error

ExampleLink to section

<Button disabled>
  Saving...
</Button>

<Alert variant="destructive">
  Payment failed. Try again.
</Alert>

FormsLink to section

Accessible forms require:

• labels
• error messages
• clear validation

ExampleLink to section

<label>Email</label>
<input />
<p role="alert">Invalid email</p>

Overlays (Dialog, Sheet)Link to section

Overlays must:

• trap focus
• be dismissible via Escape
• restore focus on close

Use accessible primitives (Radix-based).

Tables and dataLink to section

Tables should:

• use proper <table> structure
• include headers
• support keyboard navigation if interactive

Composition rulesLink to section

Accessibility lives in composition.

• UI components should stay simple
• pages must enforce accessibility rules
• patterns must define interaction behavior

Prefer / avoidLink to section

Quick checklistLink to section

• all actions are keyboard accessible
• labels are explicit
• focus is visible and logical
• errors are announced
• UI is understandable without color

Next stepsLink to section