ux-ui-agent-skills 1.1.0

package/.claude/skills/a11y-audit/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: a11y-audit
+description: Audit a UI or design against WCAG 2.2 AA/AAA and ARIA patterns, returning criterion-referenced findings with severity and specific fixes. Use when the user wants an accessibility check, contrast verification, keyboard/screen-reader review, or wants to confirm a component meets POUR.
+---
+
+# Skill: Accessibility Audit
+
+Evaluate against WCAG 2.2 and the project's ARIA patterns.
+
+## Steps
+1. Read `accessibility/wcag-checklist.md` (POUR-organized, P0/P1/P2) and `accessibility/aria-patterns.md`.
+2. Check the mandatory P0 set per component: keyboard navigable, focus visible (≥3:1), screen-reader name/role/state, contrast (4.5:1 text / 3:1 UI), target size ≥24×24, no color-only signaling.
+3. Verify WCAG 2.2 additions: Focus Not Obscured (2.4.11), Target Size (2.5.8), Accessible Authentication (3.3.8).
+4. **Contrast**: run `python3 scripts/contrast.py "<fg>" "<bg>"` for every questionable pair — report ratio + pass/fail.
+5. Check reduced-motion handling (`taste/motion-choreography.md`).
+
+## Output
+A findings table: WCAG criterion (e.g. 1.4.3) · severity (P0/P1/P2) · what fails · specific fix. Confirm passes explicitly. Accessibility may never be traded for aesthetics.

package/.claude/skills/apply-aesthetic/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: apply-aesthetic
+description: Apply a visual direction — an archetype (high-end agency, editorial minimal, brutalist, soft-SaaS, dark-tech) or one of 138 named design systems (apple, linear-app, stripe, vercel, notion, material, shadcn, spotify, tesla…) — by resolving it into the token system. Use when the user wants a specific look/vibe/brand feel, or asks to make a design feel premium/expensive/non-generic.
+---
+
+# Skill: Apply Aesthetic
+
+Choose and apply a design direction without breaking accessibility.
+
+## Steps
+1. Read the brief; infer audience, domain, tone (`taste/design-taste.md` → anti-slop doctrine + Variance Mandate).
+2. Pick a direction in `taste/aesthetic-systems.md`:
+   - An **archetype** (recipe mapped to our tokens), or
+   - A **named library system** — browse with `python3 scripts/design_systems.py list` (or `search <term>` / `show <name>`); specs live in `design-systems/library/<name>/DESIGN.md`.
+3. Apply the **Library Contract** (in `aesthetic-systems.md`): re-point `semantic.*` tokens to the chosen system's color roles; map typography/spacing/radius/shadow/motion to `tokens/*.json`.
+4. **Verify contrast** of every mapped color pair (`scripts/contrast.py` / `a11y-audit`). A brand value that fails must be adjusted — taste never overrides POUR.
+5. Add motion per `taste/motion-choreography.md`; run the pre-flight aesthetic check in `design-taste.md`.
+
+## Output
+Updated/overridden semantic tokens + notes on type/space/motion, then render via `design-code`. Confirm the result passes both the aesthetic check and accessibility.

package/.claude/skills/design-code/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: design-code
+description: Generate production-ready, accessible, token-driven component code for ANY framework — React+Tailwind, Next.js, SwiftUI, Vue, Svelte, Angular, Solid, Web Components/Lit, React Native, Flutter, Jetpack Compose, vanilla CSS, or CSS-in-JS. Use when the user wants working UI code for a component or screen in a specific stack.
+---
+
+# Skill: Design Code
+
+Render components into a target framework via the adapter system.
+
+## Steps
+1. Identify the **target framework** + styling method from the request (or ask).
+2. Read `frameworks/adapter-protocol.md` (the universal contract: token resolution, component contract, styling, dark mode, motion + output rules).
+3. Load the concrete adapter:
+   - Full references: `frameworks/react-tailwind.md`, `frameworks/nextjs.md`, `frameworks/swiftui.md`.
+   - Concise adapters: `frameworks/adapters/{vue,svelte,angular,solid,web-components-lit,react-native,flutter,jetpack-compose,vanilla-css,css-in-js}.md`.
+   - **No file for the target?** Generate an adapter on the fly using the protocol's "author a new adapter" checklist.
+4. Pull the component spec from `components/*` and the ARIA pattern from `accessibility/aria-patterns.md`.
+5. Resolve all values to tokens (`tokens/*.json`); apply aesthetic direction if requested (`apply-aesthetic` skill).
+
+## Output rules (mandatory)
+Use tokens (never hardcode) · include a11y on every interactive element · handle all applicable of the 8 states · support dark mode at the semantic layer · mobile-first · honor reduced motion · **deliver complete files, no placeholders** (`workflows/redesign-audit.md` → Output Completeness).

