Name	Email	Role
John Doe	john@example.com	Admin

Name	Email	Role	Actions
{{ user.name }}	{{ user.email }}	{{ user.role }}

This is the abridged developer documentation for Airframe # Introduction > Airframe — a structural UI system designed for humans and AI **Airframe** is a structural UI system designed for humans and AI. Import one CSS file. Get layout primitives (`af-stack`, `af-inline`, `af-grid`), a full token layer, accessible patterns, and a readable DOM. No build step. No JavaScript runtime. No framework lock-in. Like an aircraft airframe, it defines the form and integrity of the system. You bring the engine: React, Vue, Angular, AI-generated code, or whatever comes next. ## Structure first [Section titled “Structure first”](#structure-first) Most tools help you style surfaces or assemble components. Airframe starts with the layout contract underneath — stack, inline, grid, tokens, and patterns that keep markup readable. ``` Tailwind → styling utilities Bootstrap → components Airframe → UI structure ``` That is not a brand-new category. It is a different priority: structure before decoration, so the DOM stays understandable when humans or AI change it. ## What it is / isn’t [Section titled “What it is / isn’t”](#what-it-is--isnt) | Airframe is | Airframe is not | | ------------------------------------------------------------------------------- | --------------------------------------- | | Structural primitives and patterns | A component library with JS widgets | | CSS tokens you override at runtime (optional Theme Studio / `af theme` codegen) | A required build step to use the system | | Readable `af-*` markup | Utility soup | | Framework-agnostic CSS | Another React (or Vue) dependency | You keep your framework. Airframe gives the structure that survives it. ## Why start [Section titled “Why start”](#why-start) Readable markup for your team. Predictable patterns for AI. Branding via CSS variables, not a rebuild. Accessibility as infrastructure, not a plugin. [Install Airframe](/docs/installation) · [Read the Manifesto](/docs/manifesto) ## Next Steps [Section titled “Next Steps”](#next-steps) * [Installation](/docs/installation) — get the CSS in your project * [Usage](/docs/usage) — first patterns and primitives * [Layouts](/docs/layouts) — stack, inline, grid, and more * [Tokens & Theming](/docs/theming) — brand it with `--af-*` variables * [Demo](/demo) — an admin UI built only with Airframe classes * [AI Rules](/docs/ai-rules) — the contract for humans and coding agents # Installation > How to install and set up Airframe Install `@airframeui/core`, import one CSS file, and start using patterns. No build plugin required. ## Installation [Section titled “Installation”](#installation) ### 01 — Install the package [Section titled “01 — Install the package”](#01--install-the-package) ``` npm install @airframeui/core # or yarn add @airframeui/core pnpm add @airframeui/core ``` ### 02 — Import the CSS [Section titled “02 — Import the CSS”](#02--import-the-css) Add Airframe to your global stylesheet (recommended): ``` @import "@airframeui/core/core.css"; ``` Or link it from HTML: ``` ``` ### 03 — Start using Airframe [Section titled “03 — Start using Airframe”](#03--start-using-airframe) Use semantic pattern classes immediately: ```

Card Title

Card content goes here.

``` ## Framework guides [Section titled “Framework guides”](#framework-guides) Prefer a framework-specific entrypoint? Use these and skip the generic steps above. ### Next.js [Section titled “Next.js”](#nextjs) Add to `app/globals.css` or `styles/globals.css`: ``` @import "@airframeui/core/core.css"; ``` See the full [Next.js guide](/docs/nextjs). ### React (Vite / Next.js) [Section titled “React (Vite / Next.js)”](#react-vite--nextjs) Add to your main CSS file (e.g. `src/index.css`): ``` @import "@airframeui/core/core.css"; ``` ### Angular [Section titled “Angular”](#angular) Add to `angular.json` under `projects..architect.build.options`: ``` "styles": [ "node_modules/@airframeui/core/core.css", "src/styles.scss" ] ``` Or import in `src/styles.scss`: ``` @import "@airframeui/core/core.css"; ``` See the full [Angular guide](/docs/angular). ### Vue [Section titled “Vue”](#vue) Add to your main CSS file or import from `main.js` / `main.ts`: ``` @import "@airframeui/core/core.css"; ``` ## Next steps [Section titled “Next steps”](#next-steps) * [Usage](/docs/usage) — first patterns and primitives * [Core concepts](/docs/layouts) — layouts, responsive suffix, theming * [Framework Support](/docs/framework-support) — setup overview by framework * [Browser Support](/docs/browser-support) — supported browsers and polyfills # Usage > How to use Airframe in your projects Start using semantic classes immediately after installation. ## Basic Example [Section titled “Basic Example”](#basic-example) ```

Card Title

Card content goes here.

Primary action

``` ### Live Example [Section titled “Live Example”](#live-example) ## Card Title Card content goes here. [Primary action](url) ## Semantic HTML [Section titled “Semantic HTML”](#semantic-html) Airframe styles semantic HTML by default. Many elements work without classes: ```

Main Heading

Section Heading

``` ### Live Example [Section titled “Live Example”](#live-example-1) # Main Heading ## Section Heading EmailSubmit ## Layout Recipes [Section titled “Layout Recipes”](#layout-recipes) Use layout recipes for common patterns: ```

Title

Content

``` ### Live Example [Section titled “Live Example”](#live-example-2) # Title Content Action SaveCancel ## Patterns [Section titled “Patterns”](#patterns) Use pattern classes for common UI structures: ```

Card Title

Card content

Success message

Name

``` ### Live Example [Section titled “Live Example”](#live-example-3) ### Card Title Card content Success message Name ## Responsive Design [Section titled “Responsive Design”](#responsive-design) Use responsive suffixes for breakpoint-specific styles: ```

Item 1

Item 2

Item 3

``` ### Live Example [Section titled “Live Example”](#live-example-4) Item 1 Item 2 Item 3 *Resize your browser to see the grid adapt: 1 column on mobile, 2 on tablet, 3 on desktop.* ## Utilities [Section titled “Utilities”](#utilities) Use utility classes for spacing, typography, and more: ```

Content

Centered muted text

Hidden on small screens

``` ### Live Example [Section titled “Live Example”](#live-example-5) Content with padding and margin Centered muted text Hidden on small screens, visible on medium and up ## Next Steps [Section titled “Next Steps”](#next-steps) * [Layouts](/docs/layouts) - Learn layout patterns * [Theming](/docs/theming) - Customize colors and tokens * Browse [Patterns](/docs/patterns) for more UI structures # AI Rules > Authoritative rules for generating Airframe markup with AI coding agents The authoritative rules ship with `@airframeui/core` as **`@airframeui/core/rules`** (`AIRFRAME_RULES.md`). This page is the docs summary agents and humans should follow when generating markup. ## For LLMs and coding agents [Section titled “For LLMs and coding agents”](#for-llms-and-coding-agents) Prefer these entry points over scraping the whole site: * [`/llms.txt`](/llms.txt) — curated index of documentation sets and package resources * [`/llms-small.txt`](/llms-small.txt) — abridged docs (best default context) * [`/_llms-txt/ai-rules.txt`](/_llms-txt/ai-rules.txt) — this page + AI engineering notes * [`/_llms-txt/getting-started.txt`](/_llms-txt/getting-started.txt) — install, usage, tokens, layouts After `npm install @airframeui/core`, load in-project resources: ``` // JSON (safe to import in Node / bundlers) import catalog from '@airframeui/core/catalog'; // component metadata import classes from '@airframeui/core/classes'; // class reference import examples from '@airframeui/core/examples'; // code examples // Markdown — resolve the package export and read as text (do not assume a JS default export) // @airframeui/core/rules → AIRFRAME_RULES.md // @airframeui/core/ai → AI_INTEGRATION.md ``` ## Non-negotiable rules [Section titled “Non-negotiable rules”](#non-negotiable-rules) * **Semantic HTML first** — ` ``` ### Semantic typography first [Section titled “Semantic typography first”](#semantic-typography-first) ```

Title

Body text

Visually H1, semantically H2

Caption

Title

` | ### Basic Stack [Section titled “Basic Stack”](#basic-stack) Code Live ```

Item 1

Item 2

Item 3

``` Item 1 Item 2 Item 3 ### Stack Sizes [Section titled “Stack Sizes”](#stack-sizes) Code Live ```

Small spacing

Default spacing (md)

Medium spacing (same as default)

Large spacing

``` Small gap Small gap Default gap Default gap Large gap Large gap ### Live Examples [Section titled “Live Examples”](#live-examples) Basic stack (default gap-md): Item 1 Item 2 Item 3 Stack sizes: Small gap Small gap Default gap Default gap Large gap Large gap ## Inline [Section titled “Inline”](#inline) Horizontal layout with wrapping for arranging items in a row. ### Class Reference [Section titled “Class Reference”](#class-reference-1) | Class | Purpose | Gap Size | Example | | -------------- | ----------------------- | ----------------- | ---------------------------- | | `af-inline` | Default horizontal wrap | Medium (`gap-md`) | `

` | ### Basic Inline [Section titled “Basic Inline”](#basic-inline) Code Live ```

``` Button 1 Button 2 Button 3 ### Inline Sizes [Section titled “Inline Sizes”](#inline-sizes) Code Live ```

``` Small Gap Default Gap Large Gap XL Gap ### Inline with Justify Content [Section titled “Inline with Justify Content”](#inline-with-justify-content) Code Live ```

` | | `af-spread` | Inline spread (space-between) | `

` | ### Examples [Section titled “Examples”](#examples) Code Live ```

Tag 1 Tag 2 Tag 3

Left Right

``` Tag 1 Tag 2 Tag 3 Left Right **Explicit equivalents (when needed):** Code Live ```

Cluster content Cluster content

Left Right

``` Cluster content Cluster content Left Right ## Cover & Sidebar [Section titled “Cover & Sidebar”](#cover--sidebar) **Cover** - Full-viewport hero layout (min-height: 100dvh, centered content): Code Live ```

Hero

Centered full-viewport layout

``` # Hero Centered full-viewport layout **Sidebar** - Main content + sidebar (stacks on mobile, side-by-side on tablet+): Code Live ``` ``` Main content Sidebar ## Center [Section titled “Center”](#center) Centers content horizontally and vertically. Code Live ```

Centered

``` Centered **Explicit equivalent:** Code Live ```

Centered

``` Centered ## Container [Section titled “Container”](#container) Centered content wrapper with max-width and horizontal padding. Use **one class** per element. | Class | Max Width | Use Case | | ------------------ | -------------- | ------------------------------ | | `af-container` | 90em (1440px) | Default, standard page content | | `af-container-xs` | 25rem (400px) | Narrow forms, sidebars | | `af-container-sm` | 40rem (640px) | Narrow content | | `af-container-md` | 48rem (768px) | Tablet-optimized | | `af-container-lg` | 64rem (1024px) | Desktop content | | `af-container-xl` | 80rem (1280px) | Wide layouts | | `af-container-2xl` | 96rem (1536px) | Extra-wide layouts | **Tip:** Use **one class only**. `af-container-xl` is enough. Do not combine `af-container af-container-xl`. For responsive sizing, use the responsive suffix: `af-container af-container-lg@xl` (default on mobile, large at xl breakpoint). ### Basic Container [Section titled “Basic Container”](#basic-container) Code Live ```

``` Container content with default max-width (90em / 1440px) ### Container Sizes [Section titled “Container Sizes”](#container-sizes) Code Live ```

Extra small (400px max)

Small (640px max)

Medium (768px max)

Large (1024px max)

Extra large (1280px max)

``` xs - 400px max sm - 640px max md - 768px max lg - 1024px max xl - 1280px max ### Live Examples [Section titled “Live Examples”](#live-examples-2) Default container: Container content with default max-width (90em / 1440px) Container sizes: xs - 400px max sm - 640px max md - 768px max lg - 1024px max xl - 1280px max ## Surface [Section titled “Surface”](#surface) Surface pattern for creating simple containers with background, border, and border-radius. Unlike cards, surfaces don’t include padding or shadows—you add those yourself. ### Basic Surface [Section titled “Basic Surface”](#basic-surface) Code Live ```

Surface with padding added

``` Surface with padding added ### Surface Variants [Section titled “Surface Variants”](#surface-variants) Use `af-is-*` modifier classes to change the surface background: Code Live ```

Default surface (primary)

Secondary surface

Tertiary surface

``` Default surface (primary background) Secondary surface variant Tertiary surface variant ### When to Use Surface vs Card [Section titled “When to Use Surface vs Card”](#when-to-use-surface-vs-card) * **Surface** (`af-surface`): Simple container without padding or shadow. Use for panels, backgrounds, or when you need full control over spacing. * **Card** (`af-card`): Full component with padding, shadow, and semantic parts. Use for content containers with structure. ### Live Example [Section titled “Live Example”](#live-example) Default surface (primary background) Secondary surface variant Tertiary surface variant ## Section [Section titled “Section”](#section) Section pattern for consistent vertical spacing between page sections. Adds padding-block (top and bottom padding) to create visual separation. ### Basic Section [Section titled “Basic Section”](#basic-section) Code Live ```

Section Title

Section content

``` ### Section Title Section content ### Section Sizes & Variants [Section titled “Section Sizes & Variants”](#section-sizes--variants) Code Live ```

``` ### Small Section Reduced vertical spacing (space-4) ### Default Section Standard vertical spacing (space-6) ### Large Section Increased vertical spacing (space-8) ### Section Variants [Section titled “Section Variants”](#section-variants) * `af-section-hero` - Extra padding for hero sections * `af-section-alt` - Alternate background (`--af-color-surface-primary`) * `af-section-narrow` - Constrains child `.af-container` to `--af-container-max-w-md` ### Use Cases [Section titled “Use Cases”](#use-cases) * Page sections with consistent spacing * Content areas that need vertical rhythm * Separating major content blocks ### Live Example [Section titled “Live Example”](#live-example-1) ### Small Section Reduced vertical spacing (space-4) ### Default Section Standard vertical spacing (space-6) ### Large Section Increased vertical spacing (space-8) ## Spacer [Section titled “Spacer”](#spacer) Utility for adding vertical spacing (margin-block) between elements. Useful when you need spacing but don’t want to use a full stack layout. ### Basic Usage [Section titled “Basic Usage”](#basic-usage) Code Live ```

``` Content Small spacer above Content Medium spacer above Content Large spacer above Content ### Spacer Sizes [Section titled “Spacer Sizes”](#spacer-sizes) * `af-spacer-sm` - Small spacing (space-2) * `af-spacer-md` - Medium spacing (space-4) * `af-spacer-lg` - Large spacing (space-6) ### When to Use [Section titled “When to Use”](#when-to-use) * Adding spacing between individual elements * Creating gaps in non-stack layouts * Quick vertical rhythm without changing layout structure **Note:** For consistent vertical layouts, prefer `af-stack` with gap utilities. Use spacer for one-off spacing needs. ### Live Example [Section titled “Live Example”](#live-example-2) Content Small spacer above Content Medium spacer above Content Large spacer above Content ## Position [Section titled “Position”](#position) Position utilities for controlling element positioning and placement. ### Position Values [Section titled “Position Values”](#position-values) Code Live ```

``` Relative container ### Shorthand Classes [Section titled “Shorthand Classes”](#shorthand-classes) Code Live ```

Relative (shorthand)

Absolute (shorthand)

Sticky (shorthand)

``` Relative (shorthand) ### Position Offsets [Section titled “Position Offsets”](#position-offsets) Code Live ```

``` Top-left Top-right Bottom-left Bottom-right Relative container ### Available Classes [Section titled “Available Classes”](#available-classes) **Position:** * `af-pos-relative` / `af-relative` - `position: relative` * `af-pos-absolute` / `af-absolute` - `position: absolute` * `af-pos-sticky` / `af-sticky` - `position: sticky` * `af-pos-revert` - `position: revert` **Offsets:** * `af-inset-0` - `inset: 0` (all edges) * `af-top-0` - `top: 0` * `af-right-0` - `right: 0` * `af-bottom-0` - `bottom: 0` * `af-left-0` - `left: 0` ### Live Example [Section titled “Live Example”](#live-example-3) Top-left Top-right Bottom-left Bottom-right Relative container ## Responsive Suffixes [Section titled “Responsive Suffixes”](#responsive-suffixes) All layout classes support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for the full syntax and breakpoint table. Code Live ```

``` Medium gap on mobile, large gap on tablet+ Item 2 ## Flex Alignment Utilities [Section titled “Flex Alignment Utilities”](#flex-alignment-utilities) Control alignment in flex containers: ### Justify Content (Horizontal Alignment) [Section titled “Justify Content (Horizontal Alignment)”](#justify-content-horizontal-alignment) Code Live ```

``` Start Aligned Center Aligned End Aligned Space Between ### Align Items (Vertical Alignment) [Section titled “Align Items (Vertical Alignment)”](#align-items-vertical-alignment) Code Live ```

``` Start Aligned Center Aligned End Aligned ### Responsive Alignment [Section titled “Responsive Alignment”](#responsive-alignment) Code Live ```

Start on mobile, center on tablet+

``` Start on mobile Center on tablet+ ### Live Example [Section titled “Live Example”](#live-example-4) Justify content examples: StartAligned CenterAligned EndAligned SpaceBetween Align items examples: StartAligned CenterAligned EndAligned ## Masonry (Experimental) [Section titled “Masonry (Experimental)”](#masonry-experimental) Masonry layout creates a waterfall-style layout where items flow into columns based on their height, similar to Pinterest-style layouts. ⚠️ **Experimental Feature** - Uses CSS Grid Lanes, which has very limited browser support. See [Browser Support](/docs/browser-support) for details. ### Browser Support [Section titled “Browser Support”](#browser-support) * ✅ **Safari Technology Preview 234+** (December 2025) - Full support * ⚠️ **Chrome 140+** - Available behind experimental flag * ⚠️ **Firefox 147+** - Available behind experimental flag * ⚠️ **Edge** - Available behind experimental flag **Fallback:** In unsupported browsers, automatically falls back to regular CSS Grid (items display in a standard grid, not masonry). ### Class Reference [Section titled “Class Reference”](#class-reference-3) | Class | Purpose | Column Width | Example | | ----------------- | ------------------- | ------------- | ------------------------------- | | `af-masonry` | Default masonry | 250px minimum | `

` | ### Basic Masonry [Section titled “Basic Masonry”](#basic-masonry) Code Live ```

``` ### Card 1 Short content ### Card 2 This card has more content to demonstrate how masonry layouts work. ### Card 3 Medium content ### Card 4 Another short card ### Masonry Variants [Section titled “Masonry Variants”](#masonry-variants) Code Live ```

Small columns (200px min)

Default columns (250px min)

Large columns (300px min)

Extra large columns (400px min)

Text-optimized (20ch min)

``` ### Card 1 Short content ### Card 2 This card has more content to demonstrate how masonry layouts work. Items flow into columns based on their height. ### Card 3 Medium content here ### Card 4 Another short card ### Live Example [Section titled “Live Example”](#live-example-5) ### Card 1 Short content ### Card 2 This card has more content to demonstrate how masonry layouts work. Items flow into columns based on their height. ### Card 3 Medium content here ### Card 4 Another short card ### Card 5 This is a longer card with more content to show how items of different heights flow into the masonry layout. The browser automatically places each item in the column that gets it closest to the top. ### Card 6 Short ### When to Use [Section titled “When to Use”](#when-to-use-1) * Photo galleries with varying image heights * Card layouts with different content lengths * Article teasers or blog post previews * Product listings with varying descriptions ### Polyfill for Production [Section titled “Polyfill for Production”](#polyfill-for-production) For production use in unsupported browsers, consider using a JavaScript polyfill: ``` // Feature detect and load polyfill if needed if (!CSS.supports('display', 'grid-lanes')) { import('masonry-layout').then(({ default: Masonry }) => { const grids = document.querySelectorAll('.af-masonry'); grids.forEach(grid => { new Masonry(grid, { itemSelector: '> *', columnWidth: 250, gutter: 16 }); }); }); } ``` See [Browser Support](/docs/browser-support#masonry-layout-grid-lanes-experimental) for more details. ## Gap Utilities [Section titled “Gap Utilities”](#gap-utilities) Control spacing between grid items or flex items: **Source of truth:** Gap utilities are defined in `grid.css` and documented in [Grid](/docs/grid). | Class | Gap Size | Token Value | Example | | ------------ | ---------------- | -------------- | -------------------------------------------- | | `af-gap-0` | No gap | `--af-space-0` | `

` | | `af-gap-2xl` | 2XL | `--af-space-6` | `

` | | `af-gap-3xl` | 3XL | `--af-space-7` | `

` | | `af-gap-4xl` | 4XL | `--af-space-8` | `

` | **Usage:** Gap utilities can override default gaps in any layout recipe: Code Live ```

Override stack's default gap

Override inline's default gap

Override grid's default gap

``` Override stack's default gap (large) Item 2 ## Complete Class Reference [Section titled “Complete Class Reference”](#complete-class-reference) All classes available in `layouts.css`: ### Stack Classes (5) [Section titled “Stack Classes (5)”](#stack-classes-5) * `af-stack` - Default vertical stack (medium gap) * `af-stack-sm` - Small gap vertical stack * `af-stack-md` - Medium gap vertical stack (same as default) * `af-stack-lg` - Large gap vertical stack * `af-stack-xl` - Extra large gap vertical stack ### Inline Classes (5) [Section titled “Inline Classes (5)”](#inline-classes-5) * `af-inline` - Default horizontal wrap (medium gap) * `af-inline-sm` - Small gap horizontal wrap * `af-inline-md` - Medium gap horizontal wrap (same as default) * `af-inline-lg` - Large gap horizontal wrap * `af-inline-xl` - Extra large gap horizontal wrap ### Cluster / Spread / Center Classes (3) [Section titled “Cluster / Spread / Center Classes (3)”](#cluster--spread--center-classes-3) * `af-cluster` - Inline cluster (wrap + center alignment) * `af-spread` - Inline spread (space-between) * `af-center` - Center contents on both axes ### Container Classes (7) [Section titled “Container Classes (7)”](#container-classes-7) * `af-container` - Default container (90em / 1440px max-width) * `af-container-xs` - Extra small container (400px max-width) * `af-container-sm` - Small container (640px max-width) * `af-container-md` - Medium container (768px max-width) * `af-container-lg` - Large container (1024px max-width) * `af-container-xl` - Extra large container (1280px max-width) * `af-container-2xl` - 2xl container (1536px max-width) ### Gap Utilities (9) [Section titled “Gap Utilities (9)”](#gap-utilities-9) * `af-gap-0` - No gap * `af-gap-xs` - Extra small gap * `af-gap-sm` - Small gap * `af-gap-md` - Medium gap * `af-gap-lg` - Large gap * `af-gap-xl` - Extra large gap * `af-gap-2xl` / `af-gap-3xl` / `af-gap-4xl` - Larger gaps (`--af-space-6`…`8`) **Total: 29 layout classes** - All support responsive variants with `@` suffix (e.g., `af-stack@md`) **Note:** Grid classes are documented separately. See [Grid](/docs/grid) for complete grid documentation. ## Best Practices [Section titled “Best Practices”](#best-practices) * Use `af-stack` for vertical layouts * Use `af-inline` for horizontal wrapping layouts * See [Grid](/docs/grid) for grid layouts (equal columns and 12-column system) * Prefer layout recipes (`af-stack`, `af-inline`, `af-grid`, `af-container`) over many atomic utility classes * Use responsive suffixes for breakpoint-specific styles * Combine layout recipes with pattern classes for complex layouts * Use `af-justify-*` and `af-items-*` for fine-grained alignment control ## Next Steps [Section titled “Next Steps”](#next-steps) * [Grid](/docs/grid) — equal columns and the 12-column system * [Responsive Suffix](/docs/responsive-suffix) — breakpoint variants with `@` * [Recipes](/docs/recipes) — copy-paste page compositions built from these primitives # Framework Support > Using Airframe with React, Angular, Next.js, Vue, and vanilla HTML Airframe is CSS-only and framework-agnostic. Install the core package and use it with any framework or vanilla HTML. ## Install [Section titled “Install”](#install) ``` npm install @airframeui/core ``` ``` @import "@airframeui/core/core.css"; ``` ``` ``` ## React [Section titled “React”](#react) ``` /* src/index.css */ @import "@airframeui/core/core.css"; ``` ``` function App() { return (

) } ``` See [React Recipes](/docs/react-recipes) for copy-paste ready components. ## Next.js [Section titled “Next.js”](#nextjs) ### App Router [Section titled “App Router”](#app-router) ``` /* app/globals.css */ @import "@airframeui/core/core.css"; ``` ``` // app/layout.tsx import './globals.css' export default function RootLayout({ children }) { return ( {children} ) } ``` ### Pages Router [Section titled “Pages Router”](#pages-router) ``` /* styles/globals.css */ @import "@airframeui/core/core.css"; ``` ``` // pages/_app.tsx import '../styles/globals.css' export default function App({ Component, pageProps }) { return } ``` See [Next.js Setup](/docs/nextjs) for a complete guide. ## Angular [Section titled “Angular”](#angular) ``` npm install @airframeui/core ``` Add to `angular.json` under `projects..architect.build.options`: ``` "styles": [ "node_modules/@airframeui/core/core.css", "src/styles.scss" ] ``` Use directly in templates: ``` @Component({ selector: 'app-dashboard', standalone: true, template: `

