recipe-refine-visuals

Optional side-workflow for design experts to refine auto-derived Visual Tokens in brand-direction.md with professional judgment

Context: Refine the Visual Tokens section of docs/product/design/brand-direction.md with design expertise. This recipe reads the existing brand direction (including auto-derived tokens from recipe-blueprint) and lets a design expert override specific values with professional judgment. The output is the same brand-direction.md file — downstream consumers (prototype-generator, UI Spec) read it without knowing which path produced the tokens.

When to Use

  • After recipe-blueprint has completed and brand-direction.md exists with auto-derived Visual Tokens
  • When a design expert is available and wants to refine the visual system
  • This recipe is entirely optional — auto-derived tokens are sufficient for prototype generation

Orchestrator Definition

Execution Protocol:

  1. Follow the refinement flow defined below
  2. Stop at every [STOP — BLOCKING] marker — present findings and CANNOT proceed until user explicitly confirms

Workflow Overview

Input (existing brand-direction.md with auto-derived tokens)
    ↓
1. Context Reading → Read brand direction + design principles + personas
    ↓
2. Token Review → Present current tokens with their derivation rationale
    ↓
3. Expert Refinement → User specifies overrides [Stop: User confirms changes]
    ↓
Output: Updated Visual Tokens in docs/product/design/brand-direction.md

Execution Decision Flow

1. Context Reading

Gate: docs/product/design/brand-direction.md must exist with a Visual Tokens section. If missing → inform user to run recipe-blueprint first.

Read:

  • docs/product/design/brand-direction.md — current direction and auto-derived tokens
  • docs/product/design-principles.md — trade-off context
  • docs/product/personas/ — audience context
  • Reference Products listed in brand-direction — use WebSearch to inspect their current design if needed

2. Token Review

Present the current Visual Tokens organized by category, showing:

  • Current value and its derivation source
  • How it relates to the directional sections above it
  • Any inconsistencies between tokens (e.g., contrast ratio issues between text and surface colors)

Highlight areas where expert judgment would have the most impact:

  • Color harmony and palette coherence
  • Font pairing quality
  • Spacing scale appropriateness for the product's density target

3. Expert Refinement

Guide the expert through each token category:

Color Tokens

  • Present current palette as a visual summary (hex values with role labels)
  • Ask: which values to keep, which to override
  • Validate contrast ratios: --color-text against --color-surface must meet WCAG AA (4.5:1 for body text)
  • Validate color harmony across the full palette

Typography Tokens

  • Present current font selections with Google Fonts links
  • Ask: alternative font pairings, size adjustments, weight preferences
  • Validate: heading/body contrast is sufficient for hierarchy
  • Validate: selected fonts support the product's language(s)

Spacing Tokens

  • Present current scale with the base unit
  • Ask: base unit adjustment, scale ratio preferences
  • Validate: scale produces enough differentiation between levels

For each override, record the expert's rationale in the Decisions Log.

[STOP — BLOCKING] Present the refined token set to user for confirmation:

  • Side-by-side comparison: auto-derived vs. expert-refined values
  • Rationale for each change
  • Contrast and harmony validation results

CANNOT update the file until user explicitly confirms.

4. File Update

After user approval:

  • Update the Visual Tokens section in docs/product/design/brand-direction.md
  • Change Source field from auto-derived to expert-refined
  • Add override entries to the Brand Direction Decisions Log

Scope Boundaries

Included: Visual Token refinement (colors, typography, spacing) within the existing brand-direction.md Not included: Changing directional sections (Tone & Voice, Color Direction, etc.), adding new sections, component-level specifications, responsive breakpoints

Completion Criteria

  • Existing brand-direction.md read with auto-derived tokens
  • Current tokens reviewed with derivation context
  • Expert overrides collected with rationale
  • Contrast and harmony validated
  • User confirmed refined tokens
  • brand-direction.md updated with source marked as expert-refined
  • Decisions logged in Brand Direction Decisions Log