julianoczkowski/designer-skills

This skill turns a design brief into an ordered, buildable task list. Each task is a vertical slice: a piece of UI that can be built, reviewed, and verified on its own.

Example prompts

• "Break the brief into tasks"
• "What should I build first?"
• "Create a task list from the design brief"
• "Plan the build order for this feature"

Process

1. Read the design brief. Look for .design/*/DESIGN_BRIEF.md. If multiple subfolders exist, use the most recently modified one, or ask the user which feature they are working on. Also check for INFORMATION_ARCHITECTURE.md and a tokens file in the same subfolder. If none exist, ask the user to describe what they are building.

2. Explore the existing codebase to understand what is already built. Scan specifically for:

   • Component directories: components/, ui/, shared/ and list every component by name
   • Existing pages/views: what is already built that this feature must coexist with
   • Token/theme files: tokens.css, globals.css, Tailwind config, theme providers
   • File naming conventions: kebab-case, PascalCase, how files are organized (by feature, by type)
   • Test files: if tests exist alongside components, new tasks should include test expectations
   • Package.json dependencies: what UI libraries, animation libraries, and icon sets are already installed
   • Classify each relevant component as: will be reused as-is, needs modification, or does not exist yet. Only components that need modification or creation get their own tasks.

3. Break the work into vertical slices. Each task should:

   • Be independently buildable (no task should block another unless noted).
   • Include structure, styling, and interaction in a single task (not "build HTML" then "add CSS" then "add JS" as separate tasks).
   • Be verifiable: you can look at the result and confirm it matches the brief.
   • Be small enough to complete in a single session.

4. Order tasks by:

   • Dependencies first: foundational elements (tokens, layout shells, shared components) before page-specific work.
   • Visual priority: the most prominent UI element early, so the user can validate the aesthetic direction before investing in details.
   • Risk first: the hardest or most uncertain piece early, so problems surface before everything else is built around them.

5. Save the task list as TASKS.md in the same .design/<feature-slug>/ subfolder as the design brief.

Task List Template

# Build Tasks: [Feature/Page Name]

Generated from: .design/<feature-slug>/DESIGN_BRIEF.md
Date: [date]

## Foundation
- [ ] **[Task name]**: [One sentence describing what to build and what "done" looks like]. _Reuses: [existing components/tokens if any]._
- [ ] **[Task name]**: [Description]. _New component._

## Core UI
- [ ] **[Task name]**: [Description]. _Depends on: [task name if any]._
- [ ] **[Task name]**: [Description].

## Interactions & States
- [ ] **[Task name]**: [Description]. Covers: [list of states, e.g., hover, loading, error, empty].
- [ ] **[Task name]**: [Description].

## Responsive & Polish
- [ ] **[Task name]**: [Description]. Breakpoints: [which ones].
- [ ] **[Task name]**: Accessibility pass. [Specific checks from the brief].

## Review
- [ ] **Design review**: Run /design-review against the brief.

Rules

• Every task must reference whether it reuses, modifies, or creates components.
• Never create a task that is only "set up the project" or "create the file structure." Those are not vertical slices.
• If the brief specifies an aesthetic philosophy, note it in the first build task so the visual direction is established immediately.
• Group related tasks but do not nest them more than one level deep. Flat lists are easier to work through.

This skill creates a design brief through structured conversation. You may skip steps if they are not necessary.

Example prompts

• "Write a brief for the onboarding flow"
• "I need to plan a settings page before I start building"
• "Help me define the direction for a marketing landing page"
• "Brief this: a dashboard that shows project health metrics"

Process

1. Ask the user for a detailed description of what they want to build, who it is for, and any constraints or ideas they already have.

2. Explore the existing codebase to understand the current state. Scan for each of the following specifically:

   • CSS variables / tokens: files named tokens.css, variables.css, theme.css, or :root declarations with custom properties
   • Tailwind config: tailwind.config.js or tailwind.config.ts, check theme.extend for custom values
   • UI framework themes: Material UI createTheme, Chakra extendTheme, shadcn globals.css and components.json
   • Component directories: components/, ui/, shared/, or any folder containing reusable UI pieces
   • Storybook: .storybook/ directory or *.stories.* files indicating a documented component library
   • Design token files: JSON token files (Style Dictionary format, Figma token exports)
   • Package.json UI dependencies: tailwindcss, @mui/material, @chakra-ui/react, @radix-ui, lucide-react, framer-motion, etc.
   • Font loading: Google Fonts links in HTML, @font-face declarations, font imports in CSS/config
   • Existing pages/layouts: route files, layout components, page templates that show established patterns
   • If components exist, treat them as the starting vocabulary. The brief should extend, not replace.

3. Interview the user relentlessly about every aspect of the design until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one by one. For each question, provide your recommended answer.

   Cover at minimum:

   • Who is the primary user their JTBD and what are they trying to accomplish?
   • What does success look like for this interface?
   • What is the emotional tone? (calm, urgent, playful, authoritative, warm, clinical)
   • What existing products, sites, or styles should this feel like? What should it NOT feel like?
   • What are the hard constraints? (devices, accessibility requirements, performance budgets, brand guidelines)
   • What content will this interface contain? What is placeholder vs. real?

4. Once you have a complete understanding, write the brief using the template below.

File Output

Save the brief to .design/<feature-slug>/DESIGN_BRIEF.md where <feature-slug> is a short, lowercase, hyphenated name derived from the feature or page being designed (e.g., onboarding-flow, settings-page, project-dashboard).

This folder structure ensures that running the design flow multiple times for different features does not overwrite previous work. All subsequent skills (information-architecture, design-tokens, brief-to-tasks, design-review) will read from and write to this same subfolder.

Example:

.design/
├── onboarding-flow/
│   └── DESIGN_BRIEF.md
└── settings-page/
    └── DESIGN_BRIEF.md

Brief Template

# Design Brief: [Feature/Page Name]

## Problem

What problem is the user facing, described from their perspective. Not technical. Not business metrics. The human friction.

## Solution

What this interface does to solve that problem, described as an experience, not a feature list.

## Experience Principles

Three principles maximum that guide every design decision. Each principle should resolve a tension.
Example: "Progressive disclosure over upfront complexity" or "Confidence over speed."

1. [Principle] -- [What this means in practice]
2. [Principle] -- [What this means in practice]
3. [Principle] -- [What this means in practice]

## Aesthetic Direction

- **Philosophy**: [Named philosophy or described vibe. See /frontend-design skill for reference.]
- **Tone**: [Emotional register]
- **Reference points**: [Existing products, sites, or styles this should feel like]
- **Anti-references**: [What this should NOT feel like]

## Existing Patterns

Components, tokens, and conventions already in the codebase that this design must respect or extend.

- Typography: [what is currently used]
- Colors: [current palette/variables]
- Spacing: [current scale]
- Components: [existing components that will be reused or extended]

## Component Inventory

A list of the UI components this feature requires. For each, note whether it exists already, needs modification, or is new.

| Component | Status                | Notes    |
| --------- | --------------------- | -------- |
| [name]    | Exists / Modify / New | [detail] |

## Key Interactions

The critical interaction patterns. Describe what the user does and what the interface does in response. Focus on state changes, transitions, and feedback.

## Responsive Behavior

How the layout adapts across breakpoints. Note any components that change behavior (not just size) on mobile.

## Accessibility Requirements

Minimum requirements for this interface. Include contrast ratios, keyboard navigation, screen reader considerations, and focus management.

## Out of Scope

Things this brief explicitly does not cover. Be specific. This prevents scope creep during build.

This skill orchestrates the full designer workflow by running each skill in sequence. You are a guide walking the designer through each phase. Do not rush. Each phase must be completed and confirmed before moving to the next.

Example prompts

• "Run the full design flow"
• "Walk me through the complete process for a new project"
• "Start from scratch and take me through everything"
• "Design flow for a dashboard app"

The Sequence

1. Grill Me          → Clarify thinking
2. Design Brief      → Document intent
3. Info Architecture  → Define structure
4. Design Tokens     → Establish visual system
5. Brief to Tasks    → Plan the build
6. Frontend Design   → Build it
—
7. Design Review     → Run separately when ready

Rules

1. At the start, tell the designer what the full sequence looks like (phases 1-6, with review available separately) and ask if they want to skip any phases. Common skip patterns:

   • Already have a clear idea → skip grill-me
   • Single component, not a full page → skip information-architecture
   • Existing project with tokens → skip design-tokens

2. Before each phase, announce which phase you are entering and what it will produce. Example: "Phase 2: Design Brief. I'll interview you about the project and produce a DESIGN_BRIEF.md file. Ready?"

3. During each phase, read the corresponding SKILL.md file and follow its full instructions. Do not summarize or abbreviate the skill. Run it properly.

4. After each phase, summarize what was produced (the file name, the key decisions, any open questions) and ask: "Ready to move to the next phase?" Wait for confirmation.

5. Between phases, check if the output from the previous phase changes anything about the next phase. For example, if the brief names a philosophy, mention that the tokens phase will use it.

6. The designer can stop at any point. If they say "that's enough for now," summarize where they are in the sequence and what the next phase would be when they return.

Phase Details

Phase 1: Grill Me

Read the grill-me skill (grill-me/SKILL.md) and follow its instructions. Produces: Shared understanding of the project. No file output. Transition: "We've resolved the key decisions. Ready to capture this as a design brief?"

Phase 2: Design Brief

Read the design-brief skill (design-brief/SKILL.md) and follow its instructions. Produces: .design/<feature-slug>/DESIGN_BRIEF.md. Transition: "The brief is saved. Next is information architecture, where we'll define the page structure and navigation. Skip this if you're building a single component. Continue?"

Phase 3: Information Architecture

Read the information-architecture skill (information-architecture/SKILL.md) and follow its instructions. Produces: .design/<feature-slug>/INFORMATION_ARCHITECTURE.md. Transition: "IA is defined. Next we'll generate design tokens (colors, spacing, typography) based on the philosophy from the brief. Continue?"

Phase 4: Design Tokens

Read the design-tokens skill (design-tokens/SKILL.md) and follow its instructions. Produces: Token file (CSS variables, Tailwind config, or theme file depending on stack). Transition: "Tokens are set. Next I'll break the brief into a task list so we can build in order. Continue?"

Phase 5: Brief to Tasks

Read the brief-to-tasks skill (brief-to-tasks/SKILL.md) and follow its instructions. Produces: .design/<feature-slug>/TASKS.md. Transition: "Tasks are ready. Now we build. I'll start with the first task on the list. Continue?"

Phase 6: Frontend Design

Read the frontend-design skill (frontend-design/SKILL.md) and follow its instructions. Work through the tasks from TASKS.md in order. After completing each task, check it off and confirm with the designer before moving to the next task. Produces: Built components and pages. Transition: "The flow is complete. Your brief, IA, tokens, and tasks are all saved in the project. When you're ready for a design review, run /design-review and I'll critique the build against the brief."

The flow ends here. Phase 7 is not automatic.

Phase 7: Design Review (on request only)

This phase does NOT run automatically. It only runs if:

• The designer explicitly asks for a review during the flow
• The designer runs /design-review separately after building

The review requires built code to examine. If no components or pages have been built yet, do not run this phase. Instead, remind the designer: "Run /design-review once you have something built. It will check the output against the brief."

When triggered, read the design-review skill (design-review/SKILL.md) and follow its instructions. The review will capture screenshots of the running application using Playwright MCP (preferred), the Cursor IDE Browser (fallback), or by asking the user to provide them manually if no browser tool is available.

Produces: .design/<feature-slug>/DESIGN_REVIEW.md + screenshots saved in .design/<feature-slug>/screenshots/. Transition: "Review is done. Screenshots are saved in .design/<feature-slug>/screenshots/. If there are must-fix items, I can address them now."

Project Files Structure

All design flow artifacts are saved under .design/<feature-slug>/ where <feature-slug> is a short, lowercase, hyphenated name derived from the feature being designed. This ensures multiple features can be designed independently without overwriting each other.

.design/
└── <feature-slug>/
    ├── DESIGN_BRIEF.md              ← Phase 2: Project intent, goals, aesthetic direction
    ├── INFORMATION_ARCHITECTURE.md  ← Phase 3: Navigation, page structure, user flows
    ├── DESIGN_TOKENS.*              ← Phase 4: Colors, spacing, typography, shadows (CSS/Tailwind/theme)
    ├── TASKS.md                     ← Phase 5: Ordered build checklist from the brief
    ├── DESIGN_REVIEW.md             ← Phase 7: Prioritized critique against the brief
    └── screenshots/                 ← Phase 7: Visual evidence from the running app
        ├── review-[page]-desktop-1280.png
        ├── review-[page]-tablet-768.png
        ├── review-[page]-mobile-375.png
        ├── review-[page]-dark-mode-*.png
        └── review-[component]-[state].png

The screenshots/ subfolder is created during the design review phase. All visual evidence of the review (responsive breakpoints, interactive states, dark mode) is saved here with descriptive filenames so findings in DESIGN_REVIEW.md are traceable.

If the Designer Returns Mid-Flow

Check the .design/ folder for existing feature subfolders. If files from earlier phases exist (DESIGN_BRIEF.md, INFORMATION_ARCHITECTURE.md, TASKS.md) inside a feature folder, read them to understand where the designer left off. Ask which feature to resume if multiple folders exist. Resume from the next incomplete phase.

This skill runs a structured design review of what has been built, measured against the design brief and the chosen aesthetic philosophy.

CRITICAL — Visual Screenshot Capture

You MUST capture screenshots of the running application as part of every design review. Code review alone is insufficient — you need to see what the user sees. Follow the screenshot capture protocol in Step 3 below. This is not optional.

Example prompts

• "Review what I just built"
• "Run a design critique on the landing page"
• "Check this against the brief"
• "Here's a screenshot. How does it look?" [paste screenshot]
• "QA pass before I ship this"

Process

1. Read the brief. Look for the active feature's brief at .design/<feature-slug>/DESIGN_BRIEF.md. If multiple feature folders exist under .design/, ask the user which feature to review. If no .design/ folder exists, fall back to DESIGN_BRIEF.md in the project root. If neither exists, ask the user what the intended design direction was.

2. Explore the built code. Examine every component, page, and style file that was created or modified. Scan specifically for:

   • All new or modified components and their relationship to pre-existing components
   • Token/variable usage: are components using shared tokens or hardcoding values?
   • Duplicate components that should be consolidated
   • File naming and organization: do new files follow the project's conventions?
   • Understand what was actually built, not what was planned.

3. Capture screenshots of the running application.

   This step is mandatory. Do not skip it. Do not rely only on user-provided screenshots.

   Screenshot Tool Priority

   Try each option in order. Use the first one that is available:

   1. Playwright MCP (preferred). Check if the plugin-playwright-playwright MCP server is available. If it is, use it — it gives you precise control over viewport sizing, full-page captures, and file naming.
   2. Cursor IDE Browser (second choice). If Playwright MCP is not available, use the cursor-ide-browser MCP server's browser_take_screenshot tool instead. It has the same core capabilities.
   3. Ask the user (last resort). If neither MCP server nor in-app browser is available, you MUST ask the user to provide screenshots manually. Be specific about what you need:
      • "I don't have access to a browser tool. To complete the visual review I need screenshots of the running application. Please provide:"
      • A full-page screenshot at desktop width (1280px)
      • A full-page screenshot at tablet width (768px)
      • A full-page screenshot at mobile width (375px)
      • Dark mode variants (if applicable)
      • Any specific component or interactive state you want reviewed
      • Ask the user to paste/attach the images directly in chat, or to save them into the screenshots/ folder themselves.
      • Do not skip the visual review. Wait for the user to provide screenshots before proceeding with the checklist.

   Screenshot Save Location

   All screenshots MUST be saved to a screenshots/ subfolder inside the feature's .design/ directory — the same folder where DESIGN_BRIEF.md and other design flow files live.

   Path pattern: .design/<feature-slug>/screenshots/

   If the brief lives at .design/onboarding-flow/DESIGN_BRIEF.md, screenshots go to .design/onboarding-flow/screenshots/. Create the folder if it does not exist.

   If no .design/ folder exists (legacy project or standalone review), fall back to a screenshots/ folder in the project root.

   Use descriptive filenames that encode what was captured:

   .design/
   └── onboarding-flow/
       ├── DESIGN_BRIEF.md
       ├── DESIGN_REVIEW.md
       └── screenshots/
           ├── review-homepage-desktop-1280.png
           ├── review-homepage-tablet-768.png
           ├── review-homepage-mobile-375.png
           ├── review-homepage-dark-mode-desktop-1280.png
           └── review-card-component-hover.png
   

   Screenshot Capture Protocol

   a. Navigate to the application. Ask the user for the URL if not obvious from the project (e.g., http://localhost:3000). Use browser_navigate to open it.

   b. Capture responsive breakpoints. At minimum, capture these three viewports for every key page/view:

   Breakpoint	Width × Height	Filename suffix
   Mobile	375 × 812	-mobile-375
   Tablet	768 × 1024	-tablet-768
   Desktop	1280 × 800	-desktop-1280

   Use browser_resize to set the viewport before each screenshot. Use browser_take_screenshot with fullPage: true to capture the entire scrollable page, and save with the filename parameter pointing to the screenshots/ folder.

   Playwright MCP example sequence (assuming feature slug is onboarding-flow):

   1. browser_navigate → { url: "http://localhost:3000" }
   2. browser_resize   → { width: 1280, height: 800 }
   3. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-desktop-1280.png", fullPage: true }
   4. browser_resize   → { width: 768, height: 1024 }
   5. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-tablet-768.png", fullPage: true }
   6. browser_resize   → { width: 375, height: 812 }
   7. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-mobile-375.png", fullPage: true }
   

   c. Capture interactive states (when relevant).

   • Hover states on buttons, cards, links
   • Focus states on form fields
   • Open states on dropdowns, modals, menus
   • Error/success states on forms
   • Loading and empty states

   d. Capture dark mode (if the project supports it). Toggle dark mode and repeat the responsive breakpoint captures with -dark-mode in the filename.

   e. Capture specific components. If the review focuses on a particular component, use the element and ref parameters to screenshot just that element.

   Analyze Every Screenshot

   After capturing, visually analyze each screenshot against the design brief. For each screenshot:

   • Compare against the brief's aesthetic direction
   • Check visual hierarchy: is the most important element the most prominent?
   • Check spacing consistency: do margins and padding look even and intentional?
   • Check color: does the palette match the brief's direction?
   • Check typography: are font sizes, weights, and spacing visually correct?
   • Check responsive adaptation: does the layout properly reorganize (not just shrink)?
   • Note rendering issues that code review alone would miss (font loading failures, broken images, layout overflow, z-index problems, incorrect border-radius, color mismatches)

   Reference specific screenshots by filename in the review output so findings are traceable.

4. Run the review checklist below. For each category, note what passes and what needs refinement. Be specific. Reference exact components, files, line numbers, and screenshot filenames.

5. Produce a prioritized refinement list. Group issues by severity:

   • Must fix: Broken functionality, accessibility failures, major deviations from the brief.
   • Should fix: Inconsistencies, missing states, responsive issues.
   • Could improve: Polish, animation refinement, typography fine-tuning.

6. Save the review as DESIGN_REVIEW.md inside the feature's .design/<feature-slug>/ folder (next to DESIGN_BRIEF.md). If no .design/ folder exists, save to the project root. Include a "Screenshots Captured" section listing all screenshots taken with their paths. Present the review directly as well if the user prefers.

Review Checklist

Visual Hierarchy

• Is the most important content the most visually prominent on each page/view?
• Does the type scale create clear levels of importance (heading, subheading, body, caption)?
• Do interactive elements (buttons, links, inputs) have enough visual weight to be found without hunting?
• Is there a clear reading order? Can you trace where the eye goes first, second, third?

Consistency

• Are spacing values consistent? Check padding and margins against the established scale (4px/8px base or whatever the project uses).
• Are colors used consistently? Check that the same semantic meaning always maps to the same color (primary actions, errors, success states, disabled states).
• Are border radii, shadow values, and font sizes reused from a shared set, or are there one-off values?
• Do similar components look and behave similarly? (e.g., all cards, all form fields, all buttons within a category.)

Aesthetic Fidelity

• Does the implementation match the named philosophy from the brief?
• Would someone looking at this immediately recognize the intended aesthetic direction?
• Are there elements that break the aesthetic (a generic component in an otherwise distinctive interface, a conflicting font, an out-of-place color)?
• Does the level of detail match the philosophy? (Minimalist designs should not have unnecessary decoration. Maximalist designs should not have empty, unfinished areas.)

Component Quality

• Do existing components from the codebase appear correctly, or were they reimplemented?
• Are new components following the same API patterns (props, naming, file organization) as existing ones?
• Are there duplicate components that should be consolidated?

States and Interactions

• Do interactive elements have all necessary states: default, hover, focus, active, disabled?
• Do form fields have states for: empty, filled, error, success, disabled?
• Are loading states handled? Empty states?
• Do transitions and animations match the philosophy's motion guidelines?
• Is there visual feedback for every user action?

Responsive Behavior

• Does the layout work at mobile (375px), tablet (768px), and desktop (1280px+)?
• Do components adapt appropriately? (Not just shrink, but reorganize when needed.)
• Is touch target size adequate on mobile (minimum 44x44px)?
• Does text remain readable at all breakpoints? No text too small, no lines too wide (max 65-75 characters).

Accessibility

• Color contrast: Do text/background combinations meet WCAG AA (4.5:1 for body text, 3:1 for large text)?
• Keyboard navigation: Can every interactive element be reached and activated with keyboard alone?
• Focus indicators: Are focus rings visible and styled consistently?
• Semantic HTML: Are headings in order? Are landmarks used (main, nav, header, footer)? Are form labels associated?
• Screen reader: Do images have alt text? Do icons have labels? Are decorative elements hidden from assistive technology?
• Motion: Is there a reduced-motion media query for users who need it?

Typography

• Is the font actually loading? (Check for FOIT/FOUT flash.)
• Are line lengths comfortable for reading (45-75 characters on body text)?
• Is line height appropriate (1.4-1.6 for body, tighter for headings)?
• Is the type scale intentional, or are there arbitrary sizes?

Dark Mode

• If the project has dark mode tokens, are they applied correctly?
• Are all color values using CSS variables (not hardcoded hex values that won't switch)?
• Does the dark palette feel intentional for the chosen philosophy, or is it a simple inversion?
• Are shadows adjusted for dark mode (darker, more transparent)?
• Do accent colors maintain sufficient contrast against dark backgrounds?
• Is there a working toggle mechanism or prefers-color-scheme support?

Mobile-First

• Was the layout built mobile-first (using min-width media queries, not max-width)?
• Does the mobile layout work at 375px without horizontal scrolling?
• Is navigation adapted for mobile (not just a desktop nav that overflows)?
• Are touch targets at least 44x44px?
• Is body text at least 16px on mobile?

Output Format

# Design Review: [Feature/Page Name]

Reviewed against: DESIGN_BRIEF.md
Philosophy: [named philosophy]
Date: [date]

## Screenshots Captured

| Screenshot                                   | Breakpoint         | Description     |
| -------------------------------------------- | ------------------ | --------------- |
| `screenshots/review-[page]-desktop-1280.png` | Desktop (1280×800) | [what it shows] |
| `screenshots/review-[page]-tablet-768.png`   | Tablet (768×1024)  | [what it shows] |
| `screenshots/review-[page]-mobile-375.png`   | Mobile (375×812)   | [what it shows] |

> All screenshots are in `.design/<feature-slug>/screenshots/`.

## Summary

[2-3 sentences on overall quality and the biggest finding.]

## Must Fix

1. **[Issue]**: [Specific description with file/component reference]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [concrete suggestion]._

## Should Fix

1. **[Issue]**: [Description]. See [`screenshots/[relevant-screenshot].png`]. _Fix: [suggestion]._

## Could Improve

1. **[Issue]**: [Description]. _Suggestion: [idea]._

## What Works Well

[Note the strongest aspects of the implementation. This is not padding. Designers need to know what to keep doing.]

This skill generates the foundational design tokens for a project. Run this after the design brief and before building any components. Every component built after this references these tokens instead of hardcoding values.

Example prompts

• "Set up design tokens for this project"
• "Generate a token system based on Dieter Rams"
• "I need a spacing scale and color palette before I start building"
• "Create tokens that match our brief"

Process

1. Check what already exists. Before generating anything, scan the codebase for:

   • CSS variable definitions (:root, [data-theme], custom property files)
   • Tailwind config (tailwind.config.js, tailwind.config.ts) and any theme extensions
   • Theme provider files (Material UI createTheme, Chakra extendTheme, shadcn globals.css)
   • Design token JSON files (Style Dictionary format, Figma token exports)
   • Any tokens.css, variables.css, theme.css, or similarly named files
   • package.json for UI framework dependencies (tailwindcss, @mui/material, @chakra-ui/react, etc.)

   If tokens already exist, extend them rather than replacing. Identify gaps (missing dark mode, incomplete spacing scale, no motion tokens) and fill those.

2. Read the brief. Look for a design brief at .design/*/DESIGN_BRIEF.md. If multiple subfolders exist, use the most recently modified one, or ask the user which feature they are working on. If a philosophy is named, use the parameters from /frontend-design to derive token values. If no brief exists, ask the user what direction they want.

