This skill should be used when the user is implementing accessible design, checking color contrast ratios, adding keyboard navigation, supporting screen readers, handling color blindness, implementing ARIA attributes, designing focus indicators, meeting WCAG 2.2 compliance, or building inclusive interfaces. Covers WCAG 2.2 AA requirements, color contrast (4.5:1 body, 3:1 large text), color independence (never rely on color alone), keyboard navigation, focus indicators, touch targets, screen reader considerations, and automated testing with axe-core.
npx claudepluginhub oborchers/fractional-cto --plugin visual-design-principlesThis skill uses the workspace's default tool permissions.
16% of the global population has a disability (WHO). Accessibility is not an edge case -- it is a core design quality dimension. WCAG 2.2 AA compliance is the minimum bar, not a stretch goal. Inaccessible design is broken design.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
16% of the global population has a disability (WHO). Accessibility is not an edge case -- it is a core design quality dimension. WCAG 2.2 AA compliance is the minimum bar, not a stretch goal. Inaccessible design is broken design.
| Principle | Requirement | Key Rules |
|---|---|---|
| Perceivable | All content perceivable by all users | Text alternatives, captions, sufficient contrast, no color-only meaning |
| Operable | All functionality operable via all input methods | Keyboard accessible, no time traps, skip links, focus indicators |
| Understandable | Content and operation are understandable | Plain language, consistent navigation, specific error messages |
| Robust | Content works with current and future technologies | Valid HTML, ARIA roles used correctly, tested across assistive tech |
| Element | Minimum Ratio (AA) | AAA Target | Tool |
|---|---|---|---|
| Body text (<18px / <14px bold) | 4.5:1 | 7:1 | WebAIM Contrast Checker |
| Large text (>=18px / >=14px bold) | 3:1 | 4.5:1 | Chrome DevTools |
| Non-text elements (icons, borders, focus rings) | 3:1 | -- | axe-core |
| Disabled elements | Exempt | -- | -- |
| Decorative elements | Exempt | -- | -- |
Practical rule: Test every foreground/background combination. Gray text on white is the most common failure -- #767676 on #fff is the lightest gray that passes 4.5:1.
Never rely on color alone to convey meaning. Provide redundant encoding for every color-coded element.
| Context | Bad (Color Only) | Good (Redundant Encoding) |
|---|---|---|
| Status indicators | Red dot / green dot | Red dot + "Error" label / green dot + checkmark icon |
| Form validation | Red border on invalid field | Red border + error icon + error message text |
| Charts and data viz | Color-coded lines only | Color + pattern (dash, dot) + labeled legend |
| Links in body text | Color difference only | Color + underline (or underline on hover minimum) |
| Alerts and banners | Background color only | Background color + icon + role="alert" |
Never remove :focus outlines without providing a replacement. Use :focus-visible to show focus rings only for keyboard users.
| Rule | Implementation |
|---|---|
Never use outline: none without replacement | Remove only if custom focus style is applied |
Use :focus-visible over :focus | Prevents focus rings on mouse clicks |
| Minimum focus ring | 3px solid with 2px offset in high-contrast color |
| Focus must be visible on all backgrounds | Test on light, dark, and colored backgrounds |
| Focus order must match visual order | Use tabindex="0", avoid positive tabindex values |
| Requirement | Implementation |
|---|---|
| All interactive elements reachable via Tab | Buttons, links, inputs, selects, custom widgets |
| Logical tab order | Matches visual left-to-right, top-to-bottom flow |
| Skip link as first focusable element | <a href="#main" class="skip-link">Skip to content</a> |
| Escape closes modals/dropdowns | Return focus to the trigger element |
| Arrow keys for composite widgets | Tabs, menus, radio groups, listboxes |
| No keyboard traps | Every focusable area can be exited via Tab or Escape |
Minimum touch target size is 44x44px (WCAG 2.2 Level AA). Maintain 8px minimum spacing between adjacent targets to prevent accidental activation.
| Element | Minimum Size | Minimum Spacing |
|---|---|---|
| Buttons | 44x44px | 8px |
| Links in navigation | 44px height | 8px vertical gap |
| Icon buttons | 44x44px (padding around smaller icons) | 8px |
| Inline text links | Exempt (but avoid dense clusters) | -- |
| Guideline | Rule |
|---|---|
| Heading hierarchy | h1 through h6 in logical order -- never skip levels |
| Landmark regions | <header>, <nav>, <main>, <footer>, <aside> on every page |
| Alt text strategy | Informative images: describe content. Decorative images: alt="". Complex images: aria-describedby linking to long description |
| Button labels | Avoid "Click here" -- use descriptive labels: "Download invoice PDF" |
| Form labels | Every input has a visible <label> with matching for/id |
| Live regions | aria-live="polite" for status updates, aria-live="assertive" for errors |
| Hidden content | Use aria-hidden="true" for decorative elements, sr-only class for screen-reader-only text |
| Tool | Catches | Limitation |
|---|---|---|
| axe-core | ~30% of WCAG issues: contrast, missing labels, ARIA misuse | Cannot test visual layout, reading order, keyboard flow |
| Lighthouse Accessibility | Same engine as axe-core, scores 0-100 | Score of 100 does not mean accessible |
| WAVE | Visual overlay of issues on page | Cannot test dynamic content |
Automated tools catch 30-50% of issues. Manual testing is required for: keyboard navigation flow, screen reader experience, focus management in dynamic content, reading order, and cognitive clarity.
| Anti-Pattern | Why It Fails | Fix |
|---|---|---|
| Color-only status indicators | Invisible to colorblind users (8% of males) | Add icon + text label |
outline: none without replacement | Keyboard users cannot see focus | Use :focus-visible with custom ring |
| Placeholder-only labels | Disappear on input; not announced by all screen readers | Use visible <label> elements |
| Auto-playing video/audio | Disorienting; cannot be stopped by keyboard alone | Require user-initiated play |
| Missing heading hierarchy | Screen reader users cannot navigate by headings | Use h1-h6 in logical order |
div and span as buttons | No keyboard support, no screen reader role | Use <button> or add role="button" + tabindex="0" + keyboard handler |
Positive tabindex values | Breaks natural focus order | Use tabindex="0" or -1 only |
Working implementations in examples/:
examples/accessible-form-and-focus.md -- Accessible form with proper labels, focus indicators, error messaging, and ARIA attributes in CSS/HTML/ReactWhen reviewing or building for accessibility:
:focus-visible used instead of :focus where appropriateheader, nav, main, footer)<label> with matching for/idaria-describedby