Solid Buttons: High-emphasis buttons with colored backgrounds. Use for primary actions and important calls-to-action.

Outline Buttons — RETIRED 2026-08-11. Do not use in new work. Kept here, and in the CSS, only so CDN consumers can identify what they already have. Use the .tw-btn-soft-* tier instead — it is the same medium-emphasis step and every mapping is contrast-checked: outline-primary → soft-primary, and the same for secondary, success, danger, warning and info. bin/ds validate fails on any new outline usage.

Tertiary Buttons: Low-emphasis buttons with transparent background. Use for tertiary actions, supplementary options, or when you need minimal visual weight.

Sizes: Three size options to match your UI density needs. Default size works for most cases.

Icon Buttons: Buttons with Font Awesome Pro v6 icons. Use icons to reinforce meaning and improve scannability. Icons inherit the button's text size and color automatically.

Disabled Buttons: Use the disabled attribute to indicate buttons that cannot be interacted with. Disabled buttons have reduced opacity and no hover effects.

Action in flight: add .tw-btn-loading, swap the label ("Save" → "Saving…"), and set disabled + aria-busy="true". The spinner draws from the button's own text colour, so it works on every variant; the class overrides the disabled dim — a busy button reads active, not unavailable.

Block Buttons: Full-width buttons that span their container. Use for mobile interfaces, forms, or when you need a button to take up the entire available width.

Heavy Buttons: Buttons with bold text for extra emphasis. Add .tw-btn-heavy to any button variant when you need the text to stand out more.

Multiline Buttons: Buttons with multiple text lines (2 lines optimal) to support extra context in constrained space. Add .tw-btn-multiline to any button variant when you need to display in 2 lines.

Real-world examples: Typical button combinations you'll use in forms, dialogs, and interfaces.

Button Groups: Group multiple buttons together with shared borders. Use for related actions or toggles like toolbar buttons or view switchers.

Dropdown Toggle: Buttons with dropdown arrows to indicate a menu or additional options. Add the .tw-dropdown-toggle class to automatically display a dropdown arrow.

One main action + attached alternatives: the label button performs the default action; the caret opens a menu of variants ("Save" | ▾ → Save & add another, Save as draft). A .tw-btn-group whose second slot is a full .tw-dropdown wrapper — the caret carries .tw-dropdown-toggle .tw-dropdown-toggle-split and must have an aria-label. Use a split only when one action clearly dominates; equals get a plain dropdown.

Never leave a user guessing: a disabled button can't explain itself — it takes no hover and no focus. Wrap it in .tw-btn-disabled-wrap with tabindex="0" and put the tooltip (the reason) on the wrapper: pointer events fall through the disabled child, and keyboard users can Tab to the wrapper to hear the reason. The cursor reads not-allowed over the whole button.

Button-style Checkboxes/Radios: Form controls styled as buttons. Use hidden .tw-btn-check inputs with <label> elements styled as buttons for accessible toggle controls.

Pagination: Navigation component for paging through content. Use .tw-pagination container with .tw-page-item and .tw-page-link classes.

Soft: tinted fill, no border weight — quieter than solid, more present than tertiary. Reuses the badge/tag soft tokens, so a soft button and a soft badge of the same variant read as one family. Use for secondary actions in dense surfaces (DR-2026-13).

Link: an action that lives inside a sentence. Resets the button box entirely — no padding, border or radius, baseline-aligned, inherits the surrounding text size. Not for control rows: beside a primary button use .tw-btn-tertiary, whose matching height and hit area is the point. And if it navigates, it's a real <a href>, not a button.

DASHED: .tw-btn-dashed — transparent ground, dashed neutral border, normal weight

The add-another row at the end of a repeating list — reminders, contacts, custom fields, criteria. The dashed edge says "this is a slot you can fill", which a solid button does not; it is the quietest button in the system on purpose, because it must not out-rank the form's real submit. Pair it with .tw-btn-block so it spans the list it belongs to, and always label it with a leading + or plus icon plus the noun it adds. Do not use it for anything destructive, and do not use it as a general secondary button — that is .tw-btn-secondary.