3. Generate tokens in the format that matches the project's tech stack:

   • Tailwind project → extend tailwind.config.js and write to globals.css
   • CSS/HTML project → write to a tokens.css file
   • CSS-in-JS project → write to a theme.ts or theme.js file
   • If unclear, default to CSS custom properties (most portable)

4. Always generate both light and dark mode palettes. Use [data-theme="dark"] or prefers-color-scheme media query. Both palettes should feel intentional for the chosen philosophy, not just inverted values.

Token Categories

Color

/* Semantic color tokens, not raw values */
--color-bg-primary:          /* Main background */
--color-bg-secondary:        /* Secondary/card background */
--color-bg-tertiary:         /* Subtle background (inputs, wells) */
--color-bg-inverse:          /* Inverted background */

--color-text-primary:        /* Main text */
--color-text-secondary:      /* Subdued text */
--color-text-tertiary:       /* Placeholder, disabled text */
--color-text-inverse:        /* Text on inverse backgrounds */
--color-text-link:           /* Link color */

--color-border-primary:      /* Default borders */
--color-border-secondary:    /* Subtle borders */
--color-border-focus:        /* Focus ring color */

--color-accent-primary:      /* Primary action color */
--color-accent-primary-hover:
--color-accent-primary-active:
--color-accent-secondary:    /* Secondary action color */

