oh-my-opencode 4.13.0 → 4.14.1

package/dist/skills/frontend/references/designpowers/vendor/skills/synthetic-user-testing/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: synthetic-user-testing
+description: "Use after the fix round to validate the design by walking through key tasks as each persona — simulating how Jordan (low-vision), Priya (non-native speaker), Marcus (motor impairment), or any project persona would actually experience the interface. Catches the issues that code review misses because they only surface in the act of using"
+---
+
+# Synthetic User Testing
+
+Synthetic user testing is the closest thing to putting the design in front of real people without leaving the pipeline. You walk through the interface as each persona, attempting real tasks, and report what works, what breaks, and what feels wrong — from their perspective, not yours.
+
+This is not a checklist exercise. It is an act of empathy disciplined by specifics. When you test as Jordan (low-vision, uses 200% zoom and high contrast), you don't ask "is contrast sufficient?" — you ask "can Jordan find the 'continue reading' button at 200% zoom when three articles are competing for attention?"
+
+## When to Use
+
+- **After the fix round** — the design-builder has addressed findings from critic, accessibility-reviewer, and heuristic-evaluator. Now validate that the fixes work and no new issues were introduced
+- **Before verification-before-shipping** — synthetic testing feeds directly into the persona walkthrough in the verification report
+- **When the design-critic flags persona coverage gaps** — if the critique says "unclear whether Persona X can complete Task Y," run a synthetic test to find out
+- **When the team is unsure about a flow** — synthetic testing turns "I think this works for screen reader users" into "here's exactly where a screen reader user would get stuck"
+
+## Process
+
+### Step 1: Gather Test Context
+
+Before testing, assemble:
+- **Personas** from `inclusive-personas` (via `design-state.md`)
+- **Key tasks** from the design brief — the things the design must enable
+- **The build** — test the actual implementation, not the spec
+- **Assistive technology context** — for each persona, what tools they use and how (zoom level, screen reader, keyboard-only, switch access, etc.)
+
+### Step 2: Define Test Scenarios
+
+For each key task in the brief, write a scenario that a persona would actually encounter. Scenarios are not "test case 1" — they are moments:
+
+**Format:**
+```
+SCENARIO: [Natural situation trigger]
+TASK: [What the persona is trying to accomplish]
+PERSONA: [Name] — [key ability context]
+SUCCESS: [What "done" looks like for this persona]
+```
+
+**Example:**
+```
+SCENARIO: Jordan is on the train home and wants to finish an article
+          they started yesterday.
+TASK: Find and continue a partially-read article.
+PERSONA: Jordan — low vision, uses 200% zoom, high contrast mode,
+         reads on a phone with one hand.
+SUCCESS: Jordan locates the article, picks up where they left off,
+         and the progress updates when they finish.
+```
+
+### Step 3: Walk Through as Each Persona
+
+For each scenario, simulate the persona's experience step by step. This is not "would this work?" — it is "let me try to do this the way [Persona] would."
+
+**For each step, document:**
+
+```
+STEP [N]: [What the persona does]
+USING: [Input method — touch, keyboard, screen reader, switch, etc.]
+SEES: [What the interface presents — at their zoom level, contrast
+       setting, screen size]
+THINKS: [What the persona would likely think or feel]
+RESULT: ✓ succeeds / ⚠ succeeds with difficulty / ✗ fails / ? unclear
+
+FINDING: [If ⚠, ✗, or ? — what went wrong and why]
+WHO IS AFFECTED: [This persona, and any others with similar needs]
+```
+
+**Critical rules for walking through:**
+1. **Stay in character** — if the persona uses a screen reader, evaluate what the screen reader would announce, not what the sighted experience looks like
+2. **Use their device** — if the persona reads on a phone at 200% zoom, evaluate at that zoom on a phone viewport
+3. **Include emotional state** — a stressed parent and a relaxed commuter approach the same interface differently. The scenario sets the emotional context
+4. **Test error paths** — what happens if the persona makes a mistake? Can they recover? How much does recovery cost them?
+5. **Note friction, not just failure** — a task that technically succeeds but requires 8 taps and 3 scrolls has a friction problem even if it "works"
+
+### Step 4: Cross-Persona Analysis
+
+After walking through all scenarios, look for patterns across personas:
+
+**Barrier matrix:**
+```
+| Task              | Jordan    | Priya     | Marcus    | [Persona] |
+|                   | (low vis) | (ESL)     | (motor)   |           |
+|-------------------|-----------|-----------|-----------|-----------|
+| Find article      | ⚠ zoom    | ✓         | ✗ target  | ...       |
+| Continue reading  | ✓         | ⚠ jargon  | ✓         | ...       |
+| Mark complete     | ✗ no fbk  | ✓         | ⚠ gesture | ...       |
+```
+
+**Pattern analysis:**
+- **Universal barriers** — issues that affect 2+ personas → likely a design problem, not an edge case
+- **Persona-specific barriers** — issues that affect only one persona → may need targeted fix or alternative path
+- **Friction hotspots** — steps where multiple personas struggle, even if they eventually succeed
+- **Emotional patterns** — where do personas feel confused, frustrated, or lost?
+
+### Step 5: Synthesise Findings
+
+Compile findings into a structured report (see "What You Deliver" below). Every finding must:
+- Name the specific persona affected
+- Describe the exact step where the issue occurs
+- Explain why it's a problem from the persona's perspective
+- Suggest a fix
+- Classify severity (Critical / Major / Minor)
+
+**Severity in synthetic testing:**
+| Severity | Definition |
+|----------|-----------|
+| **Critical** | Persona cannot complete the task at all |
+| **Major** | Persona completes the task but with significant difficulty, confusion, or emotional friction |
+| **Minor** | Persona completes the task but the experience is rougher than it should be |
+
+### Step 6: Feed Results Forward
+
+Synthetic testing results feed into two places:
+1. **design-builder** — if fixes are needed, dispatch the builder with specific findings
+2. **verification-before-shipping** — the persona walkthrough section of the verification report should reference synthetic test results, not guesswork
+
+## What You Deliver
+
+```markdown
+# Synthetic User Test Results: [Project Name]
+
+**Date:** [YYYY-MM-DD]
+**Build tested:** [what was tested]
+**Personas tested:** [list]
+**Tasks tested:** [list]
+
+## Summary
+[2-3 sentences: overall findings — who can use this, who can't,
+ and the biggest gap]
+
+## Scenario Results
+
+### Scenario 1: [Scenario name]
+**Persona:** [Name] — [context]
+**Task:** [what they're trying to do]
+**Result:** ✓ / ⚠ / ✗
+
+[Step-by-step walkthrough with findings]
+
+### Scenario 2: ...
+
+## Barrier Matrix
+
+| Task | [Persona 1] | [Persona 2] | [Persona 3] | ... |
+|------|-------------|-------------|-------------|-----|
+| ...  | ✓/⚠/✗      | ✓/⚠/✗      | ✓/⚠/✗      | ... |
+
+## Cross-Persona Patterns
+- **Universal barriers:** [issues affecting 2+ personas]
+- **Friction hotspots:** [steps with clustered difficulty]
+- **Emotional patterns:** [where confusion/frustration clusters]
+
+## Findings by Severity
+
+### Critical
+- [Persona] cannot [task] because [specific reason] → [Fix]
+
+### Major
+- [Persona] struggles with [task] at [step] because [reason] → [Fix]
+
+### Minor
+- [Persona] experiences friction at [step] because [reason] → [Fix]
+
+## Comparison: Pre-Fix vs Post-Fix
+[If this is a re-test after fixes, show what improved and what didn't]
+
+## Recommendation
+[Ship / Fix and re-test / Rethink flow for [persona]]
+```
+
+## Integration
+
+- **Runs after:** Fix round (design-builder has addressed critic, accessibility-reviewer, and heuristic-evaluator findings)
+- **Runs before:** `verification-before-shipping`
+- **Informed by:** `inclusive-personas`, `design-discovery` (brief), `design-state` (all decisions)
+- **Feeds into:** `verification-before-shipping` (persona walkthrough evidence), `design-builder` (if fixes needed), `design-debt-tracker` (deferred findings)
+- **Complements:** `usability-testing` (which plans tests with real people — synthetic testing validates before real testing begins)
+
+## The Difference from Usability Testing
+
+| | Synthetic User Testing | Usability Testing |
+|---|---|---|
+| **Who** | AI walks through as each persona | Real people use the interface |
+| **When** | After fix round, inside the pipeline | After shipping or during user research |
+| **Speed** | Minutes | Days to weeks |
+| **Catches** | Predictable barriers, flow breaks, friction | Unexpected behaviour, mental model mismatches, emotional reactions |
+| **Misses** | True surprises — things no persona model predicts | Nothing (but expensive and slow) |
+| **Value** | Closes the gap between build and validation without leaving the pipeline | Ground truth |
+
+Synthetic testing does not replace real usability testing. It makes real testing more efficient by catching the obvious issues first, so real participants encounter the design at its best — and surface the surprises only humans can find.