Dashboard

Revenue

$84,200

` }) export class DashboardComponent {} ``` See [Angular Setup](/docs/angular) for a complete guide. ## Vue [Section titled “Vue”](#vue) ``` /* src/main.css */ @import "@airframeui/core/core.css"; ``` ``` ``` ## Vanilla HTML [Section titled “Vanilla HTML”](#vanilla-html) ``` ``` ## Next Steps [Section titled “Next Steps”](#next-steps) * [Installation](/docs/installation) - Get started * [Usage](/docs/usage) - Learn the basics * [Angular Setup](/docs/angular) - Angular specific guide * [Next.js Setup](/docs/nextjs) - Next.js specific guide * [React Recipes](/docs/react-recipes) - React examples # Badges & Chips Badges, chips, pills, icon boxes, avatars, spinners, and skeletons for status indicators and loading states. Intent badges and chips use soft backgrounds with hard text for WCAG AA contrast on small labels. ## Patterns [Section titled “Patterns”](#patterns) * **[Avatar](/docs/patterns/badges-chips/avatar)**: `af-avatar`, `af-avatar-{sm|lg}` * **[Badge](/docs/patterns/badges-chips/badge)**: `af-badge`, `af-is-*` (soft + hard) * **[Chip](/docs/patterns/badges-chips/chip)**: `af-chip`, `af-is-*` (soft + hard) * **[Icon box](/docs/patterns/badges-chips/icon-box)**: `af-icon-box`, `af-is-sm` / `af-is-lg` * **[Pill](/docs/patterns/badges-chips/pill)**: `af-pill`, `af-pill__tag`, `af-is-on-primary` * **[Skeleton](/docs/patterns/badges-chips/skeleton)**: `af-skeleton`, `af-skeleton-*` * **[Spinner](/docs/patterns/badges-chips/spinner)**: `af-spinner`, `af-spinner-{sm|lg}` # Avatar > User profile images or initials Avatars display user profile pictures or initials. ## Basic usage [Section titled “Basic usage”](#basic-usage) ```

Active users

Subtitle or supporting line.

``` ** ### Active users Subtitle or supporting line. # Pill > Rounded announcement or status pill, optionally an interactive link Pills are rounded, bordered badges used for announcements, promos, or standalone status callouts — typically paired with a short tag and a link. Unlike `af-badge` and `af-chip`, which are meant to sit inline with text, a pill is a self-contained unit often used as a link (e.g. “New: Feature name →”). ## Basic usage [Section titled “Basic usage”](#basic-usage) ``` New Standalone pill New Link pill ``` ## Live example [Section titled “Live example”](#live-example) New Standalone pill [New Link pill →](#) ## On primary backgrounds [Section titled “On primary backgrounds”](#on-primary-backgrounds) Add `af-is-on-primary` when placing a pill on a brand-color or gradient background (for example, a hero section). It swaps to translucent, on-primary-safe colors instead of the default surface/border tokens. ``` New Built for AI-assisted workflows ``` [New Built for AI-assisted workflows →](#) # Skeleton > Skeleton loaders for content placeholders Skeleton loaders provide visual placeholders while content is loading. ## Basic usage [Section titled “Basic usage”](#basic-usage) ```

``` ## Accessibility [Section titled “Accessibility”](#accessibility) * Mark the loading region `aria-busy="true"` while skeletons are shown * Skeletons are decorative and should be `aria-hidden="true"` ## Variants [Section titled “Variants”](#variants) * `af-skeleton-circle` - Circular skeleton (for avatars, icons) * `af-skeleton-text` - Text line skeleton ## Live example [Section titled “Live example”](#live-example) # Spinner > CSS-only loading spinner CSS-only loading spinner for indicating loading states. ## Basic usage [Section titled “Basic usage”](#basic-usage) ```

``` ## Accessibility [Section titled “Accessibility”](#accessibility) * Decorative spinners should be `aria-hidden="true"` * When a spinner stands alone, provide an accessible name (`aria-label="Loading"` or visually hidden text) ## Sizes [Section titled “Sizes”](#sizes) * `af-spinner-sm` - Small spinner * `af-spinner` - Default size * `af-spinner-lg` - Large spinner ## Live example [Section titled “Live example”](#live-example) # Buttons > Accessible button pattern with multiple variants, sizes, and states Buttons are split into individual pattern pages: ## Patterns [Section titled “Patterns”](#patterns) * **[Button](/docs/patterns/button/button)**: `af-btn`, `af-is-*`, states, sizes * **[Button Group](/docs/patterns/button/button-group)**: `af-btn-group` * **[Icon Button](/docs/patterns/button/icon-button)**: `af-btn-icon` * **[Link Button](/docs/patterns/button/link-button)**: `…` # Button Group > Group related buttons together Group related buttons together: Code Live ```

Primary Alert: This is a primary alert message.

Success Alert: Operation completed successfully.

Warning Alert: Please review this information.

Danger Alert: An error has occurred.

Info Alert: Here's some helpful information.

``` ### Variant Classes [Section titled “Variant Classes”](#variant-classes) * `af-is-primary` - Primary/informational * `af-is-success` - Success/positive * `af-is-warning` - Warning/caution * `af-is-danger` - Error/destructive * `af-is-info` - Informational ## Live Example [Section titled “Live Example”](#live-example) **Primary Alert:** This is a primary alert message. **Success Alert:** Operation completed successfully. **Warning Alert:** Please review this information. **Danger Alert:** An error has occurred. **Info Alert:** Here’s some helpful information. # Banner > Banner messages for site-wide announcements Banner messages for site-wide announcements. ## Markup [Section titled “Markup”](#markup) ``` ``` ## Live example [Section titled “Live example”](#live-example) **Banner:** Important site-wide message. # Callout > Subtle alert variant for less urgent messages Subtle alert variant for less urgent messages. ## Markup [Section titled “Markup”](#markup) ```

Primary Callout: Subtle alert variant.

Success Callout: Success message.

Info Callout: Informational message.

``` ## Live example [Section titled “Live example”](#live-example) **Primary Callout:** Subtle alert variant. **Success Callout:** Success message. **Info Callout:** Informational message. # Card Cards group related content with optional media, headers, and actions. Variants align with [Tailwind UI Cards](https://tailwindcss.com/plus/ui-blocks/application-ui/layout/cards): basic, with header/footer, gray footer/body, edge-to-edge on mobile, and well. ## Basic card [Section titled “Basic card”](#basic-card) Code Live ```

Card Title

Card body content goes here.

``` ## Card Title Card body content goes here. ## Card with header [Section titled “Card with header”](#card-with-header) Code Live ```

Card body content goes here.

``` ## Card Title Card body content goes here. ## Card with footer [Section titled “Card with footer”](#card-with-footer) Code Live ```

Card body content goes here.

``` Card body content goes here. Save Cancel ## Card with header and footer [Section titled “Card with header and footer”](#card-with-header-and-footer) Code Live ```

Card body content goes here.

``` ## Card Title Card body content goes here. Action ## Card with gray footer [Section titled “Card with gray footer”](#card-with-gray-footer) Add `af-is-muted` to the footer, or `af-card--footer-muted` on the card, for a muted background that extends to the card edges. Code Live ```

Card body content goes here.

``` Card body content goes here. Save Cancel ## Card with gray body [Section titled “Card with gray body”](#card-with-gray-body) Add `af-is-muted` to the body, or `af-card--body-muted` on the card, for a muted body background that extends to the card edges. Code Live ```

Card Title

Card body with muted background.

``` ## Card Title Card body with muted background. ## Card, edge-to-edge on mobile [Section titled “Card, edge-to-edge on mobile”](#card-edge-to-edge-on-mobile) Add `af-card-edge` so the card bleeds to the container edges on viewports under 48rem. Use inside a padded container; override `--af-card-edge-offset` if your container padding differs. Code Live ```

Card Title

On small screens this card extends to the edges.

``` ## Card Title On small screens this card extends to the edges. ## Well [Section titled “Well”](#well) A softer, muted card with no shadow. Use `af-well` for a simple contained block (e.g. for charts, forms, or secondary content). Code Live ```

Well Title

Softer card with muted background and no shadow.

``` ## Well Title Softer card with muted background and no shadow. ## Well, edge-to-edge on mobile [Section titled “Well, edge-to-edge on mobile”](#well-edge-to-edge-on-mobile) Add `af-well-edge` so the well bleeds to the container edges on small viewports. Code Live ```

Well that extends to the edges on mobile.

``` Well that extends to the edges on mobile. ## Card with image [Section titled “Card with image”](#card-with-image) Code Live ```

Card Title

Card body content goes here.

``` ![Description](https://placehold.co/600x400) ## Card Title Card body content goes here. ## Card with overline and subtitle [Section titled “Card with overline and subtitle”](#card-with-overline-and-subtitle) Code Live ```

OPTIONAL OVERLINE

Card Title

Optional Subtitle

Card body content goes here.

``` OPTIONAL OVERLINE ## Card Title Optional Subtitle Card body content goes here. ## Card with buttons [Section titled “Card with buttons”](#card-with-buttons) Code Live ```

OPTIONAL OVERLINE

Card Title

Optional Subtitle

Card body content goes here.

``` OPTIONAL OVERLINE ## Card Title Optional Subtitle Card body content goes here. Action 1 Action 2 ## Card with links [Section titled “Card with links”](#card-with-links) Code Live ```

OPTIONAL OVERLINE

Card Title

Optional Subtitle

Card body content goes here.

``` OPTIONAL OVERLINE ## Card Title Optional Subtitle Card body content goes here. [Link 1](#) [Link 2](#) ## Full card link [Section titled “Full card link”](#full-card-link) Make the entire card clickable by using an `` tag: Code Live ```

Card Title

Entire card is clickable.

``` ## [Card Title](#) [Entire card is clickable.](#) ## Card parts [Section titled “Card parts”](#card-parts) * `af-card` – Base card container * `af-card-edge` – Edge-to-edge on mobile (inside a padded container; override `--af-card-edge-offset` if needed) * `af-card--footer-muted` – Card whose footer uses muted background (or add `af-is-muted` on the footer) * `af-card--body-muted` – Card whose body uses muted background (or add `af-is-muted` on the body) * `af-card__image` – Card image (full width, top-aligned) * `af-card__header` – Optional header section * `af-card__overline` – Small uppercase text above title * `af-card__title` – Card title/heading * `af-card__subtitle` – Subtitle text below title * `af-card__body` – Main card content (`af-is-muted` for gray body) * `af-card__footer` – Optional footer section (`af-is-muted` for gray footer) * `af-card__actions` – Container for buttons/links in footer * `af-well` – Softer card (muted background, no shadow) * `af-well-edge` – Well, edge-to-edge on mobile ## Hover effect [Section titled “Hover effect”](#hover-effect) By default, cards don’t have hover effects. Add the `af-has-hover` modifier class to enable hover shadow enhancement: Code Live ```

Card Title

Hover over this card to see the shadow effect.

``` ## Card Title Hover over this card to see the shadow effect. ## Visual style [Section titled “Visual style”](#visual-style) Cards have a subtle shadow. When the entire card is a link, it shows a focus ring for keyboard navigation. # Empty State > Empty state pattern for when there's no content to display Empty state pattern for when there’s no content to display. ## Markup [Section titled “Markup”](#markup) ```

📭

No items found

Get started by creating your first item.

``` ## Live example [Section titled “Live example”](#live-example) 📭 ### No items found Get started by creating your first item. Create Item # KPI > Key Performance Indicator displays for metrics and statistics Key Performance Indicator displays for metrics and statistics. Positive and negative change lines use `--af-color-success-hard` / `--af-color-danger-hard` so small delta text stays readable on surface backgrounds. ## Markup [Section titled “Markup”](#markup) ```

Total Users

1,234

+12%

``` ## Live example [Section titled “Live example”](#live-example) Total Users 1,234 +12% Revenue $45,678 +5% Churn Rate 2.3% -0.5% # Meter > Meter element for displaying scalar measurements Meter element for displaying scalar measurements. ## Markup [Section titled “Markup”](#markup) ``` 70% 50% 30% ``` ## Live example [Section titled “Live example”](#live-example) 70% 50% 30% # Progress > Progress bars for showing completion status Progress bars for showing completion status. ## Native `` element [Section titled “Native \ element”](#native-progress-element) ``` ``` ## Custom progress bar [Section titled “Custom progress bar”](#custom-progress-bar) ```

``` ## Live example [Section titled “Live example”](#live-example) # Toast > Toast notifications for temporary messages Toast notifications for temporary messages. ## Markup [Section titled “Markup”](#markup) ```

Success! Your changes have been saved.

``` ## Accessibility [Section titled “Accessibility”](#accessibility) * Status / success / info toasts: `role="status"` (polite live region) * Errors / urgent toasts: `role="alert"` (assertive live region) * Prefer `role="status"` by default — `role="alert"` interrupts screen readers and should be reserved for failures that need immediate attention * Decorative icons should be `aria-hidden="true"` * CSS styles the toast only; announcement behavior comes from the live-region role when the toast is inserted into the DOM ## Live example [Section titled “Live example”](#live-example) (Look in the corners of the screen!) **Success!** Your changes have been saved. # Data Display Patterns for displaying structured data and information. ## Patterns [Section titled “Patterns”](#patterns) * **[Accordion](/docs/patterns/data-display/accordion)**: `af-accordion` * **[Code Block](/docs/patterns/data-display/code-block)**: `af-code-block` * **[Description List](/docs/patterns/data-display/description-list)**: `af-dl` * **[List Group](/docs/patterns/data-display/list-group)**: `af-list-group`, `af-list-group-*` * **[Steps](/docs/patterns/data-display/steps)**: `af-steps`, `af-step`, `af-step-*` * **[Table](/docs/patterns/data-display/table)**: `af-table`, `af-table-striped` * **[Timeline](/docs/patterns/data-display/timeline)**: `af-timeline` # Accordion > Collapsible content sections using native

Collapsible content sections using native `

` element. ## Markup [Section titled “Markup”](#markup) ```

Section 1

Content for section 1 goes here.

Section 2 (Open)

This section is open by default.

``` ## Live example [Section titled “Live example”](#live-example) # Code Block > Code blocks for displaying code snippets Airframe styles `

