Develop Design Rationale
- 498 installs
- 518 repo stars
- Updated August 4, 2026
- product-on-purpose/pm-skills
develop-design-rationale is a Claude Code product-design skill that documents the reasoning behind UX decisions including alternatives considered, evaluation criteria, and trade-offs for developers who need stakeholder a
About
develop-design-rationale is a pm-skills agent skill (version 2.1.0) that produces a design rationale document from references/TEMPLATE.md preserving why a UX choice was made, not just what was built. The skill walks through decision summary, context, at least 2-3 options considered fairly, explicit evaluation criteria, reasoning, trade-offs accepted, reversibility, and follow-up considerations. Developers reach for develop-design-rationale before design reviews, when multiple valid UX approaches exist, or when onboarding engineers to past interface decisions. It complements develop-adr for technical choices and develop-solution-brief for overall solution direction. Output follows a 10-section template with a quality checklist ensuring future readers can reconstruct why the chosen option won without asking the original team.
- develop-design-rationale
- Design & UI/UX
- AI-coding skill
Develop Design Rationale by the numbers
- 498 all-time installs (skills.sh)
- +26 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #594 of 1,880 Design & UI/UX skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/product-on-purpose/pm-skills --skill develop-design-rationaleAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 498 |
|---|---|
| repo stars | ★ 518 |
| Last updated | August 4, 2026 |
| Repository | product-on-purpose/pm-skills ↗ |
How do you document UX design decision rationale?
Helps with design & ui/ux tasks.
Who is it for?
Frontend engineers and designers documenting significant UX decisions that need stakeholder justification and future onboarding context.
Skip if: Low-stakes reversible UI tweaks where recording rationale in a PR comment or ticket is sufficient ceremony.
When should I use this skill?
A developer is making a significant UX decision, preparing for a design review, or needs to justify why one interface approach beat alternatives.
What you get
A design rationale document with decision summary, context, options considered, evaluation criteria, reasoning, trade-offs, reversibility notes, follow-up considerations, and decision history.
- Design rationale document
- Trade-off and reversibility analysis
By the numbers
- Skill version 2.1.0 with a 10-section design rationale template
- Requires documenting at least 2-3 UX alternatives before finalizing
Files
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Design Rationale
A design rationale document captures the "why" behind design decisions.the context, constraints, alternatives considered, and reasoning that led to a particular solution. While designs themselves show what was built, rationale documents preserve institutional knowledge about why it was built that way.
When to Use
- When making significant UX decisions that affect user experience
- Before design reviews to prepare stakeholder discussions
- When multiple valid approaches exist and the choice needs justification
- To onboard new team members to existing design decisions
- When revisiting past decisions to understand original reasoning
- During design system evolution to document pattern choices
When NOT to Use
- The decision is architectural or a technology selection -> use
develop-adr(Nygard format) - You need stakeholder alignment on the overall solution direction -> use
develop-solution-brief - You are documenting exploration findings rather than a decision -> use
develop-spike-summary - The decision is trivially reversible and low-stakes: a rationale document adds ceremony; record the reasoning in the PR or ticket instead
Instructions
When asked to document design rationale, follow these steps:
1. State the Decision Begin with a clear, one-sentence summary of what design decision was made. This becomes the title and reference point for the document.
2. Describe the Context Explain the situation that prompted this decision. What problem were you solving? What constraints existed? What user needs informed the direction? Include relevant research findings.
3. List Options Considered Document at least 2-3 alternatives that were evaluated. For each option, describe what it would look like and its key characteristics. Be fair to all options.avoid strawmen.
4. Define Evaluation Criteria Specify how options were assessed: usability heuristics, technical feasibility, brand alignment, user research findings, business requirements, or design principles.
5. Explain the Reasoning Walk through why the chosen option best meets the criteria. Be explicit about trade-offs.what you gained and what you sacrificed. Acknowledge where the decision is reversible vs. irreversible.
6. Document Trade-offs Accepted Every design decision involves trade-offs. Name what you gave up and why it was acceptable. This honesty helps future teams understand constraints.
7. Note Follow-up Considerations Capture anything that needs attention later: metrics to watch, conditions that might warrant revisiting the decision, or related decisions to make.
Output Format
Use the template in references/TEMPLATE.md to structure the output. A complete rationale fills every template section: Decision Summary; Context; Options Considered; Evaluation; Decision Rationale; Trade-offs Accepted; Reversibility; Follow-up Considerations; Supporting Materials; and Decision History.
Quality Checklist
Before finalizing, verify:
- [ ] Decision is clearly stated in one sentence
- [ ] Context explains the "why now" and constraints
- [ ] Multiple alternatives are documented fairly
- [ ] Evaluation criteria are explicit
- [ ] Reasoning addresses why chosen option beats alternatives
- [ ] Trade-offs are honestly acknowledged
- [ ] A reader who inherits this design can reconstruct why the chosen option won without asking anyone
Examples
See references/EXAMPLE.md for a completed example.
{
"schema": 1,
"skill": "develop-design-rationale",
"runs_per_query": 3,
"trigger_threshold": 0.5,
"queries": [
{
"q": "Document the design rationale for moving filters into a left sidebar instead of the top bar",
"expect": "trigger",
"split": "train"
},
{
"q": "We debated three onboarding flows and landed on progressive profiling. Write down why before the context evaporates.",
"expect": "trigger",
"split": "train"
},
{
"q": "Prepare the reasoning behind the new card-based dashboard layout for Thursday's design review",
"expect": "trigger",
"split": "train"
},
{
"q": "Capture which alternatives we considered for the mobile navigation and why bottom tabs won",
"expect": "trigger",
"split": "train"
},
{
"q": "New designers keep asking why search is hidden behind an icon on mobile. Put the original reasoning and trade-offs in writing.",
"expect": "trigger",
"split": "train"
},
{
"q": "Write up why we adopted inline editing over modal dialogs in our table views, including what we sacrificed",
"expect": "trigger",
"split": "train"
},
{
"q": "I want a record of why the checkout uses a single accent color, with the accessibility criteria we evaluated against",
"expect": "trigger",
"split": "validation"
},
{
"q": "Design chose skeleton screens over spinners across the app. Document the options we weighed and the principles applied.",
"expect": "trigger",
"split": "validation"
},
{
"q": "Before we ship the redesigned settings page, document why we grouped preferences by task instead of by feature area",
"expect": "trigger",
"split": "validation"
},
{
"q": "Stakeholders keep relitigating the removal of the hamburger menu. Give me a document that walks through the alternatives and why we chose what we chose.",
"expect": "trigger",
"split": "validation"
},
{
"q": "Record our decision to move session storage from cookies to Redis, with the consequences",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "develop-adr",
"notes": "Technology selection, Nygard ADR territory"
},
{
"q": "Give me a one-page overview of the proposed redesign I can use to get exec buy-in",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "develop-solution-brief",
"notes": "Pitching for alignment, not preserving decision reasoning"
},
{
"q": "We spent two days exploring whether the design system tokens can support theming. Summarize the findings and the recommendation.",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "develop-spike-summary",
"notes": "Time-boxed exploration findings, not a decision record"
},
{
"q": "Synthesize the usability test sessions from last week into themes and recommendations",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Write acceptance criteria for the new filter sidebar story",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Fix the CSS so the sidebar stops overlapping the footer at small breakpoints",
"expect": "no-trigger",
"split": "train"
},
{
"q": "Document why we selected Postgres full-text search over Elasticsearch and what trade-offs we accepted",
"expect": "no-trigger",
"split": "validation",
"near_miss_of": "develop-adr",
"notes": "Reasoning ask, but the decision is architectural"
},
{
"q": "Draft release notes announcing the redesigned dashboard to customers",
"expect": "no-trigger",
"split": "validation"
},
{
"q": "Plan a two-day team offsite agenda for the design org",
"expect": "no-trigger",
"split": "validation"
},
{
"q": "Map the customer journey for first-time buyers from landing page to first purchase",
"expect": "no-trigger",
"split": "validation"
}
]
}
develop-design-rationale - Version History
| Version | Date | Release | Effort | Type | Summary |
|---|---|---|---|---|---|
| 2.1.0 | 2026-06-10 | v2.26.0 | F-12-batch-2 | minor | Quality convergence: When NOT to Use + output-contract enumeration (F-12 Batch 2) |
| 2.0.0 | 2026-01-26 | - | - | baseline | Prior published version |
2.1.0 (2026-06-10)
Quality-convergence minor (F-12 Batch 2): added a "When NOT to Use" section with boundary pointers to neighboring skills, and the Output Format now enumerates the template sections a complete artifact fills. No template or example changes.
2.0.0 (2026-01-26)
Baseline row for the prior published version; see git history for its changes.
Design Rationale: Primary Navigation Pattern for Mobile App
Decision Summary
Decision: Use a bottom tab bar with 5 primary actions plus a "More" overflow menu for secondary features. Date: January 2026 Decision Makers: Sarah (Design Lead), Marcus (PM), Chen (Engineering Lead) Status: Implemented
---
Context
Problem Statement
Our mobile app has grown from 12 to 50+ features over three years. The current hamburger menu navigation has become a "junk drawer" where users struggle to find features. Task completion rates have dropped 15% in the past year, and support tickets about "where is X?" have increased 40%.
User Need
Users need to quickly access core functionality without hunting through menus. Research shows our users typically need the same 5-7 features in 80% of sessions, but they can't remember where those features live in the current navigation.
Constraints
| Constraint Type | Description |
|---|---|
| Technical | Must work across iOS and Android without platform-specific implementations |
| Business | Cannot remove any features; deprecation requires 6-month notice to enterprise clients |
| Timeline | Must ship by end of Q1 to align with marketing campaign |
| Resources | 2 engineers, 1 designer available for implementation |
| Brand/Platform | Must follow both iOS HIG and Material Design enough to feel native on each |
Design Principles Applied
- Progressive disclosure: Surface what's needed, hide what's not until relevant
- Recognition over recall: Users shouldn't have to remember where things are
- Flexibility and efficiency: Support both novice wayfinding and expert shortcuts
---
Options Considered
Option A: Enhanced Hamburger Menu with Categories
Description: Keep the hamburger menu but reorganize features into clear categories with icons. Add a "Favorites" section users can customize.
Pros:
- Minimal development effort.iterates on existing pattern
- Preserves screen real estate for content
- Familiar pattern for existing users
- Scales to unlimited features
Cons:
- Hidden navigation still requires recall ("where's Settings?")
- Extra tap to reach any feature
- User research shows low engagement with customization features
- Doesn't solve core discoverability problem
---
Option B: Floating Action Button (FAB) with Radial Menu
Description: A prominent FAB in the bottom-right that expands to show 6 primary actions in a radial/fan pattern. Secondary features remain in a hamburger menu.
Pros:
- Highly discoverable.the FAB draws attention
- Quick access to primary actions (single tap to reveal)
- Visually distinctive and modern
- Works well for task-oriented apps
Cons:
- Radial menus have poor accessibility (hard to tap precisely)
- Only practical for 6-8 items; doesn't solve secondary navigation
- Covers content when expanded
- Not a standard pattern on iOS (feels Android-native)
---
Option C: Bottom Tab Bar with More Menu (Selected)
Description: A persistent 5-item bottom tab bar showing the most-used features. The 5th tab is "More" which opens a organized list of all other features.
Pros:
- Most accessible pattern.large tap targets, always visible
- Industry standard across both iOS and Android
- Highly discoverable.users instantly see what app does
- Research shows 5 items is optimal for quick scanning
- "More" menu can be organized and searchable
Cons:
- Uses 50px of screen height permanently
- Only 4 primary features get direct access
- Requires difficult prioritization decisions
- "More" menu can still become cluttered
---
Evaluation
Criteria
| Criterion | Weight | Description |
|---|---|---|
| Discoverability | High | How easily can users find features? |
| Accessibility | High | Can users with motor or vision impairments use it? |
| Task efficiency | High | How quickly can users complete common tasks? |
| Scalability | Medium | Does it work as features grow? |
| Implementation effort | Medium | How much engineering work? |
| Platform consistency | Medium | Does it feel native on both iOS and Android? |
Comparison Matrix
| Criterion | Option A | Option B | Option C |
|---|---|---|---|
| Discoverability | Poor | Good | Excellent |
| Accessibility | Good | Poor | Excellent |
| Task efficiency | Poor | Good | Excellent |
| Scalability | Excellent | Poor | Good |
| Implementation effort | Low | Medium | Medium |
| Platform consistency | Good | Poor | Excellent |
User Research Input
- Usability testing (n=8): 7/8 users found target feature faster with bottom nav than hamburger
- Analytics: Current top 5 features account for 78% of all feature usage
- Competitive analysis: 4/5 top-rated productivity apps use bottom tab navigation
- User quote: "I wish I didn't have to think about where things are. Just show me."
---
Decision Rationale
Why Option C?
The bottom tab bar provides the best balance of discoverability, accessibility, and task efficiency.our three highest-weighted criteria. While it sacrifices some screen real estate and limits direct access to 4 features, user research strongly validates that our users primarily need quick access to a small set of features.
The hamburger menu (Option A) fails to solve our core problem: users still have to remember where features are. The FAB approach (Option B) has significant accessibility concerns and would require iOS users to learn an Android-centric pattern.
Key Differentiators
1. Visibility: Tab bar is always visible, creating constant awareness of primary capabilities 2. Accessibility: Large, persistent tap targets meet WCAG requirements without accommodation 3. Mental model: Users immediately understand app structure upon opening 4. Cross-platform: Pattern works identically on iOS and Android, reducing engineering complexity
Dissenting Opinions
Chen (Engineering) initially preferred Option A due to lower implementation effort. After reviewing the user research showing 15% task completion decline, he agreed that Option C's benefits justified the additional work.
---
Trade-offs Accepted
What We Gave Up
| Trade-off | Impact | Why Acceptable |
|---|---|---|
| Screen real estate | 50px permanently used by navigation | On modern devices, this is <5% of screen; content scrolls. User research showed no concern. |
| Secondary feature access | Requires 2 taps for "More" features | 78% of usage is top 5 features; acceptable friction for long tail |
| Feature count limitation | Can only highlight 4 features directly | Forces prioritization; actually a benefit for user clarity |
Risks
| Risk | Likelihood | Mitigation |
|---|---|---|
| Users can't find features in "More" | Medium | Add search within More menu; use clear categories |
| Wrong 4 features selected | Medium | A/B test feature selection; make configurable per user role |
| Enterprise pushback on change | Low | Provide documentation and training materials; grandfather existing muscle memory with shortcuts |
---
Reversibility
Is this decision reversible? Yes, with effort
Cost to reverse: Significant.requires navigation rewrite and user re-education. Estimate 4-6 weeks engineering work plus user communication.
Conditions that would warrant reverting:
- Task completion rates don't improve after 3 months
- User complaints about tab bar exceed hamburger complaints (with statistical significance)
- A/B test shows no improvement in feature discoverability
---
Follow-up Considerations
Metrics to Monitor
- Task completion rate: Should improve from 65% to 75%+ for core flows
- "Where is X?" support tickets: Should decrease by 30%+
- Feature discovery: Track % of users who use features in "More" menu
- Time to task completion: Should decrease for top 5 features
Future Decisions Required
- Which 4 features get tab bar placement (separate decision document)
- "More" menu organization and categories
- Whether to add user customization of tab bar items
- Tablet/iPad navigation pattern (larger screen may warrant different approach)
Revisit Triggers
- If app feature count exceeds 100 and "More" becomes unwieldy
- If user research reveals significantly different feature usage patterns
- If platform conventions change substantially
---
Supporting Materials
- Figma designs: Bottom Navigation Exploration
- User research: Navigation Usability Study
- Analytics: Feature Usage Report Q4 2025
- Related ADR: Mobile Framework Selection (documented separately)
---
Decision History
| Date | Change | Author |
|---|---|---|
| 2026-01-14 | Initial decision documented | Sarah Chen |
| 2026-01-14 | Added user research findings | Sarah Chen |
---
This rationale documents the reasoning at the time of decision. Context may change.
Design Rationale: [Decision Title]
Decision Summary
Decision: [One-sentence statement of what was decided] Date: [When decision was made] Decision Makers: [Who was involved] Status: [Proposed | Accepted | Implemented | Deprecated | Superseded by DR-XXX]
---
Context
Problem Statement
[What problem or opportunity prompted this decision?]
User Need
[What user need does this address? Include relevant research.]
Constraints
| Constraint Type | Description |
|---|---|
| Technical | [Technical limitations or requirements] |
| Business | [Business rules or requirements] |
| Timeline | [Time constraints] |
| Resources | [Resource limitations] |
| Brand/Platform | [Brand guidelines or platform conventions] |
Design Principles Applied
<!-- Which design principles guided this decision -->
- [Principle 1]: [How it applies]
- [Principle 2]: [How it applies]
---
Options Considered
Option A: [Name]
Description: [What this option looks like]
Visual/Wireframe: [Link or embedded image if available]
Pros:
- [Advantage 1]
- [Advantage 2]
- [Advantage 3]
Cons:
- [Disadvantage 1]
- [Disadvantage 2]
---
Option B: [Name]
Description: [What this option looks like]
Visual/Wireframe: [Link or embedded image if available]
Pros:
- [Advantage 1]
- [Advantage 2]
- [Advantage 3]
Cons:
- [Disadvantage 1]
- [Disadvantage 2]
---
Option C: [Name] (Selected)
Description: [What this option looks like]
Visual/Wireframe: [Link or embedded image if available]
Pros:
- [Advantage 1]
- [Advantage 2]
- [Advantage 3]
Cons:
- [Disadvantage 1]
- [Disadvantage 2]
---
Evaluation
Criteria
| Criterion | Weight | Description |
|---|---|---|
| [Criterion 1] | High/Med/Low | [What this measures] |
| [Criterion 2] | High/Med/Low | [What this measures] |
| [Criterion 3] | High/Med/Low | [What this measures] |
| [Criterion 4] | High/Med/Low | [What this measures] |
Comparison Matrix
| Criterion | Option A | Option B | Option C |
|---|---|---|---|
| [Criterion 1] | [Score/Rating] | [Score/Rating] | [Score/Rating] |
| [Criterion 2] | [Score/Rating] | [Score/Rating] | [Score/Rating] |
| [Criterion 3] | [Score/Rating] | [Score/Rating] | [Score/Rating] |
| [Criterion 4] | [Score/Rating] | [Score/Rating] | [Score/Rating] |
User Research Input
<!-- Relevant findings from user research -->
- [Finding 1]
- [Finding 2]
---
Decision Rationale
Why Option C?
[Detailed explanation of why this option was chosen over alternatives]
Key Differentiators
[What specifically made this option better than others]
Dissenting Opinions
<!-- Capture any disagreement for the record -->
[Any team members who preferred other options and their reasoning]
---
Trade-offs Accepted
What We Gave Up
| Trade-off | Impact | Why Acceptable |
|---|---|---|
| [Trade-off 1] | [What's affected] | [Why it's okay] |
| [Trade-off 2] | [What's affected] | [Why it's okay] |
Risks
| Risk | Likelihood | Mitigation |
|---|---|---|
| [Risk 1] | High/Med/Low | [How we'll address] |
| [Risk 2] | High/Med/Low | [How we'll address] |
---
Reversibility
Is this decision reversible? [Yes, easily | Yes, with effort | Partially | No]
Cost to reverse: [What would it take to change this later]
Conditions that would warrant reverting:
- [Condition 1]
- [Condition 2]
---
Follow-up Considerations
Metrics to Monitor
- [Metric 1]: [What it tells us]
- [Metric 2]: [What it tells us]
Future Decisions Required
- [Related decision 1]
- [Related decision 2]
Revisit Triggers
<!-- When should we reconsider this decision -->
- [Trigger 1]
- [Trigger 2]
---
Supporting Materials
- [Link to design files]
- [Link to user research]
- [Link to prototype]
- [Link to related decisions]
---
Decision History
| Date | Change | Author |
|---|---|---|
| [Date] | Initial decision | [Name] |
| [Date] | [Update] | [Name] |
---
This rationale documents the reasoning at the time of decision. Context may change.
Related skills
Frontend DesignGenerate distinctive, production-grade frontend interfaces and components that avoid generic AI aesthetics.716k165k
Web Design GuidelinesAutomatically audit frontend code against the latest Vercel Web Interface Guidelines for consistency, accessibility, and UX quality.498k29.6k
Lark WhiteboardGenerate valid Lark Whiteboard (Feishu Board) documents with correctly placed connectors, automatic routing, and proper schema compliance directly from agent inst389k16k
Sleek Design Mobile AppsGenerate mobile app screens and UI from plain English descriptions using the Sleek.design API.315k476
Design Taste FrontendOverride generic LLM frontend output with intentional, metric-driven UI/UX taste.301k69.4k
Ui Ux Pro MaxGet instant, high-quality UI/UX decisions, component recommendations, style guidance, and code improvements across web and mobile projects.290k112kHow it compares
Use develop-design-rationale for UX interface decisions; switch to develop-adr when the decision is architectural or a technology selection.
FAQ
How is develop-design-rationale different from an ADR?
develop-design-rationale records UX and interface reasoning with alternatives and usability criteria. develop-adr in pm-skills covers architectural and technology selections using the Nygard ADR format instead.
What sections does develop-design-rationale include?
develop-design-rationale fills a 10-section template covering decision summary, context, options considered, evaluation, reasoning, trade-offs, reversibility, follow-up considerations, supporting materials, and decision history.
When should teams skip develop-design-rationale?
develop-design-rationale adds ceremony best reserved for significant UX decisions. Skip it for trivially reversible low-stakes interface changes and record reasoning in the PR or ticket instead.