recipe-refine-visuals

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