Design Rationale
- 942 installs
- 1.9k repo stars
- Updated June 14, 2026
- owl-listener/designer-skills
Design-rationale is a Claude Code skill that writes structured design decision documents connecting UI choices to user needs, business goals, and evidence for developers and stakeholders who must defend or revisit design
About
Design-rationale is a documentation skill for articulating why specific design decisions were made. It follows a six-part structure: the decision itself, problem context and constraints, alternatives considered, supporting evidence from research or data, reasoning tied to user needs and business goals, and explicit trade-offs. The skill helps developers, designers, and agents produce rationale that future readers can audit without reopening every workshop. Design-rationale fits after mockups or component choices when teams need traceable justification for accessibility patterns, navigation models, or visual hierarchy. It does not generate pixels or code; it turns choices into defensible written records. Invoke it when a PR, design review, or stakeholder question needs a clear answer for why option A beat option B.
- 7-part rationale structure: decision, context, options, evidence, reasoning, trade-offs, validation plan
- Quality checklist tying rationale to user needs—not designer preference alone
- Guidance on when to write: major direction, pattern breaks, and debated choices
- Explicit trade-offs and deprioritization for auditability months later
- Validation plan section linking decisions to metrics and feedback
Design Rationale by the numbers
- 942 all-time installs (skills.sh)
- +41 installs in the week ending Jul 29, 2026 (Skillselion tracking)
- Ranked #443 of 1,888 Design & UI/UX skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Jul 31, 2026 (Skillselion catalog sync)
npx skills add https://github.com/owl-listener/designer-skills --skill design-rationaleAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 942 |
|---|---|
| repo stars | ★ 1.9k |
| Security audit | 3 / 3 scanners passed |
| Last updated | June 14, 2026 |
| Repository | owl-listener/designer-skills ↗ |
How do you document why a design decision was made?
Document why design choices were made so future you, stakeholders, and agents can defend or revisit decisions with evidence.
Who is it for?
Developers and designers who need auditable written justification for UI or UX choices before review or handoff.
Skip if: Teams that only need visual mockups or component code without written decision traceability.
When should I use this skill?
A design choice needs documented justification with alternatives, evidence, and trade-offs for stakeholders or future agents.
What you get
Structured design rationale document with decision, context, options, evidence, reasoning, and trade-offs sections
- design rationale document
By the numbers
- Uses a six-section rationale structure covering decision through trade-offs
Files
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
Related skills
Frontend DesignGenerate distinctive, production-grade frontend interfaces and components that avoid generic AI aesthetics.698k164k
Web Design GuidelinesAutomatically audit frontend code against the latest Vercel Web Interface Guidelines for consistency, accessibility, and UX quality.486k29.4k
Lark WhiteboardGenerate valid Lark Whiteboard (Feishu Board) documents with correctly placed connectors, automatic routing, and proper schema compliance directly from agent inst382k15.8k
Sleek Design Mobile AppsGenerate mobile app screens and UI from plain English descriptions using the Sleek.design API.315k470
Design Taste FrontendOverride generic LLM frontend output with intentional, metric-driven UI/UX taste.284k66.9k
Ui Ux Pro MaxGet instant, high-quality UI/UX decisions, component recommendations, style guidance, and code improvements across web and mobile projects.282k109kFAQ
What sections does design-rationale include?
Design-rationale documents six sections: the specific decision, problem context, alternatives considered, evidence used, reasoning tied to goals and principles, and trade-offs accepted. Together they form a complete audit trail.
Does design-rationale generate UI mockups?
Design-rationale does not generate mockups or code. The skill writes structured rationale explaining why a design choice was made, what options were rejected, and what evidence supported the final decision.
Is Design Rationale safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.