Design Brief

Raw
referencelatestRetrieved 2026-05-16

designer-skills — /design-brief

What it is

The design-brief skill creates a structured design brief through conversation, codebase exploration, and experience design decisions. Output is saved as a markdown file in the project at .design/<feature-slug>/DESIGN_BRIEF.md.

Key distinction from a generic planning tool: The skill includes a detailed codebase detection checklist to ensure the brief respects what already exists — preventing the AI from generating a new button when one exists, or inventing a color that clashes with the established palette.

Process

  1. User description — Ask for what they want to build, who it's for, and any constraints.
  2. Codebase exploration — Detect and catalogue existing CSS variables/tokens, Tailwind config, UI framework themes, component directories, Storybook, design token files, font loading, and existing pages/layouts.
  3. Structured interview — Walk through every design decision until shared understanding is reached, providing recommended answers for each question. Covers: primary user + JTBD, success definition, emotional tone, reference products, hard constraints, and content.
  4. Brief output — Write the structured brief using the required template.

Codebase detection checklist

The skill scans for:

  • CSS variables / tokens: tokens.css, variables.css, theme.css, or :root declarations
  • Tailwind config: tailwind.config.js / .ts, check theme.extend for custom values
  • UI framework themes: Material UI createTheme, Chakra extendTheme, shadcn globals.css
  • Component directories: components/, ui/, shared/
  • Storybook: .storybook/ directory or *.stories.* files
  • Design token files: JSON token files (Style Dictionary, Figma token exports)
  • Package.json UI dependencies
  • Font loading: Google Fonts links, @font-face declarations
  • Existing pages/layouts: route files, layout components, page templates

Brief template sections

The required brief output includes: Problem, Solution, Experience Principles (max 3), Aesthetic Direction (philosophy + tone + references + anti-references), Existing Patterns, Component Inventory, Key Interactions, Responsive Behavior, Accessibility Requirements, and Out of Scope.

File output

Saved to .design/<feature-slug>/DESIGN_BRIEF.md. All subsequent skills in the flow read from this same subfolder.