Getting Started

Design tokens

Learn about AirUI’s design tokens and how to customize them to fit your project’s needs.

AirUI design tokens

Air UI uses design tokens to define colors, spacing, radius, and other visual decisions in a consistent and scalable way. The semantic tokens documented here are exposed through Tailwind utilities and sourced from packages/air-ui-ds/assets/css/main.css and packages/air-ui-ds/assets/css/theme/ui-theme.css.

Design tokens act as the foundation of the design system, ensuring visual consistency across components, layouts, and themes.

How tokens are used:

Tokens are defined as CSS variables inside the @theme block
Tailwind utilities consume those variables automatically
design-token-table expects the raw token name only, without the Tailwind utility prefix. For example, use background-neutral-bold in the table item, not bg-background-neutral-bold

Available design tokens

Below is the list of the semantic tokens exposed by air-ui-ds and intended to be used with design-token-table.

Background colors

Token	Description
`background-container-surface`	Main surface for contained layouts and cards.
`background-overlay`	Overlay backgrounds (modals, dialogs).
`background-surface`	Default application background.
`background-danger-bold`	Strong danger background for critical actions.
`background-danger-subtler`	Subtle danger background.
`background-danger-subtlest`	Very light danger background.
`background-delete-default`	Default delete action background.
`background-delete-hover`	Delete action on hover.
`background-delete-on-neutral-hover`	Delete background over neutral hover.
`background-delete-soft`	Soft delete background.
`background-delete-soft-hover`	Soft delete hover state.
`background-info-bold`	Strong informational background.
`background-info-subtler`	Subtle informational background.
`background-info-subtlest`	Very light informational background.
`background-neutral-active`	Active neutral surface.
`background-neutral-bold`	Emphasized neutral background.
`background-neutral-default`	Default neutral background.
`background-neutral-disabled`	Disabled background state.
`background-neutral-filled-transparent`	Transparent filled neutral background.
`background-neutral-hover`	Hover state for neutral surfaces.
`background-neutral-hover-subtle`	Subtle hover state.
`background-neutral-subtler`	Exposed subtler neutral background token.
`background-neutral-subtle`	Low-contrast neutral background.
`background-neutral-subtlest`	Minimal neutral background.
`background-neutral-subtlest-on-container-surface`	Subtlest neutral background on container surfaces.
`background-neutral-filled-default`	Filled neutral element.
`background-neutral-filled-hover`	Hover state for filled neutral elements.
`background-primary-brand-default`	Primary brand background.
`background-primary-brand-hover`	Primary brand hover state.
`background-primary-brand-active`	Primary brand active state.
`background-primary-brand-checked`	Primary brand checked state.
`background-primary-brand-checked-subtlest`	Subtlest primary brand checked background.
`background-primary-brand-soft`	Soft primary brand background.
`background-primary-brand-soft-hover`	Soft primary brand hover.
`background-primary-brand-on-checked-subtle-bg`	Primary brand background used on checked subtle surfaces.
`background-primary-brand-subtle-active`	Active primary brand background for subtle variants.
`background-secondary-brand-default`	Secondary brand background.
`background-secondary-brand-hover`	Secondary brand hover.
`background-secondary-brand-checked`	Secondary brand checked state.
`background-secondary-brand-checked-subtlest`	Subtlest secondary brand checked background.
`background-secondary-brand-on-checked-subtle-bg`	Secondary brand background used on checked subtle surfaces.
`background-secondary-brand-soft`	Soft secondary brand background.
`background-success-bold`	Strong success background.
`background-success-subtler`	Subtle success background.
`background-success-subtlest`	Very light success background.
`background-warning-bold`	Strong warning background.
`background-warning-subtler`	Subtle warning background.
`background-warning-subtlest`	Very light warning background.

Chart colors

Token	Description
`chart-variant-one`	Chart color variant one.
`chart-variant-two`	Chart color variant two.
`chart-variant-three`	Chart color variant three.
`chart-variant-four`	Chart color variant four.
`chart-variant-five`	Chart color variant five.
`chart-variant-six`	Chart color variant six.

Text colors

Token	Description
Text `text-default`	Default text color.
Text `text-danger`	Text for danger states.
Text `text-delete`	Text related to delete actions.
Text `text-error`	Text for error states.
Text `text-info`	Text for informational messages.
Text `text-success`	Text for success states.
Text `text-warning`	Text for warning states.
Text `text-warning-on-bg`	Warning text on colored backgrounds.
Text `text-neutral-disabled`	Text for disabled elements.
Text `text-neutral-inactive`	Text for inactive or muted elements.
Text `text-neutral-on-filled`	Text color for filled neutral backgrounds.
Text `text-neutral-on-monochrome-active-bg`	Neutral text on active monochrome backgrounds.
Text `text-neutral-on-monochrome-hover-bg`	Neutral text on hover monochrome backgrounds.
Text `text-neutral-on-neutral-bg`	Neutral text on neutral backgrounds.
Text `text-neutral-on-neutral-filled-bg`	Neutral text on filled neutral backgrounds.
Text `text-neutral-on-primary-brand-soft-bg`	Neutral text on soft primary brand backgrounds.
Text `text-neutral-subtle`	Subtle secondary text color.
Text `text-neutral-subtle-on-disabled-bg`	Subtle neutral text on disabled backgrounds.
Text `text-neutral-subtle-on-subtler-bg`	Subtle neutral text on subtler backgrounds.
Text `text-neutral-subtler`	More muted text color.
Text `text-neutral-subtlest`	Least prominent text color.
Text `text-primary-brand-default`	Primary brand text color.
Text `text-primary-brand-hover`	Primary brand hover text color.
Text `text-primary-brand-active`	Primary brand active text color.
Text `text-primary-brand-on-checked-subtlest`	Primary brand text on checked subtlest backgrounds.
Text `text-primary-brand-on-neutral-hover-bg`	Primary brand text on neutral hover backgrounds.
Text `text-primary-brand-on-soft-bg`	Primary brand text on soft brand backgrounds.
Text `text-secondary-brand-default`	Secondary brand text color.
Text `text-secondary-brand-on-checked-subtlest`	Secondary brand text on checked subtlest backgrounds.
Text `text-secondary-brand-on-soft-bg`	Secondary brand text on soft brand backgrounds.

