Accessibility

All Constructs must meet WCAG 2.1 AA standards. This ensures everyone can use your app.

Why Accessibility Matters

• 15% of the world's population has some form of disability
• Legal requirement in many countries
• Better UX for everyone - keyboard users, power users, etc.
• Required for approval - Constructs failing accessibility checks will be rejected

Form Labels

Every form input must have an associated label:

Do this

<div className="space-y-2">
  <Label htmlFor="email">Email</Label>
  <Input id="email" type="email" />
</div>

Not this

<div>
  <p>Email</p>
  <Input type="email" />
</div>

Icon Buttons

Buttons with only icons must have aria-label:

Do this

<Button
  variant="ghost"
  size="icon"
  aria-label="Delete item"
>
  <Trash2 className="h-4 w-4" />
</Button>

Not this

<Button variant="ghost" size="icon">
  <Trash2 className="h-4 w-4" />
</Button>

Semantic HTML

Use the right HTML elements for their intended purpose:

Use	For	Not
<button>	Interactive actions	<div onClick>
<a href>	Navigation links	<span onClick>
<nav>	Navigation sections	<div>
<main>	Main content area	<div>
<section>	Thematic grouping	<div>
<article>	Self-contained content	<div>

All interactive elements must be keyboard accessible:

Key	Action
Tab	Move to next focusable element
Shift + Tab	Move to previous focusable element
Enter / Space	Activate buttons, checkboxes
Escape	Close dialogs, dropdowns
Arrow keys	Navigate within components

// Add keyboard shortcuts where helpful
const handleKeyDown = (e: React.KeyboardEvent) => {
  if (e.key === "Enter") {
    handleSubmit();
  }
};

<Input onKeyDown={handleKeyDown} />

Focus States

shadcn/ui components have built-in focus styles. Don't remove them:

Never do this

<Button className="focus:outline-none">  // BAD!
<Input className="focus:ring-0">           // BAD!

Color Contrast

Text must have sufficient contrast against its background:

Text Type	Minimum Ratio
Normal text	4.5:1
Large text (18px+ or 14px+ bold)	3:1
UI components & graphics	3:1

Safe Choices

Stick to the built-in CSS variables like text-foreground and text-muted-foreground which are designed to meet contrast requirements in both light and dark modes.

Accessibility Checklist

Before submitting, verify your Construct meets these requirements:

All form inputs have associated labels

Icon-only buttons have aria-label

Can navigate entire UI with Tab key

Can activate all buttons with Enter/Space

Focus states are visible on all interactive elements

Text has sufficient color contrast

Using semantic HTML elements

Dialogs can be closed with Escape

Testing Accessibility

• Keyboard only: Unplug your mouse and navigate the entire UI
• Screen reader: Test with VoiceOver (Mac) or NVDA (Windows)
• Browser DevTools: Use Lighthouse accessibility audit
• Validator: Our validator checks for common issues

$ construct-skill validate ./App.tsx