opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/design/skills/design-accessibility-review/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: accessibility-review
+description: Run a WCAG 2.1 AA accessibility audit on a design or page. Trigger with "audit accessibility", "check a11y", "is this accessible?", or when reviewing a design for color contrast, keyboard navigation, touch target size, or screen reader behavior before handoff.
+argument-hint: "<Figma URL, URL, or description>"
+---
+
+# /accessibility-review
+
+> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
+
+Audit a design or page for WCAG 2.1 AA accessibility compliance.
+
+## Usage
+
+```
+/accessibility-review $ARGUMENTS
+```
+
+Audit for accessibility: @$1
+
+## WCAG 2.1 AA Quick Reference
+
+### Perceivable
+- **1.1.1** Non-text content has alt text
+- **1.3.1** Info and structure conveyed semantically
+- **1.4.3** Contrast ratio >= 4.5:1 (normal text), >= 3:1 (large text)
+- **1.4.11** Non-text contrast >= 3:1 (UI components, graphics)
+
+### Operable
+- **2.1.1** All functionality available via keyboard
+- **2.4.3** Logical focus order
+- **2.4.7** Visible focus indicator
+- **2.5.5** Touch target >= 44x44 CSS pixels
+
+### Understandable
+- **3.2.1** Predictable on focus (no unexpected changes)
+- **3.3.1** Error identification (describe the error)
+- **3.3.2** Labels or instructions for inputs
+
+### Robust
+- **4.1.2** Name, role, value for all UI components
+
+## Common Issues
+
+1. Insufficient color contrast
+2. Missing form labels
+3. No keyboard access to interactive elements
+4. Missing alt text on meaningful images
+5. Focus traps in modals
+6. Missing ARIA landmarks
+7. Auto-playing media without controls
+8. Time limits without extension options
+
+## Testing Approach
+
+1. Automated scan (catches ~30% of issues)
+2. Keyboard-only navigation
+3. Screen reader testing (VoiceOver, NVDA)
+4. Color contrast verification
+5. Zoom to 200% — does layout break?
+
+## Output
+
+```markdown
+## Accessibility Audit: [Design/Page Name]
+**Standard:** WCAG 2.1 AA | **Date:** [Date]
+
+### Summary
+**Issues found:** [X] | **Critical:** [X] | **Major:** [X] | **Minor:** [X]
+
+### Findings
+
+#### Perceivable
+| # | Issue | WCAG Criterion | Severity | Recommendation |
+|---|-------|---------------|----------|----------------|
+| 1 | [Issue] | [1.4.3 Contrast] | 🔴 Critical | [Fix] |
+
+#### Operable
+| # | Issue | WCAG Criterion | Severity | Recommendation |
+|---|-------|---------------|----------|----------------|
+| 1 | [Issue] | [2.1.1 Keyboard] | 🟡 Major | [Fix] |
+
+#### Understandable
+| # | Issue | WCAG Criterion | Severity | Recommendation |
+|---|-------|---------------|----------|----------------|
+| 1 | [Issue] | [3.3.2 Labels] | 🟢 Minor | [Fix] |
+
+#### Robust
+| # | Issue | WCAG Criterion | Severity | Recommendation |
+|---|-------|---------------|----------|----------------|
+| 1 | [Issue] | [4.1.2 Name, Role, Value] | 🟡 Major | [Fix] |
+
+### Color Contrast Check
+| Element | Foreground | Background | Ratio | Required | Pass? |
+|---------|-----------|------------|-------|----------|-------|
+| [Body text] | [color] | [color] | [X]:1 | 4.5:1 | ✅/❌ |
+
+### Keyboard Navigation
+| Element | Tab Order | Enter/Space | Escape | Arrow Keys |
+|---------|-----------|-------------|--------|------------|
+| [Element] | [Order] | [Behavior] | [Behavior] | [Behavior] |
+
+### Screen Reader
+| Element | Announced As | Issue |
+|---------|-------------|-------|
+| [Element] | [What SR says] | [Problem if any] |
+
+### Priority Fixes
+1. **[Critical fix]** — Affects [who] and blocks [what]
+2. **[Major fix]** — Improves [what] for [who]
+3. **[Minor fix]** — Nice to have
+```
+
+## If Connectors Available
+
+If **~~design tool** is connected:
+- Inspect color values, font sizes, and touch targets directly from Figma
+- Check component ARIA roles and keyboard behavior in the design spec
+
+If **~~project tracker** is connected:
+- Create tickets for each accessibility finding with severity and WCAG criterion
+- Link findings to existing accessibility remediation epics
+
+## Tips
+
+1. **Start with contrast and keyboard** — These catch the most common and impactful issues.
+2. **Test with real assistive technology** — My audit is a great start, but manual testing with VoiceOver/NVDA catches things I can't.
+3. **Prioritize by impact** — Fix issues that block users first, polish later.

