Actions & feedback

Button / buttonStyles

The primary action primitive, with explicit hierarchy, size, and semantic-button behavior.

ButtonbuttonStylesButtonPropsButtonSizeButtonVariant

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

import { Save } from 'lucide-react';
import { Button } from '@ai-created/ui';

export function Example() {
  return (
    <Button>
      <Save className="h-4 w-4" aria-hidden="true" />
      {"Save changes"}
    </Button>
  );
}

Import

tsx

import { Button, buttonStyles } from '@ai-created/ui';

Client boundary

Add 'use client' to the file that owns this interactive state.

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Container

Required

Native action target carrying variant, size, and interaction styles.

button

Leading content

Optional

Optional decorative icon placed before the label.

Label

Required

Short verb phrase describing the result of activation.

Trailing content

Optional

Optional icon communicating direction or external behavior.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Actions/Button

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish one public component set with Variant, Size, and State controls and editable label/icon properties. Preserve all 168 supported combinations so designers can change visual treatment without replacing an instance. Theme, accent, and icon rendering use shared variable modes.

Auto layout

Direction: horizontal
Gap: 10px
Padding: 10px 20px to 15px 40px by size
Alignment: Center in both axes
Wrap: No wrap

Use logical leading and trailing slots. The icon size is a square frame with centered content.
Measurements use the 20px playground and Figma reference root. The package does not set html font-size. Rem-based dimensions scale with the consumer root; literal px dimensions remain fixed.

Resizing

Width: hug
Height: hug
Minimum width: Content width
Maximum width: Hug content or fill parent when Full width is true
Minimum height: Content-derived
Maximum height: Content-derived
Overflow: visible

Every variant includes a 1px border in layout, transparent where no visible boundary is needed. At the 20px root, text variants use hug height: inline 27px, sm/md 47px, and lg/xl 57px including that border; identical content and size have identical outer dimensions. Icon-only uses a fixed 55px square that is both the visual size and the interaction target. Full width is represented by native Fill container sizing in Figma, not an inert component Boolean.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Variant	variant	primary	variant	primary, secondary, destructive, ghost, filter, filter-active, icon
Size	variant	md	size	inline, sm, md, lg, xl, icon
State	variant	default	Interaction preview; disabled maps to the native disabled prop	default, hover, focus-visible, disabled
LabelRequired	text	Save changes	children	No additional constraint
Show leading icon	boolean	false	Presence of an optional leading icon child	No additional constraint
Show trailing icon	boolean	false	Presence of an optional trailing icon child	No additional constraint
Leading icon	instance-swap	None	First child, decorative unless it supplies the icon-only accessible name	No additional constraint
Trailing icon	instance-swap	None	Last child, mark decorative	No additional constraint

Nested assets and slots

Label

slot / required

Single-line action label.

children

Leading icon

slot

Optional 16px icon before the label.

children

Trailing icon

slot

Optional 16px icon after the label.

children

Content limits

Label

One line, recommended 2 to 24 characters, maximum 32

Overflow: Never truncate; revise the label or allow the parent to allocate more width.

Action labels must remain immediately scannable.

Icons

At most one icon on either side

Overflow: Remove redundant icons.

Multiple symbols compete with the action label.

Localization and RTL

Translatable: Label, Accessible name

Leading and trailing slots follow logical reading order.
Mirror directional icons; do not mirror universal symbols.
Test at 200% text size.
Test a label at twice the English length.
Test an icon-only accessible name in every locale.

Responsive behavior

Intrinsic sizing with a parent-controlled full-width option.

No internal breakpoint

Keep hug width in toolbars.
Use Full width inside narrow stacked action areas.
The consuming layout decides when actions stack.

Authoring limits

Figma states demonstrate default, hover, focus-visible, and disabled appearances; the runtime defines no separate pressed appearance. Native button semantics remain in code.
Do not detach instances to make one-off sizes.
Icon-only use requires an accessible name that is not represented by visual geometry.
buttonStyles can style another element but does not supply button behavior.

Accountable owner

Design systems action primitive owner

Canonical source: src/components/Button.tsx

A new variant or size must represent a reusable hierarchy need and include every interaction state.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Corner radius

