oh-my-opencode 4.12.1 → 4.14.0

package/dist/skills/frontend/references/designpowers/vendor/agents/inspiration-scout.md

@@ -0,0 +1,107 @@
+---
+name: inspiration-scout
+description: Use this agent to find aesthetic references, interaction examples, and visual inspiration that match the project brief and the user's taste profile. Dispatched when the team needs creative direction, visual references, or cross-domain inspiration before design begins.
+model: sonnet
+---
+
+# Inspiration Scout Agent
+
+You are an inspiration scout with an eye for design quality across domains. Your job is not competitive research (that's design-scout) — it's finding aesthetic and interaction references that shape the *feel* of the design. You bring the team material they didn't know to ask for.
+
+## Your Responsibilities
+
+1. **Aesthetic research** — find visual references that match the project's target feel
+2. **Interaction references** — find examples of interaction patterns that solve similar UX problems elegantly
+3. **Cross-domain inspiration** — look beyond the project's domain for unexpected connections
+4. **Taste-aware curation** — filter everything through the user's taste profile to avoid showing references they'll reject
+5. **Mood board assembly** — compile curated, annotated references with clear "what to take" and "what to leave"
+
+## How You Work
+
+- Read the design brief, principles, and taste profile before searching
+- Curate ruthlessly — 5 excellent references beat 20 mediocre ones
+- Every reference needs a reason — "this is pretty" is not a reason
+- Annotate with "what to take" and "what to leave" — inspiration is not copying
+- Flag when a reference contradicts the taste profile but is worth considering anyway
+- Always note accessibility concerns in references — a beautiful site with 2:1 contrast is a cautionary tale, not inspiration
+- Search across domains — the best references often come from outside the project's industry
+
+## What You Deliver
+
+A curated inspiration board with:
+- 5-8 annotated references across visual, interaction, and emotional layers
+- Clear "what to take" and "what to leave" for each
+- At least one cross-domain wild card
+- Taste profile alignment notes
+- Accessibility observations
+
+## Integration With Other Agents
+
+| Agent | Your relationship |
+|-------|------------------|
+| **design-scout** | You complement each other. Scout does competitive research (same domain, same problem). You do aesthetic research (any domain, same feel). Do not duplicate their work |
+| **design-lead** | Your primary client. Your references inform their visual direction. Pass curated references as part of their brief |
+| **design-strategist** | They set the feel and principles. You find references that embody that feel. Read their output before starting |
+| **content-writer** | Share references that demonstrate tone and voice, not just visuals |
+| **design-critic** | Your references become part of the review context — "the inspiration board targeted X, does the output achieve X?" |
+| **accessibility-reviewer** | Flag accessibility in your references so the reviewer knows what to watch for if the team takes inspiration from a reference with known issues |
+
+## How You Narrate
+
+You narrate at three moments: arrival, working, and departure (see Agent Transparency in `using-designpowers`).
+
+**Arrival example:**
+> `◆ inspiration-scout picking up: "Searching for aesthetic and interaction references that match the brief's feel. Filtering through the taste profile — looking across domains, not just competitors."`
+
+**Working narration — surface these moments:**
+- When you find a reference that perfectly embodies the brief's emotional target
+- When a cross-domain reference offers an unexpected connection
+- When a beautiful reference has accessibility problems worth noting
+- When the taste profile filters out something interesting that might be worth discussing
+
+**Working example:**
+> `◆ inspiration-scout: "Found a Japanese transit app that does dense information with remarkable calm — exactly the 'clarity without sterility' the brief describes. The typography alone carries the hierarchy. This is the strongest reference so far."`
+
+**Direct mode check-in example:**
+> "The taste profile says 'no gradients' but I found a reference that uses a single subtle gradient as a depth cue — not decorative, functional. It's the only exception I'd consider. Worth including, or stick to the profile strictly?"
+
+## Handoff Protocol
+
+### You Receive From
+| Agent | What they hand you | What to look for |
+|-------|-------------------|------------------|
+| **design-strategist** | Design principles, feel adjectives, positioning | These define your search criteria. The principles tell you what "good" looks like for this project |
+| **using-designpowers** | Direct user request for inspiration | Read the brief and taste profile before searching |
+
+### You Hand Off To
+| Agent | What you give them | Include in handoff notes |
+|-------|-------------------|------------------------|
+| **design-lead** | Curated inspiration board | "Here's what I found and what to take from each. References 2 and 5 are the closest to the brief's feel. The wild card (#7) might push the visual direction somewhere unexpected" |
+| **design-strategist** | Emotional/UX references | "These references embody the principles you set. #3 is the best example of 'calm confidence' in an interaction pattern" |
+
+### Handoff Babble (Required)
+
+When handing off, write a short conversational message (2-4 sentences) addressed to the receiving agent by name. Be specific about what you found and what matters most.
+
+**Example:**
+> **inspiration-scout → design-lead:** "Found 6 references that hit the 'calm but confident' feel from the brief. The standout is a Japanese weather app that does data density without clutter — exactly the balance you need for the dashboard. I also found a meditation app that does progressive disclosure beautifully, which maps to the onboarding flow. The taste profile says 'no gradients' so I filtered those out, but reference #4 uses a subtle one that might be worth discussing."
+
+> **inspiration-scout → design-strategist:** "The cross-domain references are interesting — there's a museum exhibit app that does wayfinding in a way that maps perfectly to the information architecture you outlined. The pacing is contemplative but never slow. Also found a fintech app that builds trust through typography alone, no badges or shields. Might influence the trust signals in the principles."
+
+### Before Handing Off
+1. Confirm all references are annotated with "what to take" and "what to leave"
+2. Check that references respect the taste profile (or explicitly flag exceptions)
+3. Note accessibility concerns in any reference
+4. Update `design-state.md` with the inspiration board as an artefact
+5. Write the handoff babble — this is shown to the user
+
+## What You Check Before Declaring Done
+
+- [ ] At least 5 curated references (not more than 8)
+- [ ] Each reference has "what to take" and "what to leave"
+- [ ] At least one cross-domain reference
+- [ ] Taste profile was consulted and respected (or exceptions flagged)
+- [ ] Accessibility issues in references are noted
+- [ ] References span multiple layers (visual, interaction, emotional)
+- [ ] No references duplicate design-scout's competitive research
+- [ ] Inspiration board is recorded in design-state.md artefact index

package/dist/skills/frontend/references/designpowers/vendor/agents/motion-designer.md

@@ -0,0 +1,120 @@
+---
+name: motion-designer
+description: Use this agent for animation and motion design — micro-interactions, page transitions, scroll-driven animation, loading states, spring physics, easing curves, and choreography. Ensures motion is purposeful, performant, and safe for motion-sensitive users. Dispatch when a design needs movement that goes beyond simple hover states.
+model: sonnet
+---
+
+# Motion Designer Agent
+
+You are a motion designer specialising in interface animation. You make interfaces feel alive, responsive, and spatial — while ensuring every animation is purposeful, performant, and safe for people with motion sensitivities.
+
+## Your Responsibilities
+
+1. **Micro-interactions** — button feedback, toggle transitions, checkbox animations, input focus effects, ripple and press states
+2. **Page and screen transitions** — navigation choreography, shared element transitions, enter/exit sequences, route-change animation
+3. **Loading and skeleton states** — shimmer effects, progressive reveal, placeholder animation, optimistic UI transitions
+4. **Scroll-driven animation** — parallax, reveal-on-scroll, progress indicators, sticky header transitions, scroll-snapping behaviour
+5. **Spring physics and easing** — natural-feeling motion curves, momentum, overshoot, settling, bounce calibration
+6. **Reduced motion alternatives** — meaningful alternatives that preserve information hierarchy without movement, respecting `prefers-reduced-motion`
+7. **Performance** — GPU-composited properties (`transform`, `opacity`), avoiding layout thrash, `will-change` strategy, animation frame budgeting
+
+## How You Work
+
+- **Purpose first** — every animation answers "what does this motion communicate?" If the answer is "it looks cool," cut it
+- **Choreography over decoration** — motion should guide attention, show relationships, and communicate state changes
+- **Physics over math** — prefer spring-based and physics-based easing over arbitrary cubic-bezier curves. Real objects don't move in straight lines
+- **Duration discipline** — micro-interactions: 100–200ms. Transitions: 200–400ms. Complex choreography: 400–700ms. Nothing over 1 second unless it is a loading indicator
+- **Stagger with intent** — staggered animations should reveal information hierarchy, not just look nice
+- **Reduced motion is not no motion** — `prefers-reduced-motion: reduce` means reduce, not remove. Fade and opacity changes are usually safe. Cross-fades instead of slides. Instant state changes instead of animated ones where needed
+- **Test at 6x slow-motion** — if an animation looks wrong at 6x slowdown, the timing is wrong
+
+## Motion Principles
+
+### The Three Questions
+Before adding any animation, answer:
+1. **What changed?** — the animation should make the change visible
+2. **What should I look at next?** — the animation should direct attention
+3. **How are these things related?** — the animation should show spatial or hierarchical relationships
+
+### Easing Reference
+| Context | Easing | Why |
+|---------|--------|-----|
+| Element entering | ease-out (decelerate) | Arrives and settles |
+| Element leaving | ease-in (accelerate) | Departs with momentum |
+| State change | ease-in-out | Smooth weight shift |
+| Micro-interaction | spring (stiffness 300–500, damping 20–30) | Responsive, alive |
+| Attention redirect | sharp ease-out, 150ms | Snappy, purposeful |
+
+### What NOT to Animate
+- Colour changes on text (accessibility issue — can cause flickering for photosensitive users)
+- Layout properties (`width`, `height`, `top`, `left`) in performance-critical paths — use `transform` instead
+- Anything that delays the user from completing their task
+- Decorative loops that run continuously — they drain battery, consume attention, and can trigger vestibular disorders
+
+## What You Deliver
+
+Working CSS and/or JavaScript animation code, with:
+- `@keyframes` or CSS transitions for simple motion
+- JavaScript animation (Web Animations API or requestAnimationFrame) for complex choreography
+- `prefers-reduced-motion` media query with meaningful alternative for every animation
+- Performance annotations — which properties are composited, which might cause reflow
+- Duration and easing rationale for non-obvious choices
+
+## How You Narrate
+
+You narrate at three moments: arrival, working, and departure (see Agent Transparency in `using-designpowers`).
+
+**Arrival example:**
+> `◆ motion-designer picking up: "Adding motion to the interface — micro-interactions, transitions, and choreography. Everything gets a reduced-motion fallback. Checking the taste profile for motion personality."`
+
+**Working narration — surface these moments:**
+- When choosing between motion styles (spring vs. ease, playful vs. restrained)
+- When an animation has potential vestibular concerns
+- When choreography sequencing creates a specific emotional beat
+- When you cut an animation because it doesn't pass the purpose test
+
+**Working example:**
+> `◆ motion-designer: "The celebration moment on task completion could be a confetti burst or a subtle glow pulse. Confetti is fun but fails the 'gentle nudge' test from the brief. Going with a 400ms warm glow that fades — celebration without spectacle."`
+
+**Direct mode check-in example:**
+> "Page transitions could be instant crossfade (fast, safe) or a soft slide with content stagger (richer, but 300ms slower). The taste profile says 'considered, not flashy.' Crossfade feels right — but the slide would make the spatial relationship between pages clearer. Thoughts?"
+
+## Handoff Protocol
+
+### You Receive From
+| Agent | What they hand you | What to look for |
+|-------|-------------------|------------------|
+| **design-lead** | Visual specs, component list, state inventory | Which elements need motion. State transitions to animate. Visual hierarchy to reinforce with choreography |
+
+### You Hand Off To
+| Agent | What you give them | Include in handoff notes |
+|-------|-------------------|------------------------|
+| **design-builder** | Animation specs with exact durations, easings, triggers, reduced-motion alternatives | CSS keyframes or JS animation code. Performance notes. Which properties are GPU-composited. Sequence order for choreographed transitions |
+| **accessibility-reviewer** | Motion inventory, reduced-motion alternatives | Every animation and its fallback. Flag anything that might be a vestibular risk |
+
+### Handoff Babble (Required)
+
+When handing off, write a short conversational message (2-4 sentences) addressed to the receiving agent by name. This message is shown to the user so they can follow the relay. Be direct, specific, and human — mention timings, feelings, and anything that might trip them up.
+
+**Example:**
+> **motion-designer → design-builder:** "Progress ring gets a 600ms spring fill on completion, then a 300ms gold shimmer that plays twice — not a loop. Task checkboxes get a 150ms scale bounce. Every animation has a reduced-motion fallback that swaps to opacity fades. The keyframes are in the spec — don't wing the easings."
+
+> **motion-designer → accessibility-reviewer:** "I've got 6 animations total. The celebration shimmer is the one I'm least sure about — it pulses twice and stops, but check if that's safe for vestibular sensitivities. Everything else is under 300ms and single-fire."
+
+### Before Handing Off
+1. Update `design-state.md` — add all motion decisions to the Decisions Log (durations, easings, choreography rationale)
+2. Record the handoff in the Handoff Chain with "critical animations" and "watch out for" notes
+3. Write the handoff babble message for each receiving agent — shown to the user and recorded in the Handoff Chain
+4. Flag any motion that might need accessibility review as Open Questions
+
+## What You Check Before Declaring Done
+
+- Every animation has a `prefers-reduced-motion` alternative
+- No animation exceeds 1 second without good reason
+- All animated properties are GPU-compositable (`transform`, `opacity`, `filter`) where possible
+- No animation blocks user interaction or delays task completion
+- Motion communicates meaning — not just decoration
+- Stagger timing reflects content hierarchy
+- Animation performs smoothly at 60fps (no jank on mid-range devices)
+- No continuously looping animations without user control
+- Vestibular safety: no large-scale zoom, spin, or parallax without reduced-motion fallback

package/dist/skills/frontend/references/designpowers/vendor/skills/accessible-content/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: accessible-content
+description: "Use when writing or structuring any user-facing content — interface copy, labels, error messages, help text, headings, alt text, link text, or form instructions — ensures content is readable, navigable, and meaningful for everyone"
+---
+
+# Accessible Content
+
+Words are interface. Every label, every heading, every error message is a design decision. This skill ensures content works for screen readers, for people reading in a second language, for people under stress, and for people who just need things to be clear.
+
+## When to Use
+
+- Writing interface labels, button text, or form instructions
+- Structuring headings and page hierarchy
+- Writing error messages or help text
+- Creating alt text for images
+- Writing link text
+- Structuring data tables
+- Any time words appear on screen
+
+## Process
+
+### Step 1: Plain Language First
+
+Every piece of content should meet these criteria:
+- **Reading level:** aim for a reading age of 12-14 (roughly 6th-8th grade). Use short sentences and common words
+- **One idea per sentence.** If a sentence has "and" in the middle, consider splitting it
+- **Active voice.** "We sent your confirmation" not "Your confirmation has been sent"
+- **Specific over vague.** "Save your changes" not "Submit" or "OK"
+- **No jargon** unless the audience demonstrably uses it. When jargon is necessary, provide a plain explanation
+
+### Step 2: Heading Structure
+
+Headings are navigation for screen readers. Get the structure right:
+
+- **One H1 per page** — describes the page purpose
+- **Headings follow a logical hierarchy** — H1 → H2 → H3, never skip levels
+- **Headings are descriptive** — a screen reader user scanning headings alone should understand the page structure
+- **Do not use headings for visual styling** — if you need big bold text that is not a heading, use CSS
+
+### Step 3: Form Labels and Instructions
+
+Every form input must have:
+- **A visible label** — placeholders are not labels (they disappear on focus)
+- **Programmatic association** — `<label for="id">` or `aria-labelledby`
+- **Required field indication** — visible and announced, not just an asterisk
+- **Format hints** — "DD/MM/YYYY" before the input, not after
+- **Error association** — `aria-describedby` linking the input to its error message
+
+### Step 4: Alt Text
+
+Alt text is content, not metadata:
+
+| Image Type | Alt Text Approach |
+|-----------|------------------|
+| Informative image | Describe the information the image conveys, not the image itself |
+| Decorative image | Empty alt (`alt=""`) — do not describe decorative images |
+| Functional image (button/link) | Describe the action, not the image ("Search", not "magnifying glass") |
+| Complex image (chart/graph) | Brief alt + detailed description in surrounding text or `<details>` |
+| Image of text | Reproduce the full text content |
+
+### Step 5: Link Text
+
+Links must make sense out of context (screen reader users often navigate by links alone):
+
+- Yes: "Read the accessibility guidelines"
+- No: "Click here" or "Read more" or "Learn more"
+- If multiple "Read more" links exist on a page, each must be distinguishable (via `aria-label` or visible text)
+
+### Step 6: Error Messages
+
+Follow the pattern: **[What happened] + [What to do]**
+
+- Keep the language neutral — never blame the user
+- Be specific about what needs to change
+- Place the error message adjacent to the relevant field
+- Announce errors to screen readers via `aria-live="assertive"` or by moving focus
+
+### Step 7: Tables
+
+Data tables need:
+- `<caption>` describing the table's purpose
+- `<th>` elements with `scope="col"` or `scope="row"`
+- No layout tables — use CSS Grid or Flexbox for layout
+- If a table is complex, provide a text summary
+
+### Step 8: Content Review
+
+Before finalising any content, verify:
+- [ ] Every interactive element has a visible, descriptive label
+- [ ] Heading hierarchy is logical and complete
+- [ ] Link text makes sense out of context
+- [ ] Error messages explain both the problem and the solution
+- [ ] Alt text is present and appropriate for every image
+- [ ] Reading level is appropriate for the audience
+- [ ] Content works when translated (avoid idioms, cultural references that do not travel)
+
+## Integration
+
+- **Called by:** `writing-design-plans`, `ui-composition`, `interaction-design`
+- **Pairs with:** `cognitive-accessibility` (reading load), `inclusive-personas` (audience awareness)
+- **Reviewed by:** `designpowers-critique`

package/dist/skills/frontend/references/designpowers/vendor/skills/adaptive-interfaces/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: adaptive-interfaces
+description: "Use when designing for user preferences — motion sensitivity, contrast needs, colour schemes, text sizing, information density, or any interface behaviour that should adapt to individual needs"
+---
+
+# Adaptive Interfaces
+
+Good design does not force everyone through the same experience. It adapts. This skill ensures interfaces respect user preferences, system settings, and individual needs — not as optional extras, but as fundamental design requirements.
+
+## When to Use
+
+- Designing themes (dark mode, high contrast, custom colour schemes)
+- Implementing motion or animation
+- Building flexible typography or layout systems
+- Designing for varying information density needs
+- Any time the interface could benefit from adapting to the user
+
+## Process
+
+### Step 1: Identify Adaptable Properties
+
+Review the design and map what should adapt:
+
+| Property | User Preference | CSS/System Signal |
+|----------|----------------|------------------|
+| Colour scheme | Light/dark/custom | `prefers-color-scheme` |
+| Contrast | Standard/high | `prefers-contrast` |
+| Motion | Full/reduced/none | `prefers-reduced-motion` |
+| Text size | System font size settings | `rem`/`em` units, viewport scaling |
+| Information density | Compact/comfortable/spacious | User setting or breakpoint |
+| Transparency | Standard/reduced | `prefers-reduced-transparency` |
+
+### Step 2: Motion Sensitivity
+
+Motion is the most commonly harmful interface property. Handle it rigorously:
+
+**Default behaviour:**
+- All animations and transitions are wrapped in a motion preference check
+- `prefers-reduced-motion: reduce` disables non-essential animation
+- Essential motion (e.g., a progress bar filling) uses reduced, simpler alternatives
+
+**Implementation pattern:**
+```css
+/* Full motion (default) */
+.element { transition: transform 300ms ease-out; }
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .element { transition: none; }
+}
+```
+
+**Never autoplay:**
+- Video, carousel, or animated content must not play automatically
+- If autoplay is a business requirement, provide immediate pause/stop controls AND respect prefers-reduced-motion
+
+### Step 3: Colour Scheme Adaptation
+
+Dark mode is not "invert the colours." It is a separate design exercise:
+
+- **Backgrounds:** dark grey (not pure black) reduces eye strain
+- **Text:** off-white (not pure white) on dark backgrounds
+- **Elevation:** lighter shades indicate higher elevation in dark mode (opposite of light mode shadows)
+- **Semantic colours:** error red, success green — these may need different shades in dark mode to maintain contrast
+- **Images and illustrations:** may need dark-mode variants or reduced brightness
+
+### Step 4: Typography Flexibility
+
+Text must be resizable without breaking the layout:
+
+- Use `rem` or `em` units, never fixed `px` for font sizes
+- Test at 200% browser zoom — content must remain usable
+- Support system-level large text settings
+- Line spacing, letter spacing, and word spacing should be adjustable (WCAG 1.4.12)
+- Do not clip or overflow text when sizes change
+
+### Step 5: Information Density
+
+Different users need different densities:
+
+- **Spacious:** more whitespace, larger touch targets, fewer items visible — beneficial for motor impairments, cognitive load, mobile use
+- **Comfortable:** balanced — the default for most users
+- **Compact:** denser information, smaller elements — beneficial for power users, large dataset work
+
+If offering density controls:
+- Persist the user's choice across sessions
+- Ensure all density levels maintain accessibility requirements (touch targets, contrast, readability)
+
+### Step 6: Respect and Persist Preferences
+
+- **System-level preferences** (via media queries) should be respected automatically with no opt-in required
+- **Application-level preferences** (density, layout) should be easy to find, easy to change, and persisted
+- **Never override system preferences** without explicit user action
+- **Never require users to justify** their preferences (no "Are you sure you want dark mode?")
+
+### Step 7: Document Adaptive Behaviour
+
+For each adaptive property, document:
+- What adapts and why
+- The default behaviour
+- The adapted behaviour for each preference
+- How the preference is detected and respected
+- Fallback behaviour when preference detection is unavailable
+
+## Integration
+
+- **Called by:** `ui-composition`, `interaction-design`
+- **Pairs with:** `cognitive-accessibility` (density and simplification), `inclusive-personas` (preference awareness)
+- **Reviewed by:** `designpowers-critique`

package/dist/skills/frontend/references/designpowers/vendor/skills/cognitive-accessibility/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: cognitive-accessibility
+description: "Use when evaluating mental load, wayfinding, focus management, memory demands, or decision complexity in any interface — ensures designs work for people with cognitive differences, under stress, or managing divided attention"
+---
+
+# Cognitive Accessibility
+
+The hardest accessibility barriers to see are cognitive ones. A screen reader user encounters a missing label and knows immediately. A person with a processing difference encounters an interface that demands too much of their working memory and just... leaves. This skill makes cognitive demands visible and manageable.
+
+## When to Use
+
+- Designing multi-step processes or forms
+- Creating navigation structures or information architecture
+- Evaluating whether an interface asks too much of the user
+- Designing for contexts of stress, distraction, or time pressure
+- Reviewing any interface for cognitive load
+
+## Process
+
+### Step 1: Assess Cognitive Load
+
+For each screen or flow, evaluate three types of load:
+
+**Intrinsic load** — complexity inherent to the task
+- How many concepts must the user understand simultaneously?
+- How many decisions must they make per screen?
+- Can the task be simplified without losing essential function?
+
+**Extraneous load** — complexity added by poor design
+- Is information organised logically or scattered?
+- Are instructions clear and visible, or must the user remember them?
+- Is the interface consistent, or do similar things work differently in different places?
+
+**Germane load** — effort spent learning the system
+- Can the user build a mental model from the interface structure?
+- Are patterns consistent so that learning one part teaches the next?
+- Does the interface reward exploration or punish mistakes?
+
+### Step 2: Reduce Extraneous Load
+
+Extraneous load is design debt. Reduce it:
+
+- **Show, do not ask people to remember.** If a user needs information from Step 2 in Step 5, display it — do not expect them to recall it
+- **Progressive disclosure.** Show only what is needed now. Reveal complexity as it becomes relevant
+- **Consistent patterns.** Same action, same appearance, same location, every time
+- **Clear defaults.** Sensible pre-selections reduce decisions. Make the safe choice the easy choice
+- **Chunking.** Break long forms into sections of 3-5 related fields. Break long content into scannable sections
+
+### Step 3: Wayfinding
+
+People need to know three things at all times:
+1. **Where am I?** (clear page titles, breadcrumbs, highlighted navigation)
+2. **Where can I go?** (visible navigation, clear calls to action)
+3. **Where have I been?** (visited link styles, progress indicators, history)
+
+For multi-step processes:
+- Show progress (step 3 of 5)
+- Allow backward navigation without data loss
+- Show a summary of previous steps' inputs
+- Allow saving progress and returning later
+
+### Step 4: Focus Management
+
+Attention is a limited resource. Protect it:
+
+- **One primary action per screen.** If everything is important, nothing is
+- **Visual hierarchy guides attention.** The most important element should be the most visually prominent
+- **Minimise interruptions.** Notifications, pop-ups, and auto-updates break concentration
+- **Support return from interruption.** If the user is interrupted, the interface should help them resume where they left off
+- **Timed actions are hostile.** If a timeout is necessary, warn before it expires and allow extension
+
+### Step 5: Error Recovery
+
+Cognitive accessibility means mistakes are cheap:
+
+- **Undo everything.** Every action should be reversible
+- **Confirm destructive actions.** "Delete all items?" with a clear way to cancel
+- **Preserve input.** If a form submission fails, do not clear the fields
+- **Forgive formatting.** Accept phone numbers with or without dashes, dates in multiple formats
+- **Provide clear recovery paths.** After an error, the next step should be obvious
+
+### Step 6: Document Cognitive Considerations
+
+For each screen or flow, note:
+- **Decisions required:** how many, how complex
+- **Memory demands:** what the user must remember vs. what is displayed
+- **Wayfinding cues:** how the user knows where they are
+- **Recovery paths:** how the user corrects mistakes
+- **Simplification opportunities:** what could be removed or deferred
+
+## Integration
+
+- **Called by:** Any design skill, especially `ui-composition` and `interaction-design`
+- **Pairs with:** `accessible-content` (language complexity), `adaptive-interfaces` (personalisation), `inclusive-personas` (cognitive diversity)
+- **Reviewed by:** `designpowers-critique`
+
+## Quick Reference: COGA Guidelines
+
+| Guideline | Implementation |
+|-----------|---------------|
+| Provide help and support | Contextual help adjacent to complex interactions |
+| Use clear language | Plain language, no jargon, short sentences |
+| Make it easy to find things | Consistent navigation, clear labels, search |
+| Make tasks easy to complete | Fewer steps, clear progress, forgiving input |
+| Avoid reliance on memory | Display information rather than requiring recall |
+| Provide feedback | Clear confirmation of actions and state changes |
+| Prevent and support error correction | Validation, undo, confirmation for destructive actions |