` and `` elements directly. No class needed for basic usage. ## Inline code [Section titled “Inline code”](#inline-code) ```  Use  npm install @airframeui/core  to get started. 
 ``` ### Preview [Section titled “Preview”](#preview) Use `npm install @airframeui/core` to get started. ## Code block [Section titled “Code block”](#code-block) Wrap code in `` for multi-line blocks: ```   function greet(name) { console.log('Hello, ' + name + '!'); } greet('World');  
 ``` ### Preview [Section titled “Preview”](#preview-1) ``` function greet(name) { console.log('Hello, ' + name + '!'); } greet('World'); ``` ## With language class [Section titled “With language class”](#with-language-class) Add a language class to `` for syntax highlighter compatibility: ```   :root { --af-base-primary: #018183; --af-font-body: 'Inter', sans-serif; }  
 ``` ### Preview [Section titled “Preview”](#preview-2) ``` :root { --af-base-primary: #018183; --af-font-body: 'Inter', sans-serif; } ``` ## Multiple blocks [Section titled “Multiple blocks”](#multiple-blocks) ```    npm install @airframeui/core  
    @import "@airframeui/core/core.css";  
 ``` ### Preview [Section titled “Preview”](#preview-3) ``` npm install @airframeui/core ``` ``` @import "@airframeui/core/core.css"; ``` ## Class reference [Section titled “Class reference”](#class-reference) | Element/Class | Purpose | | ------------------------- | ------------------------------------------------------------------- | | `` | Styled automatically. Padding, background, border, rounded corners. | | `` (inside ``) | Transparent background, inherits font. | | `` (inline) | Inline code with subtle background. | | `.af-code-block` | Alias for `` styling. Not required. | ## CSS reference [Section titled “CSS reference”](#css-reference) ``` pre, .af-code-block { padding: var(--af-space-4); background: var(--af-color-surface-secondary); border: var(--af-border-width) solid var(--af-color-border); border-radius: var(--af-radius-md); overflow-x: auto; font-family: var(--af-font-code); font-size: var(--af-text-sm); line-height: var(--af-leading-normal); } pre code { background: transparent; padding: 0; } ``` ## Related [Section titled “Related”](#related) * [Typography](/docs/utilities/typography)

# Description List

> Key-value pairs for displaying structured information

Key-value pairs for displaying structured information. ## Markup [Section titled “Markup”](#markup) ```   Name 
  John Doe 
  Email 
  john@example.com 
  Role 
  Administrator 
  Status 
  Active 
 
 ``` ## Live example [Section titled “Live example”](#live-example) * Name John Doe * Email  * Role Administrator * Status Active

# List Group

> Selectable list for navigation or selection

Selectable list for navigation or selection. ## Markup [Section titled “Markup”](#markup) ```   Item 1 
  Active Item 
  Item 3 
  Disabled Item 
  Item 5 
  ``` ## States [Section titled “States”](#states) * `af-is-active` - Active/selected item * `af-is-disabled` - Disabled item ## Live example [Section titled “Live example”](#live-example) * Item 1 * Active Item * Item 3 * Disabled Item * Item 5

# Steps

> Progress tracker for multi-step processes

Progress tracker for multi-step processes. ## Markup [Section titled “Markup”](#markup) ```    1 
  Step 1 
 
  
   2 
  Step 2 
 
  
   3 
  Step 3 
 
  
   4 
  Step 4 
 
  ``` ## States [Section titled “States”](#states) * `af-is-complete` - Completed step * `af-is-active` - Current/active step * (no modifier) - Upcoming step ## Live example [Section titled “Live example”](#live-example) 1 Step 1 2 Step 2 3 Step 3 4 Step 4

# Table

> Tables for displaying tabular data

Tables for displaying tabular data. ## Basic table [Section titled “Basic table”](#basic-table) ```     Name   Email   Role  
 
    John Doe   john@example.com   Admin  
 
 
 ``` ## Striped table [Section titled “Striped table”](#striped-table) ```   
 ``` ## Live example [Section titled “Live example”](#live-example) | Name | Email | Role | | ----------- | ------------------ | ----- | | John Doe |  | Admin | | Jane Smith |  | User | | Bob Johnson |  | User | | Product | Price | Stock | | ------- | ----- | ----- | | Item 1 | $10 | 50 | | Item 2 | $20 | 30 | | Item 3 | $30 | 20 |

# Timeline

> Timeline pattern for displaying chronological events

Timeline pattern for displaying chronological events. ## Markup [Section titled “Markup”](#markup) ```    Event 1 
  Description of event 1 
 
   Event 2 
  Description of event 2 
 
  ``` ## Live example [Section titled “Live example”](#live-example) Event 1 Description of event 1 Event 2 Description of event 2 Event 3 Description of event 3

# Forms

Complete form patterns for building accessible, user-friendly forms. ## Patterns [Section titled “Patterns”](#patterns) * **[Checkbox](/docs/patterns/forms/checkbox)**: `af-checkbox` * **[Classless form](/docs/patterns/forms/classless-form)**: `form.af-form` * **[Field](/docs/patterns/forms/field)**: `af-field`, `af-field__*` * **[File input](/docs/patterns/forms/file-input)**: `af-file-input` * **[Form layout](/docs/patterns/forms/form-layout)**: `af-field-inline`, `` * **[Input](/docs/patterns/forms/input)**: `af-input`, states, tokens * **[Input group](/docs/patterns/forms/input-group)**: `af-input-group`, `af-input-group-addon` * **[Label](/docs/patterns/forms/label)**: semantic labels (optional `.af-label`) * **[Radio](/docs/patterns/forms/radio)**: `af-radio` * **[Range](/docs/patterns/forms/range)**: `af-range` * **[Select](/docs/patterns/forms/select)**: `af-select` (or `form.af-form`) * **[Switch](/docs/patterns/forms/switch)**: `role="switch"` (or `.af-switch`) * **[Textarea](/docs/patterns/forms/textarea)**: `af-textarea`, `af-is-auto-grow` * **[Validation & error states](/docs/patterns/forms/validation)**: `aria-invalid`, `af-is-error`, `aria-describedby`

# Checkbox

> Checkboxes for selecting one or more options

Checkboxes for selecting one or more options. Labels automatically use flex layout when they contain checkboxes. Control size uses `--af-choice-size` (default `1.5rem`, shared with radio and the switch track height). Override it to scale all choice controls together — see [Tokens](/docs/tokens#shared-control-tokens). ## Markup [Section titled “Markup”](#markup) ```    Checked      Unchecked      Disabled   ``` ## Classless checkbox [Section titled “Classless checkbox”](#classless-checkbox) Checkboxes also work without classes inside `form.af-form`: ```     Enable notifications    ``` ## Live example [Section titled “Live example”](#live-example) \[x]Checked\[ ]UncheckedDisabled

# Classless Form

> Automatic styling with form.af-form

For a classless approach, wrap your form in `form.af-form`. This enables automatic styling for additional form elements. ## Markup [Section titled “Markup”](#markup) ```   Email    Country    Message     
 ``` ## What works without classes [Section titled “What works without classes”](#what-works-without-classes) Inside `form.af-form`, these elements work without classes: * `input[type="text"]`, `input[type="email"]`, `input[type="password"]`, etc. * `textarea` * `input[type="checkbox"]` * `input[type="radio"]` * `input[type="range"]` * `input[type="file"]` Note: `label` and `input[type="checkbox"][role="switch"]` already work without `form.af-form` (they have default styling). `select` requires either `.af-form` wrapper or `.af-select` class. ## Live example [Section titled “Live example”](#live-example) EmailCountryChoose a countryMessageSubmit

# Field

> Consistent form field structure with label, control, help, and error

The field pattern provides a consistent structure for form fields with labels, controls, help text, and error messages. ## Basic field [Section titled “Basic field”](#basic-field) ```   Label    
  Help text goes here 
 
 ``` ## Field with error [Section titled “Field with error”](#field-with-error) **Required for accessibility:** Error messages must be linked to the input via `aria-describedby`. The input references the error message’s `id` attribute. ```   With Error    
  Error message 
  ``` ## Live example [Section titled “Live example”](#live-example) Label Enter text Help text goes here With Error Error message

# File Input

> File upload input styling

File upload input. ## Markup [Section titled “Markup”](#markup) ```  ``` ## Live example [Section titled “Live example”](#live-example)

# Form Layout

> Inline fields and fieldset patterns

## Inline fields [Section titled “Inline fields”](#inline-fields) Fields with labels on the same line as the input. ```   Inline Field    
 
 ``` ## Fieldset [Section titled “Fieldset”](#fieldset) Group related fields together. ```   Fieldset Example    Field 1   
   Field 2   
  ``` ## Live example [Section titled “Live example”](#live-example) Inline Field Fieldset Example Field 1 Field 2

# Input Group

> Input with prefix/suffix addons

Input with prefix or suffix addons for icons, symbols, or text. ## Prefix and suffix [Section titled “Prefix and suffix”](#prefix-and-suffix) ```   $    .00  
 ``` ## Prefix only [Section titled “Prefix only”](#prefix-only) ```   @   
 ``` ## Suffix only [Section titled “Suffix only”](#suffix-only) ```    🔍   ``` ## Live example [Section titled “Live example”](#live-example) $Amount.00 @Username Search🔍

# Input

> Text inputs for single-line text entry

Text inputs for single-line text entry. Supports all standard HTML input types. ## Input types [Section titled “Input types”](#input-types) ```          ``` ## States [Section titled “States”](#states) ```    ``` ## Autosize input (experimental) [Section titled “Autosize input (experimental)”](#autosize-input-experimental) Use `af-is-autosize` to let single-line inputs grow with content: ```  ``` **Info:** Inputs growing horizontally as you type can cause layout shifts (bad in modern UI/UX). Use autosize only for narrow, controlled cases (like tag inputs or inline search). ## Component tokens [Section titled “Component tokens”](#component-tokens) Form controls use shared control tokens plus input-specific tokens (applies to inputs, selects, and textareas): * `--af-control-min-height`, `--af-control-radius` * `--af-input-min-height`, `--af-input-font-size`, `--af-input-leading` * `--af-input-placeholder-color`, `--af-input-padding-x`, `--af-input-padding-y` ```   ``` ## Error handling [Section titled “Error handling”](#error-handling) **Required for accessibility:** When showing errors, you must: 1. Set `aria-invalid="true"` on the input 2. Link the error message via `aria-describedby` (input references error message `id`) ```   Email    Please enter a valid email address 
 
 ``` ## Live example [Section titled “Live example”](#live-example) Text input[Email input]()••••••••••••••SearchError state

# Label

> Styled form labels (semantic-first)

Labels are automatically styled with proper typography and spacing. ## Markup [Section titled “Markup”](#markup) ```   Name     Email   ```

# Radio

> Radio buttons for selecting a single option

Radio buttons for selecting a single option from a group. Labels automatically use flex layout when they contain radios. Control size uses `--af-choice-size` (default `1.5rem`, shared with checkbox and the switch track height). Override it to scale all choice controls together — see [Tokens](/docs/tokens#shared-control-tokens). ## Markup [Section titled “Markup”](#markup) ```    Option 1      Option 2   ``` ## Classless radio [Section titled “Classless radio”](#classless-radio) Radios also work without classes inside `form.af-form`: ```     Light theme      Dark theme    ``` ## Live example [Section titled “Live example”](#live-example) \[x]Option 1\[ ]Option 2Disabled

# Range

> Range slider for selecting a value within a range

Range slider for selecting a value within a range. ## Markup [Section titled “Markup”](#markup) ```  ``` ## Live example [Section titled “Live example”](#live-example) 5075

# Select

> Dropdown select for choosing from a list of options

Dropdown select for choosing from a list of options. Select elements require either a `.af-form` wrapper or the `.af-select` class. In browsers that support [customizable `         
 ``` ## States [Section titled “States”](#states) ```    ``` ## Option groups [Section titled “Option groups”](#option-groups) ```  ``` ## Live example [Section titled “Live example”](#live-example) Choose an optionChoose a petError stateDisabled

# Switch

> Toggle switch for on/off states

Toggle switch for on/off states. Supports both semantic HTML and class-based approaches. Track height uses `--af-switch-height` (defaults to `--af-choice-size`, `1.5rem`). Width is `height × (1 + --af-switch-width-ratio)` (ratio default `0.8`). Checkbox and radio use the same `--af-choice-size` so the three stay visually aligned — see [Tokens](/docs/tokens#shared-control-tokens). ## Semantic switch (recommended) [Section titled “Semantic switch (recommended)”](#semantic-switch-recommended) Use `role="switch"` for better accessibility and semantic HTML. Labels automatically use flex layout when they contain switches: ```    Enable notifications   ``` ## Class-based switch (legacy) [Section titled “Class-based switch (legacy)”](#class-based-switch-legacy) The traditional class-based approach is still supported: ```      ``` ## States [Section titled “States”](#states) ```           ``` ## Live example [Section titled “Live example”](#live-example) #### Semantic switch (recommended) \[x]Enable notifications\[ ]Dark modeDisabled option #### Class-based switch (legacy) \[x]\[ ] ## Sizing tokens [Section titled “Sizing tokens”](#sizing-tokens) ``` :root { --af-choice-size: 1.5rem; /* checkbox, radio, default switch height */ --af-switch-height: var(--af-choice-size); --af-switch-width-ratio: 0.8; } ```

# Textarea

> Multi-line text input with optional auto-grow

Multi-line text input for longer content. ## Basic textarea [Section titled “Basic textarea”](#basic-textarea) ```   ``` ## With rows [Section titled “With rows”](#with-rows) ```   ``` ## Auto-grow textarea [Section titled “Auto-grow textarea”](#auto-grow-textarea) Textareas can automatically grow with content using the `af-is-auto-grow` class. This uses the modern CSS `field-sizing: content` property (supported in Chrome 123+ and Edge 123+). ```   ``` **Browser Support:** The CSS `field-sizing: content` property is supported in Chrome 123+ and Edge 123+. For full browser support, install and import the polyfills package: ``` npm install @airframeui/polyfills ``` ``` // In your entry file import '@airframeui/polyfills'; ``` The polyfills automatically detect browser support and only apply JavaScript fallbacks when needed. See the [Browser Support](/docs/browser-support) documentation for framework-specific examples and our browser support philosophy. ## States [Section titled “States”](#states) ```       ``` ## Live example [Section titled “Live example”](#live-example)

# Validation & Error States

> Error handling, required fields, and help text

## Error handling [Section titled “Error handling”](#error-handling) Use `aria-invalid="true"` or the `af-is-error` class to indicate validation errors: ```   Email    
  Please enter a valid email address 
 
 ``` ## Required fields [Section titled “Required fields”](#required-fields) Indicate required fields clearly: ```   Name  *     
 
 ``` ## Help text [Section titled “Help text”](#help-text) Provide helpful guidance to users: ```   Password    
  Must be at least 8 characters with a mix of letters and numbers 
 
 ``` ## Live example [Section titled “Live example”](#live-example) Email \*  Please enter a valid email address Password Must be at least 8 characters with a mix of letters and numbers ## Accessibility [Section titled “Accessibility”](#accessibility) ### Best practices [Section titled “Best practices”](#best-practices) * **Always use `` elements** with `for` attributes (or wrap inputs in labels) * **Associate error messages** with inputs using `aria-describedby` (required) * **Use `aria-invalid="true"`** for error states (works with `af-is-error` class) * **Group related fields** with `` and `` * **Provide help text** for complex inputs using `af-field__help` * **Use proper input types** (`email`, `password`, `tel`, `url`, etc.) for better mobile keyboards and validation * **Indicate required fields** clearly (visually and with `required` attribute) * **Use `aria-label` or `aria-labelledby`** for inputs without visible labels when necessary ### Keyboard navigation [Section titled “Keyboard navigation”](#keyboard-navigation) All form controls support standard keyboard navigation: * `Tab` - Move to next field * `Shift+Tab` - Move to previous field * `Enter` - Submit form (when in submit button) * `Space` - Toggle checkboxes/radios/switches * Arrow keys - Navigate select options and radio groups ### Screen reader support [Section titled “Screen reader support”](#screen-reader-support) * Labels are properly associated with inputs * Error messages are linked via `aria-describedby` and read when the input is focused * Required fields are indicated * Field groups use semantic `` and ``

# Foundations

Foundation patterns provide the base styling for typography, lists, images, links, and dividers. ## Patterns [Section titled “Patterns”](#patterns) * **[Divider](/docs/patterns/foundations/divider)**: styled `` element * **[Images](/docs/patterns/foundations/images)**: responsive images + figure defaults * **[Links](/docs/patterns/foundations/links)**: link defaults * **[Lists](/docs/patterns/foundations/lists)**: list defaults + `.af-list` * **[Section & Surface](/docs/patterns/foundations/section-surface)**: structural containers for spacing and backgrounds * **[Typography](/docs/utilities/typography)**: semantic headings, text roles, blockquote

# Divider

> Horizontal rule for separating content sections

Airframe styles the native `
` element directly. No class needed. ## Usage [Section titled “Usage”](#usage) ```  Content above 
 
  Content below 
 ``` ## Preview [Section titled “Preview”](#preview) Content above the divider *** Content below the divider ## Default spacing [Section titled “Default spacing”](#default-spacing) The `
` element uses the `--af-divider-spacing` token, which defaults to `var(--af-space-5)`. Override it globally to change the default gap across your project: ``` :root { --af-divider-spacing: var(--af-space-3); } ``` ## Adjusting individual dividers [Section titled “Adjusting individual dividers”](#adjusting-individual-dividers) Use margin utilities to override spacing on a per-element basis: ```  
  
  
  
 ``` ### Tight (`af-my-xs`) [Section titled “Tight (af-my-xs)”](#tight-af-my-xs) Section one *** Section two ### Default (no class) [Section titled “Default (no class)”](#default-no-class) Section one *** Section two ### Wide (`af-my-xl`) [Section titled “Wide (af-my-xl)”](#wide-af-my-xl) Section one *** Section two ### None (`af-my-0`) [Section titled “None (af-my-0)”](#none-af-my-0) Section one *** Section two ## On primary background [Section titled “On primary background”](#on-primary-background) Use `af-divider-on-primary` for dividers inside hero/CTA sections on primary background: ```  ``` ## CSS reference [Section titled “CSS reference”](#css-reference) ``` hr { border: none; border-top: 1px solid var(--af-color-border); margin: var(--af-divider-spacing, var(--af-space-5)) 0; } .af-divider-on-primary { border-top-color: color-mix(in srgb, var(--af-color-on-primary) 15%, transparent); } ``` ## Related [Section titled “Related”](#related) * [Spacing utilities](/docs/utilities/spacing) * [Tokens](/docs/tokens)

# Images

> Responsive images and figure defaults

## Responsive image [Section titled “Responsive image”](#responsive-image) Images are responsive by default: ```  ``` ## Figure with caption [Section titled “Figure with caption”](#figure-with-caption) ```    This is a figure caption 
  ``` ## Live example [Section titled “Live example”](#live-example) ### Responsive Image ![Placeholder image](https://via.placeholder.com/800x400) ### Figure with Caption ![Figure image](https://via.placeholder.com/600x300) This is a figure caption

# Links

> Link defaults

## Basic link [Section titled “Basic link”](#basic-link) ```  Default link  ``` ## Live example [Section titled “Live example”](#live-example) [Default link](#)[Hover me to see the link style](#)

# Lists

> List defaults and the af-list styling helper

Lists are **unstyled by default** to give you full control. Use the `.af-list` class to apply styling (bullets, numbers, spacing). ## Unordered list [Section titled “Unordered list”](#unordered-list) ```    First item 
  Second item 
  Third item 
 
    First item 
  Second item 
  Third item 
 
 ``` ## Ordered list [Section titled “Ordered list”](#ordered-list) ```    First step 
  Second step 
  Third step 
 
    First step 
  Second step 
  Third step 
 
 ``` ## Definition list [Section titled “Definition list”](#definition-list) ```    Term 1 
  Definition for term 1 
  Term 2 
  Definition for term 2 
 
    Term 1 
  Definition for term 1 
  Term 2 
  Definition for term 2 
  ``` ## Live example [Section titled “Live example”](#live-example) ### Unstyled Lists (Default) **Unordered:** * First item * Second item * Third item **Ordered:** 1. First step 2. Second step 3. Third step **Definition:** * Term 1 Definition for term 1 * Term 2 Definition for term 2 ### Styled Lists (with .af-list) **Unordered:** * First item * Second item * Third item **Ordered:** 1. First step 2. Second step 3. Third step **Definition:** * Term 1 Definition for term 1 * Term 2 Definition for term 2 ## Why unstyled by default? [Section titled “Why unstyled by default?”](#why-unstyled-by-default) Lists are often used in navigation, menus, and other UI patterns where you don’t want default bullets or numbers. By making lists unstyled by default, you have full control: * Navigation menus (`.af-navbar-nav`, `.af-menu-list`) work without needing to override styles * Custom list layouts are easier to build * When you need traditional list styling, just add `.af-list`

# Section & Surface

> Structural containers for spacing and background styling

## Section [Section titled “Section”](#section) Semantic section containers with vertical spacing. Use `` elements to divide page content into logical blocks. | Class | Spacing | | --------------- | ------------------- | | `af-section-sm` | `var(--af-space-4)` | | `af-section` | `var(--af-space-6)` | | `af-section-lg` | `var(--af-space-8)` | Code Live ```   Default Section 
  Standard vertical spacing. 
 
   Small Section 
  Compact vertical spacing. 
 
   Large Section 
  Generous vertical spacing. 
 
 ``` ### Default Section Standard vertical spacing (space-6). ### Small Section Compact vertical spacing (space-4). ### Large Section Generous vertical spacing (space-8). Section only sets `padding-block`. Add your own inline padding, background, or border as needed. ## Surface [Section titled “Surface”](#surface) A container with background color and border. No padding or shadow by default - add those with utility classes. | Class | Background | | ---------------------------- | ------------------------------ | | `af-surface` | `--af-color-surface-primary` | | `af-surface af-is-secondary` | `--af-color-surface-secondary` | | `af-surface af-is-tertiary` | `--af-color-surface-tertiary` | Code Live ```  Primary surface 
  Secondary surface 
  Tertiary surface  ``` Primary surface Secondary surface Tertiary surface ### Surface vs Card [Section titled “Surface vs Card”](#surface-vs-card) * **Surface** (`af-surface`) - Minimal container. No padding or shadow. Use for panels, backgrounds, or when you need full control. * **Card** (`af-card`) - Full component with built-in padding, shadow, and semantic parts. Use for structured content blocks. ## CSS reference [Section titled “CSS reference”](#css-reference) ``` /* Section */ .af-section { padding-block: var(--af-space-6); } .af-section-sm { padding-block: var(--af-space-4); } .af-section-lg { padding-block: var(--af-space-8); } /_ Surface _/ .af-surface { background: var(--af-color-surface-primary); border: var(--af-border-width) solid var(--af-color-border); border-radius: var(--af-radius-md); } .af-surface.af-is-secondary { background: var(--af-color-surface-secondary); } .af-surface.af-is-tertiary { background: var(--af-color-surface-tertiary); } ``` ## Related [Section titled “Related”](#related) * [Layouts](/docs/layouts) - Grid, stack, and layout recipes * [Cards](/docs/patterns/content/card) - Structured content containers

# Misc

Utility patterns and helpers for tooltips and print styles. ## Patterns [Section titled “Patterns”](#patterns) * **[Print styles](/docs/patterns/misc/print-styles)**: `af-no-print`, `af-print-only`, `af-page-break*` * **[Tooltip](/docs/patterns/misc/tooltip)**: `af-tooltip`, `aria-label` ## See also [Section titled “See also”](#see-also) * **[Screen reader utilities](/docs/accessibility/screen-readers)**: `af-sr-only`, `af-sr-only-focusable`

# Print Styles

> Print-only utilities and helpers

Utility classes for controlling print behavior. These classes only apply when printing (using `@media print`). ## Hide elements [Section titled “Hide elements”](#hide-elements) Hide elements when printing: ```  This content won't print 
 ``` ## Show only when printing [Section titled “Show only when printing”](#show-only-when-printing) Show elements only when printing (hidden on screen): ```  This only appears when printing 
 ``` ## Page breaks [Section titled “Page breaks”](#page-breaks) Force a page break after an element: ```  Content after this will start on a new page 
 ``` Prevent content from breaking across pages: ```  This block won't break across pages 
 ``` ## Link styling [Section titled “Link styling”](#link-styling) Links automatically show their URLs when printing: ```  Visit Example   ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-no-print` - Hide element when printing * `af-print-only` - Show element only when printing (hidden on screen) * `af-page-break` - Force page break after element * `af-page-break-avoid` - Prevent page break inside element ## Live example [Section titled “Live example”](#live-example) **This content won’t print** (has af-no-print class) This content will print normally. Use `af-no-print` to hide elements when printing. Use `af-page-break` to force a page break. Use `af-page-break-avoid` to prevent breaking inside an element. **This block won’t break across pages** (af-page-break-avoid) All content in this block stays together when printing. Note: Print styles only apply when printing. Use browser’s Print Preview to see the effect.

# Tooltip

> CSS-only tooltips using aria-label

One class, one attribute: add `class="af-tooltip"` and `aria-label="tooltip text"`. The visual tooltip uses the same text as the element’s accessible name, so screen readers and keyboard users get the same content. The tooltip appears on **hover and focus**. ## Markup [Section titled “Markup”](#markup) Code Live ```    ``` Save × ## Placement [Section titled “Placement”](#placement) Add a side modifier so the tooltip appears on the chosen side of the trigger. Default is **top**; no modifier needed. The bubble has `max-width: var(--af-tooltip-width, 25ch)` and text wraps. * **`.af-tooltip-top`** – above (default) * **`.af-tooltip-right`** – to the right * **`.af-tooltip-bottom`** – below * **`.af-tooltip-left`** – to the left ### Top (default) [Section titled “Top (default)”](#top-default) Code Live ```  ``` Hover me ### Right [Section titled “Right”](#right) Code Live ```  ``` Hover me ### Bottom [Section titled “Bottom”](#bottom) Code Live ```  ``` Hover me ### Left [Section titled “Left”](#left) Code Live ```  ``` Hover me ## Overriding tooltip width [Section titled “Overriding tooltip width”](#overriding-tooltip-width) The tooltip bubble’s max width is controlled by the CSS variable **`--af-tooltip-width`** (default `25ch`). Override it on `:root` for all tooltips, or on the trigger (or a wrapper) for a single tooltip. **Global override:** ``` :root { --af-tooltip-width: 35ch; } ``` **Per tooltip (inline or class):** Code Live ```  ``` Wider tooltip (35ch) ## On any element [Section titled “On any element”](#on-any-element) The trigger can be a `div`, `span`, or any focusable element. Ensure it’s keyboard-focusable if you want the tooltip on focus (e.g. add `tabindex="0"` for non-interactive elements). Code Live ```  Hover or focus  ``` Hover or focus ## Accessibility summary [Section titled “Accessibility summary”](#accessibility-summary) | Need | Approach | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Keyboard users see tooltip | ✅ Tooltip shows on `:focus` / `:focus-visible` (same as hover). | | Screen reader gets tooltip text | ✅ Same text from `aria-label` (element’s accessible name). | | Dismissible (e.g. Escape) | Not supported with pure CSS; use a JavaScript tooltip if you need WCAG 1.4.13 (Content on Hover or Focus) fully. |

# Navigation

Navigation patterns for building site navigation, breadcrumbs, and pagination. ## Patterns [Section titled “Patterns”](#patterns) * **[Breadcrumbs](/docs/patterns/navigation/breadcrumbs)**: `af-breadcrumbs-*` * **[Dropdown Menu](/docs/patterns/navigation/dropdown-menu)**: `.af-dropdown-menu` * **[Menu List](/docs/patterns/navigation/menu-list)**: `af-menu-*` * **[Nav Collapse](/docs/patterns/navigation/nav-collapse)**: `.af-nav-collapse` * **[Navbar](/docs/patterns/navigation/navbar)**: `af-navbar`, `af-navbar-*` * **[Pagination](/docs/patterns/navigation/pagination)**: `af-pagination-*` * **[Side Navigation](/docs/patterns/navigation/side-navigation)**: `af-side-nav-*` * **[Table of Contents](/docs/patterns/navigation/table-of-contents)**: `af-toc`

# Breadcrumbs

> Breadcrumb navigation for showing the current page location

Breadcrumb navigation for showing the current page location. ## Markup [Section titled “Markup”](#markup) ```     Home  
   Category  
  Current Page 
 
  ``` ## Live example [Section titled “Live example”](#live-example) 1. [Home](#) 2. [Category](#) 3. Current Page

# Dropdown Menu

> Dropdown menus (Element or CSS-only)

Dropdown menu with keyboard navigation and ARIA management. ## Dropdown Menu [Section titled “Dropdown Menu”](#dropdown-menu) Use CSS classes with your own JavaScript for toggle behaviour. You manage ARIA attributes and keyboard navigation: ```      Item 1  
   Item 2  
   Item 3  
 
 
  ``` ### CSS classes [Section titled “CSS classes”](#css-classes) * `.af-dropdown-menu` - Dropdown menu container * `.af-dropdown-menu-open` - Show menu (alternative to removing `hidden`) * `[role="menu"]` - ARIA role for menu pattern ### Required ARIA [Section titled “Required ARIA”](#required-aria) * `role="menu"` on the `` element * `role="menuitem"` on each `` or `     Home  
   About  
   Contact

  ``` ### CSS classes [Section titled “CSS classes”](#css-classes) * `.af-nav-collapse` - Container for collapsible navigation * `.af-nav-collapse-open` - Show menu (alternative to removing `hidden`) ### Required ARIA [Section titled “Required ARIA”](#required-aria) * `aria-expanded` on trigger button (true/false) * `aria-controls` linking trigger to menu * `hidden` attribute to show/hide menu ### Features you must implement [Section titled “Features you must implement”](#features-you-must-implement) * Focus trapping when menu is open * Escape key to close * Return focus to trigger on close * Outside click to close (optional)

# Navbar

> Main navigation bar for site-wide navigation

Main navigation bar for site-wide navigation. ## Markup [Section titled “Markup”](#markup) ```   Brand     Home  
   About  
   Contact  
 
  ``` ## Live example [Section titled “Live example”](#live-example) [Brand](#) * [Home](#) * [About](#) * [Contact](#)

# Pagination

> Pagination controls for navigating through pages of content

Pagination controls for navigating through pages of content. ## Markup [Section titled “Markup”](#markup) ```     Previous  
   1  
   2  
   3  
   Next  
 
  ``` ## Live example [Section titled “Live example”](#live-example) * [Previous](#) * [1](#) * [2](#) * [3](#) * [Next](#)

# Side Navigation

> Side navigation menu for hierarchical navigation

Side navigation menu for hierarchical navigation. ## Markup [Section titled “Markup”](#markup) ```     Active Item  
   Item 2  
   Item 3  
 
  ``` ## Live example [Section titled “Live example”](#live-example) * [Active Item](#) * [Item 2](#) * [Item 3](#)

# Table of Contents

> Styled table of contents navigation pattern

Use the `af-toc` pattern to style **in-page navigation** (e.g. “On this page” lists, long-form docs, multi-section pages). ## Markup (recommended) [Section titled “Markup (recommended)”](#markup-recommended) Use semantic HTML: * `nav` with `aria-label` * an optional heading (`h2`/`h3`) for the TOC title * `ol`/`ul` for the list Code Live ```   Contents 
    Introduction  
   Getting started  
   Components     Buttons  
   Forms  
 
 
   Conclusion  
 
 
 ``` ## Contents 1. [Introduction](#introduction) 2. [Getting started](#getting-started) 3. [Components](#components) 1. [Buttons](#buttons) 2. [Forms](#forms) 4. [Conclusion](#conclusion) ## Active link state [Section titled “Active link state”](#active-link-state) If you can set `aria-current="page"` on the active anchor, the TOC will highlight it. Code Live ```   Contents 
    Introduction  
   Usage  
 
 
 ``` ## Contents 1. [Introduction](#intro) 2. [Usage](#usage) ## Automatic styling (no class) [Section titled “Automatic styling (no class)”](#automatic-styling-no-class) The pattern also styles semantic TOCs without the class when the nav’s label suggests “contents”: Code Live ```   Contents 
    Section A  
   Section B  
 
  ``` ## Contents 1. [Section A](#a) 2. [Section B](#b) ## Notes [Section titled “Notes”](#notes) * If you’re using the docs site, Starlight’s built-in TOC uses `nav[aria-label="Table of contents"]`, which this pattern can style without extra markup changes. * You can nest lists (`ol > li > ol`) for hierarchical pages.

# Overlays

Overlay patterns for modal dialogs, backdrops, and drawers. ## Patterns [Section titled “Patterns”](#patterns) * **[Backdrop](/docs/patterns/overlays/backdrop)**: `af-backdrop` * **[Dialog](/docs/patterns/overlays/dialog)**: `af-dialog`, `af-dialog-*` * **[Drawer](/docs/patterns/overlays/drawer)**: `af-drawer`, `af-drawer-*`

# Backdrop

> Full-screen overlay backdrop

Full-screen semi-transparent overlay. Useful for custom overlay scenarios outside of native ``. **Tip:** If you’re using `` with `showModal()`, you don’t need this class. The native `::backdrop` pseudo-element is styled automatically by Airframe. ## Usage [Section titled “Usage”](#usage) ```  
 ``` ## When to use [Section titled “When to use”](#when-to-use) * Custom modal implementations that don’t use `` * Overlay behind popovers, menus, or custom drawers * Loading overlays For standard modals and drawers, use the [Dialog](/docs/patterns/overlays/dialog) or [Drawer](/docs/patterns/overlays/drawer) patterns instead. They use native `` which handles the backdrop automatically. ## Preview [Section titled “Preview”](#preview) Content behind the backdrop Content above backdrop ## CSS reference [Section titled “CSS reference”](#css-reference) ``` .af-backdrop { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.5); backdrop-filter: blur(2px); z-index: 999; } ``` ## Related [Section titled “Related”](#related) * [Dialog](/docs/patterns/overlays/dialog) * [Drawer](/docs/patterns/overlays/drawer)

# Dialog

> Modal dialogs using the native HTML dialog element

Modal dialog using the **native HTML `` element**. No JavaScript dependencies required. ## Basic dialog [Section titled “Basic dialog”](#basic-dialog) ```    Confirm action 
  
   Are you sure you want to continue? This action cannot be undone. 
 
    
   ``` ## Preview [Section titled “Preview”](#preview) ## Why native ``? [Section titled “Why native \?”](#why-native-dialog) * **`showModal()`** marks the rest of the page as inert. * **ESC key** closes the dialog automatically. * **Body scroll lock** while the modal is open. * **`::backdrop`** pseudo-element. No extra markup for the overlay. **Note:** Native `` provides basic focus containment via page inertness, but focus trapping and focus restoration are not fully reliable across all browsers and screen readers. For production apps, supplement with a focus trap library (e.g. `focus-trap`). ## API [Section titled “API”](#api) Open with `showModal()`. Close with `close()`. ``` const dialog = document.getElementById('my-dialog'); dialog.showModal(); dialog.close(); if (dialog.open) {/* dialog is visible */} ``` ## Parts [Section titled “Parts”](#parts) | Class | Purpose | | ------------------ | ----------------------------------- | | `af-dialog` | The `` element itself | | `af-dialog-header` | Header row. Flexbox, space-between. | | `af-dialog-title` | Title text inside the header | | `af-dialog-body` | Main content area | | `af-dialog-footer` | Footer row. Flexbox, end-aligned. | ## Dialog with form [Section titled “Dialog with form”](#dialog-with-form) ```     Edit profile 
  
     Name   
   Email   
 
 
    
 
   ``` Using `` lets any submit button close the dialog automatically. ## Closing on backdrop click [Section titled “Closing on backdrop click”](#closing-on-backdrop-click) The native `` doesn’t close on backdrop click by default. Add this if you want it: ``` dialog.addEventListener('click', (e) => { if (e.target === dialog) dialog.close(); }); ``` ## Accessibility [Section titled “Accessibility”](#accessibility) * Use `` element. Not a `` with `role="dialog"`. * Provide a visible title via `af-dialog-title`. * Add `aria-label` or `aria-labelledby` if the title is not visible. * Close buttons need `aria-label="Close"`. ## Related [Section titled “Related”](#related) * [Drawer](/docs/patterns/overlays/drawer) * [Backdrop](/docs/patterns/overlays/backdrop)

# Drawer

> Side drawer panel using native dialog

Side panel using the **native HTML `` element**. Slides in from the left or right. ## Basic drawer [Section titled “Basic drawer”](#basic-drawer) ```    Navigation 
  
     Dashboard  
   Settings  
   Account  
 
 
   ``` ## Preview [Section titled “Preview”](#preview) ### Navigation × * [Dashboard](#) * [Settings](#) * [Account](#) ## Right-side drawer [Section titled “Right-side drawer”](#right-side-drawer) Add `af-drawer-right` to open from the right edge: ```    Filters 
  
     Status   
   Date range   
  
 
   ``` ## API [Section titled “API”](#api) Same as dialog. Open with `showModal()`, close with `close()`. ``` const drawer = document.getElementById('my-drawer'); drawer.showModal(); drawer.close(); ``` ## Parts [Section titled “Parts”](#parts) | Class | Purpose | | ------------------ | ------------------------------------------------------- | | `af-drawer` | The `` element. Opens from the left by default. | | `af-drawer-right` | Modifier. Opens from the right instead. | | `af-drawer-header` | Header row with title and close button | | `af-drawer-body` | Scrollable content area | ## Closing on backdrop click [Section titled “Closing on backdrop click”](#closing-on-backdrop-click) ``` drawer.addEventListener('click', (e) => { if (e.target === drawer) drawer.close(); }); ``` ## Accessibility [Section titled “Accessibility”](#accessibility) Same accessibility model as dialog. Native `` with `showModal()` marks the page as inert and provides ESC key and body scroll lock. Focus trapping and focus restoration require supplemental JS for full cross-browser reliability. ## Related [Section titled “Related”](#related) * [Dialog](/docs/patterns/overlays/dialog) * [Backdrop](/docs/patterns/overlays/backdrop)

# Patterns Overview

> Complete list of all CSS patterns available in Airframe

Airframe includes **70+ CSS patterns** organized into 8 categories. This page provides a quick reference to all available patterns. ## Foundations [Section titled “Foundations”](#foundations) Base styling patterns for content and layout primitives. * **[Divider](/docs/patterns/foundations/divider)** - Styled `
` element * **[Images](/docs/patterns/foundations/images)** - Responsive images and figure defaults * **[Links](/docs/patterns/foundations/links)** - Link defaults * **[Lists](/docs/patterns/foundations/lists)** - List defaults and `.af-list` * **[Section & Surface](/docs/patterns/foundations/section-surface)** - Structural containers for spacing and backgrounds * **[Typography](/docs/utilities/typography)** - Semantic headings, text roles, blockquote ## Buttons, Badges & Status [Section titled “Buttons, Badges & Status”](#buttons-badges--status) Interactive elements for user actions and status indicators. * **[Button](/docs/patterns/button/button)** - Primary button pattern with variants and states * **[Button Group](/docs/patterns/button/button-group)** - Grouped buttons with connected styling * **[Icon Button](/docs/patterns/button/icon-button)** - Icon-only buttons * **[Link Button](/docs/patterns/button/link-button)** - Links styled as buttons * **[Avatar](/docs/patterns/badges-chips/avatar)** - User profile images * **[Badge](/docs/patterns/badges-chips/badge)** - Small status indicators * **[Chip](/docs/patterns/badges-chips/chip)** - Tags, filters, and removable items * **[Icon Box](/docs/patterns/badges-chips/icon-box)** - Icon container for feature cards * **[Pill](/docs/patterns/badges-chips/pill)** - Compact labeled chips for tags and meta * **[Skeleton](/docs/patterns/badges-chips/skeleton)** - Content placeholders * **[Spinner](/docs/patterns/badges-chips/spinner)** - Loading indicators ## Forms [Section titled “Forms”](#forms) Complete form patterns for building accessible, user-friendly forms. * **[Checkbox](/docs/patterns/forms/checkbox)** - Checkbox inputs * **[Classless Form](/docs/patterns/forms/classless-form)** - Automatic styling with `form.af-form` * **[Field](/docs/patterns/forms/field)** - Form field structure with labels and help text * **[File Input](/docs/patterns/forms/file-input)** - File upload inputs * **[Form Layout](/docs/patterns/forms/form-layout)** - Form structure and spacing * **[Input](/docs/patterns/forms/input)** - Text inputs (text, email, password, etc.) * **[Input Group](/docs/patterns/forms/input-group)** - Grouped form controls * **[Label](/docs/patterns/forms/label)** - Styled labels (semantic-first) * **[Radio](/docs/patterns/forms/radio)** - Radio button groups * **[Range](/docs/patterns/forms/range)** - Slider inputs * **[Select](/docs/patterns/forms/select)** - Dropdown selects * **[Switch](/docs/patterns/forms/switch)** - Toggle switches * **[Textarea](/docs/patterns/forms/textarea)** - Multi-line text inputs * **[Validation & Error States](/docs/patterns/forms/validation)** - Errors, help text, required fields ## Navigation [Section titled “Navigation”](#navigation) Navigation patterns for site navigation, tabs, breadcrumbs, and pagination. * **[Breadcrumbs](/docs/patterns/navigation/breadcrumbs)** - Breadcrumb navigation * **[Dropdown Menu](/docs/patterns/navigation/dropdown-menu)** - Dropdown menus * **[Menu List](/docs/patterns/navigation/menu-list)** - Menu and list navigation * **[Nav Collapse](/docs/patterns/navigation/nav-collapse)** - Collapsible navigation sections * **[Navbar](/docs/patterns/navigation/navbar)** - Main navigation bar * **[Pagination](/docs/patterns/navigation/pagination)** - Page navigation controls * **[Side Navigation](/docs/patterns/navigation/side-navigation)** - Sidebar navigation * **[Table of Contents](/docs/patterns/navigation/table-of-contents)** - In-page navigation for long-form content ## Content & Messaging [Section titled “Content & Messaging”](#content--messaging) Patterns for displaying content, messages, and status information. * **[Alert](/docs/patterns/content/alert)** - Alert messages * **[Banner](/docs/patterns/content/banner)** - Site-wide banner messages * **[Callout](/docs/patterns/content/callout)** - Subtle alert variant * **[Card](/docs/patterns/content/card)** - Card layouts and variants * **[Empty State](/docs/patterns/content/empty-state)** - Empty state displays * **[KPI](/docs/patterns/content/kpi)** - Key Performance Indicator displays * **[Meter](/docs/patterns/content/meter)** - Meter elements for measurements * **[Progress](/docs/patterns/content/progress)** - Progress bars * **[Toast](/docs/patterns/content/toast)** - Toast notifications ## Data Display [Section titled “Data Display”](#data-display) Patterns for displaying structured data and information. * **[Accordion](/docs/patterns/data-display/accordion)** - Collapsible content sections * **[Code Block](/docs/patterns/data-display/code-block)** - Code snippet displays * **[Description List](/docs/patterns/data-display/description-list)** - Key-value pairs * **[List Group](/docs/patterns/data-display/list-group)** - Selectable list items * **[Steps](/docs/patterns/data-display/steps)** - Multi-step progress trackers * **[Table](/docs/patterns/data-display/table)** - Tables for tabular data * **[Timeline](/docs/patterns/data-display/timeline)** - Chronological event displays ## Overlays [Section titled “Overlays”](#overlays) Overlay patterns for modal dialogs, backdrops, and drawers. * **[Backdrop](/docs/patterns/overlays/backdrop)** - Full-screen overlay backdrop * **[Dialog](/docs/patterns/overlays/dialog)** - Modal dialogs using native `` element * **[Drawer](/docs/patterns/overlays/drawer)** - Side drawer panels ## Media & Misc [Section titled “Media & Misc”](#media--misc) Utility patterns and helpers. * **[Print Styles](/docs/patterns/misc/print-styles)** - Print-specific styles and utilities * **[Tooltip](/docs/patterns/misc/tooltip)** - CSS-only tooltips ## Quick Links [Section titled “Quick Links”](#quick-links) Browse detailed documentation for each category: * [Badges & Chips](/docs/patterns/badges-chips) - Status indicators and tags * [Buttons](/docs/patterns/button) - Button patterns and variants * [Content & Messaging](/docs/patterns/content) - Cards, alerts, callouts, and more * [Data Display](/docs/patterns/data-display) - Tables, lists, and data components * [Forms](/docs/patterns/forms) - Complete form patterns * [Foundations](/docs/patterns/foundations) - Typography, lists, images, links, dividers * [Misc](/docs/patterns/misc) - Tooltips, print styles, and utilities * [Navigation](/docs/patterns/navigation) - Navigation components * [Overlays](/docs/patterns/overlays) - Dialogs, drawers, and modals ## Getting Started [Section titled “Getting Started”](#getting-started) All patterns are available when you import the core CSS: ``` @import "@airframeui/core/core.css"; ``` Each pattern uses semantic class names with the `af-` prefix. For example: * `af-btn` for buttons * `af-card` for cards * `af-input` for inputs * `af-table` for tables See the [Usage](/docs/usage) guide for more information on getting started with Airframe patterns.

# Accessibility

## WCAG 2.2 A/AA Compliance Promise [Section titled “WCAG 2.2 A/AA Compliance Promise”](#wcag-22-aaa-compliance-promise) **Airframe is built to meet WCAG 2.2 Level A & AA for default styles and Airframe patterns when used as documented.** Final compliance depends on product content and implementation choices (copy, structure, alt text, validation messaging, etc.). ## Built-In Accessibility [Section titled “Built-In Accessibility”](#built-in-accessibility) Airframe follows a **semantic-first, CSS-only where possible** approach that prevents common accessibility failures. ### Semantic-First Defaults [Section titled “Semantic-First Defaults”](#semantic-first-defaults) Airframe ships base styles that assume semantic HTML: * Headings are headings (`h1`-`h6`) * Buttons are `
` }) export class UserTableComponent { users = input<{ id: number; name: string; email: string; role: string }[]>([]); } ``` ## Theming [Section titled “Theming”](#theming) ### Custom tokens [Section titled “Custom tokens”](#custom-tokens) Override tokens in your `styles.scss`. No rebuild needed. ``` /* src/styles.scss */ @import "@airframeui/core/core.css"; :root { --af-base-primary: #0066cc; --af-font-body: 'Inter', sans-serif; --af-radius-md: 0.5rem; } ``` ### Dark mode [Section titled “Dark mode”](#dark-mode) Dark mode follows system preference by default. Override per-element or globally: ```     Dark card on a light page 
 ``` Available themes: `light`, `dark`, `high-contrast-light`, `high-contrast-dark` ### Dynamic theme switching [Section titled “Dynamic theme switching”](#dynamic-theme-switching) ``` @Component({ selector: 'app-theme-toggle', standalone: true, template: ` ` }) export class ThemeToggleComponent { isDark = false; toggleTheme(): void { this.isDark = !this.isDark; document.documentElement.setAttribute( 'data-theme', this.isDark ? 'dark' : 'light' ); } } ``` ## View Encapsulation [Section titled “View Encapsulation”](#view-encapsulation) Airframe classes work with Angular’s default view encapsulation. If you need to style Airframe elements from a parent component, use `:host` or set encapsulation to `None`: ``` @Component({ selector: 'app-custom', standalone: true, encapsulation: ViewEncapsulation.None, styles: ` .my-custom-card { --af-card-padding: var(--af-space-6); --af-card-radius: var(--af-radius-lg); } `, template: `   Custom Card 
 ` }) export class CustomComponent {} ``` ## SSR (Angular Universal) [Section titled “SSR (Angular Universal)”](#ssr-angular-universal) Airframe CSS works with Angular SSR out of the box. No special configuration needed. The CSS is loaded via `angular.json` styles array, which works in both client and server builds. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### CSS not loading [Section titled “CSS not loading”](#css-not-loading) * Check that `@airframeui/core/core.css` is in the `styles` array in `angular.json` * Or check that `src/styles.scss` imports it and is itself in the `styles` array ### Styles not applying [Section titled “Styles not applying”](#styles-not-applying) 1. Use `class` not `className` (Angular uses `class`) 2. Check that no conflicting CSS is overriding Airframe styles 3. If view encapsulation is blocking styles, override tokens via CSS variables instead of targeting Airframe class internals ### Build errors [Section titled “Build errors”](#build-errors) * Angular 17+ required * Node 20+ required by the Angular CLI toolchain (Airframe CSS itself has no Node runtime requirement) * Run `npm install` to ensure `@airframeui/core` is installed ## Next Steps [Section titled “Next Steps”](#next-steps) * [Patterns](/docs/patterns/button) - See all available patterns * [Tokens](/docs/tokens) - Customise your theme * [Layouts](/docs/layouts) - Structural primitives * [Accessibility](/docs/accessibility) - Built-in accessibility

# Grid

CSS Grid layout for creating responsive grids with equal-width columns or asymmetric layouts. ## Grid [Section titled “Grid”](#grid) ### Class Reference [Section titled “Class Reference”](#class-reference) | Class | Purpose | Columns | Example | | ------------ | --------------------------------- | ------------------ | -------------------------- | | `af-grid` | Auto-adjusting grid (recommended) | Auto-fit (default) | `` | | `af-grid-1` | 1 equal column (explicit) | 1 | `` | | `af-grid-2` | 2 equal columns (explicit) | 2 | `` | | `af-grid-3` | 3 equal columns (explicit) | 3 | `` | | `af-grid-4` | 4 equal columns (explicit) | 4 | `` | | `af-grid-5` | 5 equal columns (explicit) | 5 | `` | | `af-grid-6` | 6 equal columns (explicit) | 6 | `` | | `af-grid-7` | 7 equal columns (explicit) | 7 | `` | | `af-grid-8` | 8 equal columns (explicit) | 8 | `` | | `af-grid-9` | 9 equal columns (explicit) | 9 | `` | | `af-grid-10` | 10 equal columns (explicit) | 10 | `` | | `af-grid-11` | 11 equal columns (explicit) | 11 | `` | | `af-grid-12` | 12 equal columns (explicit) | 12 | `` | ### Equal Columns [Section titled “Equal Columns”](#equal-columns) For equal-width columns, use `af-grid-1` through `af-grid-12`: ```    Item 1 
  Item 2 
 
    Item 1 
  Item 2 
  Item 3 
 
 ``` ### Responsive Grid [Section titled “Responsive Grid”](#responsive-grid) All grid classes support responsive variants. Use responsive suffixes for breakpoint-specific columns: ```    Item 1 
  Item 2 
  Item 3 
  Item 4 
  Item 5 
  Item 6 
 
    Item 1 
  Item 2 
  Item 3 
  Item 4 
 
 ``` **Available responsive variants:** All `af-grid-1` through `af-grid-12` support `@xs`, `@sm`, `@md`, `@lg`, `@xl`, and `@2xl` suffixes. Use `af-grid` as the default auto-fit grid. **Tip:** New to the `@{bp}` syntax? See [Responsive Suffix](/docs/responsive-suffix) for breakpoints, patterns, and best practices. ### Gap Override [Section titled “Gap Override”](#gap-override) Use `af-gap-sm`, `af-gap-lg`, etc. to override the default `gap-md`: ```  Large gap between columns 
  Extra large gap 
 ``` **Note:** `af-grid-1` through `af-grid-12` are standalone classes that include `display: grid` and `gap-md` automatically. You don’t need to combine them with `af-grid`. ### Live Examples [Section titled “Live Examples”](#live-examples) Auto-adjusting: 2 children = 2 columns 50% 50% Auto-adjusting: 3 children = 3 columns 33% 33% 33% Explicit: 6 columns 1 2 3 4 5 6 ## 12-Column Grid [Section titled “12-Column Grid”](#12-column-grid) For asymmetric layouts, use `af-grid` with `af-col-span-*` classes. ### Class Reference [Section titled “Class Reference”](#class-reference-1) | Class | Purpose | Usage | | ---------------------------------------- | ------------------- | ------------------------------ | | `af-col-span-1` through `af-col-span-12` | Column spans (1-12) | Use inside `af-grid` container | ### Basic 12-Column Grid [Section titled “Basic 12-Column Grid”](#basic-12-column-grid) ```   Main content (8/12) 
  Sidebar (4/12) 
 
 ``` **Mobile-first default:** Items in a 12-column grid automatically default to full width (12 columns) on mobile. You only need to specify responsive spans for larger screens. ### Mobile-First Pattern [Section titled “Mobile-First Pattern”](#mobile-first-pattern) The pattern `af-col-span-8@lg` means: * **Mobile (default):** Full width (12 columns) - automatic * **Large screens and up:** 8 columns (two-thirds width) **Note:** The base `af-col-span-12` class exists for completeness but isn’t needed - full width is the automatic default. However, responsive variants like `af-col-span-12@md` are available if you need to explicitly set full width at a specific breakpoint (e.g., `af-col-span-6 af-col-span-12@md` for “half width on mobile, full width on medium+”). ### Column Spans Reference [Section titled “Column Spans Reference”](#column-spans-reference) | Class | Spans | Example | Use Case | | ---------------- | ----------------------- | ------------------------------ | ------------------------------------------------ | | `af-col-span-1` | 1 column | `` | Narrow column | | `af-col-span-2` | 2 columns | `` | Small column | | `af-col-span-3` | 3 columns | `` | Quarter width | | `af-col-span-4` | 4 columns | `` | One-third width | | `af-col-span-5` | 5 columns | `` | Custom width | | `af-col-span-6` | 6 columns (half width) | `` | Half width | | `af-col-span-7` | 7 columns | `` | Custom width | | `af-col-span-8` | 8 columns (two-thirds) | `` | Two-thirds width | | `af-col-span-9` | 9 columns | `` | Three-quarters width | | `af-col-span-10` | 10 columns | `` | Custom width | | `af-col-span-11` | 11 columns | `` | Custom width | | `af-col-span-12` | 12 columns (full width) | `` | **Full width (exists but not needed - default)** | **Note:** Full width (12 columns) is the default - no class needed. The `af-col-span-12` class exists for completeness but isn’t recommended. For explicit full width at breakpoints, use responsive variants: `af-col-span-12@md`, `af-col-span-12@lg`, etc. **Responsive:** All spans support responsive suffixes: `af-col-span-6@md`, `af-col-span-8@lg`, `af-col-span-12@md`, etc. Items default to full width on mobile, so you only need responsive classes for larger screens. ### Live Example (12-Column) [Section titled “Live Example (12-Column)”](#live-example-12-column) Main content (8 columns on large screens) Sidebar (4 columns on large screens)

# Next.js Setup Guide

Airframe works seamlessly with Next.js in both App Router and Pages Router. ## Quick Start [Section titled “Quick Start”](#quick-start) ### 1. Install [Section titled “1. Install”](#1-install) ``` npm install @airframeui/core # or pnpm add @airframeui/core ``` ### 2. Import CSS [Section titled “2. Import CSS”](#2-import-css) #### App Router (app directory) [Section titled “App Router (app directory)”](#app-router-app-directory) Create or update `app/globals.css`: ``` @import "@airframeui/core/core.css"; ``` Then import it in `app/layout.tsx`: ``` import './globals.css' export default function RootLayout({ children, }: { children: React.ReactNode }) { return (  {children}  ) } ``` #### Pages Router (pages directory) [Section titled “Pages Router (pages directory)”](#pages-router-pages-directory) Create or update `styles/globals.css`: ``` @import "@airframeui/core/core.css"; ``` Then import it in `pages/_app.tsx`: ``` import '../styles/globals.css' import type { AppProps } from 'next/app' export default function App({ Component, pageProps }: AppProps) { return  } ``` ### 3. Use Patterns [Section titled “3. Use Patterns”](#3-use-patterns) Now you can use Airframe classes anywhere: ``` // app/page.tsx (App Router) or pages/index.tsx (Pages Router) export default function Home() { return (   Welcome
  
 
 ) } ``` ## App Router Examples [Section titled “App Router Examples”](#app-router-examples) ### Basic Page [Section titled “Basic Page”](#basic-page) ``` // app/dashboard/page.tsx export default function Dashboard() { return (    Dashboard
  
    Main Content
 Content goes here
 
 
   Sidebar
 Sidebar content
 
 
 
 
 
 ) } ``` ### Server Component with Forms [Section titled “Server Component with Forms”](#server-component-with-forms) ``` // app/contact/page.tsx export default function Contact() { return (      Name   
   Email   
   Message   </div> <button type="submit" className="af-btn"> Send Message </button> </form> </div> </div> ) } ``` ### Client Component [Section titled “Client Component”](#client-component) ``` // app/components/Counter.tsx 'use client' import { useState } from 'react'; export function Counter() { const [count, setCount] = useState(0) return ( <div className="af-card af-stack"> <h2 className="af-card__title">Counter</h2> <div className="af-card__body"> <p className="af-title">{count}</p> <div className="af-inline af-gap-sm"> <button className="af-btn" onClick={() => setCount(count - 1)} > Decrease </button> <button className="af-btn" onClick={() => setCount(count + 1)}> Increase </button> </div> </div> </div> ) } ``` ## Pages Router Examples [Section titled “Pages Router Examples”](#pages-router-examples) ### Basic Page [Section titled “Basic Page”](#basic-page-1) ``` // pages/index.tsx export default function Home() { return ( <div className="af-container"> <div className="af-stack af-gap-lg"> <h1 className="af-title">Welcome</h1> <button className="af-btn">Get Started</button> </div> </div> ) } ``` ### Page with Layout [Section titled “Page with Layout”](#page-with-layout) ``` // pages/about.tsx import Layout from '../components/Layout' export default function About() { return ( <Layout> <div className="af-container"> <div className="af-stack af-gap-lg"> <h1 className="af-title">About Us</h1> <div className="af-card"> <p className="af-card__body"> Content goes here </p> </div> </div> </div> </Layout> ) } ``` ## Theming [Section titled “Theming”](#theming) ### Dark Mode [Section titled “Dark Mode”](#dark-mode) Dark mode follows system preference by default. To override the system preference, set dark mode on the root element using one of these methods: * **`data-theme` attribute**: Standard data attribute * **`.dark` class**: CSS class ``` // app/layout.tsx export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( // Using data-theme attribute <html lang="en" data-theme="dark"> <body>{children}</body> </html> ) } // Or using .dark class export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( <html lang="en" class="dark"> <body>{children}</body> </html> ) } // Or using .dark class export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( <html lang="en" className="dark"> <body>{children}</body> </html> ) } ``` ### Custom Theme [Section titled “Custom Theme”](#custom-theme) Override tokens in your CSS: ``` /* app/globals.css */ @import "@airframeui/core/core.css"; :root { --af-base-primary: #0066cc; --af-hover-mix: 12%; } ``` ## TypeScript Support [Section titled “TypeScript Support”](#typescript-support) TypeScript support is included. No additional types needed. ## Server Components [Section titled “Server Components”](#server-components) Airframe is CSS-only, so it works perfectly with Next.js Server Components: ``` // app/products/page.tsx export default async function Products() { const products = await fetchProducts() return ( <div className="af-container"> <div className="af-cols-12"> {products.map(product => ( <div key={product.id} className="af-col-span-6@md af-col-span-4@lg"> <div className="af-card"> <h2 className="af-card__title">{product.name}</h2> <p className="af-card__body">{product.description}</p> </div> </div> ))} </div> </div> ) } ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### CSS Not Loading [Section titled “CSS Not Loading”](#css-not-loading) Make sure you’re importing the CSS in the correct file: * **App Router**: `app/globals.css` imported in `app/layout.tsx` * **Pages Router**: `styles/globals.css` imported in `pages/_app.tsx` ### Styles Not Applying [Section titled “Styles Not Applying”](#styles-not-applying) Check that: 1. CSS is imported correctly 2. Classes use `className` (not `class`) in JSX 3. No conflicting CSS is overriding styles ### Build Errors [Section titled “Build Errors”](#build-errors) If you see build errors, ensure: * Node version is 20+ (check `.nvmrc`) * All dependencies are installed * TypeScript is configured correctly ## Next Steps [Section titled “Next Steps”](#next-steps) * Explore [Patterns](/docs/patterns) - See all available patterns * Learn about [Tokens](/docs/tokens) - Customize your theme * Read [Layouts](/docs/layouts) - Layout patterns and recipes