--color-status-success:
--color-status-warning:
--color-status-error:
--color-status-info:

--color-surface-overlay:     /* Modal/dropdown backdrop */

Spacing

Generate a consistent scale. The base unit should match the philosophy:

• Tight philosophies (Brutalist, Swiss): 4px base
• Balanced philosophies (Rams, Scandinavian): 4px or 8px base
• Spacious philosophies (Japanese Minimalism, Editorial): 8px base with larger multipliers

--space-0:   0;
--space-1:   /* base * 0.25 */
--space-2:   /* base * 0.5 */
--space-3:   /* base * 0.75 */
--space-4:   /* base * 1 */
--space-5:   /* base * 1.5 */
--space-6:   /* base * 2 */
--space-7:   /* base * 3 */
--space-8:   /* base * 4 */
--space-9:   /* base * 6 */
--space-10:  /* base * 8 */
--space-11:  /* base * 12 */
--space-12:  /* base * 16 */

Typography

--font-family-display:       /* Headline/display font */
--font-family-body:          /* Body text font */
--font-family-mono:          /* Code/monospace font */

--font-size-xs:
--font-size-sm:
--font-size-base:
--font-size-md:
--font-size-lg:
--font-size-xl:
--font-size-2xl:
--font-size-3xl:
--font-size-4xl:             /* Hero/display size */