Border colors

Token	Description
`border-default`	Default border color.
`border-danger`	Border for danger states.
`border-error`	Border for error states.
`border-inactive`	Border for inactive elements.
`border-info`	Border for informational messages.
`border-success`	Border for success states.
`border-warning`	Border for warning states.
`border-neutral-hover`	Border color on neutral hover state.
`border-neutral-on-disabled-bg`	Neutral border on disabled backgrounds.
`border-neutral-on-filled`	Neutral border on filled backgrounds.
`border-neutral-stacked`	Neutral stacked border color.
`border-neutral-subtle`	Subtle neutral border color.
`border-neutral-disabled`	Border color for disabled elements.
`border-primary-brand-default`	Primary brand border color.
`border-primary-brand-hover`	Primary brand hover border color.
`border-primary-brand-active`	Primary brand active border color.
`border-secondary-brand`	Secondary brand border color.
`border-delete-default`	Default delete border color.
`border-delete-subtle`	Subtle delete border color.

Icon colors

Token	Description
`icon-default`	Default icon color
`icon-danger`	Danger icon
`icon-danger-subtle`	Subtle danger icon
`icon-delete`	Icon color for delete actions
`icon-error`	Icon color for error states
`icon-info`	Informational icon
`icon-info-subtle-strong`	Emphasized subtle info icon
`icon-rating`	Icon color for rating indicators
`icon-success`	Success icon
`icon-success-subtle`	Subtle success icon
`icon-warning`	Warning icon
`icon-warning-on-bg`	Warning icon on colored backgrounds
`icon-warning-subtle`	Subtle warning icon
`icon-neutral-disabled`	Disabled icon
`icon-neutral-inactive`	Inactive icon
`icon-neutral-on-filled-bg`	Neutral icon on filled backgrounds
`icon-neutral-on-filled-secondary-brand-bg`	Neutral icon on filled secondary brand backgrounds
`icon-neutral-on-monochrome-active-bg`	Neutral icon on active monochrome backgrounds
`icon-neutral-on-monochrome-hover-bg`	Neutral icon on hover monochrome backgrounds
`icon-neutral-on-neutral-bg`	Neutral icon on neutral backgrounds
`icon-neutral-on-primary-brand-soft-bg`	Neutral icon on soft primary brand backgrounds
`icon-neutral-on-subtlest-bg`	Neutral icon on subtlest backgrounds
`icon-neutral-subtle`	Subtle neutral icon color
`icon-neutral-subtle-on-subtler-bg`	Subtle neutral icon on subtler backgrounds
`icon-neutral-subtler`	More muted neutral icon color
`icon-neutral-subtlest`	Least prominent neutral icon color
`icon-primary-brand-default`	Primary brand icon color
`icon-primary-brand-hover`	Primary brand hover icon color
`icon-primary-brand-active`	Primary brand active icon color
`icon-primary-brand-on-neutral-hover-bg`	Primary brand icon on neutral hover backgrounds
`icon-primary-brand-on-soft-bg`	Primary brand icon on soft brand backgrounds
`icon-primary-brand-rating`	Primary brand icon used for rating indicators
`icon-secondary-brand-active`	Secondary brand active icon color
`icon-secondary-brand-default`	Secondary brand icon color

Spacing

Token	Description
`column-gap`	Default column gap spacing
`content-side-padding`	Horizontal content padding
`content-side-padding-mobile`	Mobile horizontal content padding
`content-body-bottom-padding`	Bottom padding for content areas
`section-xs`	Extra-small vertical section spacing
`section-sm`	Small vertical section spacing
`section-md`	Medium vertical section spacing
`section-lg`	Large vertical section spacing
`section-xl`	Extra-large vertical section spacing

Radius

Token	Description
`button`	Standard button border radius

Opacity

Token	Description
`disabled`	Opacity for disabled elements

Token usage

Use design tokens in your code by applying the corresponding Tailwind classes, following the pattern: category-name (e.g., bg-background-neutral-bold, text-text-default, border-border-default, opacity-disabled).

 <div 
    :class="[
        'bg-background-neutral-bold',
        'text-text-default',
        'border-border-default',
        'p-section-md',
        'rounded-button',
        'opacity-disabled',
    ]"
>
    This div uses various design tokens for styling.
</div>

Theme customization

Learn how to customize the theme of AirUI.

MCP Server

Learn about the MCP Server and how to use it with AirUI.