# React Recipes

> Copy-paste ready React components using @airframeui

**Copy-paste ready React components using @airframeui.** You own the code, we provide the styling. ## Card Component [Section titled “Card Component”](#card-component) ``` import { clsx } from 'clsx'; interface CardProps { title?: string; actions?: React.ReactNode; children: React.ReactNode; className?: string; variant?: 'default' | 'elevated'; } export function Card({ title, actions, children, className, variant = 'default' }: CardProps) { return ( <section className={clsx('af-card', variant === 'elevated' && 'af-is-elevated', className)}> {title && ( <header className="af-card__header"> <h2 className="af-card__title">{title}</h2> {actions && <div className="af-card__actions">{actions}</div>} </header> )} <div className="af-card__body">{children}</div> </section> ); } ``` ## Button Component [Section titled “Button Component”](#button-component) ``` import { clsx } from 'clsx'; interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'; size?: 'sm' | 'md' | 'lg'; loading?: boolean; } export function Button({ variant = 'default', size = 'md', loading, className, disabled, children, ...props }: ButtonProps) { return ( <button className={clsx( 'af-btn', variant !== 'default' && `af-is-${variant}`, size !== 'md' && `af-is-${size}`, loading && 'af-is-loading', className )} disabled={disabled || loading} {...props} > {children} </button> ); } ``` ## Form Field Component [Section titled “Form Field Component”](#form-field-component) ``` import React from 'react'; import { clsx } from 'clsx'; interface FieldProps { id: string; // Required for accessibility - used for label 'for' and error aria-describedby label: string; hint?: string; error?: string; required?: boolean; children: React.ReactNode; className?: string; } export function Field({ id, label, hint, error, required, children, className }: FieldProps) { const errorId = `${id}-error`; return ( <div className={clsx('af-field', className)}> <label className="af-field__label" htmlFor={id}> {label} {required && <span aria-label="required">_</span>} </label> {/_ Clone children to add aria-describedby when error exists */} {error ? React.cloneElement(children as React.ReactElement, { id, 'aria-invalid': true, 'aria-describedby': errorId, className: clsx( (children as React.ReactElement).props?.className, 'af-is-error' ), }) : React.cloneElement(children as React.ReactElement, { id }) } {hint && <p className="af-field**hint" id={`${id}-hint`}>{hint}</p>} {error && ( <p className="af-field**error" id={errorId} > {error} </p> )} </div> ); } ``` ## Stack Layout Component [Section titled “Stack Layout Component”](#stack-layout-component) ``` import { clsx } from 'clsx'; interface StackProps { gap?: 'sm' | 'md' | 'lg'; responsive?: { sm?: 'stack' | 'inline'; md?: 'stack' | 'inline'; lg?: 'stack' | 'inline'; }; children: React.ReactNode; className?: string; } export function Stack({ gap = 'md', responsive, children, className }: StackProps) { const classes = clsx( 'af-stack', gap !== 'md' && `af-gap-${gap}`, responsive?.sm && `af-${responsive.sm}@sm`, responsive?.md && `af-${responsive.md}@md`, responsive?.lg && `af-${responsive.lg}@lg`, className ); return <div className={classes}>{children}</div>; } ``` ## Grid Layout Component [Section titled “Grid Layout Component”](#grid-layout-component) ``` import { clsx } from 'clsx'; interface GridProps { cols?: 1 | 2 | 3 | 4 | 5 | 6 | 12; gap?: 'sm' | 'md' | 'lg'; responsive?: { sm?: 1 | 2 | 3 | 4 | 5 | 6; md?: 1 | 2 | 3 | 4 | 5 | 6; lg?: 1 | 2 | 3 | 4 | 5 | 6; }; children: React.ReactNode; className?: string; } export function Grid({ cols = 1, gap = 'md', responsive, children, className }: GridProps) { // Use af-grid for all layouts - it auto-detects 12-column when children have spans // For equal-width columns, use af-grid (auto-adjusts) or af-grid-1 through af-grid-6 // For 12-column system, use af-grid with af-col-span-* children const classes = clsx( cols === 12 ? 'af-grid' : cols === 1 ? 'af-grid' : `af-grid-${cols}`, gap !== 'md' && `af-gap-${gap}`, responsive?.sm && `af-grid-${responsive.sm}@sm`, responsive?.md && `af-grid-${responsive.md}@md`, responsive?.lg && `af-grid-${responsive.lg}@lg`, className ); return <div className={classes}>{children}</div>; } ``` ## Responsive Column Component [Section titled “Responsive Column Component”](#responsive-column-component) ``` import { clsx } from 'clsx'; interface ColProps { span?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12; responsive?: { sm?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12; md?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12; lg?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12; }; children: React.ReactNode; className?: string; } export function Col({ span = 12, responsive, children, className }: ColProps) { const classes = clsx( `af-col-span-${span}`, responsive?.sm && `af-col-span-${responsive.sm}@sm`, responsive?.md && `af-col-span-${responsive.md}@md`, responsive?.lg && `af-col-span-${responsive.lg}@lg`, className ); return <div className={classes}>{children}</div>; } ``` ## Usage Example [Section titled “Usage Example”](#usage-example) ``` import { Card } from './Card'; import { Button } from './Button'; import { Stack } from './Stack'; import { Grid } from './Grid'; function Dashboard() { return ( <div className="af-container"> <Stack gap="lg"> <h1>Dashboard</h1> {/* Prefer af-grid with column counts for equal-width cards */} <Grid cols={1} gap="md" responsive={{ md: 2, lg: 4 }}> <Card title="Users" actions={<Button variant="primary">View</Button>}> <p>1,234 active users</p> </Card> <Card title="Revenue"> <p>$12,345</p> </Card> <Card title="Orders"> <p>567 orders</p> </Card> </Grid> </Stack> </div> ); } ``` ## Key Principles [Section titled “Key Principles”](#key-principles) 1. **You own the code** - Copy, modify, extend as needed 2. **Just classnames** - No runtime, just CSS classes 3. **Composable** - Mix and match with your own components 4. **Type-safe** - Full TypeScript support 5. **Accessible** - Semantic HTML by default

