From claude-dev-kit
Establishes a design philosophy from kickoff outputs and generates a design system, wireframes, and HTML prototypes. Run /kickoff first.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-dev-kit:uiuxThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->
Run silently at the start:
python3 scripts/kit_update_check.py 2>/dev/null
If exit code is 1 (update available), show the output to the user once. Do not block the workflow.
Run these checks silently at the start. Use results to adapt behavior:
[ -f issues.md ] — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.[ -f docs/sprint_state.md ] — if true and Status shows running, a sprint is active. Be aware of parallel work in worktrees.[ -f docs/prd_digest.md ] — if true, read it for quick project context before starting.gh auth status before any GitHub operation.At the start of this skill, check if contributor mode is enabled:
python3 scripts/kit_config.py get contributor_mode
If the result is true:
python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
/kickoff must be run first so that the following files exist:
docs/ux_spec.md (core input — IA, flows, screen inventory)docs/requirements.md (functional/non-functional requirements)docs/architecture.md (tech stack reference)/kickoff.Read kickoff outputs (required):
docs/ux_spec.md — extract screen inventory, IA, flowsdocs/requirements.md — identify UI elements from functional requirementsdocs/architecture.md — confirm tech stack, API endpointsRead PRD ($ARGUMENTS or PRD.md) as supplementary context. If docs/prd_digest.md exists, read it for quick PRD summary.
If docs/ux_spec.md does not exist:
/kickoff PRD.md first."docs/ux_spec.md, docs/requirements.md, docs/architecture.md, PRD) are reused across all subsequent Phases. Do not re-read the same file with the Read tool.Scan the project for existing UI code:
**/*.html, **/*.css, **/*.tsx, **/*.jsx, **/*.vue, **/*.svelte4.5) Ask the user the following questions to anchor the design direction. These answers become binding constraints for Phase 2. Present all questions at once (not one-by-one) and wait for answers. Also tell the user: "If any of these are hard to answer right now, just say 'skip'. You can also skip the entire interview."
a) Brand Personality: "If this product were a person, who would they be?" (e.g., a luxury hotel concierge, a neighborhood cafe barista, a strict operating room nurse, a playful friend)
b) Emotional Target: "What one emotion do you want users to feel when they see the first screen?" (e.g., trust, curiosity, relief, excitement, calm)
c) Anti-Reference: "What competing product or design should this absolutely NOT look like?" (a feeling you want to avoid, or a specific product name)
d) Aspiration Reference: "Is there a product or brand you'd like to reference for design? (doesn't have to be the same domain)" (e.g., Stripe's cleanliness, Nintendo's playfulness, Aesop's luxury)
Handle user response:
Case A — User answers (partially or fully): Record answers in memory — these become HARD CONSTRAINTS for Phase 2. If the user skips individual questions, note them as "unconstrained" but still avoid generic defaults.
Case B — User skips the entire interview (says "skip", "pass", etc.):
CHECKPOINT — MANDATORY — NEVER SKIP Verify Phase 1 outputs:
docs/ux_spec.mdexists, PRD was read, interview answers (or auto-derived constraints) are recorded. If any required input is missing: STOP and report to user.
Analyze the product's identity from PRD and UX spec:
WebFetch returns parsed text, not pixels. Asking the model to extract hex values or font pairings from a Dribbble/Mobbin URL via WebFetch is fabrication. Visual references MUST arrive as actual images.
Pick exactly ONE of three paths:
Path (a) — user-provided images (preferred):
.png/.jpg/.webp OR local file paths).Path (b) — page URLs:
python3 scripts/capture_reference.py <url>
This headless-captures the page to docs/references/<slug>.png. If the script exits non-zero (no browser backend installed), STOP this path and either install Playwright/Chromium OR switch to Path (a) OR Path (c).Path (c) — no images available:
Reference Anchor skipped: no image provided. Pass 1–3 image paths or a page URL (with Playwright/Chrome installed) to populate this section.Anti-reference (separate from path choice): WebSearch is still acceptable for titles of anti-references (e.g., "what makes corporate B2B SaaS dashboards generic"). Anti-cues are written from the model's own knowledge of the pattern being avoided — they are not visual extractions and do not require image grounding.
Synthesis (when Path (a) or (b) ran successfully — output goes into docs/design_philosophy.md "Reference Anchors"):
#1A1A1A on #F5EFE6, Fraunces 96/0.92 + Inter Tight 14) — source image path under docs/references/ OR the user-provided image URL. Strong = present in the chosen images, specific enough that no Phase 5 implementer can fall back to a default. Fewer-and-deeper beats more-and-shallow: 5 cues averaged out as "generic premium SaaS"; 2–3 force a direction.literal_quote: "<exact string>" — <where it appears>. Examples:
literal_quote: "조용한" — set in 168pt Fraunces, hero headlineliteral_quote: "47.2-A" — sample order ID, shown in mono on the order detail screenliteral_quote: "회" — quantity unit in the picker"luxury", "trust", "premium") — the literal quote is text/digits/glyphs the prototype renders, not adjectives.≈ (approximate) and leave a comment about which image it came from.Verbatim render check — Phase 5B is required to render the literal_quote string verbatim in at least one HTML file under prototype/screens/. The Phase 2 CHECKPOINT below verifies the field is populated; Phase 5B verifies it actually appears in output.
Commit to a BOLD aesthetic direction. Choose one and execute with precision:
Generate docs/design_philosophy.md:
var(--token)) — never prose-only.box-shadow: -8px 16px 0 var(--accent) — offset only, never blurred, never centered"border-radius: 14px 4px 14px 4px (asymmetric)"1px solid var(--accent) with margin-right: 12px indent — never full-width rules"letter-spacing: -0.04em, transform: skew(-2deg)"translateY(-2px) + border-left: 4px solid var(--ink) — no opacity changes"docs/references/ or a user-provided image URL/path), 1 literal_quote: field (mandatory unless Phase 1.5 was skipped), 3–5 avoided cues with reasons. If step 6.5 took Path (c) and skipped this section, omit it here too and proceed.Present the design philosophy to the user and ask for approval before proceeding.
CHECKPOINT — MANDATORY — NEVER SKIP Verify
docs/design_philosophy.mdexists with: (a) a Signature Move that is numeric/token-specific (not prose-only); (b) either a populated Reference Anchors section OR an explicit "Reference Anchors skipped (no image input)" line; AND (c) when Reference Anchors is present, exactly 2–3 adopted cues (not 1, not 4+), each citing an image path, plus aliteral_quote:field with a concrete word/number/glyph (NOT an adjective like "luxury"). The literal_quote may only be omitted if Phase 1.5 interview was explicitly skipped — in which caseliteral_quote: (skipped — interview not run)must appear instead of the field being absent. If any of (a) / (b) / (c) fails: STOP and fix before proceeding.
docs/design_system.md reflecting the chosen aesthetic:
transform and opacity are GPU-composited. Do NOT list box-shadow.docs/wireframes.md:
grid-template-columns or column ratios — e.g., 7fr 3fr, 1fr 2fr 1fr, repeat(12, 1fr)gap: 64px, column-gap: 32px; row-gap: 96pxmax-width: 1280px; padding: 0 80pxhero text overhangs column 1 by -120px, image overhangs viewport right edge by 48px, sidebar overlaps content by 24pxdocs/interactions.md:
12.5) Run the copywriter agent to generate docs/copy_guide.md:
- Input: docs/ux_spec.md, docs/design_philosophy.md, docs/wireframes.md, docs/interactions.md, PRD
- Output: Voice & tone definition, copy inventory per screen (labels, placeholders, empty/error/success states, confirmations, toasts), patterns, glossary
- Retrieve the contents of docs/ux_spec.md and PRD already read in Phase 1, and the documents generated in Phase 2-4, from memory and include them in the subagent prompt — do not re-read the files.
- The copy guide must align with the design philosophy's tone (e.g., "Ink & Paper" → restrained, precise language).
- Banned copy tells (enforce on every string): zero em-dashes (—/–) — use -, comma, period, or colon; no filler verbs (Elevate, Seamless, Unleash, Next-Gen, Revolutionize); no generic person names (John Doe) or startup-slop brand names (Acme, Nexus, SmartFlow); no fake-perfect numbers (99.99%, round 50%) — use organic values. See "Specific AI Tells" in Anti-AI-Slop Rules.
- This step MUST complete before Phase 5 so the prototype uses real copy, not placeholder text.
CHECKPOINT — MANDATORY — NEVER SKIP Verify
docs/design_system.md,docs/wireframes.md,docs/interactions.md, anddocs/copy_guide.mdall exist. Cross-check: every component in wireframes has a definition in design_system.md. If any output is missing: STOP and generate it before proceeding.
prototype/ and prototype/screens/ directories exist.prototype/styles.css:
CSS custom properties from design system (colors, spacing, typography, radii, shadows, motion tokens)
CSS reset / normalize
Utility classes (flex, grid, spacing, text alignment)
Component styles matching design system — every component with all states
Responsive breakpoint media queries (mobile-first)
Background & depth effects: gradient meshes, noise textures, layered transparencies, grain overlays (as appropriate for the aesthetic)
Dark mode via prefers-color-scheme (if appropriate for the aesthetic)
CSS keyframe animations for page-load reveals, stagger effects, hover transitions
Layout positioning rule: .sidebar, .nav, and similar layout-structural elements MUST use position: static (or relative/sticky if scroll-pinning is intended) — NEVER position: fixed or position: absolute. Fixed/absolute positioning pulls the element out of the document flow, collapsing the grid column it occupied. Sidebars participate in grid/flex layout as normal flow children; scroll-pinning should use position: sticky with a top value.
Viewport-height rule: full-height hero/section uses min-height: 100dvh — NEVER 100vh / height: 100vh. 100vh ignores the iOS Safari address bar and causes layout jump on mobile.
Multi-column rule: build column layouts with CSS Grid (grid-template-columns), NEVER flex percentage math (width: calc(33% - 1rem)), which breaks on gap rounding.
Layout-safety mechanics (deterministic — all mandatory):
overflow-x: clip on BOTH html and body (use clip, not hidden — clip preserves descendant sticky/fixed). The page must not scroll horizontally at any width 320–1920px.grid-template-columns/-rows track that holds an image uses minmax(0, 1fr), never bare 1fr (bare 1fr = minmax(auto, 1fr) → a large native image sets a huge min-width and overflows on phones).h1, .hero__title, section titles) set overflow-wrap: anywhere; min-width: 0 so long compound words can break.line-height ≥ 1.0 (never < 1.0 — cap-tops collide with the line below when the heading wraps).position: sticky; top: 0 element (the top nav). Any other sticky element offsets to top: var(--banner-height) and uses a lower z-index than the nav (split --z-sticky from --z-sticky-nav).align-items: center.Motion mechanics (deterministic — all mandatory):
transition: all / transition-all — name the exact properties.transform / opacity / filter; never animate width, height, top, left, margin, padding.scale hover applied across unrelated elements; no stacking multiple hover effects (translate+scale+shadow+rotate) on one element.cubic-bezier(…, 1.56, …)) for physical/drag interactions only — never on buttons, modals, or tooltips.transition on outline) and are built from outline, never border.Input-state mechanics (8 states; fail on any): border-width stays 1px across default/hover/focus/error (state changes go to outline/box-shadow/border-color, never border-width — it shifts layout); focus ring is outline: 2px solid var(--color-focus); outline-offset: 1px (reserve outline: 2px solid transparent at rest); input height == adjacent button height (44px floor); reserve the helper/error slot with min-height: 1lh so an appearing error doesn't push the page; disabled needs opacity + cursor: not-allowed + the disabled/aria-disabled attribute (never opacity alone).
Signature Move encoding (MANDATORY): the Signature Move from docs/design_philosophy.md MUST be encoded as a reusable utility class or component variant (e.g., .cta-primary { box-shadow: -8px 16px 0 var(--accent); }). If no natural component owns it, create a dedicated class named .signature-<move>. This class must be referenced from at least one selector that will appear on every screen.
14.5) Pilot screens selection & render (multi-archetype):
Classify every screen in docs/wireframes.md into one of these archetypes: list/feed, detail/show, form/input, hub/dashboard, modal-wizard, content/long-form, empty/cold-start.
Pick TWO pilot screens from the two most-distinct archetypes present in the inventory. Typically one consumption-oriented (list / detail / hub) plus one input-oriented (form / wizard). If only one archetype exists in the inventory, fall back to a single pilot and note this in the gate.
Generate ONLY these pilot HTML files in prototype/screens/ following all the rules listed in step 15 below. Both pilots share styles.css from step 14.
Do NOT generate other screens or prototype/index.html yet.
14.6) PILOT GATE — render → observe → critique → specificity → auto-correct → user HOLD
Generator-as-judge fails: the same context that produced the pilot will not reliably catch its own slop. This phase routes the critique through a separate sub-agent context and runs up to 3 auto-correction cycles before presenting to the user. Do not auto-proceed past Step 3.
Step 1 — Render: for each pilot HTML, run:
python3 scripts/screenshot_pilot.py prototype/screens/<pilot>.html --viewport 1280x800 --full-page
Produces prototype/screens/<pilot>.png. If the script exits "no screenshot backend available":
pilot_degraded: no_screenshot_backend in the critique log so the user sees the limitation.Step 2.0 — Neutral observation (mandatory; do this BEFORE any judgment).
For each pilot, write 5 plain factual statements about what you see in the PNG (or HTML in degraded mode).
Banned vocabulary in this step: signature move, aesthetic, archetype, philosophy, direction, taste, slop, generic, bold, restrained, premium, brand names, the chosen aesthetic name. Use only colors, sizes, shapes, positions, counts, content categories.
Output to prototype/screens/<pilot>.observations.md like:
1. Top bar 64px tall, dark navy background, four icon buttons right-aligned.
2. Hero headline reads "조용한", left-aligned, 168pt serif, off-white text.
3. Below the hero, three cards in a row at 24% / 38% / 38% widths.
4. Bottom-right floating action button, 56px, orange fill, no border.
5. Sticky bottom toolbar with four state-switcher buttons.
If you catch yourself reaching for a banned word, restart Step 2.0 — the observation is the input that prevents the critique from agreeing with itself.
Step 2.1 — Separate-context critique (mandatory). Invoke design-auditor via the Task tool to evaluate the pilot from a fresh context. Do NOT inline-critique in the generator's context.
Pass the auditor:
prototype/screens/<pilot>.observations.mddocs/design_philosophy.md (so it knows the system claim it should check)docs/design_system.md
Ask it to return:ui-reviewer via the Task tool with the same inputs. The two sub-agents' scopes are disjoint (per ISSUE-013) — do not deduplicate findings, surface both.
Save the structured output to prototype/screens/<pilot>.critique.md.Step 2.2 — Specificity check (mandatory). Ask the design-auditor (still in its separate context) to answer: "Name 3 details visible in this pilot that ONLY make sense for THIS specific product / domain / user. Generic UI primitives ('a card', 'a hero', 'a button') do not count. Domain content does count (real entity names, the literal_quote from Reference Anchors, domain-specific units, brand-specific shortcuts). If you can list fewer than 3, the pilot FAILs specificity." The literal_quote (from ISSUE-012) counts as exactly 1 of the 3 — not 0, not 2+. The other 2 must come from independent product/domain details. Specificity FAIL → treat as a critique failure feeding Step 2.3.
Step 2.3 — Auto-correction cycle (hard cap N=3 rounds). If any axis score < 3, OR Step 2.2 returns FAIL, OR slop signals are flagged:
docs/design_philosophy.md).docs/design_system.md) or Phase 4 layout numbers.prototype/screens/<pilot>.cycles.log:
cycle N: layer=<L> change="<short summary>" scores=P5 H4 E5 S3 R5 V4 specificity=PASS|FAIL.styles.css: /* pre-emit critique cycle=N: P5 H4 E5 S4 R5 V5 specificity=PASS */.Step 3 — User gate: present both pilots to the user.
open prototype/screens/<pilot1>.html and open prototype/screens/<pilot2>.html.prototype/screens/<pilot>.critique.md (Step 2.1 output) and prototype/screens/<pilot>.cycles.log (Step 2.3 history) so the user sees what was caught and what changed.<paste exact text>) visible and applied in both?
(b) Do they feel like <aesthetic name> and read as the same family across the two archetypes?
(c) Do the 3 product-specific details from the specificity check belong to this product?"If rejected: identify which layer the problem lives at and fix there before regenerating the pilots:
styles.css and pilot HTML only.Do NOT proceed to Phase 5B with an unaddressed pilot rejection.
prototype/screens/:
<nav>, <main>, <section>, <article>, <aside>, <header>, <footer>)<link> tag (single CDN exception — fonts only)<meta name="viewport"> for responsiveness../styles.cssdocs/copy_guide.md — labels, placeholders, empty states, error messages. NOT placeholder text.outline: none on :focus without :focus-visible fallbackrole="button" elements MUST have keydown handlers for Enter/Spacerole="radiogroup" elements MUST support arrow-key navigationalt text, form <label>s, ARIA attributes, color contrast >= 4.5:1, keyboard navigableprototype/index.html:
wireframes.md MUST have a definition in design_system.mddocs/design_philosophy.md must contain a Signature Move with numeric/token specificity (not prose-only).prototype/styles.css must implement it as a reusable class or component variant.prototype/screens/ (including the pilot) must apply that class/variant at least once.literal_quote: from docs/design_philosophy.md Reference Anchors.prototype/screens/*.html for the literal string. The string MUST appear verbatim in at least one screen's rendered output.literal_quote: "47.2-A" MUST appear as the literal characters 47.2-A in at least one screen file — not 47-2-A, not 47.2A, not in a comment.styles.css MUST match values in design_system.mdstyles.css that should use var(--token)outline: none on :focus without :focus-visible coverage(color, background-color) pair on a screen, verify the WCAG ratio against its computed background: body text (<24px regular / <18px bold) needs ≥ 4.5:1; large text (≥24px / ≥18px bold), icons, and focus rings need ≥ 3:1.--color-accent filling a text-bearing surface without a defined, verified --color-accent-ink; any dark section (background lightness < 50%) that did not also flip its text colour (ink-on-ink). Most-missed: text in a card that switched background but inherited color; muted text on a tinted surface.file:selector, fix, and re-check before proceeding.issues.md exists):issues.md and extract titles, scope, and UI flag from each issue.### Screen: entries in wireframes.md not implied by any existing issuedesign_system.md (FAB, list items, pickers, etc.) that no existing issue produces### Flow: entries in interactions.md not covered by an existing issueinteractions.md or copy_guide.md beyond what was anticipated in ux_spec.mdissues.md — issue creation is /issue's responsibility.issues.md does not exist, skip silently.
22.7) AI Tell sweep (CRITICAL):prototype/screens/ and prototype/styles.css for the banned tells in "Specific AI Tells" (Anti-AI-Slop Rules): em-dash (—/–), 100vh/height: 100vh on full-height sections, flex calc() column math, generic person/brand names, fake-perfect numbers, section-number eyebrows, hero version labels, three equal feature cards, <div>-based fake product UI, decorative status dots, locale/time strips, scroll cues, mono-caps decoration strips.file:line, fix it, and re-sweep. Zero tolerance on em-dash and div-based fake product UI — these must be 0 before presenting. Match CSS patterns whitespace-insensitively (height:100vh ≡ height: 100vh).
22.8) Slop-proof mechanics sweep (deterministic — grep prototype/styles.css and screens):transition: all / transition-all; animating width/height/top/left/margin/padding; bare 1fr tracks on image-bearing grids (must be minmax(0, 1fr)); font-style: italic on heading/display selectors; a second position: sticky; top: 0 (only the nav may sit there); all-caps display with line-height < 1.0.overflow-x: clip on BOTH html and body; input fields satisfy the 8-state rules (constant border-width, outline-based focus ring, reserved helper slot, multi-channel disabled) from Phase 5A step 14.transition:all ≡ transition: all, top:0 ≡ top: 0, overflow-x:clip ≡ overflow-x: clip.file:line, fix, and re-sweep./issue "uiux 산출물 기반으로 issues.md에 누락된 화면/컴포넌트/상태/플로우 작업을 batch로 추가해줘"
If no gaps were found, state explicitly: "No issues.md gaps detected — design deliverables are fully covered by existing issues."open prototype/index.html to view in browserissues.md or STATUS.md./kickoff generated issues.md. Phase 5.5 step 22.5 detects these gaps and Phase 6 reports them./issue with a gap-finder prompt — /issue's batch mode automatically reads design_system.md, wireframes.md, interactions.md, and copy_guide.md (has_design_docs flag) and appends new issues without disturbing existing ones./kickoff for this purpose — it overwrites all planning docs and resets issue numbering, Status, GH-Issue, and PR fields.docs/ux_spec.md not found: stop and suggest running /kickoff first (unless user explicitly opts to skip).docs/ cannot be created: stop and report filesystem error.docs/design_system.md for future /implement reference. Prototypes are still pure HTML/CSS for portability./uiux overwrites all outputs — safe to retry.prototype/) can be safely deleted if not needed.These rules prevent Claude from converging on generic, forgettable defaults.
Primary anchor — the Signature Move. The single most effective slop-blocker is the numeric/token-specific Signature Move defined in Phase 2 step 8 and enforced at Phase 5A pilot gate and Phase 5.5 step 17.5. Negative rules below are secondary; if the Signature Move is weak or missing, the rules below will not save the output.
NEVER:
INSTEAD:
Specific AI Tells (hard bans — sweep every screen before presenting). Concrete signatures LLMs default to. Banned unless the brief explicitly calls for one.
Content & data:
99.99%, round 50%, 1,234,567) → organic messy values (47.2%, +1 (312) 847-1928).—) and en-dash-as-separator (–): zero tolerance everywhere visible (headlines, labels, body, captions, attribution). Use a regular hyphen -, comma, period, colon, or line break. The single most-violated tell.Fake product UI:
<div> rectangles (fake dashboard, terminal, task list, chart) to fill a hero or preview. This is the #1 design tell. Use a real screenshot, generated image, real component preview, or skip the preview.v0.6.2-rc.1, last sync 4s ago).Decorative meta (agency-portfolio clichés):
001 · Capabilities, 06 · how it works) or 01 / 4 pagination labels. Name the topic in plain language.V0.6, BETA, EARLY ACCESS, ALPHA) unless the brief is explicitly a launch/preview.Lisbon 14:23 · 18°C), no scroll cues (↓ Scroll to explore), no mono-caps decoration strips (BRAND. MOTION. SPATIAL.).· to max 1 per metadata line; never as a universal separator.Frame XII · 35mm, Plate 03) — real photographer credit only.CSS mechanics (web):
min-height: 100dvh, NEVER 100vh / height: 100vh (iOS Safari address-bar jump).grid-template-columns), NEVER flex percentage math (width: calc(33% - 1rem)).Typography & interaction tells:
font-style: italic on h1–h6 / display / wordmark / hero stat / <em> inside a heading is a top tell. Emphasis = weight, accent colour, or a drawn underline. Italic only inside running body copy.file:// — no build tools, no npm, no frameworks.<link> tags are allowed for typography.npx claudepluginhub pillip/claude-dev-kit --plugin claude-dev-kitCreates a design system with foundations, brand identity, and UX patterns. Invoke via /groundwork:ux-design.
Designs UI/UX systems with style guides, color palettes, typography, and component specs for new interfaces. Asks about product type, tech stack, and deliverables before producing design tokens, layouts, or style guides.
Generates a mobile design system, wireframes, and React Native (Expo) prototype from kickoff outputs (UX spec, requirements, architecture). Run after /prd → /kickoff.