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 as a component set with variant and size axes plus boolean and swap properties.

Auto layout

Direction: horizontal
Gap: 8px
Padding: 8px 16px to 12px 32px 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.

Resizing

Width: hug
Height: fixed
Minimum width: 36px
Maximum width: Hug content or fill parent when Full width is true
Minimum height: 36px
Maximum height: 44px
Overflow: visible

Text variants hug by default. Icon-only uses a fixed 36px square.

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
Full width	boolean	false	fullWidth	No additional constraint
Disabled	boolean	false	disabled	No additional constraint
LabelRequired	slot	Save changes	children	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 interactive variants may demonstrate hover and press but cannot reproduce native button semantics.
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

8px

Horizontal padding

16 / 20 / 24 / 32px

sm / md / lg / xl.

Vertical padding

8 / 8 / 12 / 12px

sm / md / lg / xl.

Icon-only target

44 × 44px

Rules

Keep labels on one line.
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.

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.

Related specifications

confirm-dialog tooltip toggle