--font-weight-normal:
--font-weight-medium:
--font-weight-semibold:
--font-weight-bold:

--line-height-tight:         /* Headings: 1.1-1.3 */
--line-height-normal:        /* Body: 1.4-1.6 */
--line-height-relaxed:       /* Spacious body: 1.6-1.8 */

--letter-spacing-tight:      /* Display type */
--letter-spacing-normal:
--letter-spacing-wide:       /* All-caps, labels */

Layout

--max-width-content:         /* Max reading width (65-75ch equivalent) */
--max-width-wide:            /* Wide content area */
--max-width-page:            /* Full page max width */

--border-radius-sm:
--border-radius-md:
--border-radius-lg:
--border-radius-full:        /* Pill/circle */

--shadow-sm:
--shadow-md:
--shadow-lg:
--shadow-focus:              /* Focus ring shadow */

Motion

--duration-instant:   50ms;
--duration-fast:      150ms;
--duration-normal:    250ms;
--duration-slow:      400ms;
--duration-slower:    600ms;

--easing-default:     cubic-bezier(0.4, 0, 0.2, 1);
--easing-in:          cubic-bezier(0.4, 0, 1, 1);
--easing-out:         cubic-bezier(0, 0, 0.2, 1);
--easing-bounce:      cubic-bezier(0.34, 1.56, 0.64, 1);

