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

description
Refine the design before /generate-app, 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 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

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.

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