---
name: brief
description: Generate a portable Claude Design brief prompt specifying target description, 4 viewports, 3 token tiers, component anatomy, 8 states, and deliverables.
argument-hint: "<description> [--workspace <parent-path>]"
---

# Design Brief Generator

Replace `<plugin-root>` in CLI examples with the absolute directory two levels above this skill file (`skills/brief/SKILL.md`); Claude Code may use `${CLAUDE_PLUGIN_ROOT}` instead. Never execute the literal placeholder.

Generates a portable design brief prompt (written to `design-brief-<uuid>.md` when `--workspace` is supplied) designed to be copied directly into Claude Design. The brief establishes concrete design system constraints before visual exploration begins, ensuring exported artifacts can be cleanly parsed into a deterministic `DesignContract`.

## CLI Command

```bash
node "<plugin-root>/scripts/cli.mjs" generate-brief --description "<product-or-component-description>" [--workspace "<workspace-parent-path>"]
```

## Static Generator Structure (emitted by CLI)

The static prompt generated by `scripts/workflow.mjs` directly covers six structured sections:

1. **Target Description**: The raw component or interface description provided via `--description`.
2. **Viewports & Responsive Design**: Explicit fluid reflow across four target viewports:
   - `320px` (Mobile small / narrow)
   - `390px` (Mobile standard)
   - `768px` (Tablet)
   - `1440px` (Desktop)
3. **Design Token Tiers**:
   - `primitive`: Raw base palette, typography scales, spacing units, and radius primitives.
   - `semantic`: Intent tokens mapping primitives to purpose (e.g. `surface`, `text-primary`, `border-focus`).
   - `component`: Component-scoped token bindings referencing semantic tokens.
4. **Component Hierarchy, Anatomy & Slots**:
   - Element hierarchy, roles, and stable element IDs.
   - Content slots, injection points, and interactive controls.
5. **Canonical States (8 Required)**:
   - Requires behavior and styling or an explicit `N/A` with non-empty reason for all 8 states:
     `1. default`, `2. hover`, `3. focus`, `4. active`, `5. disabled`, `6. loading`, `7. error`, `8. selected`.
6. **Deliverables**:
   - `audience`: Target personas and WCAG 2.2 AA accessibility expectations.
   - `theme`: Light, dark, and high-contrast palettes, plus RTL direction support.
   - `keyboard`: Logical tab order, visible focus indicators, and accessible keyboard navigation.
   - `responsive`: Viewport reflow (320, 390, 768, 1440) and touch target sizing.
   - `export`: Component export bundle with assets, provenance, and licensing documented (manual download required).

## Optional Agent-Authored Enrichment

When invoked conversationally in Claude Code, Kimi, or Codex, the host agent may optionally suggest or append project-specific context before the user pastes the brief into Claude Design:
- **Brand Atmosphere & Craft**: Suggesting font pairings or domain-specific density (consulting `references/upstream/interface-design-main/.claude/skills/interface-design/SKILL.md`).
- **Initial Marketing Guidance**: For unstyled public marketing briefs, suggesting Three Dials parameters (variance, motion, density) from `references/upstream/taste-skill-main/skills/taste-skill/SKILL.md`. Once a design is approved, the export identity is authoritative.

## Manual Download Workflow
1. Present the generated design brief prompt (`design-brief-<uuid>.md`) to the user.
2. Instruct the user to open Claude Design, paste the brief, and approve the generated design.
3. Instruct the user to download the export package (`.zip`, `.html`, `.dc.html`, or asset folder) to a local Windows directory (e.g. `C:/Users/<Username>/Downloads/design-export.zip`).
4. Pipeline enters `WAITING_FOR_DOWNLOAD` until the user provides the local Windows path for `/ui-component-expert:ingest`.