---
description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
agent: build
---

# Update Design

This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (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

```
opencode
> /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.

### 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.
- 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.
"
```