Windsurf + Aider targets, MCP server, and demo placement (#33)
Broadens both reach (more tools) and content types (an MCP server), continuing the multi-platform story. Windsurf + Aider: - build-exports.mjs gains two platforms: exports/windsurf/*.md (workspace rules, trigger: model_decision) and exports/aider/*.md (conventions for `aider --read`). Now 5 platforms (ChatGPT, Gemini, Cursor, Windsurf, Aider). - install.sh + bin/cli.mjs install both (windsurf -> .windsurf/rules, aider -> .aider/skills with a --read hint); generated README index is excluded from copies. - One-line windsurf-install.sh / aider-install.sh wrappers for parity. MCP server (new content type): - mcp/server.mjs — zero-dependency stdio MCP server exposing list_skills, search_skills, get_skill. Published as a second bin (pm-claude-skills-mcp). Logs to stderr; reads bundled skills/ at startup. mcp/README.md documents client config. Also: README hero "See it in action" demo placement (ready to swap in a GIF; recording guide in web/docs-assets/README.md), Works-With table + exports + install docs updated, CHANGELOG Unreleased. package.json files/bin updated. Claude-Session: https://claude.ai/code/session_016JWn5jRD5tcEFKrubjQ6Px Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
mohitagw15856
GitHub
@@ -0,0 +1,178 @@
|
||||
# Accessibility Audit Skill
|
||||
|
||||
This skill produces a structured accessibility audit based on WCAG 2.2 guidelines. It covers visual, motor, cognitive, and screen reader accessibility — with prioritised remediation for each issue found.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **What is being audited** (screen, component, full product, design spec)
|
||||
- **Description or image** of the UI
|
||||
- **Target WCAG level** (A / AA / AAA — default to AA, which is the legal standard in most jurisdictions)
|
||||
- **Known assistive technology users?** (Yes/No — if yes, which: screen reader / switch access / voice control / magnification)
|
||||
- **Platform** (Web / iOS / Android / Desktop app)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Accessibility Audit: [Component or Screen Name]
|
||||
**Target standard:** WCAG 2.2 Level [AA]
|
||||
**Platform:** [Platform]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Audit Summary
|
||||
|
||||
| Category | Issues Found | Critical | Moderate | Minor |
|
||||
|---|---|---|---|---|
|
||||
| Perceivable | | | | |
|
||||
| Operable | | | | |
|
||||
| Understandable | | | | |
|
||||
| Robust | | | | |
|
||||
| **Total** | | | | |
|
||||
|
||||
**Overall compliance status:** ✅ Compliant / 🟡 Minor issues / 🔴 Fails AA standard
|
||||
|
||||
---
|
||||
|
||||
## Perceivable
|
||||
|
||||
### 1.1 Text Alternatives
|
||||
- [ ] All images have descriptive alt text (not filename or "image")
|
||||
- [ ] Decorative images have `alt=""` to be skipped by screen readers
|
||||
- [ ] Icons without visible labels have accessible names
|
||||
- [ ] Complex images (charts, diagrams) have extended descriptions
|
||||
|
||||
**Issues found:** [List specific issues or "None"]
|
||||
|
||||
### 1.3 Adaptable
|
||||
- [ ] Content structure uses semantic HTML (headings, lists, landmarks) — not just visual formatting
|
||||
- [ ] Reading order in DOM matches visual order
|
||||
- [ ] Form inputs have associated labels (not placeholder text as label)
|
||||
- [ ] Data tables have proper headers and scope
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 1.4 Distinguishable
|
||||
- [ ] Text contrast ratio ≥ 4.5:1 (normal text) or ≥ 3:1 (large text 18px+)
|
||||
- [ ] UI component contrast ratio ≥ 3:1 against background
|
||||
- [ ] Information is not conveyed by colour alone
|
||||
- [ ] Text can be resized to 200% without loss of content
|
||||
- [ ] No content that auto-plays audio
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Operable
|
||||
|
||||
### 2.1 Keyboard Accessible
|
||||
- [ ] All interactive elements are reachable by keyboard (Tab key)
|
||||
- [ ] No keyboard traps
|
||||
- [ ] Custom components have keyboard interactions (arrow keys for menus, Escape to close modals)
|
||||
- [ ] Skip navigation link available for pages with repeated navigation
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 2.4 Navigable
|
||||
- [ ] Focus is visible at all times (not removed with `outline: none` without replacement)
|
||||
- [ ] Focus order is logical and predictable
|
||||
- [ ] Page/screen has a descriptive title
|
||||
- [ ] Link text is descriptive (not "click here" or "read more")
|
||||
- [ ] Headings are hierarchical (H1 → H2 → H3, no skips)
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 2.5 Input Modalities
|
||||
- [ ] Touch targets are at least 44x44px
|
||||
- [ ] No functionality requires complex gestures (pinch, multi-touch) without a simple alternative
|
||||
- [ ] Motion or dragging interactions have button alternatives
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Understandable
|
||||
|
||||
### 3.1 Readable
|
||||
- [ ] Language of the page is set (`lang` attribute)
|
||||
- [ ] Unusual words, abbreviations, or jargon are explained
|
||||
|
||||
### 3.2 Predictable
|
||||
- [ ] Navigation is consistent across screens
|
||||
- [ ] Components behave consistently (same button does the same thing)
|
||||
- [ ] No unexpected context changes on focus or input
|
||||
|
||||
### 3.3 Input Assistance
|
||||
- [ ] Error messages identify the field and describe the error in plain language (not just "Invalid input")
|
||||
- [ ] Required fields are labelled (not just with colour or asterisk alone)
|
||||
- [ ] Forms provide suggestions for correcting errors where possible
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Robust
|
||||
|
||||
### 4.1 Compatible
|
||||
- [ ] HTML is valid and well-structured
|
||||
- [ ] ARIA roles and attributes are used correctly (not to fix broken semantics)
|
||||
- [ ] Status messages (success, error, loading) are announced to screen readers without focus change
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Prioritised Remediation List
|
||||
|
||||
| Priority | Issue | WCAG Criterion | Fix | Effort |
|
||||
|---|---|---|---|---|
|
||||
| 🔴 Critical | [Issue] | [e.g. 1.4.3 Contrast] | [Specific fix] | [Low/Med/High] |
|
||||
| 🟡 Moderate | [Issue] | | | |
|
||||
| 🟢 Minor | [Issue] | | | |
|
||||
|
||||
**Priority definitions:**
|
||||
- 🔴 Critical: Blocks access for users with disabilities. Legal risk. Fix before launch.
|
||||
- 🟡 Moderate: Significant friction. Fix in next sprint.
|
||||
- 🟢 Minor: Best practice. Address in roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Quick Wins (Fix in < 1 hour)
|
||||
|
||||
[List any issues that are trivially fixable — e.g. adding alt text, fixing contrast with a colour swap, adding a `lang` attribute. These are easy to ship immediately.]
|
||||
|
||||
---
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
- **Manual keyboard test:** Tab through the entire flow. Can you complete every task without a mouse?
|
||||
- **Screen reader test:** VoiceOver (Mac/iOS), NVDA or JAWS (Windows). Is every piece of content and every action accessible?
|
||||
- **Colour contrast check:** Use Stark (Figma plugin) or WebAIM Contrast Checker
|
||||
- **Automated scan:** Axe DevTools or Lighthouse accessibility audit (catches ~30% of issues automatically)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Issues are mapped to specific WCAG criteria
|
||||
- [ ] Every critical issue has a specific fix recommendation
|
||||
- [ ] Quick wins are separated from larger fixes
|
||||
- [ ] Effort estimates are included for prioritisation
|
||||
- [ ] Testing recommendations are included
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not rely solely on automated scanning tools — automated checks catch ~30% of issues; manual keyboard and screen reader testing is required
|
||||
- [ ] Do not label an issue "minor" simply because it only affects a small percentage of users — for those users it may block all access
|
||||
- [ ] Do not add ARIA roles to fix broken semantics — use correct semantic HTML first; ARIA is a last resort
|
||||
- [ ] Do not confuse colour contrast of text with colour contrast of UI components — they have different minimum ratios (4.5:1 vs 3:1)
|
||||
- [ ] Do not audit only the happy path — error states, empty states, and loading states must also meet accessibility requirements
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit this design for accessibility"
|
||||
- "Check WCAG compliance for [screen/component]"
|
||||
- "Give me an a11y audit of [UI description]"
|
||||
- "What accessibility issues does this design have?"
|
||||
@@ -0,0 +1,133 @@
|
||||
# Design Critique Skill
|
||||
|
||||
This skill provides structured, actionable design feedback using established UX frameworks. It balances positive observations with clear, prioritised improvement suggestions.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **What is being reviewed** (screen, flow, component, full product)
|
||||
- **Design description or attached image** (describe it if no image — the skill will still work)
|
||||
- **User goal** (what is the user trying to accomplish with this design?)
|
||||
- **Context** (web / mobile / desktop app / physical product)
|
||||
- **Stage** (early wireframe / mid-fidelity / high-fidelity / live product)
|
||||
- **Primary concern** (optional — e.g. "I'm worried the onboarding is too long" or "I think the CTA is unclear")
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Design Critique: [Design Name or Screen]
|
||||
|
||||
**User goal:** [What the user needs to accomplish]
|
||||
**Context:** [Platform / Stage]
|
||||
**Critique focus:** [Primary concern if stated, otherwise "full review"]
|
||||
|
||||
---
|
||||
|
||||
## 1. What's Working
|
||||
|
||||
[3–5 specific, honest observations about what the design does well. Don't manufacture praise — only include genuine strengths. Be specific: "The visual hierarchy clearly guides the eye from headline → supporting detail → CTA" is useful. "Looks clean" is not.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Priority Issues
|
||||
|
||||
Rank issues by impact on the user goal. Use:
|
||||
- 🔴 **High** — Blocks or significantly degrades the user's ability to complete their goal
|
||||
- 🟡 **Medium** — Causes friction or confusion but doesn't block completion
|
||||
- 🟢 **Low** — Polish or preference — nice to fix but not critical
|
||||
|
||||
For each issue:
|
||||
|
||||
### [Priority] Issue [N]: [Short name]
|
||||
|
||||
**What's happening:**
|
||||
[Describe the specific design problem — be precise about which element, screen, or interaction]
|
||||
|
||||
**Why it matters:**
|
||||
[Connect to the user goal or a specific principle — don't just say "it's confusing." Say why it creates confusion and what the consequence is for the user.]
|
||||
|
||||
**Framework reference:**
|
||||
[Name the principle being violated — e.g. Nielsen's Heuristic #6 (Recognition over Recall), Gestalt proximity, JTBD clarity, Fitts's Law, etc.]
|
||||
|
||||
**Recommendation:**
|
||||
[Specific, actionable suggestion. Not "make the button bigger" but "Increase the primary CTA to at least 44x44px to meet touch target guidelines; consider moving it below the form rather than inline with the input fields to reduce accidental taps."]
|
||||
|
||||
---
|
||||
|
||||
## 3. Heuristic Assessment
|
||||
|
||||
Quick assessment against Nielsen's 10 Usability Heuristics — score each as ✅ Pass / 🟡 Partial / ❌ Fail:
|
||||
|
||||
| Heuristic | Status | Note |
|
||||
|---|---|---|
|
||||
| 1. Visibility of system status | | |
|
||||
| 2. Match between system and real world | | |
|
||||
| 3. User control and freedom | | |
|
||||
| 4. Consistency and standards | | |
|
||||
| 5. Error prevention | | |
|
||||
| 6. Recognition rather than recall | | |
|
||||
| 7. Flexibility and efficiency of use | | |
|
||||
| 8. Aesthetic and minimalist design | | |
|
||||
| 9. Help users recognise, diagnose, and recover from errors | | |
|
||||
| 10. Help and documentation | | |
|
||||
|
||||
Only include heuristics relevant to what's visible in the design — don't penalise for things not in scope.
|
||||
|
||||
---
|
||||
|
||||
## 4. Gestalt Principles Check
|
||||
|
||||
[Comment on any Gestalt principles that are either well-applied or violated:]
|
||||
|
||||
- **Proximity:** [Are related elements grouped clearly?]
|
||||
- **Similarity:** [Do similar elements look similar?]
|
||||
- **Continuity:** [Does the eye flow naturally through the design?]
|
||||
- **Figure/Ground:** [Is the primary content clearly distinguished from background?]
|
||||
- **Closure:** [Are any implied shapes or containers confusing?]
|
||||
|
||||
---
|
||||
|
||||
## 5. JTBD Alignment
|
||||
|
||||
[Assess how well the design serves the stated job-to-be-done:]
|
||||
|
||||
- **Does the design make the user's primary job obvious?** [Yes / Partially / No — explain]
|
||||
- **Are there any elements that distract from the primary job?** [List any competing CTAs, distractions, or unclear hierarchy]
|
||||
- **What emotional job does this design serve?** [Speed / Confidence / Control / Delight / Other] — and does the visual design match that emotional goal?
|
||||
|
||||
---
|
||||
|
||||
## 6. Top 3 Recommended Next Steps
|
||||
|
||||
Prioritised list of the 3 most impactful changes. Each should be actionable in the next design iteration:
|
||||
|
||||
1. [Most impactful change — specific]
|
||||
2. [Second priority]
|
||||
3. [Third priority]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] "What's working" includes only genuine, specific observations
|
||||
- [ ] Every issue has a framework reference (not just subjective opinion)
|
||||
- [ ] Recommendations are specific and actionable
|
||||
- [ ] Priority levels (High/Medium/Low) reflect actual impact on user goal
|
||||
- [ ] Heuristic assessment only covers visible elements
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not lead with visual preference (e.g. "I don't like the colour") — every issue must reference a UX principle or user impact
|
||||
- [ ] Do not invent problems in the "What's Working" section — manufactured praise undermines the entire critique
|
||||
- [ ] Do not provide the same priority level (High/Medium/Low) to every issue — prioritisation requires genuine judgment about user impact
|
||||
- [ ] Do not skip the JTBD section for product screens — connecting feedback to the user's job-to-be-done is what separates UX critique from aesthetic opinion
|
||||
- [ ] Do not give recommendations that require a full redesign when the user is in high-fidelity — scope recommendations to the design stage
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Critique this design: [description or image]"
|
||||
- "Give me feedback on this UI/UX"
|
||||
- "Review this Figma screen for usability issues"
|
||||
- "What's wrong with this user flow?"
|
||||
- "Do a heuristic evaluation of [screen/product]"
|
||||
@@ -0,0 +1,218 @@
|
||||
# Design System Audit Skill
|
||||
|
||||
This skill produces a structured audit of a design system — covering component coverage, token consistency, documentation quality, accessibility compliance, contribution processes, and adoption health. Output is ready for a design system team, design leadership, or an engineering team evaluating their shared component library.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Design system name** and what product(s) it serves
|
||||
- **Audit scope** — component library / design tokens / documentation / contribution process / all of the above
|
||||
- **Current tooling** — Figma / Storybook / Zeroheight / custom / combination?
|
||||
- **Team using it** — how many designers and engineers, how many products?
|
||||
- **Known pain points** — what do teams complain about most?
|
||||
- **Governance model** — centralised team / federated contributors / no dedicated team?
|
||||
- **Goal of the audit** — improve adoption / prepare for a rebrand / onboard new teams / justify investment?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Design System Audit: [System Name]
|
||||
|
||||
**Products served:** [List of products / apps]
|
||||
**Audit scope:** [Full / Components only / Tokens only / Documentation]
|
||||
**Auditor:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Stakeholders:** [Design lead, Eng lead, CPO, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Overall Health Score
|
||||
|
||||
| Dimension | Score (1–5) | Status |
|
||||
|---|---|---|
|
||||
| Component coverage | [X/5] | 🟢/🟡/🔴 |
|
||||
| Token consistency | [X/5] | 🟢/🟡/🔴 |
|
||||
| Documentation quality | [X/5] | 🟢/🟡/🔴 |
|
||||
| Accessibility compliance | [X/5] | 🟢/🟡/🔴 |
|
||||
| Adoption rate | [X/5] | 🟢/🟡/🔴 |
|
||||
| Contribution process | [X/5] | 🟢/🟡/🔴 |
|
||||
| **Overall** | **[X/5]** | 🟢/🟡/🔴 |
|
||||
|
||||
**Summary:** [2–3 sentences. What is the overall state of the design system? What are the top 2 issues and what is the biggest strength?]
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Coverage Audit
|
||||
|
||||
**How to assess:** Compare components in the design system against the actual UI patterns in the product. Every pattern that exists in production but not in the system is a coverage gap.
|
||||
|
||||
### Component Inventory
|
||||
|
||||
| Category | Components present | Coverage | Gap |
|
||||
|---|---|---|---|
|
||||
| **Navigation** | [Navbar, Sidebar, Breadcrumb, Tabs] | [80%] | [Missing: Mega menu, mobile drawer] |
|
||||
| **Forms & Inputs** | [Text input, Dropdown, Checkbox, Radio, Toggle, Date picker] | [90%] | [Missing: Multi-select, Rich text editor] |
|
||||
| **Feedback & Alerts** | [Toast, Banner, Modal, Tooltip] | [60%] | [Missing: Inline validation, Progress indicator, Skeleton loader] |
|
||||
| **Data Display** | [Table, Card, Badge, Avatar] | [50%] | [Missing: Data grid, Stat card, Timeline, Gantt] |
|
||||
| **Layout** | [Grid, Container, Divider, Spacer] | [70%] | [Missing: Responsive breakpoint utilities] |
|
||||
| **Buttons & Actions** | [Button, Icon button, FAB, Link] | [100%] | [None] |
|
||||
|
||||
**Coverage score:** [X% of production UI patterns are covered by the design system]
|
||||
|
||||
**Most impactful gaps:**
|
||||
1. [Most used pattern not in the system — causing most duplication]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
---
|
||||
|
||||
## 2. Component Quality Audit
|
||||
|
||||
For each component, assess against these quality criteria:
|
||||
|
||||
| Component | States complete | Responsive | Accessibility | Dark mode | Props documented | Code matches Figma |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Button | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Modal | ⚠️ Loading state missing | ✅ | ✅ | ❌ | ⚠️ Partial | ✅ |
|
||||
| Table | ❌ Sorting state missing | ❌ No mobile layout | ⚠️ No aria-sort | ❌ | ❌ | ⚠️ Drift |
|
||||
| [Component] | [...] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Legend:** ✅ Complete — ⚠️ Partial / inconsistent — ❌ Missing
|
||||
|
||||
**Components with critical quality issues (fix before anything else):**
|
||||
- [Component name]: [Specific issue and why it's blocking]
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## 3. Design Token Audit
|
||||
|
||||
**Token coverage:**
|
||||
|
||||
| Token type | Defined | Used consistently | Issues |
|
||||
|---|---|---|---|
|
||||
| **Colour** | [X tokens defined] | [⚠️ — 12 hardcoded hex values found in Figma] | [Inconsistent use of primary-500 vs primary-600 for CTAs across products] |
|
||||
| **Typography** | [X tokens defined] | [✅] | [None — all type styles use token scale] |
|
||||
| **Spacing** | [X tokens defined] | [⚠️ — custom spacing used in X components] | [Engineers using arbitrary px values instead of spacing tokens in X components] |
|
||||
| **Border radius** | [X tokens defined] | [❌ — not defined; each component has hardcoded values] | [Button, card, modal all use different radius values with no token] |
|
||||
| **Shadow / elevation** | [X tokens defined] | [⚠️] | [3 different drop-shadow values in use; no elevation scale] |
|
||||
| **Animation / motion** | [X tokens defined] | [❌ — not defined] | [Transition durations inconsistent across components] |
|
||||
|
||||
**Semantic token layer:** [Does the system have semantic tokens (e.g. `color.action.primary` on top of `color.blue.500`) or only primitive tokens?]
|
||||
|
||||
**Token drift:** [Are code tokens and Figma tokens in sync? Use a tool like Token Studio, Style Dictionary, or manual comparison.]
|
||||
|
||||
---
|
||||
|
||||
## 4. Documentation Quality Audit
|
||||
|
||||
**Assessment per component / pattern:**
|
||||
|
||||
| Document type | Quality | Issues |
|
||||
|---|---|---|
|
||||
| **Usage guidelines** | [⚠️ — X% of components have guidelines] | [Button and Form components documented; Navigation and Data Display mostly undocumented] |
|
||||
| **Do / Don't examples** | [❌ — mostly absent] | [Engineers frequently misuse components because intent is unclear] |
|
||||
| **Accessibility notes** | [⚠️ — present for some components] | [No consistent format; accessibility notes missing for interactive components] |
|
||||
| **Code examples** | [✅ — all Storybook components have code examples] | [...] |
|
||||
| **Changelog** | [❌ — no component-level changelog exists] | [Breaking changes are not communicated; causes unexpected UI regressions] |
|
||||
| **Migration guides** | [❌ — absent] | [Teams don't know how to upgrade to new component versions] |
|
||||
|
||||
**Documentation score:** [X% of components have complete, usable documentation]
|
||||
|
||||
**Most common designer / engineer complaint about docs:** [e.g. "I can't find whether to use Modal or Drawer for this use case — no guidance exists"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Accessibility Audit
|
||||
|
||||
**WCAG 2.2 compliance status:**
|
||||
|
||||
| Criterion | Level | Status | Components affected |
|
||||
|---|---|---|---|
|
||||
| Colour contrast (text) | AA | [✅ / ⚠️ / ❌] | [e.g. ❌ — Disabled state text fails 4.5:1 ratio in 3 components] |
|
||||
| Colour contrast (UI components) | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Keyboard navigation | AA | [✅ / ⚠️ / ❌] | [⚠️ — Modal focus trap not implemented; Dropdown not keyboard accessible] |
|
||||
| Focus visible | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Screen reader support (ARIA) | AA | [✅ / ⚠️ / ❌] | [❌ — Table component lacks aria-sort; Icon buttons have no aria-label] |
|
||||
| Touch target size | AA | [✅ / ⚠️ / ❌] | [⚠️ — Mobile tap targets below 44×44px in X components] |
|
||||
| Motion / animation | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
|
||||
**Critical accessibility blockers (must fix before next release):**
|
||||
1. [Most critical issue — e.g. Keyboard users cannot close Modal — focus trap missing]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
## 6. Adoption Audit
|
||||
|
||||
**Adoption by team / product:**
|
||||
|
||||
| Product / Team | Components used from system | Custom components built outside system | Adoption score |
|
||||
|---|---|---|---|
|
||||
| [Product A] | [X% of UI uses system components] | [Y custom components] | [High / Medium / Low] |
|
||||
| [Product B] | [...] | [...] | [...] |
|
||||
|
||||
**Why teams are not adopting:**
|
||||
|
||||
| Barrier | Severity | Evidence |
|
||||
|---|---|---|
|
||||
| [Component doesn't exist] | High | [Top reason in team survey] |
|
||||
| [Component exists but doesn't meet use case] | Medium | [Modal component lacks X state needed by Product B] |
|
||||
| [Documentation too sparse to know how to use it] | Medium | [...] |
|
||||
| [No one enforces system use — easier to build custom] | High | [...] |
|
||||
| [System is out of date with product's current visual language] | Medium | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Contribution Process Audit
|
||||
|
||||
| Dimension | Current state | Assessment |
|
||||
|---|---|---|
|
||||
| **How to contribute** | [Documented / Not documented] | [✅ / ❌] |
|
||||
| **Contribution criteria** | [Clear entry bar for what goes in the system] | [⚠️ — unclear who decides what becomes a system component vs stays local] |
|
||||
| **Review process** | [Who reviews contributions and how long it takes] | [❌ — no formal review; contributions sit unreviewed for weeks] |
|
||||
| **Release cadence** | [How often system releases happen] | [⚠️ — sporadic; no set cadence] |
|
||||
| **Breaking change policy** | [How breaking changes are handled and communicated] | [❌ — no policy; breaking changes are a surprise] |
|
||||
| **Versioning** | [Semantic versioning in place?] | [✅ — all packages use semver] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Prioritised Remediation Roadmap
|
||||
|
||||
| Priority | Initiative | Impact | Effort | Timeline |
|
||||
|---|---|---|---|---|
|
||||
| P1 | Fix [X] critical accessibility issues (keyboard nav, ARIA) | Critical — legal + user impact | Medium | Sprint 1–2 |
|
||||
| P1 | Define and implement border radius and shadow token scale | High — ends inconsistency | Low | Sprint 1 |
|
||||
| P1 | Document top 10 most-used components (usage + do/don't) | High — unblocks adoption | Medium | Sprint 2–4 |
|
||||
| P2 | Build Skeleton loader + Inline validation components (top 2 gaps) | High — eliminates custom duplication | High | Quarter 2 |
|
||||
| P2 | Establish contribution process with SLA for reviews | Medium — enables growth | Low | Sprint 3 |
|
||||
| P3 | Dark mode token support | Medium — product parity | High | Quarter 3 |
|
||||
| P3 | Design-code token sync tooling (Token Studio / Style Dictionary) | Medium — reduces drift | Medium | Quarter 2–3 |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Coverage gaps are identified by comparing the design system to actual production UI, not assumed
|
||||
- [ ] Accessibility issues cite specific WCAG criterion and affected components
|
||||
- [ ] Adoption barriers are backed by evidence (interviews, survey, usage data) — not assumed
|
||||
- [ ] Remediation roadmap has effort estimates and is sequenced by impact
|
||||
- [ ] Both Figma and code (Storybook/implementation) are assessed — not just Figma
|
||||
- [ ] Stakeholders from design, engineering, and product have reviewed the audit
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not assess only the Figma library without checking the code implementation — Figma-code drift is one of the most common and costly design system failures
|
||||
- [ ] Do not score adoption without interviewing teams — audit tool metrics miss the human reasons teams build custom components instead of using the system
|
||||
- [ ] Do not treat all component gaps equally — prioritise gaps based on how many production screens rely on custom implementations, not alphabetically
|
||||
- [ ] Do not recommend adding more components without first auditing documentation quality — an undocumented component is often worse than no component
|
||||
- [ ] Do not schedule remediation without a named owner per initiative — design system improvements without ownership consistently stall
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit our design system for consistency and coverage"
|
||||
- "Review our component library and identify gaps"
|
||||
- "Assess the health of our shared design system"
|
||||
- "Run a design system audit before we do a rebrand"
|
||||
- "What's wrong with our design system and what should we fix first?"
|
||||
@@ -0,0 +1,163 @@
|
||||
# UX Research Plan Skill
|
||||
|
||||
This skill creates a complete, ready-to-execute UX research plan. Output covers everything from research objectives to screener questions, discussion guide, and synthesis framework.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Research question** (what decision will this research inform?)
|
||||
- **Product area or feature** being researched
|
||||
- **Research type** (Generative / Evaluative / Usability testing / Diary study / Survey)
|
||||
- **Stage** (Discovery / Concept validation / Prototype testing / Live product)
|
||||
- **Target participants** (role, demographics, behaviour — who should we talk to?)
|
||||
- **Timeline and number of sessions**
|
||||
- **Existing assumptions or hypotheses** (optional but valuable)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# UX Research Plan: [Study Title]
|
||||
**Product area:** [Area]
|
||||
**Research type:** [Type]
|
||||
**Date:** [Timeline]
|
||||
**Researcher:** [Leave for user]
|
||||
|
||||
---
|
||||
|
||||
## 1. Research Objectives
|
||||
|
||||
State 2–4 clear research objectives. Each objective should map to a decision that will be made differently depending on what you find.
|
||||
|
||||
**Objective [N]:** Understand [specific thing] so we can [decision this informs].
|
||||
|
||||
---
|
||||
|
||||
## 2. Research Questions
|
||||
|
||||
[5–8 questions — the actual questions you want research to answer. These are not the interview questions; they're the knowledge gaps. Organised under each objective.]
|
||||
|
||||
**Objective 1:**
|
||||
- RQ1.1: [Research question]
|
||||
- RQ1.2: [Research question]
|
||||
|
||||
---
|
||||
|
||||
## 3. Methodology & Rationale
|
||||
|
||||
**Method chosen:** [e.g. Semi-structured interviews / Usability testing / Concept testing]
|
||||
|
||||
**Why this method:**
|
||||
[2–3 sentences. Match method to research type. If evaluative: usability testing. If generative: contextual inquiry or interviews. If testing comprehension: 5-second test or concept test.]
|
||||
|
||||
**What this method will and won't tell us:**
|
||||
- **Will tell us:** [What this method is good at revealing]
|
||||
- **Won't tell us:** [What's out of scope — be honest about limits]
|
||||
|
||||
**Sample size:** [Recommended number of sessions and why — e.g. "5–6 moderated interviews for generative research; 5–8 usability sessions to identify top issues"]
|
||||
|
||||
---
|
||||
|
||||
## 4. Participant Screener
|
||||
|
||||
**Recruitment criteria:**
|
||||
|
||||
| Criterion | Must Have / Nice to Have | Disqualify if |
|
||||
|---|---|---|
|
||||
| [e.g. Uses project management software daily] | Must Have | [Never uses any PM tool] |
|
||||
| [e.g. Works in a team of 5+] | Must Have | — |
|
||||
| [e.g. B2B industry] | Nice to Have | — |
|
||||
|
||||
**Screener questions (5–8 questions):**
|
||||
|
||||
[Q1] [Screening question — clear, not leading]
|
||||
- [Answer options — flag which qualify/disqualify]
|
||||
|
||||
[Q2] ...
|
||||
|
||||
**Incentive recommendation:** [Amount and format — e.g. "£50 gift voucher for a 60-min session is standard in the UK for professional participants"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Discussion Guide
|
||||
|
||||
Structure the session:
|
||||
|
||||
### Opening (5 min)
|
||||
- Introduce yourself and the study
|
||||
- "We're testing the design, not you — there are no wrong answers"
|
||||
- Permission to record
|
||||
- Warm-up: [1–2 easy questions to build rapport — e.g. "Tell me about your role and what a typical week looks like"]
|
||||
|
||||
### Core Questions (by section)
|
||||
|
||||
**Section [A]: [Topic]** *(~X min)*
|
||||
|
||||
1. [Open question — start broad] *[Probe: Tell me more about...]*
|
||||
2. [Follow-up to go deeper] *[Probe: Can you walk me through what happened?]*
|
||||
3. [Specific scenario or past behaviour question]
|
||||
|
||||
**Section [B]: [Topic]** *(~X min)*
|
||||
[Continue with 2–3 questions per section]
|
||||
|
||||
**Usability tasks (if applicable):**
|
||||
> "I'm going to ask you to try a few things with this prototype. Please think aloud as you go."
|
||||
|
||||
- Task [N]: [Clear task instruction — write from the user's perspective, not "click on X" but "find where you would go to do Y"]
|
||||
- **Success criteria:** [What "completing this task" looks like]
|
||||
- **What to observe:** [Where friction typically appears]
|
||||
|
||||
### Closing (5 min)
|
||||
- "Is there anything about [topic] we haven't covered that you think is important?"
|
||||
- "If you could change one thing about [product/concept], what would it be?"
|
||||
- Debrief and thank
|
||||
|
||||
---
|
||||
|
||||
## 6. Synthesis Framework
|
||||
|
||||
After sessions, use this framework to synthesise findings:
|
||||
|
||||
**Step 1: Session notes → Key observations**
|
||||
For each session: 3–5 specific observations (behaviours, quotes, reactions — not interpretations yet)
|
||||
|
||||
**Step 2: Affinity mapping**
|
||||
Group observations by theme across all sessions. Aim for 4–7 clusters.
|
||||
|
||||
**Step 3: Insight statements**
|
||||
For each cluster: "When [context], users [behaviour/experience], because [underlying need or mental model]."
|
||||
|
||||
**Step 4: Implications**
|
||||
For each insight: "This means we should [design/product implication]" or "This challenges our assumption that [assumption]."
|
||||
|
||||
**Step 5: Research report structure:**
|
||||
- Key findings (3–5 headlines)
|
||||
- Supporting evidence per finding
|
||||
- Design recommendations
|
||||
- Open questions for next research cycle
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Research objectives map to real decisions
|
||||
- [ ] Discussion guide opens broad before going specific
|
||||
- [ ] Screener criteria are specific enough to get the right participants
|
||||
- [ ] Tasks (if usability) are written from the user's perspective
|
||||
- [ ] Synthesis framework is included
|
||||
- [ ] Incentive recommendation is included
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write a research plan without clearly stated research objectives — every methodology choice must flow from the objectives
|
||||
- [ ] Do not design a plan that mixes generative and evaluative research without clearly separating them
|
||||
- [ ] Do not omit screener criteria — recruiting unqualified participants invalidates the research
|
||||
- [ ] Do not write discussion guide questions that are leading — questions must be neutral and open-ended
|
||||
- [ ] Do not skip the incentive recommendation — uncompensated research has lower participant quality and completion rates
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a research plan for [feature or product area]"
|
||||
- "Create a discussion guide for user interviews about [topic]"
|
||||
- "Plan a usability test for [prototype or feature]"
|
||||
- "Write screener questions for [target user type]"
|
||||
Reference in New Issue
Block a user