--- name: design-brief description: Author the design brief for an initiative with a user-facing surface — the context handoff from Claude Code to claude.ai/design (what to design plus the hard, presentation-only constraints). Use after the PRD and before any design or build, when the intake checklist flags a user-facing surface. version: 1.1.0 owner: wawan risk: low category: design scope: read:okf, write:planning/design --- # design-brief — Author a Design Brief This skill produces a design brief instance for one initiative. It is **leg 1** of the [design loop](/okf/core/concepts/design-loop.md): the context handoff from Claude Code to claude.ai/design. The brief is to design what the [PRD](/skills/prd.skill) is to build — the shared definition of *what to design* and the hard constraints, agreed before any design or build starts. > **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/SKILL-FORMAT.md)). > Level 1 above is the trigger; this body is Level 2; rare variants go to Level 3 sub-files by name. ## When to use vs. not - **Use** when an initiative has a PRD and adds or changes a **user-facing surface** in the product's app (`web/` for PMOS's own app; the intake checklist's user-facing-surface trigger has fired). - **Do not use** to make data or feature decisions. Two cases ([D48](/okf/products/pmos/adr/d48-design-loop.md) as scoped by [D60](/okf/products/pmos/adr/d60-prototype-loop.md)): - **Redesign of an existing surface** — the brief is **presentation-only**; if a design would need new data, a new flow, or secrets in the client, that is a **separate decision** — flag it back, do not brief it in. - **New surface downstream of an approved PRD (D60 leg B)** — the brief MAY define the new views and flows **the PRD decided**, and should carry the promoted leg-A prototype as its starting point when one exists. The design produced is the reference the build works from, and is held to the [design-reference grilling rubric](/planning/evals/design-reference-eval-rubric.md). Anything beyond what the PRD decided is still flagged back. - **Do not use** for the reconciliation gate — classifying a returned design against real capability is the [design-reconcile skill](/skills/design-reconcile.skill) (leg 3). ## Procedure 0. **Grill before you brief** (the [prd skill](/skills/prd.skill)'s step-0 discipline, applied to design intent): where the PM's aesthetic or structural intent is ambiguous, ask **one question at a time with a recommended answer**, stop at unambiguous — no cap; a batch questionnaire is not compliant. Look up what the environment answers (the capability ledger, the design system, the promoted prototype); the taste calls are the PM's (D12). The recorded cost of skipping this is the console-redesign series — "too many navigations" was stated once and unhonored twice. 1. **Confirm the anchor.** The initiative has a PRD and an anchor — a parent KR, or a declared health budget `health:` (D59). The brief does not re-argue *whether* to build the surface; it says how it should look. 2. **Start from the template.** Use [design-brief-template](/okf/core/templates/design-brief-template.md) as the scaffold. Do not invent a new structure. 3. **State the product's point of view.** One paragraph on the aesthetic the design must read as (PMOS's own control-plane app, for example: a dense, dark-mode-first operations dashboard — information-first, fast to scan). 4. **Inventory each surface against its REAL data.** For every surface, name the RLS-scoped view/table it reads and its notable states (empty / loading / error). Designing to the true data shape — column counts, empty states, density — is the anti-**watermelon-UI** move at brief time: it stops the design from imagining capability that has no backend. 5. **Specify the semantic token system and component set.** Name tokens with semantic names (status, surface, text) with light + dark values, and list the reusable components + variants to design. Once the product's real component library exists, ask for its actual component vocabulary (for PMOS, see [.design-sync/conventions.md](/.design-sync/conventions.md)). 6. **State the hard constraints and out-of-scope.** Behavior-preserving; accessibility (status not by color alone); density; deployment limits. Out-of-scope is **required and non-empty**, and explicitly says a data-implying idea is flagged back, not built. 7. **Write the leg-2 prompt.** A single prompt that reproduces the brief for the claude.ai/design agent. 8. **Keep it at control altitude.** The brief specs *what to design*; it does not write the app code ([control-plane](/okf/core/concepts/control-plane.md)). ## Required content - **Identity** — `initiative_id`, `product_slug`, `pm_slug`, parent `KR`. - **Point of view** — the aesthetic the design serves. - **Surface inventory** — surface / job / real data source / notable states. - **Token system** — named semantic tokens (light + dark). - **Component set** — reusable components + variants (the deliverables `/design-sync` will carry back). - **Hard constraints** — behavior-preserving, accessibility-not-color-alone, density, deployment. - **Out-of-scope** — non-empty; data-implying ideas flagged back as a separate decision. - **Leg-2 prompt** — the paste-in prompt for claude.ai/design. ## Output and placement - Design brief instances are **operational**, not OKF knowledge. They live under `/planning/design/`, not in the bundle ([okf-governance](/okf/core/concepts/okf-governance.md)). - Filename: descriptive and slugged, e.g. `-design-brief.md`. ([planning/design-brief.md](/planning/design-brief.md) is the first instance — the D38 web refresh.) ## Quality bar Before handing off, confirm: presentation-only stated; every surface tied to a real data source; accessibility (not-color-alone) constraint present; out-of-scope non-empty; token + component deliverables named; the leg-2 prompt included. ## Level 3 sub-cases - Multi-surface or net-new-surface briefs (mobile + web, or a surface with no current data): see `design-brief-multisurface.md` (author on first need).