# Copy-Paste Recipes

> Ready-to-use patterns for common UI needs

**Ready-to-use patterns for common UI needs.** Copy, paste, customize. ## Auth Form [Section titled “Auth Form”](#auth-form) Code Live ``` <div class="af-container-xs"> <div class="af-stack af-gap-lg"> <h1> Sign In </h1> <form class="af-stack"> <div class="af-field"> <label for="email" class="af-field__label"> Email </label> <input type="email" id="email" class="af-input" required> </div> <div class="af-field"> <label for="password" class="af-field__label"> Password </label> <input type="password" id="password" class="af-input" required> </div> <div class="af-inline af-justify-between"> <label class="af-field"> <input type="checkbox" class="af-checkbox"> <span> Remember me </span> </label> <a href="#" > Forgot password? </a> </div> <button type="submit" class="af-btn af-w-full"> Sign In </button> </form> </div> </div> ``` # Sign In Email Password \[ ] Remember me [Forgot password?](#) Sign In ## Heading with Subtitle [Section titled “Heading with Subtitle”](#heading-with-subtitle) Use `<hgroup>` to visually group a heading with its subtitle or tagline. Perfect for hero sections, page headers, and card titles. Code Live ``` <!-- Hero section --> <hgroup> <h1> Airframe </h1> <p class="af-lead"> A structural UI system designed for humans and AI. </p> </hgroup> <!-- Card title with subtitle --> <div class="af-card"> <hgroup> <h2 class="af-card__title"> Dashboard </h2> <p class="af-text-sm af-text-muted"> Last updated 2 hours ago </p> </hgroup> <div class="af-card__body"> Content here </div> </div> <!-- Page header --> <hgroup> <h1> Settings </h1> <p> Manage your account preferences and security settings. </p> </hgroup> ``` # Airframe A structural UI system designed for humans and AI. ## Dashboard Last updated 2 hours ago Content here # Settings Manage your account preferences and security settings. **Note:** `<hgroup>` provides visual grouping only. Browsers don’t implement its semantic outline behavior, so ensure your heading hierarchy remains correct for accessibility. ## Settings Page [Section titled “Settings Page”](#settings-page) **Note:** This example uses `af-grid` with column spans for an asymmetric layout (3/9 split). For equal-width columns, prefer `af-grid af-grid-2` or `af-grid af-grid-3`. Code Live ``` <div class="af-container"> <div class="af-grid af-gap-xl"> <aside class="af-col-span-3@lg"> <nav class="af-stack af-gap-sm"> <a href="#" class="af-is-active"> Profile </a> <a href="#" > Security </a> <a href="#" > Notifications </a> </nav> </aside> <main class="af-col-span-9@lg"> <div class="af-stack af-gap-lg"> <h1> Settings </h1> <div class="af-card"> <h2 class="af-card__title"> Profile </h2> <div class="af-card__body"> <form class="af-stack"> <div class="af-field"> <label for="name" class="af-field__label"> Name </label> <input type="text" id="name" class="af-input" value="John Doe"> </div> <div class="af-field"> <label for="email" class="af-field__label"> Email </label> <input type="email" id="email" class="af-input" value="john@example.com"> </div> <div class="af-inline af-justify-end"> <button type="submit" class="af-btn"> Save Changes </button> </div> </form> </div> </div> </div> </main> </div> </div> ``` [Profile](#) [Security](#) [Notifications](#) # Settings ## Profile Name John Doe Email <john@example.com> Save Changes ## Table Page [Section titled “Table Page”](#table-page) Code Live ``` <div class="af-container"> <div class="af-stack af-gap-lg"> <div class="af-inline af-justify-between"> <h1> Users </h1> <button class="af-btn"> Add User </button> </div> <div class="af-card"> <div class="af-card__body"> <table class="af-table"> <thead> <tr> <th> Name </th> <th> Email </th> <th> Role </th> <th> Actions </th> </tr> </thead> <tbody> <tr> <td> John Doe </td> <td> john@example.com </td> <td> Admin </td> <td> <div class="af-inline af-gap-sm"> <button class="af-btn af-is-sm"> Edit </button> <button class="af-btn af-is-sm af-is-danger"> Delete </button> </div> </td> </tr> </tbody> </table> </div> </div> </div> </div> ``` # Users Add User | Name | Email | Role | Actions | | -------- | ----------------- | ----- | ----------- | | John Doe | john\@example.com | Admin | Edit Delete | ## Empty State [Section titled “Empty State”](#empty-state) Code Live ``` <div class="af-empty-state"> <div class="af-empty-state-icon"> 📭 </div> <h3 class="af-empty-state-title"> No items yet </h3> <p> Get started by creating your first item. </p> <button class="af-btn"> Create Item </button> </div> ``` 📭 ### No items yet Get started by creating your first item. Create Item ## Dashboard Layout [Section titled “Dashboard Layout”](#dashboard-layout) **Note:** This uses `af-grid` with column counts for equal-width cards. Prefer this over `af-cols-12` for card grids. Code Live ``` <div class="af-container"> <div class="af-stack af-gap-lg"> <header class="af-inline af-justify-between"> <h1> Dashboard </h1> <div class="af-inline af-gap-sm"> <button class="af-btn af-is-secondary"> Export </button> <button class="af-btn"> New </button> </div> </header> <div class="af-grid-1 af-grid-2@md af-grid-4@lg af-gap-lg"> <div class="af-card"> <h3 class="af-card__title"> Users </h3> <div class="af-card__body"> <p class="af-text-h2"> 1,234 </p> <p class="af-text-sm"> +12% from last month </p> </div> </div> <div class="af-card"> <h3 class="af-card__title"> Revenue </h3> <div class="af-card__body"> <p class="af-text-h2"> $12,345 </p> <p class="af-text-sm"> +8% from last month </p> </div> </div> <div class="af-card"> <h3 class="af-card__title"> Orders </h3> <div class="af-card__body"> <p class="af-text-h2"> 567 </p> <p class="af-text-sm"> +5% from last month </p> </div> </div> <div class="af-card"> <h3 class="af-card__title"> Growth </h3> <div class="af-card__body"> <p class="af-text-h2"> +23% </p> <p class="af-text-sm"> Overall growth rate </p> </div> </div> </div> </div> </div> ``` # Dashboard Export New ### Users 1,234 +12% from last month ### Revenue $12,345 +8% from last month ### Orders 567 +5% from last month ### Growth +23% Overall growth rate ## Responsive Sidebar Layout [Section titled “Responsive Sidebar Layout”](#responsive-sidebar-layout) **Note:** This uses `af-grid` with column spans for an asymmetric layout (3/9 split). The grid auto-detects the 12-column system when children have `af-col-span-*` classes. Code Live ``` <div class="af-grid af-gap-0"> <!-- Sidebar --> <aside class="af-col-span-3@lg af-drawer af-drawer-left"> <nav class="af-stack af-gap-sm af-p-lg"> <a href="#" class="af-is-active"> Dashboard </a> <a href="#" > Settings </a> <a href="#" > Profile </a> </nav> </aside> <!-- Main Content --> <main class="af-col-span-9@lg af-p-xl"> <div class="af-stack af-gap-lg"> <h1> Dashboard </h1> <div class="af-card"> <div class="af-card__body"> Main content here </div> </div> </div> </main> </div> ``` [Dashboard](#) [Settings](#) [Profile](#) # Dashboard Main content here ## React Recipes [Section titled “React Recipes”](#react-recipes) All recipes work identically in React - just use `className` instead of `class`: ``` <div className="af-stack af-gap-lg"> <h1>Dashboard</h1> <div className="af-card"> <div className="af-card__body">Content</div> </div> </div> ```

# Responsive Suffix

> Apply breakpoint-specific styles with @xs through @2xl

