Use this skill to audit a Jylhis design-system surface (web showcase, preview card, prototype, terminal theme, CLI script, or TUI integration) against the system's accessibility commitments and the CLI/TUI design conventions. Combines automated validators with a manual review playbook covering web a11y (WCAG 2.1 AA/AAA), non-web a11y (WCAG2ICT), CLI conventions (clig.dev / GNU / 12-Factor / GitHub-CLI accessibility work), TUI design (Ratatui / Bubble Tea / Textual + WAI APG), CVD spot-checking, and keyboard / focus walk-through. Produces a structured markdown report with severity-tagged findings and pointers back to the canonical specs.
Use this skill to audit a Jylhis design-system surface (web showcase, preview card, prototype, terminal theme, CLI script, or TUI integration) against the system's accessibility commitments and the CLI/TUI design conventions. Combines automated validators with a manual review playbook covering web a11y (WCAG 2.1 AA/AAA), non-web a11y (WCAG2ICT), CLI conventions (clig.dev / GNU / 12-Factor / GitHub-CLI accessibility work), TUI design (Ratatui / Bubble Tea / Textual + WAI APG), CVD spot-checking, and keyboard / focus walk-through. Produces a structured markdown report with severity-tagged findings and pointers back to the canonical specs.
This skill audits any surface in the Jylhis design system end-to-end. It runs the static validators first, then walks a structured manual checklist that the validators cannot cover, then writes a markdown report.
The canonical specs are:
docs/ACCESSIBILITY.md — measurable WCAG commitments, CVD policy, what the validators enforce.
docs/CLI-TUI-GUIDELINES.md — CLI and TUI conventions synthesised from clig.dev, GNU, 12-Factor CLI, WCAG2ICT, GitHub-CLI accessibility work, the Sampath/Merrick/Macvean CHI paper, and Ratatui/Bubble Tea/Textual.
A new HTML preview, prototype, or showcase page is being added or significantly modified.
A new platform target is being added (terminal theme, GTK theme, etc.).
A new CLI/TUI tool is being added or an existing one substantially changed.
Before a release that touches any user-facing surface.
Skip for trivial token-only edits — the validators in CI already cover those.
Phase 1 — Pre-flight: run the validators
Run all five from the repo root and capture the output. Do not proceed to manual review until the validators pass or known failures are explicitly waived.
bun scripts/validate-tokens.mjs
bun scripts/validate-a11y-html.mjs
bun scripts/validate-a11y-css.mjs
bun scripts/validate-cli-conventions.mjs
bun scripts/generate.mjs --check
Summarise in the report:
Which validators exited 0 vs 1.
The list of errors (must be fixed before merge).
The count of warnings (acceptable but worth noting).
Any suggestions the auditor wants to act on.
Phase 2 — Web accessibility (WCAG 2.1 AA/AAA)
For HTML files in index.html, palette.html, font_options.html, md.html, platforms/index.html, preview/*.html, and prototypes/*.html:
Check
Method
Spec
<html lang> set
grep
WCAG 3.1.1
Single <h1> per page; no skipped heading levels
manual scan
WCAG 1.3.1, 2.4.6
Every <img> has alt (empty for decorative)
grep
WCAG 1.1.1
Every interactive element has an accessible name
manual + DevTools
WCAG 4.1.2
Form fields have <label> (or aria-label)
grep
WCAG 1.3.1, 3.3.2
Focus visible on every focusable element at 2px
manual Tab through
WCAG 2.4.7, 2.4.11; KEYBOARD.md
prefers-reduced-motion respected
DevTools emulation
WCAG 2.3.3
Skip-to-content link is the first focusable element on full pages
manual Tab from address bar
KEYBOARD.md
Status indicators carry a glyph or word, not colour-only
inspect each .status*/.alert*
ACCESSIBILITY.md §CVD
Resizing text to 200% in the browser keeps content usable
DevTools zoom
WCAG 1.4.4
Phase 3 — Non-web accessibility (WCAG2ICT)
For terminal themes (platforms/ghostty/, platforms/emacs/, platforms/shell/), Wayland chrome (platforms/hyprland/, platforms/waybar/, platforms/mako/, platforms/rofi/), and GUI themes (platforms/gtk/, platforms/kvantum/):
Foreground/background pairs meet the contrast floors documented in tokens.json#contrast. The token validator's extended sweep covers the four paperstock surfaces; if a platform composes its own surfaces (e.g. mako notification body), spot-check those manually with WebAIM Contrast Checker or bun scripts/validate-tokens.mjs's helpers.
Named ANSI colours are used in any terminal-emitting code (slot 11 = brand copper across the system). Hex literals only where the target requires them (Ghostty, Rofi).
Status colour is never the only signal — pairs with a glyph (✓/✗/!/i) or word.
The theme works in a remapped terminal: the user can override ANSI 0–15 via terminal preferences without breaking the design.
Phase 4 — CLI conventions
For every script in scripts/ and any consumer CLI built on top of the system, walk docs/CLI-TUI-GUIDELINES.md §2:
Real argument parser (clap / cobra / argparse / parseArgs — not hand-rolled argv walking).
-h / --help and --version handled, exit 0.
Help is example-led (lead with Examples:, then args, then options).
Stdout for data, stderr for diagnostics. No mixing.
Exit codes: 0 success, 1 runtime failure, 2 usage error. Documented when the tool defines extras.
