---
title: "Design Rationale"
description: "Documents the reasoning behind design decisions including alternatives considered, trade-offs evaluated, and principles applied. Use when making significant UX decisions, aligning with stakeholders on design direction, or preserving design context for future reference."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Develop
  - specification
---

:::note[Quick facts]
**Phase:** Develop | **Version:** 2.0.0 | **Category:** specification | **License:** Apache-2.0
:::

**Try it:** `/design-rationale "Your context here"`

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:

```
/design-rationale "Your context here"
```

Or reference the skill file directly: `skills/develop-design-rationale/SKILL.md`

## 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 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

<!-- 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.*

## Example Output

<details>
<summary>Design Rationale: Primary Navigation Pattern for Mobile App</summary>

# 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](https://figma.com/file/xxx)
- [User research: Navigation Usability Study](https://docs.google.com/xxx)
- [Analytics: Feature Usage Report Q4 2025](https://looker.com/xxx)
- 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.*

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . Campaigns audience selection UX design decision</summary>

**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

</details>

<details>
<summary>Brainshelf (Consumer): Brainshelf consumer PKM app . digest email layout design decision for the Resurface feature</summary>

**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

</details>

<details>
<summary>Workbench (Enterprise): "Workbench enterprise collaboration platform: guided wizard vs. blank canvas for Blueprint creation flow"</summary>

**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

</details>

## 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.
