Run any Skill in Manus with one click

design-accessibility

Stars0

Forks0

UpdatedJune 14, 2026 at 10:07

Make a full-stack Rails 8.1 Hotwire UI accessible to WCAG 2.2 AA — semantic HTML, ARIA patterns, keyboard operability, visible focus, color contrast, screen-reader support, and the focus-management gotchas specific to Turbo Drive/Frames/Streams swaps — then prove it with axe automation in system tests. Menu-driven for the conformance target and the testing approach (default WCAG 2.2 AA, axe-core in Capybara system tests). This is the canonical accessibility rubric the other design-* skills cross-link to instead of repeating; apply when auditing or fixing a11y, adding ARIA, wiring keyboard/focus behavior, or setting up automated a11y tests. Web apps only.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

jcuervo

jcuervo/rails-design

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

8 files

SKILL.md

readonly

More from this repository

same repository

design-components

jcuervo/rails-design

Build a reusable UI component library for a full-stack Rails 8.1 app — choose the component architecture (ViewComponent, Phlex, or ERB partials), adopt a UI kit (daisyUI, Flowbite, Tailwind UI, or hand-rolled Tailwind), and preview/document components in isolation with Lookbook. Menu-driven with a Recommended default per menu; detects the view layer the app already chose (honors installed view_component/phlex-rails) and the installed UI kit first, builds components from the tokens design-foundations established, and verifies they render in isolation and in a page. Apply when creating buttons/cards/badges/component primitives, organizing a design system, integrating a UI kit, or setting up component previews. Web apps only.

2026-06-140

design-forms

jcuervo/rails-design

Design the forms of a full-stack Rails 8.1 Hotwire app for usability and accessibility — the form builder (form_with helpers, simple_form, or a form object), the layout (stacked, floating, or inline labels), and the validation/error UX (server-rendered errors via Turbo Streams with a 422, inline hints, or full reload), plus multi-step flows and accessible input patterns. Menu-driven with a Recommended default per menu; detects the installed form gem and validation approach first, builds from design-foundations tokens and design-components inputs, and verifies forms submit, show errors correctly, and pass an accessibility check. Owns form layout and error UX; defers params to rails-controllers, validations to rails-models, and Turbo response codes to rails-hotwire. Web apps only.

2026-06-140

design-foundations

jcuervo/rails-design

Establish the design-system foundations of a full-stack Rails 8.1 app — the color/spacing/typography tokens, the theming strategy, dark mode, and the modular type & spacing scale — on top of the app's chosen CSS stack (Tailwind v4 CSS-first `@theme`, Tailwind v3 `tailwind.config.js`, daisyUI semantic themes, or plain CSS custom properties). Menu-driven with a Recommended default per menu; detects the Tailwind major and any installed UI kit first (v4 configures tokens in CSS via `@theme`, v3 in JS), and verifies the stylesheet builds and the tokens render. Start here before building components — every other design-* skill consumes these tokens. Web apps only; API-only apps have no design layer.

2026-06-140

design-interactions

jcuervo/rails-design

Design the interactive UX micro-patterns of a full-stack Rails 8.1 Hotwire app — modals/dialogs, drawers, dropdowns, tabs, toast/flash notifications, inline editing, loading/skeleton states, empty states, and infinite scroll — built with Turbo Frames/Streams and Stimulus. Menu-driven with a Recommended default per menu (native <dialog> + Turbo Frame + Stimulus for overlays, Stimulus auto-dismiss + Turbo Stream for toasts, Turbo loading states + skeletons for feedback). Owns the visual/UX shape of these patterns and the accessibility contract each must meet (the canonical a11y rules live in design-accessibility); the Turbo/Stimulus plumbing is rails-hotwire. Detects the installed UI kit and Hotwire wiring first, then verifies the interaction works and is keyboard/screen-reader accessible. Apply when building any of these patterns. Web apps only.

2026-06-140

design-layout-navigation

jcuervo/rails-design