package/content/design/skills/design-design-critique/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: design-critique
+description: Get structured design feedback on usability, hierarchy, and consistency. Trigger with "review this design", "critique this mockup", "what do you think of this screen?", or when sharing a Figma link or screenshot for feedback at any stage from exploration to final polish.
+argument-hint: "<Figma URL, screenshot, or description>"
+---
+
+# /design-critique
+
+> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
+
+Get structured design feedback across multiple dimensions.
+
+## Usage
+
+```
+/design-critique $ARGUMENTS
+```
+
+Review the design: @$1
+
+If a Figma URL is provided, pull the design from Figma. If a file is referenced, read it. Otherwise, ask the user to describe or share their design.
+
+## What I Need From You
+
+- **The design**: Figma URL, screenshot, or detailed description
+- **Context**: What is this? Who is it for? What stage (exploration, refinement, final)?
+- **Focus** (optional): "Focus on mobile" or "Focus on the onboarding flow"
+
+## Critique Framework
+
+### 1. First Impression (2 seconds)
+- What draws the eye first? Is that correct?
+- What's the emotional reaction?
+- Is the purpose immediately clear?
+
+### 2. Usability
+- Can the user accomplish their goal?
+- Is the navigation intuitive?
+- Are interactive elements obvious?
+- Are there unnecessary steps?
+
+### 3. Visual Hierarchy
+- Is there a clear reading order?
+- Are the right elements emphasized?
+- Is whitespace used effectively?
+- Is typography creating the right hierarchy?
+
+### 4. Consistency
+- Does it follow the design system?
+- Are spacing, colors, and typography consistent?
+- Do similar elements behave similarly?
+
+### 5. Accessibility
+- Color contrast ratios
+- Touch target sizes
+- Text readability
+- Alternative text for images
+
+## How to Give Feedback
+
+- **Be specific**: "The CTA competes with the navigation" not "the layout is confusing"
+- **Explain why**: Connect feedback to design principles or user needs
+- **Suggest alternatives**: Don't just identify problems, propose solutions
+- **Acknowledge what works**: Good feedback includes positive observations
+- **Match the stage**: Early exploration gets different feedback than final polish
+
+## Output
+
+```markdown
+## Design Critique: [Design Name]
+
+### Overall Impression
+[1-2 sentence first reaction — what works, what's the biggest opportunity]
+
+### Usability
+| Finding | Severity | Recommendation |
+|---------|----------|----------------|
+| [Issue] | 🔴 Critical / 🟡 Moderate / 🟢 Minor | [Fix] |
+
+### Visual Hierarchy
+- **What draws the eye first**: [Element] — [Is this correct?]
+- **Reading flow**: [How does the eye move through the layout?]
+- **Emphasis**: [Are the right things emphasized?]
+
+### Consistency
+| Element | Issue | Recommendation |
+|---------|-------|----------------|
+| [Typography/spacing/color] | [Inconsistency] | [Fix] |
+
+### Accessibility
+- **Color contrast**: [Pass/fail for key text]
+- **Touch targets**: [Adequate size?]
+- **Text readability**: [Font size, line height]
+
+### What Works Well
+- [Positive observation 1]
+- [Positive observation 2]
+
+### Priority Recommendations
+1. **[Most impactful change]** — [Why and how]
+2. **[Second priority]** — [Why and how]
+3. **[Third priority]** — [Why and how]
+```
+
+## If Connectors Available
+
+If **~~design tool** is connected:
+- Pull the design directly from Figma and inspect components, tokens, and layers
+- Compare against the existing design system for consistency
+
+If **~~user feedback** is connected:
+- Cross-reference design decisions with recent user feedback and support tickets
+
+## Tips
+
+1. **Share the context** — "This is a checkout flow for a B2B SaaS" helps me give relevant feedback.
+2. **Specify your stage** — Early exploration gets different feedback than final polish.
+3. **Ask me to focus** — "Just look at the navigation" gives you more depth on one area.

