oh-my-opencode 4.13.0 → 4.14.1

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/interaction-design/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: interaction-design
+description: "Use when designing states, transitions, animations, error handling, loading patterns, feedback, or any behaviour that responds to user action — ensures interactions are perceivable, operable, and inclusive"
+---
+
+# Interaction Design
+
+Interactions are promises. Every button says "click me and something will happen." Every loading spinner says "wait, it is coming." This skill ensures those promises are kept for everyone, regardless of how they interact with the interface.
+
+## When to Use
+
+- Designing component states (default, hover, active, focus, disabled, error)
+- Creating transitions or animations
+- Handling errors, empty states, or edge cases
+- Designing loading and progress patterns
+- Defining feedback mechanisms (success, warning, error confirmations)
+- Designing gesture or touch interactions
+
+## Process
+
+### Step 1: Map All States
+
+For every interactive element, define:
+
+| State | Visual | Screen Reader | Keyboard | Touch |
+|-------|--------|--------------|----------|-------|
+| Default | [appearance] | [announcement] | [behaviour] | [behaviour] |
+| Hover | [appearance] | n/a | n/a | n/a |
+| Focus | [appearance + focus ring] | [announcement] | [how to reach] | n/a |
+| Active/Pressed | [appearance] | [announcement] | [trigger key] | [gesture] |
+| Disabled | [appearance, not just greyed] | [announcement + reason] | [skip in tab order?] | [behaviour] |
+| Error | [appearance + message] | [announcement + guidance] | [focus moved?] | [behaviour] |
+| Loading | [appearance] | [live region update] | [interaction blocked?] | [behaviour] |
+| Success | [appearance] | [announcement] | [next focus target] | [behaviour] |
+
+### Step 2: Design Feedback Patterns
+
+Every user action deserves a response. Map the feedback:
+
+**Immediate feedback (< 100ms):**
+- Visual state change on interaction (button press, toggle flip)
+- Must be perceivable without relying on colour alone
+
+**Short wait feedback (100ms - 1s):**
+- Loading indicator or skeleton screen
+- ARIA live region announcement: "Loading..."
+
+**Long wait feedback (> 1s):**
+- Progress indicator with estimated time or progress percentage
+- Ability to cancel or navigate away
+- ARIA live region updates at intervals
+
+**Completion feedback:**
+- Clear success or error state
+- Screen reader announcement of outcome
+- Logical next focus target
+
+### Step 3: Error Handling
+
+Errors are not edge cases — they are guaranteed states. Design for them:
+
+1. **Prevention first** — inline validation, clear constraints, sensible defaults
+2. **Clear identification** — what went wrong, in plain language
+3. **Specific guidance** — what the person should do next
+4. **Accessible delivery** — errors announced to screen readers, focus moved to the error, not just a colour change
+5. **Recovery path** — preserve user input, allow correction without starting over
+
+Error message format: **[What happened] + [What to do about it]**
+- Yes: "That email address is already registered. Try signing in instead, or use a different email."
+- No: "Error: invalid input"
+
+### Step 4: Animation and Motion
+
+Animations serve a purpose or they serve nobody:
+
+**When to animate:**
+- To show a relationship between elements (a panel sliding in from its trigger)
+- To maintain spatial orientation (a page transition showing direction)
+- To provide feedback (a subtle bounce on a successful action)
+
+**When NOT to animate:**
+- Decoration without function
+- Anything that delays the user from completing their task
+- Anything that loops indefinitely
+
+**Inclusive motion:**
+- Respect `prefers-reduced-motion` — always provide a reduced or no-motion alternative
+- Keep durations short: 150-300ms for micro-interactions, 300-500ms for transitions
+- Avoid parallax, auto-playing video, flashing content (3 flashes per second maximum per WCAG)
+- Provide pause/stop controls for any animation longer than 5 seconds
+
+### Step 5: Gesture and Input Design
+
+If the design includes gesture interactions:
+- Every gesture must have a non-gesture alternative (button, keyboard shortcut)
+- Swipe actions must be discoverable without trial-and-error
+- Drag-and-drop must have a keyboard-accessible alternative
+- Touch targets: 44x44px minimum, with adequate spacing between targets
+
+### Step 6: Document the Interaction Spec
+
+For each interaction, document:
+- Trigger (what initiates the interaction)
+- Behaviour (what happens, step by step)
+- States (all states the element passes through)
+- Feedback (what the user perceives at each stage)
+- Accessibility (screen reader announcements, keyboard behaviour, motion reduction)
+
+## Integration
+
+- **Called by:** `writing-design-plans` (as part of plan execution)
+- **Pairs with:** `ui-composition` (visual states), `cognitive-accessibility` (interaction complexity), `accessible-content` (error messages)
+- **Reviewed by:** `designpowers-critique`
+
+## Red Flags
+
+| Flag | Response |
+|------|----------|
+| Component with only default and hover states | Map ALL states including focus, error, loading, disabled |
+| Animation without prefers-reduced-motion support | Add motion reduction. This is not optional |
+| Error state that only changes colour | Add text, icon, and screen reader announcement |
+| Gesture without alternative input method | Add keyboard and/or button alternative |

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/motion-choreography/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: motion-choreography
+description: "Use when designing animation sequences, page transitions, micro-interactions, loading states, or any motion that communicates meaning — ensures motion is purposeful, performant, and safe for motion-sensitive users"
+---
+
+# Motion Choreography
+
+Motion is communication. Every animation answers a question the user didn't know they had. If it doesn't answer one, cut it.
+
+## The Three Questions
+
+Before adding any animation:
+1. **What changed?** — the animation makes it visible
+2. **What should I look at next?** — directs attention
+3. **How are these related?** — shows spatial/hierarchical relationship
+
+Can't answer at least one? The animation is decoration. Cut it.
+
+## Duration Guide
+
+| Context | Duration |
+|---------|----------|
+| Micro-interaction (button, toggle) | 100-200ms |
+| State change (card expand, tab) | 200-300ms |
+| Screen transition | 250-400ms |
+| Complex choreography | 400-700ms total |
+
+Nothing over 1 second unless it's a loading indicator.
+
+## Easing Reference
+
+| Context | Easing |
+|---------|--------|
+| Entering | ease-out (decelerate) |
+| Leaving | ease-in (accelerate) |
+| State change | ease-in-out |
+| Micro-interaction | spring (stiffness 300-500) |
+
+## Stagger Patterns
+
+- 50-80ms delay between items
+- Maximum 5 items staggered, rest appear instantly
+- Follow reading order
+- Reveal hierarchy — important items first
+
+## Reduced Motion
+
+`prefers-reduced-motion: reduce` means reduce, not remove.
+
+| Standard | Reduced alternative |
+|----------|-------------------|
+| Slide in | Fade in |
+| Scale with bounce | Instant appearance |
+| Parallax scroll | Static |
+| Staggered reveal | Simultaneous fade |
+| Continuous pulse | Static state |
+
+**Every animation must have a reduced-motion alternative. No exceptions.**
+
+## What NOT to Animate
+
+- Text colour changes (photosensitive risk)
+- Layout properties in performance paths (use transform)
+- Anything that delays task completion
+- Decorative loops without user control
+
+## Performance
+
+Only animate: `transform`, `opacity`, `filter`. These are GPU-composited.
+
+## What You Deliver
+
+- Animation specs with durations, easings, triggers
+- Reduced-motion alternatives for every animation
+- Performance annotations
+- Sequence diagrams for complex choreography
+
+## Integration
+
+- **Informed by:** `design-lead`, `interaction-design`
+- **Feeds into:** `motion-designer` agent, `accessibility-reviewer`, `design-builder`

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/research-planning/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: research-planning
+description: "Use when user needs are unclear, assumptions need validation, or the design brief identifies gaps in understanding — plans what to learn, which methods to use, and from whom"
+---
+
+# Research Planning
+
+Research is how we replace assumptions with evidence. This skill structures what you need to learn before committing to a design direction.
+
+## When to Use
+
+- The design brief identifies unknowns about users, context, or behaviour
+- The team is making decisions based on assumptions rather than evidence
+- A design is being created for a new audience or unfamiliar context
+- Stakeholders disagree about user needs
+
+## Process
+
+### Step 1: Identify Knowledge Gaps
+
+Review the design brief and list:
+- What do we **know** about the people who will use this? (Evidence-backed)
+- What do we **assume**? (Believed but unverified)
+- What do we **not know**? (Acknowledged gaps)
+
+Present this to the user. Assumptions and unknowns become research questions.
+
+### Step 2: Frame Research Questions
+
+Convert gaps into answerable questions. Good research questions are:
+- **Specific** — "How do users with screen readers navigate multi-step forms?" not "Is the form accessible?"
+- **Observable** — focused on behaviour, not opinion
+- **Actionable** — the answer will change a design decision
+
+Aim for 3-5 research questions. More than that means you need to narrow scope.
+
+### Step 3: Select Methods
+
+Match methods to questions:
+
+| Question Type | Recommended Methods |
+|--------------|-------------------|
+| "What do people currently do?" | Journey mapping, diary studies, contextual inquiry |
+| "Why do people struggle with X?" | Usability testing, think-aloud protocols |
+| "What do people need?" | Interviews, jobs-to-be-done analysis |
+| "Which approach works better?" | A/B testing, preference testing, card sorting |
+| "How does our offering compare?" | Competitive analysis, heuristic evaluation |
+| "Who are we designing for?" | Persona development, ability spectrum mapping |
+
+### Step 4: Plan for Inclusion
+
+Every research plan must address:
+- **Participant diversity** — include people with disabilities, different ages, different technical literacy, different languages
+- **Method accessibility** — ensure research methods themselves are accessible (e.g., interview formats that work for people with communication differences)
+- **Situational contexts** — include scenarios of stress, distraction, low bandwidth, unfamiliar environments
+
+### Step 5: Write the Research Plan
+
+```markdown
+# Research Plan: [Topic]
+
+## Research Questions
+1. [Question]
+2. [Question]
+3. [Question]
+
+## Methods
+| Method | Questions Addressed | Participants | Timeline |
+|--------|-------------------|-------------|----------|
+| [Method] | Q1, Q2 | [Who and how many] | [When] |
+
+## Inclusion Considerations
+[How participant diversity and method accessibility will be ensured]
+
+## Expected Outputs
+[What deliverables this research will produce — personas, journey maps, findings report]
+
+## Decision Points
+[Which design decisions this research will inform]
+```
+
+Save to: `docs/designpowers/research/YYYY-MM-DD-<topic>-plan.md`
+
+### Step 6: User Review
+
+Present the plan. Confirm scope, methods, and timeline are realistic.
+
+## Integration
+
+- **Called by:** `design-discovery`
+- **Calls:** `inclusive-personas` (when persona development is a research output)
+- **Pairs with:** `design-strategy` (research informs strategy)
+
+## What This Skill Does NOT Do
+
+This skill plans research — it does not execute it. Execution happens with real people in the real world. The plan ensures that when research happens, it is structured, inclusive, and actionable.

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/responsive-patterns/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: responsive-patterns
+description: "Use when designing complex responsive layouts — breakpoint strategy, layout shifts, content reflow, responsive typography, container queries, and ensuring the experience works across the full device spectrum"
+---
+
+# Responsive Patterns
+
+Responsive design is not "make it fit on a phone." It is designing for every context — one-handed on a bus, zoomed to 200% on a desktop, on a tablet in sunlight.
+
+## When to Use
+
+- When `ui-composition` defines a layout that spans breakpoints
+- When the design-critic flags responsive issues
+- When building anything more complex than single-column
+
+## Breakpoint Strategy
+
+Content drives breakpoints, not devices. Do not use 768px because "that's tablet." Use the width where your content breaks.
+
+1. Start at 320px
+2. Widen slowly
+3. When the layout looks wrong — that's a breakpoint
+4. Name by behaviour, not device
+
+```css
+--bp-stack: 0;
+--bp-sidebar: 640px;
+--bp-columns: 900px;
+--bp-wide: 1200px;
+```
+
+## Content Priority Shifting
+
+At narrow widths, decide what gets:
+- **Kept** — essential for the task
+- **Collapsed** — behind a toggle
+- **Deferred** — lower in scroll order
+- **Hidden** — removed (last resort)
+
+Document these decisions.
+
+## Responsive Typography
+
+```css
+--font-size-body: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
+--font-size-h1: clamp(1.75rem, 1.5rem + 1.25vw, 2.5rem);
+```
+
+Body text minimum 16px. Line length 45-75 characters. At 200% zoom, no horizontal scroll (WCAG 1.4.10).
+
+## Container Queries vs Media Queries
+
+| Use case | Use |
+|----------|-----|
+| Page-level layout | `@media` |
+| Component adaptation | `@container` |
+
+## Touch Targets
+
+44x44px minimum at mobile. 8px minimum gap between adjacent targets.
+
+## Testing
+
+Test at: 320px, one pixel below each breakpoint, 200% zoom at 1280px, landscape phone, and real devices.
+
+## What You Deliver
+
+- Breakpoint definitions with rationale
+- Layout behaviour at each breakpoint
+- Content priority decisions
+- Typography scale with clamp() values
+- Touch target verification
+
+## Integration
+
+- **Informed by:** `ui-composition`, `design-discovery`
+- **Feeds into:** `design-builder`, `accessibility-reviewer`

package/packages/shared-skills/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.