---
description: Refine the design before the app shell is generated (milestone 01), or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
---

# Update Design

This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** the app shell is generated by milestone 01 (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.

**Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)

## How to Run

```bash
claude
> /update-design add a profile screen with avatar and edit form
```

## Pre-Run Check

Confirm the design files exist. If they are missing, stop and tell the user to run `/define-design` first:

- `docs/design/design-brief.md`
- `docs/design/design-tokens.json`
- `docs/design/ui-blueprint.json`
- `docs/design/platform-mapping.md`

## Procedure

### Step 0: Read the Inputs

Read:

- The existing design files listed above
- `docs/product-requirements.md` and `docs/functional-design.md` for context
- The change description provided in `$ARGUMENTS`

### Step 1: Update `ui-blueprint.json` First

The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.

If the change adds or removes screens, also update `docs/design/screen-inventory.md` (create it if missing — see the ui-design skill) so it stays the complete screen list: new screens get a checked (`[x]`) entry with purpose, source, and how they are reached; removed screens are deleted from it.

### Step 2: Update `design-tokens.json` (if needed)

If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.

### Step 3: Update `design-brief.md` (if the direction changes)

If the change affects the overall design direction (visual mood, layout principles, navigation principles, accessibility), update the brief. If it is a localized screen/component change, leave the brief unchanged.

### Step 4: Update `platform-mapping.md` (if needed)

If the change introduces a new platform target or a new kind of mapping (e.g. a new component family that maps differently per platform), update the mapping. Otherwise leave it unchanged.

### Step 5: Regenerate Affected SVG Wireframes

For every screen added or modified in `ui-blueprint.json`, generate or regenerate the corresponding SVG under `docs/design/screens/`. Remember: SVGs are visual references only — the blueprint is the source of truth.

### Step 6: Consistency Check

- Every screen in `ui-blueprint.json` has a matching SVG.
- `docs/design/screen-inventory.md` (if present) lists exactly the blueprint's screens.
- Token names referenced in the blueprint exist in `design-tokens.json`.
- The brief and mapping remain consistent with the blueprint.

### Step 7: Do Not Implement Code

Do **not** modify application code in this command. If the user also wants the code updated, they should run `/add-feature` (which reads the updated design files) or ask explicitly.

## Completion Criteria

- `ui-blueprint.json` has been updated (source of truth).
- `design-tokens.json` updated only if new tokens were needed.
- `design-brief.md` updated only if the direction changed.
- `platform-mapping.md` updated only if mappings changed.
- Affected SVG wireframes regenerated.
- No application code was changed.

Completion message:
```
"Design has been updated.

Updated:
✅ docs/design/ui-blueprint.json   (source of truth)
✅ docs/design/design-tokens.json   (if new tokens were needed)
✅ docs/design/design-brief.md      (if the direction changed)
✅ docs/design/platform-mapping.md  (if mappings changed)
✅ docs/design/screens/*.svg        (regenerated as needed)

Note: application code was not changed. Run /add-feature to implement the change, respecting the updated design.
"
```