The Craftsman standard for UI/UX — design tokens, component patterns, pixel-perfect standards, Tailwind/React implementation, motion craft, an AI-tells anti-pattern catalog, and a two-pass review protocol (static review + live browser audit). Use this whenever designing, building, reviewing, auditing, redesigning, or polishing UI — a component, page, dashboard, landing page, modal, form, or layout; standing up or hardening a design system; checking spacing, typography, color, motion, or accessibility; or hunting AI-generated "tells". Trigger even on "make this look better", "fix the styling", "audit my design tokens", or "test it in the browser" without naming a tool or framework. App architecture (state, data fetching, bundles, routing) → craft-frontend. Does NOT fire on backend, database, CI/CD, or infra requests, or UI-free code-quality asks.
The single, self-contained standard for building UI with consistency and intention — applied the
same way across every repo. The method and opinions live here; the project specifics (token
names, component paths, framework) live in the target repo and are always discovered, never
hardcoded. Illustrated stack: Tailwind + React are the primary examples in references;
layering principles (tokens → primitives → components → states → motion) apply regardless — do not
invent large Vue/Svelte-specific docs when the project uses another UI stack; map principles to what
discovery finds.
Standards, patterns, motion frameworks, and review protocols live in references/ and load on
demand. Before any non-trivial task, read references/foundations.md — it defines the persona,
operating principles, the discover-before-build discipline, standing opinions, hard constraints, and
communication style that everything else assumes.
Supersedes the older split skills: elite-ux-architect, ux-architect, review-ux,
design-motion-principles, redesign-existing-projects.
Initialization
When invoked without a specific task: introduce capabilities briefly, ask for direction. Do not
proactively audit, scan files, or assess implementation quality. Wait for the user.
The design-system layers (build in this order)
The spine of the skill. Each layer builds on the one below; get the lower layers right before
reaching for the higher ones. For the meta-guide on how to stand up (or harden) the whole system
— the layered architecture, the CSS-variable bridge, governance, and migration order — read
references/building-a-design-system.md. To keep it from rotting, references/token-audit.md covers
finding violations and building the scanner that blocks them in CI.
Tokens — color, spacing, typography as CSS variables + a typed module. → references/layer-1-tokens.md
Primitives & implementation — Stack/Inline/Grid/Box and the Tailwind/cn()/CVA
mechanics every component sits on. → references/layer-2-primitives.md
Components — the supported set (forms, tables, modals, nav, notifications) with consistent
variant/size APIs. → references/layer-3-components.md
States — loading, empty, error, disabled as first-class. → references/layer-4-states.md
Motion & accessibility — purposeful motion + the a11y floor. → references/layer-5-motion.md
(three designer deep-dives live in references/motion/ — Emil, Jakub, Jhey)
Reference index
Task
Load
Persona, principles, discover-first, standing opinions, hard constraints
references/foundations.md
Build a design system from scratch or harden an ad-hoc one — layered architecture, bridge, governance
references/building-a-design-system.md
Audit / enforce design tokens — find violations, fix by category, build the scanner
Web Interface Guidelines rule list — vendored, SHA-pinned, applied by the compliance pass
references/web-interface-guidelines.md
Live audit — drive the running app (Playwright / claude-in-chrome) for rendered/visual defects
references/live-audit.md
Standard workflows
Workflow
Mandatory
Add when needed
Build a design system
foundations + building-a-design-system
layer-1 for token values, starter-kits for greenfield fonts/palettes, layer-2 for primitives, token-audit to add the scanner
Audit / enforce tokens
token-audit
layer-1 for the canonical values, building-a-design-system for where a value belongs, anti-patterns for tells
Build a component
foundations + layer-2
layer-3 for the pattern, layer-1 for token values, layer-4 for its states
Build a page / dashboard
foundations + layer-2 + composition
layer-3 for components, composition arsenal for a distinctive aesthetic
Polish interactions
foundations + layer-5
layer-5 routes to the right designer (motion/*); layer-1 for timing values
Review code
review-protocol + anti-patterns
layer-3 for forms/modals/tables/states, layer-2 for Tailwind/CVA/hydration/perf, layer-1 for visual specifics
Live audit (Pass 2)
live-audit (after the static review)
review-protocol for the shared severity model + output format; layer-4 for the empty/loading/error states to force
Audit motion
layer-5 (routes by context)
whichever motion/* designer reference it weights
Redesign existing UI
redesign-audit (Scan→Diagnose→Fix)
anti-patterns for the Diagnose pass, layer-2 + layer-1 for the Fix pass
Load lazily. Pull a file only when the task actually asks the question it answers — don't
preload the "add when needed" column.
Pair with project context
This skill is reusable across products and carries the full standards + craft on its own. For
project-specific competitive intelligence, stack constraints, and routing to project-only utility
skills (a token-audit gate, RTL rules, perf audit), the calling agent may also load a thin
project-level UX skill. The project skill provides the "why this matters here" frame; this skill
provides the standards and craft. impeccable remains available for extra aesthetic exploration,
but is no longer required — craft-ux is self-sufficient for persona + system + review.
Audit checklist (for craft-audit)
When craft-audit plans a ux pass for a scope, it turns this checklist into the plan.md
todo list — the checklist is owned by this skill, not improvised by the orchestrator. Tailor to what
discovery found: skip a step that genuinely doesn't apply with a one-line reason; never silently drop
one. Emit findings using craft-audit workspace.md → "Canonical findings.md emission format"
(authority). Heading grammar (variables required — do not hardcode NNN/severity/status):
## <scopeLabel>-UX-<NNN> · severity <🔴|🟡|🟢> · status <open|fixed|wontfix (reason)|regressed|fixed (merged into <ID>)>
Example only: ## <scopeLabel>-UX-001 · severity 🔴 · status open
Required fields under each heading, in order, with these exact labels:
**What breaks (plain language):** · **Technical:** · **Fix:** · **Fingerprint:** ·
**Last-checked:** (optional **Confidence:** — verified | inferred | unverified-from-repo, absent
means verified — then optional **Fix-attempt:** only from craft-fix).
Assign sequential NNN per (scope, domain); judge severity with craft-audit prioritization.md.
Forbidden: ### headings; ## ID · 🔴 · open shorthand; severity/status as body bullets.
Run discovery first — locate the token module, layout primitives, and scanner; flag "no layered
system" or tokens that exist but are bypassed/misused, not just absent → references/foundations.md
Audit design tokens for adoption — hardcoded raw palette colors, raw spacing, and structured
tokens passed where a class string is expected; build/confirm the CI scanner → references/token-audit.md
Check visual fidelity against the token scale — off-scale spacing, typography, color, radius,
shadows, icons, and motion-timing values → references/layer-1-tokens.md
Verify state completeness — every route subtree has loading/empty/error boundaries (reason about
cascade + layout/provider errors), no populated-only views → references/layer-4-states.md
Review component patterns — forms (labels, semantic type, autocomplete), modals, tables, nav,
and notifications for consistent variant/size APIs and missing a11y → references/layer-3-components.md
Sweep for AI-tells and dark/technical anti-patterns — transition-all, <div onClick>,
outline-none with no focus ring, <img> without dimensions → references/anti-patterns.md
Check footer/legal furniture — privacy policy and terms links reachable from every page (not
just the marketing homepage), and any consent banner offers equally easy accept/decline →
references/layer-3-components.md
Run motion audit protocol — verify prefers-reduced-motion is handled, duration/easing tokens
are used consistently (not magic numbers), no layout-property animations, ARIA live regions on
dynamic content, and no janky animations on low-end hardware → references/layer-5-motion.md
Run the static review with its grep sweep + Web-Interface Compliance pass against the vendored
references/web-interface-guidelines.md (no review-time network fetch) — severity model
(Critical / Important / Opportunities → 🔴 / 🟡 / 🟢) from references/review-protocol.md;
emission path depends on context: under craft-audit / writing .craftsman/**/findings.md,
emit each finding in the canonical workspace heading format above (not the punch-list tables);
standalone UX review may use the review-protocol banner + tables → references/review-protocol.md
Run the live pass after the static one — clear the preflight gate (non-prod, throwaway identity,
side effects neutralized), then walk flows × 375/768/1280 × empty/loading/error, tagging each
finding with its rendered condition; same dual-emission rule as the static pass →
references/live-audit.md
1---2name: craft-ux3description: The Craftsman standard for UI/UX — design tokens, component patterns, pixel-perfect standards, Tailwind/React implementation, motion craft, an AI-tells anti-pattern catalog, and a two-pass review protocol (static review + live browser audit). Use this whenever designing, building, reviewing, auditing, redesigning, or polishing UI — a component, page, dashboard, landing page, modal, form, or layout; standing up or hardening a design system; checking spacing, typography, color, motion, or accessibility; or hunting AI-generated "tells". Trigger even on "make this look better", "fix the styling", "audit my design tokens", or "test it in the browser" without naming a tool or framework. App architecture (state, data fetching, bundles, routing) → craft-frontend. Does NOT fire on backend, database, CI/CD, or infra requests, or UI-free code-quality asks.4---56# UX Craft78The single, self-contained standard for building UI with consistency and intention — applied the9same way across every repo. The **method and opinions** live here; the **project specifics** (token10names, component paths, framework) live in the target repo and are always discovered, never11hardcoded. **Illustrated stack:** Tailwind + React are the primary examples in references;12layering principles (tokens → primitives → components → states → motion) apply regardless — do not13invent large Vue/Svelte-specific docs when the project uses another UI stack; map principles to what14discovery finds.1516Standards, patterns, motion frameworks, and review protocols live in `references/` and load on17demand. **Before any non-trivial task, read `references/foundations.md`** — it defines the persona,18operating principles, the discover-before-build discipline, standing opinions, hard constraints, and19communication style that everything else assumes.2021> **Supersedes** the older split skills: `elite-ux-architect`, `ux-architect`, `review-ux`,22> `design-motion-principles`, `redesign-existing-projects`.2324## Initialization2526When invoked without a specific task: introduce capabilities briefly, ask for direction. **Do not27proactively audit, scan files, or assess implementation quality.** Wait for the user.2829## The design-system layers (build in this order)3031The spine of the skill. Each layer builds on the one below; get the lower layers right before32reaching for the higher ones. For the meta-guide on **how to stand up (or harden) the whole system**33— the layered architecture, the CSS-variable bridge, governance, and migration order — read34`references/building-a-design-system.md`. To keep it from rotting, `references/token-audit.md` covers35finding violations and building the scanner that blocks them in CI.36371. **Tokens** — color, spacing, typography as CSS variables + a typed module. → `references/layer-1-tokens.md`382. **Primitives & implementation** — `Stack`/`Inline`/`Grid`/`Box` and the Tailwind/`cn()`/CVA39 mechanics every component sits on. → `references/layer-2-primitives.md`403. **Components** — the supported set (forms, tables, modals, nav, notifications) with consistent41 variant/size APIs. → `references/layer-3-components.md`424. **States** — loading, empty, error, disabled as first-class. → `references/layer-4-states.md`435. **Motion & accessibility** — purposeful motion + the a11y floor. → `references/layer-5-motion.md`44 (three designer deep-dives live in `references/motion/` — Emil, Jakub, Jhey)4546## Reference index4748| Task | Load |49| --------------------------------------------------------------------------------------------------------- | ---------------------------------------- |50| **Persona, principles, discover-first, standing opinions, hard constraints** | `references/foundations.md` |51| **Build a design system** from scratch or harden an ad-hoc one — layered architecture, bridge, governance | `references/building-a-design-system.md` |52| **Audit / enforce design tokens** — find violations, fix by category, build the scanner | `references/token-audit.md` |53| Spacing, typography, color, radius, shadows, icons, touch targets, motion-timing tokens, breakpoints | `references/layer-1-tokens.md` |54| **Greenfield starter kits** — vetted font pairings + contrast-verified palettes + variation protocol | `references/starter-kits.md` |55| Layout primitives; Tailwind, `cn()`, CVA, mobile-first, dark mode, hydration safety, perf building blocks | `references/layer-2-primitives.md` |56| Forms, tables, modals, navigation, notifications; component anatomy + variant APIs | `references/layer-3-components.md` |57| Empty / loading / error / disabled states | `references/layer-4-states.md` |58| Motion audit framework + accessibility fundamentals | `references/layer-5-motion.md` |59| Emil Kowalski — restraint, speed, springs, clip-path, gestures | `references/motion/emil-craft.md` |60| Jakub Krehel — production polish, subtle enter/exit, shadows, optical alignment | `references/motion/jakub-polish.md` |61| Jhey Tompkins — playful CSS, `linear()`, `@property`, scroll-driven, 3D | `references/motion/jhey-experimental.md` |62| Fluid gesture physics — velocity handoff, momentum projection, rubberbanding, sheets/drag/swipe | `references/motion/fluid-gestures.md` |63| Page/dashboard architecture, landing sections, Bento, design-intensity calibration | `references/composition.md` |64| Canonical AI-tells catalog — **what to flag in reviews** | `references/anti-patterns.md` |65| Redesigning existing UI — Scan → Diagnose → Fix | `references/redesign-audit.md` |66| Code-review **structure** + web-interface compliance checklist (static pass) | `references/review-protocol.md` |67| Web Interface Guidelines rule list — vendored, SHA-pinned, applied by the compliance pass | `references/web-interface-guidelines.md` |68| **Live audit** — drive the running app (Playwright / `claude-in-chrome`) for rendered/visual defects | `references/live-audit.md` |6970## Standard workflows7172| Workflow | Mandatory | Add when needed |73| ---------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |74| **Build a design system** | `foundations` + `building-a-design-system` | `layer-1` for token values, `starter-kits` for greenfield fonts/palettes, `layer-2` for primitives, `token-audit` to add the scanner |75| **Audit / enforce tokens** | `token-audit` | `layer-1` for the canonical values, `building-a-design-system` for where a value belongs, `anti-patterns` for tells |76| **Build a component** | `foundations` + `layer-2` | `layer-3` for the pattern, `layer-1` for token values, `layer-4` for its states |77| **Build a page / dashboard** | `foundations` + `layer-2` + `composition` | `layer-3` for components, `composition` arsenal for a distinctive aesthetic |78| **Polish interactions** | `foundations` + `layer-5` | `layer-5` routes to the right designer (`motion/*`); `layer-1` for timing values |79| **Review code** | `review-protocol` + `anti-patterns` | `layer-3` for forms/modals/tables/states, `layer-2` for Tailwind/CVA/hydration/perf, `layer-1` for visual specifics |80| **Live audit (Pass 2)** | `live-audit` (after the static review) | `review-protocol` for the shared severity model + output format; `layer-4` for the empty/loading/error states to force |81| **Audit motion** | `layer-5` (routes by context) | whichever `motion/*` designer reference it weights |82| **Redesign existing UI** | `redesign-audit` (Scan→Diagnose→Fix) | `anti-patterns` for the Diagnose pass, `layer-2` + `layer-1` for the Fix pass |8384**Load lazily.** Pull a file only when the task actually asks the question it answers — don't85preload the "add when needed" column.8687## Pair with project context8889This skill is reusable across products and carries the full standards + craft on its own. For90project-specific competitive intelligence, stack constraints, and routing to project-only utility91skills (a token-audit gate, RTL rules, perf audit), the calling agent may also load a thin92project-level UX skill. The project skill provides the "why this matters here" frame; this skill93provides the standards and craft. `impeccable` remains available for extra aesthetic exploration,94but is no longer required — `craft-ux` is self-sufficient for persona + system + review.9596## Audit checklist (for craft-audit)9798When `craft-audit` plans a ux pass for a scope, it turns this checklist into the `plan.md`99todo list — the checklist is owned by this skill, not improvised by the orchestrator. Tailor to what100discovery found: skip a step that genuinely doesn't apply with a one-line reason; never silently drop101one. Emit findings using craft-audit `workspace.md` → "Canonical findings.md emission format"102(authority). Heading grammar (variables required — do not hardcode NNN/severity/status):103104`## <scopeLabel>-UX-<NNN> · severity <🔴|🟡|🟢> · status <open|fixed|wontfix (reason)|regressed|fixed (merged into <ID>)>`105106Example only: `## <scopeLabel>-UX-001 · severity 🔴 · status open`107108Required fields under each heading, in order, with these exact labels:109`**What breaks (plain language):**` · `**Technical:**` · `**Fix:**` · `**Fingerprint:**` ·110`**Last-checked:**` (optional `**Confidence:**` — `verified | inferred | unverified-from-repo`, absent111means `verified` — then optional `**Fix-attempt:**` only from craft-fix).112Assign sequential NNN per (scope, domain); judge severity with craft-audit `prioritization.md`.113Forbidden: `###` headings; `## ID · 🔴 · open` shorthand; severity/status as body bullets.114115- [ ] Run discovery first — locate the token module, layout primitives, and scanner; flag "no layered116 system" or tokens that exist but are bypassed/misused, not just absent → `references/foundations.md`117- [ ] Audit design tokens for adoption — hardcoded raw palette colors, raw spacing, and structured118 tokens passed where a class string is expected; build/confirm the CI scanner → `references/token-audit.md`119- [ ] Check visual fidelity against the token scale — off-scale spacing, typography, color, radius,120 shadows, icons, and motion-timing values → `references/layer-1-tokens.md`121- [ ] Verify state completeness — every route subtree has loading/empty/error boundaries (reason about122 cascade + layout/provider errors), no populated-only views → `references/layer-4-states.md`123- [ ] Review component patterns — forms (labels, semantic `type`, autocomplete), modals, tables, nav,124 and notifications for consistent variant/size APIs and missing a11y → `references/layer-3-components.md`125- [ ] Sweep for AI-tells and dark/technical anti-patterns — `transition-all`, `<div onClick>`,126 `outline-none` with no focus ring, `<img>` without dimensions → `references/anti-patterns.md`127- [ ] Check footer/legal furniture — privacy policy and terms links reachable from every page (not128 just the marketing homepage), and any consent banner offers equally easy accept/decline →129 `references/layer-3-components.md`130- [ ] Run motion audit protocol — verify `prefers-reduced-motion` is handled, duration/easing tokens131 are used consistently (not magic numbers), no layout-property animations, ARIA live regions on132 dynamic content, and no janky animations on low-end hardware → `references/layer-5-motion.md`133- [ ] Run the static review with its grep sweep + Web-Interface Compliance pass against the vendored134 `references/web-interface-guidelines.md` (no review-time network fetch) — severity model135 (Critical / Important / Opportunities → 🔴 / 🟡 / 🟢) from `references/review-protocol.md`;136 **emission path depends on context:** under `craft-audit` / writing `.craftsman/**/findings.md`,137 emit each finding in the canonical workspace heading format above (not the punch-list tables);138 standalone UX review may use the review-protocol banner + tables → `references/review-protocol.md`139- [ ] Run the live pass after the static one — clear the preflight gate (non-prod, throwaway identity,140 side effects neutralized), then walk flows × 375/768/1280 × empty/loading/error, tagging each141 finding with its rendered condition; same dual-emission rule as the static pass →142 `references/live-audit.md`143
Run npx skillmds@latest add gul-labs/craft-ux in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
The Craftsman standard for UI/UX — design tokens, component patterns, pixel-perfect standards, Tailwind/React implementation, motion craft, an AI-tells anti-pattern catalog, and a two-pass review protocol (static review + live browser audit). Use this whenever designing, building, reviewing, auditing, redesigning, or polishing UI — a component, page, dashboard, landing page, modal, form, or layout; standing up or hardening a design system; checking spacing, typography, color, motion, or accessibility; or hunting AI-generated "tells". Trigger even on "make this look better", "fix the styling", "audit my design tokens", or "test it in the browser" without naming a tool or framework. App architecture (state, data fetching, bundles, routing) → craft-frontend. Does NOT fire on backend, database, CI/CD, or infra requests, or UI-free code-quality asks. It is listed under Design & Media on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
gul-labs (@gul-labs) published this skill. Their other Agent Skills are listed on their SkillMD profile.
gul-labs