package/.claude/skills/design-component/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: design-component
+description: Design a UI component spec to the house quality bar — anatomy, variants, sizes, the 8 states, token mapping, and accessibility. Use when the user wants to design or document a component (button, input, tabs, toast, combobox, date picker, modal, etc.) at the spec level before or alongside code. For generating framework code, use design-code.
+---
+
+# Skill: Design Component
+
+Produce a complete component specification matching the project format.
+
+## Steps
+1. Read `CLAUDE.md` → "Component Guidelines" (quality bar, the 8-state table) and "Atomic Design".
+2. Check if it already exists: `components/atoms.md`, `molecules.md`, `organisms.md`, `templates.md`, `navigation.md`, `feedback.md`, `forms-advanced.md`, `overlays.md`. Match the existing spec format.
+3. Pull the ARIA pattern from `accessibility/aria-patterns.md` and contrast/target rules from `accessibility/wcag-checklist.md`.
+4. Map every value to tokens (`tokens/*.json`) — sizes via `sizing.json`, states via `states.json`.
+5. Apply visual judgment from `taste/design-taste.md` (states, focus, no slop).
+6. Optional fast start: `python3 scripts/scaffold_component.py "<Name>"` to emit a stub, then fill it in.
+
+## Output
+Spec with: anatomy diagram, variants table, sizes table, all 8 applicable states, token mapping, accessibility (role/keyboard/SR), and a note to render via `frameworks/adapter-protocol.md`.

package/.claude/skills/design-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: design-review
+description: Review or audit a design/UI across 6 weighted dimensions with Nielsen's 10 heuristics and a prioritized findings table. Use when the user wants a design critique, quality score, heuristic evaluation, or audit of an existing screen, page, or product before/after build.
+---
+
+# Skill: Design Review
+
+Run a structured, scored review.
+
+## Steps
+1. Read `workflows/design-review.md` (rubric, scoring guide, Nielsen heuristics, process).
+2. Gather context: the screen(s)/flow, target users, platform, constraints.
+3. Score the 6 dimensions (Visual Hierarchy 20%, Consistency 20%, Accessibility 20%, Usability 20%, Responsiveness 10%, Performance 10%); compute the weighted overall.
+4. Run the accessibility lens with `accessibility/wcag-checklist.md`; use `scripts/contrast.py` for any color-pair doubts.
+5. Check against the anti-slop tells in `taste/design-taste.md` (Banned Defaults checklist).
+6. Apply Nielsen's 10 heuristics; flag violations by number.
+
+## Output
+- The 6-dimension scored table + overall score.
+- A prioritized findings table: # · Severity (Critical → Major → Minor → Enhancement) · Finding · Recommendation.
+- Concrete, token-referenced fixes.

package/.claude/skills/design-tokens/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: design-tokens
+description: Generate, extend, or audit design tokens in DTCG format with the 3-tier architecture (primitive → semantic → component). Use when the user wants a color palette, type scale, spacing/shadow/radius/motion tokens, multi-brand theming, or wants to validate token files. Covers colors, typography, spacing, shadows, borders, breakpoints, motion, gradients, opacity, blur, sizing, states, theming.
+---
+
+# Skill: Design Tokens
+
+Produce and maintain DTCG (`$type`/`$value`) tokens following the project's 3-tier system.
+
+## Steps
+1. Read `CLAUDE.md` → "Token System" + "Color/Typography/Spacing Guidelines" for the rules (4px base, Major Third scale, OKLCH palette generation, dark-mode-at-semantic-layer).
+2. Read the relevant existing files in `tokens/` to match structure: `colors.json`, `typography.json`, `spacing.json`, `shadows.json`, `borders.json`, `breakpoints.json`, `motion.json`, `gradients.json`, `opacity.json`, `blur.json`, `sizing.json`, `states.json`, `theming.json`.
+3. Generate/extend tokens:
+   - Primitives = raw values (never used directly). Semantic = purpose aliases. Component = component-scoped.
+   - New palettes: generate 11 OKLCH shades; verify 500 ≥ 4.5:1 on white (text), 600 ≥ 3:1 (UI) using the `a11y-audit` skill / `scripts/contrast.py`.
+   - Multi-brand/density → `theming.json`.
+4. **Validate**: run `python3 scripts/validate_tokens.py` (JSON validity + alias resolution).
+
+## Output
+DTCG JSON. Preserve `$description` on every token. Reference, never hardcode.