Responsive Breakpoints

--breakpoint-sm:   375px;    /* Mobile */
--breakpoint-md:   768px;    /* Tablet */
--breakpoint-lg:   1024px;   /* Small desktop */
--breakpoint-xl:   1280px;   /* Desktop */
--breakpoint-2xl:  1536px;   /* Wide desktop */

Dark Mode

Always generate dark mode tokens alongside light mode. Rules:

• Do not simply invert colors. Dark backgrounds should be warm or cool depending on the philosophy.
• Reduce contrast slightly in dark mode (pure white text on pure black is harsh).
• Shadows should use darker, more transparent values in dark mode, not the same shadows as light.
• Accent colors may need lightness adjustments to maintain contrast ratios.
• Include a prefers-color-scheme media query AND a [data-theme="dark"] attribute selector so the user can support both system preference and manual toggle.

:root {
  /* Light mode tokens */
}

[data-theme="dark"] {
  /* Dark mode overrides */
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* System-preference dark mode, unless user explicitly chose light */
  }
}

Output

Save the tokens file in the appropriate location for the project's tech stack. State which philosophy the tokens are derived from and note any deviations or choices made.

This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with exceptional attention to aesthetic detail.

Example prompts

• "Build the hero section from the brief"
• "Create a card component in a Scandinavian style"
• "I want this to feel like a Japanese magazine. Build the layout."
• "Build the settings page. Use whatever style fits."