Airframe uses a simple responsive suffix to make utilities, layouts, and grid classes adapt at specific breakpoints. Add `@{bp}` to a class name to apply it from that breakpoint and up. ## Syntax [Section titled “Syntax”](#syntax) ``` base-class@bp base-class@bp-only ``` * `base-class` is any Airframe class (utility, layout recipe, grid, etc.) * `bp` is one of the supported breakpoints (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`) * `@{bp}` applies the class from that breakpoint **and up** (mobile-first) * `@{bp}-only` applies the class **only at that specific breakpoint range** (not above or below) ### Example [Section titled “Example”](#example) ``` <div class="af-gap-sm af-gap-lg@md"> <!-- Small gap on mobile, large gap on md+ --> </div> ``` ### Breakpoint-Only Example [Section titled “Breakpoint-Only Example”](#breakpoint-only-example) ``` <div class="af-hidden@sm-only"> <!-- Hidden only at sm breakpoint (640px-767px), visible elsewhere --> </div> ``` ## Breakpoints [Section titled “Breakpoints”](#breakpoints) | Suffix | Min Width | Typical Use | | ------ | --------- | ------------------------------- | | `@xs` | 360px+ | Small phones, compact viewports | | `@sm` | 640px+ | Large phones, small tablets | | `@md` | 768px+ | Tablets (portrait) | | `@lg` | 1024px+ | Tablet landscape, small laptops | | `@xl` | 1280px+ | Standard desktop | | `@2xl` | 1536px+ | Large desktop, wide screens | ## How It Works [Section titled “How It Works”](#how-it-works) * **Mobile-first:** base classes apply to all sizes, then `@{bp}` overrides start at the matching breakpoint. * **Min-width media queries:** `@{bp}` maps to a `min-width` query (applies from that breakpoint and up). * **Breakpoint-only queries:** `@{bp}-only` maps to both `min-width` and `max-width` queries (applies only at that specific breakpoint range). * **Stackable:** use multiple suffixes to progressively adjust styles. ``` <div class="af-grid-1 af-grid-2@md af-grid-4@lg"> <!-- 1 column on mobile, 2 on md+, 4 on lg+ --> </div> ``` ### Breakpoint-Only Variants [Section titled “Breakpoint-Only Variants”](#breakpoint-only-variants) Breakpoint-only variants (`@{bp}-only`) target a specific breakpoint range, not “and up”. This is useful when you need styles that apply only at a particular screen size. **Available for:** `af-hidden` and `af-show` utilities only. ``` <div class="af-hidden@sm-only"> <!-- Hidden only at sm (640px-767px), visible at all other sizes --> </div> <div class="af-show@md-only"> <!-- Visible only at md (768px-1023px), hidden at all other sizes --> </div> ``` **Breakpoint ranges:** * `@xs-only`: 360px - 639px * `@sm-only`: 640px - 767px * `@md-only`: 768px - 1023px * `@lg-only`: 1024px - 1279px * `@xl-only`: 1280px - 1535px * `@2xl-only`: Not available (2xl has no upper limit) ## Where You Can Use It [Section titled “Where You Can Use It”](#where-you-can-use-it) Most Airframe utilities and all layout/grid classes support responsive suffixes. Common categories: * **Spacing:** `af-gap-lg@md`, `af-p-xl@lg` * **Layout recipes:** `af-stack-lg@md`, `af-inline-sm@lg` * **Grid:** `af-grid-2@md`, `af-col-span-8@lg` * **Visibility:** `af-hidden@xs`, `af-show@md`, `af-hidden@sm-only`, `af-show@md-only` * **Position:** `af-pos-sticky@md` * **Alignment:** `af-text-center@sm`, `af-text-start@md` * **Color utilities:** `af-bg-primary@lg`, `af-text-muted@md` If a class has a responsive variant, it follows the exact same naming with `@{bp}` appended. ## Base Classes With Responsive Suffix [Section titled “Base Classes With Responsive Suffix”](#base-classes-with-responsive-suffix) Add `@{bp}` to any base class in the lists below. ### Spacing Utilities [Section titled “Spacing Utilities”](#spacing-utilities) * `af-gap-0` / `af-gap-xs` / `af-gap-sm` / `af-gap-md` / `af-gap-lg` / `af-gap-xl` / `af-gap-2xl` / `af-gap-3xl` / `af-gap-4xl` * `af-p-0` / `af-p-xs` / `af-p-sm` / `af-p-md` / `af-p-lg` / `af-p-xl` / `af-p-2xl` / `af-p-3xl` / `af-p-4xl` * `af-px-*`, `af-py-*`, `af-pt-*`, `af-pr-*`, `af-pb-*`, `af-pl-*` * `af-m-*`, `af-mx-auto`, `af-mx-*`, `af-my-*`, `af-mt-*`, `af-mr-*`, `af-mb-*`, `af-ml-*` ### Display & Alignment Utilities [Section titled “Display & Alignment Utilities”](#display--alignment-utilities) * `af-hidden` * `af-block` * `af-inline-block` * `af-flex` * `af-inline-flex` * `af-flex-reverse` * `af-row` / `af-row-reverse` * `af-col` / `af-col-reverse` * `af-wrap` * `af-nowrap` * `af-justify-start` * `af-justify-center` * `af-justify-end` * `af-justify-between` * `af-justify-around` * `af-justify-evenly` * `af-items-start` * `af-items-center` * `af-items-end` * `af-items-stretch` * `af-items-baseline` * `af-align-top` * `af-align-middle` * `af-align-bottom` * `af-align-baseline` * `af-align-top` / `af-align-middle` / `af-align-bottom` ### Position Utilities [Section titled “Position Utilities”](#position-utilities) * `af-pos-relative` * `af-pos-absolute` * `af-pos-sticky` * `af-pos-revert` ### Typography Utilities [Section titled “Typography Utilities”](#typography-utilities) * `af-text-h1` * `af-text-h2` * `af-text-h3` * `af-text-body` * `af-text-muted` * `af-text-mono` * `af-text-sm` * `af-text-md` * `af-text-lg` * `af-text-body-sm` * `af-text-strong` * `af-title` * `af-text-nowrap` * `af-text-break` * `af-clamp` * `af-clamp-1` * `af-clamp-2` * `af-clamp-3` * `af-clamp-4` * `af-numeric` ### Text Alignment Utilities [Section titled “Text Alignment Utilities”](#text-alignment-utilities) * `af-text-center` * `af-text-start` * `af-text-end` ### Text Color Utilities [Section titled “Text Color Utilities”](#text-color-utilities) * `af-text` * `af-text-muted` * `af-text-inverse` * `af-text-primary` * `af-text-link` * `af-text-success` * `af-text-danger` * `af-text-warning` * `af-text-info` ### Background Color Utilities [Section titled “Background Color Utilities”](#background-color-utilities) * `af-bg-background` * `af-bg-surface` * `af-bg-surface-2` * `af-bg-surface-3` * `af-bg-primary` * `af-bg-success` * `af-bg-danger` * `af-bg-warning` * `af-bg-info` * `af-bg-primary-soft` * `af-bg-success-soft` * `af-bg-danger-soft` * `af-bg-warning-soft` * `af-bg-info-soft` * `af-gradient-accent` * `af-gradient-subtle` * `af-gradient-border` ### Border Color Utilities [Section titled “Border Color Utilities”](#border-color-utilities) * `af-border` * `af-border-default` * `af-border-muted` * `af-border-focus` * `af-border-strong` * `af-border-primary` * `af-border-success` * `af-border-danger` * `af-border-warning` * `af-border-info` ### Radius & Shadow Utilities [Section titled “Radius & Shadow Utilities”](#radius--shadow-utilities) * `af-radius-sm` * `af-radius-md` * `af-radius-lg` * `af-radius-full` * `af-shadow-sm` * `af-shadow-md` * `af-shadow-lg` ### State Helpers [Section titled “State Helpers”](#state-helpers) * `af-is-disabled` * `af-is-loading` * `af-is-active` * `af-is-muted` * `af-has-error` * `af-has-focus` ### Visibility Helpers [Section titled “Visibility Helpers”](#visibility-helpers) * `af-hidden` * `af-show` ### Accessibility Helpers [Section titled “Accessibility Helpers”](#accessibility-helpers) * `af-sr-only` ### Layout Recipes [Section titled “Layout Recipes”](#layout-recipes) * `af-stack` * `af-stack-sm` * `af-stack-md` * `af-stack-lg` * `af-inline` * `af-inline-sm` * `af-inline-md` * `af-inline-lg` * `af-cluster` * `af-spread` * `af-center` * `af-container` * `af-container-xs` * `af-container-sm` * `af-container-md` * `af-container-lg` * `af-container-xl` * `af-section-sm` * `af-section` * `af-section-lg` * `af-spacer-sm` * `af-spacer-md` * `af-spacer-lg` * `af-surface` * `af-surface-2` ### Flex Alignment Utilities [Section titled “Flex Alignment Utilities”](#flex-alignment-utilities) * `af-justify-start` * `af-justify-center` * `af-justify-end` * `af-justify-between` * `af-justify-around` * `af-justify-evenly` * `af-items-start` * `af-items-center` * `af-items-end` * `af-items-stretch` * `af-items-baseline` ### Flex Order & Sizing Utilities [Section titled “Flex Order & Sizing Utilities”](#flex-order--sizing-utilities) * `af-order-first` * `af-order-default` * `af-order-1` … `af-order-6` * `af-order-last` * `af-grow` / `af-grow-0` * `af-shrink` / `af-shrink-0` * `af-basis-0` / `af-basis-auto` * `af-self-start` / `af-self-center` / `af-self-end` / `af-self-stretch` / `af-self-baseline` ### Outline & Focus Utilities [Section titled “Outline & Focus Utilities”](#outline--focus-utilities) * `af-focus-ring` * `af-focus-ring-inset` * `af-focus-none` * `af-outline` * `af-outline-0` * `af-outline-offset-2` * `af-outline-offset-4` ### Cursor & Motion Utilities [Section titled “Cursor & Motion Utilities”](#cursor--motion-utilities) * `af-cursor-pointer` * `af-cursor-not-allowed` * `af-reduce-motion` ### Hit Target Utilities [Section titled “Hit Target Utilities”](#hit-target-utilities) * `af-hit` * `af-hit-44` ### Grid Classes [Section titled “Grid Classes”](#grid-classes) * `af-grid` * `af-grid-1` * `af-grid-2` * `af-grid-3` * `af-grid-4` * `af-grid-5` * `af-grid-6` * `af-col-span-1` * `af-col-span-2` * `af-col-span-3` * `af-col-span-4` * `af-col-span-5` * `af-col-span-6` * `af-col-span-7` * `af-col-span-8` * `af-col-span-9` * `af-col-span-10` * `af-col-span-11` * `af-col-span-12` ## Common Patterns [Section titled “Common Patterns”](#common-patterns) ### Progressive Enhancement [Section titled “Progressive Enhancement”](#progressive-enhancement) ``` <div class="af-stack af-stack-lg@md"> <!-- Default layout for mobile, larger gap on md+ --> </div> ``` ### Responsive Visibility [Section titled “Responsive Visibility”](#responsive-visibility) ``` <div class="af-hidden@xs af-show@md"> <!-- Hidden on extra-small screens, visible from md up --> </div> ``` ### Breakpoint-Only Visibility [Section titled “Breakpoint-Only Visibility”](#breakpoint-only-visibility) ``` <div class="af-hidden@sm-only"> <!-- Hidden only at sm breakpoint (640px-767px), visible elsewhere --> </div> <div class="af-show@md-only"> <!-- Visible only at md breakpoint (768px-1023px), hidden elsewhere --> </div> ``` ### Responsive Alignment [Section titled “Responsive Alignment”](#responsive-alignment) ``` <h2 class="af-text-center af-text-start@md"> Center on mobile, start-aligned on md+ </h2> ``` ## Tips [Section titled “Tips”](#tips) * Start with a sensible **base class** for mobile, then add responsive overrides. * You can add a responsive class without a base class when you only want behavior at and above a breakpoint. * Keep class lists readable by grouping responsive overrides together. ## Related Docs [Section titled “Related Docs”](#related-docs) * [Utilities](/docs/utilities) * [Layouts](/docs/layouts) * [Grid](/docs/grid)

# Typography guide

> Philosophy, tokens, and override-friendly type customization

Airframe styles semantic elements by default and provides a **small set of text roles** for when semantics and visuals diverge. ## Philosophy [Section titled “Philosophy”](#philosophy) * **Semantic first**: `<h1>`–`<h6>`, `<p>`, `<small>` look good by default. **Use semantic elements by default.** * **Text roles only for visual hierarchy overrides**: Use `af-text-h*` or `af-text-body` **only when semantics and visuals must diverge**. * ✅ `<h2 class="af-text-h1">` — visually H1, semantically H2 * ✅ `<p class="af-text-caption">` — caption styling on paragraph * ❌ `<h1 class="af-text-h1">` — redundant, use `<h1>` instead * **Token-driven**: Typography is controlled by `--af-type-*` tokens for easy brand overrides. ## Semantic Defaults [Section titled “Semantic Defaults”](#semantic-defaults) These elements are styled automatically: ``` <h1> Title </h1> <h2> Section </h2> <p> Body text </p> <small> Caption </small> ``` ### Heading Groups [Section titled “Heading Groups”](#heading-groups) Use `<hgroup>` to visually group a heading with its subtitle or tagline. This is useful for hero sections, page headers, and card titles: ``` <hgroup> <h1> Page Title </h1> <p class="af-lead"> Subtitle or tagline text </p> </hgroup> ``` **Important:** `<hgroup>` provides visual grouping only. Browsers don’t implement its semantic outline algorithm behavior, so ensure your heading hierarchy (`<h1>`–`<h6>`) remains correct for accessibility. The element is styled with appropriate spacing to group the heading and subtitle together. ### Default Rhythm [Section titled “Default Rhythm”](#default-rhythm) Headings, paragraphs, lists, blockquotes, and dividers include **sensible spacing** by default. You should rarely need to add manual spacing for typical long-form content. ## Text Roles (Optional) [Section titled “Text Roles (Optional)”](#text-roles-optional) Use text roles when semantics and appearance need to diverge: ``` <h2 class="af-text-h1"> Visually H1, semantically H2 </h2> <p class="af-text-h3"> Visually H3, semantically paragraph </p> <p class="af-text-body"> Explicit body role </p> <p class="af-text-caption"> Caption text </p> <span class="af-text-overline"> Overline label </span> <div class="af-text-display"> Hero headline </div> ``` Available roles: * `af-text-display` * `af-text-h1` … `af-text-h6` * `af-text-body` * `af-text-caption` * `af-text-overline` ## Page Patterns (Hero, Stats, Prose) [Section titled “Page Patterns (Hero, Stats, Prose)”](#page-patterns-hero-stats-prose) For marketing pages and dashboards: * **`af-eyebrow`** – Section label (uppercase, letter-spacing). Add `af-is-on-primary` for hero/CTA on primary background. * **`af-text-fluid-h1`**, **`af-text-fluid-h2`**, **`af-text-fluid-h3`** – Responsive hero headings (clamp-based). * **`af-stat-display`** – Large hero numbers (e.g. “12.4k”, “0”, “1”). * **`af-prose`** / **`af-measure`** – Readable line length (65ch). Variants: `af-measure-narrow` (45ch), `af-measure-wide` (80ch). ``` <p class="af-eyebrow"> Why Airframe </p> <h1 class="af-text-fluid-h1"> Hero heading </h1> <p class="af-stat-display"> 12.4k </p> <div class="af-prose"> Long-form content with optimal line length </div> ``` ## Typography Helpers (Minimal) [Section titled “Typography Helpers (Minimal)”](#typography-helpers-minimal) These are intentionally small and common: * `af-text-muted` – muted text color * `af-text-on-primary` – text on primary background (hero/CTA) * `af-text-on-primary-muted` – muted text on primary (opacity 0.7) * `af-text-mono` – monospace font * `af-text-sm` / `af-text-md` / `af-text-lg` – simple size helpers * `af-title` – quick title style ## Text Alignment (Dir-Aware) [Section titled “Text Alignment (Dir-Aware)”](#text-alignment-dir-aware) Text alignment utilities that respect document direction (LTR/RTL): ``` <!-- Base alignment --> <p class="af-text-center"> Centered text </p> <p class="af-text-start"> Start-aligned (left in LTR, right in RTL) </p> <p class="af-text-end"> End-aligned (right in LTR, left in RTL) </p> <!-- Responsive pattern: center on small, start on md+ --> <h2 class="af-text-h2 af-text-center af-text-start@md"> Responsive, RTL-safe heading </h2> ``` **Available classes:** * `af-text-center` – Center alignment * `af-text-start` – Start alignment (RTL-safe) * `af-text-end` – End alignment (RTL-safe) **Responsive variants (v0.1):** * `af-text-center@{bp}` – Center at breakpoint and up * `af-text-start@{bp}` – Start at breakpoint and up **Why `start`/`end` instead of `left`/`right`?** * `start` = left in LTR, right in RTL * `end` = right in LTR, left in RTL * Automatically respects `[dir="ltr"]` and `[dir="rtl"]` * No JavaScript needed * Standards-compliant and future-proof **Recommended Pattern:** ``` <!-- Center on small screens, start-aligned from md up (RTL-safe) --> <h2 class="af-text-h2 af-text-center af-text-start@md"> Responsive, RTL-safe heading </h2> ``` **Behavior:** * **xs / sm**: Centered * **md+ (LTR)**: Left-aligned * **md+ (RTL)**: Right-aligned ## Token Model [Section titled “Token Model”](#token-model) Typography uses semantic tokens so brands can override safely: ### Font Families [Section titled “Font Families”](#font-families) ``` :root { /* Font primitives */ --af-base-font-sans: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji"; --af-base-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; /_ Semantic font tokens _/ --af-font-primary: var(--af-base-font-sans); /_ Primary font (used for body text by default) _/ --af-font-heading: var(--af-font-primary); /_ Heading font (applied to h1-h6, .af-text-h_, .af-text-display) _/ --af-font-body: var(--af-base-font-sans); /_ Body text font _/ --af-font-code: var(--af-base-font-mono); /_ Code font _/ --af-font-mono: var(--af-base-font-mono); /_ Monospace font */ } ``` **Customizing fonts:** ``` :root { /* Use custom web fonts */ --af-font-primary: 'Inter', 'Roboto', sans-serif; --af-font-heading: 'Playfair Display', serif; /* Different font for headings */ --af-font-body: var(--af-font-primary); /* Body uses primary */ } ``` ### Type Scale [Section titled “Type Scale”](#type-scale) ``` :root { /* Sizes */ --af-text-xs: 0.75rem; --af-text-sm: 0.875rem; --af-text-md: 1rem; --af-text-lg: 1.125rem; --af-text-xl: 1.25rem; --af-text-2xl: 1.5rem; --af-text-3xl: 1.875rem; /_ Leading (line-height) - typography term for vertical spacing between lines _/ /_ Use --af-leading-_ tokens; these map to CSS line-height property */ --af-leading-tight: 1.1; --af-leading-normal: 1.5; --af-leading-loose: 1.7; /_ Weights _/ --af-weight-regular: 400; --af-weight-medium: 500; --af-weight-semibold: 600; --af-weight-bold: 700; /_ Roles _/ --af-type-h1-size: var(--af-text-3xl); --af-type-h1-weight: var(--af-weight-semibold); --af-type-h1-leading: var(--af-leading-tight); --af-type-h1-tracking: -0.02em; --af-type-h2-tracking: -0.01em; --af-type-h3-tracking: 0em; --af-type-h4-tracking: 0em; --af-type-h5-tracking: 0em; --af-type-h6-tracking: 0em; } ``` ## Example: Card Title with Visual Override [Section titled “Example: Card Title with Visual Override”](#example-card-title-with-visual-override) ``` <div class="af-card"> <h3 class="af-text-h2"> Card Title </h3> <p class="af-card__body"> Body text remains semantic and readable. </p> </div> ``` ## Best Practices [Section titled “Best Practices”](#best-practices) * Prefer semantic elements (`<h1>`–`<h6>`, `<p>`, `<small>`) by default. * Use text roles only when you need visual hierarchy overrides. * Override typography via tokens, not by increasing selector specificity. For class-level utilities (`af-text-*`, alignment, wrap), see [Typography utilities](/docs/utilities/typography).

# Utilities

> All utility classes with examples

This page provides an overview of all utility classes in @airframeui. Utilities are intentionally small and predictable. ## Responsive Suffix [Section titled “Responsive Suffix”](#responsive-suffix) Most utilities support responsive variants using the `@{bp}` suffix. See the dedicated [Responsive Suffix](/docs/responsive-suffix) page for syntax, breakpoints, and best practices. ## Utility Categories [Section titled “Utility Categories”](#utility-categories) * **[Spacing Utilities](/docs/utilities/spacing)** - Padding and margin utilities * **[Display & Alignment](/docs/utilities/display)** - Display, flexbox, and alignment utilities * **[Color Utilities](/docs/utilities/colors)** - Text, background, and border color utilities * **[Typography](/docs/utilities/typography)** — Semantic type defaults, text roles, and typography utilities * **[Layout Utilities](/docs/utilities/layout)** - Layout helpers, sizing, and density utilities * **[Interaction & Overflow](/docs/utilities/interaction)** - Focus, cursor, pointer events, and overflow utilities * **[Position Utilities](/docs/utilities/position)** - Position and placement utilities * **[Visibility & State](/docs/utilities/visibility)** - Visibility, state helpers, accessibility, and border utilities ## Notes [Section titled “Notes”](#notes) * Utilities are **intentionally minimal** to keep DOM readable. * Prefer layout recipes (`af-stack`, `af-inline`, `af-grid`) for larger composition. * Use responsive suffixes when needed: `@xs/@sm/@md/@lg/@xl/@2xl`.

# Color Utilities

> Text, background, and border color utility classes

Color utilities use semantic tokens that automatically adapt to light/dark themes and maintain proper contrast ratios. ## Class groups [Section titled “Class groups”](#class-groups) * **[Text color](/docs/utilities/colors/text-color)**: `af-text*` * **[Background color](/docs/utilities/colors/background-color)**: `af-bg-*` * **[Border color](/docs/utilities/colors/border-color)**: `af-border-*` (color only) * **[Gradients](/docs/utilities/colors/gradients)**: `af-gradient-*`

# Background color

> Semantic background utilities

Background utilities for surfaces and intents. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------------- | ----------------------------------------------------- | | `af-bg-background` | `background-color: var(--af-color-background)` | | `af-bg-surface` | `background-color: var(--af-color-surface-primary)` | | `af-bg-surface-secondary` | `background-color: var(--af-color-surface-secondary)` | | `af-bg-surface-tertiary` | `background-color: var(--af-color-surface-tertiary)` | | `af-bg-muted` | `background-color: var(--af-color-surface-secondary)` | | `af-bg-primary` | `background-color: var(--af-color-primary)` | | `af-bg-success` | `background-color: var(--af-color-success)` | | `af-bg-danger` | `background-color: var(--af-color-danger)` | | `af-bg-warning` | `background-color: var(--af-color-warning)` | | `af-bg-info` | `background-color: var(--af-color-info)` | | `af-bg-*-soft` | `background-color: var(--af-color-*-soft)` | | `af-bg-*-hard` | `background-color: var(--af-color-*-hard)` | ## Examples [Section titled “Examples”](#examples) Surface backgrounds Surface Secondary ``` <div class="af-bg-surface af-border af-radius-md af-p-sm"> Surface </div> <div class="af-bg-surface-secondary af-border af-radius-md af-p-sm"> Secondary </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-bg-background` - Base background * `af-bg-surface` - Surface background (primary) * `af-bg-surface-secondary` - Secondary surface background * `af-bg-surface-tertiary` - Tertiary surface background * `af-bg-muted` - Muted surface background (same as surface-secondary) * `af-bg-primary` - Primary intent background * `af-bg-success` - Success intent background * `af-bg-danger` - Danger intent background * `af-bg-warning` - Warning intent background * `af-bg-info` - Info intent background * `af-bg-primary-soft` / `af-bg-success-soft` / `af-bg-danger-soft` / `af-bg-warning-soft` / `af-bg-info-soft` * `af-bg-primary-hard` / `af-bg-success-hard` / `af-bg-danger-hard` / `af-bg-warning-hard` / `af-bg-info-hard` When placing small text on a soft intent background, use the matching `*-hard` color (as badges/chips do), not the mid-tone intent token — soft + base often fails WCAG AA. For gradients, see [Gradients](/docs/utilities/colors/gradients). ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All background utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Text color](/docs/utilities/colors/text-color)

# Border color

> Semantic border color utilities

Border color utilities set the border color using semantic tokens. For border width utilities, see [Border width](/docs/utilities/visibility/border-width). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------- | --------------------------------------------- | | `af-border-default` | `border-color: var(--af-color-border)` | | `af-border-muted` | mixed border color (subtle) | | `af-border-focus` | `border-color: var(--af-focus-ring-color)` | | `af-border-strong` | `border-color: var(--af-color-border-strong)` | | `af-border-primary` | `border-color: var(--af-color-primary)` | | `af-border-success` | `border-color: var(--af-color-success)` | | `af-border-danger` | `border-color: var(--af-color-danger)` | | `af-border-warning` | `border-color: var(--af-color-warning)` | | `af-border-info` | `border-color: var(--af-color-info)` | ## Examples [Section titled “Examples”](#examples) Border intents Primary border Danger border ``` <div class="af-border af-border-primary af-radius-md af-p-sm"> Primary border </div> <div class="af-border af-border-danger af-radius-md af-p-sm"> Danger border </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-border-default` - Default border color * `af-border-muted` - Muted border color * `af-border-focus` - Focus border color * `af-border-strong` - Strong border color * `af-border-primary` - Primary intent border * `af-border-success` - Success intent border * `af-border-danger` - Danger intent border * `af-border-warning` - Warning intent border * `af-border-info` - Info intent border ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All border color utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Border width](/docs/utilities/visibility/border-width)

# Gradients

> Gradient utility classes

