¶
Quick facts
Phase: Develop | Version: 2.0.0 | Category: specification | License: 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
How to Use¶
Use the /design-rationale slash command:
Or reference the skill file directly: skills/develop-design-rationale/SKILL.md
Instructions¶
When asked to document design rationale, follow these steps:
-
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.
-
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.
-
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.
-
Define Evaluation Criteria Specify how options were assessed: usability heuristics, technical feasibility, brand alignment, user research findings, business requirements, or design principles.
-
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.
-
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.
-
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 Template¶
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¶
- [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¶
- [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¶
[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¶
- [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.
Example Output¶
Design Rationale: Primary Navigation Pattern for Mobile App
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): ⅞ users found target feature faster with bottom nav than hamburger
- Analytics: Current top 5 features account for 78% of all feature usage
- Competitive analysis: ⅘ 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¶
- Visibility: Tab bar is always visible, creating constant awareness of primary capabilities
- Accessibility: Large, persistent tap targets meet WCAG requirements without accommodation
- Mental model: Users immediately understand app structure upon opening
- 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.
Real-World Examples¶
See this skill applied to three different product contexts:
Storevine (B2B): Storevine B2B ecommerce platform — Campaigns audience selection UX design decision
Prompt:
/design-rationale
Project: Campaigns — native email marketing for Storevine merchants
Decision: Audience selection UX for the campaign creation flow
Stage: Pre-sprint design review — finalizing Figma specs before engineering
Decision I need to document:
- We debated 3 audience selection approaches before the design review:
A. Custom filter builder (SQL-like nested conditions, matches Klaviyo)
B. Pre-built named segments only (curated list, no customization)
C. Pre-built segments as default + custom filter as secondary option
- We chose Option C after design review with PM, design lead, and eng lead
Context:
- Primary target segment: non-adopter merchants (no current email tool)
- Interview data: 3 of 8 merchants cited setup complexity as the barrier
- Figma link: [internal — Campaigns audience selection v3 spec]
Need: full design rationale document for the engineering handoff package.
Decision makers: Design Lead, Growth PM, Engineering Lead.
Output:
Design Rationale: Campaigns Audience Selection UX¶
Brainshelf (Consumer): Brainshelf consumer PKM app — digest email layout design decision for the Resurface feature
Prompt:
/design-rationale
digest email layout for resurface. dan showed three options:
option A: rich cards — article thumbnail, title, excerpt, topic tag
for each item. looks great in figma but heavy on images and might
trigger promotions tab.
option B: structured text — article title (linked), source domain,
topic tag, estimated read time. no images. clean, editorial feel.
fast to scan.
option C: minimal plain text — just titles and links, no styling.
maximum deliverability but looks like a system notification, not a
product experience.
we did a quick preference test with 12 users. 9 preferred option B.
reasons: "fast," "doesn't look like spam," "I'd actually read this."
going with B. need the rationale written up.
Output:
Design Rationale: Resurface Digest Email Layout¶
Workbench (Enterprise): Workbench enterprise collaboration platform: guided wizard vs. blank canvas for Blueprint creation flow
Prompt:
/design-rationale
Decision: Blueprint creation flow -- guided wizard vs. blank canvas
Product: Workbench Blueprints (enterprise doc templates with required sections and approval gates)
Stage: Develop phase, pre-PRD
Problem: How should a new Blueprint be created? Two options:
- Option A: Guided wizard -- step-by-step flow, one section per screen, progress indicator, validation per step
- Option B: Blank canvas -- full template opens in the editor, all sections visible, fill in any order (Confluence model)
- Option C (hybrid): Wizard for first-time creation, canvas for returning authors who have completed a Blueprint before
Context:
- Enterprise users are not power users of Workbench yet -- Blueprints is a new feature
- Required sections are the core differentiator; the creation flow must make enforcement feel helpful, not punitive
- Discovery interviews: middle managers act as "docs police"; the creation flow should reduce, not increase, that burden
- Closed-beta preference test (8 users [fictional]): 6 preferred wizard on first use, 5 preferred canvas after their second Blueprint
- Karen L. (Eng Lead): wizard adds 1 sprint of effort vs. canvas [fictional]
- Tomas G. (Design Lead): wizard produces cleaner first submissions but risks feeling patronizing for experienced authors
Evaluation criteria: first-submission completeness rate, author time-to-submit, author satisfaction (NPS), engineering effort, scalability to custom templates
Stakeholders: Sandra C. (Head of Product), Karen L. (Eng Lead), Tomas G. (Design Lead)
Output:
Design Rationale: Blueprint Creation Flow¶
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
- Document is useful to someone inheriting this design
Output Format¶
Use the template in references/TEMPLATE.md to structure the output.