Before You Write Any Code

1. Explore the existing codebase first. Scan specifically for:

   • Component directories: components/, ui/, shared/ and list every component by name and its props/API
   • CSS variables / tokens: files named tokens.css, variables.css, theme.css, or :root declarations with custom properties
   • Tailwind config: tailwind.config.js or tailwind.config.ts, check theme.extend for custom values
   • UI framework themes: Material UI createTheme, Chakra extendTheme, shadcn globals.css and components.json
   • Storybook: .storybook/ directory or *.stories.* files indicating documented components
   • Font loading: Google Fonts links, @font-face declarations, font imports
   • Layout patterns: how existing pages handle grid, containers, breakpoints, and spacing
   • Package.json UI dependencies: tailwindcss, @mui/material, @chakra-ui/react, @radix-ui, lucide-react, framer-motion, etc.
   • If components exist that match or partially match what you need to build, extend or compose them. Do not create duplicates.

2. Understand the context:

   • What problem does this interface solve? Who uses it?
   • What is the intended emotional tone?
   • What are the hard constraints (framework, devices, performance, accessibility)?

3. Commit to an aesthetic direction. Either the user names one (see philosophies below) or you choose one that fits the context. State your choice and why before writing code.

Aesthetic Philosophies

When the user names a philosophy or describes a vibe, use these as concrete implementation guides. Each philosophy defines typography, color, layout, spacing, motion, and detail treatment.

Dieter Rams (Functionalist)

Less but better. Every element earns its place. Nothing decorative without function.

• Typography: Clean sans-serif (Helvetica Neue, Suisse Intl, Akkurat). Tight letterspacing on headings. Generous line height on body. One size scale, used strictly.
• Color: Restrained. Monochromatic with a single functional accent. White or light grey backgrounds. Color is information, not decoration.
• Layout: Strict grid. Clear functional hierarchy. Components aligned to a spatial system. No asymmetry for its own sake.
• Spacing: Consistent, mathematical scale (4px/8px base). Generous padding. Breathing room between elements.
• Motion: Minimal. Purposeful transitions only (state changes, reveals). No decorative animation.
• Details: Subtle borders and dividers over shadows. Precise alignment. Rounded corners used sparingly and consistently.

Swiss / International Typographic

Objectivity through structure. The grid is sacred. Content is king.

• Typography: Strong sans-serifs (Neue Haas Grotesk, Univers, Aktiv Grotesk). Dramatic scale contrast between headings and body. All-caps subheadings with generous letterspacing.
• Color: High contrast. Black, white, and one primary color. Bold color blocks as compositional elements.
• Layout: Rigid multi-column grid. Asymmetric balance. Text and image in dialogue. Alignment across elements is non-negotiable.
• Spacing: Defined by the grid module. Gutters are part of the design, not afterthought.
• Motion: Page transitions and scroll-triggered reveals that respect the grid. No playful bounce.
• Details: Rules (horizontal lines) as structural elements. No gradients. No shadows. Flatness is the point.

Japanese Minimalism (Ma)

