Buttons Skill
How this skill behaves (read first)
This is a generative skill. The default failure modes are opposite: flat sameness (every action gets the same generic button, no hierarchy, vague "Submit/OK" labels, missing states) and decoration overload (every button raised, shadowed, branded, icon-stuffed). A checklist is not a mandate, so this skill gates:
- Establish context — platform, the screen's action hierarchy, brand personality, and whether any action is destructive.
- Apply the always-true core — hierarchy-driven type selection, action-verb labels, full state coverage, accessible sizing and contrast.
- Surface the stylistic levers (shape, elevation, icon-only, FAB, width strategy) as decisions with trade-offs — not defaults.
Then it hands off to ux-heuristics-audit, ux-accessibility-audit, ux-aesthetics-audit, and ux-microcopy-audit for validation.
Step 0 — Establish context before designing
Ask if not known; state the assumption if proceeding without an answer:
- Platform — mobile tightens everything: touch targets (≥48×48px), spacing between adjacent buttons, fixed widths for stacked buttons, tactile feedback. Desktop relies on hover/cursor cues instead.
- Action hierarchy on this screen — what is the one thing the user came to do? That action gets the only primary button; everything else is secondary or tertiary.
- Brand personality — serious/trustworthy vs. friendly/playful decides shape (sharp ↔ rounded ↔ pill) and how expressive styling can get.
- Destructive or irreversible actions? — these flip defaults: explicit verb labels ("Delete project," never "Yes"), semantic color (red family), never a FAB, never the visually dominant button by default.
The always-apply core (correct for almost every case)
Pick the type from the action's importance — not from looks
- Primary — the action the interface wants users to take. One per view, most visually prominent (saturated, contrasting fill). If everything is prominent, nothing is.
- Secondary — the alternative (Cancel next to Submit). Subdued: outlined/ghost works well, but the outline needs enough contrast to stay visible.
- Tertiary — rare or low-priority actions. Text buttons, muted colors, smaller weight; place them away from the primary to prevent accidental taps.
- Grouping types: a menu/dropdown button tucks related actions of equal importance into a list; a split button adds a default one-click action plus a dropdown — keep a visual separator so users don't expect the whole button to open the menu; a toggle group keeps 2–3 mutually exclusive options visible with one selected.
- ❌ A dropdown as a catch-all bucket of unrelated actions ✅ Only related actions, grouped to simplify the decision
Labels are commands
- Specific action verbs that state the result: ❌ "Yes" / "No" / "OK" / "Go" ✅ "Delete project" / "Save changes" / "Subscribe"
- 2–3 words, one line. Two-line labels cause wrong choices. No italics, underline, or end punctuation; a heavier weight than body copy is enough.
- Minimum 16px label size, centered horizontally and vertically.
- Icons go on the left (in LTR languages) where they aid recognition — trailing icons are decoration, except the dropdown arrow, which the leading icon leaves room for.
- Icon + label beats either alone. A floppy disk means nothing to part of your audience; a label makes it explicit and gives screen readers something to announce.
Design every state, not just the resting one
Enabled, hover, pressed (brief but crucial feedback that the tap registered), focused (a visible ring/border — vital for keyboard and assistive-tech users; don't style it so close to other states that it's ambiguous), and disabled (grayed out, clearly inert). Buttons that toggle something on/off must make the current direction explicit.
Size, space, and contrast are not negotiable
- Touch target ≥ 48×48px on mobile (~9mm finger pad, per WCAG/Material guidance); on desktop, generous padding keeps click areas honest.
- Padding rule of thumb: horizontal padding ≈ 2× vertical; at minimum an uppercase "W" fits between label and edge.
- Set a minimum width for hug-content buttons — overly narrow buttons miss the target size and stop looking like buttons.
- Adequate spacing between adjacent buttons so fingers don't slide onto the wrong action.
- Contrast: button-vs-background and label-vs-button both meet WCAG (4.5:1 normal text, 3:1 large). On image backgrounds, add a semi-opaque layer. Exact ratios → defer to the
accessibilityaudit.
Be consistent and predictable
- One button style system product-wide — same colors, shapes, typography, and placement for the same actions everywhere (Principle of Least Astonishment).
- It must look like a button. Affordance beats creativity: users should never have to guess what's clickable.
- Place buttons where users expect them — at the natural end of the reading flow (Gutenberg/Z-pattern: primary action bottom-right of the content it concludes), never hidden.
- Color carries meaning: red for destructive, your accent for primary. Align with conventions; don't make users learn a private color language.
The context-dependent decisions (surface, don't auto-apply)
Present each with its trade-off and a recommendation tied to Step 0. Applying all of these by default is the decoration-overload failure mode.
| Decision | Apply when | Avoid / adapt when | Default recommendation |
|---|---|---|---|
| Shape: sharp ↔ rounded ↔ pill | Sharp = serious, solid (finance, insurance); rounded = friendly, safe; pill = playful, informal | Sharp corners on a warm consumer brand; pills in formal/enterprise UI | Slightly rounded rectangle — the familiar, trusted middle; pill radius = ½ height + extra horizontal padding |
| Elevation / shadows | Raised buttons to lift the primary action; flat for everything else | Shadows on transparent buttons or near labels (kills legibility); big dark default-black shadows | Shadow tinted near the button's color, <40% opacity, smaller than the button — depth cue, not decoration |
| Icon-only buttons | Routine actions with universal icons (edit, delete, search, home) in tight space | Any icon users must decode; anywhere without an accessible name | Icon + label; if icon-only, universal symbol + accessible name |
| FAB | One fixed, constructive, most-used action in an app (compose, add) | Destructive actions; more than one per page; content it would cover | At most one, only if the app has a single dominant create-action |
| Branded buttons ("Sign in with Google") | Third-party auth/integration points | Restyling them to match your UI — breaks trust and brand guidelines | Use the brand's official assets verbatim, placed where the action occurs |
| Custom shapes | The shape amplifies the function (arrow-shaped "Next") | Novelty that obscures clickability | Stick to conventions; if custom, reinforce affordance with contrast/size/shadow |
| Width: hug vs. fixed | Fixed width for stacked primary/secondary on mobile — balanced, scannable | Fixed width truncating long labels (i18n) | Hug with a minimum width on web; fixed for stacked mobile pairs |
| Tactile feedback | Mobile: subtle vibration on tap confirms registration | Stacking every visual + tactile effect at once (overwhelming) | Visual state change always; haptics as a light mobile enhancement |
Validate the result (orchestration)
Hand-offs name each lens by its installable skill
name. Invoke one only if that skill is installed; if it isn't, this skill's own core already carries these rules — proceed without it rather than blocking.
After generating or revising, hand the result to the audit lenses rather than declaring it done. These are candidate lenses — posture is set by docs/orchestration-policy.md, or route the whole thing through ux-design-review. Here, heuristics and microcopy are Tier A (auto-run); accessibility, aesthetics, and mobile-responsiveness are Tier B (offered) — under an existing design system aesthetics is suppressed and accessibility narrows to usage; mobile-responsiveness applies only on mobile. If the user invoked this skill for one specific thing, respect that scope.
ux-heuristics-audit(Tier A) — visibility of system status (states/feedback), consistency, error prevention around destructive buttons.ux-accessibility-audit(Tier B — offer; narrow under a design system) — contrast ratios, touch-target sizes, focus visibility, accessible names for icon-only buttons.ux-aesthetics-audit(Tier B — offer; suppress under a design system) — hierarchy clarity and whether styling tipped into decoration overload (competing primaries, shadow soup).ux-microcopy-audit(Tier A) — label clarity, action-verb phrasing, consistency of command language across the product.ux-mobile-responsiveness-audit(Tier B — offer; applies only on mobile) — when the context is mobile: target sizes, spacing, and stacked-button layout.
If the audits surface a conflict (e.g., brand expressiveness vs. affordance), resolve back toward the primary task: the user must instantly recognize and successfully hit the right action.
Common do/don't patterns
| ❌ Don't | ✅ Do |
|---|---|
| Three equally prominent buttons on one screen | One primary; secondary/tertiary visibly subordinate |
| "Yes" / "No" / "OK" labels | Action verbs stating the result: "Delete project," "Save changes" |
| Icon-only button with a clever-but-obscure symbol | Universal icon + label (or accessible name at minimum) |
| Design only the resting state | Enabled, hover, pressed, focused, disabled — all distinct |
| 32px-tall tappable area on mobile | ≥48×48px touch target with breathing room between buttons |
| FAB for "Delete account" | FAB only for the app's main constructive action — or no FAB |
| Restyle "Sign in with Google" to match your palette | Official brand assets, untouched |
| Shadow every button for "depth" | Elevation only where it signals priority; tinted, subtle, smaller than the button |
| Different styles for the same action across screens | One consistent button system product-wide |
| Ship without checking | Hand off to heuristics + accessibility + aesthetics + microcopy |
