---
type: Template
title: Design Brief Template
description: The scaffold for a design brief instance — the context handoff from the interactive agent to an external design surface (e.g. claude.ai/design). Copy into /planning/design/ and fill; presentation-only.
tags: [template, design, brief, planning]
timestamp: 2026-07-01
---

# Design Brief Template

**Situating context:** This template is the canonical scaffold the
[design-brief skill](/skills/design-brief.skill) instantiates — leg 1 of the
[design loop](/okf/core/concepts/design-loop.md). It is to design what the
[PRD template](/okf/core/templates/prd-template.md) is to build: the shared definition before work starts.
Copy the block into `/planning/design/<slug>-design-brief.md` and fill it; the copy is an operational
instance and does not live in the OKF bundle.

> Usage: replace every `<…>` placeholder; delete guidance comments (`<!-- … -->`). **Behavior is locked —
> only presentation is in scope.** Every surface must tie to a real data source (that is the anti-watermelon
> move at brief time). An empty out-of-scope list means the brief is not ready.

---

```markdown
# Design Brief: <initiative title> (for claude.ai/design)

## Identity
- initiative_id: <id>
- product_slug: <product_slug>
- pm_slug: <pm_slug>
- parent_KR: <objective.kr reference OR health:<id> (D59)>
- date: <YYYY-MM-DD>

## Point of view (so the design has one)
<!-- What the product is and the aesthetic it should read as. Keep it to the design's job. -->
<e.g. a dense, dark-mode-first operations dashboard — calm, information-first, fast to scan — not a
marketing site. Every screen answers one operator question.>

## Surfaces to design
<!-- One row per surface. Tie each to the REAL data it shows so the design fits the true shape
     (column counts, empty states, density) — this is where watermelon-UI is prevented up front. -->

| Surface | Job (one operator question) | Real data source (RLS-scoped view/table) | Notable states |
|---|---|---|---|
| <surface> | <job> | <view/table> | <empty / loading / error / active> |

## Semantic token system (the heart of it)
<!-- Named tokens with light + dark values, NOT one-off swatches. The build maps them to CSS variables
     once; views never touch raw hex again. -->
- <status tokens, e.g. rag-red / rag-amber / rag-green; pulse-*; eval-*; watermelon>
- <base tokens: background / foreground / primary / muted / border / destructive>

## Component set (deliverables)
<!-- Reusable components + their variants — exactly what /design-sync carries back as the library. -->
1. <component> — <variants / sizes>
2. ...

## Hard constraints (do not design around these)
- **Behavior-preserving** — no new views, no new data, no changed flows. Presentation only.
- **Accessibility** — status must not rely on color alone (glyph + text; contrast; focus states).
- **Density** — favor information density and scan-ability over whitespace (if an ops console).
- <deployment / bundle / platform constraints, e.g. static hosting, bundle budget>

## Out of scope (REQUIRED, non-empty)
<!-- New features, data-model changes, flow changes, secrets/keys in the client. If a design implies a
     data change, FLAG IT BACK — it is a separate decision, not part of this brief. -->
- <out-of-scope item>

## Leg-2 prompt (paste into claude.ai/design)
<!-- A single prompt that reproduces the above for the design agent. -->
> <prompt>
```

---

## Authoring checklist

- [ ] `parent_KR` present and real; brief paired to an initiative that passed intake.
- [ ] Every surface tied to a real data source (no imagined capability).
- [ ] Token system named with semantic names, not swatches.
- [ ] Accessibility (not-color-alone) constraint present.
- [ ] Out-of-scope non-empty; any data-implying idea flagged back as a separate decision.
- [ ] Component deliverables named; leg-2 prompt included.
- [ ] Stays presentation-only — no behavior, data, or flow changes proposed.