Negative space is content. Restraint communicates sophistication. Quiet over loud.

• Typography: Thin-weight sans-serifs or elegant serifs (Noto Sans, Cormorant). Generous line height (1.8-2.0). Small body size with large whitespace margins.
• Color: Muted naturals (warm greys, stone, sage, washi). Subtle tonal shifts over hard contrasts. Near-monochrome.
• Layout: Asymmetric but balanced. Off-center content. Large empty areas are intentional. Content floats in space.
• Spacing: Extreme whitespace. Padding and margins 2-3x what feels "normal." Elements breathe.
• Motion: Slow, gentle fades (400-600ms). No bounce, no overshoot. Opacity transitions over position shifts.
• Details: Hairline borders. Subtle texture (paper grain, linen). No sharp shadows. Soft, diffused effects.

Brutalist / Raw

Structure is visible. No polish. Anti-aesthetic is the aesthetic.

• Typography: System fonts, monospace (JetBrains Mono, IBM Plex Mono, Courier), or aggressive display faces. Mixed sizes. Text as texture.
• Color: Black and white primary. If color, it is raw and clashing (construction yellow, hazard orange, terminal green). No gradients.
• Layout: Visible borders. Box model exposed. Stacked blocks. Deliberate roughness. Content first, beauty never.
• Spacing: Tight or intentionally uneven. Padding that feels compressed.
• Motion: None, or jarring (instant state changes, hard cuts). No easing.
• Details: Visible outlines. Default browser form elements can be intentional. Text-only interfaces. No icons unless functional.

Scandinavian

Warmth plus restraint. Functional beauty. Accessible by default.

• Typography: Rounded, friendly sans-serifs (Nunito, Poppins, Circular, Cera Pro). Medium weights. Comfortable reading sizes.
• Color: Natural palette. Warm whites, soft blues, muted greens, clay. Pastel accents. No pure black (use charcoal).
• Layout: Clean and open. Card-based. Rounded corners (8-12px). Comfortable, generous layouts.
• Spacing: Generous but not extreme. Everything feels approachable and uncluttered.
• Motion: Gentle, natural easing. Subtle hover lifts. Content that settles into place.
• Details: Soft shadows (large blur, low opacity). Rounded elements. Warm undertones in greys. Illustration-friendly.

Art Deco / Geometric

Bold symmetry. Decorative precision. Statement and luxury.

• Typography: Geometric display faces (Futura, Poiret One, Josefin Sans). All-caps headlines with extreme letterspacing. Serif body text for contrast.
• Color: Rich and deep. Gold/champagne, emerald, navy, burgundy, black. Metallic accents (gold gradients, shimmer effects).
• Layout: Symmetrical and centered. Strong vertical axis. Decorative frames and borders. Layered depth.
• Spacing: Structured and formal. Padding is architectural.
• Motion: Elegant reveals. Staggered entrance animations. Parallax depth.
• Details: Geometric patterns (chevrons, sunbursts, fan shapes). Ornamental borders. Texture (marble, brushed metal). Statement typography at hero scale.

Neo-Memphis

Playful chaos. Anti-corporate. Shapes as characters.

• Typography: Mix of weights and styles. Clashing fonts is intentional. Oversized headlines. Text at angles.
• Color: Bold primaries and neons. Clashing combinations (pink and yellow, blue and orange). No muted tones. Flat color, no gradients.
• Layout: Broken grid. Overlapping elements. Shapes (circles, triangles, squiggles) as compositional elements. Asymmetric on purpose.
• Spacing: Dense in some areas, empty in others. Rhythm is irregular.
• Motion: Bouncy, playful. Exaggerated hover effects. Elements that wiggle, rotate, or pop.
• Details: Thick borders. Geometric shapes as decoration. Patterns (dots, dashes, zigzags). Drop shadows with hard edges and bright colors.

Editorial / Magazine

Content-led design. Typography does the heavy lifting. Every page is a spread.

• Typography: Display serif for headlines (Playfair Display, Fraunces, Instrument Serif). Clean sans for body (DM Sans, Source Sans). Dramatic scale (hero headlines at 72-120px). Pull quotes. Drop caps.
• Color: Minimal. Black and white with one accent. Color used editorially (to highlight, not decorate).
• Layout: Strong column grid (3-5 columns). Full-bleed images. Text wrapping. Mixed column widths. Vertical rhythm.
• Spacing: Generous margins. Tight leading on headlines, open on body. Whitespace as a compositional tool.
• Motion: Scroll-triggered reveals. Parallax on images. Smooth page transitions.
• Details: Thin rules as dividers. Caption typography. Issue/date metadata. Print-inspired details (folio numbers, running headers).

Implementation Guidelines

• Typography: Choose distinctive fonts loaded via Google Fonts or CDN. Avoid generic defaults (Inter, Roboto, Arial, system fonts). Pair a display font with a body font.
• Color: Use CSS variables for consistency. Dominant color with sharp accents outperforms safe, evenly-distributed palettes.
• Motion: CSS transitions for HTML. Framer Motion / Motion library for React. Focus on high-impact moments (page load reveals, state changes) over scattered micro-interactions.
• Spatial composition: Unexpected layouts earn attention. Asymmetry, overlap, diagonal flow, grid-breaking elements. Or, if the philosophy demands it, strict grids executed with precision.
• Backgrounds and depth: Create atmosphere. Gradient meshes, noise textures, geometric patterns, layered transparencies, grain overlays. Match the chosen philosophy.

NEVER produce generic AI aesthetics: purple gradients on white, Inter font, predictable card grids, cookie-cutter component layouts. Every output should feel designed for its specific context.

Match implementation complexity to the aesthetic vision. A Dieter Rams interface is 50 lines of precise CSS. A Neo-Memphis interface is 300 lines of creative chaos. Both are correct.