Build the page structure and navigation of a full-stack Rails 8.1 Hotwire app — the application shell (layout + content regions, header/main/footer landmarks), primary navigation (top navbar, sidebar, or hybrid), breadcrumbs and active-state highlighting, responsive/mobile navigation, and pagination UX (Pagy). Menu-driven with a Recommended default per menu; detects the existing layout, nav, and pagination gem first, builds from design-foundations tokens and design-components primitives, and verifies the shell renders responsively with correct landmarks. Apply when creating the app layout, a navbar/sidebar, breadcrumbs, a responsive menu, or paginating a list. Web apps only.

2026-06-140

design-visual-qa

jcuervo/rails-design

Prove the UI of a full-stack Rails 8.1 Hotwire app actually works — system tests that exercise the rendered Turbo/Stimulus flows, visual-regression screenshots to catch unintended visual changes, automated accessibility checks (axe) wired into the suite, and Lookbook-based component review. Menu-driven with a Recommended default per menu (Selenium/headless Chrome driver, built-in screenshot diffing, axe-core a11y assertions). Owns the visual/UX assertions; the test stack itself — framework, driver, CI — is owned by rails-testing, and the a11y rules by design-accessibility. Detects the installed test framework and driver first, then verifies the UI renders, matches its baseline, and is accessible. Apply when testing UI flows, catching visual regressions, or gating a11y in CI. Web apps only.

2026-06-140

name	design-accessibility
description	Make a full-stack Rails 8.1 Hotwire UI accessible to WCAG 2.2 AA — semantic HTML, ARIA patterns, keyboard operability, visible focus, color contrast, screen-reader support, and the focus-management gotchas specific to Turbo Drive/Frames/Streams swaps — then prove it with axe automation in system tests. Menu-driven for the conformance target and the testing approach (default WCAG 2.2 AA, axe-core in Capybara system tests). This is the canonical accessibility rubric the other design-* skills cross-link to instead of repeating; apply when auditing or fixing a11y, adding ARIA, wiring keyboard/focus behavior, or setting up automated a11y tests. Web apps only.
metadata	{"owner":"rails-design","status":"stable"}
user-invocable	true
argument-hint	[component-or-page]

design-accessibility

Purpose

The canonical accessibility rubric for the suite. Owns WCAG 2.2 AA conformance for a Hotwire UI: semantic HTML first, ARIA only where HTML falls short, full keyboard operability, always-visible focus, sufficient color contrast, screen-reader support, and the focus-management problems unique to Turbo (Drive visits, Frame/Stream DOM swaps that move focus or announce nothing). It then makes a11y enforceable with axe-core in system tests. Every other design-* skill defers here for a11y rather than re-documenting it — link to this skill, don't copy it.

When to Apply

Use this skill when the task is:

Auditing a page/component against WCAG 2.2 AA or fixing reported a11y issues
Adding ARIA (roles/states/properties) to a custom widget
Making something keyboard operable (tab order, Esc/Enter/arrow keys, focus traps)
Fixing focus after a Turbo Frame/Stream swap, modal open/close, or Drive visit
Ensuring screen-reader announcements (live regions, labels, names)
Wiring automated a11y tests (axe-core in Capybara, Lighthouse CI)

Do not use this skill when the task is:

Choosing contrast-safe tokens at the source → read ../design-foundations/SKILL.md (it sets safe color pairs; this skill audits the result)
The interaction mechanics of a modal/dropdown/toast → read ../design-interactions/SKILL.md (it builds them; link here for the a11y requirements)
Form field/label/error structure → read ../design-forms/SKILL.md (it owns form UX; this skill owns the a11y rules it must meet)
The Turbo/Stimulus plumbing itself → read ../rails-hotwire/SKILL.md
The test stack setup (drivers, CI) → read ../rails-testing/SKILL.md (this skill adds a11y assertions on top)
An API-only app — no UI to make accessible

Detect Before You Generate

grep -nE "api_only" config/application.rb               # api_only=true → no UI; stop
grep -E "axe-core-rspec|axe-core-capybara|axe-matchers|lighthouse" Gemfile.lock 2>/dev/null
ls spec/system test/system 2>/dev/null                  # where a11y system tests will live
grep -rlnE "aria-|role=" app/views app/components 2>/dev/null | head   # existing ARIA usage
grep -rnE "tabindex=\"[1-9]" app/views app/components 2>/dev/null       # positive tabindex (anti-pattern)
grep -rlnE "lang=" app/views/layouts 2>/dev/null        # <html lang> present?

