Design Rationale

Quick facts

Phase: Develop | Version: 2.1.0 | Category: specification | License: Apache-2.0

Try it: /pm-skills:develop-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

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

How to Use

Invoke the skill by name (/pm-skills:develop-design-rationale on Claude Code, $develop-design-rationale on Codex):

/pm-skills:develop-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 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.

Examples

See references/EXAMPLE.md for a completed example.

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): 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.

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:

develop-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:

develop-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:

develop-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
• A reader who inherits this design can reconstruct why the chosen option won without asking anyone