Mobile-First

Build mobile layout first, then scale up. This is non-negotiable.

• Start with a single-column layout at 375px width.
• Add complexity at each breakpoint (min-width media queries, not max-width).
• Touch targets must be at least 44x44px on mobile.
• Body text must be at least 16px on mobile (prevents iOS zoom on input focus).
• Navigation must have a mobile-specific pattern (hamburger, bottom tabs, or drawer). Do not rely on horizontal nav bars that overflow.
• Test that line lengths stay comfortable (45-75 characters) at every breakpoint.

Dark Mode

If a design tokens file exists (from /design-tokens), use its dark mode palette. If not, generate dark mode support alongside the light theme.

• Use CSS custom properties so switching themes means changing variable values, not rewriting components.
• Support both prefers-color-scheme media query (system preference) and a [data-theme="dark"] attribute (manual toggle).
• Do not simply invert colors. Dark backgrounds should be warm or cool to match the philosophy (warm charcoal for Scandinavian, cool slate for Swiss, near-black for Brutalist).
• Reduce pure white text to off-white (e.g., #E5E5E5 or rgba(255,255,255,0.87)) to reduce eye strain.
• Shadows in dark mode should be darker and more transparent, not the same values as light mode.
• Accent colors may need lightness adjustments to maintain WCAG contrast ratios against dark backgrounds.
• Include a prefers-reduced-motion media query for users who need it. Disable or simplify all animations and transitions within that query.

Example prompts

• "Grill me on this landing page idea"
• "I want to build a dashboard for tracking team metrics. Challenge my thinking."
• "Stress-test my approach to this settings page"
• "I have a rough idea for a portfolio site. Help me think it through."

Instructions

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one by one.

If a question can be answered by exploring the codebase, explore the codebase instead of asking me.

If a question can be answered by examining existing components, styles, or design tokens in the project, examine them instead of asking me.

For each question, provide your recommended answer.

This skill defines the structural skeleton of a product or site. It sits between the design brief and the build. Run this after the brief is written and before tasks are created.

Example prompts

• "Plan the IA for this app before I start building"
• "Map out the navigation and page structure"
• "I need to organize the content for a documentation site"
• "Define user flows for the onboarding experience"

Process

1. Look for an existing design brief at .design/*/DESIGN_BRIEF.md. If multiple subfolders exist, use the most recently modified one, or ask the user which feature they are working on. If no brief exists, ask the user what they are building and for whom.

2. Explore the existing codebase to understand what structure already exists:

   • Routing: Next.js app/ or pages/ directory, React Router config, Vue Router, SvelteKit routes, or static HTML page files
   • Navigation components: header, sidebar, navbar, breadcrumb, footer components
   • Layout components: root layouts, nested layouts, page wrappers, container components
   • Page directories: how pages are currently organized in the file system
   • URL patterns: existing slugs, dynamic segments, query parameter conventions
   • CMS or data layer: content models, API routes, data fetching patterns, MDX/content directories
   • If structure exists, this skill extends and improves it. Do not propose a new architecture that ignores what is already built.

3. Interview the user about structural decisions. For each question, provide your recommended answer.

   Cover at minimum:

   • What are the primary things a user needs to find or do? Rank by frequency.
   • How many levels of navigation depth are acceptable?
   • What content will grow over time vs. what is fixed?
   • Are there distinct user types who need different entry points?
   • What is the one page/view where the user spends 80% of their time?

4. Once you have a shared understanding, produce the IA document using the template below and save it as INFORMATION_ARCHITECTURE.md in the same .design/<feature-slug>/ subfolder as the design brief.

IA Document Template

# Information Architecture: [Product/Site Name]

## Site Map

A hierarchical map of every page or view. Use indentation to show nesting. Include the URL pattern for each.

- Home `/`
  - Feature A `/feature-a`
    - Sub-page `/feature-a/detail`
  - Feature B `/feature-b`
- Settings `/settings`
  - Profile `/settings/profile`

## Navigation Model

Describe the navigation system:
- **Primary navigation**: What appears in the main nav? Maximum items.
- **Secondary navigation**: Sidebar, tabs, or contextual links within sections.
- **Utility navigation**: Account, settings, help, and anything outside the main content hierarchy.
- **Mobile navigation**: How navigation adapts. Hamburger, bottom tabs, or something else.

## Content Hierarchy

For each major page or view, define the content priority:

### [Page Name]
1. [Highest priority content] -- Why this comes first
2. [Second priority] -- Why this comes second
3. [Third priority] -- Rationale
4. [Below the fold / secondary]

## User Flows

The critical paths through the product. Each flow is a sequence of steps with decision points noted.

### [Flow Name] (e.g., "New user onboarding" or "Create a project")
1. User lands on [page]
2. User sees [content/prompt]
3. User takes action: [action]
   - If [condition A] -> [outcome]
   - If [condition B] -> [outcome]
4. User arrives at [destination]

## Naming Conventions

A glossary of terms used in the interface. Consistency matters. Pick one word and use it everywhere.

| Concept | Label in UI | Notes |
|---------|-------------|-------|
| [thing] | [what we call it] | [why this word] |

## Component Reuse Map

Which structural components (layouts, containers, navigation elements) are shared across pages.

| Component | Used on | Behavior differences |
|-----------|---------|---------------------|
| [layout/component] | [pages] | [any variations] |

## Content Growth Plan

Which sections of the site will accumulate content over time and how the IA accommodates that growth (pagination, filtering, search, archive patterns).

## URL Strategy

Rules for URL construction:
- Pattern: [e.g., `/section/subsection/item-slug`]
- Dynamic segments: [what is parameterized]
- Query parameters: [filtering, sorting, pagination]