Gradient utilities built on design tokens (works in light/dark themes). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | -------------------- | ------------------------------------------------------------------------ | | `af-gradient-accent` | `background-image: linear-gradient(135deg, primary → info)` | | `af-gradient-subtle` | `background-image: linear-gradient(180deg, surface → surface-secondary)` | | `af-gradient-border` | `background-image: linear-gradient(135deg, border → border-strong)` | ## Examples [Section titled “Examples”](#examples) Accent gradient ``` <div class="af-gradient-accent af-radius-md" style="height: 4rem;"> </div> ``` Subtle gradient ``` <div class="af-gradient-subtle af-radius-md af-border" style="height: 4rem;"> </div> ``` Border gradient ``` <div class="af-gradient-border af-radius-md" style="padding: 1px;"> <div class="af-bg-surface af-radius-md" style="height: 4rem;"> </div> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-gradient-accent` * `af-gradient-subtle` * `af-gradient-border` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All gradient utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Background color](/docs/utilities/colors/background-color)

# Text color

> Semantic text color utilities

Color utilities use semantic tokens that automatically adapt to light/dark themes and maintain proper contrast ratios. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------- | ------------------------------------- | | `af-text` | `color: var(--af-color-text)` | | `af-text-muted` | `color: var(--af-color-text-muted)` | | `af-text-inverse` | `color: var(--af-color-text-inverse)` | | `af-text-primary` | `color: var(--af-color-primary)` | | `af-text-link` | primary color + underline | | `af-text-success` | `color: var(--af-color-success)` | | `af-text-danger` | `color: var(--af-color-danger)` | | `af-text-warning` | `color: var(--af-color-warning)` | | `af-text-info` | `color: var(--af-color-info)` | ## Examples [Section titled “Examples”](#examples) Common text colors Default Muted Primary [Link](#) ``` <div style="display:grid; gap: var(--af-space-2);"> <p class="af-text"> Default </p> <p class="af-text-muted"> Muted </p> <p class="af-text-primary"> Primary </p> <a class="af-text-link" href="#"> Link </a> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-text` - Default text color * `af-text-muted` - Muted text color * `af-text-inverse` - Inverse text color * `af-text-primary` - Primary intent color * `af-text-link` - Link color * `af-text-success` - Success intent color * `af-text-danger` - Danger intent color * `af-text-warning` - Warning intent color * `af-text-info` - Info intent color Mid-tone intent text utilities (`af-text-success`, `af-text-warning`, `af-text-info`) can fail WCAG AA on white or soft backgrounds at small sizes. For soft surfaces and badge-like labels, use `--af-color-*-hard` (see [Tokens](/docs/tokens) and [Badge](/docs/patterns/badges-chips/badge)). ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All text color utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Background color](/docs/utilities/colors/background-color)

# Display & Alignment

> Display, flex, and alignment utility classes

Utilities for controlling display, flex direction, and alignment. **Layout recipes first:** For common patterns (horizontal wrap with gap, space-between, centered content), prefer [Layouts](/docs/layouts): `af-inline`, `af-cluster`, `af-spread`, `af-center`. Use these Display & Alignment utilities when you need custom combinations. ## Class groups [Section titled “Class groups”](#class-groups) * **[Display](/docs/utilities/display/display)**: `af-block`, `af-inline-block`, `af-flex`, `af-inline-flex` * **[Flex direction](/docs/utilities/display/flex-direction)**: `af-row*`, `af-col*`, `af-flex-reverse` * **[Justify content](/docs/utilities/display/justify-content)**: `af-justify-*` * **[Align items](/docs/utilities/display/align-items)**: `af-items-*` * **[Flex wrap](/docs/utilities/display/flex-wrap)**: `af-wrap`, `af-nowrap` * **[Vertical align](/docs/utilities/display/vertical-align)**: `af-align-*` For responsive show/hide utilities, see [Visibility](/docs/utilities/visibility/visibility).

# Align items

> Align items utilities

Utilities for aligning flex items along the cross axis. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------- | ------------------------- | | `af-items-start` | `align-items: flex-start` | | `af-items-center` | `align-items: center` | | `af-items-end` | `align-items: flex-end` | | `af-items-stretch` | `align-items: stretch` | | `af-items-baseline` | `align-items: baseline` | ## Examples [Section titled “Examples”](#examples) Basic example A B C ``` <div class="af-flex af-items-center" style="height: 5rem; gap: 0.5rem;"> <div class="af-badge"> A </div> <div class="af-badge" style="padding-top: 1.25rem; padding-bottom: 1.25rem;"> B </div> <div class="af-badge"> C </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All align-items utilities support responsive variants using the `@{bp}` suffix: * `af-items-start@md` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Justify content](/docs/utilities/display/justify-content)

# Display

> Utilities for controlling display values

Utilities for controlling an element’s `display` value. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------- | ----------------------- | | `af-block` | `display: block` | | `af-inline-block` | `display: inline-block` | | `af-flex` | `display: flex` | | `af-inline-flex` | `display: inline-flex` | ## Examples [Section titled “Examples”](#examples) ### Flex vs inline-flex [Section titled “Flex vs inline-flex”](#flex-vs-inline-flex) Use `af-flex` or `af-inline-flex` when you need a flex container without a layout recipe: Flex vs inline-flex A B ``` <div class="af-inline-flex" style="gap: 0.5rem;"> <div class="af-badge"> A </div> <div class="af-badge"> B </div> </div> ``` For common layouts, prefer [layout recipes](/docs/layouts) (`af-stack`, `af-inline`, …) over raw display utilities. For responsive show/hide, see [Visibility](/docs/utilities/visibility/visibility). ## Responsive design [Section titled “Responsive design”](#responsive-design) Prefix a display utility with a breakpoint suffix to apply it from that breakpoint and up: ``` <div class="af-flex@md"> <!-- ... --> </div> ``` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Layouts](/docs/layouts) — semantic layout recipes that combine display, alignment, and gap * [Visibility](/docs/utilities/visibility/visibility)

# Flex direction

> Row/column direction utilities

Utilities for controlling flex direction. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------- | -------------------------------- | | `af-row` | `flex-direction: row` | | `af-row-reverse` | `flex-direction: row-reverse` | | `af-col` | `flex-direction: column` | | `af-col-reverse` | `flex-direction: column-reverse` | | `af-flex-reverse` | `flex-direction: row-reverse` | ## Examples [Section titled “Examples”](#examples) Row vs column One Two Three ``` <div class="af-flex af-col" style="gap: 0.5rem;"> <div class="af-badge"> One </div> <div class="af-badge"> Two </div> <div class="af-badge"> Three </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All flex-direction utilities support responsive variants using the `@{bp}` suffix: * `af-col@md` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Flex wrap](/docs/utilities/display/flex-wrap)

# Flex wrap

> Flex wrapping utilities

Utilities for controlling wrapping in flex containers. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------- | ------------------- | | `af-wrap` | `flex-wrap: wrap` | | `af-nowrap` | `flex-wrap: nowrap` | ## Examples [Section titled “Examples”](#examples) Wrap One Two Three Four ``` <div class="af-flex af-wrap" style="gap: 0.5rem; max-width: 14rem;"> <div class="af-badge"> One </div> <div class="af-badge"> Two </div> <div class="af-badge"> Three </div> <div class="af-badge"> Four </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All wrap utilities support responsive variants using the `@{bp}` suffix: * `af-wrap@lg` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Flex direction](/docs/utilities/display/flex-direction)

# Justify content

> Justify content utilities

Utilities for aligning flex items along the main axis. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | -------------------- | -------------------------------- | | `af-justify-start` | `justify-content: flex-start` | | `af-justify-center` | `justify-content: center` | | `af-justify-end` | `justify-content: flex-end` | | `af-justify-between` | `justify-content: space-between` | | `af-justify-around` | `justify-content: space-around` | | `af-justify-evenly` | `justify-content: space-evenly` | ## Examples [Section titled “Examples”](#examples) Basic example A B C ``` <div class="af-flex af-justify-between" style="gap: 0.5rem;"> <div class="af-badge"> A </div> <div class="af-badge"> B </div> <div class="af-badge"> C </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All justify utilities support responsive variants using the `@{bp}` suffix: * `af-justify-center@lg` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Align items](/docs/utilities/display/align-items)

# Vertical align

> Vertical alignment utilities for inline elements

Utilities for vertical alignment of inline and inline-block elements. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------- | -------------------------- | | `af-align-top` | `vertical-align: top` | | `af-align-middle` | `vertical-align: middle` | | `af-align-bottom` | `vertical-align: bottom` | | `af-align-baseline` | `vertical-align: baseline` | ## Examples [Section titled “Examples”](#examples) Inline alignment Top Middle Bottom Baseline ``` <div style="line-height: 2.5rem;"> <span class="af-badge af-align-top"> Top </span> <span class="af-badge af-align-middle"> Middle </span> <span class="af-badge af-align-bottom"> Bottom </span> <span class="af-badge af-align-baseline"> Baseline </span> <span style="display:inline-block; height: 2.5rem; border-left: 1px dashed var(--af-color-border); margin-left: var(--af-space-2); vertical-align: middle;"> </span> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All vertical-align utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Display](/docs/utilities/display/display)

# Interaction & Overflow Utilities

> Focus, cursor, pointer events, and overflow utility classes

Utilities for focus, input behavior, and overflow handling. ## Class groups [Section titled “Class groups”](#class-groups) * **[Focus ring](/docs/utilities/interaction/focus-ring)**: `af-focus-ring*`, `af-focus-none` * **[Outline](/docs/utilities/interaction/outline)**: `af-outline*` * **[Cursor](/docs/utilities/interaction/cursor)**: `af-cursor-*` * **[Pointer events](/docs/utilities/interaction/pointer-events)**: `af-pointer-*` * **[User select](/docs/utilities/interaction/user-select)**: `af-select-*` * **[Inert](/docs/utilities/interaction/inert)**: `af-inert` * **[Reduce motion](/docs/utilities/interaction/reduce-motion)**: `af-reduce-motion` * **[Overflow](/docs/utilities/interaction/overflow)**: `af-overflow*` * **[Scroll behavior](/docs/utilities/interaction/scroll-behavior)**: `af-scroll-smooth` * **[Scrollbar](/docs/utilities/interaction/scrollbar)**: `af-scrollbar`

# Cursor

> Cursor utilities

Utilities for cursor styles. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------------- | --------------------- | | `af-cursor-pointer` | `cursor: pointer` | | `af-cursor-not-allowed` | `cursor: not-allowed` | ## Examples [Section titled “Examples”](#examples) Pointer cursor Hover me ``` <button class="af-btn af-cursor-pointer"> Hover me </button> ``` Not allowed cursor Not allowed cursor ``` <div class="af-cursor-not-allowed"> Not allowed cursor </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All cursor utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Pointer events](/docs/utilities/interaction/pointer-events)

# Focus ring

> Focus ring utilities

Utilities for consistent focus treatment. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------------------------- | ------------------------------------------------------------------------------- | | `af-focus-ring:focus-visible` | `outline: var(--af-focus-ring-width) solid var(--af-focus-ring-color)` + offset | | `af-focus-ring-inset:focus-visible` | inset ring via `box-shadow` | | `af-focus-none:focus-visible` | `outline: none` | ## Examples [Section titled “Examples”](#examples) Focus ring Tab to focus ``` <button class="af-btn af-focus-ring"> Tab to focus </button> ``` Inset focus ring Tab to focus ``` <button class="af-btn af-focus-ring-inset"> Tab to focus </button> ``` No focus outline Tab to focus ``` <button class="af-btn af-focus-none"> Tab to focus </button> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All focus utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Outline](/docs/utilities/interaction/outline)

# Inert

> Inert subtree utility

`af-inert` disables interaction within a subtree (it sets `pointer-events: none` and `user-select: none`). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ---------- | ----------------------------------------- | | `af-inert` | `pointer-events: none; user-select: none` | ## Examples [Section titled “Examples”](#examples) Disable a subtree Can’t be clicked ``` <div class="af-inert"> <button class="af-btn"> Can't be clicked </button> </div> ``` ## Related [Section titled “Related”](#related) * [Pointer events](/docs/utilities/interaction/pointer-events)

# Outline

> Outline utilities

Utilities for outline and outline offset. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | --------------------- | ---------------------------------------------------- | | `af-outline` | `outline: var(--af-border-width) solid currentColor` | | `af-outline-0` | `outline: 0` | | `af-outline-offset-2` | `outline-offset: 2px` | | `af-outline-offset-4` | `outline-offset: 4px` | ## Examples [Section titled “Examples”](#examples) Outline Outline ``` <button class="af-btn af-outline af-outline-offset-2"> Outline </button> ``` Outline offset 4 Outline ``` <button class="af-btn af-outline af-outline-offset-4"> Outline </button> ``` Remove outline No outline ``` <button class="af-btn af-outline af-outline-offset-2 af-outline-0"> No outline </button> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All outline utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Focus ring](/docs/utilities/interaction/focus-ring)

# Overflow

> Overflow and scrolling utilities

Utilities for overflow behavior (clipping or scrolling overflow content). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | --------------------- | ------------------- | | `af-overflow-hidden` | `overflow: hidden` | | `af-overflow-auto` | `overflow: auto` | | `af-overflow-scroll` | `overflow: scroll` | | `af-overflow-visible` | `overflow: visible` | | `af-overflow-x-auto` | `overflow-x: auto` | | `af-overflow-y-auto` | `overflow-y: auto` | ## Examples [Section titled “Examples”](#examples) Horizontal scrolling Item 1Item 2 Item 3Item 4 Item 5 ``` <div class="af-overflow-x-auto af-scrollbar" style="max-width: 18rem; white-space: nowrap;"> <span class="af-badge"> Item 1 </span> <span class="af-badge"> Item 2 </span> <span class="af-badge"> Item 3 </span> <span class="af-badge"> Item 4 </span> <span class="af-badge"> Item 5 </span> </div> ``` Clip overflow (hidden) This is clipped ``` <div class="af-overflow-hidden af-border af-radius-md" style="height: 4rem;"> <div class="af-bg-muted" style="height: 6rem; padding: 1rem;"> This is clipped </div> </div> ``` Scroll overflow (auto) Scroll me ``` <div class="af-overflow-auto af-scrollbar af-border af-radius-md" style="height: 4rem; padding: 1rem;"> <div style="height: 8rem;"> Scroll me </div> </div> ``` Always show scrollbars (scroll) Scroll me ``` <div class="af-overflow-scroll af-scrollbar af-border af-radius-md" style="height: 4rem; padding: 1rem;"> <div style="height: 8rem;"> Scroll me </div> </div> ``` Let overflow show (visible) I overflow ``` <div class="af-overflow-visible af-border af-radius-md" style="height: 4rem; padding: 1rem;"> <span class="af-badge" style="display: inline-block; transform: translateY(2.25rem);"> I overflow </span> </div> ``` Vertical scrolling (overflow-y-auto) Scroll me ``` <div class="af-overflow-y-auto af-scrollbar af-border af-radius-md" style="height: 4rem; padding: 1rem;"> <div style="height: 8rem;"> Scroll me </div> </div> ``` For scroll behavior and styled scrollbars, see: * [Scroll behavior](/docs/utilities/interaction/scroll-behavior) * [Scrollbar](/docs/utilities/interaction/scrollbar) ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) Responsive variants are generated for `af-overflow-hidden` only (e.g. `af-overflow-hidden@md`). The other overflow utilities do not currently have responsive variants. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Scrollbar](/docs/utilities/interaction/scrollbar)

# Pointer events

> Pointer events utilities

Utilities for enabling/disabling pointer events. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------- | ---------------------- | | `af-pointer-none` | `pointer-events: none` | | `af-pointer-auto` | `pointer-events: auto` | ## Examples [Section titled “Examples”](#examples) Disable clicks Not clickable ``` <button class="af-btn af-pointer-none"> Not clickable </button> ``` Re-enable pointer events Clickable ``` <div class="af-pointer-none af-border af-radius-md af-p-sm"> <button class="af-btn af-pointer-auto"> Clickable </button> </div> ``` ## Related [Section titled “Related”](#related) * [User select](/docs/utilities/interaction/user-select)

# Reduce motion

> Reduced motion utility

Use `af-reduce-motion` to reduce or remove animations in a subtree for users who prefer reduced motion. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------ | -------------------------------------------------------------- | | `af-reduce-motion` | Forces near-zero animation/transition durations within subtree | ## Examples [Section titled “Examples”](#examples) Reduce motion in a subtree ``` <div class="af-reduce-motion"> <div class="af-spinner"> </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All reduce-motion utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Scroll behavior](/docs/utilities/interaction/scroll-behavior)

# Scroll behavior

> Scroll behavior utilities

Utilities for scroll behavior. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------ | ------------------------- | | `af-scroll-smooth` | `scroll-behavior: smooth` | ## Examples [Section titled “Examples”](#examples) Smooth scrolling [Scroll smoothly](#demo-anchor) Anchor ``` <a class="af-text-link af-scroll-smooth" href="#demo-anchor"> Scroll smoothly </a> <div style="height: 6rem;"> </div> <div id="demo-anchor" class="af-border af-radius-md af-p-sm"> Anchor </div> ``` ## Related [Section titled “Related”](#related) * [Overflow](/docs/utilities/interaction/overflow)

# Scrollbar

> Styled scrollbar utility

Use `af-scrollbar` for a modern styled scrollbar that adapts to your theme. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | -------------- | -------------------------------------------------------- | | `af-scrollbar` | Styled scrollbars (Firefox + WebKit) using design tokens | ## Examples [Section titled “Examples”](#examples) Styled scrollbar Scroll to see the styled scrollbar thumb. ``` <div class="af-scrollbar af-border af-radius-md" style="overflow: auto; height: 200px; padding: 1rem;"> <p class="af-text"> Scroll to see the styled scrollbar thumb. </p> <div style="height: 500px;"> </div> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-scrollbar` ## Related [Section titled “Related”](#related) * [Overflow](/docs/utilities/interaction/overflow)

# User select

> Text selection utilities

Utilities for controlling text selection. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ---------------- | ------------------- | | `af-select-none` | `user-select: none` | | `af-select-text` | `user-select: text` | ## Examples [Section titled “Examples”](#examples) Disable selection Try selecting this text. ``` <div class="af-select-none"> Try selecting this text. </div> ``` Allow text selection This part can be selected. This part can’t. ``` <div class="af-select-none"> <span class="af-select-text"> This part can be selected. </span> <span> This part can't. </span> </div> ``` ## Related [Section titled “Related”](#related) * [Pointer events](/docs/utilities/interaction/pointer-events)

# Layout Utilities

> Layout helpers, sizing, and density utility classes

Utilities for sizing, flex sizing, and density controls. ## Class groups [Section titled “Class groups”](#class-groups) * **[Sizing](/docs/utilities/layout/sizing)**: `af-w-full`, `af-h-full`, `af-min-w-0`, `af-min-h-0` * **[Flex sizing](/docs/utilities/layout/flex-sizing)**: `af-grow*`, `af-shrink*`, `af-basis-*` * **[Align self](/docs/utilities/layout/align-self)**: `af-self-*` * **[Order](/docs/utilities/layout/order)**: `af-order-*` * **[Density & hit area](/docs/utilities/layout/density-hit-area)**: `af-hit*`, `af-density-*`, `af-control-padding`

# Align self

> Self-alignment utilities

Utilities for aligning a single flex/grid item. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------ | ------------------------ | | `af-self-start` | `align-self: flex-start` | | `af-self-center` | `align-self: center` | | `af-self-end` | `align-self: flex-end` | | `af-self-stretch` | `align-self: stretch` | | `af-self-baseline` | `align-self: baseline` | ## Examples [Section titled “Examples”](#examples) Center one item A af-self-center C ``` <div class="af-flex af-items-stretch" style="height: 5rem; gap: 0.5rem;"> <div class="af-badge"> A </div> <div class="af-badge af-self-center"> af-self-center </div> <div class="af-badge"> C </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All align-self utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Align items](/docs/utilities/display/align-items)

# Density & hit area

> Hit target and density utilities

Utilities for consistent hit targets and control density. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------------ | ------------------------------------------------------------------ | | `af-hit` | `min-width/min-height: var(--af-hit-size)` | | `af-hit-44` | `min-width/min-height: 44px` | | `af-density-compact` | sets `--af-control-padding-*` to compact values | | `af-density-comfortable` | sets `--af-control-padding-*` to comfortable values | | `af-control-padding` | `padding: var(--af-control-padding-y) var(--af-control-padding-x)` | ## Examples [Section titled “Examples”](#examples) Hit target af-hit ``` <button class="af-btn af-hit"> af-hit </button> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-hit` * `af-hit-44` * `af-density-compact` / `af-density-comfortable` * `af-control-padding` Token: `--af-hit-size` defaults to `2.75rem` (44px). ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) Responsive variants are generated for `af-hit` and `af-hit-44` only. `af-density-compact`, `af-density-comfortable`, and `af-control-padding` do not currently have responsive variants. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Sizing](/docs/utilities/layout/sizing)

# Flex sizing

> Flex grow, shrink, and basis utilities

Utilities for controlling how flex items grow, shrink, and size. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | --------------- | ------------------ | | `af-grow` | `flex-grow: 1` | | `af-grow-0` | `flex-grow: 0` | | `af-shrink` | `flex-shrink: 1` | | `af-shrink-0` | `flex-shrink: 0` | | `af-basis-0` | `flex-basis: 0` | | `af-basis-auto` | `flex-basis: auto` | ## Examples [Section titled “Examples”](#examples) Grow Fixed af-grow ``` <div class="af-flex" style="gap: 0.5rem; width: 100%; max-width: 20rem;"> <div class="af-bg-primary-soft af-radius-sm af-p-sm" style="width: 6rem;"> Fixed </div> <div class="af-bg-primary-soft af-radius-sm af-p-sm af-grow"> af-grow </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All flex sizing utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Order](/docs/utilities/layout/order)

# Order

> Flex and grid order utilities

Utilities for controlling visual order of items. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------ | ------------- | | `af-order-first` | `order: -1` | | `af-order-default` | `order: 0` | | `af-order-{1..6}` | `order: <n>` | | `af-order-last` | `order: 9999` | ## Examples [Section titled “Examples”](#examples) Reorder A (order 2) B (order 1) C (order 3) ``` <div class="af-flex" style="gap: 0.5rem;"> <div class="af-badge af-order-2"> A (order 2) </div> <div class="af-badge af-order-1"> B (order 1) </div> <div class="af-badge af-order-3"> C (order 3) </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All order utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Flex sizing](/docs/utilities/layout/flex-sizing)

# Sizing

> Width/height and min-size utilities

Utilities for sizing elements. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------ | --------------- | | `af-w-full` | `width: 100%` | | `af-h-full` | `height: 100%` | | `af-min-w-0` | `min-width: 0` | | `af-min-h-0` | `min-height: 0` | ## Examples [Section titled “Examples”](#examples) Full width af-w-full ``` <div style="max-width: 18rem;"> <div class="af-bg-primary-soft af-radius-sm af-w-full af-p-sm"> af-w-full </div> </div> ``` ## Responsive design [Section titled “Responsive design”](#responsive-design) Prefix a sizing utility with a breakpoint suffix to apply it from that breakpoint and up: ``` <div class="af-w-full@md"> <!-- ... --> </div> ``` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Flex sizing](/docs/utilities/layout/flex-sizing)

# Position Utilities

> Position and placement utility classes

Utilities for controlling positioning and offsets. ## Class groups [Section titled “Class groups”](#class-groups) * **[Position](/docs/utilities/position/position)**: `af-pos-*` (and aliases) * **[Inset](/docs/utilities/position/inset)**: `af-inset-0`, `af-top-0`, `af-right-0`, `af-bottom-0`, `af-left-0`

# Inset