6px

Uses radius-md.

Content gap

10px

Horizontal padding

20 / 25 / 30 / 40px

sm / md / lg / xl.

Vertical padding

10 / 10 / 15 / 15px

sm / md / lg / xl.

Text button height

Content-derived: inline 27px, sm/md 47px, lg/xl 57px including the shared 1px border

Measurements use the 20px root; identical content and size have identical outer dimensions across every variant.

Icon-only target

55 × 55px

Rules

Keep labels on one line.
Reserve a 1px border in every variant, transparent where no visible boundary is needed; changing variant or interaction state must not change the outer dimensions for identical content and size.
Use the icon size for square icon-only controls; do not force an icon into text-button spacing.
Primary and destructive use distinct semantic action tokens; specific copy still communicates the consequence.
Measurements use the 20px playground and Figma reference root. The package does not set html font-size. Rem-based dimensions scale with the consumer root; literal px dimensions remain fixed.

Responsive behavior

Use fullWidth only when the surrounding layout calls for a full-row action.
Stack competing actions at narrow widths in the consuming layout.

Token dependencies

--color-action-primary / --color-action-primary-hover

Primary action background and hover.

--color-action-destructive / --color-action-destructive-hover

Destructive action background and hover.

--color-on-action

Foreground on filled actions.

--color-control-border / --color-control-border-strong

Secondary, filter, and icon control boundaries.

--color-focus

Global focus-visible outline.

--motion-fast

Color transition duration.

--radius-md

Container radius.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

default

Trigger: Idle and enabled.
Visual response: Variant-specific fill, border, and text establish action hierarchy.
Behavior: Activates on click, Enter, or Space.
Accessibility: Native button semantics expose name and state.

hover

Trigger: Pointer rests over an enabled button.
Visual response: Background, text, or border gains emphasis over 200ms.
Behavior: No action until activation.

focus-visible

Trigger: Keyboard focus enters the button.
Visual response: 2px focus-color outline with a 3px offset.
Behavior: Remains the current tab stop.

disabled

Trigger: disabled is true.
Visual response: 50% opacity and not-allowed cursor.
Behavior: Native activation and focus are suppressed.
Accessibility: Disabled state is exposed by the native element.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Native <button>; buttonStyles is presentation-only when used on another element.
Accessible name: Visible text supplies the name. Icon-only buttons require aria-label.

Keep type="button" unless the control intentionally submits or resets a form.
Do not remove the focus-visible outline.
Mark decorative icons aria-hidden.
A disabled action must use the disabled attribute, not only visual opacity.

Keyboard behavior

Enter: Activates the button.
Space: Activates the button.
Tab / Shift+Tab: Moves focus to or from an enabled button.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Button, buttonStyles } from '@ai-created/ui';

Client Component required

Button forwards its HTMLButtonElement ref and all native button attributes.
Consumer className is merged last and can override default Tailwind utilities.
Use buttonStyles only when another semantic element genuinely needs the same appearance.

tsx

<Button variant="primary">Save changes</Button>

Submit action

Use a native submit type inside a form.

tsx

<Button type="submit">Save changes</Button>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
variant	ButtonVariant	primary	primary, secondary, destructive, ghost, filter, filter-active, or icon.
size	ButtonSize	md	inline, sm, md, lg, xl, or icon.
fullWidth	boolean	false	Expands the button to the available width.
type	button \| submit \| reset	button	Native button type.
className	string	undefined	Additional classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Lead labels with a specific verb such as Save, Create, or Delete.
Use one clear primary action per decision area.

Do not

Do not use a button for navigation; use a link.
Do not rely on color alone to distinguish destructive meaning.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Defaults to primary, md, and type button.
Forwards ref, className, disabled, and native attributes.

Interaction

Activates by pointer, Enter, and Space; disabled buttons do not activate.

Accessibility

Has an accessible name and no axe violations in every variant.

Visual

Snapshot every variant, size, disabled state, focus-visible state, and both themes.
Compare rendered outer dimensions across every variant and size with identical content at 16px and 20px roots; hover, focus-visible, and disabled states preserve geometry.

Related specifications

confirm-dialog tooltip toggle