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)