> Top/right/bottom/left offset utilities

Utilities for positioning offsets. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------- | ----------- | | `af-inset-0` | `inset: 0` | | `af-top-0` | `top: 0` | | `af-right-0` | `right: 0` | | `af-bottom-0` | `bottom: 0` | | `af-left-0` | `left: 0` | ## Available classes [Section titled “Available classes”](#available-classes) * `af-inset-0` (all edges) * `af-top-0` / `af-right-0` / `af-bottom-0` / `af-left-0` (individual edges) ## Examples [Section titled “Examples”](#examples) Full overlay Overlay ``` <div class="af-pos-relative af-border af-radius-md" style="height: 7rem;"> <div class="af-pos-absolute af-inset-0 af-badge" style="display: grid; place-items: center;"> Overlay </div> </div> ``` Pin to corners TL TR BL BR ``` <div class="af-pos-relative af-border af-radius-md" style="height: 7rem;"> <div class="af-pos-absolute af-top-0 af-left-0 af-badge"> TL </div> <div class="af-pos-absolute af-top-0 af-right-0 af-badge"> TR </div> <div class="af-pos-absolute af-bottom-0 af-left-0 af-badge"> BL </div> <div class="af-pos-absolute af-bottom-0 af-right-0 af-badge"> BR </div> </div> ``` ## Related [Section titled “Related”](#related) * [Position](/docs/utilities/position/position)

# Position

> Positioning utilities

Utilities for controlling positioning mode. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | --------------------------------- | -------------------- | | `af-pos-relative` / `af-relative` | `position: relative` | | `af-pos-absolute` / `af-absolute` | `position: absolute` | | `af-pos-sticky` / `af-sticky` | `position: sticky` | | `af-pos-revert` | `position: revert` | ## Available classes [Section titled “Available classes”](#available-classes) * `af-pos-relative` * `af-pos-absolute` * `af-pos-sticky` * `af-pos-revert` * `af-relative` / `af-absolute` / `af-sticky` For offsets, see [Inset (top/right/bottom/left)](/docs/utilities/position/inset). ## Examples [Section titled “Examples”](#examples) Absolute positioning Top right ``` <div class="af-pos-relative af-border af-radius-md" style="height: 6rem;"> <div class="af-pos-absolute af-top-0 af-right-0 af-badge"> Top right </div> </div> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) Responsive variants are generated for `af-pos-relative`, `af-pos-absolute`, `af-pos-sticky`, and `af-pos-revert`. The aliases (`af-relative`, `af-absolute`, `af-sticky`) do not currently have responsive variants. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Inset](/docs/utilities/position/inset)

# Spacing Utilities

> Padding and margin utility classes

Spacing utilities for padding and margin. ## Class groups [Section titled “Class groups”](#class-groups) * **[Padding](/docs/utilities/spacing/padding)**: `af-p-*`, `af-px-*`, `af-py-*`, `af-pt-*`, `af-pr-*`, `af-pb-*`, `af-pl-*` * **[Margin](/docs/utilities/spacing/margin)**: `af-m-*`, `af-mx-*`, `af-my-*`, `af-mt-*`, `af-mr-*`, `af-mb-*`, `af-ml-*`, `af-mx-auto` Gap utilities are documented in [Grid](/docs/grid) (source of truth for `af-gap-*`).

# Margin

> Utilities for controlling an element's margin

Utilities for controlling an element’s margin (space outside an element). ## Quick reference [Section titled “Quick reference”](#quick-reference) Scale: `0` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl` (maps to `--af-space-0`…`8`). | Class | Styles | | ------------ | ---------------------------------- | | `af-m-*` | `margin: var(--af-space-*)` | | `af-mx-*` | `margin-inline: var(--af-space-*)` | | `af-my-*` | `margin-block: var(--af-space-*)` | | `af-mt-*` | `margin-top: var(--af-space-*)` | | `af-mr-*` | `margin-right: var(--af-space-*)` | | `af-mb-*` | `margin-bottom: var(--af-space-*)` | | `af-ml-*` | `margin-left: var(--af-space-*)` | | `af-mx-auto` | `margin-inline: auto` | ## Examples [Section titled “Examples”](#examples) ### Basic margin [Section titled “Basic margin”](#basic-margin) Use `af-m-*` utilities like `af-m-md` and `af-m-lg` to control margin on all sides: Basic margin af-m-lg ``` <div class="af-bg-primary-soft af-radius-sm af-m-lg af-p-sm"> af-m-lg </div> ``` ### Auto centering [Section titled “Auto centering”](#auto-centering) Use `af-mx-auto` to center a block horizontally: Auto centering af-mx-auto ``` <div class="af-bg-primary-soft af-radius-sm af-w-full" style="max-width: 18rem;"> <div class="af-mx-auto af-p-sm" style="max-width: 12rem;"> af-mx-auto </div> </div> ``` ## Responsive design [Section titled “Responsive design”](#responsive-design) Prefix a margin utility with a breakpoint suffix to apply it from that breakpoint and up: ``` <div class="af-mx-auto@lg"> <!-- ... --> </div> ``` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Customizing your theme [Section titled “Customizing your theme”](#customizing-your-theme) Margin utilities are driven by the `--af-space-*` tokens. Override them in CSS — no rebuild required: ``` :root { --af-space-sm: 0.5rem; --af-space-md: 1rem; --af-space-lg: 1.5rem; } ``` See [Theming](/docs/theming) and [Tokens](/docs/tokens) for the full spacing scale. ## Related [Section titled “Related”](#related) * [Padding](/docs/utilities/spacing/padding)

# Padding

> Utilities for controlling an element's padding

Utilities for controlling an element’s padding (space inside an element). ## Quick reference [Section titled “Quick reference”](#quick-reference) Scale: `0` · `xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl` (maps to `--af-space-0`…`8`). | Class | Styles | | --------- | ----------------------------------- | | `af-p-*` | `padding: var(--af-space-*)` | | `af-px-*` | `padding-inline: var(--af-space-*)` | | `af-py-*` | `padding-block: var(--af-space-*)` | | `af-pt-*` | `padding-top: var(--af-space-*)` | | `af-pr-*` | `padding-right: var(--af-space-*)` | | `af-pb-*` | `padding-bottom: var(--af-space-*)` | | `af-pl-*` | `padding-left: var(--af-space-*)` | ## Examples [Section titled “Examples”](#examples) ### Basic padding [Section titled “Basic padding”](#basic-padding) Use `af-p-*` utilities like `af-p-sm` and `af-p-lg` to control padding on all sides: Basic padding Padded content ``` <div class="af-p-lg"> <div class="af-border af-radius-sm af-bg-primary-soft af-p-sm"> Padded content </div> </div> ``` ### Directional padding [Section titled “Directional padding”](#directional-padding) Use axis and side utilities (`af-px-*`, `af-py-*`, `af-pt-*`, …) for finer control: Directional padding px + py pt + pr + pb + pl ``` <div class="af-px-lg af-py-sm"> px + py </div> <div class="af-pt-lg af-pr-md af-pb-sm af-pl-md"> pt + pr + pb + pl </div> ``` ## Responsive design [Section titled “Responsive design”](#responsive-design) Prefix a padding utility with a breakpoint suffix to apply it from that breakpoint and up: ``` <div class="af-p-sm af-p-lg@md"> <!-- ... --> </div> ``` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Customizing your theme [Section titled “Customizing your theme”](#customizing-your-theme) Padding utilities are driven by the `--af-space-*` tokens. Override them in CSS — no rebuild required: ``` :root { --af-space-sm: 0.5rem; --af-space-md: 1rem; --af-space-lg: 1.5rem; } ``` See [Theming](/docs/theming) and [Tokens](/docs/tokens) for the full spacing scale. ## Related [Section titled “Related”](#related) * [Margin](/docs/utilities/spacing/margin)

# Typography

> Semantic headings, text roles, and typography utility classes

Airframe styles **semantic HTML** first (`<h1>`–`<h6>`, `<p>`, `<small>`). Use **`af-text-*` roles** only when the accessible heading level and the visual size should differ. For the type scale, tokens, and deep customization, see the **[Typography guide](/docs/typography)** and **[Tokens](/docs/tokens)**. For small utility tweaks (muted, mono, `af-title`), see **[Text style](/docs/utilities/typography/text-style)** below. ## Semantic type & text roles [Section titled “Semantic type & text roles”](#semantic-type--text-roles) ### Quick reference [Section titled “Quick reference”](#quick-reference) | Markup | When to use | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `<h1>` … `<h6>` | Default: real document outline and visual hierarchy match. | | `<h2 class="af-text-h1">` … `af-text-h6` | Same outline, different **visual** level (e.g. page title look on a section heading). | | `<p class="af-text-h3">` | **Rare:** paragraph or span that should **look** like a heading but must not be a heading in the outline. | | `.af-text-display`, `.af-text-fluid-h1` | Marketing hero / large display (not a substitute for a real `<h1>` when one is needed). | ### Semantic headings [Section titled “Semantic headings”](#semantic-headings) Use one real `<h1>` per page (or main landmark) when you are establishing the outline. Levels **h2–h6** nest under it. Default Airframe styles apply automatically—no classes required. *Previews on this page start at `<h2>` so they don’t add a second page-level `<h1>` next to the docs title. Use `<h1>` on your site the same way as in the snippet.* Heading levels h1–h6 ## Monthly summary ### Revenue #### North America ##### Enterprise accounts ###### Last updated Preview starts at h2; add `h1` for your main title (see code tab). ``` <h1> Reports dashboard </h1> <h2> Monthly summary </h2> <h3> Revenue </h3> <h4> North America </h4> <h5> Enterprise accounts </h5> <h6> Last updated </h6> ``` ### Text roles (semantics vs visuals) [Section titled “Text roles (semantics vs visuals)”](#text-roles-semantics-vs-visuals) Prefer fixing the **heading level** in the markup whenever you can. Use `af-text-h1` … `af-text-h6` when the correct accessible level is already chosen but the **visual** step should be different. Visual override with af-text-\* ## Looks like H1, outline says H2 ### Compact section title ``` <h2 class="af-text-h1"> Looks like H1, outline says H2 </h2> <h3 class="af-text-h4"> Compact section title </h3> ``` Optional **paragraph-sized** roles for copy that should not be headings in the tree: Body, caption, lead, overline Regular body text. Explicit body role (same as an unclassed paragraph). Lead — larger intro, muted color. Caption / fine print. Overline label ``` <p> Regular body text. </p> <p class="af-text-body"> Explicit body role (same default as plain p). </p> <p class="af-lead"> Lead — larger intro, muted color. </p> <p class="af-text-caption"> Caption / fine print. </p> <span class="af-text-overline"> Overline label </span> ``` ### Display and marketing type [Section titled “Display and marketing type”](#display-and-marketing-type) For heroes, stats, and section labels—**still pair with a proper heading** where SEO and assistive tech need a real outline. Display, fluid headings, eyebrow, stat Product Ship faster with less CSS ## Responsive hero (fluid) 12.4k ``` <p class="af-eyebrow"> Product </p> <div class="af-text-display"> Ship faster with less CSS </div> <h1 class="af-text-fluid-h1"> Responsive hero (fluid) </h1> <p class="af-stat-display"> 12.4k </p> ``` On primary surfaces, use **`af-is-on-primary`** with `af-eyebrow` so contrast stays readable. ### Heading groups [Section titled “Heading groups”](#heading-groups) Use **`<hgroup>`** to group a heading with a subtitle or tagline (hero, card header, page title). hgroup + lead ## Invoices Review and send billing in one place. ``` <hgroup> <h1> Invoices </h1> <p class="af-lead"> Review and send billing in one place. </p> </hgroup> ``` `<hgroup>` only affects **layout**. It does not fix a wrong outline: keep **h1 → h2 → h3** order meaningful for [keyboard and screen reader users](/docs/accessibility/keyboard-focus). ### Readable line length [Section titled “Readable line length”](#readable-line-length) Wrap long-form copy in **`af-prose`** or **`af-measure`** (65ch). Narrow: **`af-measure-narrow`** (45ch). Wide: **`af-measure-wide`** (80ch). ``` <article class="af-prose"> <h2> Chapter title </h2> <p> Paragraphs stay within a comfortable measure. </p> </article> ``` ### Blockquote [Section titled “Blockquote”](#blockquote) ``` <blockquote> <p> Quoted statement with default blockquote styling. </p> </blockquote> ``` ### Inline code [Section titled “Inline code”](#inline-code) ``` <p> Use <code> const x = 1 </code> inside sentences. </p> ``` ## Utility class groups [Section titled “Utility class groups”](#utility-class-groups) Sizing, alignment, wrapping, and numeric helpers live in dedicated pages: * **[Text style](/docs/utilities/typography/text-style)** — `af-text-muted`, `af-text-sm` / `md` / `lg`, `af-title`, `af-text-strong`, … * **[Text wrapping & clamp](/docs/utilities/typography/text-wrap)** — `af-text-nowrap`, `af-text-break`, `af-clamp*` * **[Text alignment](/docs/utilities/typography/text-align)** — `af-text-center`, `af-text-start`, `af-text-end` * **[Numeric](/docs/utilities/typography/numeric)** — `af-numeric` ## Related [Section titled “Related”](#related) * [Typography guide](/docs/typography) — philosophy, tokens, PostCSS typography output * [Tokens](/docs/tokens) — `--af-type-*` and font variables

# Numeric

> Numeric typography utilities

Utilities for numeric typography (tabular numerals). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------ | ------------------------------------ | | `af-numeric` | `font-variant-numeric: tabular-nums` | ## Examples [Section titled “Examples”](#examples) Tabular numerals 1,234.56 98,765.43 ``` <div style="display:grid; gap: var(--af-space-2);"> <div class="af-numeric"> 1,234.56 </div> <div class="af-numeric"> 98,765.43 </div> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-numeric` (tabular numerals) ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All numeric utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Text wrapping & clamp](/docs/utilities/typography/text-wrap)

# Text alignment

> Direction-aware text alignment utilities

Text alignment utilities that respect document direction (LTR/RTL). ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ---------------- | --------------------------- | | `af-text-center` | center align | | `af-text-start` | start align (LTR/RTL aware) | | `af-text-end` | end align (LTR/RTL aware) | ## Examples [Section titled “Examples”](#examples) Start/end alignment Start aligned End aligned ``` <div style="display:grid; gap: var(--af-space-2);"> <p class="af-text-start"> Start aligned </p> <p class="af-text-end"> End aligned </p> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-text-center` – Center alignment * `af-text-start` – Start alignment (RTL-safe) * `af-text-end` – End alignment (RTL-safe) ## Why `start`/`end`? [Section titled “Why start/end?”](#why-startend) * Automatically respects `[dir="ltr"]` and `[dir="rtl"]` * `start` = left in LTR, right in RTL * `end` = right in LTR, left in RTL * No JavaScript needed * Standards-compliant ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All alignment utilities support responsive variants using the `@{bp}` suffix: * `af-text-center@{bp}` * `af-text-start@{bp}` * `af-text-end@{bp}` See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Text style](/docs/utilities/typography/text-style)

# Text style

> Text sizing and typographic helper utilities

Utilities for common typographic treatments and sizes. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ----------------- | ---------------------------------------- | | `af-text-muted` | `color: var(--af-color-text-muted)` | | `af-text-mono` | `font-family: var(--af-font-code)` | | `af-text-sm` | `font-size: var(--af-text-sm)` | | `af-text-md` | `font-size: var(--af-text-md)` | | `af-text-lg` | `font-size: var(--af-text-lg)` | | `af-text-body-sm` | `font-size: var(--af-text-sm)` | | `af-text-strong` | `font-weight: var(--af-weight-semibold)` | | `af-title` | large title style (2xl + semibold) | ## Examples [Section titled “Examples”](#examples) Text size af-text-sm af-text-md af-text-lg ``` <div style="display:grid; gap: var(--af-space-2);"> <p class="af-text-sm"> af-text-sm </p> <p class="af-text-md"> af-text-md </p> <p class="af-text-lg"> af-text-lg </p> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-text-muted` * `af-text-mono` * `af-text-sm` * `af-text-md` * `af-text-lg` * `af-text-body-sm` * `af-text-strong` * `af-title` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All text style utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Text alignment](/docs/utilities/typography/text-align)

# Text wrapping & clamp

> Wrapping, breaking, and line-clamp utilities

Utilities for controlling wrapping, breaking long strings, and line clamping. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------------------------------ | ------------------------------------------------- | | `af-text-nowrap` | `white-space: nowrap` | | `af-text-break` | `overflow-wrap: anywhere; word-break: break-word` | | `af-clamp` / `af-clamp-1` | 1-line clamp | | `af-clamp-2` / `af-clamp-3` / `af-clamp-4` | multi-line clamp | ## Available classes [Section titled “Available classes”](#available-classes) * `af-text-nowrap` * `af-text-break` * `af-clamp` / `af-clamp-1` (equivalent - clamp to 1 line) * `af-clamp-2` / `af-clamp-3` / `af-clamp-4` ## Examples [Section titled “Examples”](#examples) Clamp to 2 lines A long paragraph that will be clamped to two lines. Add enough text and you’ll see it truncate after the second line. ``` <p class="af-clamp-2 af-p-sm" style="max-width: 20rem;"> A long paragraph that will be clamped to two lines. Add enough text and you'll see it truncate after the second line. </p> ``` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All wrapping utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Numeric](/docs/utilities/typography/numeric)

# Visibility & State Utilities

> Visibility, state helpers, accessibility, and border utilities

Utilities for responsive visibility, state helpers, and “UI primitives” like border width, radius, and shadow. ## Class groups [Section titled “Class groups”](#class-groups) * **[Border width](/docs/utilities/visibility/border-width)**: `af-border`, `af-border-0` * **[Radius](/docs/utilities/visibility/radius)**: `af-radius-*` * **[Shadow](/docs/utilities/visibility/shadow)**: `af-shadow-*` * **[State helpers](/docs/utilities/visibility/state)**: `af-is-*`, `af-has-*` * **[Visibility](/docs/utilities/visibility/visibility)**: `af-hidden*`, `af-show*` Screen reader utilities (`af-sr-only`, `af-sr-only-focusable`) are documented in [Screen Reader Utilities](/docs/accessibility/screen-readers). For border colors, see [Color Utilities](/docs/utilities/colors).

# Border width

> Border width utilities

Utilities for enabling/disabling borders. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------- | ------------------------------------------------------------- | | `af-border` | `border: var(--af-border-width) solid var(--af-color-border)` | | `af-border-0` | `border: 0` | ## Examples [Section titled “Examples”](#examples) Border on/off af-border af-border-0 ``` <div class="af-border af-radius-md af-p-sm"> af-border </div> <div class="af-border-0 af-radius-md af-p-sm"> af-border-0 </div> ``` For border colors, see [Border color](/docs/utilities/colors/border-color). ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) Responsive variants are not generated for `af-border-0`. Note: `af-border@{bp}` exists but only sets `border-color` (it won’t “turn on” a border by itself). See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Border color](/docs/utilities/colors/border-color)

# Radius

> Border radius utilities

Utilities for border radius. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ---------------- | ------------------------------------ | | `af-radius-sm` | `border-radius: var(--af-radius-sm)` | | `af-radius-md` | `border-radius: var(--af-radius-md)` | | `af-radius-lg` | `border-radius: var(--af-radius-lg)` | | `af-radius-full` | `border-radius: 9999px` | ## Examples [Section titled “Examples”](#examples) Radius af-radius-sm af-radius-lg ``` <div class="af-bg-primary-soft af-radius-sm af-p-sm"> af-radius-sm </div> <div class="af-bg-primary-soft af-radius-lg af-p-sm"> af-radius-lg </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-radius-sm` * `af-radius-md` * `af-radius-lg` * `af-radius-full` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All radius utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Shadow](/docs/utilities/visibility/shadow)

# Shadow

> Shadow utilities

Utilities for shadows. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | -------------- | --------------------------------- | | `af-shadow-sm` | `box-shadow: var(--af-shadow-sm)` | | `af-shadow-md` | `box-shadow: var(--af-shadow-md)` | | `af-shadow-lg` | `box-shadow: var(--af-shadow-lg)` | ## Examples [Section titled “Examples”](#examples) Shadow af-shadow-sm ``` <div class="af-bg-surface af-radius-md af-shadow-sm af-p-sm"> af-shadow-sm </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-shadow-sm` * `af-shadow-md` * `af-shadow-lg` ## Responsive variants [Section titled “Responsive variants”](#responsive-variants) All shadow utilities support responsive variants using the `@{bp}` suffix. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Radius](/docs/utilities/visibility/radius)

# State helpers

> State helper utilities

Utilities for communicating state in the DOM. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ---------------- | --------------------------------------------------------- | | `af-is-disabled` | `opacity: 0.6; cursor: not-allowed; pointer-events: none` | | `af-is-loading` | `opacity: 0.7; pointer-events: none` | | `af-is-active` | `opacity: 0.9` | | `af-is-muted` | `opacity: 0.6` | | `af-has-error` | `border-color: var(--af-color-danger)` | | `af-has-focus` | `border-color: var(--af-color-primary)` | ## Examples [Section titled “Examples”](#examples) Disabled Disabled ``` <button class="af-btn af-is-disabled"> Disabled </button> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-is-disabled` * `af-is-loading` * `af-is-active` * `af-is-muted` * `af-has-error` * `af-has-focus` ## Related [Section titled “Related”](#related) * [Visibility](/docs/utilities/visibility/visibility)

# Visibility

> Responsive show/hide utilities

Utilities for controlling whether content is shown or hidden. ## Quick reference [Section titled “Quick reference”](#quick-reference) | Class | Styles | | ------------------------------------------- | ------------------------------- | | `af-hidden` | `display: none !important` | | `af-show` | `display: revert !important` | | `af-hidden@{bp}` / `af-show@{bp}` | apply from breakpoint and up | | `af-hidden@{bp}-only` / `af-show@{bp}-only` | apply only for given breakpoint | ## Examples [Section titled “Examples”](#examples) Basic Visible Hidden ``` <div style="display:grid; gap: var(--af-space-2);"> <div class="af-show af-bg-primary-soft af-radius-sm af-p-sm"> Visible </div> <div class="af-hidden af-bg-primary-soft af-radius-sm af-p-sm"> Hidden </div> </div> ``` ## Available classes [Section titled “Available classes”](#available-classes) * `af-hidden` * `af-show` * `af-hidden@xs` through `af-hidden@2xl` (applies from breakpoint and up) * `af-show@xs` through `af-show@2xl` (applies from breakpoint and up) * `af-hidden@xs-only` through `af-hidden@xl-only` (applies only at specific breakpoint range) * `af-show@xs-only` through `af-show@xl-only` (applies only at specific breakpoint range) ## Breakpoint-only ranges [Section titled “Breakpoint-only ranges”](#breakpoint-only-ranges) * `@xs-only`: 360px - 639px * `@sm-only`: 640px - 767px * `@md-only`: 768px - 1023px * `@lg-only`: 1024px - 1279px * `@xl-only`: 1280px - 1535px ## Responsive design [Section titled “Responsive design”](#responsive-design) Visibility utilities are built around the `@{bp}` and `@{bp}-only` suffixes. See [Responsive Suffix](/docs/responsive-suffix) for syntax and breakpoints. ## Related [Section titled “Related”](#related) * [Display](/docs/utilities/display/display) * [Responsive Suffix](/docs/responsive-suffix)