package/dist/skills/frontend/references/designpowers/vendor/skills/taste-feedback/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: taste-feedback
+description: "Use during the build phase to show the user intermediate visual output and ask for taste direction before the full build completes — enables mid-flight course correction so taste mismatches are caught early, not in review"
+---
+
+# Live Taste Feedback
+
+The standard Designpowers pipeline catches taste mismatches at critique — after the full build is done. That's expensive. A wrong colour palette discovered after 8 components are built means rebuilding all 8. This skill interrupts the build at strategic moments to show intermediate output and ask: "Is this heading in the right direction?"
+
+## When to Use
+
+- During `design-builder` execution, at natural visual checkpoints
+- When the build involves subjective aesthetic decisions (colour, typography, spacing, tone)
+- When this project's taste direction (`design-taste`) is ambiguous on the decision at hand
+- When the project is new and there's little explicit direction yet for this decision
+- When the design-lead's direction was based on interpretation, not explicit user instruction
+
+## Do Not Use When
+
+- The user is in auto mode and hasn't opted into taste checks
+- The build is purely structural (data models, API integration, routing)
+- This project's `design-taste` direction already settles this decision clearly
+- The user has explicitly said "just build it, I'll review at the end"
+
+## Process
+
+### Step 1: Identify Checkpoints
+
+Before the build begins, identify 2-4 moments where taste feedback is most valuable. More than 4 interruptions becomes annoying. Choose wisely.
+
+**High-value checkpoints:**
+
+| Checkpoint | Why It Matters | When to Show |
+|------------|---------------|-------------|
+| **Colour and typography applied** | The foundational visual layer — everything else builds on this | After the first component is styled |
+| **Layout structure visible** | Spatial relationships, density, whitespace | After the primary screen scaffold is built |
+| **First interaction implemented** | How the interface moves and responds | After the first stateful component works |
+| **Content integrated** | How real words look in the design | After content-writer's copy is in place |
+
+**Low-value checkpoints (avoid):**
+
+| Checkpoint | Why It's Low Value |
+|------------|-------------------|
+| Unstyled HTML structure | Nothing to react to aesthetically |
+| Individual component in isolation | Context-free judgement is unreliable |
+| After every small change | Interruption fatigue kills the creative flow |
+
+### Step 2: Prepare the Checkpoint
+
+At each checkpoint, capture the current state:
+
+1. **Take a screenshot** of the running output (or describe the visual state precisely if screenshots aren't available)
+2. **Identify the taste-sensitive decisions** visible in the current output
+3. **Prepare specific questions** — do not ask "does this look good?" (too vague)
+
+Good taste questions are specific and answerable:
+
+| Bad Question | Good Question |
+|-------------|--------------|
+| "Does this look good?" | "The heading is set in 32px Inter Medium — is that weight right, or do you want bolder/lighter?" |
+| "Any feedback?" | "The cards have 16px padding and 8px radius. Does this density feel right, or do you want more breathing room?" |
+| "Is this the right direction?" | "I went warm grey (#F5F3F0) for the background instead of pure white. Does this warmth match what you had in mind?" |
+
+### Step 3: Present the Checkpoint
+
+Show the user the intermediate state with targeted questions:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  TASTE CHECK  [1 of 3]
+  Phase: [e.g., "Colour & Typography"]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [Screenshot or detailed visual description]
+
+  DECISIONS VISIBLE:
+  • [Decision 1 — e.g., "Sage green (#8FAE8B) as primary"]
+  • [Decision 2 — e.g., "Space Grotesk for headings, Inter for body"]
+  • [Decision 3 — e.g., "Generous padding, low density"]
+
+  TASTE QUESTIONS:
+  1. [Specific question about a visible decision]
+  2. [Specific question about a visible decision]
+
+  Quick responses welcome:
+  • "Looks right" → continue building
+  • "Warmer/cooler/bolder/quieter" → adjust and continue
+  • "Stop — wrong direction" → pause build, discuss
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 4: Process the Response
+
+The user's response determines what happens next:
+
+| Response | Action | Taste Signal |
+|----------|--------|-------------|
+| "Looks right" / "Yes" / "Continue" | Resume building. No changes needed | Moderate positive — note in design-memory as confirmed direction |
+| Specific adjustment ("make it warmer") | Apply the adjustment, show confirmation, then continue | Strong — record the adjustment and the direction they moved from/to |
+| "Wrong direction" / "Stop" | Pause the build. Ask what feels off. This is the most valuable taste data | Very strong negative — record what was rejected and why |
+| Detailed feedback ("I like the type but the colour feels too muted") | Apply partial changes. Acknowledge what works, adjust what doesn't | Mixed signal — record both the positive and negative separately |
+| "Skip these checks" | Disable further taste checks for this build. Respect the preference | Meta-preference — they want to review at the end instead |
+
+### Step 5: Adjust and Confirm
+
+When the user requests a change:
+
+1. Make the adjustment
+2. Show the updated state briefly — do not re-present the full checkpoint
+3. Confirm: "Updated [what changed]. Continuing the build."
+4. Do not ask for re-approval unless the change was ambiguous
+
+If the change cascades (e.g., new colour palette affects multiple components already built):
+
+1. Flag the cascade: "This colour change will affect the 3 components already built. I'll update them all."
+2. Update everything before continuing
+3. Optionally show the cascaded result at the next checkpoint
+
+### Step 6: Record Taste Data
+
+After each checkpoint interaction, update taste signals:
+
+1. Record confirmed decisions as positive signals in `design-memory`
+2. Record adjustments with before/after — these are the richest taste data
+3. Record rejections as anti-pattern candidates
+4. Note the *direction* of adjustments — "wanted warmer", "wanted more contrast", "wanted tighter spacing" — these directional signals generalize across projects
+
+## Checkpoint Frequency
+
+Adapt based on user behaviour:
+
+| User Behaviour | Adjust To |
+|---------------|-----------|
+| Approves every checkpoint quickly | Reduce to 1-2 checkpoints — they trust the direction |
+| Gives detailed feedback at every checkpoint | Maintain 3-4 — they want to shape the output |
+| Says "skip" or seems impatient | Drop to 1 checkpoint or none — ask at the end |
+| Requests more checkpoints | Add checkpoints — they want more control |
+
+The system should learn this preference over time via `design-memory`.
+
+## Integration With Pipeline Modes
+
+| Mode | Behaviour |
+|------|-----------|
+| **Direct** | Taste checkpoints are shown naturally — they fit the approval flow |
+| **Auto** | Taste checkpoints are **disabled by default** in auto mode. The user chose speed. If the user opts in ("auto but check my taste"), enable minimal checkpoints (1-2 max) |
+
+## Integration
+
+- **Called by:** `design-builder` (at visual checkpoints during build), `using-designpowers` (can be enabled/disabled)
+- **Calls:** `design-memory` (to record taste signals from feedback)
+- **Reads from:** Taste profile (to determine checkpoint frequency and known preferences), `design-state.md` (for current decisions)
+- **Pairs with:** `design-memory`, `ui-composition`, `designpowers-critique`
+
+## Anti-Patterns
+
+| Pattern | Why It Fails |
+|---------|-------------|
+| Asking "does this look good?" | Too vague. The user can't give actionable feedback without specific questions |
+| Checking after every change | Interruption fatigue. 2-4 checkpoints per build, maximum |
+| Showing unstyled output | There's nothing to react to. Wait until visual decisions are visible |
+| Ignoring "skip" signals | If the user wants to review at the end, respect that. Don't force mid-flight checks |
+| Not recording feedback | Every checkpoint interaction is taste data. If you don't record it, you'll ask the same questions next project |
+| Presenting in auto mode without consent | Auto mode means "don't interrupt me." Only show taste checks if the user explicitly opted in |
+| Asking about non-visual decisions | "Is this the right React component pattern?" is not a taste question. Keep checks visual and aesthetic |

package/dist/skills/frontend/references/designpowers/vendor/skills/taste-report/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: taste-report
+description: "Use when the user wants to see how they design — \"what's my taste\", \"show me my taste report\", \"how do I decide\", \"what are my patterns\", or periodically as the personal profile matures. Generates a longitudinal, reflective report from the PERSONAL taste profile (design-memory) — recurring moves, tells, evolution, blind spots — that helps a designer understand their own instincts. Personal layer only: it never reports client-specific signals from any project's DESIGN.md"
+---
+
+# Taste Report
+
+A taste report turns the personal taste profile from a lookup table into a mirror. `design-memory` accumulates a designer's portable instincts over many projects; this skill reads that accumulation and reflects it back as something the designer can actually learn from — *how you decide, what you reach for, what you reject, and how that's changed.* It's the moment the system stops just remembering your taste and starts helping you see it.
+
+## Scope: Personal Layer Only
+
+This report describes the **portable** taste in `~/.designpowers/taste-profile.md` — the instincts that travel with the designer regardless of client. It **must not** include client- or project-specific signals (the contents of any project's `DESIGN.md`). A client's required teal accent is that client's taste, not the designer's. If the personal profile is clean (it should be — `design-memory`'s Promotion Gate keeps client specifics out), this is automatic. If you notice client-bound entries that leaked into the personal profile, flag them as contamination rather than reporting them as the designer's taste.
+
+## When to Use
+
+- The user asks: "what's my taste?", "how do I design?", "show me my patterns", "what do I always do?"
+- Periodically, as the profile matures — offer it after a project's retrospective once the profile has **3+ projects** of history (below that, there isn't enough signal; say so).
+- When a designer wants to articulate their own style — for a portfolio, a team, a client pitch.
+
+## What the Report Contains
+
+Read `~/.designpowers/taste-profile.md` and the project history, then synthesise — don't just reformat the tables. Look for the patterns *across* entries that the designer might not see themselves.
+
+```markdown
+# How You Design — Taste Report
+_Generated [date] · based on [N] projects · [X] strong opinions, [Y] soft patterns_
+
+## In one line
+[The single sharpest characterisation of their taste. e.g. "You're a restraint-first
+designer who earns every accent and trusts whitespace to do the work."]
+
+## How you decide
+[3-5 observations about their decision-making, each with evidence from the profile.
+Not what they like — HOW they choose. e.g.:
+- "You subtract before you add — your overrides almost always remove an element
+   rather than restyle it (4 of 5 recorded overrides)."
+- "You decide colour last. Type and spacing are settled before accent appears."]
+
+## What you reach for
+[Recurring moves — the defaults they return to across projects. The strong opinions
+and confirmed soft patterns, framed as instincts not rules.]
+
+## What you reject
+[The anti-patterns, synthesised into a point of view. e.g. "You reject anything that
+performs friendliness — confetti, mascots, exclamation marks, skeleton 'delight'."]
+
+## How your taste is evolving
+[Movement over time from the project history. What's hardened from soft to strong,
+what you've changed your mind about, what's newly appearing. e.g. "Your tolerance
+for density has risen — early projects favoured sparse layouts, recent ones trust
+the user with more on screen."]
+
+## Possible blind spots
+[Gentle, honest. Tendencies that could become ruts, or places the profile is thin.
+e.g. "Every project leans editorial-serif for personality — worth testing whether
+that's taste or habit." Frame as questions, not judgements.]
+
+## Where the signal is thin
+[What the profile doesn't yet know — areas with little evidence, so the designer
+knows what's well-established vs. a guess. Honesty about confidence.]
+```
+
+## How to Write It Well
+
+1. **Synthesise, don't transcribe.** The value is in patterns *across* entries — "you always subtract," "you decide colour last" — not in re-listing the table rows. If you're just reformatting the profile, you haven't done the work.
+2. **Every claim cites evidence.** Tie each observation to specific projects, overrides, or repeated decisions in the profile. No evidence, no claim — this is `design-memory`, and the same "evidence over claims" rule applies.
+3. **Describe decision-making, not just preference.** "Prefers muted palettes" is a lookup. "Decides colour last, after structure is settled" is insight. Reach for the second.
+4. **Be honest about confidence and thinness.** Distinguish strong, well-evidenced patterns from thin ones. Don't manufacture a richer picture than the data supports.
+5. **Blind spots are a gift, not a verdict.** Surface ruts and gaps gently, as questions. The goal is self-awareness, never a grade.
+6. **Stay in the personal layer.** If a "preference" is really one client's brand requirement, it does not belong here.
+
+## Integration
+
+- **Reads from:** `~/.designpowers/taste-profile.md` and its project history (via `design-memory`)
+- **Never reads:** any project's `DESIGN.md` as personal taste (that's client taste — see `design-md`)
+- **Offered after:** `design-retrospective`, once the profile has enough history
+- **Pairs with:** `design-memory` (the store), `design-taste` (per-project calibration)
+- **Produces:** a report for the user — not a profile edit. It reflects; it does not rewrite the profile.

package/dist/skills/frontend/references/designpowers/vendor/skills/token-architecture/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: token-architecture
+description: "Use when building or restructuring design token systems — global tokens, semantic tokens, component tokens, naming conventions, theming, and multi-platform token distribution"
+---
+
+# Token Architecture
+
+Design tokens are the single source of truth for visual decisions. They bridge design intent and code. This skill structures how tokens are named, layered, and distributed.
+
+## When to Use
+
+- When starting a new design system
+- When `design-system-alignment` identifies inconsistency
+- When adding theming (dark mode, brand variants)
+- When shipping across web, iOS, and Android
+
+## The Three-Layer Model
+
+### Layer 1: Global Tokens (the palette)
+Raw values. Named by what they are, not what they do.
+```
+--color-green-500: #2D6B4F;
+--space-4: 16px;
+--radius-md: 12px;
+```
+These never appear in component CSS.
+
+### Layer 2: Semantic Tokens (the meaning)
+Map global tokens to roles. Named by what they do.
+```
+--color-surface: var(--color-green-100);
+--color-text-primary: var(--color-green-900);
+--color-accent: var(--color-green-500);
+```
+Theming happens here — dark mode swaps semantic mappings, not global values.
+
+### Layer 3: Component Tokens (the specifics)
+Map semantic tokens to component contexts. Optional but valuable at scale.
+```
+--button-bg: var(--color-accent);
+--card-bg: var(--color-surface);
+```
+
+## Naming Convention
+
+`--{category}-{property}-{variant}-{state}`
+
+Categories: color, space, font, radius, shadow, motion. Never use hex values in names or ambiguous abbreviations.
+
+## Theming
+
+Dark mode is a semantic token remap:
+```css
+[data-theme="dark"] {
+  --color-surface: var(--color-grey-900);
+  --color-text-primary: var(--color-grey-100);
+}
+```
+Global tokens stay. Semantic tokens swap. Component tokens inherit.
+
+## Accessibility
+
+- Always define foreground/background pairs together and verify AA contrast
+- Motion tokens must include `--motion-duration-none: 0ms` for reduced-motion
+
+## What You Deliver
+
+- Token file (CSS custom properties, JSON, or both) with all three layers
+- Naming convention document
+- Theme variants if applicable
+
+## Integration
+
+- **Informed by:** `design-lead`, `ui-composition`
+- **Feeds into:** `design-builder`, `design-system-alignment`

package/dist/skills/frontend/references/designpowers/vendor/skills/ui-composition/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ui-composition
+description: "Use when building layouts, choosing colours, setting typography, establishing visual hierarchy, designing responsive behaviour, or making any visual design decision — ensures every visual choice serves both aesthetics and accessibility"
+---
+
+# UI Composition
+
+Visual design is where intent becomes tangible. Every colour, every spacing decision, every typographic choice either includes or excludes people. This skill ensures visual decisions are principled, systematic, and inclusive.
+
+## When to Use
+
+- Designing screen layouts or page structures
+- Choosing or refining colour palettes
+- Setting typography systems
+- Establishing spacing and grid systems
+- Designing for responsive breakpoints
+- Creating or modifying visual hierarchy
+- Designing dark mode or high contrast variants
+
+## Process
+
+### Step 1: Reference the Foundation
+
+Before making visual decisions, confirm you have:
+- Design brief or strategy (from earlier phases)
+- Personas (especially ability spectrum considerations)
+- Existing design system (invoke `design-system-alignment` if one exists)
+
+### Step 2: Layout and Structure
+
+**Grid system:**
+- Define columns, gutters, and margins
+- Ensure the grid adapts across breakpoints (mobile, tablet, desktop)
+- Test that content reflows sensibly when zoomed to 200%
+
+**Visual hierarchy:**
+- Establish a clear reading order that works both visually and in the DOM
+- Ensure the hierarchy communicates through structure, not colour alone
+- Verify that removing all colour still leaves a readable, navigable page
+
+**Spacing system:**
+- Use a consistent spacing scale (e.g., 4px base)
+- Ensure touch targets are at least 44x44px
+- Provide adequate spacing between interactive elements to prevent accidental activation
+
+### Step 3: Colour
+
+**Palette construction:**
+- Define primary, secondary, neutral, and semantic colours (success, warning, error, info)
+- Every colour pairing must meet WCAG AA contrast ratios minimum (4.5:1 for text, 3:1 for large text and UI components)
+- Target WCAG AAA (7:1) where feasible
+
+**Colour independence:**
+- Never convey information through colour alone
+- Always pair colour with text labels, icons, or patterns
+- Test with simulated colour blindness (protanopia, deuteranopia, tritanopia)
+
+**Dark mode / high contrast:**
+- If applicable, design dark mode as a first-class experience, not an afterthought
+- Ensure all contrast ratios hold in both modes
+- Respect `prefers-color-scheme` and `prefers-contrast` media queries
+
+### Step 4: Typography
+
+**Type scale:**
+- Define a modular scale with clear hierarchy (heading levels, body, caption, label)
+- Base body size: minimum 16px (1rem)
+- Line height: 1.5 for body text, 1.2-1.3 for headings
+
+**Readability:**
+- Line length: 45-75 characters for body text
+- Paragraph spacing: at least 1.5x the font size
+- Avoid justified text (ragged right is more readable for most people)
+- Ensure text can be resized to 200% without loss of content or functionality
+
+**Font selection:**
+- Prioritise legibility over personality
+- Ensure the chosen font has distinct characters for I, l, 1 and O, 0
+- Provide fallback fonts in the same classification
+
+### Step 5: Responsive Design
+
+Design for these breakpoints (adjust to project needs):
+- **Mobile** (320-480px): single column, stacked layout, thumb-reachable interactions
+- **Tablet** (481-1024px): flexible layout, touch and pointer support
+- **Desktop** (1025px+): multi-column, keyboard and pointer optimised
+
+At every breakpoint:
+- Content priority remains correct
+- Touch targets remain adequate
+- Text remains readable without horizontal scrolling
+- No information is hidden that was visible at other breakpoints (unless intentionally progressive)
+
+### Step 6: Document Decisions
+
+For each visual decision, document:
+- **What:** the decision made
+- **Why:** how it serves the design principles and personas
+- **Accessibility:** how it meets inclusive design requirements
+
+## Integration
+
+- **Called by:** `writing-design-plans` (as part of plan execution)
+- **Pairs with:** `design-system-alignment` (for consistency), `cognitive-accessibility` (for visual load), `adaptive-interfaces` (for user preferences)
+- **Reviewed by:** `designpowers-critique`
+
+## Quick Reference: Accessibility Minimums
+
+| Element | Requirement |
+|---------|------------|
+| Text contrast | 4.5:1 (AA) or 7:1 (AAA) |
+| Large text contrast | 3:1 minimum |
+| UI component contrast | 3:1 against adjacent colours |
+| Touch target | 44x44px minimum |
+| Focus indicator | Visible, 3:1 contrast against adjacent |
+| Text resize | Content usable at 200% zoom |
+| Colour alone | Never the sole indicator of state or meaning |