Button Hierarchy
The hierarchical grouping of button styles within a UI surface. Hierarchy clarity — which action is the primary, which is alternative, which is optional — is the single most important driver of action discoverability.…
$ aoe install @community/category-button-hierarchyProjection
Always in _index.xml · the agent never has to ask for this.
ButtonHierarchy [category] v1.0.0
The hierarchical grouping of button styles within a UI surface. Hierarchy clarity — which action is the primary, which is alternative, which is optional — is the single most important driver of action discoverability. This category covers the structural rules for composing buttons; @community/taxonomy-cta-styles enumerates the individual styles.
Loaded when retrieval picks the atom as adjacent / supporting.
ButtonHierarchy [category] v1.0.0
The hierarchical grouping of button styles within a UI surface. Hierarchy clarity — which action is the primary, which is alternative, which is optional — is the single most important driver of action discoverability. This category covers the structural rules for composing buttons; @community/taxonomy-cta-styles enumerates the individual styles.
Label
Button / Action Hierarchy
Parent
@community/category-actions
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Members
- primary
- secondary
- tertiary
- destructive
- ghost
Composition Rules
- Rule: single-primary-per-region
- Detail: At most one primary button visible per logical decision region (modal footer, form actions, page hero CTA). Two primaries split user attention and dilute the call-to-action.
- Rule: primary-rightmost-on-desktop
- Detail: On desktop, place primary action to the right of secondary in horizontal action rows (Material, Chrome, macOS conventions). On iOS modals, primary is left and bold (Apple HIG).
- Rule: destructive-not-primary
- Detail: Destructive should never visually compete with primary on default view. Reveal destructive only after user-initiated intent (e.g. 'Delete' on a confirmation modal that the user opened).
- Rule: tertiary-for-optional
- Detail: Optional/dismissive actions (Cancel, Skip, Maybe later) are tertiary or ghost — never secondary if a primary exists.
- Rule: icon-only-needs-label
- Detail: Icon-only buttons require aria-label (see @community/check-aria-label-required) and ideally a tooltip for sighted users.
Hierarchy Tiers
- Primary:
- Tier: 1
- Visual Weight: highest — solid fill, brand color, bold weight
- Max Per Region: 1
- Role: the main action the user came to take
- Secondary:
- Tier: 2
- Visual Weight: medium — outlined or low-fill
- Max Per Region: multiple acceptable for equal-weight choices
- Role: alternative or paired action (e.g. Cancel next to Submit)
- Tertiary:
- Tier: 3
- Visual Weight: low — text-only or minimal styling
- Max Per Region: many acceptable
- Role: optional, supplementary, or dismissive
- Destructive:
- Tier: special
- Visual Weight: high but RED-coded
- Max Per Region: 1
- Role: irreversible negative action; always paired with confirmation
- Ghost:
- Tier: special
- Visual Weight: minimal at rest, visible on hover/focus
- Max Per Region: many
- Role: compact toolbar/inline action where space is scarce
Example Compositions
- Surface: Modal footer (form submit)
- Buttons:
- Cancel (tertiary, left)
- Submit (primary, right)
- Surface: Settings page section
- Buttons:
- Save changes (primary)
- Cancel (tertiary)
- Delete account (destructive, separated visually)
- Surface: Marketing hero
- Buttons:
- Get started free (primary)
- View demo (secondary)
- Surface: Empty state
- Buttons:
- Add your first item (primary, centered, prominent)
Loaded when retrieval picks the atom as a focal / direct hit.
ButtonHierarchy [category] v1.0.0
The hierarchical grouping of button styles within a UI surface. Hierarchy clarity — which action is the primary, which is alternative, which is optional — is the single most important driver of action discoverability. This category covers the structural rules for composing buttons; @community/taxonomy-cta-styles enumerates the individual styles.
Label
Button / Action Hierarchy
Parent
@community/category-actions
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Members
- primary
- secondary
- tertiary
- destructive
- ghost
Composition Rules
- Rule: single-primary-per-region
- Detail: At most one primary button visible per logical decision region (modal footer, form actions, page hero CTA). Two primaries split user attention and dilute the call-to-action.
- Rule: primary-rightmost-on-desktop
- Detail: On desktop, place primary action to the right of secondary in horizontal action rows (Material, Chrome, macOS conventions). On iOS modals, primary is left and bold (Apple HIG).
- Rule: destructive-not-primary
- Detail: Destructive should never visually compete with primary on default view. Reveal destructive only after user-initiated intent (e.g. 'Delete' on a confirmation modal that the user opened).
- Rule: tertiary-for-optional
- Detail: Optional/dismissive actions (Cancel, Skip, Maybe later) are tertiary or ghost — never secondary if a primary exists.
- Rule: icon-only-needs-label
- Detail: Icon-only buttons require aria-label (see @community/check-aria-label-required) and ideally a tooltip for sighted users.
Hierarchy Tiers
- Primary:
- Tier: 1
- Visual Weight: highest — solid fill, brand color, bold weight
- Max Per Region: 1
- Role: the main action the user came to take
- Secondary:
- Tier: 2
- Visual Weight: medium — outlined or low-fill
- Max Per Region: multiple acceptable for equal-weight choices
- Role: alternative or paired action (e.g. Cancel next to Submit)
- Tertiary:
- Tier: 3
- Visual Weight: low — text-only or minimal styling
- Max Per Region: many acceptable
- Role: optional, supplementary, or dismissive
- Destructive:
- Tier: special
- Visual Weight: high but RED-coded
- Max Per Region: 1
- Role: irreversible negative action; always paired with confirmation
- Ghost:
- Tier: special
- Visual Weight: minimal at rest, visible on hover/focus
- Max Per Region: many
- Role: compact toolbar/inline action where space is scarce
Example Compositions
- Surface: Modal footer (form submit)
- Buttons:
- Cancel (tertiary, left)
- Submit (primary, right)
- Surface: Settings page section
- Buttons:
- Save changes (primary)
- Cancel (tertiary)
- Delete account (destructive, separated visually)
- Surface: Marketing hero
- Buttons:
- Get started free (primary)
- View demo (secondary)
- Surface: Empty state
- Buttons:
- Add your first item (primary, centered, prominent)
Relations
related: [@community/taxonomy-cta-styles, @community/category-form-input-states, @community/value-touch-target-min, @community/fact-ios-button-style-hierarchy]
Label
Button / Action Hierarchy
Parent
@community/category-actions
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Members
- primary
- secondary
- tertiary
- destructive
- ghost
Composition Rules
- Rule: single-primary-per-region
- Detail: At most one primary button visible per logical decision region (modal footer, form actions, page hero CTA). Two primaries split user attention and dilute the call-to-action.
- Rule: primary-rightmost-on-desktop
- Detail: On desktop, place primary action to the right of secondary in horizontal action rows (Material, Chrome, macOS conventions). On iOS modals, primary is left and bold (Apple HIG).
- Rule: destructive-not-primary
- Detail: Destructive should never visually compete with primary on default view. Reveal destructive only after user-initiated intent (e.g. 'Delete' on a confirmation modal that the user opened).
- Rule: tertiary-for-optional
- Detail: Optional/dismissive actions (Cancel, Skip, Maybe later) are tertiary or ghost — never secondary if a primary exists.
- Rule: icon-only-needs-label
- Detail: Icon-only buttons require aria-label (see @community/check-aria-label-required) and ideally a tooltip for sighted users.
Hierarchy Tiers
- Primary:
- Tier: 1
- Visual Weight: highest — solid fill, brand color, bold weight
- Max Per Region: 1
- Role: the main action the user came to take
- Secondary:
- Tier: 2
- Visual Weight: medium — outlined or low-fill
- Max Per Region: multiple acceptable for equal-weight choices
- Role: alternative or paired action (e.g. Cancel next to Submit)
- Tertiary:
- Tier: 3
- Visual Weight: low — text-only or minimal styling
- Max Per Region: many acceptable
- Role: optional, supplementary, or dismissive
- Destructive:
- Tier: special
- Visual Weight: high but RED-coded
- Max Per Region: 1
- Role: irreversible negative action; always paired with confirmation
- Ghost:
- Tier: special
- Visual Weight: minimal at rest, visible on hover/focus
- Max Per Region: many
- Role: compact toolbar/inline action where space is scarce
Example Compositions
- Surface: Modal footer (form submit)
- Buttons:
- Cancel (tertiary, left)
- Submit (primary, right)
- Surface: Settings page section
- Buttons:
- Save changes (primary)
- Cancel (tertiary)
- Delete account (destructive, separated visually)
- Surface: Marketing hero
- Buttons:
- Get started free (primary)
- View demo (secondary)
- Surface: Empty state
- Buttons:
- Add your first item (primary, centered, prominent)
Source
aoe-engine/examples/frontend-design/primes/compiled/@community/category-button-hierarchy/atom.yaml