claudecode-boilerplate/.claude/commands/update-design.md

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

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