Button

OverviewCopy Anchor Link

A button invokes an action. Every button should communicate three things at a glance: that it is clickable, what it will do, and how important the action is relative to its neighbors. Use intent to set the action's weight, size to match its container, and style (solid vs. ghost) to control how loudly it sits on the page.

When to useCopy Anchor Link

• To commit a change or submit a form (Save, Create, Sign document)
• To advance a user through a flow (Continue, Next step)
• To trigger an immediate, self-contained action (Send, Download, Copy link)

When not to useCopy Anchor Link

• For navigation between pages — use a link instead. Buttons do things; links go places.
• To toggle a setting on or off — use a switch or checkbox.
• For a choice between a small set of options — use a segmented control.

AnatomyCopy Anchor Link

A button is a single focusable element: a label framed by geometry, with optional icons flanking the label. Color properties (fill, border, label) are driven by --nm-button-* custom properties. Geometry (height, padding, gap, radius) is baked directly into the size modifier classes (nm-button--xs through nm-button--xl).

Tokens and values that drive each partCopy Anchor Link

IntentsCopy Anchor Link

Intent communicates what an action means. Pick the one that matches the semantic weight, not the color you want. Each intent owns a full triple of default / hover / active tokens in both solid and ghost style — nothing else needs customizing.

Solid & ghostCopy Anchor Link

Every intent is available as solid (filled container with border) or ghost (transparent until hovered). Choose by hierarchy, not by taste.

SolidCopy Anchor Link

Filled buttons command attention. Use them for the action a user is expected to take — one primary on any given view, with secondaries alongside.

GhostCopy Anchor Link

Ghost buttons sit lighter on the canvas. Use them for tertiary actions, table-row actions, toolbar commands, and anywhere the filled chip would be visual noise.

SizesCopy Anchor Link

Five sizes, each defined by the nm-button--{size} modifier class. Match the size to the density of the surrounding UI, not to the importance of the action — importance is communicated by intent.

Choosing a sizeCopy Anchor Link

• xs — inline chips, table-cell actions, filter bars
• sm — dense toolbars, compact dialogs
• md — default for forms, cards, panel footers
• lg — marketing hero, onboarding CTAs, empty states
• xl — signing surfaces, fullscreen confirmations, touch-first kiosks

Icon variantsCopy Anchor Link

A button can appear as label-only, label + leading icon, label + trailing icon, or icon-only. Icons clarify intent — they never replace clear language.

Solid primary · md · four configurations

Leading iconCopy Anchor Link

Use when the icon adds concrete meaning to the label (↓ Download, + Add user, ↻ Refresh). The icon sits to the left of the label.

Trailing iconCopy Anchor Link

Use when the icon indicates direction or state — Continue →, Open menu ▾, External ↗. Don't use trailing icons to decorate an already-clear verb.

Icon-onlyCopy Anchor Link

Reserve for actions that are universally recognized (✕ close, ⋯ more, ◀ back) or that sit inside a dense bar where a label would break the layout. Icon-only buttons must have an aria-label.

StatesCopy Anchor Link

Every button responds to four interaction states. Hover and active colors come pre-baked from the tokens — you never hand-pick them.

Primary · md · four states

FocusCopy Anchor Link

Focus is rendered by a 2px --theme-focus outline, 2px offset from the button, that respects :focus-visible. Never suppress the focus ring. In dark theme the focus color shifts to a lighter blue for contrast — handled automatically by the theme layer.

No disabled stateCopy Anchor Link

Namirial buttons never ship a disabled appearance. A button that can be clicked but can't act is a dead end — users don't know what's wrong or how to fix it. Instead, keep the button enabled and let it trigger an inline error, field-level validation, or a toast that explains what needs to change.

Light & dark themeCopy Anchor Link

All button tokens are remapped under data-theme="light" and data-theme="dark". Contrast, hover directionality, and focus color are all handled for you — author buttons once, they adapt.

Both previews are locked — they don't follow the page theme switcher. Toggle the page theme to see the rest of the documentation cascade.

Buttons in contextCopy Anchor Link

How buttons compose with the rest of the system. These are layout recommendations, not rigid rules — adjust to your surface.

Dialog footerCopy Anchor Link

Primary action right-aligned, ghost secondary to its left. In destructive dialogs swap the primary for negative intent.

Form page footerCopy Anchor Link

Empty stateCopy Anchor Link

ToolbarCopy Anchor Link

Do & don'tCopy Anchor Link

The subtle rules that keep button hierarchy legible at a glance.

AccessibilityCopy Anchor Link

Namirial buttons inherit from the native <button> element. The tokens handle contrast; you handle semantics and labeling.

SemanticsCopy Anchor Link

• Use <button type="button"> by default. Use type="submit" only inside a <form> that should submit on Enter.
• Never style an <a> as a button (or vice versa). A button does; a link navigates.

KeyboardCopy Anchor Link

• Tab moves focus; Shift + Tab moves backwards.
• Space and Enter both trigger the button.
• Focus ring uses :focus-visible, so it appears on keyboard focus but not on mouse click — no override needed.

ContrastCopy Anchor Link

• All seven intents, in both themes, meet WCAG 2.2 AA contrast for label-over-container at every state.
• Focus ring contrast is ≥ 3:1 against both the button and the surrounding background.

LabelingCopy Anchor Link

• Icon-only buttons require aria-label. Make the label describe the action, not the icon ("Close dialog", not "X icon").
• Toggle buttons (e.g. Bold in a toolbar) require aria-pressed.
• Buttons that open a menu require aria-haspopup and aria-expanded.

PlaygroundCopy Anchor Link

Configure every axis at once. The code snippet updates as you go — copy it straight into your product.

Token referenceCopy Anchor Link

Every button variant resolves to a handful of custom properties. When you need a one-off tweak, override these on a wrapper — never on the .nm-button rule itself.

Per-intent color tokensCopy Anchor Link

{intent} = primary · secondary · accent · positive · negative · warning · info

Per-size geometry valuesCopy Anchor Link

Values are baked into .nm-button--{size} modifier classes. No custom properties to override — use a different size class instead.

ImplementationCopy Anchor Link

The component uses BEM modifier classes. Import namirial-theme.css and compose classes — no data attributes, no build step.

<link rel="stylesheet" href="namirial-theme.css">

<button class="nm-button nm-button--accent nm-button--md">
  Continue
  <i class="icon-arrow-right"></i>
</button>

CSS classesCopy Anchor Link