| name | button-and-action-system |
| description | Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction. |
Button and Action System
Purpose
The Button and Action System provides a methodology for designing the primary
drivers of user interaction. Buttons are the fundamental link between a user's
intent and a system's response. This system ensures that every action is
visually prioritized (Hierarchy), consistently styled (Cohesion), and easy to
interact with across all devices (Usability). It moves beyond "making a button"
to defining a logical framework for how different types of actions relate to
each other within a layout.
Use Cases
- Defining a button component library for a design system.
- Establishing a hierarchy of actions in a Hero section or Page Header.
- Organizing groups of related actions (e.g., Save, Cancel, Delete).
- Designing specialized triggers like icon-only buttons or floating action
buttons (FABs).
- Standardizing the relationship between button sizes and layout density.
When NOT to Use
- Global Navigation Links: For moving between major site sections, use
site-navigation-system.
- In-Text Hyperlinks: For links embedded within a paragraph of text that
lead to more information, use standard typography treatments.
- Purely Decorative Elements: Do not use button styles for elements that
cannot be clicked or tapped.
- Complex Form Inputs: For selecting options (Checkboxes, Radios, Selects),
use
form-design-system.
Inputs
- Action Priority: Is the task Primary (Level 1), Secondary (Level 2), or
Tertiary (Level 3)?
- Action Gravity: Is the action "Positive" (Submit), "Neutral" (Cancel), or
"Destructive" (Delete)?
- Contextual Density: Where does the button live? (e.g., a spacious Hero vs.
a compact Data Table row).
- Brand Tokens: Color palette, typography scale, and corner radius
preferences.
Outputs
- Button Variant Matrix: Defined styles for Primary, Secondary, Ghost, and
Danger variants.
- Sizing Scale: A range of heights and paddings (e.g., Small, Medium,
Large).
- Anatomy Spec: Internal spacing rules for text, icons, and containers.
- Action Grouping Rules: Guidelines for alignment, order, and spacing
between multiple buttons.
Workflow
1. Establish the Variant Hierarchy
Assign visual weights to buttons based on their importance to the user goal:
- Primary (Level 1): High-contrast, filled background. Usually the "main"
goal of the page. Only one per view.
- Secondary (Level 2): Outlined or low-contrast background. Used for
alternative or supporting actions.
- Tertiary/Ghost (Level 3): No background or border in its default state.
Used for low-priority tasks or within dense UI (like tables).
- Danger: High-contrast color (usually Red). Used strictly for destructive,
permanent actions.
2. Define the Sizing Scale
Map button dimensions to the layout context using the fluid-spacing-system:
- Large (Hero/Landing): Max prominence. High vertical padding.
- Medium (Default): The standard for forms, modals, and headers.
- Small (Compact): Used in sidebars, cards, and data tables where space is
at a premium.
3. Design the Internal Anatomy
Standardize the structure of the button container:
- Padding: Maintain a consistent horizontal vs. vertical ratio (usually
horizontal = 1.5x to 2x vertical).
- Icon Integration: Define the gap between an icon and text (e.g.,
--space-xs).
- Corner Radius: Determine the "roundness" (Sharp, Rounded, or Pill) to
match the brand's visual tone.
4. Create Button Groups
When placing multiple actions together, follow a logical order:
- Order: Place the Primary action in the "conclusion" position (Right on
desktop, Top in a vertical mobile stack).
- Spacing: Use a consistent gap (e.g.,
--space-s) between buttons in a
group.
- Alignment: Right-align actions in modals/headers; Left-align in forms;
Center-align in Heroes.
5. Define Responsive Behavior
Ensure actions remain usable on all viewports:
- Full-Width (Block) Buttons: On mobile, small buttons often expand to fill
the width of the container for easier thumb reach.
- Icon-Only Fallback: In extremely tight headers, text labels may be hidden
in favor of icons (ensure
aria-label is present).
Decision Rules
- The "One Primary" Rule: There should only be one Primary (Level 1) button
visible in any single viewport/context to avoid "choice paralysis."
- Ghost vs. Link: Use a Ghost button when the action is functional (e.g.,
"Close," "Cancel"); use a text link when the action is navigational (e.g.,
"Learn more about our policy").
- Icon Placement: Use a leading icon (Left) to clarify the action (e.g.,
a Search icon); use a trailing icon (Right) to indicate direction (e.g.,
an Arrow for "Next Step").
- Contrast for Danger: Destructive buttons must look significantly
different from Primary buttons to prevent accidental clicks.
Constraints
- Accessibility: Text must meet WCAG AA contrast (4.5:1). Interactive
elements must have a clear
focus state (see interactive-state-system).
- Touch Targets: All buttons must have a minimum interactive area of
24x24px (WCAG 2.2 SC 2.5.8), even if the visual element is smaller; use
44x44px as the comfortable default for primary actions and mobile layouts.
- Truncation: Button text should never truncate. If the label is too long,
re-evaluate the copy or allow the button to wrap/expand.
Common Failure Patterns
- Button Soup: Using 3-4 Primary buttons on one page, which dilutes the
importance of the main CTA.
- The "Grey Zone": Making buttons look like disabled elements because they
lack enough contrast or color.
- Missing Interaction: Failing to define
hover or active states,
leaving the user unsure if their click was registered.
- Tiny Targets: Designing small, text-only ghost buttons that are nearly
impossible to hit on a mobile screen.
- Confusing Alignment: Mixing different button alignments in the same flow,
forcing the user to "hunt" for the next action.
Validation Criteria
