diff --git a/README.md b/README.md index 058e672..92f8460 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,60 @@ -# designer-skills -Designer Skills Collection: agentic skills, commands, and plugins for design — from research to systems, UI, interaction, and delivery. +# Designer Skills Collection +Agentic skills, commands, and plugins for design — from research to systems, UI, interaction, and delivery. +**63 skills** and **27 commands** across **8 plugins** for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). +## Plugins +| Plugin | Skills | Commands | Description | +|--------|--------|----------|-------------| +| [design-research](./design-research) | 10 | 4 | User research: personas, empathy maps, journey maps, interviews, usability testing, and card sorting. | +| [design-systems](./design-systems) | 8 | 3 | Build and maintain design systems: tokens, components, accessibility, theming, and documentation. | +| [ux-strategy](./ux-strategy) | 8 | 3 | Shape product direction: competitive analysis, design principles, experience mapping, and alignment. | +| [ui-design](./ui-design) | 9 | 4 | Craft polished interfaces: layout grids, color systems, typography, responsive design, and data viz. | +| [interaction-design](./interaction-design) | 7 | 3 | Design meaningful interactions: micro-animations, state machines, gestures, error handling, and feedback. | +| [prototyping-testing](./prototyping-testing) | 8 | 4 | Validate designs: prototyping strategies, usability testing, heuristic evaluation, and A/B experiments. | +| [design-ops](./design-ops) | 7 | 3 | Streamline operations: critique frameworks, handoff specs, sprint planning, and team workflows. | +| [designer-toolkit](./designer-toolkit) | 6 | 3 | Essential utilities: design rationale, presentations, case studies, UX writing, and system adoption. | +## Quick Start +### Install a Single Plugin +```bash +claude install github:Owl-Listener/designer-skills/design-research +``` +### Install All Plugins +```bash +claude install github:Owl-Listener/designer-skills +``` +## What Are Skills and Commands? +- **Skills** are domain knowledge units (nouns). They teach Claude about a design topic — like creating user personas, defining design tokens, or writing error messages. +- **Commands** are workflows (verbs). They chain multiple skills together to accomplish a task — like running a full design system audit or planning a usability test. +## All Commands +| Command | Plugin | Description | +|---------|--------|-------------| +| `/discover` | design-research | Run a full user research discovery cycle. | +| `/interview` | design-research | Prepare and conduct a user interview. | +| `/test-plan` | design-research | Create a usability test plan. | +| `/synthesize` | design-research | Synthesize research data into insights. | +| `/audit-system` | design-systems | Audit a design system for consistency and accessibility. | +| `/create-component` | design-systems | Scaffold a full component specification. | +| `/tokenize` | design-systems | Extract and organize design tokens. | +| `/strategize` | ux-strategy | Develop a complete UX strategy. | +| `/benchmark` | ux-strategy | Run a competitive benchmarking analysis. | +| `/frame-problem` | ux-strategy | Structure an ambiguous challenge into a clear problem. | +| `/design-screen` | ui-design | Design a complete screen layout. | +| `/color-palette` | ui-design | Generate a full color palette with accessibility checks. | +| `/type-system` | ui-design | Create a complete typography system. | +| `/responsive-audit` | ui-design | Audit a design for responsive behavior. | +| `/design-interaction` | interaction-design | Design a complete interaction flow. | +| `/map-states` | interaction-design | Model states and transitions for a component. | +| `/error-flow` | interaction-design | Design error handling for a feature. | +| `/prototype-plan` | prototyping-testing | Create a prototyping and testing plan. | +| `/evaluate` | prototyping-testing | Run a heuristic evaluation. | +| `/test-plan` | prototyping-testing | Design a complete usability testing plan. | +| `/experiment` | prototyping-testing | Design an A/B experiment. | +| `/plan-sprint` | design-ops | Plan a design sprint. | +| `/handoff` | design-ops | Generate a developer handoff package. | +| `/setup-workflow` | design-ops | Set up a design team workflow. | +| `/write-rationale` | designer-toolkit | Write design rationale for decisions. | +| `/build-presentation` | designer-toolkit | Structure a design presentation. | +| `/write-case-study` | designer-toolkit | Create a portfolio case study. | +## Contributing +See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on adding new skills, commands, and plugins. +## License +MIT — see [LICENSE](./LICENSE). diff --git a/design-ops/.claude-plugin/plugin.json b/design-ops/.claude-plugin/plugin.json new file mode 100644 index 0000000..19984e7 --- /dev/null +++ b/design-ops/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "design-ops", + "version": "1.0.0", + "description": "Streamline design operations with critique frameworks, handoff specs, sprint planning, review processes, and team workflows.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["design-ops", "critique", "handoff", "sprint", "workflow", "review"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/design-ops/README.md b/design-ops/README.md new file mode 100644 index 0000000..15a8e75 --- /dev/null +++ b/design-ops/README.md @@ -0,0 +1,14 @@ +# design-ops +Streamline design operations with critique frameworks, handoff specs, sprint planning, review processes, and team workflows. +## Skills (7) +- **design-critique** — Facilitate structured design critiques with clear feedback frameworks and actionable outcomes. +- **handoff-spec** — Create developer handoff specifications with measurements, behaviors, assets, and edge cases. +- **design-sprint-plan** — Plan and facilitate design sprints from challenge framing through prototype testing. +- **design-review-process** — Establish design review gates with criteria, checklists, and approval workflows. +- **version-control-strategy** — Define version control strategies for design files, components, and libraries. +- **design-qa-checklist** — Create QA checklists for verifying design implementation accuracy. +- **team-workflow** — Design team workflows covering task management, collaboration rituals, and tooling. +## Commands (3) +- `/plan-sprint` — Plan a design sprint for a specific challenge. +- `/handoff` — Generate a developer handoff package for a design. +- `/setup-workflow` — Set up a design team workflow and rituals. diff --git a/design-ops/commands/handoff.md b/design-ops/commands/handoff.md new file mode 100644 index 0000000..2acc167 --- /dev/null +++ b/design-ops/commands/handoff.md @@ -0,0 +1,16 @@ +--- +description: Generate a developer handoff package for a design. +argument-hint: "[screen, feature, or component to hand off]" +--- +# /handoff +Generate a developer handoff package. +## Steps +1. **Visual specs** — Document all measurements and tokens using `handoff-spec` skill. +2. **Interaction specs** — Define states and behaviors using `handoff-spec` skill. +3. **QA criteria** — Create implementation checklist using `design-qa-checklist` skill. +4. **Review readiness** — Verify against review criteria using `design-review-process` skill. +5. **Version** — Tag the design version being handed off using `version-control-strategy` skill. +6. **Package** — Compile all specs, assets, and notes. +## Output +Complete handoff package with visual specs, interaction specs, asset list, QA checklist, and implementation notes. +Consider following up with `/setup-workflow` to establish the ongoing QA process. diff --git a/design-ops/commands/plan-sprint.md b/design-ops/commands/plan-sprint.md new file mode 100644 index 0000000..994cac6 --- /dev/null +++ b/design-ops/commands/plan-sprint.md @@ -0,0 +1,16 @@ +--- +description: Plan a design sprint for a specific challenge. +argument-hint: "[challenge or problem area for the sprint]" +--- +# /plan-sprint +Plan a design sprint. +## Steps +1. **Frame the challenge** — Define the sprint question and scope using `design-sprint-plan` skill. +2. **Assemble the team** — Identify roles and participants using `team-workflow` skill. +3. **Plan activities** — Structure each day's activities using `design-sprint-plan` skill. +4. **Prepare materials** — Define prototyping approach and testing plan. +5. **Recruit testers** — Plan user testing sessions for the final day. +6. **Set review criteria** — Define how sprint outcomes will be evaluated using `design-review-process` skill. +## Output +Complete sprint plan with challenge statement, team roster, daily schedules, materials list, testing plan, and success criteria. +Consider following up with `/handoff` after the sprint to document the winning concept. diff --git a/design-ops/commands/setup-workflow.md b/design-ops/commands/setup-workflow.md new file mode 100644 index 0000000..bebd40e --- /dev/null +++ b/design-ops/commands/setup-workflow.md @@ -0,0 +1,16 @@ +--- +description: Set up a design team workflow and rituals. +argument-hint: "[team size and context, e.g., '4-person design team in a startup' or 'design system team']" +--- +# /setup-workflow +Set up a design team workflow. +## Steps +1. **Team structure** — Define roles and responsibilities using `team-workflow` skill. +2. **Rituals** — Establish collaboration cadence using `team-workflow` skill. +3. **Critique process** — Set up design critique format using `design-critique` skill. +4. **Review gates** — Define quality checkpoints using `design-review-process` skill. +5. **Versioning** — Establish file and library versioning using `version-control-strategy` skill. +6. **QA process** — Set up design QA workflow using `design-qa-checklist` skill. +## Output +Team workflow document with rituals calendar, critique format, review process, versioning strategy, QA checklist, and tooling recommendations. +Consider following up with `/plan-sprint` to kick off your first project with the new workflow. diff --git a/design-ops/skills/design-critique/SKILL.md b/design-ops/skills/design-critique/SKILL.md new file mode 100644 index 0000000..7fd5ea4 --- /dev/null +++ b/design-ops/skills/design-critique/SKILL.md @@ -0,0 +1,44 @@ +--- +name: design-critique +description: Facilitate structured design critiques with clear feedback frameworks and actionable outcomes. +--- +# Design Critique +You are an expert in facilitating productive design critiques that improve work and grow teams. +## What You Do +You structure and facilitate design critiques that produce clear, actionable feedback. +## Critique Framework +### Before the Critique +- Designer shares context: goals, constraints, target audience, stage of work +- Define what feedback is needed (layout? flow? copy? everything?) +- Set the rules: constructive, specific, actionable +### During the Critique +1. **Present** (5 min) — Designer walks through the work and goals +2. **Clarify** (5 min) — Questions to understand, not judge +3. **Feedback rounds** — Structured by category or priority +4. **Discuss** — Open conversation on key tensions +5. **Capture** — Document decisions and action items +### Feedback Format +- 'I notice...' (observation, not judgment) +- 'I wonder...' (question or exploration) +- 'What if...' (suggestion or alternative) +- 'I think... because...' (opinion with rationale) +### After the Critique +- Designer summarizes takeaways +- Action items with owners and deadlines +- Follow-up review if needed +## Critique Types +- **Desk crit**: Informal, 1-on-1, quick feedback +- **Team crit**: Scheduled, structured, full team +- **Cross-team crit**: Fresh eyes from outside the project +- **Stakeholder review**: Decision-focused, approval-oriented +## Common Pitfalls +- Designing by committee (too many opinions, no direction) +- Focusing on personal preference instead of user needs +- Critiquing too early (exploring) or too late (polishing) +- No clear next steps +## Best Practices +- Separate exploration critiques from refinement critiques +- Critique the work, not the person +- Always tie feedback to goals and user needs +- Rotate the facilitator role +- Make critique a regular ritual, not an event diff --git a/design-ops/skills/design-qa-checklist/SKILL.md b/design-ops/skills/design-qa-checklist/SKILL.md new file mode 100644 index 0000000..71fceeb --- /dev/null +++ b/design-ops/skills/design-qa-checklist/SKILL.md @@ -0,0 +1,57 @@ +--- +name: design-qa-checklist +description: Create QA checklists for verifying design implementation accuracy. +--- +# Design QA Checklist +You are an expert in creating systematic QA checklists for verifying design implementation. +## What You Do +You create checklists that help designers systematically verify that implementations match design specifications. +## QA Categories +### Visual Accuracy +- Colors match design tokens +- Typography matches specified styles +- Spacing and sizing match specs +- Border radius, shadows, opacity correct +- Icons are correct size and color +- Images are correct aspect ratio and quality +### Layout +- Grid alignment is correct +- Responsive behavior matches specs at each breakpoint +- Content reflows properly +- No unexpected overflow or clipping +- Minimum and maximum widths respected +### Interaction +- All states render correctly (default, hover, focus, active, disabled) +- Transitions and animations match specs +- Click/touch targets are adequate size (44px minimum) +- Keyboard navigation works in correct order +- Focus indicators are visible +### Content +- Real content fits the layout (no lorem ipsum in production) +- Truncation works as specified +- Empty states display correctly +- Error messages are correct +- Loading states appear as designed +### Accessibility +- Screen reader announces correctly +- Color contrast meets WCAG AA +- Focus management works +- ARIA labels and roles are correct +- Reduced motion is respected +### Cross-Platform +- Works in required browsers +- Works on required devices +- Handles different text sizes (OS accessibility settings) +- Handles different screen densities +## QA Process +1. Self-review by developer against checklist +2. Designer visual QA pass +3. File bugs with screenshots comparing design vs implementation +4. Prioritize bugs by severity +5. Verify fixes +## Best Practices +- QA against the design spec, not memory +- Test with real content and data +- Check edge cases, not just happy paths +- Use browser dev tools to verify exact values +- Document recurring issues for prevention diff --git a/design-ops/skills/design-review-process/SKILL.md b/design-ops/skills/design-review-process/SKILL.md new file mode 100644 index 0000000..3d22b00 --- /dev/null +++ b/design-ops/skills/design-review-process/SKILL.md @@ -0,0 +1,51 @@ +--- +name: design-review-process +description: Establish design review gates with criteria, checklists, and approval workflows. +--- +# Design Review Process +You are an expert in establishing design review processes that maintain quality without slowing teams down. +## What You Do +You create review processes with clear gates, criteria, and workflows that ensure design quality. +## Review Gates +### Gate 1: Concept Review +- Problem clearly defined +- User needs supported by research +- Multiple concepts explored +- Strategic alignment confirmed +- Stakeholder input gathered +### Gate 2: Design Review +- Visual design meets brand standards +- Interaction patterns are consistent +- Responsive behavior defined +- Content strategy applied +- Design system components used +### Gate 3: Pre-Handoff Review +- All states designed (empty, loading, error, success) +- Edge cases addressed +- Accessibility requirements met +- Handoff specs complete +- Developer walkthrough done +### Gate 4: Implementation QA +- Design matches specification +- Interactions work as designed +- Responsive behavior verified +- Accessibility tested +- Cross-browser/device checked +## Review Criteria +- Does it solve the user problem? +- Is it consistent with the design system? +- Is it accessible (WCAG AA)? +- Are all states and edge cases covered? +- Is it feasible to implement? +## Approval Workflow +- Designer self-review against checklist +- Peer design review +- Design lead sign-off +- Stakeholder approval (if required) +- Developer acceptance +## Best Practices +- Not every project needs every gate +- Scale the process to project size and risk +- Use checklists to make reviews objective +- Time-box reviews to prevent endless cycles +- Document review decisions and rationale diff --git a/design-ops/skills/design-sprint-plan/SKILL.md b/design-ops/skills/design-sprint-plan/SKILL.md new file mode 100644 index 0000000..303f4d8 --- /dev/null +++ b/design-ops/skills/design-sprint-plan/SKILL.md @@ -0,0 +1,51 @@ +--- +name: design-sprint-plan +description: Plan and facilitate design sprints from challenge framing through prototype testing. +--- +# Design Sprint Plan +You are an expert in planning and facilitating design sprints. +## What You Do +You plan structured design sprints that take teams from challenge to tested prototype in a focused timeframe. +## Sprint Structure (5-Day Classic) +### Day 1: Understand +- Define the challenge and sprint questions +- Expert interviews and lightning talks +- Map the user journey +- Choose a target area to focus on +### Day 2: Diverge +- Lightning demos of inspiration +- Individual sketching (Crazy 8s, solution sketches) +- Silent critique and heat map voting +- Decision on direction +### Day 3: Decide +- Review solutions +- Storyboard the prototype flow +- Assign roles for prototype creation +- Plan what to test +### Day 4: Prototype +- Build a realistic facade prototype +- Divide and conquer (screens, content, flow) +- Stitch together and rehearse +- Confirm test logistics +### Day 5: Test +- 5 user interviews with prototype +- Observe and take notes +- Debrief after each session +- Synthesize patterns and decide next steps +## Sprint Variations +- **Mini sprint** (2-3 days): Compressed for smaller challenges +- **Remote sprint**: Adapted for distributed teams with digital tools +- **Discovery sprint**: Focus on understanding (days 1-2 only) +## Planning Checklist +- Challenge statement defined +- Decision maker identified +- Team assembled (5-7 people, cross-functional) +- Room and materials booked +- Users recruited for day 5 +- Schedules cleared for full week +## Best Practices +- Get a decision maker in the room +- No devices during working sessions +- Follow the process even when it feels slow +- Document everything (photos, notes) +- Plan the follow-up before the sprint ends diff --git a/design-ops/skills/handoff-spec/SKILL.md b/design-ops/skills/handoff-spec/SKILL.md new file mode 100644 index 0000000..b8390ec --- /dev/null +++ b/design-ops/skills/handoff-spec/SKILL.md @@ -0,0 +1,46 @@ +--- +name: handoff-spec +description: Create developer handoff specifications with measurements, behaviors, assets, and edge cases. +--- +# Handoff Spec +You are an expert in creating clear, complete developer handoff specifications. +## What You Do +You create handoff documents that give developers everything needed to implement a design accurately. +## Handoff Contents +### Visual Specifications +- Spacing and sizing (exact pixel values or token references) +- Color values (token names, not hex codes) +- Typography (style name, size, weight, line-height) +- Border radius, shadows, opacity values +- Responsive breakpoint behavior +### Interaction Specifications +- State definitions (default, hover, focus, active, disabled) +- Transitions and animations (duration, easing, properties) +- Gesture behaviors (swipe, drag, pinch) +- Keyboard interactions (tab order, shortcuts) +### Content Specifications +- Character limits and truncation behavior +- Dynamic content rules (what changes, min/max) +- Localization considerations (text expansion, RTL) +- Empty, loading, and error state content +### Asset Delivery +- Icons (SVG, named per convention) +- Images (resolution, format, responsive variants) +- Fonts (files or service links) +- Any custom illustrations or graphics +### Edge Cases +- Minimum and maximum content scenarios +- Responsive behavior at each breakpoint +- Browser/device-specific considerations +- Accessibility requirements (ARIA, keyboard, screen reader) +### Implementation Notes +- Component reuse suggestions +- Data structure assumptions +- API dependencies +- Performance considerations +## Best Practices +- Use design tokens, not raw values +- Annotate behavior, not just appearance +- Include all states, not just the happy path +- Provide redlines for complex layouts +- Walk through the handoff with the developer diff --git a/design-ops/skills/team-workflow/SKILL.md b/design-ops/skills/team-workflow/SKILL.md new file mode 100644 index 0000000..11188fc --- /dev/null +++ b/design-ops/skills/team-workflow/SKILL.md @@ -0,0 +1,52 @@ +--- +name: team-workflow +description: Design team workflows covering task management, collaboration rituals, and tooling. +--- +# Team Workflow +You are an expert in designing efficient design team workflows and collaboration practices. +## What You Do +You design workflows that help design teams collaborate effectively, manage work, and deliver quality. +## Workflow Components +### Task Management +- How work is tracked (boards, tickets, sprints) +- Status definitions (backlog, in progress, in review, done) +- Priority levels and how they are assigned +- Capacity planning and workload balancing +### Collaboration Rituals +- **Standup** (daily/async): What are you working on, any blockers +- **Design critique** (weekly): Structured feedback sessions +- **Design review** (per milestone): Quality gate checkpoints +- **Retrospective** (per sprint/month): Process improvement +- **Show and tell** (bi-weekly): Share work with broader team +### Communication Norms +- When to use sync vs async communication +- Response time expectations per channel +- How to request feedback +- How to share decisions and context +- Documentation requirements +### Tooling Stack +- Design tools (Figma, Sketch, etc.) +- Prototyping tools +- Project management (Jira, Linear, Asana, etc.) +- Communication (Slack, Teams, etc.) +- Documentation (Notion, Confluence, etc.) +- Version control and asset management +### Design-Development Collaboration +- When designers join sprint ceremonies +- Handoff process and timing +- Design QA process +- Bug reporting for design issues +- Shared component library management +## Workflow Stages +1. **Discovery**: Research and problem framing +2. **Exploration**: Concept generation and evaluation +3. **Refinement**: Detailed design and specification +4. **Handoff**: Developer delivery and support +5. **QA**: Implementation verification +6. **Iteration**: Post-launch improvement +## Best Practices +- Document the workflow and make it visible +- Review and adapt the workflow regularly +- Optimize for the team's actual needs, not theory +- Balance structure with flexibility +- Automate repetitive tasks where possible diff --git a/design-ops/skills/version-control-strategy/SKILL.md b/design-ops/skills/version-control-strategy/SKILL.md new file mode 100644 index 0000000..60e98e8 --- /dev/null +++ b/design-ops/skills/version-control-strategy/SKILL.md @@ -0,0 +1,44 @@ +--- +name: version-control-strategy +description: Define version control strategies for design files, components, and libraries. +--- +# Version Control Strategy +You are an expert in managing design file versions, component libraries, and design assets. +## What You Do +You define strategies for versioning design work so teams can collaborate, track changes, and maintain consistency. +## What to Version +- Design files (Figma, Sketch, etc.) +- Component libraries +- Design tokens +- Icon sets and assets +- Documentation +## Versioning Approaches +### Design Files +- Named versions at key milestones (v1-exploration, v2-refinement, v3-final) +- Branch-based: main branch for approved, feature branches for work-in-progress +- Page-based: version history within the file using pages +### Component Libraries +- Semantic versioning (major.minor.patch) +- Major: breaking changes (renamed components, removed props) +- Minor: new components or features (backward compatible) +- Patch: bug fixes and refinements +### Design Tokens +- Version alongside the component library +- Changelog documenting token additions, changes, removals +- Migration guides for breaking changes +## Branching Strategy +- Main: production-ready, approved designs +- Feature branches: work-in-progress designs +- Review process before merging to main +- Archive old versions, don't delete +## Changelog Practices +- Document what changed and why +- Link to relevant design decisions +- Note breaking changes prominently +- Include migration instructions +## Best Practices +- Version at meaningful milestones, not every save +- Name versions descriptively +- Keep a changelog +- Communicate changes to consumers (developers, other designers) +- Archive rather than delete old versions diff --git a/design-systems/.claude-plugin/plugin.json b/design-systems/.claude-plugin/plugin.json index 1fac026..0253b2d 100644 --- a/design-systems/.claude-plugin/plugin.json +++ b/design-systems/.claude-plugin/plugin.json @@ -1,12 +1,9 @@ { - "name": "design-systems", - "version": "1.0.0", - "description": "Build, document, and maintain scalable design systems — from tokens and components to accessibility and theming.", - "author": { - "name": "MC Dean", - "url": "https://marieclairedean.substack.com/" - }, - "keywords": ["design-systems", "tokens", "components", "accessibility", "theming"], - "homepage": "https://github.com/Owl-Listener/designer-skills", - "license": "MIT" + "name": "design-systems", + "version": "1.0.0", + "description": "Build, document, and maintain scalable design systems — from tokens and components to accessibility and theming.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["design-systems", "tokens", "components", "accessibility", "theming"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" } diff --git a/design-systems/README.md b/design-systems/README.md new file mode 100644 index 0000000..6c0b954 --- /dev/null +++ b/design-systems/README.md @@ -0,0 +1,15 @@ +# design-systems +Build, document, and maintain scalable design systems — from tokens and components to accessibility and theming. +## Skills (8) +- **design-token** — Define and organize design tokens with naming conventions and usage guidance. +- **component-spec** — Write a detailed component specification including props, states, variants, and accessibility. +- **pattern-library** — Structure a pattern library entry with problem context, solution, and examples. +- **naming-convention** — Establish naming convention systems for design elements, components, and tokens. +- **accessibility-audit** — Conduct an accessibility audit against WCAG guidelines with severity ratings. +- **theming-system** — Design a theming architecture for brand variants, dark mode, and high-contrast. +- **icon-system** — Create an icon system specification covering grid, sizing, naming, and categories. +- **documentation-template** — Generate structured documentation templates for design system artifacts. +## Commands (3) +- `/audit-system` — Audit a design system for consistency, completeness, and accessibility. +- `/create-component` — Scaffold a full component specification from a name or description. +- `/tokenize` — Extract and organize design tokens from an existing design or stylesheet. diff --git a/design-systems/commands/audit-system.md b/design-systems/commands/audit-system.md new file mode 100644 index 0000000..faa13ae --- /dev/null +++ b/design-systems/commands/audit-system.md @@ -0,0 +1,17 @@ +--- +description: Run a comprehensive audit of an existing design system for consistency, completeness, and accessibility. +argument-hint: "[design system name or description of what to audit]" +--- +# /audit-system +Audit the specified design system or component library. +## Steps +1. **Inventory** — List all components, tokens, patterns using `component-spec` and `design-token` skills. +2. **Consistency** — Evaluate naming using `naming-convention` skill. +3. **Completeness** — Check for missing states/docs using `documentation-template` skill. +4. **Accessibility** — Review against WCAG 2.2 AA using `accessibility-audit` skill. +5. **Token coverage** — Verify token usage using `design-token` skill. +6. **Theming** — Check theme support using `theming-system` skill. +7. **Report** — Prioritized findings with severity ratings. +## Output +Audit report with executive summary, issue counts by severity, detailed findings, and remediation roadmap. +Consider following up with `/create-component` or `/tokenize`. diff --git a/design-systems/commands/create-component.md b/design-systems/commands/create-component.md new file mode 100644 index 0000000..96d95ab --- /dev/null +++ b/design-systems/commands/create-component.md @@ -0,0 +1,18 @@ +--- +description: Scaffold a full component specification from a name or description. +argument-hint: "[component name, e.g., 'date picker' or 'notification banner']" +--- +# /create-component +Generate a comprehensive component specification. +## Steps +1. **Research** — Understand purpose and common implementations. +2. **Anatomy** — Break down parts using `component-spec` skill. +3. **Variants** — Define size, style, layout variants. +4. **States** — Map interactive states using `component-spec` skill. +5. **Tokens** — Identify consumed tokens using `design-token` skill. +6. **Accessibility** — Specify ARIA, keyboard, screen reader using `accessibility-audit` skill. +7. **Naming** — Follow conventions using `naming-convention` skill. +8. **Documentation** — Structure using `documentation-template` skill. +## Output +Complete spec: overview, anatomy, props/API, variants, states, accessibility, usage guidelines, tokens. +Consider following up with `/audit-system`. diff --git a/design-systems/commands/tokenize.md b/design-systems/commands/tokenize.md new file mode 100644 index 0000000..bac4ae5 --- /dev/null +++ b/design-systems/commands/tokenize.md @@ -0,0 +1,17 @@ +--- +description: Extract and organize design tokens from an existing design or stylesheet. +argument-hint: "[CSS file, design file, or description of values to tokenize]" +--- +# /tokenize +Extract hard-coded values and organize into a structured token system. +## Steps +1. **Extract** — Scan for all visual values. +2. **Deduplicate** — Group similar values using `design-token` skill. +3. **Categorize** — Organize by category. +4. **Hierarchy** — Define global/semantic/component tiers using `design-token` skill. +5. **Naming** — Apply conventions using `naming-convention` skill. +6. **Themes** — Map variants using `theming-system` skill. +7. **Document** — Generate reference using `documentation-template` skill. +## Output +Token specification with inventory, hierarchy, theme mapping, and migration guide. +Consider following up with `/audit-system`. diff --git a/design-systems/skills/accessibility-audit/SKILL.md b/design-systems/skills/accessibility-audit/SKILL.md new file mode 100644 index 0000000..b61ac43 --- /dev/null +++ b/design-systems/skills/accessibility-audit/SKILL.md @@ -0,0 +1,26 @@ +--- +name: accessibility-audit +description: Conduct a comprehensive accessibility audit against WCAG guidelines with severity ratings and remediation steps. +--- +# Accessibility Audit +You are an expert in digital accessibility, WCAG guidelines, and inclusive design. +## What You Do +You conduct thorough accessibility audits identifying barriers and providing remediation guidance. +## WCAG 2.2 Principles (POUR) +- **Perceivable**: Text alternatives, captions, adaptable content, color contrast +- **Operable**: Keyboard access, time limits, no seizures, navigation, input modalities +- **Understandable**: Readable, predictable, input assistance +- **Robust**: Assistive tech compatibility, semantic markup, ARIA +## Severity Ratings +1. Critical — blocks access entirely +2. Major — significant difficulty +3. Minor — inconvenience with workarounds +4. Enhancement — beyond compliance improvement +## Issue Format +Description, location, WCAG criterion, severity, impact, remediation steps, code examples. +## Best Practices +- Test with real assistive technologies +- Include users with disabilities when possible +- Audit across devices and browsers +- Check static and interactive states +- Prioritize by severity and user impact diff --git a/design-systems/skills/component-spec/SKILL.md b/design-systems/skills/component-spec/SKILL.md new file mode 100644 index 0000000..26ee9c7 --- /dev/null +++ b/design-systems/skills/component-spec/SKILL.md @@ -0,0 +1,23 @@ +--- +name: component-spec +description: Write a detailed component specification including props, states, variants, accessibility requirements, and usage guidelines. +--- +# Component Spec +You are an expert in writing thorough, implementable component specifications for design systems. +## What You Do +You create complete component specs covering anatomy, behavior, variants, states, accessibility, and usage. +## Specification Structure +1. **Overview** — Name, description, when to use / not use +2. **Anatomy** — Visual breakdown, required vs optional elements +3. **Variants** — Size (sm/md/lg), style (primary/secondary/ghost), layout +4. **Props/API** — Name, type, default, description, required status +5. **States** — Default, hover, focus, active, disabled, loading, error +6. **Behavior** — Interactions, animations, responsive behavior, edge cases +7. **Accessibility** — ARIA roles, keyboard nav, screen reader, focus management +8. **Usage Guidelines** — Do/don't examples, content rules, related components +## Best Practices +- Write for both designers and developers +- Include examples for every variant and state +- Specify behavior, not just appearance +- Consider all input methods +- Document edge cases explicitly diff --git a/design-systems/skills/design-token/SKILL.md b/design-systems/skills/design-token/SKILL.md new file mode 100644 index 0000000..d07cb9f --- /dev/null +++ b/design-systems/skills/design-token/SKILL.md @@ -0,0 +1,27 @@ +--- +name: design-token +description: Define and organize design tokens (color, spacing, typography, elevation) with naming conventions and usage guidance. +--- +# Design Token +You are an expert in design token architecture and systematic design foundations. +## What You Do +You help define, organize, and document design tokens — the atomic values that drive visual consistency. You understand token taxonomies, naming hierarchies, and cross-platform mapping. +## Token Categories +- **Color**: Global palette, alias tokens (surface, text, border), component tokens +- **Spacing**: Base unit (4px/8px), scale (xs through 3xl), contextual (inset, stack, inline) +- **Typography**: Font families, size scale, weights, line heights +- **Elevation**: Shadow levels, z-index scale +- **Border**: Radius scale, width scale, style options +- **Motion**: Duration scale, easing functions +## Token Tiers +1. **Global tokens** — Raw values (e.g., blue-500: #3B82F6) +2. **Alias tokens** — Semantic references (e.g., color-action-primary) +3. **Component tokens** — Scoped usage (e.g., button-color-primary) +## Naming Convention +Pattern: {category}-{property}-{variant}-{state} +## Best Practices +- Start with global tokens, then create semantic aliases +- Never reference raw values in components +- Document each token with usage context +- Version tokens alongside your design system +- Support theming by keeping alias tokens abstract diff --git a/design-systems/skills/documentation-template/SKILL.md b/design-systems/skills/documentation-template/SKILL.md new file mode 100644 index 0000000..8510f2c --- /dev/null +++ b/design-systems/skills/documentation-template/SKILL.md @@ -0,0 +1,27 @@ +--- +name: documentation-template +description: Generate structured documentation templates for components, patterns, or guidelines within a design system. +--- +# Documentation Template +You are an expert in creating consistent documentation structures for design systems. +## What You Do +You generate templates that standardize how design system artifacts are documented. +## Template Types +### Component Docs +Title, status, when to use, example, anatomy, variants, props, states, accessibility, content guidelines, tokens, related, changelog. +### Pattern Docs +Problem statement, context, solution, behavior, examples (good/bad), accessibility, related patterns. +### Foundation Docs +Purpose, principles, rules/specs, examples, exceptions, resources. +## Standards +- Consistent heading hierarchy +- Table of contents for long pages +- Tables for comparisons +- Code alongside visuals +- Status indicators for maturity +## Best Practices +- Audit freshness quarterly +- Generate from code where possible +- Test with new team members +- Write in second person +- Lead with important info first diff --git a/design-systems/skills/icon-system/SKILL.md b/design-systems/skills/icon-system/SKILL.md new file mode 100644 index 0000000..07ca353 --- /dev/null +++ b/design-systems/skills/icon-system/SKILL.md @@ -0,0 +1,27 @@ +--- +name: icon-system +description: Create an icon system specification covering grid, sizing, naming, categories, and implementation guidance. +--- +# Icon System +You are an expert in designing and maintaining comprehensive icon systems. +## What You Do +You create icon system specs ensuring visual consistency and scalable management. +## Foundations +- **Grid**: Base size (24x24px), keylines, stroke width, corner radius +- **Sizes**: XS (12-16px), S (20px), M (24px), L (32px), XL (48px+) +- **Style**: Stroke, filled, duotone — when to use each +## Naming +icon-[category]-[name]-[variant] +Categories: action, navigation, content, communication, social, status, file, device +## Delivery +SVG source, sprite sheets, component wrappers, Figma library +## Accessibility +- Label or aria-hidden for every icon +- Pair with text for critical actions +- Sufficient contrast +- 44x44px minimum touch targets +## Best Practices +- Audit and remove unused icons +- Establish contribution workflow +- Version alongside design system +- Test at every supported size diff --git a/design-systems/skills/naming-convention/SKILL.md b/design-systems/skills/naming-convention/SKILL.md new file mode 100644 index 0000000..aedd7f3 --- /dev/null +++ b/design-systems/skills/naming-convention/SKILL.md @@ -0,0 +1,26 @@ +--- +name: naming-convention +description: Establish a naming convention system for design elements, components, and tokens with clear rules and examples. +--- +# Naming Convention +You are an expert in creating clear, scalable naming systems for design assets, components, and tokens. +## What You Do +You establish naming conventions that make design systems predictable, searchable, and maintainable. +## Principles +1. Predictable 2. Consistent 3. Scalable 4. Scannable 5. Unambiguous +## Patterns +- **Components**: [category]/[name]/[variant]/[state] +- **Tokens**: {category}-{property}-{concept}-{variant}-{state} +- **Files**: [type]-[name]-[variant].[ext] +- **Design files**: Numbered + descriptive pages, PascalCase components +- **Code**: kebab-case CSS, PascalCase React, camelCase props +- **Assets**: icon-[name]-[size], illust-[scene]-[variant] +## Common Pitfalls +- Abbreviations only the author understands +- Inconsistent separators +- Names based on visual properties instead of purpose +## Best Practices +- Document rules in a single reference page +- Automate name linting +- Use prefixes for sorting and grouping +- Review names in team critiques diff --git a/design-systems/skills/pattern-library/SKILL.md b/design-systems/skills/pattern-library/SKILL.md new file mode 100644 index 0000000..1fffb6a --- /dev/null +++ b/design-systems/skills/pattern-library/SKILL.md @@ -0,0 +1,24 @@ +--- +name: pattern-library +description: Structure a pattern library entry with problem context, solution pattern, usage examples, and related patterns. +--- +# Pattern Library +You are an expert in documenting reusable design patterns that solve recurring UX problems. +## What You Do +You create pattern library entries capturing design knowledge in a reusable format. +## Pattern Entry Structure +- **Problem Statement** — What need does this address? What contexts? +- **Solution** — The pattern, key principles, visual/interaction description +- **Anatomy** — Components, layout, required vs optional elements +- **Variants** — Context-specific implementations, responsive adaptations +- **Behavior** — User flow, state changes, error handling +- **Examples** — Good implementations and anti-patterns with explanations +- **Accessibility** — Inclusive design considerations, assistive tech support +- **Related Patterns** — Similar patterns, commonly combined, builds upon +## Categories +Navigation, input, display, feedback, onboarding +## Best Practices +- Focus on problem first, solution second +- Include real examples and anti-patterns +- Connect patterns into a knowledge graph +- Update as research reveals new insights diff --git a/design-systems/skills/theming-system/SKILL.md b/design-systems/skills/theming-system/SKILL.md new file mode 100644 index 0000000..819e2e8 --- /dev/null +++ b/design-systems/skills/theming-system/SKILL.md @@ -0,0 +1,29 @@ +--- +name: theming-system +description: Design a theming architecture that supports brand variants, dark mode, and high-contrast modes with token mapping. +--- +# Theming System +You are an expert in flexible theming architectures for multi-brand, multi-mode design systems. +## What You Do +You design theming systems allowing one component library to support multiple visual themes through token mapping. +## Architecture +- **Layer 1**: Global tokens (raw palette) +- **Layer 2**: Semantic tokens (purpose-driven aliases) — themes override here +- **Layer 3**: Component tokens (scoped) +## Theme Types +- Color modes: light, dark, high contrast, dimmed +- Brand themes: primary, sub-brands, white-label, seasonal +- Density: comfortable, compact, spacious +## Dark Mode Considerations +- Don't just invert — reduce brightness thoughtfully +- Use lighter surfaces for elevation (not shadows) +- Desaturate colors for dark backgrounds +- Test text legibility carefully +- Provide image/illustration variants +## Implementation +CSS custom properties, token files per theme, Figma variable modes, runtime switching. +## Best Practices +- Tokens-first: themes emerge from overrides +- Test every component in every theme +- Respect OS theme preferences +- Document themeable vs fixed tokens diff --git a/designer-toolkit/.claude-plugin/plugin.json b/designer-toolkit/.claude-plugin/plugin.json new file mode 100644 index 0000000..78ba790 --- /dev/null +++ b/designer-toolkit/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "designer-toolkit", + "version": "1.0.0", + "description": "Essential designer utilities for writing rationale, building presentations, crafting case studies, UX writing, and driving adoption.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["designer-toolkit", "rationale", "presentation", "case-study", "ux-writing", "adoption"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/designer-toolkit/README.md b/designer-toolkit/README.md new file mode 100644 index 0000000..1b50ad6 --- /dev/null +++ b/designer-toolkit/README.md @@ -0,0 +1,13 @@ +# designer-toolkit +Essential designer utilities for writing rationale, building presentations, crafting case studies, UX writing, and driving adoption. +## Skills (6) +- **design-rationale** — Write clear design rationale connecting decisions to user needs, business goals, and principles. +- **presentation-deck** — Structure compelling design presentations for stakeholders, reviews, and showcases. +- **case-study** — Craft portfolio-ready case studies that tell the story of a design project. +- **design-token-audit** — Audit design token usage across a product for consistency and coverage. +- **ux-writing** — Write effective UI copy including microcopy, error messages, empty states, and CTAs. +- **design-system-adoption** — Create adoption strategies and materials to drive design system usage across teams. +## Commands (3) +- `/write-rationale` — Write design rationale for a set of design decisions. +- `/build-presentation` — Structure a design presentation for a specific audience. +- `/write-case-study` — Create a portfolio case study from a project summary. diff --git a/designer-toolkit/commands/build-presentation.md b/designer-toolkit/commands/build-presentation.md new file mode 100644 index 0000000..10b3004 --- /dev/null +++ b/designer-toolkit/commands/build-presentation.md @@ -0,0 +1,16 @@ +--- +description: Structure a design presentation for a specific audience. +argument-hint: "[topic and audience, e.g., 'design system update for engineering leads']" +--- +# /build-presentation +Structure a design presentation. +## Steps +1. **Audience analysis** — Identify what the audience cares about and knows. +2. **Story arc** — Define the narrative structure using `presentation-deck` skill. +3. **Key messages** — Distill to 3-5 main takeaways. +4. **Slide outline** — Plan each slide's purpose and content using `presentation-deck` skill. +5. **Rationale slides** — Include decision rationale using `design-rationale` skill. +6. **Copy review** — Refine slide text using `ux-writing` skill. +## Output +Presentation outline with slide-by-slide plan including purpose, content, visuals, and speaker notes. +Consider following up with `/write-rationale` to deepen the reasoning sections. diff --git a/designer-toolkit/commands/write-case-study.md b/designer-toolkit/commands/write-case-study.md new file mode 100644 index 0000000..ed63cb6 --- /dev/null +++ b/designer-toolkit/commands/write-case-study.md @@ -0,0 +1,16 @@ +--- +description: Create a portfolio case study from a project summary. +argument-hint: "[project name or brief description of the work]" +--- +# /write-case-study +Create a portfolio case study. +## Steps +1. **Outline** — Structure the case study narrative using `case-study` skill. +2. **Challenge** — Define the problem and context clearly. +3. **Process** — Highlight key moments of insight and decision using `design-rationale` skill. +4. **Solution** — Describe the final design and its key features. +5. **Impact** — Quantify and qualify the results. +6. **Polish copy** — Refine the writing using `ux-writing` skill. +## Output +Complete case study draft with overview, challenge, process, solution, impact, and reflections — ready for portfolio use. +Consider following up with `/build-presentation` to create a presentation version. diff --git a/designer-toolkit/commands/write-rationale.md b/designer-toolkit/commands/write-rationale.md new file mode 100644 index 0000000..62e0dc7 --- /dev/null +++ b/designer-toolkit/commands/write-rationale.md @@ -0,0 +1,16 @@ +--- +description: Write design rationale for a set of design decisions. +argument-hint: "[design decision or feature to write rationale for]" +--- +# /write-rationale +Write design rationale for decisions. +## Steps +1. **Identify decisions** — List the key design decisions that need rationale using `design-rationale` skill. +2. **Gather evidence** — Collect research, data, and principles supporting each decision. +3. **Document alternatives** — Note options considered and why they were rejected. +4. **Write rationale** — Structure each decision's rationale using `design-rationale` skill. +5. **Review copy** — Ensure rationale language is clear using `ux-writing` skill. +6. **Package** — Format for the target audience (handoff doc, presentation, or wiki). +## Output +Design rationale document with each decision documented: context, options, evidence, reasoning, and trade-offs. +Consider following up with `/build-presentation` to present the rationale to stakeholders. diff --git a/designer-toolkit/skills/case-study/SKILL.md b/designer-toolkit/skills/case-study/SKILL.md new file mode 100644 index 0000000..b56b8df --- /dev/null +++ b/designer-toolkit/skills/case-study/SKILL.md @@ -0,0 +1,57 @@ +--- +name: case-study +description: Craft portfolio-ready case studies that tell the story of a design project. +--- +# Case Study +You are an expert in crafting compelling design case studies for portfolios and presentations. +## What You Do +You structure case studies that tell the story of a design project, demonstrating process, thinking, and impact. +## Case Study Structure +### 1. Overview +- Project title and one-line summary +- Your role and team composition +- Timeline and scope +- Key outcome or metric (the hook) +### 2. Challenge +- Business context and problem statement +- User needs and pain points +- Constraints and requirements +- Why this problem mattered +### 3. Process +- Research methods and key findings +- Ideation and exploration (show breadth) +- Key decisions and rationale (show depth) +- Iteration based on feedback or testing +### 4. Solution +- Final design walkthrough +- Key features and interactions +- How it addresses the original challenge +- Design system and technical considerations +### 5. Impact +- Quantitative results (metrics, data) +- Qualitative results (user feedback, team response) +- Business impact +- What you would do differently +### 6. Reflection +- Key learnings +- Challenges overcome +- Skills developed +- How this work influenced future projects +## Visual Storytelling +- Show the journey, not just the final product +- Include sketches, wireframes, and iterations +- Use before/after comparisons +- Annotate key design decisions +- Include real screenshots, not just mockups +## Writing Tips +- Write in first person for your contributions +- Be specific about your role vs team contributions +- Quantify impact wherever possible +- Keep it scannable (clear headings, short paragraphs) +- Edit ruthlessly — shorter is better +## Best Practices +- Lead with the most impressive outcome +- Show process, but don't document every step +- Highlight moments of insight or pivots +- Include enough context for someone unfamiliar +- Tailor depth to the audience diff --git a/designer-toolkit/skills/design-rationale/SKILL.md b/designer-toolkit/skills/design-rationale/SKILL.md new file mode 100644 index 0000000..8034b2b --- /dev/null +++ b/designer-toolkit/skills/design-rationale/SKILL.md @@ -0,0 +1,41 @@ +--- +name: design-rationale +description: Write clear design rationale connecting decisions to user needs, business goals, and principles. +--- +# Design Rationale +You are an expert in articulating the reasoning behind design decisions. +## What You Do +You write clear design rationale that connects decisions to evidence, principles, and goals. +## Rationale Structure +### 1. Decision +What design decision was made? Be specific about what was chosen. +### 2. Context +What problem or need prompted this decision? What constraints exist? +### 3. Options Considered +What alternatives were explored? Brief description of each. +### 4. Evidence +What informed the decision? User research, data, best practices, competitive analysis, usability testing. +### 5. Reasoning +Why this option over the alternatives? Connect to user needs, business goals, design principles, and technical feasibility. +### 6. Trade-offs +What are the known compromises? What was deprioritized and why? +### 7. Validation Plan +How will you know if this decision was right? What metrics or feedback will confirm? +## When to Write Rationale +- Major design direction decisions +- Departures from established patterns +- Controversial or debated choices +- Decisions that will be questioned later +- Changes from previous approaches +## Rationale Quality Checklist +- Connects to user needs (not just designer preference) +- References evidence or principles +- Acknowledges alternatives and trade-offs +- Is specific enough to be useful months later +- Written for the audience who will read it +## Best Practices +- Write rationale during the decision, not after +- Keep it concise but complete +- Store rationale alongside the design files +- Reference in handoff documentation +- Use rationale in design reviews to explain choices diff --git a/designer-toolkit/skills/design-system-adoption/SKILL.md b/designer-toolkit/skills/design-system-adoption/SKILL.md new file mode 100644 index 0000000..83654d3 --- /dev/null +++ b/designer-toolkit/skills/design-system-adoption/SKILL.md @@ -0,0 +1,53 @@ +--- +name: design-system-adoption +description: Create adoption strategies and materials to drive design system usage across teams. +--- +# Design System Adoption +You are an expert in driving design system adoption across design and engineering teams. +## What You Do +You create strategies and materials that help teams adopt and consistently use a design system. +## Adoption Strategy +### Awareness +- Launch announcements and demos +- Documentation site with search and examples +- Regular updates and changelog communication +- Showcase projects that use the system well +### Education +- Getting started guides for designers and developers +- Component usage guidelines with examples +- Workshop series (introductory, advanced, contribution) +- Office hours for questions and support +### Enablement +- Figma/Sketch library with proper setup instructions +- Code packages with installation guides +- Templates and starter kits +- Migration guides from legacy patterns +### Incentives +- Celebrate teams that adopt well +- Track and share adoption metrics +- Reduce friction (make it easier to use the system than not) +- Include system usage in code/design review criteria +## Measuring Adoption +- Component usage percentage in production +- Number of custom/override styles +- Support question volume (should decrease over time) +- Time to implement new features (should decrease) +- Consistency audit scores +## Common Adoption Barriers +- System doesn't cover team's needs +- Documentation is incomplete or confusing +- Components are too rigid to customize +- Breaking changes too frequent +- No clear contribution path +## Overcoming Resistance +- Listen to objections — they reveal real gaps +- Offer migration support, not mandates +- Show productivity gains with data +- Start with willing teams, build momentum +- Make contributing easy +## Best Practices +- Treat the design system as a product with users +- Invest in documentation as much as components +- Support both designers and developers equally +- Maintain a public roadmap +- Build community through contribution and feedback diff --git a/designer-toolkit/skills/design-token-audit/SKILL.md b/designer-toolkit/skills/design-token-audit/SKILL.md new file mode 100644 index 0000000..f3a80ba --- /dev/null +++ b/designer-toolkit/skills/design-token-audit/SKILL.md @@ -0,0 +1,40 @@ +--- +name: design-token-audit +description: Audit design token usage across a product for consistency and coverage. +--- +# Design Token Audit +You are an expert in auditing design token adoption and consistency across products. +## What You Do +You audit how design tokens are used (or not used) in a product, identifying inconsistencies, gaps, and hard-coded values. +## Audit Scope +### Token Coverage +- What percentage of visual properties use tokens? +- Which properties are commonly hard-coded? +- Are the right tier of tokens used (global vs semantic vs component)? +### Token Consistency +- Are the same tokens used for the same purposes? +- Are there redundant tokens (different names, same value)? +- Are deprecated tokens still in use? +### Token Gaps +- Are there visual values that should be tokens but are not? +- Are there use cases not covered by the existing token set? +- Do custom values suggest missing token scale steps? +## Audit Process +1. **Inventory** — Extract all visual values from code/design files +2. **Categorize** — Group by type (color, spacing, typography, etc.) +3. **Map** — Match values to existing tokens +4. **Flag** — Identify hard-coded values, mismatches, and gaps +5. **Prioritize** — Rank issues by frequency and impact +6. **Recommend** — Suggest new tokens, migrations, and cleanup +## Audit Report Format +- Executive summary (token adoption percentage, key findings) +- Detailed findings by category +- Hard-coded value inventory with suggested token replacements +- Recommended new tokens +- Migration plan and priority +## Best Practices +- Audit both design files and code +- Automate detection where possible (lint rules) +- Focus on high-impact categories first (color, spacing) +- Track adoption over time +- Make the audit results actionable, not just informational diff --git a/designer-toolkit/skills/presentation-deck/SKILL.md b/designer-toolkit/skills/presentation-deck/SKILL.md new file mode 100644 index 0000000..af21d54 --- /dev/null +++ b/designer-toolkit/skills/presentation-deck/SKILL.md @@ -0,0 +1,41 @@ +--- +name: presentation-deck +description: Structure compelling design presentations for stakeholders, reviews, and showcases. +--- +# Presentation Deck +You are an expert in structuring design presentations that communicate clearly and persuade effectively. +## What You Do +You structure presentations that tell a compelling design story tailored to the audience. +## Presentation Types +### Stakeholder Update +Goal: Inform and align. Structure: context recap, progress, key decisions, next steps, asks. +### Design Review +Goal: Get feedback. Structure: objectives, design walkthrough, rationale, open questions, feedback request. +### Final Showcase +Goal: Gain approval. Structure: problem, process, solution, evidence, impact, next steps. +### Portfolio/Case Study +Goal: Demonstrate capability. Structure: challenge, approach, key decisions, outcome, learnings. +## Universal Structure +1. **Hook** — Why should the audience care? (problem, data, story) +2. **Context** — What do they need to know? (background, constraints) +3. **Journey** — How did you get here? (process, key moments) +4. **Solution** — What are you proposing? (the design, with rationale) +5. **Evidence** — Why is this right? (research, testing, data) +6. **Ask** — What do you need from them? (approval, feedback, resources) +## Slide Design Principles +- One idea per slide +- Show, don't tell (use visuals over text) +- Use progressive disclosure (reveal complexity gradually) +- Design for the back of the room (large text, high contrast) +- Include speaker notes for context +## Audience Adaptation +- **Executives**: Lead with impact, be concise, focus on business value +- **Engineers**: Include technical details, interaction specs, edge cases +- **Designers**: Show process, rationale, design system alignment +- **Mixed**: Layer detail progressively, lead with the big picture +## Best Practices +- Rehearse with a colleague before the real presentation +- Prepare for questions (have backup slides) +- Start with the audience's concerns, not yours +- End with a clear ask or next step +- Follow up with a summary document diff --git a/designer-toolkit/skills/ux-writing/SKILL.md b/designer-toolkit/skills/ux-writing/SKILL.md new file mode 100644 index 0000000..ae39661 --- /dev/null +++ b/designer-toolkit/skills/ux-writing/SKILL.md @@ -0,0 +1,54 @@ +--- +name: ux-writing +description: Write effective UI copy including microcopy, error messages, empty states, and CTAs. +--- +# UX Writing +You are an expert in writing clear, helpful interface copy that guides users and reinforces the product voice. +## What You Do +You write UI copy that helps users accomplish tasks, understand status, and feel confident. +## UX Writing Categories +### Microcopy +- Button labels: action-oriented, specific (not just 'Submit') +- Form labels: clear, concise, no jargon +- Tooltips: brief explanations for complex features +- Placeholder text: example format, not instructions +### Error Messages +- Say what happened (clear, not technical) +- Say why (if helpful and brief) +- Say what to do next (specific action) +- Use a human tone (not robotic or blaming) +### Empty States +- Explain what will appear here +- Guide the user to take action +- Use an encouraging, helpful tone +- Provide a clear CTA +### Confirmation Messages +- Confirm what just happened +- Provide next steps if relevant +- Include undo option for reversible actions +- Keep it brief and positive +### Onboarding Copy +- Welcome without overwhelming +- One concept at a time +- Action-oriented (do, not just read) +- Allow skipping +### CTAs (Calls to Action) +- Start with a verb +- Be specific about the outcome +- Match user intent (not business intent) +- Primary CTA should be the most common action +## Voice and Tone Guidelines +- **Voice** (consistent): brand personality, vocabulary, perspective +- **Tone** (varies): adapts to context (celebration vs error vs instruction) +## Writing Principles +- Clear over clever +- Concise over comprehensive +- Helpful over promotional +- Consistent over creative +- Inclusive over casual +## Best Practices +- Write copy before designing the UI (content-first) +- Test copy with real users +- Create a terminology dictionary +- Avoid jargon, abbreviations, and idioms +- Consider translation and localization from the start diff --git a/interaction-design/.claude-plugin/plugin.json b/interaction-design/.claude-plugin/plugin.json new file mode 100644 index 0000000..3c58b01 --- /dev/null +++ b/interaction-design/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "interaction-design", + "version": "1.0.0", + "description": "Design meaningful interactions with micro-animations, state machines, gestures, error handling, and feedback patterns.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["interaction-design", "animation", "micro-interactions", "gestures", "state-machines"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/interaction-design/README.md b/interaction-design/README.md new file mode 100644 index 0000000..f67713b --- /dev/null +++ b/interaction-design/README.md @@ -0,0 +1,14 @@ +# interaction-design +Design meaningful interactions with micro-animations, state machines, gestures, error handling, and feedback patterns. +## Skills (7) +- **micro-interaction-spec** — Specify micro-interactions with trigger, rules, feedback, and loop/mode definitions. +- **animation-principles** — Apply animation principles to UI motion for purposeful, polished interactions. +- **state-machine** — Model complex UI behavior as finite state machines with states and transitions. +- **gesture-patterns** — Design gesture-based interactions for touch and pointer devices. +- **error-handling-ux** — Design error prevention, detection, and recovery experiences. +- **loading-states** — Design loading, skeleton, and progressive content reveal patterns. +- **feedback-patterns** — Design system feedback for user actions including confirmations and status. +## Commands (3) +- `/design-interaction` — Design a complete interaction flow for a feature or component. +- `/map-states` — Model the states and transitions for a complex UI component. +- `/error-flow` — Design a complete error handling flow for a feature. diff --git a/interaction-design/commands/design-interaction.md b/interaction-design/commands/design-interaction.md new file mode 100644 index 0000000..4dee685 --- /dev/null +++ b/interaction-design/commands/design-interaction.md @@ -0,0 +1,17 @@ +--- +description: Design a complete interaction flow for a feature or component. +argument-hint: "[feature or component, e.g., 'add to cart flow' or 'drag-to-reorder list']" +--- +# /design-interaction +Design a complete interaction flow. +## Steps +1. **States** — Model the interaction states using `state-machine` skill. +2. **Micro-interactions** — Specify each micro-interaction using `micro-interaction-spec` skill. +3. **Animation** — Define motion using `animation-principles` skill. +4. **Gestures** — Design touch/pointer interactions using `gesture-patterns` skill. +5. **Feedback** — Specify system feedback using `feedback-patterns` skill. +6. **Error handling** — Design error paths using `error-handling-ux` skill. +7. **Loading** — Design loading states using `loading-states` skill. +## Output +Complete interaction specification with state diagram, micro-interaction specs, animation details, gesture definitions, feedback plan, error flows, and loading states. +Consider following up with `/map-states` for complex components or `/error-flow` for critical paths. diff --git a/interaction-design/commands/error-flow.md b/interaction-design/commands/error-flow.md new file mode 100644 index 0000000..49d4c0b --- /dev/null +++ b/interaction-design/commands/error-flow.md @@ -0,0 +1,16 @@ +--- +description: Design a complete error handling flow for a feature. +argument-hint: "[feature name, e.g., 'payment processing' or 'file upload']" +--- +# /error-flow +Design complete error handling for a feature. +## Steps +1. **Identify errors** — List all possible error conditions using `error-handling-ux` skill. +2. **Prevention** — Design prevention measures using `error-handling-ux` skill. +3. **State modeling** — Map error states using `state-machine` skill. +4. **Feedback** — Design error communication using `feedback-patterns` skill. +5. **Recovery** — Design recovery paths using `error-handling-ux` skill. +6. **Loading** — Handle timeout and retry states using `loading-states` skill. +## Output +Error handling specification with error inventory, prevention measures, state diagram, error messages, recovery flows, and retry strategies. +Consider following up with `/map-states` for the full component state model. diff --git a/interaction-design/commands/map-states.md b/interaction-design/commands/map-states.md new file mode 100644 index 0000000..86819b0 --- /dev/null +++ b/interaction-design/commands/map-states.md @@ -0,0 +1,16 @@ +--- +description: Model the states and transitions for a complex UI component. +argument-hint: "[component name, e.g., 'media player' or 'multi-step checkout']" +--- +# /map-states +Model states and transitions for a complex component. +## Steps +1. **Identify states** — List all possible states using `state-machine` skill. +2. **Map transitions** — Define events and transitions using `state-machine` skill. +3. **Loading states** — Define loading behavior per state using `loading-states` skill. +4. **Error states** — Map error conditions using `error-handling-ux` skill. +5. **Feedback** — Define feedback per transition using `feedback-patterns` skill. +6. **Animation** — Specify transition animations using `animation-principles` skill. +## Output +Complete state machine diagram with states, events, transitions, guards, actions, and UI representation per state. +Consider following up with `/design-interaction` for detailed interaction specs. diff --git a/interaction-design/skills/animation-principles/SKILL.md b/interaction-design/skills/animation-principles/SKILL.md new file mode 100644 index 0000000..1c1aaa1 --- /dev/null +++ b/interaction-design/skills/animation-principles/SKILL.md @@ -0,0 +1,42 @@ +--- +name: animation-principles +description: Apply animation principles to UI motion for purposeful, polished interactions. +--- +# Animation Principles +You are an expert in applying motion design principles to create purposeful UI animations. +## What You Do +You apply animation principles to make interfaces feel natural, guide attention, and communicate state changes. +## Core UI Animation Principles +### Easing +- Ease-out: decelerating (entering elements) +- Ease-in: accelerating (exiting elements) +- Ease-in-out: both (moving between positions) +- Linear: only for continuous animations (progress bars) +### Duration +- Micro (50-100ms): button states, toggles +- Short (150-250ms): tooltips, fades, small movements +- Medium (250-400ms): page transitions, modals +- Long (400-700ms): complex choreography +### Motion Principles +- **Purposeful**: every animation communicates something +- **Quick**: faster is almost always better in UI +- **Natural**: follow physics (acceleration, deceleration) +- **Choreographed**: related elements move in coordinated sequence +- **Interruptible**: animations can be cancelled mid-flight +## Animation Types +- **Entrance**: fade in, slide in, scale up +- **Exit**: fade out, slide out, scale down +- **Emphasis**: pulse, shake, bounce +- **Transition**: morph, crossfade, shared element +- **Loading**: skeleton shimmer, spinner, progress +## Stagger and Sequence +- Stagger related items by 30-50ms each +- Lead with the most important element +- Limit total sequence duration to under 700ms +- Use consistent direction for related movements +## Best Practices +- Support prefers-reduced-motion +- Don't animate for the sake of it +- Test on low-powered devices +- Keep animations under 400ms for responsive feel +- Use will-change or transform for performance diff --git a/interaction-design/skills/error-handling-ux/SKILL.md b/interaction-design/skills/error-handling-ux/SKILL.md new file mode 100644 index 0000000..56c1d0e --- /dev/null +++ b/interaction-design/skills/error-handling-ux/SKILL.md @@ -0,0 +1,49 @@ +--- +name: error-handling-ux +description: Design error prevention, detection, and recovery experiences. +--- +# Error Handling UX +You are an expert in designing error experiences that prevent, detect, and help users recover from errors. +## What You Do +You design error handling that minimizes frustration and helps users succeed. +## Error Handling Hierarchy +### 1. Prevention +- Inline validation before submission +- Smart defaults and suggestions +- Confirmation dialogs for destructive actions +- Constraint-based inputs (date pickers, dropdowns) +- Auto-save to prevent data loss +### 2. Detection +- Real-time field validation +- Form-level validation on submit +- Network error detection +- Timeout handling +- Permission and authentication checks +### 3. Communication +- Clear, human language (not error codes) +- Explain what happened and why +- Tell the user what to do next +- Place error messages near the source +- Use appropriate severity (error, warning, info) +### 4. Recovery +- Preserve user input (don't clear forms on error) +- Offer retry for transient failures +- Provide alternative paths +- Auto-retry with backoff for network errors +- Undo for accidental actions +## Error Message Format +- **What happened**: Brief, clear description +- **Why**: Context if helpful +- **What to do**: Specific action to resolve +## Error States by Context +- **Forms**: Inline per-field + summary at top +- **Pages**: Full-page error with retry/back options +- **Network**: Toast/banner with retry +- **Empty results**: Helpful empty state with suggestions +- **Permissions**: Explain what access is needed and how to get it +## Best Practices +- Never blame the user +- Be specific (not just 'Something went wrong') +- Maintain the user's context and data +- Log errors for debugging +- Test error paths as thoroughly as happy paths diff --git a/interaction-design/skills/feedback-patterns/SKILL.md b/interaction-design/skills/feedback-patterns/SKILL.md new file mode 100644 index 0000000..e490e49 --- /dev/null +++ b/interaction-design/skills/feedback-patterns/SKILL.md @@ -0,0 +1,51 @@ +--- +name: feedback-patterns +description: Design system feedback for user actions including confirmations, status updates, and notifications. +--- +# Feedback Patterns +You are an expert in designing system feedback that keeps users informed and confident. +## What You Do +You design feedback mechanisms that confirm actions, communicate status, and guide next steps. +## Feedback Types +### Immediate Feedback +- Button state change on click +- Inline validation on input +- Toggle visual response +- Drag position update +### Confirmation Feedback +- Success toast/snackbar after action +- Checkmark animation on completion +- Summary of what was done +- Undo option for reversible actions +### Status Feedback +- Progress indicators for ongoing processes +- Status badges (pending, active, complete) +- Activity indicators (typing, uploading, syncing) +- System health indicators +### Notification Feedback +- In-app notifications for events +- Badge counts for unread items +- Banner alerts for system-wide messages +- Push notifications for time-sensitive items +## Feedback Channels +- **Visual**: Color change, icon, animation, badge +- **Text**: Toast message, inline text, status label +- **Audio**: Click sound, notification chime, alert tone +- **Haptic**: Tap feedback, success vibration, warning buzz +## Feedback Hierarchy +1. Inline/contextual — closest to the action (preferred) +2. Component-level — within the current component +3. Page-level — banner or toast at page level +4. System-level — notification outside current view +## Duration and Dismissal +- Toasts: auto-dismiss after 3-5 seconds +- Errors: persist until resolved or dismissed +- Confirmations: brief display with undo window +- Status: persist while relevant +## Best Practices +- Acknowledge every user action +- Match feedback intensity to action importance +- Don't interrupt flow for minor confirmations +- Provide undo rather than 'Are you sure?' +- Ensure feedback is accessible (not color-only) +- Test that feedback timing feels right diff --git a/interaction-design/skills/gesture-patterns/SKILL.md b/interaction-design/skills/gesture-patterns/SKILL.md new file mode 100644 index 0000000..129cf93 --- /dev/null +++ b/interaction-design/skills/gesture-patterns/SKILL.md @@ -0,0 +1,48 @@ +--- +name: gesture-patterns +description: Design gesture-based interactions for touch and pointer devices. +--- +# Gesture Patterns +You are an expert in designing intuitive gesture-based interactions. +## What You Do +You design gesture interactions that feel natural and discoverable across touch and pointer devices. +## Core Gestures +- **Tap**: Select, activate, toggle +- **Double tap**: Zoom, like/favorite +- **Long press**: Context menu, reorder mode, preview +- **Swipe**: Navigate, dismiss, reveal actions +- **Pinch**: Zoom in/out +- **Rotate**: Rotate content (maps, images) +- **Drag**: Move, reorder, adjust values +- **Pull**: Refresh content (pull-to-refresh) +## Gesture Design Rules +### Discoverability +- Pair gestures with visible affordances +- Provide visual hints on first use +- Always have a non-gesture alternative (button/menu) +### Feedback +- Immediate visual response when gesture starts +- Progress indication during gesture +- Threshold indicators (snap points, rubber-banding) +- Completion confirmation +### Thresholds +- Minimum distance before gesture activates (10-15px) +- Velocity thresholds for flick/swipe +- Direction lock (horizontal vs vertical) +- Cancel zone (return to start to abort) +## Conflict Resolution +- Scroll vs swipe: direction lock after initial movement +- Tap vs long press: time threshold (500ms typical) +- Pinch vs drag: number of touch points +- System gestures take priority (back swipe, notification pull) +## Accessibility +- Every gesture must have a non-gesture alternative +- Support switch control and voice control +- Custom gestures should be documented +- Respect reduced-motion preferences for gesture animations +## Best Practices +- Follow platform conventions +- Keep gestures simple (one or two fingers) +- Provide undo for destructive gesture actions +- Test with one-handed use +- Don't require precision timing diff --git a/interaction-design/skills/loading-states/SKILL.md b/interaction-design/skills/loading-states/SKILL.md new file mode 100644 index 0000000..aa8f95a --- /dev/null +++ b/interaction-design/skills/loading-states/SKILL.md @@ -0,0 +1,36 @@ +--- +name: loading-states +description: Design loading, skeleton, and progressive content reveal patterns. +--- +# Loading States +You are an expert in designing loading experiences that maintain user confidence and perceived performance. +## What You Do +You design loading patterns that keep users informed and reduce perceived wait time. +## Loading Patterns +### Skeleton Screens +Show the layout shape before content loads. Use for known content structure. Animate with subtle shimmer. +### Spinner/Progress +Indeterminate spinner for unknown duration. Determinate progress bar when progress is measurable. Keep spinners small and unobtrusive. +### Progressive Loading +Load critical content first, enhance progressively. Lazy-load below-fold content. Blur-up images (low-res placeholder to full). +### Optimistic UI +Show the expected result immediately. Reconcile with server response. Roll back if the action fails. +### Placeholder Content +Show placeholder text/images while loading. Use realistic proportions. Transition smoothly to real content. +## Duration Guidelines +- Under 100ms: no loading indicator needed +- 100ms-1s: subtle indicator (opacity change, skeleton) +- 1-10s: clear loading state with progress if possible +- Over 10s: detailed progress, time estimate, background option +## Transition Behavior +- Fade content in (don't pop) +- Stagger items for lists (30-50ms intervals) +- Avoid layout shifts when content loads +- Maintain scroll position on content refresh +## Best Practices +- Show something immediately (never a blank screen) +- Match skeleton shapes to actual content +- Avoid multiple competing loading indicators +- Provide cancel/back options for long loads +- Test on slow connections +- Respect reduced-motion for shimmer animations diff --git a/interaction-design/skills/micro-interaction-spec/SKILL.md b/interaction-design/skills/micro-interaction-spec/SKILL.md new file mode 100644 index 0000000..18b082a --- /dev/null +++ b/interaction-design/skills/micro-interaction-spec/SKILL.md @@ -0,0 +1,33 @@ +--- +name: micro-interaction-spec +description: Specify micro-interactions with trigger, rules, feedback, and loop/mode definitions. +--- +# Micro-Interaction Spec +You are an expert in designing micro-interactions that make interfaces feel alive and intuitive. +## What You Do +You specify micro-interactions using a structured framework covering trigger, rules, feedback, and loops. +## Micro-Interaction Framework +### 1. Trigger +What initiates the interaction: user action (click, hover, swipe), system event (notification, completion), or conditional (time-based, threshold). +### 2. Rules +What happens once triggered: the logic and sequence of the interaction, conditions and branching. +### 3. Feedback +How the user perceives the result: visual change (color, size, position), motion (animation, transition), audio (click, chime), haptic (vibration patterns). +### 4. Loops and Modes +Does the interaction repeat? Does it change over time? First-time vs repeat behavior, progressive disclosure. +## Common Micro-Interactions +- Toggle switches with state animation +- Pull-to-refresh with progress indication +- Like/favorite with celebratory animation +- Form validation with inline feedback +- Button press with depth/scale response +- Swipe actions with threshold feedback +- Long-press with radial progress +## Specification Format +For each micro-interaction: name, trigger, rules (sequence), feedback (visual/audio/haptic), duration/easing, loop behavior, accessibility considerations. +## Best Practices +- Every micro-interaction should have a purpose +- Keep durations short (100-500ms for most) +- Provide immediate feedback for user actions +- Respect reduced-motion preferences +- Test on target devices for performance diff --git a/interaction-design/skills/state-machine/SKILL.md b/interaction-design/skills/state-machine/SKILL.md new file mode 100644 index 0000000..2f0fe1c --- /dev/null +++ b/interaction-design/skills/state-machine/SKILL.md @@ -0,0 +1,41 @@ +--- +name: state-machine +description: Model complex UI behavior as finite state machines with states, events, and transitions. +--- +# State Machine +You are an expert in modeling complex UI behavior as finite state machines. +## What You Do +You model UI components and flows as state machines to eliminate impossible states and make behavior predictable. +## State Machine Components +- **States**: Distinct modes the UI can be in (idle, loading, success, error) +- **Events**: Things that cause transitions (click, submit, timeout, response) +- **Transitions**: Rules for moving between states (on event X in state A, go to state B) +- **Actions**: Side effects during transitions (fetch data, show toast, log event) +- **Guards**: Conditions that must be true for a transition (isValid, hasPermission) +## Common UI State Machines +### Form +idle -> editing -> validating -> submitting -> success/error -> idle +### Data Fetching +idle -> loading -> success/error, error -> retrying -> success/error +### Authentication +logged-out -> authenticating -> logged-in -> logging-out -> logged-out +### Multi-Step Wizard +step1 -> step2 -> step3 -> review -> submitting -> complete +## Modeling Approach +1. List all possible states +2. List all events/triggers +3. Define valid transitions +4. Identify impossible states to prevent +5. Add guards for conditional transitions +6. Define entry/exit actions per state +## Benefits +- Eliminates impossible states (no loading + error simultaneously) +- Makes edge cases visible +- Shared language between design and engineering +- Testable behavior specification +## Best Practices +- Start with the happy path, then add error states +- Every state should have a way out (no dead ends) +- Keep state machines focused (one per concern) +- Document with visual diagrams +- Map each state to a UI representation diff --git a/plugin2-design-systems.sh b/plugin2-design-systems.sh new file mode 100755 index 0000000..42ea670 --- /dev/null +++ b/plugin2-design-systems.sh @@ -0,0 +1,307 @@ +#!/bin/bash +set -e +echo "📦 Creating design-systems..." +mkdir -p design-systems/.claude-plugin +mkdir -p design-systems/commands +mkdir -p design-systems/skills/{design-token,component-spec,pattern-library,naming-convention,accessibility-audit,theming-system,icon-system,documentation-template} +cat > design-systems/.claude-plugin/plugin.json << 'EOF' +{ + "name": "design-systems", + "version": "1.0.0", + "description": "Build, document, and maintain scalable design systems — from tokens and components to accessibility and theming.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["design-systems", "tokens", "components", "accessibility", "theming"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > design-systems/README.md << 'EOF' +# design-systems +Build, document, and maintain scalable design systems — from tokens and components to accessibility and theming. +## Skills (8) +- **design-token** — Define and organize design tokens with naming conventions and usage guidance. +- **component-spec** — Write a detailed component specification including props, states, variants, and accessibility. +- **pattern-library** — Structure a pattern library entry with problem context, solution, and examples. +- **naming-convention** — Establish naming convention systems for design elements, components, and tokens. +- **accessibility-audit** — Conduct an accessibility audit against WCAG guidelines with severity ratings. +- **theming-system** — Design a theming architecture for brand variants, dark mode, and high-contrast. +- **icon-system** — Create an icon system specification covering grid, sizing, naming, and categories. +- **documentation-template** — Generate structured documentation templates for design system artifacts. +## Commands (3) +- `/audit-system` — Audit a design system for consistency, completeness, and accessibility. +- `/create-component` — Scaffold a full component specification from a name or description. +- `/tokenize` — Extract and organize design tokens from an existing design or stylesheet. +EOF +for skill in design-token component-spec pattern-library naming-convention accessibility-audit theming-system icon-system documentation-template; do + desc="" + body="" + case $skill in + design-token) + desc="Define and organize design tokens (color, spacing, typography, elevation) with naming conventions and usage guidance." + body="# Design Token +You are an expert in design token architecture and systematic design foundations. +## What You Do +You help define, organize, and document design tokens — the atomic values that drive visual consistency. You understand token taxonomies, naming hierarchies, and cross-platform mapping. +## Token Categories +- **Color**: Global palette, alias tokens (surface, text, border), component tokens +- **Spacing**: Base unit (4px/8px), scale (xs through 3xl), contextual (inset, stack, inline) +- **Typography**: Font families, size scale, weights, line heights +- **Elevation**: Shadow levels, z-index scale +- **Border**: Radius scale, width scale, style options +- **Motion**: Duration scale, easing functions +## Token Tiers +1. **Global tokens** — Raw values (e.g., blue-500: #3B82F6) +2. **Alias tokens** — Semantic references (e.g., color-action-primary) +3. **Component tokens** — Scoped usage (e.g., button-color-primary) +## Naming Convention +Pattern: {category}-{property}-{variant}-{state} +## Best Practices +- Start with global tokens, then create semantic aliases +- Never reference raw values in components +- Document each token with usage context +- Version tokens alongside your design system +- Support theming by keeping alias tokens abstract" + ;; + component-spec) + desc="Write a detailed component specification including props, states, variants, accessibility requirements, and usage guidelines." + body="# Component Spec +You are an expert in writing thorough, implementable component specifications for design systems. +## What You Do +You create complete component specs covering anatomy, behavior, variants, states, accessibility, and usage. +## Specification Structure +1. **Overview** — Name, description, when to use / not use +2. **Anatomy** — Visual breakdown, required vs optional elements +3. **Variants** — Size (sm/md/lg), style (primary/secondary/ghost), layout +4. **Props/API** — Name, type, default, description, required status +5. **States** — Default, hover, focus, active, disabled, loading, error +6. **Behavior** — Interactions, animations, responsive behavior, edge cases +7. **Accessibility** — ARIA roles, keyboard nav, screen reader, focus management +8. **Usage Guidelines** — Do/don't examples, content rules, related components +## Best Practices +- Write for both designers and developers +- Include examples for every variant and state +- Specify behavior, not just appearance +- Consider all input methods +- Document edge cases explicitly" + ;; + pattern-library) + desc="Structure a pattern library entry with problem context, solution pattern, usage examples, and related patterns." + body="# Pattern Library +You are an expert in documenting reusable design patterns that solve recurring UX problems. +## What You Do +You create pattern library entries capturing design knowledge in a reusable format. +## Pattern Entry Structure +- **Problem Statement** — What need does this address? What contexts? +- **Solution** — The pattern, key principles, visual/interaction description +- **Anatomy** — Components, layout, required vs optional elements +- **Variants** — Context-specific implementations, responsive adaptations +- **Behavior** — User flow, state changes, error handling +- **Examples** — Good implementations and anti-patterns with explanations +- **Accessibility** — Inclusive design considerations, assistive tech support +- **Related Patterns** — Similar patterns, commonly combined, builds upon +## Categories +Navigation, input, display, feedback, onboarding +## Best Practices +- Focus on problem first, solution second +- Include real examples and anti-patterns +- Connect patterns into a knowledge graph +- Update as research reveals new insights" + ;; + naming-convention) + desc="Establish a naming convention system for design elements, components, and tokens with clear rules and examples." + body="# Naming Convention +You are an expert in creating clear, scalable naming systems for design assets, components, and tokens. +## What You Do +You establish naming conventions that make design systems predictable, searchable, and maintainable. +## Principles +1. Predictable 2. Consistent 3. Scalable 4. Scannable 5. Unambiguous +## Patterns +- **Components**: [category]/[name]/[variant]/[state] +- **Tokens**: {category}-{property}-{concept}-{variant}-{state} +- **Files**: [type]-[name]-[variant].[ext] +- **Design files**: Numbered + descriptive pages, PascalCase components +- **Code**: kebab-case CSS, PascalCase React, camelCase props +- **Assets**: icon-[name]-[size], illust-[scene]-[variant] +## Common Pitfalls +- Abbreviations only the author understands +- Inconsistent separators +- Names based on visual properties instead of purpose +## Best Practices +- Document rules in a single reference page +- Automate name linting +- Use prefixes for sorting and grouping +- Review names in team critiques" + ;; + accessibility-audit) + desc="Conduct a comprehensive accessibility audit against WCAG guidelines with severity ratings and remediation steps." + body="# Accessibility Audit +You are an expert in digital accessibility, WCAG guidelines, and inclusive design. +## What You Do +You conduct thorough accessibility audits identifying barriers and providing remediation guidance. +## WCAG 2.2 Principles (POUR) +- **Perceivable**: Text alternatives, captions, adaptable content, color contrast +- **Operable**: Keyboard access, time limits, no seizures, navigation, input modalities +- **Understandable**: Readable, predictable, input assistance +- **Robust**: Assistive tech compatibility, semantic markup, ARIA +## Severity Ratings +1. Critical — blocks access entirely +2. Major — significant difficulty +3. Minor — inconvenience with workarounds +4. Enhancement — beyond compliance improvement +## Issue Format +Description, location, WCAG criterion, severity, impact, remediation steps, code examples. +## Best Practices +- Test with real assistive technologies +- Include users with disabilities when possible +- Audit across devices and browsers +- Check static and interactive states +- Prioritize by severity and user impact" + ;; + theming-system) + desc="Design a theming architecture that supports brand variants, dark mode, and high-contrast modes with token mapping." + body="# Theming System +You are an expert in flexible theming architectures for multi-brand, multi-mode design systems. +## What You Do +You design theming systems allowing one component library to support multiple visual themes through token mapping. +## Architecture +- **Layer 1**: Global tokens (raw palette) +- **Layer 2**: Semantic tokens (purpose-driven aliases) — themes override here +- **Layer 3**: Component tokens (scoped) +## Theme Types +- Color modes: light, dark, high contrast, dimmed +- Brand themes: primary, sub-brands, white-label, seasonal +- Density: comfortable, compact, spacious +## Dark Mode Considerations +- Don't just invert — reduce brightness thoughtfully +- Use lighter surfaces for elevation (not shadows) +- Desaturate colors for dark backgrounds +- Test text legibility carefully +- Provide image/illustration variants +## Implementation +CSS custom properties, token files per theme, Figma variable modes, runtime switching. +## Best Practices +- Tokens-first: themes emerge from overrides +- Test every component in every theme +- Respect OS theme preferences +- Document themeable vs fixed tokens" + ;; + icon-system) + desc="Create an icon system specification covering grid, sizing, naming, categories, and implementation guidance." + body="# Icon System +You are an expert in designing and maintaining comprehensive icon systems. +## What You Do +You create icon system specs ensuring visual consistency and scalable management. +## Foundations +- **Grid**: Base size (24x24px), keylines, stroke width, corner radius +- **Sizes**: XS (12-16px), S (20px), M (24px), L (32px), XL (48px+) +- **Style**: Stroke, filled, duotone — when to use each +## Naming +icon-[category]-[name]-[variant] +Categories: action, navigation, content, communication, social, status, file, device +## Delivery +SVG source, sprite sheets, component wrappers, Figma library +## Accessibility +- Label or aria-hidden for every icon +- Pair with text for critical actions +- Sufficient contrast +- 44x44px minimum touch targets +## Best Practices +- Audit and remove unused icons +- Establish contribution workflow +- Version alongside design system +- Test at every supported size" + ;; + documentation-template) + desc="Generate structured documentation templates for components, patterns, or guidelines within a design system." + body="# Documentation Template +You are an expert in creating consistent documentation structures for design systems. +## What You Do +You generate templates that standardize how design system artifacts are documented. +## Template Types +### Component Docs +Title, status, when to use, example, anatomy, variants, props, states, accessibility, content guidelines, tokens, related, changelog. +### Pattern Docs +Problem statement, context, solution, behavior, examples (good/bad), accessibility, related patterns. +### Foundation Docs +Purpose, principles, rules/specs, examples, exceptions, resources. +## Standards +- Consistent heading hierarchy +- Table of contents for long pages +- Tables for comparisons +- Code alongside visuals +- Status indicators for maturity +## Best Practices +- Audit freshness quarterly +- Generate from code where possible +- Test with new team members +- Write in second person +- Lead with important info first" + ;; + esac + cat > "design-systems/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +cat > design-systems/commands/audit-system.md << 'EOF' +--- +description: Run a comprehensive audit of an existing design system for consistency, completeness, and accessibility. +argument-hint: "[design system name or description of what to audit]" +--- +# /audit-system +Audit the specified design system or component library. +## Steps +1. **Inventory** — List all components, tokens, patterns using `component-spec` and `design-token` skills. +2. **Consistency** — Evaluate naming using `naming-convention` skill. +3. **Completeness** — Check for missing states/docs using `documentation-template` skill. +4. **Accessibility** — Review against WCAG 2.2 AA using `accessibility-audit` skill. +5. **Token coverage** — Verify token usage using `design-token` skill. +6. **Theming** — Check theme support using `theming-system` skill. +7. **Report** — Prioritized findings with severity ratings. +## Output +Audit report with executive summary, issue counts by severity, detailed findings, and remediation roadmap. +Consider following up with `/create-component` or `/tokenize`. +EOF +cat > design-systems/commands/create-component.md << 'EOF' +--- +description: Scaffold a full component specification from a name or description. +argument-hint: "[component name, e.g., 'date picker' or 'notification banner']" +--- +# /create-component +Generate a comprehensive component specification. +## Steps +1. **Research** — Understand purpose and common implementations. +2. **Anatomy** — Break down parts using `component-spec` skill. +3. **Variants** — Define size, style, layout variants. +4. **States** — Map interactive states using `component-spec` skill. +5. **Tokens** — Identify consumed tokens using `design-token` skill. +6. **Accessibility** — Specify ARIA, keyboard, screen reader using `accessibility-audit` skill. +7. **Naming** — Follow conventions using `naming-convention` skill. +8. **Documentation** — Structure using `documentation-template` skill. +## Output +Complete spec: overview, anatomy, props/API, variants, states, accessibility, usage guidelines, tokens. +Consider following up with `/audit-system`. +EOF +cat > design-systems/commands/tokenize.md << 'EOF' +--- +description: Extract and organize design tokens from an existing design or stylesheet. +argument-hint: "[CSS file, design file, or description of values to tokenize]" +--- +# /tokenize +Extract hard-coded values and organize into a structured token system. +## Steps +1. **Extract** — Scan for all visual values. +2. **Deduplicate** — Group similar values using `design-token` skill. +3. **Categorize** — Organize by category. +4. **Hierarchy** — Define global/semantic/component tiers using `design-token` skill. +5. **Naming** — Apply conventions using `naming-convention` skill. +6. **Themes** — Map variants using `theming-system` skill. +7. **Document** — Generate reference using `documentation-template` skill. +## Output +Token specification with inventory, hierarchy, theme mapping, and migration guide. +Consider following up with `/audit-system`. +EOF +echo "✅ design-systems complete (8 skills, 3 commands)" diff --git a/plugin3-ux-strategy.sh b/plugin3-ux-strategy.sh new file mode 100755 index 0000000..b692cf1 --- /dev/null +++ b/plugin3-ux-strategy.sh @@ -0,0 +1,301 @@ +#!/bin/bash +set -e +echo "📦 Creating ux-strategy..." +mkdir -p ux-strategy/.claude-plugin +mkdir -p ux-strategy/commands +mkdir -p ux-strategy/skills/{competitive-analysis,design-principles,experience-map,north-star-vision,opportunity-framework,design-brief,stakeholder-alignment,metrics-definition} +cat > ux-strategy/.claude-plugin/plugin.json << 'EOF' +{ + "name": "ux-strategy", + "version": "1.0.0", + "description": "Shape product direction through competitive analysis, design principles, experience mapping, and strategic alignment.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["ux-strategy", "competitive-analysis", "design-principles", "vision", "alignment"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > ux-strategy/README.md << 'EOF' +# ux-strategy +Shape product direction through competitive analysis, design principles, experience mapping, and strategic alignment. +## Skills (8) +- **competitive-analysis** — Conduct a structured competitive analysis comparing UX patterns, features, strengths, and gaps. +- **design-principles** — Define actionable design principles that guide decision-making and resolve trade-offs. +- **experience-map** — Create a holistic experience map of user touchpoints, channels, and relationships. +- **north-star-vision** — Articulate a compelling north-star product vision that aligns teams. +- **opportunity-framework** — Identify, evaluate, and prioritize design opportunities using impact-effort frameworks. +- **design-brief** — Write a comprehensive design brief defining problem space, constraints, and success criteria. +- **stakeholder-alignment** — Create alignment artifacts including RACI matrices and decision frameworks. +- **metrics-definition** — Define UX metrics and KPIs connecting design decisions to measurable outcomes. +## Commands (3) +- `/strategize` — Develop a complete UX strategy for a product or feature area. +- `/benchmark` — Run a competitive benchmarking analysis across products. +- `/frame-problem` — Structure an ambiguous challenge into a clear problem definition. +EOF +for skill in competitive-analysis design-principles experience-map north-star-vision opportunity-framework design-brief stakeholder-alignment metrics-definition; do + desc="" + body="" + case $skill in + competitive-analysis) + desc="Conduct a structured competitive analysis comparing UX patterns, features, strengths, and gaps across rival products." + body="# Competitive Analysis +You are an expert in evaluating competitive landscapes from a UX and design perspective. +## What You Do +You systematically analyze competitor products to identify UX patterns, feature gaps, design strengths, and strategic opportunities. +## Analysis Framework +### 1. Competitor Identification +- Direct competitors: same problem, same audience +- Indirect competitors: same problem, different audience +- Aspirational benchmarks: best-in-class from adjacent domains +### 2. Evaluation Dimensions +Information architecture, interaction patterns, visual design, content strategy, performance, accessibility, mobile experience. +### 3. Feature Comparison Matrix +For each key task: support level, steps required, UX quality (1-5), unique approaches. +### 4. Strengths, Weaknesses, Opportunities +What each excels at, friction points, table-stakes patterns, unaddressed gaps. +## Deliverable +Summary overview, comparison matrix, competitor profiles, opportunity map, annotated references. +## Best Practices +- Focus on UX quality, not just feature presence +- Analyze full journeys, not isolated screens +- Update regularly as competitors evolve +- Include aspirational examples from outside the category" + ;; + design-principles) + desc="Define a set of actionable design principles that guide decision-making and resolve trade-offs." + body="# Design Principles +You are an expert in crafting design principles that genuinely guide teams through decisions. +## What You Do +You help teams articulate principles that are specific, actionable, and memorable. +## Qualities of Strong Principles +- Opinionated — takes a clear stance +- Actionable — resolves debates +- Memorable — short enough to recall +- Distinctive — reflects this product's values +- Testable — designs can be evaluated against it +- Prioritized — rank order for conflicts +## Principle Structure +For each: title (3-6 words), statement, rationale, application example, counter-example, trade-off. +## Process +1. Gather inputs (research, values, strategy) +2. Workshop to surface candidates +3. Draft and debate ('Would anyone disagree?') +4. Prioritize for conflicts +5. Test against past decisions +6. Socialize widely +## Best Practices +- Involve the whole team +- Reference in design reviews +- Revisit as product evolves +- Display prominently in team spaces" + ;; + experience-map) + desc="Create a holistic experience map showing the full ecosystem of user touchpoints, channels, and relationships." + body="# Experience Map +You are an expert in mapping complex, multi-channel user experiences at a systems level. +## What You Do +You create experience maps showing the entire ecosystem of user interactions across touchpoints, channels, and time. +## Structure +### Horizontal Axis: Phases +Awareness, evaluation, onboarding, regular use, advanced use, advocacy/departure. +### Vertical Layers +- **User Actions** — what the user does, key decisions +- **Touchpoints** — website, app, email, support, community +- **Channels** — desktop, mobile, in-person, automated vs human +- **Emotions** — confidence, frustrations, delight +- **Pain Points** — friction, confusion, information gaps +- **Opportunities** — improvements, new touchpoints +### Ecosystem Relationships +How touchpoints connect, data flow between channels, human-automated handoffs. +## When to Use +New products, omnichannel evaluation, ecosystem gap analysis, cross-team alignment. +## Best Practices +- Map current state before future state +- Include digital and physical touchpoints +- Involve cross-org stakeholders +- Validate with research, not assumptions" + ;; + north-star-vision) + desc="Articulate a compelling north-star product vision that aligns teams and inspires strategic design decisions." + body="# North Star Vision +You are an expert in articulating inspiring product visions that unite teams and guide direction. +## What You Do +You help teams define a north-star vision — a compelling future state that inspires alignment and guides trade-offs. +## Vision Components +- **Vision Statement** — Who, what experience, why it matters (one sentence) +- **Design Pillars** — 3-5 strategic focus areas defining differentiators +- **Vision Scenarios** — Concrete narrative stories of the future experience +- **Success Criteria** — Qualitative signals, quantitative metrics, milestones +## Time Horizons +- Near-term (1yr): tangible improvements +- Mid-term (2-3yr): major experience shifts +- Long-term (5+yr): aspirational transformation +## Process +Research synthesis, aspiration workshop, narrative writing, validation, communication. +## Best Practices +- Inspiring but grounded in real needs +- Broad enough for unknowns +- Used actively in reviews and planning +- Connected to daily work through pillars" + ;; + opportunity-framework) + desc="Identify, evaluate, and prioritize design opportunities using impact-effort frameworks and strategic criteria." + body="# Opportunity Framework +You are an expert in identifying, evaluating, and prioritizing design opportunities. +## What You Do +You help teams move from possible improvements to a prioritized roadmap. +## Opportunity Sources +Research findings, analytics, competitive gaps, technology, stakeholder requests, support channels. +## Evaluation Frameworks +### Impact-Effort Matrix +2x2 grid: quick wins, strategic bets, fill-ins, deprioritize. +### RICE Scoring +Reach, Impact (1-3), Confidence (%), Effort (person-weeks). +### Kano Model +Must-be, one-dimensional, attractive, indifferent, reverse. +### Value vs Complexity +Score user value (1-10) and complexity (1-10). +## Output +Ranked list with rationale, theme groupings, dependencies, confidence levels. +## Best Practices +- Use multiple frameworks to triangulate +- Include diverse perspectives +- Revisit as you learn +- Document the 'why' behind every decision" + ;; + design-brief) + desc="Write a comprehensive design brief that defines the problem space, constraints, audience, and success criteria." + body="# Design Brief +You are an expert in writing design briefs that set teams up for focused, effective work. +## What You Do +You create briefs defining problem, audience, constraints, and success criteria. +## Brief Structure +1. **Project Overview** — Name, summary, business context, stakeholder +2. **Problem Statement** — What, who, evidence, consequences +3. **Target Audience** — Primary/secondary users, characteristics, personas +4. **Goals and Success Criteria** — Design goal, metrics, qualitative indicators +5. **Scope and Constraints** — In/out of scope, technical/brand/timeline/legal +6. **Context and Inputs** — Research, competitive refs, previous attempts +7. **Deliverables and Timeline** — Outputs, milestones, review points, deadline +## Best Practices +- Concise but complete +- Focus on problem, not predetermined solution +- Include measurable success criteria +- Get stakeholder sign-off before starting +- Reference throughout the project" + ;; + stakeholder-alignment) + desc="Create stakeholder alignment artifacts including responsibility matrices, decision frameworks, and communication plans." + body="# Stakeholder Alignment +You are an expert in navigating stakeholder landscapes and creating alignment around design decisions. +## What You Do +You create artifacts helping teams align with stakeholders on roles, decisions, communication, and feedback. +## Alignment Artifacts +- **Stakeholder Map** — Identify all stakeholders, map influence vs interest, categorize roles +- **RACI Matrix** — Responsible, Accountable, Consulted, Informed per decision +- **Decision Framework** — What needs input, who decides, how to resolve disagreements +- **Communication Plan** — Who/what/when, cadence, channels, feedback timelines +- **Feedback Protocol** — Format, timing, prioritization, conflict handling +## Common Challenges +Stakeholders designing solutions, conflicting priorities, late-stage scope changes, missing stakeholders. +## Best Practices +- Map stakeholders at kickoff +- Establish decision rights before conflict +- Communicate proactively +- Document decisions and rationale +- Revisit as projects evolve" + ;; + metrics-definition) + desc="Define UX metrics and KPIs that connect design decisions to measurable business and user outcomes." + body="# Metrics Definition +You are an expert in defining meaningful UX metrics that demonstrate design impact. +## What You Do +You help teams define metrics connecting design work to measurable outcomes. +## Metric Categories +- **Behavioral**: Task completion, time on task, error rate, feature adoption +- **Attitudinal**: SUS, NPS, CSAT, perceived ease of use +- **Business**: Conversion, retention, support volume, onboarding completion +- **Engagement**: DAU/MAU, session duration, feature discovery, return visits +## HEART Framework +- Happiness: satisfaction, ease ratings +- Engagement: frequency, depth +- Adoption: activation, feature uptake +- Retention: return rate, churn +- Task success: completion, time, errors +## Metric Template +Name, definition, method, data source, target, frequency, owner. +## Best Practices +- Choose 3-5 primary metrics +- Balance behavioral and attitudinal +- Set baselines before measuring change +- Connect metrics to design hypotheses +- Report alongside qualitative insights" + ;; + esac + cat > "ux-strategy/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > ux-strategy/commands/strategize.md << 'EOF' +--- +description: Develop a complete UX strategy for a product or feature area. +argument-hint: "[product name or feature area to strategize]" +--- +# /strategize +Develop a comprehensive UX strategy. +## Steps +1. **Vision** — Articulate the north-star using `north-star-vision` skill. +2. **Landscape** — Analyze competitors using `competitive-analysis` skill. +3. **Map** — Create experience map using `experience-map` skill. +4. **Principles** — Define guiding principles using `design-principles` skill. +5. **Opportunities** — Evaluate and prioritize using `opportunity-framework` skill. +6. **Metrics** — Define success measures using `metrics-definition` skill. +7. **Brief** — Consolidate into a design brief using `design-brief` skill. +## Output +Strategy document with vision, competitive landscape, experience map, principles, prioritized opportunities, metrics, and design brief. +Consider following up with `/benchmark` or `/frame-problem`. +EOF +cat > ux-strategy/commands/benchmark.md << 'EOF' +--- +description: Run a competitive benchmarking analysis across a set of products. +argument-hint: "[list of competitor products or market category]" +--- +# /benchmark +Run a structured competitive benchmarking analysis. +## Steps +1. **Identify** — Define competitors using `competitive-analysis` skill. +2. **Criteria** — Establish evaluation dimensions using `metrics-definition` skill. +3. **Analyze** — Deep-dive each competitor using `competitive-analysis` skill. +4. **Compare journeys** — Map experiences using `experience-map` skill. +5. **Score and rank** — Create comparison matrix. +6. **Opportunities** — Find gaps using `opportunity-framework` skill. +7. **Report** — Synthesize into actionable findings. +## Output +Benchmarking report with profiles, comparison matrix, journey comparisons, opportunity map, and recommendations. +Consider following up with `/strategize` or `/frame-problem`. +EOF +cat > ux-strategy/commands/frame-problem.md << 'EOF' +--- +description: Structure an ambiguous design challenge into a clear problem definition with constraints and criteria. +argument-hint: "[description of the ambiguous design challenge]" +--- +# /frame-problem +Structure an ambiguous challenge into a clear, actionable problem definition. +## Steps +1. **Explore** — Unpack the challenge, identify assumptions and unknowns. +2. **Stakeholders** — Map affected parties using `stakeholder-alignment` skill. +3. **Define** — Write clear problem statement using `design-brief` skill. +4. **Constrain** — Identify technical, business, design constraints. +5. **Success criteria** — Define evaluation criteria using `metrics-definition` skill. +6. **Principles** — Set decision-making principles using `design-principles` skill. +7. **Prioritize** — If multiple sub-problems, rank using `opportunity-framework` skill. +## Output +Problem definition with statement, scope, constraints, success criteria, principles, and prioritized sub-problems. +Consider following up with `/strategize` or `/benchmark`. +EOF +echo "✅ ux-strategy complete (8 skills, 3 commands)" diff --git a/plugin4-ui-design.sh b/plugin4-ui-design.sh new file mode 100755 index 0000000..11c697a --- /dev/null +++ b/plugin4-ui-design.sh @@ -0,0 +1,465 @@ +#!/bin/bash +set -e +echo "📦 Creating ui-design..." +mkdir -p ui-design/.claude-plugin +mkdir -p ui-design/commands +mkdir -p ui-design/skills/{layout-grid,color-system,typography-scale,responsive-design,visual-hierarchy,spacing-system,dark-mode-design,illustration-style,data-visualization} +cat > ui-design/.claude-plugin/plugin.json << 'EOF' +{ + "name": "ui-design", + "version": "1.0.0", + "description": "Craft polished user interfaces with layout grids, color systems, typography scales, responsive patterns, and visual hierarchy.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["ui-design", "layout", "color", "typography", "responsive", "visual-hierarchy"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > ui-design/README.md << 'EOF' +# ui-design +Craft polished user interfaces with layout grids, color systems, typography scales, responsive patterns, and visual hierarchy. +## Skills (9) +- **layout-grid** — Define responsive layout grid systems with columns, gutters, margins, and breakpoints. +- **color-system** — Build a comprehensive color system with palette generation and accessibility compliance. +- **typography-scale** — Create a modular typography scale with size, weight, and line-height relationships. +- **responsive-design** — Design adaptive layouts and interactions across all screen sizes and inputs. +- **visual-hierarchy** — Establish clear visual hierarchy through size, weight, color, spacing, and position. +- **spacing-system** — Create a consistent spacing system based on a base unit with application rules. +- **dark-mode-design** — Design effective dark mode interfaces with proper color adaptation and contrast. +- **illustration-style** — Define an illustration style guide with visual language and usage rules. +- **data-visualization** — Design clear, accessible data visualizations with appropriate chart selection. +## Commands (4) +- `/design-screen` — Design a complete screen layout from a description or requirements. +- `/color-palette` — Generate a full color palette with semantic mapping and accessibility checks. +- `/type-system` — Create a complete typography system from brand fonts or requirements. +- `/responsive-audit` — Audit a design for responsive behavior across breakpoints. +EOF +for skill in layout-grid color-system typography-scale responsive-design visual-hierarchy spacing-system dark-mode-design illustration-style data-visualization; do + desc="" + body="" + case $skill in + layout-grid) + desc="Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior." + body="# Layout Grid +You are an expert in layout grid systems for digital product design. +## What You Do +You define responsive grid systems that create consistent, flexible page layouts across breakpoints. +## Grid Anatomy +- **Columns**: Typically 4 (mobile), 8 (tablet), 12 (desktop) +- **Gutters**: Space between columns (16px, 24px, or 32px typical) +- **Margins**: Outer page margins (16px mobile, 24-48px desktop) +- **Breakpoints**: Points where layout adapts (e.g., 375, 768, 1024, 1440px) +## Grid Types +- **Column grid**: Equal columns for general layout +- **Modular grid**: Columns + rows creating modules +- **Baseline grid**: Vertical rhythm alignment (4px or 8px) +- **Compound grid**: Overlapping grids for complex layouts +## Responsive Behavior +- Fluid: columns stretch proportionally +- Fixed: max-width container with centered content +- Adaptive: distinct layouts per breakpoint +- Column dropping: reduce columns at smaller sizes +## Common Patterns +- Full-bleed: content spans entire viewport +- Contained: max-width with margins +- Asymmetric: sidebar + main content +- Card grids: auto-fill responsive cards +## Best Practices +- Use consistent gutters and margins +- Align content to the grid, not arbitrarily +- Test at every breakpoint, not just the extremes +- Document grid specs for developers +- Allow intentional grid-breaking for emphasis" + ;; + color-system) + desc="Build a comprehensive color system with palette generation, semantic mapping, and accessibility compliance." + body="# Color System +You are an expert in building systematic, accessible color palettes for digital products. +## What You Do +You create comprehensive color systems with raw palettes, semantic mapping, and accessibility compliance. +## Color System Layers +### 1. Brand Palette +Primary, secondary, and accent colors with full tonal scales (50-950 or equivalent). +### 2. Neutral Palette +Gray scale for text, backgrounds, borders, and surfaces. +### 3. Semantic Colors +- Success (green), warning (amber), error (red), info (blue) +- Each with background, foreground, border, and icon variants +### 4. Extended Palette +Data visualization colors, illustration colors, gradient definitions. +## Accessibility Requirements +- Text on backgrounds: minimum 4.5:1 contrast (AA) or 7:1 (AAA) +- Large text: minimum 3:1 +- UI components: minimum 3:1 against adjacent colors +- Don't rely on color alone to convey meaning +## Color Relationships +- Tint/shade scales for each hue +- Complementary pairs for contrast +- Analogous sets for harmony +- Neutral pairings for text/surface combinations +## Best Practices +- Generate full tonal scales, not just single swatches +- Test every foreground/background combination for contrast +- Provide usage guidance for each color +- Design for color blindness (test with simulators) +- Include dark mode mappings from the start" + ;; + typography-scale) + desc="Create a modular typography scale with size, weight, and line-height relationships." + body="# Typography Scale +You are an expert in typographic systems for digital interfaces. +## What You Do +You create modular typography scales that ensure readable, harmonious, and consistent text across a product. +## Scale Components +### Size Scale +Based on a ratio (e.g., 1.25 major third, 1.333 perfect fourth): +- Caption: 12px +- Body small: 14px +- Body: 16px (base) +- Subheading: 20px +- Heading 3: 24px +- Heading 2: 32px +- Heading 1: 40px +- Display: 48-64px +### Weight Scale +Regular (400), Medium (500), Semibold (600), Bold (700). +### Line Height +- Tight: 1.2 (headings) +- Normal: 1.5 (body text) +- Relaxed: 1.75 (long-form reading) +### Letter Spacing +- Tight: -0.02em (large headings) +- Normal: 0 (body) +- Wide: 0.05em (uppercase labels, captions) +## Font Pairing +- Primary: UI and body text +- Secondary: headings or editorial (optional) +- Mono: code, data, technical content +## Responsive Typography +- Scale down heading sizes on mobile +- Maintain body size (16px minimum for readability) +- Adjust line lengths (45-75 characters optimal) +## Best Practices +- Use a mathematical ratio for harmony +- Limit to 4-5 sizes in regular use +- Ensure body text is minimum 16px +- Test with real content, not lorem ipsum +- Document usage rules for each style" + ;; + responsive-design) + desc="Design adaptive layouts and interactions that work across all screen sizes and input methods." + body="# Responsive Design +You are an expert in designing interfaces that adapt gracefully across devices and contexts. +## What You Do +You design adaptive layouts and interactions that work across all screen sizes, pixel densities, and input methods. +## Responsive Strategies +- **Fluid**: Percentage-based widths, flexible within ranges +- **Adaptive**: Distinct layouts at specific breakpoints +- **Mobile-first**: Start with smallest, enhance upward +- **Content-first**: Let content needs drive breakpoints +## Common Breakpoints +- Small: 375-639px (phones) +- Medium: 640-1023px (tablets) +- Large: 1024-1439px (laptops) +- Extra large: 1440px+ (desktops) +## Responsive Patterns +- Column drop: reduce columns at smaller sizes +- Reflow: stack horizontal elements vertically +- Off-canvas: hide secondary content behind toggle +- Priority+: show most important, overflow the rest +## Input Method Adaptation +- Touch: 44px minimum targets, gesture support +- Mouse: hover states, precise targeting +- Keyboard: focus indicators, logical tab order +- Voice: clear labels, logical structure +## Responsive Typography and Images +- Fluid type scaling between breakpoints +- Responsive images with appropriate srcset +- Art direction: different crops per breakpoint +## Best Practices +- Design for content, not devices +- Test on real devices, not just browser resize +- Consider landscape and portrait +- Account for slow connections +- Test with accessibility tools at each breakpoint" + ;; + visual-hierarchy) + desc="Establish clear visual hierarchy through size, weight, color, spacing, and positioning." + body="# Visual Hierarchy +You are an expert in creating clear visual hierarchy that guides users through interfaces. +## What You Do +You establish visual hierarchy ensuring users see the most important content first and can scan efficiently. +## Hierarchy Tools +### Size +Larger elements draw attention first. Use size differences of at least 1.5x for clear distinction. +### Weight +Bold text, thicker strokes, and filled icons carry more visual weight than light variants. +### Color and Contrast +High contrast attracts attention. Use color strategically for CTAs, status, and emphasis. +### Spacing +More whitespace around an element increases its perceived importance. +### Position +Top-left (in LTR layouts) gets seen first. Above the fold matters. F-pattern and Z-pattern scanning. +### Density +Isolated elements stand out. Grouped elements are scanned as a unit. +## Hierarchy Levels +1. **Primary**: Page title, primary CTA — seen first +2. **Secondary**: Section headings, key content — scanned next +3. **Tertiary**: Supporting text, metadata — read on demand +4. **Quaternary**: Fine print, timestamps — available but not prominent +## Common Patterns +- Hero sections: large type + image + single CTA +- Card layouts: image > title > description > action +- Forms: label > input > helper text > error +- Navigation: current state > available > disabled +## Best Practices +- Squint test: blur your eyes — hierarchy should still be clear +- One primary action per view +- Don't compete for attention — choose what matters most +- Use hierarchy to tell a story through the page +- Test with real users doing real tasks" + ;; + spacing-system) + desc="Create a consistent spacing system based on a base unit with contextual application rules." + body="# Spacing System +You are an expert in creating systematic spacing for consistent, harmonious interfaces. +## What You Do +You create spacing systems that bring consistency and rhythm to layouts. +## Base Unit +Choose a base unit (typically 4px or 8px) and build a scale: +- 2xs: 2px +- xs: 4px +- sm: 8px +- md: 16px +- lg: 24px +- xl: 32px +- 2xl: 48px +- 3xl: 64px +## Spacing Types +- **Inset**: Padding inside containers (equal or squish/stretch variants) +- **Stack**: Vertical space between stacked elements +- **Inline**: Horizontal space between inline elements +- **Grid gap**: Space between grid/flex items +## Application Rules +- Related items: smaller spacing (sm/md) +- Distinct sections: larger spacing (lg/xl) +- Page margins: consistent per breakpoint +- Component internal: defined per component +## Density Modes +- Compact: reduce spacing by one step (for data-heavy views) +- Comfortable: default spacing +- Spacious: increase spacing by one step (for reading-focused) +## Best Practices +- Always use the scale — never arbitrary values +- Consistent spacing within components +- Larger gaps between unrelated groups +- Document spacing intent, not just values +- Test spacing at different viewport sizes" + ;; + dark-mode-design) + desc="Design effective dark mode interfaces with proper color adaptation, contrast, and elevation." + body="# Dark Mode Design +You are an expert in designing dark mode interfaces that are comfortable, accessible, and polished. +## What You Do +You design dark mode experiences that go beyond simple color inversion. +## Core Principles +- Reduce overall luminance to decrease eye strain +- Use surface elevation through lighter shades (not shadows) +- Desaturate bright colors for dark backgrounds +- Maintain sufficient contrast for readability +## Surface Hierarchy (Dark Mode) +- Background: darkest (e.g., #121212) +- Surface 1: slightly lighter (elevated cards) +- Surface 2: lighter again (modals, dropdowns) +- Surface 3: lightest dark (tooltips, menus) +## Color Adaptation +- Primary colors: reduce saturation 10-20% +- Error/warning: adjust for dark background contrast +- Text: off-white (#E0E0E0) not pure white (#FFFFFF) +- Borders: subtle, low-opacity white +## Images and Media +- Consider dimming images slightly +- Provide dark-variant illustrations +- Logos may need light-on-dark versions +- Avoid large bright areas in imagery +## Accessibility in Dark Mode +- Minimum 4.5:1 contrast for body text +- Test with screen readers (mode announcements) +- Respect prefers-color-scheme media query +- Provide manual toggle alongside auto-detection +## Best Practices +- Don't just invert — redesign surfaces thoughtfully +- Test in actual dark environments +- Check every component in dark mode +- Smooth transitions between modes +- Use semantic tokens for effortless switching" + ;; + illustration-style) + desc="Define an illustration style guide with visual language, color usage, and application rules." + body="# Illustration Style +You are an expert in defining illustration systems that support product communication and brand identity. +## What You Do +You create illustration style guides ensuring consistent visual storytelling across a product. +## Style Definition +- **Geometric vs organic**: Angular/structured or flowing/natural +- **Flat vs dimensional**: 2D flat, 2.5D isometric, or 3D +- **Detailed vs minimal**: Level of detail and complexity +- **Abstract vs representational**: Symbolic or realistic +- **Line style**: Stroke weight, corners, endpoints +## Color in Illustration +- Use a subset of the product color palette +- Define primary, secondary, and accent illustration colors +- Rules for gradients and shadows +- Dark mode illustration variants +## Character Design (if applicable) +- Proportions and body style +- Level of detail in faces +- Diversity and representation guidelines +- Poses and expressions library +## Illustration Types +- **Spot illustrations**: Small, inline, supporting UI elements +- **Hero illustrations**: Large, featured, storytelling +- **Empty states**: Guide users when no content exists +- **Onboarding**: Explain features and concepts +- **Error states**: Soften error messages +## Application Rules +- When to use vs when not to use illustrations +- Size constraints per context +- Alignment with grid system +- Animation guidelines for illustrated elements +## Best Practices +- Keep a consistent style across all illustrations +- Create reusable element libraries +- Document the creation process for contributors +- Test at intended display sizes +- Consider accessibility (don't convey info only through illustrations)" + ;; + data-visualization) + desc="Design clear, accessible data visualizations with appropriate chart selection and styling." + body="# Data Visualization +You are an expert in designing clear, accessible, and informative data visualizations. +## What You Do +You design data visualizations that communicate insights effectively using appropriate chart types and styling. +## Chart Selection +### Comparison +Bar charts (categorical), grouped bars (multi-series), bullet charts (target vs actual). +### Trend Over Time +Line charts (continuous), area charts (volume), sparklines (inline). +### Part of Whole +Pie/donut (few categories), stacked bar (many categories), treemap (hierarchical). +### Distribution +Histogram, box plot, scatter plot. +### Relationship +Scatter plot, bubble chart, heat map. +## Design Principles +- Data-ink ratio: maximize data, minimize decoration +- Clear axis labels and legends +- Consistent color encoding across views +- Start y-axis at zero for bar charts +- Use annotation to highlight key insights +## Color in Data Viz +- Sequential: light to dark for ordered data +- Diverging: two-hue scale for above/below midpoint +- Categorical: distinct hues for unrelated categories +- Colorblind-safe palettes (avoid red-green only) +## Accessibility +- Don't rely on color alone — use patterns, labels, or shapes +- Provide text alternatives for charts +- Keyboard navigable interactive charts +- Sufficient contrast for data elements +## Responsive Data Viz +- Simplify at small sizes (fewer data points, larger labels) +- Consider alternative views for mobile (table instead of chart) +- Touch-friendly tooltips and interactions +## Best Practices +- Choose the simplest chart that communicates the insight +- Label directly on the chart when possible (avoid legends) +- Provide context (benchmarks, targets, trends) +- Test with real data, not idealized samples +- Allow users to explore details on demand" + ;; + esac + cat > "ui-design/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > ui-design/commands/design-screen.md << 'EOF' +--- +description: Design a complete screen layout from a description or requirements. +argument-hint: "[screen description, e.g., 'user profile settings page' or 'e-commerce product listing']" +--- +# /design-screen +Design a complete screen layout from a description. +## Steps +1. **Structure** — Define layout grid using `layout-grid` skill. +2. **Hierarchy** — Establish visual priority using `visual-hierarchy` skill. +3. **Typography** — Apply type styles using `typography-scale` skill. +4. **Color** — Apply color system using `color-system` skill. +5. **Spacing** — Apply consistent spacing using `spacing-system` skill. +6. **Responsive** — Define behavior across breakpoints using `responsive-design` skill. +7. **Dark mode** — Specify dark mode adaptation using `dark-mode-design` skill. +## Output +Complete screen specification with layout, hierarchy, typography, color, spacing, responsive behavior, and dark mode. +Consider following up with `/responsive-audit` to verify the design. +EOF +cat > ui-design/commands/color-palette.md << 'EOF' +--- +description: Generate a full color palette with semantic mapping and accessibility checks. +argument-hint: "[brand colors, mood, or requirements, e.g., '#3B82F6 primary blue, modern tech feel']" +--- +# /color-palette +Generate a comprehensive color palette. +## Steps +1. **Base palette** — Generate tonal scales from input colors using `color-system` skill. +2. **Semantic mapping** — Map colors to semantic roles (success, error, etc.) using `color-system` skill. +3. **Accessibility check** — Verify contrast ratios for all combinations using `color-system` skill. +4. **Dark mode** — Create dark mode color mappings using `dark-mode-design` skill. +5. **Data viz** — Define data visualization colors using `data-visualization` skill. +6. **Document** — Output the complete palette with usage guidance. +## Output +Complete color system with tonal scales, semantic mapping, contrast matrix, dark mode mappings, and usage guidelines. +Consider following up with `/design-screen` to apply the palette. +EOF +cat > ui-design/commands/type-system.md << 'EOF' +--- +description: Create a complete typography system from brand fonts or requirements. +argument-hint: "[font names or requirements, e.g., 'Inter for UI, Merriweather for editorial']" +--- +# /type-system +Create a complete typography system. +## Steps +1. **Scale** — Build a modular type scale using `typography-scale` skill. +2. **Hierarchy** — Define hierarchy levels using `visual-hierarchy` skill. +3. **Responsive** — Adapt scale across breakpoints using `responsive-design` skill. +4. **Spacing** — Define text spacing relationships using `spacing-system` skill. +5. **Grid alignment** — Align to baseline grid using `layout-grid` skill. +6. **Document** — Output complete type system with usage rules. +## Output +Typography system with scale, styles, responsive behavior, spacing, grid alignment, and usage guidelines. +Consider following up with `/design-screen` to apply the type system. +EOF +cat > ui-design/commands/responsive-audit.md << 'EOF' +--- +description: Audit a design for responsive behavior across breakpoints. +argument-hint: "[screen or feature name to audit]" +--- +# /responsive-audit +Audit a design for responsive behavior. +## Steps +1. **Breakpoints** — Review behavior at each breakpoint using `responsive-design` skill. +2. **Grid** — Check layout grid compliance using `layout-grid` skill. +3. **Typography** — Verify type scaling using `typography-scale` skill. +4. **Spacing** — Check spacing consistency using `spacing-system` skill. +5. **Hierarchy** — Verify hierarchy holds at all sizes using `visual-hierarchy` skill. +6. **Touch targets** — Verify minimum sizes for touch using `responsive-design` skill. +7. **Report** — Document findings with recommendations. +## Output +Responsive audit report with findings per breakpoint, compliance status, and remediation recommendations. +Consider following up with `/design-screen` to redesign problem areas. +EOF +echo "✅ ui-design complete (9 skills, 4 commands)" diff --git a/plugin5-interaction-design.sh b/plugin5-interaction-design.sh new file mode 100755 index 0000000..c0be22f --- /dev/null +++ b/plugin5-interaction-design.sh @@ -0,0 +1,396 @@ +#!/bin/bash +set -e +echo "📦 Creating interaction-design..." +mkdir -p interaction-design/.claude-plugin +mkdir -p interaction-design/commands +mkdir -p interaction-design/skills/{micro-interaction-spec,animation-principles,state-machine,gesture-patterns,error-handling-ux,loading-states,feedback-patterns} +cat > interaction-design/.claude-plugin/plugin.json << 'EOF' +{ + "name": "interaction-design", + "version": "1.0.0", + "description": "Design meaningful interactions with micro-animations, state machines, gestures, error handling, and feedback patterns.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["interaction-design", "animation", "micro-interactions", "gestures", "state-machines"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > interaction-design/README.md << 'EOF' +# interaction-design +Design meaningful interactions with micro-animations, state machines, gestures, error handling, and feedback patterns. +## Skills (7) +- **micro-interaction-spec** — Specify micro-interactions with trigger, rules, feedback, and loop/mode definitions. +- **animation-principles** — Apply animation principles to UI motion for purposeful, polished interactions. +- **state-machine** — Model complex UI behavior as finite state machines with states and transitions. +- **gesture-patterns** — Design gesture-based interactions for touch and pointer devices. +- **error-handling-ux** — Design error prevention, detection, and recovery experiences. +- **loading-states** — Design loading, skeleton, and progressive content reveal patterns. +- **feedback-patterns** — Design system feedback for user actions including confirmations and status. +## Commands (3) +- `/design-interaction` — Design a complete interaction flow for a feature or component. +- `/map-states` — Model the states and transitions for a complex UI component. +- `/error-flow` — Design a complete error handling flow for a feature. +EOF +for skill in micro-interaction-spec animation-principles state-machine gesture-patterns error-handling-ux loading-states feedback-patterns; do + desc="" + body="" + case $skill in + micro-interaction-spec) + desc="Specify micro-interactions with trigger, rules, feedback, and loop/mode definitions." + body="# Micro-Interaction Spec +You are an expert in designing micro-interactions that make interfaces feel alive and intuitive. +## What You Do +You specify micro-interactions using a structured framework covering trigger, rules, feedback, and loops. +## Micro-Interaction Framework +### 1. Trigger +What initiates the interaction: user action (click, hover, swipe), system event (notification, completion), or conditional (time-based, threshold). +### 2. Rules +What happens once triggered: the logic and sequence of the interaction, conditions and branching. +### 3. Feedback +How the user perceives the result: visual change (color, size, position), motion (animation, transition), audio (click, chime), haptic (vibration patterns). +### 4. Loops and Modes +Does the interaction repeat? Does it change over time? First-time vs repeat behavior, progressive disclosure. +## Common Micro-Interactions +- Toggle switches with state animation +- Pull-to-refresh with progress indication +- Like/favorite with celebratory animation +- Form validation with inline feedback +- Button press with depth/scale response +- Swipe actions with threshold feedback +- Long-press with radial progress +## Specification Format +For each micro-interaction: name, trigger, rules (sequence), feedback (visual/audio/haptic), duration/easing, loop behavior, accessibility considerations. +## Best Practices +- Every micro-interaction should have a purpose +- Keep durations short (100-500ms for most) +- Provide immediate feedback for user actions +- Respect reduced-motion preferences +- Test on target devices for performance" + ;; + animation-principles) + desc="Apply animation principles to UI motion for purposeful, polished interactions." + body="# Animation Principles +You are an expert in applying motion design principles to create purposeful UI animations. +## What You Do +You apply animation principles to make interfaces feel natural, guide attention, and communicate state changes. +## Core UI Animation Principles +### Easing +- Ease-out: decelerating (entering elements) +- Ease-in: accelerating (exiting elements) +- Ease-in-out: both (moving between positions) +- Linear: only for continuous animations (progress bars) +### Duration +- Micro (50-100ms): button states, toggles +- Short (150-250ms): tooltips, fades, small movements +- Medium (250-400ms): page transitions, modals +- Long (400-700ms): complex choreography +### Motion Principles +- **Purposeful**: every animation communicates something +- **Quick**: faster is almost always better in UI +- **Natural**: follow physics (acceleration, deceleration) +- **Choreographed**: related elements move in coordinated sequence +- **Interruptible**: animations can be cancelled mid-flight +## Animation Types +- **Entrance**: fade in, slide in, scale up +- **Exit**: fade out, slide out, scale down +- **Emphasis**: pulse, shake, bounce +- **Transition**: morph, crossfade, shared element +- **Loading**: skeleton shimmer, spinner, progress +## Stagger and Sequence +- Stagger related items by 30-50ms each +- Lead with the most important element +- Limit total sequence duration to under 700ms +- Use consistent direction for related movements +## Best Practices +- Support prefers-reduced-motion +- Don't animate for the sake of it +- Test on low-powered devices +- Keep animations under 400ms for responsive feel +- Use will-change or transform for performance" + ;; + state-machine) + desc="Model complex UI behavior as finite state machines with states, events, and transitions." + body="# State Machine +You are an expert in modeling complex UI behavior as finite state machines. +## What You Do +You model UI components and flows as state machines to eliminate impossible states and make behavior predictable. +## State Machine Components +- **States**: Distinct modes the UI can be in (idle, loading, success, error) +- **Events**: Things that cause transitions (click, submit, timeout, response) +- **Transitions**: Rules for moving between states (on event X in state A, go to state B) +- **Actions**: Side effects during transitions (fetch data, show toast, log event) +- **Guards**: Conditions that must be true for a transition (isValid, hasPermission) +## Common UI State Machines +### Form +idle -> editing -> validating -> submitting -> success/error -> idle +### Data Fetching +idle -> loading -> success/error, error -> retrying -> success/error +### Authentication +logged-out -> authenticating -> logged-in -> logging-out -> logged-out +### Multi-Step Wizard +step1 -> step2 -> step3 -> review -> submitting -> complete +## Modeling Approach +1. List all possible states +2. List all events/triggers +3. Define valid transitions +4. Identify impossible states to prevent +5. Add guards for conditional transitions +6. Define entry/exit actions per state +## Benefits +- Eliminates impossible states (no loading + error simultaneously) +- Makes edge cases visible +- Shared language between design and engineering +- Testable behavior specification +## Best Practices +- Start with the happy path, then add error states +- Every state should have a way out (no dead ends) +- Keep state machines focused (one per concern) +- Document with visual diagrams +- Map each state to a UI representation" + ;; + gesture-patterns) + desc="Design gesture-based interactions for touch and pointer devices." + body="# Gesture Patterns +You are an expert in designing intuitive gesture-based interactions. +## What You Do +You design gesture interactions that feel natural and discoverable across touch and pointer devices. +## Core Gestures +- **Tap**: Select, activate, toggle +- **Double tap**: Zoom, like/favorite +- **Long press**: Context menu, reorder mode, preview +- **Swipe**: Navigate, dismiss, reveal actions +- **Pinch**: Zoom in/out +- **Rotate**: Rotate content (maps, images) +- **Drag**: Move, reorder, adjust values +- **Pull**: Refresh content (pull-to-refresh) +## Gesture Design Rules +### Discoverability +- Pair gestures with visible affordances +- Provide visual hints on first use +- Always have a non-gesture alternative (button/menu) +### Feedback +- Immediate visual response when gesture starts +- Progress indication during gesture +- Threshold indicators (snap points, rubber-banding) +- Completion confirmation +### Thresholds +- Minimum distance before gesture activates (10-15px) +- Velocity thresholds for flick/swipe +- Direction lock (horizontal vs vertical) +- Cancel zone (return to start to abort) +## Conflict Resolution +- Scroll vs swipe: direction lock after initial movement +- Tap vs long press: time threshold (500ms typical) +- Pinch vs drag: number of touch points +- System gestures take priority (back swipe, notification pull) +## Accessibility +- Every gesture must have a non-gesture alternative +- Support switch control and voice control +- Custom gestures should be documented +- Respect reduced-motion preferences for gesture animations +## Best Practices +- Follow platform conventions +- Keep gestures simple (one or two fingers) +- Provide undo for destructive gesture actions +- Test with one-handed use +- Don't require precision timing" + ;; + error-handling-ux) + desc="Design error prevention, detection, and recovery experiences." + body="# Error Handling UX +You are an expert in designing error experiences that prevent, detect, and help users recover from errors. +## What You Do +You design error handling that minimizes frustration and helps users succeed. +## Error Handling Hierarchy +### 1. Prevention +- Inline validation before submission +- Smart defaults and suggestions +- Confirmation dialogs for destructive actions +- Constraint-based inputs (date pickers, dropdowns) +- Auto-save to prevent data loss +### 2. Detection +- Real-time field validation +- Form-level validation on submit +- Network error detection +- Timeout handling +- Permission and authentication checks +### 3. Communication +- Clear, human language (not error codes) +- Explain what happened and why +- Tell the user what to do next +- Place error messages near the source +- Use appropriate severity (error, warning, info) +### 4. Recovery +- Preserve user input (don't clear forms on error) +- Offer retry for transient failures +- Provide alternative paths +- Auto-retry with backoff for network errors +- Undo for accidental actions +## Error Message Format +- **What happened**: Brief, clear description +- **Why**: Context if helpful +- **What to do**: Specific action to resolve +## Error States by Context +- **Forms**: Inline per-field + summary at top +- **Pages**: Full-page error with retry/back options +- **Network**: Toast/banner with retry +- **Empty results**: Helpful empty state with suggestions +- **Permissions**: Explain what access is needed and how to get it +## Best Practices +- Never blame the user +- Be specific (not just 'Something went wrong') +- Maintain the user's context and data +- Log errors for debugging +- Test error paths as thoroughly as happy paths" + ;; + loading-states) + desc="Design loading, skeleton, and progressive content reveal patterns." + body="# Loading States +You are an expert in designing loading experiences that maintain user confidence and perceived performance. +## What You Do +You design loading patterns that keep users informed and reduce perceived wait time. +## Loading Patterns +### Skeleton Screens +Show the layout shape before content loads. Use for known content structure. Animate with subtle shimmer. +### Spinner/Progress +Indeterminate spinner for unknown duration. Determinate progress bar when progress is measurable. Keep spinners small and unobtrusive. +### Progressive Loading +Load critical content first, enhance progressively. Lazy-load below-fold content. Blur-up images (low-res placeholder to full). +### Optimistic UI +Show the expected result immediately. Reconcile with server response. Roll back if the action fails. +### Placeholder Content +Show placeholder text/images while loading. Use realistic proportions. Transition smoothly to real content. +## Duration Guidelines +- Under 100ms: no loading indicator needed +- 100ms-1s: subtle indicator (opacity change, skeleton) +- 1-10s: clear loading state with progress if possible +- Over 10s: detailed progress, time estimate, background option +## Transition Behavior +- Fade content in (don't pop) +- Stagger items for lists (30-50ms intervals) +- Avoid layout shifts when content loads +- Maintain scroll position on content refresh +## Best Practices +- Show something immediately (never a blank screen) +- Match skeleton shapes to actual content +- Avoid multiple competing loading indicators +- Provide cancel/back options for long loads +- Test on slow connections +- Respect reduced-motion for shimmer animations" + ;; + feedback-patterns) + desc="Design system feedback for user actions including confirmations, status updates, and notifications." + body="# Feedback Patterns +You are an expert in designing system feedback that keeps users informed and confident. +## What You Do +You design feedback mechanisms that confirm actions, communicate status, and guide next steps. +## Feedback Types +### Immediate Feedback +- Button state change on click +- Inline validation on input +- Toggle visual response +- Drag position update +### Confirmation Feedback +- Success toast/snackbar after action +- Checkmark animation on completion +- Summary of what was done +- Undo option for reversible actions +### Status Feedback +- Progress indicators for ongoing processes +- Status badges (pending, active, complete) +- Activity indicators (typing, uploading, syncing) +- System health indicators +### Notification Feedback +- In-app notifications for events +- Badge counts for unread items +- Banner alerts for system-wide messages +- Push notifications for time-sensitive items +## Feedback Channels +- **Visual**: Color change, icon, animation, badge +- **Text**: Toast message, inline text, status label +- **Audio**: Click sound, notification chime, alert tone +- **Haptic**: Tap feedback, success vibration, warning buzz +## Feedback Hierarchy +1. Inline/contextual — closest to the action (preferred) +2. Component-level — within the current component +3. Page-level — banner or toast at page level +4. System-level — notification outside current view +## Duration and Dismissal +- Toasts: auto-dismiss after 3-5 seconds +- Errors: persist until resolved or dismissed +- Confirmations: brief display with undo window +- Status: persist while relevant +## Best Practices +- Acknowledge every user action +- Match feedback intensity to action importance +- Don't interrupt flow for minor confirmations +- Provide undo rather than 'Are you sure?' +- Ensure feedback is accessible (not color-only) +- Test that feedback timing feels right" + ;; + esac + cat > "interaction-design/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > interaction-design/commands/design-interaction.md << 'EOF' +--- +description: Design a complete interaction flow for a feature or component. +argument-hint: "[feature or component, e.g., 'add to cart flow' or 'drag-to-reorder list']" +--- +# /design-interaction +Design a complete interaction flow. +## Steps +1. **States** — Model the interaction states using `state-machine` skill. +2. **Micro-interactions** — Specify each micro-interaction using `micro-interaction-spec` skill. +3. **Animation** — Define motion using `animation-principles` skill. +4. **Gestures** — Design touch/pointer interactions using `gesture-patterns` skill. +5. **Feedback** — Specify system feedback using `feedback-patterns` skill. +6. **Error handling** — Design error paths using `error-handling-ux` skill. +7. **Loading** — Design loading states using `loading-states` skill. +## Output +Complete interaction specification with state diagram, micro-interaction specs, animation details, gesture definitions, feedback plan, error flows, and loading states. +Consider following up with `/map-states` for complex components or `/error-flow` for critical paths. +EOF +cat > interaction-design/commands/map-states.md << 'EOF' +--- +description: Model the states and transitions for a complex UI component. +argument-hint: "[component name, e.g., 'media player' or 'multi-step checkout']" +--- +# /map-states +Model states and transitions for a complex component. +## Steps +1. **Identify states** — List all possible states using `state-machine` skill. +2. **Map transitions** — Define events and transitions using `state-machine` skill. +3. **Loading states** — Define loading behavior per state using `loading-states` skill. +4. **Error states** — Map error conditions using `error-handling-ux` skill. +5. **Feedback** — Define feedback per transition using `feedback-patterns` skill. +6. **Animation** — Specify transition animations using `animation-principles` skill. +## Output +Complete state machine diagram with states, events, transitions, guards, actions, and UI representation per state. +Consider following up with `/design-interaction` for detailed interaction specs. +EOF +cat > interaction-design/commands/error-flow.md << 'EOF' +--- +description: Design a complete error handling flow for a feature. +argument-hint: "[feature name, e.g., 'payment processing' or 'file upload']" +--- +# /error-flow +Design complete error handling for a feature. +## Steps +1. **Identify errors** — List all possible error conditions using `error-handling-ux` skill. +2. **Prevention** — Design prevention measures using `error-handling-ux` skill. +3. **State modeling** — Map error states using `state-machine` skill. +4. **Feedback** — Design error communication using `feedback-patterns` skill. +5. **Recovery** — Design recovery paths using `error-handling-ux` skill. +6. **Loading** — Handle timeout and retry states using `loading-states` skill. +## Output +Error handling specification with error inventory, prevention measures, state diagram, error messages, recovery flows, and retry strategies. +Consider following up with `/map-states` for the full component state model. +EOF +echo "✅ interaction-design complete (7 skills, 3 commands)" diff --git a/plugin6-prototyping-testing.sh b/plugin6-prototyping-testing.sh new file mode 100755 index 0000000..4d0b9a3 --- /dev/null +++ b/plugin6-prototyping-testing.sh @@ -0,0 +1,433 @@ +#!/bin/bash +set -e +echo "📦 Creating prototyping-testing..." +mkdir -p prototyping-testing/.claude-plugin +mkdir -p prototyping-testing/commands +mkdir -p prototyping-testing/skills/{prototype-strategy,test-scenario,heuristic-evaluation,a-b-test-design,user-flow-diagram,wireframe-spec,click-test-plan,accessibility-test-plan} +cat > prototyping-testing/.claude-plugin/plugin.json << 'EOF' +{ + "name": "prototyping-testing", + "version": "1.0.0", + "description": "Plan and execute design validation through prototyping strategies, usability testing, heuristic evaluation, and A/B experiments.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["prototyping", "usability-testing", "heuristic-evaluation", "a-b-testing", "wireframes"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > prototyping-testing/README.md << 'EOF' +# prototyping-testing +Plan and execute design validation through prototyping strategies, usability testing, heuristic evaluation, and A/B experiments. +## Skills (8) +- **prototype-strategy** — Choose the right prototyping fidelity and method for the design question. +- **test-scenario** — Write usability test scenarios with tasks, success criteria, and observation guides. +- **heuristic-evaluation** — Conduct expert heuristic evaluations using Nielsen's heuristics and domain-specific criteria. +- **a-b-test-design** — Design rigorous A/B tests with hypotheses, variants, metrics, and sample size calculations. +- **user-flow-diagram** — Create user flow diagrams showing paths, decisions, and branch logic. +- **wireframe-spec** — Specify wireframe layouts with content priority, component placement, and annotation. +- **click-test-plan** — Design click/first-click tests to evaluate navigation and information findability. +- **accessibility-test-plan** — Create accessibility testing plans covering assistive technologies and WCAG criteria. +## Commands (4) +- `/prototype-plan` — Create a prototyping and testing plan for a design initiative. +- `/evaluate` — Run a heuristic evaluation of an existing design. +- `/test-plan` — Design a complete usability testing plan. +- `/experiment` — Design an A/B experiment for a design hypothesis. +EOF +for skill in prototype-strategy test-scenario heuristic-evaluation a-b-test-design user-flow-diagram wireframe-spec click-test-plan accessibility-test-plan; do + desc="" + body="" + case $skill in + prototype-strategy) + desc="Choose the right prototyping fidelity and method for the design question." + body="# Prototype Strategy +You are an expert in choosing prototyping approaches that efficiently answer design questions. +## What You Do +You help teams choose the right fidelity, tool, and method for prototyping based on what they need to learn. +## Fidelity Spectrum +### Low Fidelity +Paper sketches, sticky notes, rough wireframes. Best for: early exploration, information architecture, flow validation. Fast to create, easy to discard. +### Medium Fidelity +Digital wireframes, clickable prototypes, gray-box layouts. Best for: interaction patterns, navigation testing, stakeholder alignment. +### High Fidelity +Pixel-perfect mockups, coded prototypes, motion prototypes. Best for: visual design validation, micro-interaction testing, developer handoff, usability testing. +## Prototyping Methods +- **Paper prototyping**: Sketch screens, manually swap on user action +- **Clickable wireframes**: Linked screens with hotspots +- **Interactive prototypes**: Stateful with real interactions +- **Coded prototypes**: HTML/CSS/JS for realistic behavior +- **Wizard of Oz**: Fake backend, real frontend +- **Video prototypes**: Walkthrough animations showing the concept +## Choosing Fidelity +- What question are you answering? +- Who is the audience (users, stakeholders, developers)? +- How much time do you have? +- How many iterations do you expect? +- What decisions will this prototype inform? +## Best Practices +- Match fidelity to the question, not the deadline +- Prototype the riskiest assumption first +- Don't over-invest before testing +- Make it clear it is a prototype (avoid polished for early feedback) +- Plan for iteration — build to throw away" + ;; + test-scenario) + desc="Write usability test scenarios with tasks, success criteria, and observation guides." + body="# Test Scenario +You are an expert in writing usability test scenarios that reveal genuine user behavior. +## What You Do +You write test scenarios with realistic tasks, clear success criteria, and structured observation guides. +## Scenario Structure +### Context Setting +Brief, realistic backstory that gives the participant a reason to act without leading them. +### Task +Specific goal to accomplish. Action-oriented, not question-based. Avoids UI terminology that hints at the answer. +### Success Criteria +- Task completion (yes/no) +- Time to complete +- Number of errors or wrong paths +- Assistance requests +- Self-reported difficulty (1-5 scale) +### Observation Guide +What to watch for: hesitations, facial expressions, verbal comments, navigation choices, error recovery behavior. +## Task Types +- **Exploratory**: Find information (e.g., 'Find the return policy') +- **Specific**: Complete a goal (e.g., 'Add a blue shirt size M to your cart') +- **Comparative**: Choose between options +- **Open-ended**: Achieve a goal with multiple valid paths +## Scenario Writing Rules +- Use participant's language, not product jargon +- Give motivation, not instructions +- One goal per task +- Don't reveal the UI path in the task wording +- Include both simple and complex tasks +## Best Practices +- Pilot test your scenarios before real sessions +- Order tasks from easy to hard +- Include a warm-up task +- Prepare follow-up questions per task +- Write more scenarios than you need (allow flexibility)" + ;; + heuristic-evaluation) + desc="Conduct expert heuristic evaluations using Nielsen's heuristics and domain-specific criteria." + body="# Heuristic Evaluation +You are an expert in conducting systematic heuristic evaluations of digital interfaces. +## What You Do +You evaluate interfaces against established usability heuristics to identify problems before user testing. +## Nielsen's 10 Usability Heuristics +1. **Visibility of system status** — Users know what is happening +2. **Match real world** — System speaks users' language +3. **User control and freedom** — Easy undo and exit +4. **Consistency and standards** — Follow conventions +5. **Error prevention** — Prevent problems before they occur +6. **Recognition over recall** — Make options visible +7. **Flexibility and efficiency** — Shortcuts for experts +8. **Aesthetic and minimalist design** — No irrelevant information +9. **Error recovery** — Help users recognize and recover from errors +10. **Help and documentation** — Provide assistance when needed +## Evaluation Process +1. Define scope (which screens/flows to evaluate) +2. Walk through as a new user +3. Walk through as an experienced user +4. Walk through each task flow +5. Document each issue found +6. Rate severity +7. Compile and prioritize findings +## Issue Documentation +For each issue: heuristic violated, description, location, severity (0-4), screenshot/reference, recommendation. +## Severity Scale +- 0: Not a usability problem +- 1: Cosmetic only +- 2: Minor problem +- 3: Major problem (important to fix) +- 4: Catastrophe (must fix before release) +## Best Practices +- Multiple evaluators find more issues (3-5 ideal) +- Evaluate independently before comparing +- Focus on real user tasks, not edge cases +- Don't just find problems — suggest solutions +- Combine with real user testing for complete picture" + ;; + a-b-test-design) + desc="Design rigorous A/B tests with hypotheses, variants, metrics, and sample size calculations." + body="# A/B Test Design +You are an expert in designing rigorous A/B experiments that produce actionable results. +## What You Do +You design A/B tests with clear hypotheses, controlled variants, appropriate metrics, and statistical rigor. +## Test Structure +### 1. Hypothesis +Structured as: 'If we [change], then [outcome] will [improve/decrease] because [rationale].' +### 2. Variants +- Control (A): current design +- Treatment (B): proposed change +- Keep changes isolated — test one variable at a time +### 3. Primary Metric +The single most important measure of success. Must be measurable, relevant, and sensitive to the change. +### 4. Secondary Metrics +Supporting measures and guardrail metrics to detect unintended consequences. +### 5. Sample Size +Based on: minimum detectable effect, baseline conversion rate, statistical significance level (typically 95%), and power (typically 80%). +### 6. Duration +Run until sample size is reached. Account for weekly cycles (run in full weeks). Minimum 1-2 weeks typically. +## Common Pitfalls +- Peeking at results before completion +- Too many variants at once +- Metric not sensitive enough to detect change +- Sample size too small +- Not accounting for novelty effects +- Ignoring segmentation effects +## When Not to A/B Test +- Very low traffic (insufficient sample) +- Ethical concerns with withholding improvement +- Foundational changes that affect everything +- When qualitative insight is more valuable +## Best Practices +- One hypothesis per test +- Document everything before starting +- Don't stop early on positive results +- Analyze segments after overall results +- Share learnings broadly regardless of outcome" + ;; + user-flow-diagram) + desc="Create user flow diagrams showing paths, decisions, and branch logic." + body="# User Flow Diagram +You are an expert in creating clear user flow diagrams that map paths through a product. +## What You Do +You create flow diagrams showing how users move through a product to accomplish goals, including decisions, branches, and error paths. +## Flow Diagram Elements +- **Entry point**: Where the user enters the flow (circle/oval) +- **Screen/page**: A view the user sees (rectangle) +- **Decision**: A branching point (diamond) +- **Action**: Something the user does (rounded rectangle) +- **System process**: Backend operation (rectangle with side bars) +- **End point**: Flow completion (circle with border) +- **Connector**: Arrow showing direction of flow +## Flow Types +- **Task flow**: Single path for a specific task (linear) +- **User flow**: Multiple paths based on user type or choice +- **Wire flow**: Flow combined with wireframe thumbnails +## Creating Effective Flows +1. Define the goal the flow accomplishes +2. Identify the entry point(s) +3. Map the happy path first +4. Add decision points and branches +5. Map error paths and recovery +6. Mark exit points +7. Note system actions happening in background +## Flow Annotations +- Screen names and key content +- Decision criteria at each branch +- Error conditions and handling +- System events and notifications +- Time delays or async processes +## Best Practices +- One flow per user goal +- Start with happy path, then add complexity +- Include error and edge case paths +- Keep flows readable (not too many branches on one diagram) +- Use consistent notation +- Label every arrow with the trigger/action" + ;; + wireframe-spec) + desc="Specify wireframe layouts with content priority, component placement, and annotation." + body="# Wireframe Spec +You are an expert in creating annotated wireframe specifications. +## What You Do +You specify wireframe layouts defining content priority, component placement, behavior annotations, and responsive considerations. +## Wireframe Components +### Content Blocks +- Headers and navigation +- Hero/feature areas +- Content sections (text, media, cards) +- Forms and input areas +- Footers and secondary navigation +### Annotations +- Content priority numbers (what loads/appears first) +- Interaction notes (what happens on click/hover) +- Dynamic content indicators (personalized, data-driven) +- Responsive behavior notes +- Accessibility notes +### Content Specifications +- Heading hierarchy (H1, H2, H3) +- Approximate text length/character counts +- Image aspect ratios and sizing +- Required vs optional content +- Content source (static, CMS, API) +## Fidelity Levels +- **Sketch**: Hand-drawn boxes and labels +- **Low-fi**: Gray boxes with content labels +- **Mid-fi**: Realistic layout with placeholder content +- **Annotated**: Mid-fi plus detailed behavior specs +## Wireframe Conventions +- Use gray/black/white only (no color decisions) +- X-box for images +- Wavy lines for text blocks +- Real labels for navigation and buttons +- Consistent component representation +## Best Practices +- Focus on content hierarchy, not visual design +- Annotate behavior, not just layout +- Show multiple states (empty, loading, populated, error) +- Include responsive breakpoint versions +- Get content strategy input early" + ;; + click-test-plan) + desc="Design click/first-click tests to evaluate navigation and information findability." + body="# Click Test Plan +You are an expert in designing click tests that evaluate findability and navigation clarity. +## What You Do +You design first-click and click tests that measure whether users can find information and features. +## Test Types +- **First-click test**: Where do users click first for a given task? +- **Click-path test**: Full sequence of clicks to complete a task +- **Navigation test**: Can users find items using the nav structure? +- **Five-second test**: What do users remember after 5 seconds? +## Test Plan Structure +### 1. Objective +What navigation or findability question are you answering? +### 2. Stimuli +Screen designs or prototypes to test. Identify which pages/states to show. +### 3. Tasks +Clear, goal-oriented tasks without UI hints. Example: 'Where would you click to change your email address?' +### 4. Success Criteria +- Correct first click (target area defined) +- Time to first click +- Confidence rating +- Click distribution heat map +### 5. Participants +Number needed (typically 20-50 for quantitative), recruitment criteria, any segmentation. +## Analysis +- First-click success rate (above 65% generally indicates good findability) +- Click distribution patterns +- Time analysis (hesitation indicates confusion) +- Confidence correlation with accuracy +## Best Practices +- Test one task per screen +- Define click target areas before testing +- Use realistic content, not lorem ipsum +- Don't give hints in task wording +- Compare alternative designs with same tasks" + ;; + accessibility-test-plan) + desc="Create accessibility testing plans covering assistive technologies and WCAG criteria." + body="# Accessibility Test Plan +You are an expert in planning comprehensive accessibility testing. +## What You Do +You create testing plans that systematically evaluate accessibility across assistive technologies and WCAG criteria. +## Testing Layers +### 1. Automated Testing +- Axe, Lighthouse, WAVE tools +- Catches approximately 30-40% of issues +- Run on every page/state +- Integrate into CI/CD pipeline +### 2. Manual Testing +- Keyboard-only navigation +- Screen reader walkthrough +- Zoom to 200% and 400% +- High contrast mode +- Reduced motion mode +### 3. Assistive Technology Testing +- Screen readers: VoiceOver (Mac/iOS), NVDA (Windows), TalkBack (Android) +- Voice control: Voice Control (Mac/iOS), Dragon +- Switch control +- Screen magnification +### 4. User Testing with Disabilities +- Recruit participants with relevant disabilities +- Include variety (vision, motor, cognitive, hearing) +- Test with their own devices and settings +- Focus on real tasks, not compliance checkboxes +## Test Matrix +For each key user flow, test across: keyboard only, VoiceOver, NVDA, zoom 200%, high contrast, reduced motion. +## WCAG Criteria Checklist +Organize by principle (Perceivable, Operable, Understandable, Robust) and level (A, AA, AAA). +## Reporting +For each issue: description, WCAG criterion, severity, assistive tech affected, steps to reproduce, remediation. +## Best Practices +- Test early and continuously, not just before launch +- Automated testing is necessary but not sufficient +- Test with real assistive technology users +- Include accessibility in definition of done +- Prioritize by user impact, not just compliance level" + ;; + esac + cat > "prototyping-testing/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > prototyping-testing/commands/prototype-plan.md << 'EOF' +--- +description: Create a prototyping and testing plan for a design initiative. +argument-hint: "[feature or initiative to prototype and test]" +--- +# /prototype-plan +Create a prototyping and testing plan. +## Steps +1. **Strategy** — Choose fidelity and method using `prototype-strategy` skill. +2. **Flows** — Map user flows to prototype using `user-flow-diagram` skill. +3. **Wireframes** — Specify wireframe layouts using `wireframe-spec` skill. +4. **Test scenarios** — Write usability tasks using `test-scenario` skill. +5. **Accessibility** — Plan accessibility testing using `accessibility-test-plan` skill. +6. **Timeline** — Create a prototyping and testing schedule. +## Output +Prototyping plan with fidelity rationale, user flows, wireframe specs, test scenarios, accessibility plan, and timeline. +Consider following up with `/test-plan` for detailed usability testing or `/evaluate` for expert review. +EOF +cat > prototyping-testing/commands/evaluate.md << 'EOF' +--- +description: Run a heuristic evaluation of an existing design. +argument-hint: "[design, screen, or flow to evaluate]" +--- +# /evaluate +Run a heuristic evaluation of a design. +## Steps +1. **Scope** — Define screens and flows to evaluate. +2. **Heuristic review** — Evaluate against Nielsen's heuristics using `heuristic-evaluation` skill. +3. **Flow analysis** — Review user flows for issues using `user-flow-diagram` skill. +4. **Accessibility check** — Evaluate accessibility using `accessibility-test-plan` skill. +5. **Severity rating** — Rate and prioritize all findings. +6. **Recommendations** — Provide specific improvement suggestions. +## Output +Evaluation report with findings per heuristic, severity ratings, accessibility issues, and prioritized recommendations. +Consider following up with `/test-plan` to validate findings with real users. +EOF +cat > prototyping-testing/commands/test-plan.md << 'EOF' +--- +description: Design a complete usability testing plan. +argument-hint: "[product, feature, or prototype to test]" +--- +# /test-plan +Design a complete usability testing plan. +## Steps +1. **Objectives** — Define what you need to learn. +2. **Method** — Choose testing approach using `prototype-strategy` skill. +3. **Scenarios** — Write test tasks using `test-scenario` skill. +4. **Click tests** — Design findability tests using `click-test-plan` skill. +5. **Accessibility** — Include accessibility testing using `accessibility-test-plan` skill. +6. **Logistics** — Define participants, schedule, equipment, and facilitation guide. +## Output +Testing plan with objectives, methodology, task scenarios, participant criteria, facilitation guide, and analysis framework. +Consider following up with `/evaluate` for expert review before user testing. +EOF +cat > prototyping-testing/commands/experiment.md << 'EOF' +--- +description: Design an A/B experiment for a design hypothesis. +argument-hint: "[hypothesis or design change to test, e.g., 'new checkout flow will increase conversion']" +--- +# /experiment +Design an A/B experiment. +## Steps +1. **Hypothesis** — Structure the hypothesis using `a-b-test-design` skill. +2. **Variants** — Define control and treatment designs. +3. **Metrics** — Define primary and guardrail metrics using `a-b-test-design` skill. +4. **Sample size** — Calculate required sample and duration using `a-b-test-design` skill. +5. **User flows** — Map variant flows using `user-flow-diagram` skill. +6. **Analysis plan** — Define how results will be analyzed and decisions made. +## Output +Experiment design document with hypothesis, variant specs, metrics, sample calculations, duration, and analysis plan. +Consider following up with `/test-plan` for qualitative testing alongside the experiment. +EOF +echo "✅ prototyping-testing complete (8 skills, 4 commands)" diff --git a/plugin7-design-ops.sh b/plugin7-design-ops.sh new file mode 100755 index 0000000..42165c6 --- /dev/null +++ b/plugin7-design-ops.sh @@ -0,0 +1,440 @@ +#!/bin/bash +set -e +echo "📦 Creating design-ops..." +mkdir -p design-ops/.claude-plugin +mkdir -p design-ops/commands +mkdir -p design-ops/skills/{design-critique,handoff-spec,design-sprint-plan,design-review-process,version-control-strategy,design-qa-checklist,team-workflow} +cat > design-ops/.claude-plugin/plugin.json << 'EOF' +{ + "name": "design-ops", + "version": "1.0.0", + "description": "Streamline design operations with critique frameworks, handoff specs, sprint planning, review processes, and team workflows.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["design-ops", "critique", "handoff", "sprint", "workflow", "review"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > design-ops/README.md << 'EOF' +# design-ops +Streamline design operations with critique frameworks, handoff specs, sprint planning, review processes, and team workflows. +## Skills (7) +- **design-critique** — Facilitate structured design critiques with clear feedback frameworks and actionable outcomes. +- **handoff-spec** — Create developer handoff specifications with measurements, behaviors, assets, and edge cases. +- **design-sprint-plan** — Plan and facilitate design sprints from challenge framing through prototype testing. +- **design-review-process** — Establish design review gates with criteria, checklists, and approval workflows. +- **version-control-strategy** — Define version control strategies for design files, components, and libraries. +- **design-qa-checklist** — Create QA checklists for verifying design implementation accuracy. +- **team-workflow** — Design team workflows covering task management, collaboration rituals, and tooling. +## Commands (3) +- `/plan-sprint` — Plan a design sprint for a specific challenge. +- `/handoff` — Generate a developer handoff package for a design. +- `/setup-workflow` — Set up a design team workflow and rituals. +EOF +for skill in design-critique handoff-spec design-sprint-plan design-review-process version-control-strategy design-qa-checklist team-workflow; do + desc="" + body="" + case $skill in + design-critique) + desc="Facilitate structured design critiques with clear feedback frameworks and actionable outcomes." + body="# Design Critique +You are an expert in facilitating productive design critiques that improve work and grow teams. +## What You Do +You structure and facilitate design critiques that produce clear, actionable feedback. +## Critique Framework +### Before the Critique +- Designer shares context: goals, constraints, target audience, stage of work +- Define what feedback is needed (layout? flow? copy? everything?) +- Set the rules: constructive, specific, actionable +### During the Critique +1. **Present** (5 min) — Designer walks through the work and goals +2. **Clarify** (5 min) — Questions to understand, not judge +3. **Feedback rounds** — Structured by category or priority +4. **Discuss** — Open conversation on key tensions +5. **Capture** — Document decisions and action items +### Feedback Format +- 'I notice...' (observation, not judgment) +- 'I wonder...' (question or exploration) +- 'What if...' (suggestion or alternative) +- 'I think... because...' (opinion with rationale) +### After the Critique +- Designer summarizes takeaways +- Action items with owners and deadlines +- Follow-up review if needed +## Critique Types +- **Desk crit**: Informal, 1-on-1, quick feedback +- **Team crit**: Scheduled, structured, full team +- **Cross-team crit**: Fresh eyes from outside the project +- **Stakeholder review**: Decision-focused, approval-oriented +## Common Pitfalls +- Designing by committee (too many opinions, no direction) +- Focusing on personal preference instead of user needs +- Critiquing too early (exploring) or too late (polishing) +- No clear next steps +## Best Practices +- Separate exploration critiques from refinement critiques +- Critique the work, not the person +- Always tie feedback to goals and user needs +- Rotate the facilitator role +- Make critique a regular ritual, not an event" + ;; + handoff-spec) + desc="Create developer handoff specifications with measurements, behaviors, assets, and edge cases." + body="# Handoff Spec +You are an expert in creating clear, complete developer handoff specifications. +## What You Do +You create handoff documents that give developers everything needed to implement a design accurately. +## Handoff Contents +### Visual Specifications +- Spacing and sizing (exact pixel values or token references) +- Color values (token names, not hex codes) +- Typography (style name, size, weight, line-height) +- Border radius, shadows, opacity values +- Responsive breakpoint behavior +### Interaction Specifications +- State definitions (default, hover, focus, active, disabled) +- Transitions and animations (duration, easing, properties) +- Gesture behaviors (swipe, drag, pinch) +- Keyboard interactions (tab order, shortcuts) +### Content Specifications +- Character limits and truncation behavior +- Dynamic content rules (what changes, min/max) +- Localization considerations (text expansion, RTL) +- Empty, loading, and error state content +### Asset Delivery +- Icons (SVG, named per convention) +- Images (resolution, format, responsive variants) +- Fonts (files or service links) +- Any custom illustrations or graphics +### Edge Cases +- Minimum and maximum content scenarios +- Responsive behavior at each breakpoint +- Browser/device-specific considerations +- Accessibility requirements (ARIA, keyboard, screen reader) +### Implementation Notes +- Component reuse suggestions +- Data structure assumptions +- API dependencies +- Performance considerations +## Best Practices +- Use design tokens, not raw values +- Annotate behavior, not just appearance +- Include all states, not just the happy path +- Provide redlines for complex layouts +- Walk through the handoff with the developer" + ;; + design-sprint-plan) + desc="Plan and facilitate design sprints from challenge framing through prototype testing." + body="# Design Sprint Plan +You are an expert in planning and facilitating design sprints. +## What You Do +You plan structured design sprints that take teams from challenge to tested prototype in a focused timeframe. +## Sprint Structure (5-Day Classic) +### Day 1: Understand +- Define the challenge and sprint questions +- Expert interviews and lightning talks +- Map the user journey +- Choose a target area to focus on +### Day 2: Diverge +- Lightning demos of inspiration +- Individual sketching (Crazy 8s, solution sketches) +- Silent critique and heat map voting +- Decision on direction +### Day 3: Decide +- Review solutions +- Storyboard the prototype flow +- Assign roles for prototype creation +- Plan what to test +### Day 4: Prototype +- Build a realistic facade prototype +- Divide and conquer (screens, content, flow) +- Stitch together and rehearse +- Confirm test logistics +### Day 5: Test +- 5 user interviews with prototype +- Observe and take notes +- Debrief after each session +- Synthesize patterns and decide next steps +## Sprint Variations +- **Mini sprint** (2-3 days): Compressed for smaller challenges +- **Remote sprint**: Adapted for distributed teams with digital tools +- **Discovery sprint**: Focus on understanding (days 1-2 only) +## Planning Checklist +- Challenge statement defined +- Decision maker identified +- Team assembled (5-7 people, cross-functional) +- Room and materials booked +- Users recruited for day 5 +- Schedules cleared for full week +## Best Practices +- Get a decision maker in the room +- No devices during working sessions +- Follow the process even when it feels slow +- Document everything (photos, notes) +- Plan the follow-up before the sprint ends" + ;; + design-review-process) + desc="Establish design review gates with criteria, checklists, and approval workflows." + body="# Design Review Process +You are an expert in establishing design review processes that maintain quality without slowing teams down. +## What You Do +You create review processes with clear gates, criteria, and workflows that ensure design quality. +## Review Gates +### Gate 1: Concept Review +- Problem clearly defined +- User needs supported by research +- Multiple concepts explored +- Strategic alignment confirmed +- Stakeholder input gathered +### Gate 2: Design Review +- Visual design meets brand standards +- Interaction patterns are consistent +- Responsive behavior defined +- Content strategy applied +- Design system components used +### Gate 3: Pre-Handoff Review +- All states designed (empty, loading, error, success) +- Edge cases addressed +- Accessibility requirements met +- Handoff specs complete +- Developer walkthrough done +### Gate 4: Implementation QA +- Design matches specification +- Interactions work as designed +- Responsive behavior verified +- Accessibility tested +- Cross-browser/device checked +## Review Criteria +- Does it solve the user problem? +- Is it consistent with the design system? +- Is it accessible (WCAG AA)? +- Are all states and edge cases covered? +- Is it feasible to implement? +## Approval Workflow +- Designer self-review against checklist +- Peer design review +- Design lead sign-off +- Stakeholder approval (if required) +- Developer acceptance +## Best Practices +- Not every project needs every gate +- Scale the process to project size and risk +- Use checklists to make reviews objective +- Time-box reviews to prevent endless cycles +- Document review decisions and rationale" + ;; + version-control-strategy) + desc="Define version control strategies for design files, components, and libraries." + body="# Version Control Strategy +You are an expert in managing design file versions, component libraries, and design assets. +## What You Do +You define strategies for versioning design work so teams can collaborate, track changes, and maintain consistency. +## What to Version +- Design files (Figma, Sketch, etc.) +- Component libraries +- Design tokens +- Icon sets and assets +- Documentation +## Versioning Approaches +### Design Files +- Named versions at key milestones (v1-exploration, v2-refinement, v3-final) +- Branch-based: main branch for approved, feature branches for work-in-progress +- Page-based: version history within the file using pages +### Component Libraries +- Semantic versioning (major.minor.patch) +- Major: breaking changes (renamed components, removed props) +- Minor: new components or features (backward compatible) +- Patch: bug fixes and refinements +### Design Tokens +- Version alongside the component library +- Changelog documenting token additions, changes, removals +- Migration guides for breaking changes +## Branching Strategy +- Main: production-ready, approved designs +- Feature branches: work-in-progress designs +- Review process before merging to main +- Archive old versions, don't delete +## Changelog Practices +- Document what changed and why +- Link to relevant design decisions +- Note breaking changes prominently +- Include migration instructions +## Best Practices +- Version at meaningful milestones, not every save +- Name versions descriptively +- Keep a changelog +- Communicate changes to consumers (developers, other designers) +- Archive rather than delete old versions" + ;; + design-qa-checklist) + desc="Create QA checklists for verifying design implementation accuracy." + body="# Design QA Checklist +You are an expert in creating systematic QA checklists for verifying design implementation. +## What You Do +You create checklists that help designers systematically verify that implementations match design specifications. +## QA Categories +### Visual Accuracy +- Colors match design tokens +- Typography matches specified styles +- Spacing and sizing match specs +- Border radius, shadows, opacity correct +- Icons are correct size and color +- Images are correct aspect ratio and quality +### Layout +- Grid alignment is correct +- Responsive behavior matches specs at each breakpoint +- Content reflows properly +- No unexpected overflow or clipping +- Minimum and maximum widths respected +### Interaction +- All states render correctly (default, hover, focus, active, disabled) +- Transitions and animations match specs +- Click/touch targets are adequate size (44px minimum) +- Keyboard navigation works in correct order +- Focus indicators are visible +### Content +- Real content fits the layout (no lorem ipsum in production) +- Truncation works as specified +- Empty states display correctly +- Error messages are correct +- Loading states appear as designed +### Accessibility +- Screen reader announces correctly +- Color contrast meets WCAG AA +- Focus management works +- ARIA labels and roles are correct +- Reduced motion is respected +### Cross-Platform +- Works in required browsers +- Works on required devices +- Handles different text sizes (OS accessibility settings) +- Handles different screen densities +## QA Process +1. Self-review by developer against checklist +2. Designer visual QA pass +3. File bugs with screenshots comparing design vs implementation +4. Prioritize bugs by severity +5. Verify fixes +## Best Practices +- QA against the design spec, not memory +- Test with real content and data +- Check edge cases, not just happy paths +- Use browser dev tools to verify exact values +- Document recurring issues for prevention" + ;; + team-workflow) + desc="Design team workflows covering task management, collaboration rituals, and tooling." + body="# Team Workflow +You are an expert in designing efficient design team workflows and collaboration practices. +## What You Do +You design workflows that help design teams collaborate effectively, manage work, and deliver quality. +## Workflow Components +### Task Management +- How work is tracked (boards, tickets, sprints) +- Status definitions (backlog, in progress, in review, done) +- Priority levels and how they are assigned +- Capacity planning and workload balancing +### Collaboration Rituals +- **Standup** (daily/async): What are you working on, any blockers +- **Design critique** (weekly): Structured feedback sessions +- **Design review** (per milestone): Quality gate checkpoints +- **Retrospective** (per sprint/month): Process improvement +- **Show and tell** (bi-weekly): Share work with broader team +### Communication Norms +- When to use sync vs async communication +- Response time expectations per channel +- How to request feedback +- How to share decisions and context +- Documentation requirements +### Tooling Stack +- Design tools (Figma, Sketch, etc.) +- Prototyping tools +- Project management (Jira, Linear, Asana, etc.) +- Communication (Slack, Teams, etc.) +- Documentation (Notion, Confluence, etc.) +- Version control and asset management +### Design-Development Collaboration +- When designers join sprint ceremonies +- Handoff process and timing +- Design QA process +- Bug reporting for design issues +- Shared component library management +## Workflow Stages +1. **Discovery**: Research and problem framing +2. **Exploration**: Concept generation and evaluation +3. **Refinement**: Detailed design and specification +4. **Handoff**: Developer delivery and support +5. **QA**: Implementation verification +6. **Iteration**: Post-launch improvement +## Best Practices +- Document the workflow and make it visible +- Review and adapt the workflow regularly +- Optimize for the team's actual needs, not theory +- Balance structure with flexibility +- Automate repetitive tasks where possible" + ;; + esac + cat > "design-ops/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > design-ops/commands/plan-sprint.md << 'EOF' +--- +description: Plan a design sprint for a specific challenge. +argument-hint: "[challenge or problem area for the sprint]" +--- +# /plan-sprint +Plan a design sprint. +## Steps +1. **Frame the challenge** — Define the sprint question and scope using `design-sprint-plan` skill. +2. **Assemble the team** — Identify roles and participants using `team-workflow` skill. +3. **Plan activities** — Structure each day's activities using `design-sprint-plan` skill. +4. **Prepare materials** — Define prototyping approach and testing plan. +5. **Recruit testers** — Plan user testing sessions for the final day. +6. **Set review criteria** — Define how sprint outcomes will be evaluated using `design-review-process` skill. +## Output +Complete sprint plan with challenge statement, team roster, daily schedules, materials list, testing plan, and success criteria. +Consider following up with `/handoff` after the sprint to document the winning concept. +EOF +cat > design-ops/commands/handoff.md << 'EOF' +--- +description: Generate a developer handoff package for a design. +argument-hint: "[screen, feature, or component to hand off]" +--- +# /handoff +Generate a developer handoff package. +## Steps +1. **Visual specs** — Document all measurements and tokens using `handoff-spec` skill. +2. **Interaction specs** — Define states and behaviors using `handoff-spec` skill. +3. **QA criteria** — Create implementation checklist using `design-qa-checklist` skill. +4. **Review readiness** — Verify against review criteria using `design-review-process` skill. +5. **Version** — Tag the design version being handed off using `version-control-strategy` skill. +6. **Package** — Compile all specs, assets, and notes. +## Output +Complete handoff package with visual specs, interaction specs, asset list, QA checklist, and implementation notes. +Consider following up with `/setup-workflow` to establish the ongoing QA process. +EOF +cat > design-ops/commands/setup-workflow.md << 'EOF' +--- +description: Set up a design team workflow and rituals. +argument-hint: "[team size and context, e.g., '4-person design team in a startup' or 'design system team']" +--- +# /setup-workflow +Set up a design team workflow. +## Steps +1. **Team structure** — Define roles and responsibilities using `team-workflow` skill. +2. **Rituals** — Establish collaboration cadence using `team-workflow` skill. +3. **Critique process** — Set up design critique format using `design-critique` skill. +4. **Review gates** — Define quality checkpoints using `design-review-process` skill. +5. **Versioning** — Establish file and library versioning using `version-control-strategy` skill. +6. **QA process** — Set up design QA workflow using `design-qa-checklist` skill. +## Output +Team workflow document with rituals calendar, critique format, review process, versioning strategy, QA checklist, and tooling recommendations. +Consider following up with `/plan-sprint` to kick off your first project with the new workflow. +EOF +echo "✅ design-ops complete (7 skills, 3 commands)" diff --git a/plugin8-designer-toolkit.sh b/plugin8-designer-toolkit.sh new file mode 100755 index 0000000..7bec7ea --- /dev/null +++ b/plugin8-designer-toolkit.sh @@ -0,0 +1,381 @@ +#!/bin/bash +set -e +echo "📦 Creating designer-toolkit..." +mkdir -p designer-toolkit/.claude-plugin +mkdir -p designer-toolkit/commands +mkdir -p designer-toolkit/skills/{design-rationale,presentation-deck,case-study,design-token-audit,ux-writing,design-system-adoption} +cat > designer-toolkit/.claude-plugin/plugin.json << 'EOF' +{ + "name": "designer-toolkit", + "version": "1.0.0", + "description": "Essential designer utilities for writing rationale, building presentations, crafting case studies, UX writing, and driving adoption.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["designer-toolkit", "rationale", "presentation", "case-study", "ux-writing", "adoption"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} +EOF +cat > designer-toolkit/README.md << 'EOF' +# designer-toolkit +Essential designer utilities for writing rationale, building presentations, crafting case studies, UX writing, and driving adoption. +## Skills (6) +- **design-rationale** — Write clear design rationale connecting decisions to user needs, business goals, and principles. +- **presentation-deck** — Structure compelling design presentations for stakeholders, reviews, and showcases. +- **case-study** — Craft portfolio-ready case studies that tell the story of a design project. +- **design-token-audit** — Audit design token usage across a product for consistency and coverage. +- **ux-writing** — Write effective UI copy including microcopy, error messages, empty states, and CTAs. +- **design-system-adoption** — Create adoption strategies and materials to drive design system usage across teams. +## Commands (3) +- `/write-rationale` — Write design rationale for a set of design decisions. +- `/build-presentation` — Structure a design presentation for a specific audience. +- `/write-case-study` — Create a portfolio case study from a project summary. +EOF +for skill in design-rationale presentation-deck case-study design-token-audit ux-writing design-system-adoption; do + desc="" + body="" + case $skill in + design-rationale) + desc="Write clear design rationale connecting decisions to user needs, business goals, and principles." + body="# Design Rationale +You are an expert in articulating the reasoning behind design decisions. +## What You Do +You write clear design rationale that connects decisions to evidence, principles, and goals. +## Rationale Structure +### 1. Decision +What design decision was made? Be specific about what was chosen. +### 2. Context +What problem or need prompted this decision? What constraints exist? +### 3. Options Considered +What alternatives were explored? Brief description of each. +### 4. Evidence +What informed the decision? User research, data, best practices, competitive analysis, usability testing. +### 5. Reasoning +Why this option over the alternatives? Connect to user needs, business goals, design principles, and technical feasibility. +### 6. Trade-offs +What are the known compromises? What was deprioritized and why? +### 7. Validation Plan +How will you know if this decision was right? What metrics or feedback will confirm? +## When to Write Rationale +- Major design direction decisions +- Departures from established patterns +- Controversial or debated choices +- Decisions that will be questioned later +- Changes from previous approaches +## Rationale Quality Checklist +- Connects to user needs (not just designer preference) +- References evidence or principles +- Acknowledges alternatives and trade-offs +- Is specific enough to be useful months later +- Written for the audience who will read it +## Best Practices +- Write rationale during the decision, not after +- Keep it concise but complete +- Store rationale alongside the design files +- Reference in handoff documentation +- Use rationale in design reviews to explain choices" + ;; + presentation-deck) + desc="Structure compelling design presentations for stakeholders, reviews, and showcases." + body="# Presentation Deck +You are an expert in structuring design presentations that communicate clearly and persuade effectively. +## What You Do +You structure presentations that tell a compelling design story tailored to the audience. +## Presentation Types +### Stakeholder Update +Goal: Inform and align. Structure: context recap, progress, key decisions, next steps, asks. +### Design Review +Goal: Get feedback. Structure: objectives, design walkthrough, rationale, open questions, feedback request. +### Final Showcase +Goal: Gain approval. Structure: problem, process, solution, evidence, impact, next steps. +### Portfolio/Case Study +Goal: Demonstrate capability. Structure: challenge, approach, key decisions, outcome, learnings. +## Universal Structure +1. **Hook** — Why should the audience care? (problem, data, story) +2. **Context** — What do they need to know? (background, constraints) +3. **Journey** — How did you get here? (process, key moments) +4. **Solution** — What are you proposing? (the design, with rationale) +5. **Evidence** — Why is this right? (research, testing, data) +6. **Ask** — What do you need from them? (approval, feedback, resources) +## Slide Design Principles +- One idea per slide +- Show, don't tell (use visuals over text) +- Use progressive disclosure (reveal complexity gradually) +- Design for the back of the room (large text, high contrast) +- Include speaker notes for context +## Audience Adaptation +- **Executives**: Lead with impact, be concise, focus on business value +- **Engineers**: Include technical details, interaction specs, edge cases +- **Designers**: Show process, rationale, design system alignment +- **Mixed**: Layer detail progressively, lead with the big picture +## Best Practices +- Rehearse with a colleague before the real presentation +- Prepare for questions (have backup slides) +- Start with the audience's concerns, not yours +- End with a clear ask or next step +- Follow up with a summary document" + ;; + case-study) + desc="Craft portfolio-ready case studies that tell the story of a design project." + body="# Case Study +You are an expert in crafting compelling design case studies for portfolios and presentations. +## What You Do +You structure case studies that tell the story of a design project, demonstrating process, thinking, and impact. +## Case Study Structure +### 1. Overview +- Project title and one-line summary +- Your role and team composition +- Timeline and scope +- Key outcome or metric (the hook) +### 2. Challenge +- Business context and problem statement +- User needs and pain points +- Constraints and requirements +- Why this problem mattered +### 3. Process +- Research methods and key findings +- Ideation and exploration (show breadth) +- Key decisions and rationale (show depth) +- Iteration based on feedback or testing +### 4. Solution +- Final design walkthrough +- Key features and interactions +- How it addresses the original challenge +- Design system and technical considerations +### 5. Impact +- Quantitative results (metrics, data) +- Qualitative results (user feedback, team response) +- Business impact +- What you would do differently +### 6. Reflection +- Key learnings +- Challenges overcome +- Skills developed +- How this work influenced future projects +## Visual Storytelling +- Show the journey, not just the final product +- Include sketches, wireframes, and iterations +- Use before/after comparisons +- Annotate key design decisions +- Include real screenshots, not just mockups +## Writing Tips +- Write in first person for your contributions +- Be specific about your role vs team contributions +- Quantify impact wherever possible +- Keep it scannable (clear headings, short paragraphs) +- Edit ruthlessly — shorter is better +## Best Practices +- Lead with the most impressive outcome +- Show process, but don't document every step +- Highlight moments of insight or pivots +- Include enough context for someone unfamiliar +- Tailor depth to the audience" + ;; + design-token-audit) + desc="Audit design token usage across a product for consistency and coverage." + body="# Design Token Audit +You are an expert in auditing design token adoption and consistency across products. +## What You Do +You audit how design tokens are used (or not used) in a product, identifying inconsistencies, gaps, and hard-coded values. +## Audit Scope +### Token Coverage +- What percentage of visual properties use tokens? +- Which properties are commonly hard-coded? +- Are the right tier of tokens used (global vs semantic vs component)? +### Token Consistency +- Are the same tokens used for the same purposes? +- Are there redundant tokens (different names, same value)? +- Are deprecated tokens still in use? +### Token Gaps +- Are there visual values that should be tokens but are not? +- Are there use cases not covered by the existing token set? +- Do custom values suggest missing token scale steps? +## Audit Process +1. **Inventory** — Extract all visual values from code/design files +2. **Categorize** — Group by type (color, spacing, typography, etc.) +3. **Map** — Match values to existing tokens +4. **Flag** — Identify hard-coded values, mismatches, and gaps +5. **Prioritize** — Rank issues by frequency and impact +6. **Recommend** — Suggest new tokens, migrations, and cleanup +## Audit Report Format +- Executive summary (token adoption percentage, key findings) +- Detailed findings by category +- Hard-coded value inventory with suggested token replacements +- Recommended new tokens +- Migration plan and priority +## Best Practices +- Audit both design files and code +- Automate detection where possible (lint rules) +- Focus on high-impact categories first (color, spacing) +- Track adoption over time +- Make the audit results actionable, not just informational" + ;; + ux-writing) + desc="Write effective UI copy including microcopy, error messages, empty states, and CTAs." + body="# UX Writing +You are an expert in writing clear, helpful interface copy that guides users and reinforces the product voice. +## What You Do +You write UI copy that helps users accomplish tasks, understand status, and feel confident. +## UX Writing Categories +### Microcopy +- Button labels: action-oriented, specific (not just 'Submit') +- Form labels: clear, concise, no jargon +- Tooltips: brief explanations for complex features +- Placeholder text: example format, not instructions +### Error Messages +- Say what happened (clear, not technical) +- Say why (if helpful and brief) +- Say what to do next (specific action) +- Use a human tone (not robotic or blaming) +### Empty States +- Explain what will appear here +- Guide the user to take action +- Use an encouraging, helpful tone +- Provide a clear CTA +### Confirmation Messages +- Confirm what just happened +- Provide next steps if relevant +- Include undo option for reversible actions +- Keep it brief and positive +### Onboarding Copy +- Welcome without overwhelming +- One concept at a time +- Action-oriented (do, not just read) +- Allow skipping +### CTAs (Calls to Action) +- Start with a verb +- Be specific about the outcome +- Match user intent (not business intent) +- Primary CTA should be the most common action +## Voice and Tone Guidelines +- **Voice** (consistent): brand personality, vocabulary, perspective +- **Tone** (varies): adapts to context (celebration vs error vs instruction) +## Writing Principles +- Clear over clever +- Concise over comprehensive +- Helpful over promotional +- Consistent over creative +- Inclusive over casual +## Best Practices +- Write copy before designing the UI (content-first) +- Test copy with real users +- Create a terminology dictionary +- Avoid jargon, abbreviations, and idioms +- Consider translation and localization from the start" + ;; + design-system-adoption) + desc="Create adoption strategies and materials to drive design system usage across teams." + body="# Design System Adoption +You are an expert in driving design system adoption across design and engineering teams. +## What You Do +You create strategies and materials that help teams adopt and consistently use a design system. +## Adoption Strategy +### Awareness +- Launch announcements and demos +- Documentation site with search and examples +- Regular updates and changelog communication +- Showcase projects that use the system well +### Education +- Getting started guides for designers and developers +- Component usage guidelines with examples +- Workshop series (introductory, advanced, contribution) +- Office hours for questions and support +### Enablement +- Figma/Sketch library with proper setup instructions +- Code packages with installation guides +- Templates and starter kits +- Migration guides from legacy patterns +### Incentives +- Celebrate teams that adopt well +- Track and share adoption metrics +- Reduce friction (make it easier to use the system than not) +- Include system usage in code/design review criteria +## Measuring Adoption +- Component usage percentage in production +- Number of custom/override styles +- Support question volume (should decrease over time) +- Time to implement new features (should decrease) +- Consistency audit scores +## Common Adoption Barriers +- System doesn't cover team's needs +- Documentation is incomplete or confusing +- Components are too rigid to customize +- Breaking changes too frequent +- No clear contribution path +## Overcoming Resistance +- Listen to objections — they reveal real gaps +- Offer migration support, not mandates +- Show productivity gains with data +- Start with willing teams, build momentum +- Make contributing easy +## Best Practices +- Treat the design system as a product with users +- Invest in documentation as much as components +- Support both designers and developers equally +- Maintain a public roadmap +- Build community through contribution and feedback" + ;; + esac + cat > "designer-toolkit/skills/$skill/SKILL.md" << ENDFILE +--- +name: $skill +description: $desc +--- +$body +ENDFILE +done +# Commands +cat > designer-toolkit/commands/write-rationale.md << 'EOF' +--- +description: Write design rationale for a set of design decisions. +argument-hint: "[design decision or feature to write rationale for]" +--- +# /write-rationale +Write design rationale for decisions. +## Steps +1. **Identify decisions** — List the key design decisions that need rationale using `design-rationale` skill. +2. **Gather evidence** — Collect research, data, and principles supporting each decision. +3. **Document alternatives** — Note options considered and why they were rejected. +4. **Write rationale** — Structure each decision's rationale using `design-rationale` skill. +5. **Review copy** — Ensure rationale language is clear using `ux-writing` skill. +6. **Package** — Format for the target audience (handoff doc, presentation, or wiki). +## Output +Design rationale document with each decision documented: context, options, evidence, reasoning, and trade-offs. +Consider following up with `/build-presentation` to present the rationale to stakeholders. +EOF +cat > designer-toolkit/commands/build-presentation.md << 'EOF' +--- +description: Structure a design presentation for a specific audience. +argument-hint: "[topic and audience, e.g., 'design system update for engineering leads']" +--- +# /build-presentation +Structure a design presentation. +## Steps +1. **Audience analysis** — Identify what the audience cares about and knows. +2. **Story arc** — Define the narrative structure using `presentation-deck` skill. +3. **Key messages** — Distill to 3-5 main takeaways. +4. **Slide outline** — Plan each slide's purpose and content using `presentation-deck` skill. +5. **Rationale slides** — Include decision rationale using `design-rationale` skill. +6. **Copy review** — Refine slide text using `ux-writing` skill. +## Output +Presentation outline with slide-by-slide plan including purpose, content, visuals, and speaker notes. +Consider following up with `/write-rationale` to deepen the reasoning sections. +EOF +cat > designer-toolkit/commands/write-case-study.md << 'EOF' +--- +description: Create a portfolio case study from a project summary. +argument-hint: "[project name or brief description of the work]" +--- +# /write-case-study +Create a portfolio case study. +## Steps +1. **Outline** — Structure the case study narrative using `case-study` skill. +2. **Challenge** — Define the problem and context clearly. +3. **Process** — Highlight key moments of insight and decision using `design-rationale` skill. +4. **Solution** — Describe the final design and its key features. +5. **Impact** — Quantify and qualify the results. +6. **Polish copy** — Refine the writing using `ux-writing` skill. +## Output +Complete case study draft with overview, challenge, process, solution, impact, and reflections — ready for portfolio use. +Consider following up with `/build-presentation` to create a presentation version. +EOF +echo "✅ designer-toolkit complete (6 skills, 3 commands)" diff --git a/prototyping-testing/.claude-plugin/plugin.json b/prototyping-testing/.claude-plugin/plugin.json new file mode 100644 index 0000000..13d659e --- /dev/null +++ b/prototyping-testing/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "prototyping-testing", + "version": "1.0.0", + "description": "Plan and execute design validation through prototyping strategies, usability testing, heuristic evaluation, and A/B experiments.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["prototyping", "usability-testing", "heuristic-evaluation", "a-b-testing", "wireframes"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/prototyping-testing/README.md b/prototyping-testing/README.md new file mode 100644 index 0000000..569f5e8 --- /dev/null +++ b/prototyping-testing/README.md @@ -0,0 +1,16 @@ +# prototyping-testing +Plan and execute design validation through prototyping strategies, usability testing, heuristic evaluation, and A/B experiments. +## Skills (8) +- **prototype-strategy** — Choose the right prototyping fidelity and method for the design question. +- **test-scenario** — Write usability test scenarios with tasks, success criteria, and observation guides. +- **heuristic-evaluation** — Conduct expert heuristic evaluations using Nielsen's heuristics and domain-specific criteria. +- **a-b-test-design** — Design rigorous A/B tests with hypotheses, variants, metrics, and sample size calculations. +- **user-flow-diagram** — Create user flow diagrams showing paths, decisions, and branch logic. +- **wireframe-spec** — Specify wireframe layouts with content priority, component placement, and annotation. +- **click-test-plan** — Design click/first-click tests to evaluate navigation and information findability. +- **accessibility-test-plan** — Create accessibility testing plans covering assistive technologies and WCAG criteria. +## Commands (4) +- `/prototype-plan` — Create a prototyping and testing plan for a design initiative. +- `/evaluate` — Run a heuristic evaluation of an existing design. +- `/test-plan` — Design a complete usability testing plan. +- `/experiment` — Design an A/B experiment for a design hypothesis. diff --git a/prototyping-testing/commands/evaluate.md b/prototyping-testing/commands/evaluate.md new file mode 100644 index 0000000..c5f76b2 --- /dev/null +++ b/prototyping-testing/commands/evaluate.md @@ -0,0 +1,16 @@ +--- +description: Run a heuristic evaluation of an existing design. +argument-hint: "[design, screen, or flow to evaluate]" +--- +# /evaluate +Run a heuristic evaluation of a design. +## Steps +1. **Scope** — Define screens and flows to evaluate. +2. **Heuristic review** — Evaluate against Nielsen's heuristics using `heuristic-evaluation` skill. +3. **Flow analysis** — Review user flows for issues using `user-flow-diagram` skill. +4. **Accessibility check** — Evaluate accessibility using `accessibility-test-plan` skill. +5. **Severity rating** — Rate and prioritize all findings. +6. **Recommendations** — Provide specific improvement suggestions. +## Output +Evaluation report with findings per heuristic, severity ratings, accessibility issues, and prioritized recommendations. +Consider following up with `/test-plan` to validate findings with real users. diff --git a/prototyping-testing/commands/experiment.md b/prototyping-testing/commands/experiment.md new file mode 100644 index 0000000..8ecc3ce --- /dev/null +++ b/prototyping-testing/commands/experiment.md @@ -0,0 +1,16 @@ +--- +description: Design an A/B experiment for a design hypothesis. +argument-hint: "[hypothesis or design change to test, e.g., 'new checkout flow will increase conversion']" +--- +# /experiment +Design an A/B experiment. +## Steps +1. **Hypothesis** — Structure the hypothesis using `a-b-test-design` skill. +2. **Variants** — Define control and treatment designs. +3. **Metrics** — Define primary and guardrail metrics using `a-b-test-design` skill. +4. **Sample size** — Calculate required sample and duration using `a-b-test-design` skill. +5. **User flows** — Map variant flows using `user-flow-diagram` skill. +6. **Analysis plan** — Define how results will be analyzed and decisions made. +## Output +Experiment design document with hypothesis, variant specs, metrics, sample calculations, duration, and analysis plan. +Consider following up with `/test-plan` for qualitative testing alongside the experiment. diff --git a/prototyping-testing/commands/prototype-plan.md b/prototyping-testing/commands/prototype-plan.md new file mode 100644 index 0000000..de47db0 --- /dev/null +++ b/prototyping-testing/commands/prototype-plan.md @@ -0,0 +1,16 @@ +--- +description: Create a prototyping and testing plan for a design initiative. +argument-hint: "[feature or initiative to prototype and test]" +--- +# /prototype-plan +Create a prototyping and testing plan. +## Steps +1. **Strategy** — Choose fidelity and method using `prototype-strategy` skill. +2. **Flows** — Map user flows to prototype using `user-flow-diagram` skill. +3. **Wireframes** — Specify wireframe layouts using `wireframe-spec` skill. +4. **Test scenarios** — Write usability tasks using `test-scenario` skill. +5. **Accessibility** — Plan accessibility testing using `accessibility-test-plan` skill. +6. **Timeline** — Create a prototyping and testing schedule. +## Output +Prototyping plan with fidelity rationale, user flows, wireframe specs, test scenarios, accessibility plan, and timeline. +Consider following up with `/test-plan` for detailed usability testing or `/evaluate` for expert review. diff --git a/prototyping-testing/commands/test-plan.md b/prototyping-testing/commands/test-plan.md new file mode 100644 index 0000000..76c655f --- /dev/null +++ b/prototyping-testing/commands/test-plan.md @@ -0,0 +1,16 @@ +--- +description: Design a complete usability testing plan. +argument-hint: "[product, feature, or prototype to test]" +--- +# /test-plan +Design a complete usability testing plan. +## Steps +1. **Objectives** — Define what you need to learn. +2. **Method** — Choose testing approach using `prototype-strategy` skill. +3. **Scenarios** — Write test tasks using `test-scenario` skill. +4. **Click tests** — Design findability tests using `click-test-plan` skill. +5. **Accessibility** — Include accessibility testing using `accessibility-test-plan` skill. +6. **Logistics** — Define participants, schedule, equipment, and facilitation guide. +## Output +Testing plan with objectives, methodology, task scenarios, participant criteria, facilitation guide, and analysis framework. +Consider following up with `/evaluate` for expert review before user testing. diff --git a/prototyping-testing/skills/a-b-test-design/SKILL.md b/prototyping-testing/skills/a-b-test-design/SKILL.md new file mode 100644 index 0000000..9983039 --- /dev/null +++ b/prototyping-testing/skills/a-b-test-design/SKILL.md @@ -0,0 +1,41 @@ +--- +name: a-b-test-design +description: Design rigorous A/B tests with hypotheses, variants, metrics, and sample size calculations. +--- +# A/B Test Design +You are an expert in designing rigorous A/B experiments that produce actionable results. +## What You Do +You design A/B tests with clear hypotheses, controlled variants, appropriate metrics, and statistical rigor. +## Test Structure +### 1. Hypothesis +Structured as: 'If we [change], then [outcome] will [improve/decrease] because [rationale].' +### 2. Variants +- Control (A): current design +- Treatment (B): proposed change +- Keep changes isolated — test one variable at a time +### 3. Primary Metric +The single most important measure of success. Must be measurable, relevant, and sensitive to the change. +### 4. Secondary Metrics +Supporting measures and guardrail metrics to detect unintended consequences. +### 5. Sample Size +Based on: minimum detectable effect, baseline conversion rate, statistical significance level (typically 95%), and power (typically 80%). +### 6. Duration +Run until sample size is reached. Account for weekly cycles (run in full weeks). Minimum 1-2 weeks typically. +## Common Pitfalls +- Peeking at results before completion +- Too many variants at once +- Metric not sensitive enough to detect change +- Sample size too small +- Not accounting for novelty effects +- Ignoring segmentation effects +## When Not to A/B Test +- Very low traffic (insufficient sample) +- Ethical concerns with withholding improvement +- Foundational changes that affect everything +- When qualitative insight is more valuable +## Best Practices +- One hypothesis per test +- Document everything before starting +- Don't stop early on positive results +- Analyze segments after overall results +- Share learnings broadly regardless of outcome diff --git a/prototyping-testing/skills/accessibility-test-plan/SKILL.md b/prototyping-testing/skills/accessibility-test-plan/SKILL.md new file mode 100644 index 0000000..7a33bb1 --- /dev/null +++ b/prototyping-testing/skills/accessibility-test-plan/SKILL.md @@ -0,0 +1,42 @@ +--- +name: accessibility-test-plan +description: Create accessibility testing plans covering assistive technologies and WCAG criteria. +--- +# Accessibility Test Plan +You are an expert in planning comprehensive accessibility testing. +## What You Do +You create testing plans that systematically evaluate accessibility across assistive technologies and WCAG criteria. +## Testing Layers +### 1. Automated Testing +- Axe, Lighthouse, WAVE tools +- Catches approximately 30-40% of issues +- Run on every page/state +- Integrate into CI/CD pipeline +### 2. Manual Testing +- Keyboard-only navigation +- Screen reader walkthrough +- Zoom to 200% and 400% +- High contrast mode +- Reduced motion mode +### 3. Assistive Technology Testing +- Screen readers: VoiceOver (Mac/iOS), NVDA (Windows), TalkBack (Android) +- Voice control: Voice Control (Mac/iOS), Dragon +- Switch control +- Screen magnification +### 4. User Testing with Disabilities +- Recruit participants with relevant disabilities +- Include variety (vision, motor, cognitive, hearing) +- Test with their own devices and settings +- Focus on real tasks, not compliance checkboxes +## Test Matrix +For each key user flow, test across: keyboard only, VoiceOver, NVDA, zoom 200%, high contrast, reduced motion. +## WCAG Criteria Checklist +Organize by principle (Perceivable, Operable, Understandable, Robust) and level (A, AA, AAA). +## Reporting +For each issue: description, WCAG criterion, severity, assistive tech affected, steps to reproduce, remediation. +## Best Practices +- Test early and continuously, not just before launch +- Automated testing is necessary but not sufficient +- Test with real assistive technology users +- Include accessibility in definition of done +- Prioritize by user impact, not just compliance level diff --git a/prototyping-testing/skills/click-test-plan/SKILL.md b/prototyping-testing/skills/click-test-plan/SKILL.md new file mode 100644 index 0000000..7c3c036 --- /dev/null +++ b/prototyping-testing/skills/click-test-plan/SKILL.md @@ -0,0 +1,38 @@ +--- +name: click-test-plan +description: Design click/first-click tests to evaluate navigation and information findability. +--- +# Click Test Plan +You are an expert in designing click tests that evaluate findability and navigation clarity. +## What You Do +You design first-click and click tests that measure whether users can find information and features. +## Test Types +- **First-click test**: Where do users click first for a given task? +- **Click-path test**: Full sequence of clicks to complete a task +- **Navigation test**: Can users find items using the nav structure? +- **Five-second test**: What do users remember after 5 seconds? +## Test Plan Structure +### 1. Objective +What navigation or findability question are you answering? +### 2. Stimuli +Screen designs or prototypes to test. Identify which pages/states to show. +### 3. Tasks +Clear, goal-oriented tasks without UI hints. Example: 'Where would you click to change your email address?' +### 4. Success Criteria +- Correct first click (target area defined) +- Time to first click +- Confidence rating +- Click distribution heat map +### 5. Participants +Number needed (typically 20-50 for quantitative), recruitment criteria, any segmentation. +## Analysis +- First-click success rate (above 65% generally indicates good findability) +- Click distribution patterns +- Time analysis (hesitation indicates confusion) +- Confidence correlation with accuracy +## Best Practices +- Test one task per screen +- Define click target areas before testing +- Use realistic content, not lorem ipsum +- Don't give hints in task wording +- Compare alternative designs with same tasks diff --git a/prototyping-testing/skills/heuristic-evaluation/SKILL.md b/prototyping-testing/skills/heuristic-evaluation/SKILL.md new file mode 100644 index 0000000..299e654 --- /dev/null +++ b/prototyping-testing/skills/heuristic-evaluation/SKILL.md @@ -0,0 +1,41 @@ +--- +name: heuristic-evaluation +description: Conduct expert heuristic evaluations using Nielsen's heuristics and domain-specific criteria. +--- +# Heuristic Evaluation +You are an expert in conducting systematic heuristic evaluations of digital interfaces. +## What You Do +You evaluate interfaces against established usability heuristics to identify problems before user testing. +## Nielsen's 10 Usability Heuristics +1. **Visibility of system status** — Users know what is happening +2. **Match real world** — System speaks users' language +3. **User control and freedom** — Easy undo and exit +4. **Consistency and standards** — Follow conventions +5. **Error prevention** — Prevent problems before they occur +6. **Recognition over recall** — Make options visible +7. **Flexibility and efficiency** — Shortcuts for experts +8. **Aesthetic and minimalist design** — No irrelevant information +9. **Error recovery** — Help users recognize and recover from errors +10. **Help and documentation** — Provide assistance when needed +## Evaluation Process +1. Define scope (which screens/flows to evaluate) +2. Walk through as a new user +3. Walk through as an experienced user +4. Walk through each task flow +5. Document each issue found +6. Rate severity +7. Compile and prioritize findings +## Issue Documentation +For each issue: heuristic violated, description, location, severity (0-4), screenshot/reference, recommendation. +## Severity Scale +- 0: Not a usability problem +- 1: Cosmetic only +- 2: Minor problem +- 3: Major problem (important to fix) +- 4: Catastrophe (must fix before release) +## Best Practices +- Multiple evaluators find more issues (3-5 ideal) +- Evaluate independently before comparing +- Focus on real user tasks, not edge cases +- Don't just find problems — suggest solutions +- Combine with real user testing for complete picture diff --git a/prototyping-testing/skills/prototype-strategy/SKILL.md b/prototyping-testing/skills/prototype-strategy/SKILL.md new file mode 100644 index 0000000..d87111d --- /dev/null +++ b/prototyping-testing/skills/prototype-strategy/SKILL.md @@ -0,0 +1,34 @@ +--- +name: prototype-strategy +description: Choose the right prototyping fidelity and method for the design question. +--- +# Prototype Strategy +You are an expert in choosing prototyping approaches that efficiently answer design questions. +## What You Do +You help teams choose the right fidelity, tool, and method for prototyping based on what they need to learn. +## Fidelity Spectrum +### Low Fidelity +Paper sketches, sticky notes, rough wireframes. Best for: early exploration, information architecture, flow validation. Fast to create, easy to discard. +### Medium Fidelity +Digital wireframes, clickable prototypes, gray-box layouts. Best for: interaction patterns, navigation testing, stakeholder alignment. +### High Fidelity +Pixel-perfect mockups, coded prototypes, motion prototypes. Best for: visual design validation, micro-interaction testing, developer handoff, usability testing. +## Prototyping Methods +- **Paper prototyping**: Sketch screens, manually swap on user action +- **Clickable wireframes**: Linked screens with hotspots +- **Interactive prototypes**: Stateful with real interactions +- **Coded prototypes**: HTML/CSS/JS for realistic behavior +- **Wizard of Oz**: Fake backend, real frontend +- **Video prototypes**: Walkthrough animations showing the concept +## Choosing Fidelity +- What question are you answering? +- Who is the audience (users, stakeholders, developers)? +- How much time do you have? +- How many iterations do you expect? +- What decisions will this prototype inform? +## Best Practices +- Match fidelity to the question, not the deadline +- Prototype the riskiest assumption first +- Don't over-invest before testing +- Make it clear it is a prototype (avoid polished for early feedback) +- Plan for iteration — build to throw away diff --git a/prototyping-testing/skills/test-scenario/SKILL.md b/prototyping-testing/skills/test-scenario/SKILL.md new file mode 100644 index 0000000..5f065e2 --- /dev/null +++ b/prototyping-testing/skills/test-scenario/SKILL.md @@ -0,0 +1,38 @@ +--- +name: test-scenario +description: Write usability test scenarios with tasks, success criteria, and observation guides. +--- +# Test Scenario +You are an expert in writing usability test scenarios that reveal genuine user behavior. +## What You Do +You write test scenarios with realistic tasks, clear success criteria, and structured observation guides. +## Scenario Structure +### Context Setting +Brief, realistic backstory that gives the participant a reason to act without leading them. +### Task +Specific goal to accomplish. Action-oriented, not question-based. Avoids UI terminology that hints at the answer. +### Success Criteria +- Task completion (yes/no) +- Time to complete +- Number of errors or wrong paths +- Assistance requests +- Self-reported difficulty (1-5 scale) +### Observation Guide +What to watch for: hesitations, facial expressions, verbal comments, navigation choices, error recovery behavior. +## Task Types +- **Exploratory**: Find information (e.g., 'Find the return policy') +- **Specific**: Complete a goal (e.g., 'Add a blue shirt size M to your cart') +- **Comparative**: Choose between options +- **Open-ended**: Achieve a goal with multiple valid paths +## Scenario Writing Rules +- Use participant's language, not product jargon +- Give motivation, not instructions +- One goal per task +- Don't reveal the UI path in the task wording +- Include both simple and complex tasks +## Best Practices +- Pilot test your scenarios before real sessions +- Order tasks from easy to hard +- Include a warm-up task +- Prepare follow-up questions per task +- Write more scenarios than you need (allow flexibility) diff --git a/prototyping-testing/skills/user-flow-diagram/SKILL.md b/prototyping-testing/skills/user-flow-diagram/SKILL.md new file mode 100644 index 0000000..9f7bc65 --- /dev/null +++ b/prototyping-testing/skills/user-flow-diagram/SKILL.md @@ -0,0 +1,41 @@ +--- +name: user-flow-diagram +description: Create user flow diagrams showing paths, decisions, and branch logic. +--- +# User Flow Diagram +You are an expert in creating clear user flow diagrams that map paths through a product. +## What You Do +You create flow diagrams showing how users move through a product to accomplish goals, including decisions, branches, and error paths. +## Flow Diagram Elements +- **Entry point**: Where the user enters the flow (circle/oval) +- **Screen/page**: A view the user sees (rectangle) +- **Decision**: A branching point (diamond) +- **Action**: Something the user does (rounded rectangle) +- **System process**: Backend operation (rectangle with side bars) +- **End point**: Flow completion (circle with border) +- **Connector**: Arrow showing direction of flow +## Flow Types +- **Task flow**: Single path for a specific task (linear) +- **User flow**: Multiple paths based on user type or choice +- **Wire flow**: Flow combined with wireframe thumbnails +## Creating Effective Flows +1. Define the goal the flow accomplishes +2. Identify the entry point(s) +3. Map the happy path first +4. Add decision points and branches +5. Map error paths and recovery +6. Mark exit points +7. Note system actions happening in background +## Flow Annotations +- Screen names and key content +- Decision criteria at each branch +- Error conditions and handling +- System events and notifications +- Time delays or async processes +## Best Practices +- One flow per user goal +- Start with happy path, then add complexity +- Include error and edge case paths +- Keep flows readable (not too many branches on one diagram) +- Use consistent notation +- Label every arrow with the trigger/action diff --git a/prototyping-testing/skills/wireframe-spec/SKILL.md b/prototyping-testing/skills/wireframe-spec/SKILL.md new file mode 100644 index 0000000..9e4c85b --- /dev/null +++ b/prototyping-testing/skills/wireframe-spec/SKILL.md @@ -0,0 +1,44 @@ +--- +name: wireframe-spec +description: Specify wireframe layouts with content priority, component placement, and annotation. +--- +# Wireframe Spec +You are an expert in creating annotated wireframe specifications. +## What You Do +You specify wireframe layouts defining content priority, component placement, behavior annotations, and responsive considerations. +## Wireframe Components +### Content Blocks +- Headers and navigation +- Hero/feature areas +- Content sections (text, media, cards) +- Forms and input areas +- Footers and secondary navigation +### Annotations +- Content priority numbers (what loads/appears first) +- Interaction notes (what happens on click/hover) +- Dynamic content indicators (personalized, data-driven) +- Responsive behavior notes +- Accessibility notes +### Content Specifications +- Heading hierarchy (H1, H2, H3) +- Approximate text length/character counts +- Image aspect ratios and sizing +- Required vs optional content +- Content source (static, CMS, API) +## Fidelity Levels +- **Sketch**: Hand-drawn boxes and labels +- **Low-fi**: Gray boxes with content labels +- **Mid-fi**: Realistic layout with placeholder content +- **Annotated**: Mid-fi plus detailed behavior specs +## Wireframe Conventions +- Use gray/black/white only (no color decisions) +- X-box for images +- Wavy lines for text blocks +- Real labels for navigation and buttons +- Consistent component representation +## Best Practices +- Focus on content hierarchy, not visual design +- Annotate behavior, not just layout +- Show multiple states (empty, loading, populated, error) +- Include responsive breakpoint versions +- Get content strategy input early diff --git a/ui-design/.claude-plugin/plugin.json b/ui-design/.claude-plugin/plugin.json new file mode 100644 index 0000000..26cef0e --- /dev/null +++ b/ui-design/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "ui-design", + "version": "1.0.0", + "description": "Craft polished user interfaces with layout grids, color systems, typography scales, responsive patterns, and visual hierarchy.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["ui-design", "layout", "color", "typography", "responsive", "visual-hierarchy"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/ui-design/README.md b/ui-design/README.md new file mode 100644 index 0000000..3dfa6e5 --- /dev/null +++ b/ui-design/README.md @@ -0,0 +1,17 @@ +# ui-design +Craft polished user interfaces with layout grids, color systems, typography scales, responsive patterns, and visual hierarchy. +## Skills (9) +- **layout-grid** — Define responsive layout grid systems with columns, gutters, margins, and breakpoints. +- **color-system** — Build a comprehensive color system with palette generation and accessibility compliance. +- **typography-scale** — Create a modular typography scale with size, weight, and line-height relationships. +- **responsive-design** — Design adaptive layouts and interactions across all screen sizes and inputs. +- **visual-hierarchy** — Establish clear visual hierarchy through size, weight, color, spacing, and position. +- **spacing-system** — Create a consistent spacing system based on a base unit with application rules. +- **dark-mode-design** — Design effective dark mode interfaces with proper color adaptation and contrast. +- **illustration-style** — Define an illustration style guide with visual language and usage rules. +- **data-visualization** — Design clear, accessible data visualizations with appropriate chart selection. +## Commands (4) +- `/design-screen` — Design a complete screen layout from a description or requirements. +- `/color-palette` — Generate a full color palette with semantic mapping and accessibility checks. +- `/type-system` — Create a complete typography system from brand fonts or requirements. +- `/responsive-audit` — Audit a design for responsive behavior across breakpoints. diff --git a/ui-design/commands/color-palette.md b/ui-design/commands/color-palette.md new file mode 100644 index 0000000..6b53140 --- /dev/null +++ b/ui-design/commands/color-palette.md @@ -0,0 +1,16 @@ +--- +description: Generate a full color palette with semantic mapping and accessibility checks. +argument-hint: "[brand colors, mood, or requirements, e.g., '#3B82F6 primary blue, modern tech feel']" +--- +# /color-palette +Generate a comprehensive color palette. +## Steps +1. **Base palette** — Generate tonal scales from input colors using `color-system` skill. +2. **Semantic mapping** — Map colors to semantic roles (success, error, etc.) using `color-system` skill. +3. **Accessibility check** — Verify contrast ratios for all combinations using `color-system` skill. +4. **Dark mode** — Create dark mode color mappings using `dark-mode-design` skill. +5. **Data viz** — Define data visualization colors using `data-visualization` skill. +6. **Document** — Output the complete palette with usage guidance. +## Output +Complete color system with tonal scales, semantic mapping, contrast matrix, dark mode mappings, and usage guidelines. +Consider following up with `/design-screen` to apply the palette. diff --git a/ui-design/commands/design-screen.md b/ui-design/commands/design-screen.md new file mode 100644 index 0000000..0ada60a --- /dev/null +++ b/ui-design/commands/design-screen.md @@ -0,0 +1,17 @@ +--- +description: Design a complete screen layout from a description or requirements. +argument-hint: "[screen description, e.g., 'user profile settings page' or 'e-commerce product listing']" +--- +# /design-screen +Design a complete screen layout from a description. +## Steps +1. **Structure** — Define layout grid using `layout-grid` skill. +2. **Hierarchy** — Establish visual priority using `visual-hierarchy` skill. +3. **Typography** — Apply type styles using `typography-scale` skill. +4. **Color** — Apply color system using `color-system` skill. +5. **Spacing** — Apply consistent spacing using `spacing-system` skill. +6. **Responsive** — Define behavior across breakpoints using `responsive-design` skill. +7. **Dark mode** — Specify dark mode adaptation using `dark-mode-design` skill. +## Output +Complete screen specification with layout, hierarchy, typography, color, spacing, responsive behavior, and dark mode. +Consider following up with `/responsive-audit` to verify the design. diff --git a/ui-design/commands/responsive-audit.md b/ui-design/commands/responsive-audit.md new file mode 100644 index 0000000..087e1e1 --- /dev/null +++ b/ui-design/commands/responsive-audit.md @@ -0,0 +1,17 @@ +--- +description: Audit a design for responsive behavior across breakpoints. +argument-hint: "[screen or feature name to audit]" +--- +# /responsive-audit +Audit a design for responsive behavior. +## Steps +1. **Breakpoints** — Review behavior at each breakpoint using `responsive-design` skill. +2. **Grid** — Check layout grid compliance using `layout-grid` skill. +3. **Typography** — Verify type scaling using `typography-scale` skill. +4. **Spacing** — Check spacing consistency using `spacing-system` skill. +5. **Hierarchy** — Verify hierarchy holds at all sizes using `visual-hierarchy` skill. +6. **Touch targets** — Verify minimum sizes for touch using `responsive-design` skill. +7. **Report** — Document findings with recommendations. +## Output +Responsive audit report with findings per breakpoint, compliance status, and remediation recommendations. +Consider following up with `/design-screen` to redesign problem areas. diff --git a/ui-design/commands/type-system.md b/ui-design/commands/type-system.md new file mode 100644 index 0000000..4cf9ed2 --- /dev/null +++ b/ui-design/commands/type-system.md @@ -0,0 +1,16 @@ +--- +description: Create a complete typography system from brand fonts or requirements. +argument-hint: "[font names or requirements, e.g., 'Inter for UI, Merriweather for editorial']" +--- +# /type-system +Create a complete typography system. +## Steps +1. **Scale** — Build a modular type scale using `typography-scale` skill. +2. **Hierarchy** — Define hierarchy levels using `visual-hierarchy` skill. +3. **Responsive** — Adapt scale across breakpoints using `responsive-design` skill. +4. **Spacing** — Define text spacing relationships using `spacing-system` skill. +5. **Grid alignment** — Align to baseline grid using `layout-grid` skill. +6. **Document** — Output complete type system with usage rules. +## Output +Typography system with scale, styles, responsive behavior, spacing, grid alignment, and usage guidelines. +Consider following up with `/design-screen` to apply the type system. diff --git a/ui-design/skills/color-system/SKILL.md b/ui-design/skills/color-system/SKILL.md new file mode 100644 index 0000000..7ae70ce --- /dev/null +++ b/ui-design/skills/color-system/SKILL.md @@ -0,0 +1,34 @@ +--- +name: color-system +description: Build a comprehensive color system with palette generation, semantic mapping, and accessibility compliance. +--- +# Color System +You are an expert in building systematic, accessible color palettes for digital products. +## What You Do +You create comprehensive color systems with raw palettes, semantic mapping, and accessibility compliance. +## Color System Layers +### 1. Brand Palette +Primary, secondary, and accent colors with full tonal scales (50-950 or equivalent). +### 2. Neutral Palette +Gray scale for text, backgrounds, borders, and surfaces. +### 3. Semantic Colors +- Success (green), warning (amber), error (red), info (blue) +- Each with background, foreground, border, and icon variants +### 4. Extended Palette +Data visualization colors, illustration colors, gradient definitions. +## Accessibility Requirements +- Text on backgrounds: minimum 4.5:1 contrast (AA) or 7:1 (AAA) +- Large text: minimum 3:1 +- UI components: minimum 3:1 against adjacent colors +- Don't rely on color alone to convey meaning +## Color Relationships +- Tint/shade scales for each hue +- Complementary pairs for contrast +- Analogous sets for harmony +- Neutral pairings for text/surface combinations +## Best Practices +- Generate full tonal scales, not just single swatches +- Test every foreground/background combination for contrast +- Provide usage guidance for each color +- Design for color blindness (test with simulators) +- Include dark mode mappings from the start diff --git a/ui-design/skills/dark-mode-design/SKILL.md b/ui-design/skills/dark-mode-design/SKILL.md new file mode 100644 index 0000000..69dad30 --- /dev/null +++ b/ui-design/skills/dark-mode-design/SKILL.md @@ -0,0 +1,39 @@ +--- +name: dark-mode-design +description: Design effective dark mode interfaces with proper color adaptation, contrast, and elevation. +--- +# Dark Mode Design +You are an expert in designing dark mode interfaces that are comfortable, accessible, and polished. +## What You Do +You design dark mode experiences that go beyond simple color inversion. +## Core Principles +- Reduce overall luminance to decrease eye strain +- Use surface elevation through lighter shades (not shadows) +- Desaturate bright colors for dark backgrounds +- Maintain sufficient contrast for readability +## Surface Hierarchy (Dark Mode) +- Background: darkest (e.g., #121212) +- Surface 1: slightly lighter (elevated cards) +- Surface 2: lighter again (modals, dropdowns) +- Surface 3: lightest dark (tooltips, menus) +## Color Adaptation +- Primary colors: reduce saturation 10-20% +- Error/warning: adjust for dark background contrast +- Text: off-white (#E0E0E0) not pure white (#FFFFFF) +- Borders: subtle, low-opacity white +## Images and Media +- Consider dimming images slightly +- Provide dark-variant illustrations +- Logos may need light-on-dark versions +- Avoid large bright areas in imagery +## Accessibility in Dark Mode +- Minimum 4.5:1 contrast for body text +- Test with screen readers (mode announcements) +- Respect prefers-color-scheme media query +- Provide manual toggle alongside auto-detection +## Best Practices +- Don't just invert — redesign surfaces thoughtfully +- Test in actual dark environments +- Check every component in dark mode +- Smooth transitions between modes +- Use semantic tokens for effortless switching diff --git a/ui-design/skills/data-visualization/SKILL.md b/ui-design/skills/data-visualization/SKILL.md new file mode 100644 index 0000000..b35f2d9 --- /dev/null +++ b/ui-design/skills/data-visualization/SKILL.md @@ -0,0 +1,45 @@ +--- +name: data-visualization +description: Design clear, accessible data visualizations with appropriate chart selection and styling. +--- +# Data Visualization +You are an expert in designing clear, accessible, and informative data visualizations. +## What You Do +You design data visualizations that communicate insights effectively using appropriate chart types and styling. +## Chart Selection +### Comparison +Bar charts (categorical), grouped bars (multi-series), bullet charts (target vs actual). +### Trend Over Time +Line charts (continuous), area charts (volume), sparklines (inline). +### Part of Whole +Pie/donut (few categories), stacked bar (many categories), treemap (hierarchical). +### Distribution +Histogram, box plot, scatter plot. +### Relationship +Scatter plot, bubble chart, heat map. +## Design Principles +- Data-ink ratio: maximize data, minimize decoration +- Clear axis labels and legends +- Consistent color encoding across views +- Start y-axis at zero for bar charts +- Use annotation to highlight key insights +## Color in Data Viz +- Sequential: light to dark for ordered data +- Diverging: two-hue scale for above/below midpoint +- Categorical: distinct hues for unrelated categories +- Colorblind-safe palettes (avoid red-green only) +## Accessibility +- Don't rely on color alone — use patterns, labels, or shapes +- Provide text alternatives for charts +- Keyboard navigable interactive charts +- Sufficient contrast for data elements +## Responsive Data Viz +- Simplify at small sizes (fewer data points, larger labels) +- Consider alternative views for mobile (table instead of chart) +- Touch-friendly tooltips and interactions +## Best Practices +- Choose the simplest chart that communicates the insight +- Label directly on the chart when possible (avoid legends) +- Provide context (benchmarks, targets, trends) +- Test with real data, not idealized samples +- Allow users to explore details on demand diff --git a/ui-design/skills/illustration-style/SKILL.md b/ui-design/skills/illustration-style/SKILL.md new file mode 100644 index 0000000..0e77b23 --- /dev/null +++ b/ui-design/skills/illustration-style/SKILL.md @@ -0,0 +1,41 @@ +--- +name: illustration-style +description: Define an illustration style guide with visual language, color usage, and application rules. +--- +# Illustration Style +You are an expert in defining illustration systems that support product communication and brand identity. +## What You Do +You create illustration style guides ensuring consistent visual storytelling across a product. +## Style Definition +- **Geometric vs organic**: Angular/structured or flowing/natural +- **Flat vs dimensional**: 2D flat, 2.5D isometric, or 3D +- **Detailed vs minimal**: Level of detail and complexity +- **Abstract vs representational**: Symbolic or realistic +- **Line style**: Stroke weight, corners, endpoints +## Color in Illustration +- Use a subset of the product color palette +- Define primary, secondary, and accent illustration colors +- Rules for gradients and shadows +- Dark mode illustration variants +## Character Design (if applicable) +- Proportions and body style +- Level of detail in faces +- Diversity and representation guidelines +- Poses and expressions library +## Illustration Types +- **Spot illustrations**: Small, inline, supporting UI elements +- **Hero illustrations**: Large, featured, storytelling +- **Empty states**: Guide users when no content exists +- **Onboarding**: Explain features and concepts +- **Error states**: Soften error messages +## Application Rules +- When to use vs when not to use illustrations +- Size constraints per context +- Alignment with grid system +- Animation guidelines for illustrated elements +## Best Practices +- Keep a consistent style across all illustrations +- Create reusable element libraries +- Document the creation process for contributors +- Test at intended display sizes +- Consider accessibility (don't convey info only through illustrations) diff --git a/ui-design/skills/layout-grid/SKILL.md b/ui-design/skills/layout-grid/SKILL.md new file mode 100644 index 0000000..34ccd51 --- /dev/null +++ b/ui-design/skills/layout-grid/SKILL.md @@ -0,0 +1,34 @@ +--- +name: layout-grid +description: Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior. +--- +# Layout Grid +You are an expert in layout grid systems for digital product design. +## What You Do +You define responsive grid systems that create consistent, flexible page layouts across breakpoints. +## Grid Anatomy +- **Columns**: Typically 4 (mobile), 8 (tablet), 12 (desktop) +- **Gutters**: Space between columns (16px, 24px, or 32px typical) +- **Margins**: Outer page margins (16px mobile, 24-48px desktop) +- **Breakpoints**: Points where layout adapts (e.g., 375, 768, 1024, 1440px) +## Grid Types +- **Column grid**: Equal columns for general layout +- **Modular grid**: Columns + rows creating modules +- **Baseline grid**: Vertical rhythm alignment (4px or 8px) +- **Compound grid**: Overlapping grids for complex layouts +## Responsive Behavior +- Fluid: columns stretch proportionally +- Fixed: max-width container with centered content +- Adaptive: distinct layouts per breakpoint +- Column dropping: reduce columns at smaller sizes +## Common Patterns +- Full-bleed: content spans entire viewport +- Contained: max-width with margins +- Asymmetric: sidebar + main content +- Card grids: auto-fill responsive cards +## Best Practices +- Use consistent gutters and margins +- Align content to the grid, not arbitrarily +- Test at every breakpoint, not just the extremes +- Document grid specs for developers +- Allow intentional grid-breaking for emphasis diff --git a/ui-design/skills/responsive-design/SKILL.md b/ui-design/skills/responsive-design/SKILL.md new file mode 100644 index 0000000..2e5dad4 --- /dev/null +++ b/ui-design/skills/responsive-design/SKILL.md @@ -0,0 +1,38 @@ +--- +name: responsive-design +description: Design adaptive layouts and interactions that work across all screen sizes and input methods. +--- +# Responsive Design +You are an expert in designing interfaces that adapt gracefully across devices and contexts. +## What You Do +You design adaptive layouts and interactions that work across all screen sizes, pixel densities, and input methods. +## Responsive Strategies +- **Fluid**: Percentage-based widths, flexible within ranges +- **Adaptive**: Distinct layouts at specific breakpoints +- **Mobile-first**: Start with smallest, enhance upward +- **Content-first**: Let content needs drive breakpoints +## Common Breakpoints +- Small: 375-639px (phones) +- Medium: 640-1023px (tablets) +- Large: 1024-1439px (laptops) +- Extra large: 1440px+ (desktops) +## Responsive Patterns +- Column drop: reduce columns at smaller sizes +- Reflow: stack horizontal elements vertically +- Off-canvas: hide secondary content behind toggle +- Priority+: show most important, overflow the rest +## Input Method Adaptation +- Touch: 44px minimum targets, gesture support +- Mouse: hover states, precise targeting +- Keyboard: focus indicators, logical tab order +- Voice: clear labels, logical structure +## Responsive Typography and Images +- Fluid type scaling between breakpoints +- Responsive images with appropriate srcset +- Art direction: different crops per breakpoint +## Best Practices +- Design for content, not devices +- Test on real devices, not just browser resize +- Consider landscape and portrait +- Account for slow connections +- Test with accessibility tools at each breakpoint diff --git a/ui-design/skills/spacing-system/SKILL.md b/ui-design/skills/spacing-system/SKILL.md new file mode 100644 index 0000000..6ca094e --- /dev/null +++ b/ui-design/skills/spacing-system/SKILL.md @@ -0,0 +1,38 @@ +--- +name: spacing-system +description: Create a consistent spacing system based on a base unit with contextual application rules. +--- +# Spacing System +You are an expert in creating systematic spacing for consistent, harmonious interfaces. +## What You Do +You create spacing systems that bring consistency and rhythm to layouts. +## Base Unit +Choose a base unit (typically 4px or 8px) and build a scale: +- 2xs: 2px +- xs: 4px +- sm: 8px +- md: 16px +- lg: 24px +- xl: 32px +- 2xl: 48px +- 3xl: 64px +## Spacing Types +- **Inset**: Padding inside containers (equal or squish/stretch variants) +- **Stack**: Vertical space between stacked elements +- **Inline**: Horizontal space between inline elements +- **Grid gap**: Space between grid/flex items +## Application Rules +- Related items: smaller spacing (sm/md) +- Distinct sections: larger spacing (lg/xl) +- Page margins: consistent per breakpoint +- Component internal: defined per component +## Density Modes +- Compact: reduce spacing by one step (for data-heavy views) +- Comfortable: default spacing +- Spacious: increase spacing by one step (for reading-focused) +## Best Practices +- Always use the scale — never arbitrary values +- Consistent spacing within components +- Larger gaps between unrelated groups +- Document spacing intent, not just values +- Test spacing at different viewport sizes diff --git a/ui-design/skills/typography-scale/SKILL.md b/ui-design/skills/typography-scale/SKILL.md new file mode 100644 index 0000000..c649219 --- /dev/null +++ b/ui-design/skills/typography-scale/SKILL.md @@ -0,0 +1,43 @@ +--- +name: typography-scale +description: Create a modular typography scale with size, weight, and line-height relationships. +--- +# Typography Scale +You are an expert in typographic systems for digital interfaces. +## What You Do +You create modular typography scales that ensure readable, harmonious, and consistent text across a product. +## Scale Components +### Size Scale +Based on a ratio (e.g., 1.25 major third, 1.333 perfect fourth): +- Caption: 12px +- Body small: 14px +- Body: 16px (base) +- Subheading: 20px +- Heading 3: 24px +- Heading 2: 32px +- Heading 1: 40px +- Display: 48-64px +### Weight Scale +Regular (400), Medium (500), Semibold (600), Bold (700). +### Line Height +- Tight: 1.2 (headings) +- Normal: 1.5 (body text) +- Relaxed: 1.75 (long-form reading) +### Letter Spacing +- Tight: -0.02em (large headings) +- Normal: 0 (body) +- Wide: 0.05em (uppercase labels, captions) +## Font Pairing +- Primary: UI and body text +- Secondary: headings or editorial (optional) +- Mono: code, data, technical content +## Responsive Typography +- Scale down heading sizes on mobile +- Maintain body size (16px minimum for readability) +- Adjust line lengths (45-75 characters optimal) +## Best Practices +- Use a mathematical ratio for harmony +- Limit to 4-5 sizes in regular use +- Ensure body text is minimum 16px +- Test with real content, not lorem ipsum +- Document usage rules for each style diff --git a/ui-design/skills/visual-hierarchy/SKILL.md b/ui-design/skills/visual-hierarchy/SKILL.md new file mode 100644 index 0000000..c351b54 --- /dev/null +++ b/ui-design/skills/visual-hierarchy/SKILL.md @@ -0,0 +1,37 @@ +--- +name: visual-hierarchy +description: Establish clear visual hierarchy through size, weight, color, spacing, and positioning. +--- +# Visual Hierarchy +You are an expert in creating clear visual hierarchy that guides users through interfaces. +## What You Do +You establish visual hierarchy ensuring users see the most important content first and can scan efficiently. +## Hierarchy Tools +### Size +Larger elements draw attention first. Use size differences of at least 1.5x for clear distinction. +### Weight +Bold text, thicker strokes, and filled icons carry more visual weight than light variants. +### Color and Contrast +High contrast attracts attention. Use color strategically for CTAs, status, and emphasis. +### Spacing +More whitespace around an element increases its perceived importance. +### Position +Top-left (in LTR layouts) gets seen first. Above the fold matters. F-pattern and Z-pattern scanning. +### Density +Isolated elements stand out. Grouped elements are scanned as a unit. +## Hierarchy Levels +1. **Primary**: Page title, primary CTA — seen first +2. **Secondary**: Section headings, key content — scanned next +3. **Tertiary**: Supporting text, metadata — read on demand +4. **Quaternary**: Fine print, timestamps — available but not prominent +## Common Patterns +- Hero sections: large type + image + single CTA +- Card layouts: image > title > description > action +- Forms: label > input > helper text > error +- Navigation: current state > available > disabled +## Best Practices +- Squint test: blur your eyes — hierarchy should still be clear +- One primary action per view +- Don't compete for attention — choose what matters most +- Use hierarchy to tell a story through the page +- Test with real users doing real tasks diff --git a/update-readme.sh b/update-readme.sh new file mode 100755 index 0000000..f870931 --- /dev/null +++ b/update-readme.sh @@ -0,0 +1,66 @@ +#!/bin/bash +set -e +echo "📝 Updating root README..." +cat > README.md << 'EOF' +# Designer Skills Collection +Agentic skills, commands, and plugins for design — from research to systems, UI, interaction, and delivery. +**63 skills** and **27 commands** across **8 plugins** for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). +## Plugins +| Plugin | Skills | Commands | Description | +|--------|--------|----------|-------------| +| [design-research](./design-research) | 10 | 4 | User research: personas, empathy maps, journey maps, interviews, usability testing, and card sorting. | +| [design-systems](./design-systems) | 8 | 3 | Build and maintain design systems: tokens, components, accessibility, theming, and documentation. | +| [ux-strategy](./ux-strategy) | 8 | 3 | Shape product direction: competitive analysis, design principles, experience mapping, and alignment. | +| [ui-design](./ui-design) | 9 | 4 | Craft polished interfaces: layout grids, color systems, typography, responsive design, and data viz. | +| [interaction-design](./interaction-design) | 7 | 3 | Design meaningful interactions: micro-animations, state machines, gestures, error handling, and feedback. | +| [prototyping-testing](./prototyping-testing) | 8 | 4 | Validate designs: prototyping strategies, usability testing, heuristic evaluation, and A/B experiments. | +| [design-ops](./design-ops) | 7 | 3 | Streamline operations: critique frameworks, handoff specs, sprint planning, and team workflows. | +| [designer-toolkit](./designer-toolkit) | 6 | 3 | Essential utilities: design rationale, presentations, case studies, UX writing, and system adoption. | +## Quick Start +### Install a Single Plugin +```bash +claude install github:Owl-Listener/designer-skills/design-research +``` +### Install All Plugins +```bash +claude install github:Owl-Listener/designer-skills +``` +## What Are Skills and Commands? +- **Skills** are domain knowledge units (nouns). They teach Claude about a design topic — like creating user personas, defining design tokens, or writing error messages. +- **Commands** are workflows (verbs). They chain multiple skills together to accomplish a task — like running a full design system audit or planning a usability test. +## All Commands +| Command | Plugin | Description | +|---------|--------|-------------| +| `/discover` | design-research | Run a full user research discovery cycle. | +| `/interview` | design-research | Prepare and conduct a user interview. | +| `/test-plan` | design-research | Create a usability test plan. | +| `/synthesize` | design-research | Synthesize research data into insights. | +| `/audit-system` | design-systems | Audit a design system for consistency and accessibility. | +| `/create-component` | design-systems | Scaffold a full component specification. | +| `/tokenize` | design-systems | Extract and organize design tokens. | +| `/strategize` | ux-strategy | Develop a complete UX strategy. | +| `/benchmark` | ux-strategy | Run a competitive benchmarking analysis. | +| `/frame-problem` | ux-strategy | Structure an ambiguous challenge into a clear problem. | +| `/design-screen` | ui-design | Design a complete screen layout. | +| `/color-palette` | ui-design | Generate a full color palette with accessibility checks. | +| `/type-system` | ui-design | Create a complete typography system. | +| `/responsive-audit` | ui-design | Audit a design for responsive behavior. | +| `/design-interaction` | interaction-design | Design a complete interaction flow. | +| `/map-states` | interaction-design | Model states and transitions for a component. | +| `/error-flow` | interaction-design | Design error handling for a feature. | +| `/prototype-plan` | prototyping-testing | Create a prototyping and testing plan. | +| `/evaluate` | prototyping-testing | Run a heuristic evaluation. | +| `/test-plan` | prototyping-testing | Design a complete usability testing plan. | +| `/experiment` | prototyping-testing | Design an A/B experiment. | +| `/plan-sprint` | design-ops | Plan a design sprint. | +| `/handoff` | design-ops | Generate a developer handoff package. | +| `/setup-workflow` | design-ops | Set up a design team workflow. | +| `/write-rationale` | designer-toolkit | Write design rationale for decisions. | +| `/build-presentation` | designer-toolkit | Structure a design presentation. | +| `/write-case-study` | designer-toolkit | Create a portfolio case study. | +## Contributing +See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on adding new skills, commands, and plugins. +## License +MIT — see [LICENSE](./LICENSE). +EOF +echo "✅ README updated" diff --git a/ux-strategy/.claude-plugin/plugin.json b/ux-strategy/.claude-plugin/plugin.json new file mode 100644 index 0000000..70b9e61 --- /dev/null +++ b/ux-strategy/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "ux-strategy", + "version": "1.0.0", + "description": "Shape product direction through competitive analysis, design principles, experience mapping, and strategic alignment.", + "author": { "name": "MC Dean", "url": "https://marieclairedean.substack.com/" }, + "keywords": ["ux-strategy", "competitive-analysis", "design-principles", "vision", "alignment"], + "homepage": "https://github.com/Owl-Listener/designer-skills", + "license": "MIT" +} diff --git a/ux-strategy/README.md b/ux-strategy/README.md new file mode 100644 index 0000000..6a14c14 --- /dev/null +++ b/ux-strategy/README.md @@ -0,0 +1,15 @@ +# ux-strategy +Shape product direction through competitive analysis, design principles, experience mapping, and strategic alignment. +## Skills (8) +- **competitive-analysis** — Conduct a structured competitive analysis comparing UX patterns, features, strengths, and gaps. +- **design-principles** — Define actionable design principles that guide decision-making and resolve trade-offs. +- **experience-map** — Create a holistic experience map of user touchpoints, channels, and relationships. +- **north-star-vision** — Articulate a compelling north-star product vision that aligns teams. +- **opportunity-framework** — Identify, evaluate, and prioritize design opportunities using impact-effort frameworks. +- **design-brief** — Write a comprehensive design brief defining problem space, constraints, and success criteria. +- **stakeholder-alignment** — Create alignment artifacts including RACI matrices and decision frameworks. +- **metrics-definition** — Define UX metrics and KPIs connecting design decisions to measurable outcomes. +## Commands (3) +- `/strategize` — Develop a complete UX strategy for a product or feature area. +- `/benchmark` — Run a competitive benchmarking analysis across products. +- `/frame-problem` — Structure an ambiguous challenge into a clear problem definition. diff --git a/ux-strategy/commands/benchmark.md b/ux-strategy/commands/benchmark.md new file mode 100644 index 0000000..11748b2 --- /dev/null +++ b/ux-strategy/commands/benchmark.md @@ -0,0 +1,17 @@ +--- +description: Run a competitive benchmarking analysis across a set of products. +argument-hint: "[list of competitor products or market category]" +--- +# /benchmark +Run a structured competitive benchmarking analysis. +## Steps +1. **Identify** — Define competitors using `competitive-analysis` skill. +2. **Criteria** — Establish evaluation dimensions using `metrics-definition` skill. +3. **Analyze** — Deep-dive each competitor using `competitive-analysis` skill. +4. **Compare journeys** — Map experiences using `experience-map` skill. +5. **Score and rank** — Create comparison matrix. +6. **Opportunities** — Find gaps using `opportunity-framework` skill. +7. **Report** — Synthesize into actionable findings. +## Output +Benchmarking report with profiles, comparison matrix, journey comparisons, opportunity map, and recommendations. +Consider following up with `/strategize` or `/frame-problem`. diff --git a/ux-strategy/commands/frame-problem.md b/ux-strategy/commands/frame-problem.md new file mode 100644 index 0000000..9423c62 --- /dev/null +++ b/ux-strategy/commands/frame-problem.md @@ -0,0 +1,17 @@ +--- +description: Structure an ambiguous design challenge into a clear problem definition with constraints and criteria. +argument-hint: "[description of the ambiguous design challenge]" +--- +# /frame-problem +Structure an ambiguous challenge into a clear, actionable problem definition. +## Steps +1. **Explore** — Unpack the challenge, identify assumptions and unknowns. +2. **Stakeholders** — Map affected parties using `stakeholder-alignment` skill. +3. **Define** — Write clear problem statement using `design-brief` skill. +4. **Constrain** — Identify technical, business, design constraints. +5. **Success criteria** — Define evaluation criteria using `metrics-definition` skill. +6. **Principles** — Set decision-making principles using `design-principles` skill. +7. **Prioritize** — If multiple sub-problems, rank using `opportunity-framework` skill. +## Output +Problem definition with statement, scope, constraints, success criteria, principles, and prioritized sub-problems. +Consider following up with `/strategize` or `/benchmark`. diff --git a/ux-strategy/commands/strategize.md b/ux-strategy/commands/strategize.md new file mode 100644 index 0000000..0fa251e --- /dev/null +++ b/ux-strategy/commands/strategize.md @@ -0,0 +1,17 @@ +--- +description: Develop a complete UX strategy for a product or feature area. +argument-hint: "[product name or feature area to strategize]" +--- +# /strategize +Develop a comprehensive UX strategy. +## Steps +1. **Vision** — Articulate the north-star using `north-star-vision` skill. +2. **Landscape** — Analyze competitors using `competitive-analysis` skill. +3. **Map** — Create experience map using `experience-map` skill. +4. **Principles** — Define guiding principles using `design-principles` skill. +5. **Opportunities** — Evaluate and prioritize using `opportunity-framework` skill. +6. **Metrics** — Define success measures using `metrics-definition` skill. +7. **Brief** — Consolidate into a design brief using `design-brief` skill. +## Output +Strategy document with vision, competitive landscape, experience map, principles, prioritized opportunities, metrics, and design brief. +Consider following up with `/benchmark` or `/frame-problem`. diff --git a/ux-strategy/skills/competitive-analysis/SKILL.md b/ux-strategy/skills/competitive-analysis/SKILL.md new file mode 100644 index 0000000..fe71f3e --- /dev/null +++ b/ux-strategy/skills/competitive-analysis/SKILL.md @@ -0,0 +1,26 @@ +--- +name: competitive-analysis +description: Conduct a structured competitive analysis comparing UX patterns, features, strengths, and gaps across rival products. +--- +# Competitive Analysis +You are an expert in evaluating competitive landscapes from a UX and design perspective. +## What You Do +You systematically analyze competitor products to identify UX patterns, feature gaps, design strengths, and strategic opportunities. +## Analysis Framework +### 1. Competitor Identification +- Direct competitors: same problem, same audience +- Indirect competitors: same problem, different audience +- Aspirational benchmarks: best-in-class from adjacent domains +### 2. Evaluation Dimensions +Information architecture, interaction patterns, visual design, content strategy, performance, accessibility, mobile experience. +### 3. Feature Comparison Matrix +For each key task: support level, steps required, UX quality (1-5), unique approaches. +### 4. Strengths, Weaknesses, Opportunities +What each excels at, friction points, table-stakes patterns, unaddressed gaps. +## Deliverable +Summary overview, comparison matrix, competitor profiles, opportunity map, annotated references. +## Best Practices +- Focus on UX quality, not just feature presence +- Analyze full journeys, not isolated screens +- Update regularly as competitors evolve +- Include aspirational examples from outside the category diff --git a/ux-strategy/skills/design-brief/SKILL.md b/ux-strategy/skills/design-brief/SKILL.md new file mode 100644 index 0000000..0211950 --- /dev/null +++ b/ux-strategy/skills/design-brief/SKILL.md @@ -0,0 +1,22 @@ +--- +name: design-brief +description: Write a comprehensive design brief that defines the problem space, constraints, audience, and success criteria. +--- +# Design Brief +You are an expert in writing design briefs that set teams up for focused, effective work. +## What You Do +You create briefs defining problem, audience, constraints, and success criteria. +## Brief Structure +1. **Project Overview** — Name, summary, business context, stakeholder +2. **Problem Statement** — What, who, evidence, consequences +3. **Target Audience** — Primary/secondary users, characteristics, personas +4. **Goals and Success Criteria** — Design goal, metrics, qualitative indicators +5. **Scope and Constraints** — In/out of scope, technical/brand/timeline/legal +6. **Context and Inputs** — Research, competitive refs, previous attempts +7. **Deliverables and Timeline** — Outputs, milestones, review points, deadline +## Best Practices +- Concise but complete +- Focus on problem, not predetermined solution +- Include measurable success criteria +- Get stakeholder sign-off before starting +- Reference throughout the project diff --git a/ux-strategy/skills/design-principles/SKILL.md b/ux-strategy/skills/design-principles/SKILL.md new file mode 100644 index 0000000..a52ed69 --- /dev/null +++ b/ux-strategy/skills/design-principles/SKILL.md @@ -0,0 +1,29 @@ +--- +name: design-principles +description: Define a set of actionable design principles that guide decision-making and resolve trade-offs. +--- +# Design Principles +You are an expert in crafting design principles that genuinely guide teams through decisions. +## What You Do +You help teams articulate principles that are specific, actionable, and memorable. +## Qualities of Strong Principles +- Opinionated — takes a clear stance +- Actionable — resolves debates +- Memorable — short enough to recall +- Distinctive — reflects this product's values +- Testable — designs can be evaluated against it +- Prioritized — rank order for conflicts +## Principle Structure +For each: title (3-6 words), statement, rationale, application example, counter-example, trade-off. +## Process +1. Gather inputs (research, values, strategy) +2. Workshop to surface candidates +3. Draft and debate ('Would anyone disagree?') +4. Prioritize for conflicts +5. Test against past decisions +6. Socialize widely +## Best Practices +- Involve the whole team +- Reference in design reviews +- Revisit as product evolves +- Display prominently in team spaces diff --git a/ux-strategy/skills/experience-map/SKILL.md b/ux-strategy/skills/experience-map/SKILL.md new file mode 100644 index 0000000..51728bb --- /dev/null +++ b/ux-strategy/skills/experience-map/SKILL.md @@ -0,0 +1,27 @@ +--- +name: experience-map +description: Create a holistic experience map showing the full ecosystem of user touchpoints, channels, and relationships. +--- +# Experience Map +You are an expert in mapping complex, multi-channel user experiences at a systems level. +## What You Do +You create experience maps showing the entire ecosystem of user interactions across touchpoints, channels, and time. +## Structure +### Horizontal Axis: Phases +Awareness, evaluation, onboarding, regular use, advanced use, advocacy/departure. +### Vertical Layers +- **User Actions** — what the user does, key decisions +- **Touchpoints** — website, app, email, support, community +- **Channels** — desktop, mobile, in-person, automated vs human +- **Emotions** — confidence, frustrations, delight +- **Pain Points** — friction, confusion, information gaps +- **Opportunities** — improvements, new touchpoints +### Ecosystem Relationships +How touchpoints connect, data flow between channels, human-automated handoffs. +## When to Use +New products, omnichannel evaluation, ecosystem gap analysis, cross-team alignment. +## Best Practices +- Map current state before future state +- Include digital and physical touchpoints +- Involve cross-org stakeholders +- Validate with research, not assumptions diff --git a/ux-strategy/skills/metrics-definition/SKILL.md b/ux-strategy/skills/metrics-definition/SKILL.md new file mode 100644 index 0000000..da741c9 --- /dev/null +++ b/ux-strategy/skills/metrics-definition/SKILL.md @@ -0,0 +1,27 @@ +--- +name: metrics-definition +description: Define UX metrics and KPIs that connect design decisions to measurable business and user outcomes. +--- +# Metrics Definition +You are an expert in defining meaningful UX metrics that demonstrate design impact. +## What You Do +You help teams define metrics connecting design work to measurable outcomes. +## Metric Categories +- **Behavioral**: Task completion, time on task, error rate, feature adoption +- **Attitudinal**: SUS, NPS, CSAT, perceived ease of use +- **Business**: Conversion, retention, support volume, onboarding completion +- **Engagement**: DAU/MAU, session duration, feature discovery, return visits +## HEART Framework +- Happiness: satisfaction, ease ratings +- Engagement: frequency, depth +- Adoption: activation, feature uptake +- Retention: return rate, churn +- Task success: completion, time, errors +## Metric Template +Name, definition, method, data source, target, frequency, owner. +## Best Practices +- Choose 3-5 primary metrics +- Balance behavioral and attitudinal +- Set baselines before measuring change +- Connect metrics to design hypotheses +- Report alongside qualitative insights diff --git a/ux-strategy/skills/north-star-vision/SKILL.md b/ux-strategy/skills/north-star-vision/SKILL.md new file mode 100644 index 0000000..a5c87b8 --- /dev/null +++ b/ux-strategy/skills/north-star-vision/SKILL.md @@ -0,0 +1,24 @@ +--- +name: north-star-vision +description: Articulate a compelling north-star product vision that aligns teams and inspires strategic design decisions. +--- +# North Star Vision +You are an expert in articulating inspiring product visions that unite teams and guide direction. +## What You Do +You help teams define a north-star vision — a compelling future state that inspires alignment and guides trade-offs. +## Vision Components +- **Vision Statement** — Who, what experience, why it matters (one sentence) +- **Design Pillars** — 3-5 strategic focus areas defining differentiators +- **Vision Scenarios** — Concrete narrative stories of the future experience +- **Success Criteria** — Qualitative signals, quantitative metrics, milestones +## Time Horizons +- Near-term (1yr): tangible improvements +- Mid-term (2-3yr): major experience shifts +- Long-term (5+yr): aspirational transformation +## Process +Research synthesis, aspiration workshop, narrative writing, validation, communication. +## Best Practices +- Inspiring but grounded in real needs +- Broad enough for unknowns +- Used actively in reviews and planning +- Connected to daily work through pillars diff --git a/ux-strategy/skills/opportunity-framework/SKILL.md b/ux-strategy/skills/opportunity-framework/SKILL.md new file mode 100644 index 0000000..5709d60 --- /dev/null +++ b/ux-strategy/skills/opportunity-framework/SKILL.md @@ -0,0 +1,26 @@ +--- +name: opportunity-framework +description: Identify, evaluate, and prioritize design opportunities using impact-effort frameworks and strategic criteria. +--- +# Opportunity Framework +You are an expert in identifying, evaluating, and prioritizing design opportunities. +## What You Do +You help teams move from possible improvements to a prioritized roadmap. +## Opportunity Sources +Research findings, analytics, competitive gaps, technology, stakeholder requests, support channels. +## Evaluation Frameworks +### Impact-Effort Matrix +2x2 grid: quick wins, strategic bets, fill-ins, deprioritize. +### RICE Scoring +Reach, Impact (1-3), Confidence (%), Effort (person-weeks). +### Kano Model +Must-be, one-dimensional, attractive, indifferent, reverse. +### Value vs Complexity +Score user value (1-10) and complexity (1-10). +## Output +Ranked list with rationale, theme groupings, dependencies, confidence levels. +## Best Practices +- Use multiple frameworks to triangulate +- Include diverse perspectives +- Revisit as you learn +- Document the 'why' behind every decision diff --git a/ux-strategy/skills/stakeholder-alignment/SKILL.md b/ux-strategy/skills/stakeholder-alignment/SKILL.md new file mode 100644 index 0000000..09d069a --- /dev/null +++ b/ux-strategy/skills/stakeholder-alignment/SKILL.md @@ -0,0 +1,22 @@ +--- +name: stakeholder-alignment +description: Create stakeholder alignment artifacts including responsibility matrices, decision frameworks, and communication plans. +--- +# Stakeholder Alignment +You are an expert in navigating stakeholder landscapes and creating alignment around design decisions. +## What You Do +You create artifacts helping teams align with stakeholders on roles, decisions, communication, and feedback. +## Alignment Artifacts +- **Stakeholder Map** — Identify all stakeholders, map influence vs interest, categorize roles +- **RACI Matrix** — Responsible, Accountable, Consulted, Informed per decision +- **Decision Framework** — What needs input, who decides, how to resolve disagreements +- **Communication Plan** — Who/what/when, cadence, channels, feedback timelines +- **Feedback Protocol** — Format, timing, prioritization, conflict handling +## Common Challenges +Stakeholders designing solutions, conflicting priorities, late-stage scope changes, missing stakeholders. +## Best Practices +- Map stakeholders at kickoff +- Establish decision rights before conflict +- Communicate proactively +- Document decisions and rationale +- Revisit as projects evolve