package/content/design/skills/design-design-handoff/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: design-handoff
+description: Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.
+argument-hint: "<Figma URL or design description>"
+---
+
+# /design-handoff
+
+> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
+
+Generate comprehensive developer handoff documentation from a design.
+
+## Usage
+
+```
+/design-handoff $ARGUMENTS
+```
+
+Generate handoff specs for: @$1
+
+If a Figma URL is provided, pull the design from Figma. Otherwise, work from the provided description or screenshot.
+
+## What to Include
+
+### Visual Specifications
+- Exact measurements (padding, margins, widths)
+- Design token references (colors, typography, spacing)
+- Responsive breakpoints and behavior
+- Component variants and states
+
+### Interaction Specifications
+- Click/tap behavior
+- Hover states
+- Transitions and animations (duration, easing)
+- Gesture support (swipe, pinch, long-press)
+
+### Content Specifications
+- Character limits
+- Truncation behavior
+- Empty states
+- Loading states
+- Error states
+
+### Edge Cases
+- Minimum/maximum content
+- International text (longer strings)
+- Slow connections
+- Missing data
+
+### Accessibility
+- Focus order
+- ARIA labels and roles
+- Keyboard interactions
+- Screen reader announcements
+
+## Principles
+
+1. **Don't assume** — If it's not specified, the developer will guess. Specify everything.
+2. **Use tokens, not values** — Reference `spacing-md` not `16px`.
+3. **Show all states** — Default, hover, active, disabled, loading, error, empty.
+4. **Describe the why** — "This collapses on mobile because users primarily use one-handed" helps developers make good judgment calls.
+
+## Output
+
+```markdown
+## Handoff Spec: [Feature/Screen Name]
+
+### Overview
+[What this screen/feature does, user context]
+
+### Layout
+[Grid system, breakpoints, responsive behavior]
+
+### Design Tokens Used
+| Token | Value | Usage |
+|-------|-------|-------|
+| `color-primary` | #[hex] | CTA buttons, links |
+| `spacing-md` | [X]px | Between sections |
+| `font-heading-lg` | [size/weight/family] | Page title |
+
+### Components
+| Component | Variant | Props | Notes |
+|-----------|---------|-------|-------|
+| [Component] | [Variant] | [Props] | [Special behavior] |
+
+### States and Interactions
+| Element | State | Behavior |
+|---------|-------|----------|
+| [CTA Button] | Hover | [Background darken 10%] |
+| [CTA Button] | Loading | [Spinner, disabled] |
+| [Form] | Error | [Red border, error message below] |
+
+### Responsive Behavior
+| Breakpoint | Changes |
+|------------|---------|
+| Desktop (>1024px) | [Default layout] |
+| Tablet (768-1024px) | [What changes] |
+| Mobile (<768px) | [What changes] |
+
+### Edge Cases
+- **Empty state**: [What to show when no data]
+- **Long text**: [Truncation rules]
+- **Loading**: [Skeleton or spinner]
+- **Error**: [Error state appearance]
+
+### Animation / Motion
+| Element | Trigger | Animation | Duration | Easing |
+|---------|---------|-----------|----------|--------|
+| [Element] | [Trigger] | [Description] | [ms] | [easing] |
+
+### Accessibility Notes
+- [Focus order]
+- [ARIA labels needed]
+- [Keyboard interactions]
+```
+
+## If Connectors Available
+
+If **~~design tool** is connected:
+- Pull exact measurements, tokens, and component specs from Figma
+- Export assets and generate a complete spec sheet
+
+If **~~project tracker** is connected:
+- Link the handoff to the implementation ticket
+- Create sub-tasks for each section of the spec
+
+## Tips
+
+1. **Share the Figma link** — I can pull exact measurements, tokens, and component info.
+2. **Mention edge cases** — "What happens with 100 items?" helps me spec boundary conditions.
+3. **Specify the tech stack** — "We use React + Tailwind" helps me give relevant implementation notes.