If axe-core-capybara/axe-core-rspec is installed, wire assertions into the existing system-test setup (driver/framework owned by ../rails-testing/).
Existing ARIA/tabindex usage tells you where custom widgets already exist — audit those first; they're the likeliest violations.
<html lang> and a real <title> per page are baseline — confirm they exist.

Option	One-line trade-off	Deep dive
WCAG 2.2 AA (Recommended)	The standard target for most apps and the bar most regulations reference. Comprehensive without AAA's extremes.	wcag-checklist.md
WCAG 2.2 AAA	Highest bar (7:1 contrast, etc.); rarely required wholesale, hard to sustain. Adopt specific criteria, not all.	wcag-checklist.md
WCAG 2.2 A	Minimum legal floor; leaves real barriers (contrast, focus). Use only as a stepping stone to AA.	wcag-checklist.md

Automated a11y testing

Option	One-line trade-off	Deep dive
axe-core in system tests (Recommended)	Runs the axe engine on real rendered pages in Capybara; catches ~30–50% of issues automatically, in CI.	axe-system-tests.md
Manual axe DevTools	Browser-extension scans during development; great for spot checks, not enforced in CI.	axe-system-tests.md
Lighthouse CI	Page-level a11y score in CI alongside perf; coarser than axe-core assertions.	axe-system-tests.md

Decision Flow

Target AA. It's the right default and what audits/regulations expect. Pull in a specific AAA criterion (e.g. enhanced contrast) where it matters; don't chase AAA wholesale. Treat A as a floor you're already past.
Automate with axe-core in system tests and keep manual testing — automation catches contrast, missing names/labels, and structural issues but cannot judge meaningful focus order, sensible announcements, or whether a name describes its control. Budget manual keyboard + screen-reader passes for key flows.
Semantic HTML before ARIA. A <button>, <a>, <nav>, <dialog>, <label> carries role + keyboard behavior for free. Reach for ARIA only to fill gaps — and remember "no ARIA is better than bad ARIA."
Turbo changes the focus contract. Frame/Stream swaps and Drive visits move or drop focus and don't announce changes by default. Manage focus and use live regions explicitly — see focus-management-hotwire.md.

Problem → Reference

Task	Read
Audit against WCAG 2.2 AA (the checklist, what's new in 2.2)	references/wcag-checklist.md
ARIA roles/states for custom widgets (and when NOT to use ARIA)	references/aria-patterns.md
Focus after Turbo Frame/Stream swaps, modal open/close, Drive visits	references/focus-management-hotwire.md
Keyboard operability: tab order, Esc/Enter/arrows, skip links, traps	references/keyboard-navigation.md
Color contrast audit (AA ratios, non-color cues)	references/color-contrast.md
Screen-reader testing (VoiceOver/NVDA), live regions, names	references/screen-reader-testing.md
Automated a11y tests: axe-core in Capybara, CI wiring	references/axe-system-tests.md

Verify

Accessibility is verified by machine + keyboard + screen reader — all three:

# 1) Automated: axe-core finds zero violations on key pages (in a system test)
bin/rails test test/system 2>/dev/null || bundle exec rspec spec/system
#    a passing a11y system test asserts: expect(page).to be_axe_clean (or run_axe)

# 2) Keyboard: load the page, unplug the mouse — Tab through every interactive element,
#    operate each with Enter/Space/Esc/arrows, confirm focus is always visible.

# 3) Screen reader: VoiceOver (⌘F5 on macOS) or NVDA — every control announces a
#    meaningful name + role; Turbo updates are announced via live regions.

A page is accessible when axe is clean and it's fully keyboard-operable and a screen reader narrates it sensibly. Wire the axe assertion into ../rails-testing/'s suite so regressions fail CI.

design-accessibility

design-accessibility

Purpose

When to Apply

Detect Before You Generate

Menu

Conformance target

Automated a11y testing

Decision Flow

Problem → Reference

Verify

design-accessibility

Purpose

When to Apply

Detect Before You Generate

Menu

Conformance target

Automated a11y testing

Decision Flow

Problem → Reference

Verify