| name | uiux-test-doc-gen |
| description | Generate and maintain reusable UI/UX test documents under docs/uiux/ based on the current project UI implementation and the design-system constraints. Use when a developer asks to complete UI/UX test docs, add missing UI/UX scenarios, align UI constraints, or wants UI consistency/a11y/responsive regression checks during development. |
UI/UX Test Doc Gen
Generate/complete docs/uiux/** so it evolves from a generic checklist into a set of project-aligned, reproducible, executable UI/UX test scenarios.
Source Of Truth (Mutable)
docs/design-system.md is a developer-maintained and evolving source of design language and constraints. When using this skill:
- Always use the current repo's
docs/design-system.md (do not rely on memory).
- Avoid hardcoding token numeric values into test expectations. Prefer verifying "tokens/rules are used" and reference the latest values in
docs/design-system.md only when numeric thresholds are necessary.
Inputs
- Project design system:
docs/design-system.md
- Frontend code (if present):
portal/, frontend/, web/, ui/, etc.
- If available: a confirmed plan or the current diff (new routes, forms, components)
Outputs
- Update/add
docs/uiux/** docs (only what applies to the current project)
- Generate/update
docs/uiux/_surface/* (inputs like UI routes)
- Update
docs/uiux/README.md index (keep it lightweight; do not hardcode totals)
Workflow
-
Define scope
feature-only: align only UI/UX constraints related to the current feature (default)system-baseline: baseline regression across the whole UI (pre-release)
-
Discover UI surface (from code/config)
- Prefer running the UI route extraction script:
.claude/skills/uiux-test-doc-gen/scripts/extract_surface.sh- Output defaults to
docs/uiux/_surface/
- Optional override:
PORTAL_DIRS=portal,frontend,web (comma-separated)
- If output is empty: the project likely has no frontend directory yet. Maintain only generic docs and constraint notes, and clearly state "no UI integrated" in doc headers.
-
Update scenarios against the design system
- Any expectation involving visuals/interactions must align with
docs/design-system.md:
- tokens (light/dark)
- glass/fallback behavior
- spacing/radius
- focus ring/a11y
- animation duration and reduced motion
-
Align and extend by module (prefer few, high-signal, reproducible scenarios)
- Visual consistency:
docs/uiux/01-03-*.md
- Interaction experience:
docs/uiux/04-06-*.md
- Accessibility:
docs/uiux/07-accessibility.md
- Forms/lists/dialogs:
docs/uiux/08-10-*.md
- For each scenario:
- Replace
{placeholder} with real routes/selectors/component names where possible (keep a small number of placeholders for tester-supplied values)
- Provide runnable verification methods (DevTools console snippets, computed CSS checks, a11y tree checks)
-
Feature-only mapping: "change -> scenarios"
- New pages/routes:
- Update deep-link and active-nav cases in
docs/uiux/06-navigation-ia.md
- Update breakpoint coverage in
docs/uiux/05-responsive-layout.md (at least mobile/tablet/desktop)
- New forms:
- Update
docs/uiux/08-forms-validation.md (labels, errors, submission state, cancel behavior)
- If dialogs are involved: update
docs/uiux/10-dialogs-notifications.md
- New data lists/tables:
- Update
docs/uiux/09-lists-tables.md (density, pagination/sort, empty/error states)
- Theme/style changes:
- Update
docs/uiux/01-design-consistency.md and docs/uiux/02-theme-switching.md
-
Update index
- Update
docs/uiux/README.md index table:
- If some modules do not apply to the current project, remove them from the index (preferred: cleaner index)
Doc Format Rules
- Writing style reference:
.claude/skills/uiux-test-doc-gen/references/uiux-doc-style.md
- Language: English throughout. Keep technical identifiers (tokens/selectors/ARIA) as-is.
- Each doc should have <= 5 numbered scenarios (split if needed).
- Each scenario must include:
- Goal
- Steps
- Expected results (behavior/visual expectations)
- Verification tooling (runnable snippets)
References
- Design system constraints:
docs/design-system.md
- UI/UX baseline entry:
docs/uiux/README.md
- Writing style guide:
.claude/skills/uiux-test-doc-gen/references/uiux-doc-style.md
- UI surface extraction script:
.claude/skills/uiux-test-doc-gen/scripts/extract_surface.sh