package/.claude/skills/migrate-design-system/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: migrate-design-system
+description: Map this token system to or from any external design system (Material Design 3, Apple HIG, Fluent, Carbon, Ant, shadcn/ui, Radix, Chakra, Mantine, Bootstrap…) — adopt their look, build on their stack, or migrate between systems. Use when the user mentions interop, migration, or a specific design-system/component-library bridge.
+---
+
+# Skill: Migrate / Interop Design System
+
+Bridge to or from external design systems via a role-based crosswalk.
+
+## Steps
+1. Read `design-systems/interop-protocol.md` (Crosswalk Method, the three directions, headless-vs-styled guidance, verification).
+2. Use the curated tables in `design-systems/crosswalk.md` for Material 3 / Apple HIG / Fluent 2 / Carbon / shadcn/ui / Radix. For others, derive a mapping with the Crosswalk Method (map by role/intent across 6 axes: color roles, type scale, spacing unit, radius, elevation, motion).
+3. Choose the direction:
+   - **FROM** external → our tokens (adopt their look): re-point `semantic.*`.
+   - **TO** external stack (our components on their foundation): theme their primitives with our tokens.
+   - **Migrate**: Audit → Map → Bridge (alias layer) → Verify, screen by screen.
+4. **Verify** every mapped color pair for contrast (`scripts/contrast.py` / `a11y-audit`); confirm all 8 states + dark mode survive the mapping.
+
+## Output
+A crosswalk table (our token → their token → value note), a bridge plan if migrating, and verified token overrides. Render via `design-code`.

package/.claude/skills/prototype/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: prototype
+description: Move an idea up the fidelity ladder (content-first → wireframe → low-fi → high-fi → code) with a validation plan at each level, plus user-journey mapping and usability-testing scripts. Use when the user wants to prototype, wireframe, map a user flow, or plan/run usability testing.
+---
+
+# Skill: Prototype & Research
+
+Guide work through the right fidelity level with validation.
+
+## Steps
+1. Read `workflows/prototyping.md` (5-level fidelity ladder, journey mapping template, usability-testing script, sample data).
+2. Identify the current need and pick the **lowest** fidelity that answers it — never skip levels:
+   - Content-first (info needs) → Wireframe (layout/nav) → Low-fi (task completion) → High-fi (visual/a11y) → Code (feasibility/perf).
+3. For flows: produce a user-journey map with decision points, error paths, and edge cases.
+4. For validation: define the usability test (tasks, success criteria, 5-user rule) using the script.
+5. High-fi/code steps pull tokens (`tokens/*`), components (`components/*`), taste (`taste/*`), and a11y (`accessibility/*`).
+
+## Output
+The artifact at the chosen fidelity + an explicit "what we validate next" plan.

package/.claude/skills/redesign/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: redesign
+description: Upgrade an existing website or app to premium quality without breaking functionality — audit the current design, identify generic/AI tells, then apply taste and system rules surgically. Use when the user wants to improve, modernize, polish, or "make better" an existing UI/codebase.
+---
+
+# Skill: Redesign & Audit
+
+Audit-first redesign that preserves behavior.
+
+## Steps
+1. Read `workflows/redesign-audit.md` (the full Scan → Diagnose → Direct → Apply → Verify sequence + Output Completeness).
+2. **Scan** the codebase: framework, styling method (→ route to the matching `frameworks/` adapter), token reality, components, what must be preserved.
+3. **Diagnose** with the Banned Defaults checklist (`taste/design-taste.md`) + the review rubric (`design-review` skill). Produce a prioritized findings table.
+4. **Direct**: choose an archetype/system (`apply-aesthetic` skill) that fits the brand.
+5. **Apply** in order — tokens first, then typography/spacing, then component states, then motion — without changing routes/data/markup semantics (except a11y fixes).
+6. **Verify**: re-run `design-review` + `a11y-audit`; smoke-test every previously working flow; dark mode + responsive spot-check.
+
+## Guardrails
+Never sacrifice a working feature for aesthetics. Never ship a brand color that fails contrast. Never remove existing accessibility affordances. Deliver complete files — no placeholders.

package/.claude/skills/ux-writing/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ux-writing
+description: Write or review UI copy — buttons, errors, empty states, microcopy, notifications, labels — using the voice & tone system (clear, concise, useful, human, honest) with the what→why→how error formula and inclusive-language rules. Use when the user needs interface copy, error messages, empty-state text, or a copy review.
+---
+
+# Skill: UX Writing
+
+Produce or critique interface copy in the project's voice.
+
+## Steps
+1. Read `content/voice-tone.md` (voice principles, tone spectrum, formulas, microcopy patterns, inclusive language, pre-ship checklist).
+2. Match tone to the user's emotional state (onboarding/success/routine/error/destructive). Higher stress → plainer language.
+3. Apply the formulas:
+   - Buttons: frontload the verb, name the outcome.
+   - Errors: what happened → why → how to fix (no dead ends, no codes/stack traces).
+   - Empty states: value → first action.
+4. Enforce mechanics: sentence case, no ALL CAPS, numerals, no blame on the user, labels (not placeholders), no directional/color-only instructions.
+5. Run the 10-item pre-ship copy checklist.
+
+## Output
+Final copy (or a redline review) that reads naturally aloud and passes the checklist. Keep within any character limits for tight UI.