package/content/design/skills/design-design-system/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: design-system
+description: Audit, document, or extend your design system. Use when checking for naming inconsistencies or hardcoded values across components, writing documentation for a component's variants, states, and accessibility notes, or designing a new pattern that fits the existing system.
+argument-hint: "[audit | document | extend] <component or system>"
+---
+
+# /design-system
+
+> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
+
+Manage your design system — audit for consistency, document components, or design new patterns.
+
+## Usage
+
+```
+/design-system audit                    # Full system audit
+/design-system document [component]     # Document a component
+/design-system extend [pattern]         # Design a new component or pattern
+```
+
+## Components of a Design System
+
+### Design Tokens
+Atomic values that define the visual language:
+- Colors (brand, semantic, neutral)
+- Typography (scale, weights, line heights)
+- Spacing (scale, component padding)
+- Borders (radius, width)
+- Shadows (elevation levels)
+- Motion (durations, easings)
+
+### Components
+Reusable UI elements with defined:
+- Variants (primary, secondary, ghost)
+- States (default, hover, active, disabled, loading, error)
+- Sizes (sm, md, lg)
+- Behavior (interactions, animations)
+- Accessibility (ARIA, keyboard)
+
+### Patterns
+Common UI solutions combining components:
+- Forms (input groups, validation, submission)
+- Navigation (sidebar, tabs, breadcrumbs)
+- Data display (tables, cards, lists)
+- Feedback (toasts, modals, inline messages)
+
+## Principles
+
+1. **Consistency over creativity** — The system exists so teams don't reinvent the wheel
+2. **Flexibility within constraints** — Components should be composable, not rigid
+3. **Document everything** — If it's not documented, it doesn't exist
+4. **Version and migrate** — Breaking changes need migration paths
+
+## Output — Audit
+
+```markdown
+## Design System Audit
+
+### Summary
+**Components reviewed:** [X] | **Issues found:** [X] | **Score:** [X/100]
+
+### Naming Consistency
+| Issue | Components | Recommendation |
+|-------|------------|----------------|
+| [Inconsistent naming] | [List] | [Standard to adopt] |
+
+### Token Coverage
+| Category | Defined | Hardcoded Values Found |
+|----------|---------|----------------------|
+| Colors | [X] | [X] instances of hardcoded hex |
+| Spacing | [X] | [X] instances of arbitrary values |
+| Typography | [X] | [X] instances of custom fonts/sizes |
+
+### Component Completeness
+| Component | States | Variants | Docs | Score |
+|-----------|--------|----------|------|-------|
+| Button | ✅ | ✅ | ⚠️ | 8/10 |
+| Input | ✅ | ⚠️ | ❌ | 5/10 |
+
+### Priority Actions
+1. [Most impactful improvement]
+2. [Second priority]
+3. [Third priority]
+```
+
+## Output — Document
+
+```markdown
+## Component: [Name]
+
+### Description
+[What this component is and when to use it]
+
+### Variants
+| Variant | Use When |
+|---------|----------|
+| [Primary] | [Main actions] |
+| [Secondary] | [Supporting actions] |
+
+### Props / Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| [prop] | [type] | [default] | [description] |
+
+### States
+| State | Visual | Behavior |
+|-------|--------|----------|
+| Default | [description] | — |
+| Hover | [description] | [interaction] |
+| Active | [description] | [interaction] |
+| Disabled | [description] | Non-interactive |
+| Loading | [description] | [animation] |
+
+### Accessibility
+- **Role**: [ARIA role]
+- **Keyboard**: [Tab, Enter, Escape behavior]
+- **Screen reader**: [Announced as...]
+
+### Do's and Don'ts
+| ✅ Do | ❌ Don't |
+|------|---------|
+| [Best practice] | [Anti-pattern] |
+
+### Code Example
+[Framework-appropriate code snippet]
+```
+
+## Output — Extend
+
+```markdown
+## New Component: [Name]
+
+### Problem
+[What user need or gap this component addresses]
+
+### Existing Patterns
+| Related Component | Similarity | Why It's Not Enough |
+|-------------------|-----------|---------------------|
+| [Component] | [What's shared] | [What's missing] |
+
+### Proposed Design
+
+#### API / Props
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| [prop] | [type] | [default] | [description] |
+
+#### Variants
+| Variant | Use When | Visual |
+|---------|----------|--------|
+| [Variant] | [Scenario] | [Description] |
+
+#### States
+| State | Behavior | Notes |
+|-------|----------|-------|
+| Default | [Description] | — |
+| Hover | [Description] | [Interaction] |
+| Disabled | [Description] | Non-interactive |
+| Loading | [Description] | [Animation] |
+
+#### Tokens Used
+- Colors: [Which tokens]
+- Spacing: [Which tokens]
+- Typography: [Which tokens]
+
+### Accessibility
+- **Role**: [ARIA role]
+- **Keyboard**: [Expected interactions]
+- **Screen reader**: [Announced as...]
+
+### Open Questions
+- [Decision that needs design review]
+- [Edge case to resolve]
+```
+
+## If Connectors Available
+
+If **~~design tool** is connected:
+- Audit components directly in Figma — check naming, variants, and token usage
+- Pull component properties and layer structure for documentation
+
+If **~~knowledge base** is connected:
+- Search for existing component documentation and usage guidelines
+- Publish updated documentation to your wiki
+
+## Tips
+
+1. **Start with an audit** — Know where you are before deciding where to go.
+2. **Document as you build** — It's easier to document a component while designing it.
+3. **Prioritize coverage over perfection** — 80% of components documented beats 100% of 10 components.

