oh-my-opencode 4.13.0 → 4.14.0

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

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

@@ -0,0 +1,199 @@
+---
+name: design-debate
+description: "Use when a design direction is uncertain, when the team could go multiple ways, or when the user wants to see competing approaches argued before committing — orchestrates structured debate between agents who advocate for different directions"
+---
+
+# Design Debate
+
+Good design decisions come from tension, not consensus. When agents converge too quickly, they optimise for agreement instead of the best answer. This skill creates productive conflict — agents argue for competing directions with real trade-offs, and the user decides.
+
+## When to Use
+
+- When the design-strategist identifies multiple viable directions
+- When the design-lead proposes a visual direction and alternatives exist
+- When the user says "I'm not sure which way to go" or "what are my options?"
+- When the design-critic recommends "rethink" — a debate can surface the better path
+- When a decision has significant downstream consequences (navigation pattern, layout model, interaction paradigm)
+- When the user explicitly asks for a debate: "debate this", "argue both sides", "what are the trade-offs?"
+
+## Do Not Use When
+
+- The decision is trivial (icon choice, exact padding value)
+- Accessibility requirements dictate the answer — there is nothing to debate
+- The user has already made up their mind — respect their direction
+- The brief clearly specifies the approach — follow it
+
+## Process
+
+### Step 1: Frame the Question
+
+Define the design question precisely. A debate without a clear question produces noise.
+
+Format:
+```
+DESIGN QUESTION: [Specific, answerable question]
+CONTEXT: [Brief context from design-state.md]
+CONSTRAINTS: [Non-negotiable requirements from brief, accessibility, taste profile]
+STAKES: [Why this decision matters — what it affects downstream]
+```
+
+**Example:**
+```
+DESIGN QUESTION: Should the onboarding flow use a multi-step wizard or a single scrollable page?
+CONTEXT: App for first-time pet owners, ages 25-45. Primary persona has mild anxiety about "doing it right."
+CONSTRAINTS: Must be completable in under 3 minutes. Must work on mobile. Must not require account creation upfront.
+STAKES: Sets the interaction pattern for all future multi-step flows in the app.
+```
+
+### Step 2: Assign Advocates
+
+Select 2-3 agents to argue for different directions. Each agent argues FOR their assigned position — they are advocates, not neutral analysts.
+
+| Role | What They Argue |
+|------|----------------|
+| **Advocate A** | The case for Direction A — strengths, evidence, personas it serves best |
+| **Advocate B** | The case for Direction B — strengths, evidence, personas it serves best |
+| **Advocate C** (optional) | A third direction, a hybrid, or a "neither — here's why" position |
+
+Assign agents based on their expertise:
+
+| Agent | Best suited to advocate for |
+|-------|---------------------------|
+| **design-strategist** | UX patterns, information architecture, user flow approaches |
+| **design-lead** | Visual directions, layout models, component architecture |
+| **content-writer** | Content strategy approaches, tone directions, naming conventions |
+| **motion-designer** | Interaction paradigms, feedback models, transition approaches |
+| **accessibility-reviewer** | The most inclusive option, cognitive load implications |
+| **design-scout** | Evidence-backed positions from competitive research |
+
+### Step 3: Run the Debate
+
+Each advocate delivers their argument in this format:
+
+```markdown
+## [Agent Name] argues for: [Direction]
+
+### The Case
+[2-3 paragraphs making the strongest possible argument for this direction.
+Be specific — reference the brief, personas, principles, and evidence.]
+
+### Who This Serves Best
+[Which personas benefit most and why]
+
+### Who This Serves Least
+[Which personas might struggle and why — be honest]
+
+### Trade-Offs
+[What you give up by choosing this direction]
+
+### Evidence
+[Research, patterns, competitive examples, or design principles that support this]
+```
+
+Rules for advocates:
+1. **Argue to win** — make the strongest case you can. Do not hedge
+2. **Be honest about weaknesses** — a strong argument acknowledges its trade-offs
+3. **Reference the brief** — ground arguments in the project's actual goals
+4. **Reference personas** — every argument must address who it helps and who it doesn't
+5. **No straw men** — do not weaken the opposing position to make yours look better
+
+### Step 4: Cross-Examination
+
+After all advocates present, each gets one round of rebuttal:
+
+```markdown
+### [Agent Name] responds to [Other Agent]:
+[1-2 paragraphs directly addressing the strongest point of the opposing argument.
+Concede what is true. Challenge what is weak.]
+```
+
+This prevents echo-chamber advocacy — each agent must engage with the other side's best arguments.
+
+### Step 5: Accessibility Check
+
+Before presenting to the user, the **accessibility-reviewer** evaluates all proposed directions:
+
+```markdown
+## Accessibility Assessment
+
+| Direction | Accessibility Impact | Concern Level |
+|-----------|---------------------|---------------|
+| Direction A | [Assessment] | Low / Medium / High |
+| Direction B | [Assessment] | Low / Medium / High |
+
+[If any direction creates accessibility barriers, flag it clearly.
+This is not an argument for a direction — it is a constraint check.]
+```
+
+If a direction has High accessibility concern, it should be flagged prominently in the presentation to the user. The user can still choose it, but they should know the cost.
+
+### Step 6: Present to User
+
+Show the debate to the user in a structured format:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  DESIGN DEBATE
+  Question: [The design question]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  DIRECTION A: [Name]
+  Argued by: [agent]
+  [2-3 sentence summary of the case]
+  Best for: [personas]
+  Trade-off: [key trade-off]
+
+  DIRECTION B: [Name]
+  Argued by: [agent]
+  [2-3 sentence summary of the case]
+  Best for: [personas]
+  Trade-off: [key trade-off]
+
+  [DIRECTION C if applicable]
+
+  ACCESSIBILITY: [One-line summary of any concerns]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  YOUR CALL: Which direction do you want to take?
+  (You can also ask for more detail on any direction,
+   or propose a hybrid.)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 7: Record the Decision
+
+After the user decides:
+
+1. Record the chosen direction in `design-state.md` Decisions Log with rationale
+2. Record the rejected directions and why — this is valuable context for future debates
+3. If the decision reveals a taste preference, update `design-memory`
+4. Dispatch the appropriate agent to execute the chosen direction
+
+## Debate Depth
+
+Not every debate needs the full process. Scale the depth to the stakes:
+
+| Stakes | Debate Format |
+|--------|--------------|
+| **High** (sets architectural pattern) | Full debate: 2-3 advocates, cross-examination, accessibility review |
+| **Medium** (affects multiple screens) | Quick debate: 2 advocates, no cross-examination, accessibility flag |
+| **Low** (affects one component) | Micro debate: 2 options presented as a simple comparison table, user picks |
+
+## Integration
+
+- **Called by:** `design-strategy`, `using-designpowers` (when user requests debate), `designpowers-critique` (when "rethink" is recommended)
+- **Calls:** Any agent as advocate, `accessibility-reviewer` for constraint check
+- **Updates:** `design-state` with decision and rejected alternatives
+- **Informs:** `design-memory` with taste signals from the user's choice
+- **Pairs with:** `design-strategy`, `design-memory`, `taste-feedback`
+
+## Anti-Patterns
+
+| Pattern | Why It Fails |
+|---------|-------------|
+| Debating after the user has decided | Wastes time. If the user has a direction, execute it |
+| Debating trivial decisions | 8px vs 12px padding is not a debate — it's a design system decision |
+| Agents being polite instead of advocating | "Both options are great!" is not a debate. Agents must argue to win |
+| Presenting a debate without accessibility review | Every direction must be evaluated for inclusion before the user chooses |
+| Running a debate in auto mode without pausing | Debates ALWAYS pause for user decision — they are inherently direct-mode moments |
+| More than 3 directions | Too many options cause decision paralysis. If there are more than 3, narrow down first |