design-brief

Q: How do I install design-brief?

Run npx skills add https://github.com/julianoczkowski/designer-skills --skill design-brief in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-brief/ (personal) or .claude/skills/design-brief/ (project).

by julianoczkowskiFrontend & Design

Create a design brief through an interactive interview, codebase exploration, and experience design decisions. Saved as a markdown file in the project. Use when user wants to write a design brief, plan a new feature or page, define a UI direction, or mentions "brief".

Installs: 5.3K
Last 24h: —
Trending rank: —
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/julianoczkowski/designer-skills --skill design-brief

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads design-brief automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill helps create design briefs by interviewing the user and analyzing the project's CSS and configuration files. It is generally safe and contains no executable code; however, it has a minor vulnerability to indirect prompt injection because it processes content from local codebase files that could potentially contain malicious instructions.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed

SKILL.md

The instructions your agent reads when the skill is triggered.

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

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.
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.
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?
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.

FAQ

What does the design-brief skill do?

How do I install design-brief?

Run npx skills add https://github.com/julianoczkowski/designer-skills --skill design-brief in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-brief/ (personal) or .claude/skills/design-brief/ (project).

Which AI agents can use design-brief?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is design-brief safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains design-brief?

It is published by julianoczkowski in julianoczkowski/designer-skills. It has 5,330 recorded installs.