design-state

Design State

The design state is a shared, living document that accumulates design decisions as the workflow progresses. Every Designpowers agent reads it before starting work and updates it when done. It is the single source of truth for the current state of the design.

Welcome Gate

BEFORE initialising or reading design state, check whether the Designpowers welcome sequence has been shown this session. If the user has not yet seen the welcome (the bird, the greeting, and the walkthrough offer), you MUST invoke the using-designpowers skill FIRST and complete the welcome sequence before returning here. The bird must appear before any work begins. No exceptions.

The File

The design state lives at design-state.md in the project root (or working directory). One file per project.

When to Use This Skill

• Initialise — when design-discovery completes and a brief is approved, create the design state file
• Read — before dispatching any Designpowers agent, confirm the design state file exists and is current
• Update — after any agent completes work, append their decisions and outputs to the state file
• Review — during critique or verification, use the state file as the definitive record of what was decided

Structure

Create and maintain the design state file with this structure:

# Design State: [Project Name]

_Last updated: [date] by [agent name]_

## Brief
- **Problem:** [one-line problem statement]
- **Primary persona:** [name and context]
- **Success metric:** [what "done" looks like]
- **Brief document:** [relative path to full brief]

## Personas
[Link to personas document]
- [Persona 1 name] — [one-line context]
- [Persona 2 name] — [one-line context]
- ...

## Design Principles
1. [Principle] — [what it means in practice]
2. [Principle] — [what it means in practice]
3. ...

## Taste Profile
- **Emotional target:** [2-3 words — e.g., "calm confidence", "playful warmth"]
- **Quality level:** [Prototype / Production / Flagship]
- **Key references:** [names/URLs]
- **Aesthetic principles:** [list]
- **Taste document:** [path to full taste profile]

_If no taste calibration was done, note: "No taste profile — craft evaluation uses general quality standards only."_

## Decisions Log
Append-only. Each entry records who decided, what, and why.

| Date | Agent | Decision | Rationale |
|------|-------|----------|-----------|
| [date] | design-strategist | Bottom tab navigation, 3 items | Minimises cognitive load per principle #1 |
| [date] | design-lead | Mint/sage palette, category colour coding | Warm, approachable, passes AA contrast |
| ... | ... | ... | ... |

## Open Questions
Things that need resolution. Remove when resolved (move decision to log).

- [ ] [Question — who needs to answer it]
- [ ] ...

## Artefact Index
Paths to key documents produced during the workflow.

| Artefact | Path | Status |
|----------|------|--------|
| Brief | [path] | Approved |
| Personas | [path] | Complete |
| Strategy | [path] | Complete |
| Plan | [path] | In progress |
| Heuristic evaluation | [path] | [Pending/Complete] |
| Synthetic test results | [path] | [Pending/Complete] |
| ... | ... | ... |

## Design Debt Register
Deferred findings from critique, accessibility review, heuristic evaluation, and synthetic user testing. Managed by `design-debt-tracker`.

_Items: 0 | Critical: 0 | Oldest: —_

| ID | Date | Source | Severity | What | Who is affected | Suggested fix | Status | Notes |
|----|------|--------|----------|------|----------------|---------------|--------|-------|

## Handoff Chain
Track which agent handed off to which. Each entry includes the conversational babble message that the agent wrote when handing off. These messages are shown to the user.

### [timestamp] design-strategist → design-lead
> "The core users are families with a new puppy, kids aged 8-14 taking the lead. Principle #1 says 'celebrate effort, not perfection' — so nothing should feel like a report card. The setup flow needs progressive disclosure. Over to you for the visual direction."

### [timestamp] design-lead → motion-designer
> "I've gone with frosted glass cards and a mint/sage palette. The progress ring is the hero moment — when it hits 100% it needs to feel like a celebration, not just a colour change. Keep it subtle everywhere else."

**🎨 User override:** "Use my existing design system instead of mint/sage. The tokens are in /tokens/colors.json."

### [timestamp] motion-designer → design-builder
> "Progress ring gets a 600ms spring fill. Checkboxes get 150ms bounce. Reduced-motion fallbacks swap to opacity fades."

### [timestamp] ...