package/content/design/skills/design-research-synthesis/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: research-synthesis
+description: Synthesize user research into themes, insights, and recommendations. Use when you have interview transcripts, survey results, usability test notes, support tickets, or NPS responses that need to be distilled into patterns, user segments, and prioritized next steps.
+argument-hint: "<research data, transcripts, or survey results>"
+---
+
+# /research-synthesis
+
+> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
+
+Synthesize user research data into actionable insights. See the **user-research** skill for research methods, interview guides, and analysis frameworks.
+
+## Usage
+
+```
+/research-synthesis $ARGUMENTS
+```
+
+## What I Accept
+
+- Interview transcripts or notes
+- Survey results (CSV, pasted data)
+- Usability test recordings or notes
+- Support tickets or feedback
+- NPS/CSAT responses
+- App store reviews
+
+## Output
+
+```markdown
+## Research Synthesis: [Study Name]
+**Method:** [Interviews / Survey / Usability Test] | **Participants:** [X]
+**Date:** [Date range] | **Researcher:** [Name]
+
+### Executive Summary
+[3-4 sentence overview of key findings]
+
+### Key Themes
+
+#### Theme 1: [Name]
+**Prevalence:** [X of Y participants]
+**Summary:** [What this theme is about]
+**Supporting Evidence:**
+- "[Quote]" — P[X]
+- "[Quote]" — P[X]
+**Implication:** [What this means for the product]
+
+#### Theme 2: [Name]
+[Same format]
+
+### Insights → Opportunities
+
+| Insight | Opportunity | Impact | Effort |
+|---------|-------------|--------|--------|
+| [What we learned] | [What we could do] | High/Med/Low | High/Med/Low |
+
+### User Segments Identified
+| Segment | Characteristics | Needs | Size |
+|---------|----------------|-------|------|
+| [Name] | [Description] | [Key needs] | [Rough %] |
+
+### Recommendations
+1. **[High priority]** — [Why, based on which findings]
+2. **[Medium priority]** — [Why]
+3. **[Lower priority]** — [Why]
+
+### Questions for Further Research
+- [What we still don't know]
+
+### Methodology Notes
+[How the research was conducted, any limitations or biases to note]
+```
+
+## If Connectors Available
+
+If **~~user feedback** is connected:
+- Pull support tickets, feature requests, and NPS responses to supplement research data
+- Cross-reference themes with real user complaints and requests
+
+If **~~product analytics** is connected:
+- Validate qualitative findings with usage data and behavioral metrics
+- Quantify the impact of identified pain points
+
+If **~~knowledge base** is connected:
+- Search for prior research studies and findings to compare against
+- Publish the synthesis to your research repository
+
+## Tips
+
+1. **Include raw quotes** — Direct participant quotes make insights credible and memorable.
+2. **Separate observations from interpretations** — "5 of 8 users clicked the wrong button" is an observation. "The button placement is confusing" is an interpretation.
+3. **Quantify where possible** — "Most users" is vague. "7 of 10 users" is specific.

package/content/design/skills/design-user-research/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: user-research
+description: Plan, conduct, and synthesize user research. Trigger with "user research plan", "interview guide", "usability test", "survey design", "research questions", or when the user needs help with any aspect of understanding their users through research.
+---
+
+# User Research
+
+Help plan, execute, and synthesize user research studies.
+
+## Research Methods
+
+| Method | Best For | Sample Size | Time |
+|--------|----------|-------------|------|
+| User interviews | Deep understanding of needs and motivations | 5-8 | 2-4 weeks |
+| Usability testing | Evaluating a specific design or flow | 5-8 | 1-2 weeks |
+| Surveys | Quantifying attitudes and preferences | 100+ | 1-2 weeks |
+| Card sorting | Information architecture decisions | 15-30 | 1 week |
+| Diary studies | Understanding behavior over time | 10-15 | 2-8 weeks |
+| A/B testing | Comparing specific design choices | Statistical significance | 1-4 weeks |
+
+## Interview Guide Structure
+
+1. **Warm-up** (5 min): Build rapport, explain the session
+2. **Context** (10 min): Understand their current workflow
+3. **Deep dive** (20 min): Explore the specific topic
+4. **Reaction** (10 min): Show concepts or prototypes
+5. **Wrap-up** (5 min): Anything we missed? Thank them.
+
+## Analysis Framework
+
+- **Affinity mapping**: Group observations into themes
+- **Impact/effort matrix**: Prioritize findings
+- **Journey mapping**: Visualize the user experience over time
+- **Jobs to be done**: Understand what users are hiring your product to do
+
+## Deliverables
+
+- Research plan (objectives, methods, timeline, participants)
+- Interview guide (questions, probes, activities)
+- Synthesis report (themes, insights, recommendations)
+- Highlight reel (key quotes and observations)