05 Design Button Hierarchy

---
name: design-button-hierarchy
description: Create clear primary/secondary/tertiary action distinctions
domain: ui-design
skill-type: generative
version: 1.0.0
author: refactoring-ui-expert
prerequisites: []
dependencies:
  - 03-build-color-palette
---

# Skill: Design Button Hierarchy

## Purpose
Create clear distinctions between primary, secondary, and tertiary actions so users know which action to take.

## Type
Generative + Evaluative

## Input
- List of actions/buttons needed
- Relative importance of each action (primary, secondary, tertiary)
- Context (form, modal, page, toolbar)

## Output
- Button style specifications for each level
- Pass/Fail assessment of existing button hierarchy

## Transformation Performed
Maps action importance to visual treatment: primary = filled brand color, secondary = outline or subtle (including grey solid), tertiary = text-only or link style.

## Decision Criteria

### PASS (Good Button Hierarchy)
- **One clear primary action** per screen/section (filled, high contrast, brand color)
- **Secondary actions** visually subordinate (outlined, ghost, or lower contrast solid including grey)
- **Tertiary actions** minimal (text link or subtle)
- Clear visual distinction between levels (not subtle 10% differences)
- Destructive actions (delete) use red but don't compete with primary

### FAIL (Poor Button Hierarchy)
- Multiple buttons with equal visual weight
- Primary action not obvious
- Very light grey (200) secondary looks disabled
- Destructive actions draw more attention than primary
- All buttons filled with same color

## Button Style Patterns

| Level | Background | Border | Text | Use Case |
|-------|------------|--------|------|----------|
| **Primary** | Brand color (solid) | None | White/light | Main CTA, save, submit |
| **Secondary** | Grey (solid) or transparent | Brand color (if outline) | Brand color or grey | Alternative action, cancel |
| **Tertiary** | Transparent | None | Brand color or gray | Optional actions, learn more |
| **Destructive** | Red | None | White | Delete, remove (not competing) |
| **Disabled** | Gray 200 | None | Gray 400 | Cannot proceed |

## Visual/UX Signals Used
1. **Fill vs outline**: Filled = primary, outline = secondary
2. **Color saturation**: More saturated = more important
3. **Size**: Primary can be slightly larger
4. **Position**: Primary often on right or bottom (reading pattern)

## Common Failure Modes

| Failure | Description | Fix |
|---------|-------------|-----|
| **Button Battle** | Save and Cancel both filled brand | Make Cancel outline or grey solid |
| **Gray Button Confusion** | Very light grey (200) secondary looks disabled | Use grey 400-500 or outline, not near-white grey |
| **Red Alert** | Delete button more prominent than primary | Make delete text-only or smaller |
| **Primary Overload** | 3+ "primary" buttons | Choose one primary, demote others |
| **Invisible Tertiary** | Text links same color as body | Use brand color or underline |

## Prerequisites
- Visual hierarchy established
- Color palette defined

## Dependencies
- `build-color-palette` (needs brand and semantic colors)
- `establish-visual-hierarchy` (buttons are part of hierarchy)

## Refactoring UI References
- "Make primary actions obvious"
- "Destructive actions shouldn't dominate"
- "Secondary actions should be clear but not prominent - outline styles or lower contrast background colors are great options"

## Example Assessment

**Input:** Modal with "Save Changes" (filled blue), "Cancel" (filled grey), "Delete" (filled red)

**Evaluation:** PARTIAL
- Cancel: Grey filled is acceptable secondary treatment (lower contrast solid)
- Delete: Filled red competes with Save (should be text red)
- Issue: Two actions with solid fills competing

**Recommendation:**
- Save: Keep filled blue (primary)
- Cancel: Grey filled is acceptable, but could be outline for clearer distinction
- Delete: Change to text red (destructive shouldn't compete)