# BYU OIT Design System

> A CSS-first design system for BYU applications. This self-contained document is generated and distributed with the compiled stylesheets for use by coding agents and other automated consumers.

Use semantic HTML and native browser behavior first. The component documentation below describes supported markup, behavior, accessibility requirements, and CSS custom properties. Use `byu.css` during development or `byu.min.css` for the equivalent minified stylesheet.

## Included documentation

- src/css/accordion.md
- src/css/badge.md
- src/css/breadcrumbs.md
- src/css/button.md
- src/css/card.md
- src/css/checkbox.md
- src/css/chip.md
- src/css/code.md
- src/css/color.md
- src/css/dialog.md
- src/css/dropdown.md
- src/css/file.md
- src/css/footer.md
- src/css/form.md
- src/css/header.md
- src/css/icon.md
- src/css/input.md
- src/css/layout.md
- src/css/loading.md
- src/css/nav.md
- src/css/pagination.md
- src/css/progress.md
- src/css/radio.md
- src/css/range.md
- src/css/select.md
- src/css/stepper.md
- src/css/switch.md
- src/css/table.md
- src/css/textarea.md
- src/css/tooltip.md
- src/css/typography.md
- src/js/card.md

---

<!-- Source: src/css/accordion.md -->

# Accordion

## Overview

The accordion component presents grouped disclosure content through native `<details>` and `<summary>` elements.

The component is fully classless. It styles native `<details>` and `<summary>` markup directly so authors can keep the structure semantic and minimal.

## Usage

```html
<details open>
  <summary>What is included?</summary>
  <div>
    <p>Shared theme tokens, component CSS, and semantic HTML examples.</p>
  </div>
</details>

<hr />

<details>
  <summary>Does it need JavaScript?</summary>
  <div>
    <p>No. The interaction uses native disclosure behavior.</p>
  </div>
</details>
```

Use this component when the user needs to scan several short sections and expand only the ones they care about.

Use nav, a stepper, or a table instead when the content should stay visible side by side, represent sequence, or compare values across rows and columns.

Add `<hr />` between items when the design expects a visible divider. It now renders as a subtle system border, while surrounding layout still controls spacing.

The summary text should stay short and descriptive enough to make sense on its own.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- ACC-001: The component uses native disclosure semantics and keyboard behavior from `<details>` and `<summary>`.
- ACC-002: Multiple items may stay open at the same time.
- ACC-003: Comfortable and compact density come from the shared layout theme tokens instead of accordion-specific theme branches.
- ACC-004: The summary row keeps a visible focus treatment and a rotating disclosure icon without extra markup.
- ACC-005: Content should accept normal block flow such as paragraphs, lists, and small form groups without requiring named inner wrappers.
- ACC-006: Dividers are opt-in. Authors provide `<hr />` wherever they want a subtle border between items.
- ACC-007: Visual emphasis should come from shared accent, text, and primary tokens rather than one-off component colors.
## Accessibility

- Use a native `<summary>` as the interactive label for each panel.
- Keep the summary concise so it remains understandable when announced on its own.
- Group related accordions in a labeled container only when the set needs extra page-level context or an accessible name.
- Do not replace the native summary interaction with nested buttons or links.
- Do not rely on the disclosure icon alone to communicate open and closed state.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--accordion-accent-color` | `<color>` | Sets the color for disclosure icons and highlighted summary text; change it when the accordion accent should differ from the surrounding text accent. |
| `--accordion-color-focus-ring` | `<color>` | Sets --accordion-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-content-color` | `<color>` | Sets the text color for expanded accordion content; change it when body copy inside panels needs a different contrast treatment. |
| `--accordion-control-gap` | `<length>` | Sets --accordion-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-min-height` | `<length>` | Sets --accordion-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-padding-block` | `<length>` | Sets --accordion-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-control-padding-inline` | `<length>` | Sets --accordion-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-focus-ring-size` | `<length>` | Sets --accordion-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-font-family-sans` | `Any` | Sets --accordion-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-font-size` | `<length>` | Sets --accordion-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-icon-font-family` | `Any` | Sets --accordion-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-icon-size` | `<length>` | Sets the disclosure icon font size; change it to make the open and closed indicators larger or smaller without changing summary text size. |
| `--accordion-line-height` | `<number>` | Sets --accordion-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-space-inline` | `<length>` | Sets --accordion-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--accordion-summary-color` | `<color>` | Sets the default summary label color; change it when collapsed accordion headings need stronger or subtler emphasis. |

## Depends On

- `--color-focus-ring`
- `--color-text`
- `--color-text-accent`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--icon-font-family`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/badge.md -->

# Badge

## Overview

The badge component presents short inline labels, status values, metadata, and rendered token values with a compact rounded visual treatment.

Use `span.badge` for display-only content. Use chips when the user is choosing checkbox or radio values.

## Usage

For a default brand badge, omit `data-variant`:

```html
<span class="badge">Featured</span>
```

For a status or low-emphasis badge, use `data-variant`:

```html
<span class="badge" data-variant="success">Approved</span>
<span class="badge" data-variant="warning">Pending</span>
<span class="badge" data-variant="unavailable">Unavailable</span>
```

Badges can include an optional leading icon through the shared `.icon` pattern:

```html
<span class="badge" data-variant="success">
  <span class="icon" aria-hidden="true">check_circle</span>
  <span>Approved</span>
</span>
```

Use badges when the interface needs a short read-only label, status, metadata token, or rendered token value.

Use chips when a checkbox or radio group should scan like compact chips while keeping native form behavior.

Use a future token input pattern, not a standalone badge, when the user needs to enter, parse, remove, validate, or submit a comma-, tab-, newline-, or space-separated set of tokens.

Do not use `a.badge` or `button.badge`; link badges and button badges are not part of this component's public API.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- BDG-001: The default badge and `data-variant="brand"` use a filled brand treatment.
- BDG-002: `info`, `success`, `warning`, `error`, and `unavailable` variants use a subtle background with strong-color text and border.
- BDG-003: Individual badges stay on one line; use `.cluster` to wrap groups of badges.
- BDG-004: Badges use a fixed pill radius by default and can override it with `--badge-border-radius`.
## Accessibility

- Use `span.badge` only for display content.
- Keep badge text short and descriptive.
- Mark decorative icons with `aria-hidden="true"`.
- Do not rely on color alone when a status value needs to communicate critical information; include clear text.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--badge-background` | `<color>` | Sets the badge fill color for the default and status variants; change it to tune the visual weight of the badge surface. |
| `--badge-border-color` | `<color>` | Sets the badge outline color; change it when the border needs to separate the badge from nearby surfaces or match a status color. |
| `--badge-border-radius` | `<length>` | Sets the badge corner shape; change it to move badges from pill-shaped labels toward a squarer product style. |
| `--badge-border-width` | `<length>` | Sets the badge surface border width; change it when badges need a stronger or subtler edge. |
| `--badge-color` | `<color>` | Sets the badge text and icon color; change it when the fill or border color requires a different contrast pairing. |
| `--badge-control-gap` | `<length>` | Sets --badge-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-control-padding-inline` | `<length>` | Sets --badge-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-family-sans` | `Any` | Sets --badge-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-size` | `<length>` | Sets --badge-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-font-size-caption` | `<length>` | Sets --badge-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--badge-icon-size` | `<length>` | Sets the size passed to icons inside badges; change it when icons should read larger or smaller than the label text. |
| `--badge-line-height` | `<number>` | Sets --badge-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-error-strong`
- `--color-error-subtle`
- `--color-info-strong`
- `--color-info-subtle`
- `--color-primary`
- `--color-success-strong`
- `--color-success-subtle`
- `--color-text-inverse`
- `--color-unavailable-strong`
- `--color-unavailable-subtle`
- `--color-warning-strong`
- `--color-warning-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-gap`
- `--layout-control-padding-inline`
- `--layout-surface-border-width`

---

<!-- Source: src/css/breadcrumbs.md -->

# Breadcrumbs

## Overview

The breadcrumbs component presents the current page's position inside a hierarchy as a classless ordered list of links.

It styles a native `<nav aria-label="breadcrumb">` with a direct child `<ol>`. Separators are inserted by CSS, so authors only provide the hierarchy items.

Use nav instead when users need to move between peer destinations. Use pagination when the controls move through paged table results.

## Usage

```html
<nav aria-label="breadcrumb">
  <ol>
    <li><a href="/docs">Docs</a></li>
    <li><a href="/docs/components">Components</a></li>
    <li><span aria-current="page">Breadcrumbs</span></li>
  </ol>
</nav>
```

Use breadcrumbs when the interface needs to show where the current page sits within a hierarchy.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- BCR-001: Breadcrumbs render as an inline ordered trail with separators inserted by CSS.
- BCR-002: Links use the text accent color by default.
- BCR-003: Separators use the subtle border color by default.
- BCR-004: Separators render as the `chevron_forward` icon.
- BCR-005: The item marked with `aria-current`, or the last item when no item is marked current, uses the default text color.
- BCR-006: The trail can wrap by default.
- BCR-007: Current-location items should be identified with `aria-current` and remain visually distinct from sibling links.
- BCR-008: Comfortable and compact density come from the shared layout tokens for min-height, padding, and gap.
- BCR-009: The component relies on native `nav`, ordered-list, and link structure instead of requiring component-specific classes.
## Accessibility

- Use a native `<nav>` with `aria-label="breadcrumb"`.
- Prefer an ordered list because the sequence communicates hierarchy and current location.
- Keep breadcrumb destinations as real `<a>` elements.
- Use `aria-current="page"` or `aria-current="location"` for the current item.
- Keep `aria-label="breadcrumb"` exactly on the breadcrumb navigation element so the breadcrumb selector activates.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--breadcrumb-color-focus-ring` | `<color>` | Sets --breadcrumb-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-gap` | `<length>` | Sets --breadcrumb-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-min-height` | `<length>` | Sets --breadcrumb-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-control-padding-block` | `<length>` | Sets --breadcrumb-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-current-color` | `<color>` | Sets the color for the current page crumb; change it when the final crumb should be more or less prominent than links. |
| `--breadcrumb-focus-ring-size` | `<length>` | Sets --breadcrumb-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-font-family-sans` | `Any` | Sets --breadcrumb-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-font-size` | `<length>` | Sets --breadcrumb-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-fill` | `<number>` | Sets --breadcrumb-icon-fill so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-font-family` | `Any` | Sets --breadcrumb-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-grad` | `<number>` | Sets --breadcrumb-icon-grad so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-opsz` | `<number>` | Sets --breadcrumb-icon-opsz so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-size` | `<length>` | Sets --breadcrumb-icon-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-icon-wght` | `<number>` | Sets --breadcrumb-icon-wght so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-line-height` | `<number>` | Sets --breadcrumb-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--breadcrumb-link-color` | `<color>` | Sets the default breadcrumb link color; change it to match the navigation context or a contrasting header surface. |
| `--breadcrumb-link-hover-color` | `<color>` | Sets the hover color for breadcrumb links; change it when links need a stronger interactive state than their resting color. |
| `--breadcrumb-separator-color` | `<color>` | Sets the color of separators between crumbs; change it when dividers should recede or align with nearby border tokens. |

## Depends On

- `--color-border-subtle`
- `--color-focus-ring`
- `--color-text`
- `--color-text-accent`
- `--color-text-accent-strong`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--icon-fill`
- `--icon-font-family`
- `--icon-grad`
- `--icon-opsz`
- `--icon-size`
- `--icon-wght`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-focus-ring-size`

---

<!-- Source: src/css/button.md -->

# Button

## Overview

The button component is a clickable control for actions such as submitting a form, confirming a choice, or triggering a UI change.

The component styles a native `<button>` element directly, with optional inline icon content when the action needs a visual cue in addition to text.

## Usage

```html
<button type="button">Primary Button</button>
```

```html
<button type="button" style="--button-border-radius: 999px;">Rounded Button</button>
```

For a secondary action that should stay visually distinct from the primary fill, use the `secondary` helper:

```html
<button class="secondary" type="button">Secondary Button</button>
```

For a lower-emphasis action that should read as lighter-weight while keeping button affordances, use the `tertiary` helper:

```html
<button class="tertiary" type="button">Tertiary Button</button>
```

For a destructive action that should stand out from brand-colored actions, use the `error` helper:

```html
<button class="error" type="button">Delete Item</button>
```

Buttons marked with `aria-active="true"` use the primary filled treatment:

```html
<button aria-active="true" type="button">Active View</button>
```

When a button includes an icon, use the Material Symbols icon font through the shared `.icon` element pattern:

```html
<button type="button">
  <span class="icon" aria-hidden="true">add</span>
  <span>Create Item</span>
</button>
```

For icon-only buttons, apply the `.icon` class directly to the button and provide an accessible name:

```html
<button class="icon" type="button" aria-label="Add item">add</button>
```

For buttons with a loading indicator, use `aria-busy="true"` and keep an action-specific visible label. Add `disabled` when the action must not be triggered again while it is processing:

```html
<button disabled aria-busy="true" type="button">Saving…</button>
```

Button loaders render at `75%` of `--button-icon-size`. Typical SVG icons include internal padding within their view box, while the CSS loading ring fills its entire box; the reduction gives both a comparable optical size. Keeping the loader derived from the icon token also preserves consistent button dimensions between busy buttons and the icon button variant when the shared icon size changes.

When space is constrained, an empty busy button centers the loading indicator. Provide its action-specific accessible name with `aria-label`:

```html
<button disabled aria-busy="true" type="button" aria-label="Saving report"></button>
```

Use this component when the user needs to trigger an immediate action.

Use a link instead when the interaction navigates to another page or location.

Use a navigation pattern instead when the interface needs a row of destination choices such as section links or a primary page bar, even if the visual treatment looks similar to grouped controls.

Button text should describe the action clearly and work without relying on surrounding context.

The button should use a native `<button>` element so it keeps keyboard behavior, disabled state support, and expected form interactions.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- BTN-001: The button should size from its content, padding, and border radius rather than a fixed width.
- BTN-002: Buttons should reserve a `0.125rem` border in every variant so switching visual treatments does not change the outer size.
- BTN-003: Buttons should use vertical padding that resolves with the reserved border to `0.75rem` of occupied space per side.
- BTN-004: Buttons can override the shared control radius with `--button-border-radius` when an action needs a different corner treatment.
- BTN-005: Enabled buttons should show the pointer cursor to reinforce that the control is clickable, while disabled buttons should not.
- BTN-006: Primary buttons should keep the primary filled treatment on hover and move to the strong primary tone when pressed.
- BTN-007: Button text should either match the button's visible surface or stroke color, or use the inverse text color when the button is filled.
- BTN-008: Secondary buttons should keep a visible accent-text stroke with a matching label until pressed, then use the same strong pressed fill and inverse label as the primary button.
- BTN-009: Tertiary buttons should stay borderless with accent text by default, show a subtle primary stroke on hover, and keep the accent label on the subtle primary pressed fill.
- BTN-010: Button color changes should transition smoothly, with reduced-motion preferences disabling the transition.
- BTN-011: Focus-visible should use each variant's hover treatment and add a visible ring.
- BTN-012: Error buttons should use the error color scale so destructive actions remain visually distinct from primary actions.
- BTN-013: Buttons with `aria-active="true"` should use the primary filled treatment so the active choice reads with stronger emphasis.
- BTN-014: Disabled primary and tertiary buttons should use the disabled accent fill, while disabled secondary buttons should keep a visible neutral stroke.
- BTN-015: Buttons with icons should keep the icon inline with the label and adjust spacing without requiring a separate variant class.
- BTN-016: Busy buttons should keep disabled visual styling when disabled, use the wait cursor, and space the generated loading indicator consistently with an inline icon.
- BTN-017: Icon-only buttons should use the same vertical padding as text buttons, remain square, center the glyph, and keep an accessible name through `aria-label` when no visible text is present.
- BTN-018: Buttons should not be used as stand-ins for destination navigation just because the interface groups them horizontally.
- BTN-019: Empty busy buttons should remain square, center the generated loading indicator, and require an accessible name such as `aria-label`.
## Accessibility

- Use a native `<button>` for actions so keyboard and assistive technology behavior stays intact.
- Provide an explicit `type` when the button appears in a form so submit behavior is intentional.
- Keep the visible label descriptive enough to stand on its own.
- Mark decorative icons with `aria-hidden="true"` so they do not add noise to the accessible name.
- Use `aria-busy="true"` only while an action is processing, and remove it when the action finishes.
- Pair `aria-busy="true"` with `disabled` when repeated activation must be prevented; `aria-busy` does not disable the button by itself.
- Do not rely on color alone to communicate disabled or pressed state.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--button-action-padding-block` | `<length>` | Sets --button-action-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-action-padding-inline` | `<length>` | Sets --button-action-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-active-background` | `<color>` | Sets the pressed or active fill color; change it when active buttons need a stronger, weaker, or variant-specific state surface. |
| `--button-active-border-color` | `<color>` | Sets the pressed or active border color; change it with the active background when the button outline should track state changes. |
| `--button-active-color` | `<color>` | Sets the pressed or active label and icon color; change it when the active surface needs a different contrast color. |
| `--button-background` | `<color>` | Sets the resting fill color for filled button variants; change it to create primary, danger, or contextual button treatments. |
| `--button-border-color` | `<color>` | Sets the resting border color; change it for outlined variants or when the button edge needs different emphasis from the fill. |
| `--button-border-radius` | `<length>` | Sets the button corner radius and grouped-control radius; change it to make buttons more rounded, squared, or search-pill shaped. |
| `--button-border-width` | `<length>` | Sets the button stroke width and contributes to computed height; change it when buttons need a heavier or lighter outline. |
| `--button-color` | `<color>` | Sets the resting label and icon color; change it when the button background or border treatment requires a different contrast color. |
| `--button-color-focus-ring` | `<color>` | Sets --button-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-control-gap` | `<length>` | Sets --button-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-control-radius` | `<length>` | Sets --button-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-disabled-background` | `<color>` | Sets the disabled fill color; change it when unavailable actions should appear more subtle or keep a transparent surface. |
| `--button-disabled-border-color` | `<color>` | Sets the disabled border color; change it when disabled outlined buttons need a visible but noninteractive edge. |
| `--button-disabled-color` | `<color>` | Sets the disabled label and icon color; change it to keep disabled text legible while still reading inactive. |
| `--button-focus-ring-size` | `<length>` | Sets --button-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-font-family-sans` | `Any` | Sets --button-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-font-size` | `<length>` | Sets --button-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-height` | `<length>` | Sets the minimum button height after padding, line-height, and border space are combined; change it to tune control density. |
| `--button-hover-background` | `<color>` | Sets the hover fill color; change it when pointer hover should preview a stronger or subtler interaction state. |
| `--button-hover-border-color` | `<color>` | Sets the hover border color; change it when outlined or filled buttons need a distinct pointer affordance. |
| `--button-hover-color` | `<color>` | Sets the hover label and icon color; change it when the hover surface needs a different contrast pairing. |
| `--button-hover-scale-inline` | `<number>` | Sets the horizontal scale applied on hover; change it to adjust or remove the slight expansion interaction. |
| `--button-icon-fill` | `<number>` | Sets --button-icon-fill so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-icon-font-family` | `Any` | Sets --button-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-icon-grad` | `<number>` | Sets --button-icon-grad so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-icon-opsz` | `<number>` | Sets --button-icon-opsz so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--button-icon-size` | `<length>` | Sets the font size for icons and busy indicators in buttons; change it when icon glyphs should differ from the control text scale. |
| `--button-icon-wght` | `<number>` | Sets --button-icon-wght so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-accent-disabled`
- `--color-border`
- `--color-error`
- `--color-focus-ring`
- `--color-primary`
- `--color-primary-strong`
- `--color-primary-subtle`
- `--color-text-accent`
- `--color-text-inverse`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--icon-fill`
- `--icon-font-family`
- `--icon-grad`
- `--icon-opsz`
- `--icon-wght`
- `--layout-action-padding-block`
- `--layout-action-padding-inline`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- [Loading](./loading.md)

---

<!-- Source: src/css/card.md -->

# Card

## Overview

The card component presents a self-contained `<article>` or `<figure>` on a contained surface with a subtle shadow.

The component styles native `<article>` and `<figure>` elements directly so authors can use semantic markup without an extra component class.

For exact card styles, use [card.css](./card.css) as the source of truth.

## Usage

```html
<article aria-labelledby="card-title">
  <header>
    <h3 id="card-title">Quarterly update</h3>
    <p>Shared token adoption is now the default path for new components.</p>
  </header>

  <p>The card groups short related content into a single readable surface without requiring extra presentational wrappers.</p>

  <footer>
    <button class="secondary" type="button">Review</button>
    <button type="button">Publish</button>
  </footer>
</article>
```

```html
<figure aria-labelledby="chart-card-title">
  <img src="adoption-chart.png" alt="Token adoption increased across three releases.">
  <figcaption id="chart-card-title">Token adoption trend</figcaption>
</figure>
```

Images placed directly inside a figure extend through the figure's inline padding and crop with `object-fit: cover`. An image at the start or end of the figure also extends through the corresponding block padding, while captions and other content retain the card spacing.

To present a card as a flat surface without elevation, add the `flat` class to the native `<article>` or `<figure>` element:

```html
<article class="flat" aria-labelledby="flat-card-title">
  <h3 id="flat-card-title">Flat surface</h3>
  <p>This card retains its surface and subtle border without casting a shadow.</p>
</article>
```

Flat cards retain the card surface, spacing, and radius, use the subtle surface border, and do not cast a shadow in either light or dark themes.

When a card is refreshing existing content, set `aria-busy="true"` and disable any controls that must not be activated while the update is in progress:

```html
<article aria-busy="true" aria-labelledby="busy-card-title">
  <header>
    <h3 id="busy-card-title">Quarterly update</h3>
  </header>

  <p>Content is being refreshed.</p>

  <footer>
    <button type="button" disabled>Publish</button>
  </footer>
</article>
```

Remove `aria-busy` and restore the controls when the update finishes. Busy-card styling blocks pointer interaction with direct children, while native `disabled` attributes also prevent keyboard activation without removing the article's loading state from the accessibility tree.

### Alert variants

Add `data-variant` to an `<article>` to present a short status message with a generated icon. Text placed directly inside the article is laid out beside the icon and wraps within the content column:

```html
<article data-variant="error">
  Uploaded file could not be processed.
</article>
```

Supported variants are:

- `info` for neutral information
- `success` for a completed or successful action
- `warning` for a condition that may require attention
- `error` for a failed action or problem
- `unavailable` for a feature or resource that cannot currently be used

The base `data-variant` styling defaults to the informational treatment, but authors should use one of the supported values so the message's intent remains explicit.

To make an alert dismissible, set `data-closable="true"`. CSS generates the close control through the article's `::after` pseudo-element, and `card.js` removes the alert when that control is activated:

```html
<article data-variant="error" data-closable="true">Uploaded file could not be processed.</article>
```

Alert articles use a two-column grid. The first column is reserved for the circular generated icon, while the second uses `minmax(0, 1fr)` so long text wraps beside the icon instead of moving below it. The icon is created by CSS; no decorative icon element is required in the markup.

Use this component when a short piece of content needs its own surface, separation, and clear boundary from surrounding layout. Avoid using alerts excessively. In many scenarios, other indicators can be used in place of an alert.

Use a plain section, list item, or table row instead when the content is part of a continuous document flow, repeated structured data, or a layout that should stay visually flat.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- CRD-001: The card should style native `<article>` and `<figure>` elements directly rather than require a component class.
- CRD-002: Padding, radius, spacing, and foreground/background colors should come from the shared layout and color tokens.
- CRD-003: The shell should expose `--card-border-radius`, `--card-border-width`, and `--card-shadow` so its shape and elevation can be customized consistently; nested footer controls derive their inner corner radius from the shell values.
- CRD-004: The component should accept normal flow content such as headings, paragraphs, lists, and button rows.
- CRD-005: The first and last child margins should collapse cleanly against the card padding so authored content does not create uneven outer spacing.
- CRD-006: Optional `header` and `footer` regions should lay out with shared spacing tokens instead of card-specific measurements, with footer content aligned to the end.
- CRD-007: The component should work without JavaScript and without decorative helper elements inside the article.
- CRD-008: Busy cards should retain their layout while direct child content is shown at `48%` opacity with a `4px` blur.
- CRD-009: The generated loading indicator should remain sharp and centered over the dimmed content.
- CRD-010: Busy-card children should ignore pointer interaction while the update is in progress.
- CRD-011: Articles with `data-variant` should reserve a fixed-width first column for the generated icon and a flexible second column for message content.
- CRD-012: Alert text should align to the start of the icon and wrap within its own column.
- CRD-013: Dark-theme alerts should use the same inverse surface treatment as tooltips so they remain distinct from card and page backgrounds.
- CRD-014: Alert icon size, symbol size, background, and foreground should be controlled through the alert custom properties and shared design tokens.
- CRD-015: Images placed directly inside figure cards should cover their available dimensions full-bleed while captions and other figure content retain the card padding.
- CRD-016: Direct card children should be allowed to shrink within the card so intrinsically wide content can manage its own overflow without widening or clipping the page layout.
- CRD-017: Figure cards should allow descendant overlays to extend beyond the card boundary while full-bleed images preserve the card's rounded corners directly.
- CRD-018: An alert should expose a generated close control only when `data-closable="true"` is present.
- CRD-019: Clicking the generated close control or pressing Enter or Space while its alert is focused should remove only that alert without JavaScript generating child elements.
- CRD-020: Closable alerts inserted after initial page parsing should receive the same focus and dismissal behavior as alerts present when the script runs.
- CRD-021: Native article and figure cards with the `flat` class should retain their surface and subtle border while rendering without a shadow in light and dark themes.

## Accessibility

- Use `<article>` when the content is independently meaningful in the page outline or feed.
- Use `<figure>` when the card contains self-contained media, a diagram, a chart, a table, or code that benefits from a caption.
- Provide a heading when the card content benefits from a clear accessible label.
- Keep interactive controls inside the card keyboard reachable and descriptive on their own.
- Use `aria-busy="true"` only while the card is being updated, and remove it when the update finishes.
- Disable native controls individually when they must not be activated during loading; visual dimming and `pointer-events` alone do not prevent keyboard interaction.
- Do not use the shadow alone to communicate important status or state.
- Write alert text that communicates the status without relying on the generated icon or color.
- Static alert content does not need a live-region role. When a message is inserted or updated dynamically and must be announced, use `role="status"` for non-urgent information or `role="alert"` for urgent problems.
  - Do not use `role="alert"` for non-urgent information, as this will interrupt accessibility APIs.
- Do not include an additional decorative icon in alert markup; the visual icon is generated by CSS.
- JavaScript makes closable alerts focusable and supplies a dismissal description because generated content does not provide native button semantics.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--alert-background-color` | `<color>` | Sets the circular alert icon background for each alert variant; change it when status indicators need different severity colors. |
| `--alert-border-color` | `<color>` | Sets the border around dark-theme alert cards; change it when the alert surface needs more or less separation in dark contexts. |
| `--alert-icon` | `<string>` | Sets the Material Symbols glyph rendered before alert content; change it to swap the status icon for a variant. |
| `--alert-icon-size` | `<length>` | Sets the size of the circular alert icon container and its grid column; change it when the status marker should occupy more or less space. |
| `--alert-surface-background` | `<color>` | Sets the alert card surface color; change it when alert content needs a different neutral or inverted background. |
| `--alert-surface-color` | `<color>` | Sets the text color used on alert surfaces; change it when the surface background requires a different contrast color. |
| `--alert-symbol-color` | `<color>` | Sets the glyph color inside the circular alert marker; change it when the marker fill changes or warning icons need dark text. |
| `--alert-symbol-size` | `<length>` | Sets the Material Symbols glyph size inside the alert marker; change it when the symbol should be larger or smaller than the container default. |
| `--card-border-color` | `<color>` | Sets the card outline color; change it when cards need clearer separation from the page or dark-theme surfaces. |
| `--card-border-radius` | `<length>` | Sets the outer card corner radius and feeds the inner footer-button radius calculation; change it to adjust card shape globally. |
| `--card-border-width` | `<length>` | Sets the card outline width and reduces the inner radius; change it when card edges need stronger or subtler definition. |
| `--card-color-accent` | `<color>` | Sets --card-color-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-color-accent-subtle` | `<color>` | Sets --card-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-color-text` | `<color>` | Sets --card-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-control-gap` | `<length>` | Sets --card-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-control-min-height` | `<length>` | Sets --card-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-focus-ring-size` | `<length>` | Sets the focus outline width and offset for keyboard-dismissible cards; change it to align the closable-card focus treatment with its surrounding interface. |
| `--card-icon-font-family` | `Any` | Sets --card-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-shadow` | `Any` | Sets the card elevation shadow; change it to tune surface depth or disable elevation in dense layouts. |
| `--card-space-inline` | `<length>` | Sets --card-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--card-space-stack` | `<length>` | Sets --card-space-stack so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-accent`
- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-border-subtle-inverse`
- `--color-error-strong`
- `--color-info`
- `--color-primary-strong`
- `--color-success-strong`
- `--color-text`
- `--color-text-inverse`
- `--color-unavailable`
- `--color-warning`
- `--icon-font-family`
- `--icon-size`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-shadow`
- `--layout-space-inline`
- `--layout-space-stack`
- `--layout-surface-border-width`
- [Loading](./loading.md)

---

<!-- Source: src/css/checkbox.md -->

# Checkbox

## Overview

The checkbox component is a multi-select form control for toggling one or more independent options on or off.

The component pattern uses a native `<fieldset>` with a native `<legend>` and native checkbox inputs inside wrapping `<label>` elements, so the group keeps its semantics without requiring classed wrappers.

## Usage

```html
<fieldset>
  <legend>Notifications</legend>
  <label>
    <input type="checkbox" name="notifications" value="email" checked />
    Email updates
  </label>
  <label>
    <input type="checkbox" name="notifications" value="sms" />
    SMS alerts
  </label>
</fieldset>
```

Use this component when the user can select any number of independent options, including none or all of them.

Use radios instead when the user must choose exactly one option from the set.

The group should use native `<fieldset>` and `<legend>` elements so assistive technology announces the shared question and each option in context.

Each checkbox should stay inside its own wrapping `<label>` so the full text remains clickable without extra helper markup.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- CHK-001: The group stacks options with shared layout theme spacing rather than component-specific density values.
- CHK-002: Each option keeps native checkbox rendering and browser interaction while the accent color follows the shared primary token.
- CHK-003: Disabled options should dim through shared text tokens rather than bespoke disabled colors.
- CHK-004: Focus must remain clearly visible for keyboard users.
## Accessibility

- Use a native `<fieldset>` and `<legend>` for related checkbox questions instead of a plain container and heading.
- Wrap each checkbox in a native `<label>` so the label text enlarges the interactive target.
- Keep option text descriptive enough to make sense when announced on its own.
- Do not replace the native checkbox with custom scripted markup unless the product truly requires behavior the platform cannot provide.
- If helper or error text is needed, place it near the fieldset and associate it with `aria-describedby`.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--checkbox-color-primary` | `<color>` | Sets --checkbox-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-primary-subtle` | `<color>` | Sets --checkbox-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text` | `<color>` | Sets --checkbox-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text-accent` | `<color>` | Sets --checkbox-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-color-text-subtle` | `<color>` | Sets --checkbox-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-control-border-width` | `<length>` | Sets --checkbox-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-control-gap` | `<length>` | Sets --checkbox-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-focus-ring-size` | `<length>` | Sets --checkbox-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-font-family-sans` | `Any` | Sets --checkbox-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-font-size` | `<length>` | Sets --checkbox-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-line-height` | `<number>` | Sets --checkbox-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--checkbox-space-inline` | `<length>` | Sets --checkbox-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/chip.md -->

# Chip

## Overview

The chip component presents compact native selection options with a rounded visual treatment.

Use `label.chip` with a direct child checkbox or radio input when the chip is a selectable form option. Use `span.badge` for display-only labels and status values.

## Usage

Keep the native input as a direct child of the label and wrap the visible label text in a child span:

```html
<fieldset>
  <legend>Notification channels</legend>
  <div class="cluster">
    <label class="chip">
      <input type="checkbox" name="channels" value="email" checked />
      <span>Email</span>
    </label>
    <label class="chip">
      <input type="checkbox" name="channels" value="sms" />
      <span>SMS</span>
    </label>
  </div>
</fieldset>
```

Radio chips use the same label pattern:

```html
<fieldset>
  <legend>Approval priority</legend>
  <div class="cluster">
    <label class="chip">
      <input type="radio" name="priority" value="standard" checked />
      <span>Standard</span>
    </label>
    <label class="chip">
      <input type="radio" name="priority" value="expedited" />
      <span>Expedited</span>
    </label>
  </div>
</fieldset>
```

Use chips when a checkbox or radio group should scan like compact chips while keeping native form behavior.

Use the existing checkbox or radio components when the native control shape should remain visible.

Do not use the chip class on display, link, or button elements; those are not part of this component's public API.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- CHP-001: Chips hide the native checkbox or radio visually while preserving native input semantics.
- CHP-002: Checked chips use the filled brand treatment.
- CHP-003: Unchecked chips use a subtle surface and the same brand outline and text color as secondary buttons.
- CHP-004: Unchecked enabled chips use the subtle primary accent on hover.
- CHP-005: Chip color changes should transition smoothly, with reduced-motion preferences disabling the transition.
- CHP-006: Disabled chips use disabled surface and text tokens and the not-allowed cursor.
- CHP-007: Keyboard focus on a hidden selectable input appears on the visible chip surface.
- CHP-008: Individual chips stay on one line; use `.cluster` to wrap groups of chips.
- CHP-009: Chips use a fixed pill radius by default and can override it with `--chip-border-radius`.
- CHP-010: Chip groups suppress native fieldset border, margin, and padding so they match checkbox and radio group chrome.
## Accessibility

- Use native checkbox and radio inputs for chips so form submission, grouping, disabled state, and assistive technology semantics remain intact.
- Group chips in a native `<fieldset>` with a `<legend>`.
- Keep chip text short and descriptive.
- Mark decorative icons with `aria-hidden="true"`.
- Do not rely on color alone when a status value needs to communicate critical information; include clear text.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--chip-background` | `<color>` | Sets the chip fill color for resting, selected, and disabled states; change it to tune the chip treatment for a status or selection context. |
| `--chip-border-color` | `<color>` | Sets the chip outline color; change it when selectable chips need more or less edge contrast. |
| `--chip-border-radius` | `<length>` | Sets the chip corner shape; change it to move chips away from the default pill treatment. |
| `--chip-color` | `<color>` | Sets the chip label and icon color; change it when the fill or selected state needs a different contrast pairing. |
| `--chip-color-focus-ring` | `<color>` | Sets --chip-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-color-text` | `<color>` | Sets the chip group text color; change it when chip group chrome needs a different foreground role. |
| `--chip-color-text-accent` | `<color>` | Sets the chip group legend color; change it when chip groups need stronger or subtler label emphasis. |
| `--chip-control-border-width` | `<length>` | Sets --chip-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-control-gap` | `<length>` | Sets --chip-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-control-padding-inline` | `<length>` | Sets --chip-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-focus-ring-size` | `<length>` | Sets --chip-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-family-sans` | `Any` | Sets --chip-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-size` | `<length>` | Sets --chip-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-size-caption` | `<length>` | Sets --chip-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-hover-scale-inline` | `<number>` | Sets the horizontal scale applied to interactive chips on hover; change it to adjust or remove the expansion affordance. |
| `--chip-icon-size` | `<length>` | Sets the icon size inside chips; change it when chip icons should be balanced differently against the label text. |
| `--chip-line-height` | `<number>` | Sets --chip-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-accent-disabled`
- `--color-accent-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--color-text-inverse`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-padding-inline`
- `--layout-focus-ring-size`

---

<!-- Source: src/css/code.md -->

# Code

## Overview

The code module styles inline code, block code examples, and Highlight.js syntax tokens.

This module is optional. It is not included in the main `byu.css` component bundle. Use `byu-code.css` only on pages that render code examples or syntax-highlighted snippets.

## Basic Usage

Use inline code for short technical terms, token names, file names, or literal values:

```html
<p>Use <code>--font-size</code> to set the base type scale.</p>
```

Use a direct `<pre><code>` pair with an explicit language class for code examples:

```html
<pre><code class="language-html">&lt;button type="button"&gt;Save&lt;/button&gt;</code></pre>
```

Code blocks wrap long lines by default. When preserving each source line is more important, add `overflow-auto` to `pre` and make the resulting scroll region keyboard focusable:

```html
<pre class="overflow-auto" tabindex="0"><code class="language-html">&lt;button type="button"&gt;Save&lt;/button&gt;</code></pre>
```

## Syntax Highlighting

For syntax highlighting, add a Highlight.js language class and load the Highlight.js runtime separately:

```html
<script src="vendor/highlightjs/highlight.min.js" defer></script>
<script src="highlight-init.js" defer></script>

<pre><code class="language-html">&lt;button type="button"&gt;Save&lt;/button&gt;</code></pre>
```

The design system does not require Highlight.js, but `byu-code.css` includes a project-owned visual theme for Highlight.js token classes such as `.hljs-keyword`, `.hljs-string`, and `.hljs-attr`.

If your application uses Highlight.js, configure it to add the standard `hljs` classes and language token classes. The documentation site uses:

```js
document.addEventListener("DOMContentLoaded", () => {
  if (!window.hljs) {
    return;
  }

  window.hljs.configure({
    languages: ["xml", "css", "javascript"]
  });
  window.hljs.highlightAll();
});
```

Do not load a separate Highlight.js theme stylesheet alongside `byu-code.css`; the code bundle is the syntax theme.

## Configuration

The code bundle follows the active design-system color theme through CSS variables. Set the same theme attribute used by the main bundle:

```html
<html lang="en" data-color-theme="dark">
```

Override code-specific variables locally when a product needs a different syntax palette:

```css
.developer-docs {
  --code-token-string: #0f5f2e;
  --code-token-title: #5f3dc4;
}
```

Keep overrides above WCAG AA contrast against `--code-background`.

Use this module when documentation, examples, or developer tooling pages need readable code presentation.

Do not include `byu-code.css` on pages that do not render code; keep the module opt-in so application bundles do not pay for syntax styles they do not use.

## Behavior

Covered by [Playwright accessibility tests](../../tests/e2e/accessibility.spec.js).

- COD-001: Code examples preserve indentation and line breaks while wrapping long lines instead of creating horizontal scroll regions by default.
- COD-002: Inline code inherits the surrounding text flow and uses the shared monospace stack.
- COD-003: Code blocks use the semantic code surface token, border token, and shared control radius.
- COD-004: Highlight.js token colors are project-owned and theme-aware through CSS variables.
- COD-005: Highlight.js theme styles are not bundled or loaded separately; `byu-code.css` is the syntax theme.
- COD-006: The code module is emitted as `byu-code.css` and `byu-code.min.css`, separate from `byu.css`.
- COD-007: Applying `.overflow-auto` to `pre` preserves source lines without wrapping and delegates overflow scrolling to the shared layout utility.

## Accessibility

- Code blocks wrap long lines by default so keyboard users do not need to reach a horizontal scroll region.
- When using `.overflow-auto`, add `tabindex="0"` to `pre` so keyboard users can reach and operate the scroll region.
- Syntax token colors must meet WCAG AA contrast in both light and dark themes.
- Do not rely on syntax color alone to communicate required information; code should remain understandable as plain text.
- Keep examples concise enough to scan, especially on narrow viewports where long lines wrap.
- Load the Highlight.js runtime only when syntax tokenization is needed. Without it, `<pre><code>` remains readable plain text.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--code-background` | `<color>` | Sets the background for inline code and code blocks; change it when code samples need stronger contrast from surrounding content. |
| `--code-border-radius` | `<length>` | Sets the corner radius for inline code and code blocks; change it to align code samples with a sharper or softer surface style. |
| `--code-border-width` | `<length>` | Sets the border width for block-code surfaces; change it when code blocks need a stronger or subtler edge. |
| `--code-color-border-subtle` | `<color>` | Sets --code-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--code-color-text` | `<color>` | Sets --code-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--code-token` | `<color>` | Sets the fallback syntax-highlight color for unclassified code tokens; change it to adjust the base code text color. |
| `--code-token-attribute` | `<color>` | Sets the syntax-highlight color for attributes and selector-like metadata; change it when attribute tokens need different emphasis. |
| `--code-token-keyword` | `<color>` | Sets the syntax-highlight color for language keywords; change it to rebalance keyword emphasis in light and dark code themes. |
| `--code-token-literal` | `<color>` | Sets the syntax-highlight color for literals such as numbers, booleans, and constants; change it to distinguish data values more clearly. |
| `--code-token-muted` | `<color>` | Sets the syntax-highlight color for comments and subdued tokens; change it when secondary code text is too prominent or too faint. |
| `--code-token-name` | `<color>` | Sets the syntax-highlight color for names such as tags, selectors, or identifiers; change it to tune structural token emphasis. |
| `--code-token-string` | `<color>` | Sets the syntax-highlight color for strings; change it when quoted values need more or less visual distinction. |
| `--code-token-title` | `<color>` | Sets the syntax-highlight color for titles, functions, and emphasized identifiers; change it to adjust high-salience code tokens. |

## Depends On

- `--color-accent`
- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-text`
- `--layout-control-radius`
- `--layout-surface-border-width`

---

<!-- Source: src/css/color.md -->

# Color Tokens

## Overview

The repo currently defines two color themes:

- `light`: the default color theme
- `dark`: a dark mode theme using the BYU navy background, softened blue accents, and brighter status colors

Color themes are defined in [color.css](/Users/stuft2/Projects/design-system/src/css/color.css) and are applied with the `data-color-theme` attribute when needed.

Both themes define semantic utility color families for `info`, `success`, `warning`, `error`, and `unavailable`.

Each color family has one authored default token. Strong and subtle variants are calculated from that default so theme authors do not need to provide a separate value for every step in the scale.

## Usage

Apply a color theme when needed:

```html
<html data-color-theme="light">
```

```html
<html data-color-theme="dark">
```

Display token values with native color inputs when documenting or configuring a color scale:

```html
<label for="color-primary">
  Primary
  <input id="color-primary" name="primary" type="color" value="#0047ba" />
  <small>--color-primary</small>
</label>
```

For exact shared color values and computed token definitions, use [color.css](/Users/stuft2/Projects/design-system/src/css/color.css) as the source of truth.

Reference color tokens directly from component styles. The shared color stylesheet defines semantic tokens, not public text or background helper classes.

## Authoring Rules

- Use shared color tokens before creating a new component-level color token.
- Prefer semantic names that describe role or state instead of raw hue names.
- Derive supportive utility shades from the base semantic token when that preserves the intended family relationship.
- Do not use semantic color tokens as generic replacements for unrelated primary, accent, text, or border roles.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--color-accent` | `<color>` | Default accent background color. Use for: page backgrounds, control backgrounds, and neutral component accents Avoid for: borders or text |
| `--color-accent-disabled` | `<color>` | Muted accent color for disabled controls. Use for: disabled buttons and inactive accents Avoid for: default interactive controls |
| `--color-accent-strong` | `<color>` | Strong accent fill color. Derived from: `--color-accent` Use for: filled secondary UI accents that need contrast with white content Avoid for: borders or text |
| `--color-accent-subtle` | `<color>` | Quiet accent background color. Derived from: `--color-accent` by increasing each RGB channel Use for: low-emphasis panels, code blocks, and grouped preview regions Avoid for: primary page backgrounds |
| `--color-border` | `<color>` | Default border color source. Use for: the authored border color that derived border variants are calculated from Avoid for: component borders when a subtle or strong role better describes the treatment |
| `--color-border-inverse` | `<color>` | Default border color for inverse accents. Use for: dividers and outlines on inverted accents Avoid for: component borders on default light accents |
| `--color-border-strong` | `<color>` | Strong border color. Derived from: `--color-border` Use for: emphasized outlines and low-emphasis badges or chips that need visible separation Avoid for: primary text |
| `--color-border-strong-inverse` | `<color>` | Strong border color for inverse accents. Derived from: `--color-border-inverse` Use for: high-emphasis dividers and outlines on inverted accents Avoid for: component borders on default light accents |
| `--color-border-subtle` | `<color>` | Subtle border color. Derived from: `--color-border` Use for: default control borders and quiet separators Avoid for: primary actions or text |
| `--color-border-subtle-inverse` | `<color>` | Subtle border color for inverse accents. Derived from: `--color-border-inverse` Use for: quiet dividers and outlines on inverted accents Avoid for: essential focus indicators |
| `--color-error` | `<color>` | Default error utility color. Use for: the standard error tone in components and the source color for the error scale Avoid for: non-semantic decorative emphasis |
| `--color-error-strong` | `<color>` | Derived darker error utility color. Use for: destructive and high-emphasis error states Avoid for: default body text |
| `--color-error-subtle` | `<color>` | Derived lighter error utility color. Use for: low-emphasis error backgrounds and inline validation regions Avoid for: high-contrast borders or dense copy |
| `--color-focus-ring` | `<color>` | Focus ring color paired with the primary color. Derived from: `--color-primary-subtle` Use for: accessible focus indication around interactive elements Avoid for: static fills or borders |
| `--color-info` | `<color>` | Default informational utility color. Use for: the standard info tone in components and the source color for the info scale Avoid for: direct replacement of all primary accents |
| `--color-info-strong` | `<color>` | Derived darker informational utility color. Use for: higher-emphasis info surfaces, badges, and banners Avoid for: default body text |
| `--color-info-subtle` | `<color>` | Derived lighter informational utility color. Use for: low-emphasis info backgrounds and supporting UI Avoid for: high-contrast borders or dense text |
| `--color-primary` | `<color>` | Primary action color. Use for: primary action fills, primary borders, control accents, and derived primary accents Avoid for: foreground accent text when `--color-text-accent` better describes the role |
| `--color-primary-strong` | `<color>` | Stronger primary color for pressed or deeper emphasis states. Derived from: `--color-primary` Use for: pressed primary actions and higher-emphasis primary accents Avoid for: default accent text on page accents |
| `--color-primary-subtle` | `<color>` | Subtle primary accent color. Derived from: `--color-primary` Use for: selected tab backgrounds, quiet primary hover accents, and low-emphasis primary fills Avoid for: foreground text or primary action fills |
| `--color-success` | `<color>` | Default success utility color. Use for: the standard success tone in components and the source color for the success scale Avoid for: generic primary styling |
| `--color-success-strong` | `<color>` | Derived darker success utility color. Use for: high-emphasis success states and confirmation surfaces Avoid for: default body text |
| `--color-success-subtle` | `<color>` | Derived lighter success utility color. Use for: quiet success backgrounds and supportive emphasis Avoid for: strong dividers or compact text |
| `--color-text` | `<color>` | Default foreground text color. Use for: primary text and form values Avoid for: placeholder text or subtle dividers |
| `--color-text-accent` | `<color>` | Accent foreground text color. Derived from: `--color-primary` Use for: accent-colored links, labels, headings, and foreground accents on default accents Avoid for: primary fills, borders, and native control accents |
| `--color-text-accent-inverse` | `<color>` | Accent foreground text color for inverse accents. Copies the same value as `--color-text-inverse` without aliasing it Use for: accent-colored foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary fills, borders, and foreground text on default light accents |
| `--color-text-accent-strong` | `<color>` | Strong accent foreground text color. Derived from: `--color-text-accent` Use for: higher-emphasis accent foreground accents on default accents Avoid for: primary fills or non-accent text emphasis |
| `--color-text-accent-strong-inverse` | `<color>` | Strong accent foreground text color for inverse accents. Uses the same derivation as `--color-text-strong-inverse` without aliasing it Use for: higher-emphasis accent foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary fills or foreground text on default light accents |
| `--color-text-accent-subtle` | `<color>` | Subtle accent foreground text color. Derived from: `--color-text-accent` Use for: lower-emphasis accent foreground accents on default accents Avoid for: long-form body text or disabled text |
| `--color-text-accent-subtle-inverse` | `<color>` | Subtle accent foreground text color for inverse accents. Uses the same derivation as `--color-text-subtle-inverse` without aliasing it Use for: lower-emphasis accent foreground accents on dark, inverse, or primary-heavy accents Avoid for: primary text on inverse accents |
| `--color-text-inverse` | `<color>` | Default foreground text color for inverse accents. Sits between `--color-text-strong-inverse` and `--color-text-subtle-inverse` Use for: primary text on inverted accents Avoid for: primary text on default light accents |
| `--color-text-strong` | `<color>` | Strong foreground text color. Derived from: `--color-text` Use for: high-emphasis foreground content Avoid for: subtle helper text |
| `--color-text-strong-inverse` | `<color>` | Strong foreground text color for inverse accents. Derived from: `--color-text-inverse` by mixing darker Use for: darker foreground content on inverted accents Avoid for: subtle helper text or current navigation items that need maximum inverse contrast |
| `--color-text-subtle` | `<color>` | Subtle foreground text color. Derived from: `--color-text` Use for: secondary copy, quiet labels, and low-emphasis foregrounds Avoid for: long-form primary reading text |
| `--color-text-subtle-inverse` | `<color>` | Subtle foreground text color for inverse accents. Derived from: `--color-text-inverse` by mixing lighter Use for: lighter foreground accents on inverted accents Avoid for: muted or low-emphasis text on inverse accents |
| `--color-unavailable` | `<color>` | Default unavailable utility color. Use for: unavailable states, unavailable item markers, and the source color for the unavailable scale Avoid for: disabled control styling when `--color-accent-disabled` better describes the role |
| `--color-unavailable-strong` | `<color>` | Derived darker unavailable utility color. Use for: higher-emphasis unavailable markers and unavailable state accents Avoid for: default body text |
| `--color-unavailable-subtle` | `<color>` | Derived lighter unavailable utility color. Use for: low-emphasis unavailable backgrounds and supporting UI Avoid for: essential borders or dense copy without contrast testing |
| `--color-warning` | `<color>` | Default warning utility color. Use for: the standard warning tone in components and the source color for the warning scale Avoid for: body text or default low-emphasis highlighting |
| `--color-warning-strong` | `<color>` | Derived darker warning utility color. Use for: high-emphasis warning states and warning banners Avoid for: low-contrast content |
| `--color-warning-subtle` | `<color>` | Derived lighter warning utility color. Use for: low-emphasis warning backgrounds Avoid for: text-heavy UI without stronger foreground contrast |

---

<!-- Source: src/css/dialog.md -->

# Dialog

## Overview

The dialog component presents a focused native `<dialog popover>` surface for confirmations, approvals, and compact review flows.

The component is classless by default. It styles semantic dialog structure directly through the native `<dialog>` element, a direct child `<form>`, a `<header>` for the title and dismissal control, and a `<footer>` for actions.

## Usage

```html
<button type="button" id="open-dialog" popovertarget="review-dialog" popovertargetaction="show">Open dialog</button>

<dialog id="review-dialog" popover aria-labelledby="dialog-title">
  <form>
    <header>
      <h2 id="dialog-title">Review changes</h2>
      <p>Confirm the update before publishing it to production.</p>
      <button class="tertiary icon" type="button" popovertarget="review-dialog" popovertargetaction="hide" aria-label="Close dialog">close</button>
    </header>

    <p>Shipping this change will make it visible to all users immediately.</p>

    <footer>
      <button class="secondary" type="button" popovertarget="review-dialog" popovertargetaction="hide">Cancel</button>
      <button type="button" popovertarget="review-dialog" popovertargetaction="hide">Confirm</button>
    </footer>
  </form>
</dialog>
```

Use this component when the user should complete or dismiss a focused task while keeping the surrounding page available.

Use a modal dialog opened with `showModal()` instead when the surrounding page must become inert.

Triggering a dialog from a separate button does not require JavaScript when the dialog is exposed as a popover. Use `popovertarget` on the trigger and `popovertargetaction="hide"` on dismissal controls.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- DLG-001: The dialog surface should size within the viewport and center itself without requiring a wrapper.
- DLG-002: The dialog shell exposes `--dialog-border-radius` and `--dialog-border-width` so its shape and edge definition can be customized consistently.
- DLG-003: Open and close transitions should fade opacity while preserving a reduced-motion fallback.
- DLG-004: The body layout should stack header, content, and actions with shared spacing tokens instead of one-off gaps or helper wrappers.
- DLG-005: Action rows should align to the end and wrap cleanly when space is constrained.
- DLG-006: The component should work with `popover` and `popovertarget` attributes so open and close actions can stay declarative.
- DLG-007: The dialog shell should rely on semantic elements and scoped descendant selectors rather than component-specific class names.
- DLG-008: Trigger buttons should open the dialog with `popovertargetaction="show"` when a popover interaction is needed.
## Accessibility

- Provide an accessible name with `aria-labelledby` or `aria-label`.
- Use a heading inside the dialog so the purpose is immediately clear.
- Keep dismiss controls keyboard reachable and give icon-only buttons an accessible name.
- Use native dialog behavior rather than replacing it with custom overlays or focus trapping logic unless product requirements exceed platform support.
- Keep the body content concise enough that the modal surface remains scannable on smaller screens.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--dialog-backdrop-color` | `<color>` | Sets the modal backdrop overlay color; change it to make the page behind dialogs more or less visually suppressed. |
| `--dialog-border-radius` | `<length>` | Sets the outer dialog corner radius and feeds the inner radius calculation; change it to align dialogs with the product surface shape. |
| `--dialog-border-width` | `<length>` | Sets the dialog border width and inner-radius offset; change it when dialogs need stronger or subtler edge definition. |
| `--dialog-color-accent-subtle` | `<color>` | Sets --dialog-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-color-border-subtle` | `<color>` | Sets --dialog-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-color-text` | `<color>` | Sets --dialog-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-control-gap` | `<length>` | Sets --dialog-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-font-size` | `<length>` | Sets --dialog-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-max-inline-size` | `<length>` | Sets the preferred maximum dialog width before viewport gutters are applied; change it for narrower confirmations or wider form dialogs. |
| `--dialog-shadow` | `Any` | Sets the dialog elevation shadow; change it to tune modal depth or reduce visual weight. |
| `--dialog-space-inline` | `<length>` | Sets --dialog-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-space-stack` | `<length>` | Sets --dialog-space-stack so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dialog-transition-duration` | `<time>` | Sets the open and close animation duration for the dialog and backdrop; change it when modal motion should feel faster or calmer. |

## Depends On

- `--color-accent-strong`
- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-text`
- `--font-size`
- `--layout-control-gap`
- `--layout-control-radius`
- `--layout-space-inline`
- `--layout-space-stack`
- `--layout-surface-border-width`

---

<!-- Source: src/css/dropdown.md -->

# Dropdown

## Overview

The dropdown component presents a short list of actions or links through a native `<details>` disclosure that visually matches the select control.

The component uses a scoped `.dropdown` class on `<details>` so it can style the trigger and menu without colliding with the global accordion treatment.

## Usage

```html
<details class="dropdown">
  <summary>Dropdown</summary>
  <ul>
    <li><a href="#">Solid</a></li>
    <li><a href="#">Liquid</a></li>
    <li><a href="#">Gas</a></li>
    <li><a href="#">Plasma</a></li>
  </ul>
</details>
```

Use this component when the user needs to reveal a compact list of navigation targets or actions from a single trigger.

The list can also contain labels with direct child checkbox or radio inputs when users need to make compact, browser-managed choices without JavaScript.

Use `select` instead when the field is part of form submission and the browser should manage value selection, validation, and picker semantics.

Keep the summary label short enough to read like a control label rather than a sentence.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- DRP-001: The closed trigger should align visually with the shared select control, including border, padding, focus ring, and downward chevron treatment.
- DRP-002: The disclosure remains native `<details>` and `<summary>` behavior, so keyboard interaction and open state management stay browser-driven.
- DRP-003: The menu panel should stay scoped to `.dropdown` and should not restyle unrelated `details` disclosures.
- DRP-004: The revealed list should accept simple anchor-only menu items without extra wrapper markup.
- DRP-005: Menu item hover and focus surfaces should stay flush with the list while clipping to the panel's rounded border.
- DRP-006: The indicator uses `--dropdown-icon-source` as a mask and `--dropdown-icon-color` as its theme-aware fill so consumers can customize its artwork and color independently.
- DRP-007: Comfortable and compact density should both come from shared layout tokens.
- DRP-008: A dropdown list item may contain a label with a direct child checkbox or radio, making the full padded row clickable while preserving native form behavior.
- DRP-009: Choice rows should expose native checked, radio-group, focus, and disabled behavior without closing the disclosure automatically.
- DRP-010: The chevron should remain centered at the trigger's configured inline offset, point down while closed, and rotate 180 degrees to point up while open.

## Accessibility

- Use a native `<summary>` as the visible trigger label.
- Keep menu item text descriptive on its own because each link may be announced without surrounding context.
- Use real links for navigation destinations and buttons only when the revealed items trigger in-place actions.
- Use `select` or another true form control when the user is choosing a submitted value rather than opening a short action list.
- Keep native checkbox and radio inputs visible, put each input inside its visible label, and use a shared `name` for related controls.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--dropdown-color-accent-subtle` | `<color>` | Sets --dropdown-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-border-subtle` | `<color>` | Sets --dropdown-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-focus-ring` | `<color>` | Sets --dropdown-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-primary` | `<color>` | Sets --dropdown-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-primary-subtle` | `<color>` | Sets --dropdown-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-color-text` | `<color>` | Sets --dropdown-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-border-width` | `<length>` | Sets --dropdown-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-gap` | `<length>` | Sets --dropdown-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-min-height` | `<length>` | Sets --dropdown-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-padding-block` | `<length>` | Sets --dropdown-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-padding-inline` | `<length>` | Sets --dropdown-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-control-radius` | `<length>` | Sets --dropdown-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-focus-ring-size` | `<length>` | Sets --dropdown-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-font-size` | `<length>` | Sets --dropdown-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-icon-color` | `<color>` | Sets the dropdown chevron color; change it when the disclosure indicator needs a different semantic emphasis. |
| `--dropdown-icon-offset` | `<length>` | Sets the inline offset between the dropdown chevron and the control edge; change it when padding or icon alignment changes. |
| `--dropdown-icon-size` | `<length>` | Sets the chevron size in dropdown controls; change it when the icon should scale differently from the control text. |
| `--dropdown-icon-source` | `<image> | none` | Sets the chevron mask used for dropdown controls; change it to swap the indicator artwork independently from its color. |
| `--dropdown-line-height` | `<number>` | Sets --dropdown-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--dropdown-panel-offset` | `<length>` | Sets the gap between the trigger and dropdown panel; change it when the popover should sit tighter to or farther from the control. |

## Depends On

- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/file.md -->

# File

## Overview

The file component is a native file picker that mirrors the input component's border, spacing, typography, and focus treatment while keeping the browser's built-in filename readout.

The pattern uses a wrapping native `<label>` and a native `<input type="file">`, with the chooser button styled through `::file-selector-button` and no component-specific classes.

## Usage

```html
<label>
  <span data-role="label">Attachment</span>
  <input id="demo-file" type="file" required />
  <span data-role="message" data-invalid="Choose a file before continuing."></span>
</label>
```

Use this component when the user needs to upload a document, image, or other local file.

Keep the native file input in the DOM so browser file selection, keyboard behavior, and form submission continue to work normally.

Let the browser render the selected filename text. This component intentionally avoids JavaScript and does not replace the native file selection UI.

Wrap the visible label text in a `[data-role="label"]` element so required fields can render the red asterisk immediately after the label text.

For native validation, place a `[data-role="message"]` element directly after the input inside the same label and pair that with native constraints such as `required` or `accept`.

This component follows the same classless authoring approach as the text input component and should not require a named wrapper class.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- FIL-001: The chooser button should align with the shared secondary button treatment so it feels consistent with the rest of the system, including the subtle brand hover surface.
- FIL-002: File input color changes should transition smoothly, with reduced-motion preferences disabling the transition.
- FIL-003: The overall control should use the same border, radius, padding, and focus treatment as the text input component.
- FIL-004: The filename text comes from the browser's native file input rendering and may vary slightly by engine.
- FIL-005: Validation feedback should appear only after user interaction by using `:user-invalid`.
- FIL-006: Disabled file inputs should communicate their state through muted text and disabled surfaces.
## Accessibility

- Keep the native `<input type="file">` focusable and available to assistive technology.
- Use a visible label so the purpose of the upload control is always clear.
- Do not hide or replace the browser's native filename feedback unless a documented accessible enhancement is required.
- Provide clear helper or error text when accepted file types, size limits, or count limits need explanation.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--file-action-padding-inline` | `<length>` | Sets --file-action-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-border-color` | `<color>` | Sets the file input wrapper border color; change it for validation states or when file controls need stronger container separation. |
| `--file-color-border-subtle` | `<color>` | Sets --file-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-error-strong` | `<color>` | Sets --file-color-error-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-focus-ring` | `<color>` | Sets --file-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-primary` | `<color>` | Sets --file-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-text` | `<color>` | Sets --file-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-text-accent` | `<color>` | Sets --file-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-color-text-subtle` | `<color>` | Sets --file-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-border-width` | `<length>` | Sets --file-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-gap` | `<length>` | Sets --file-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-min-height` | `<length>` | Sets --file-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-padding-block` | `<length>` | Sets --file-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-padding-inline` | `<length>` | Sets --file-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-control-radius` | `<length>` | Sets --file-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-focus-ring-size` | `<length>` | Sets --file-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-font-family-sans` | `Any` | Sets --file-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-font-size` | `<length>` | Sets --file-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-font-size-caption` | `<length>` | Sets --file-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-line-height` | `<number>` | Sets --file-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--file-message-color` | `<color>` | Sets helper and validation message text color for file inputs; change it when status messaging should read as neutral, subtle, or error. |
| `--file-space-inline` | `<length>` | Sets --file-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-border-subtle`
- `--color-error-strong`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-action-padding-inline`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/footer.md -->

# Footer

## Overview

The footer component provides a page-level content info region for site ownership and closing legal or utility content.

Like the header, the footer is built as a semantic contract around native HTML instead of a legacy class tree.

For exact styles, use [footer.css](/Users/stuft2/Projects/design-tokens/src/css/footer.css) as the source of truth.

## Usage

Sticky-footer behavior is a page-shell concern, not a footer variant. The shared layout baseline now handles that automatically for the standard page contract:

```html
<body>
  <header>...</header>
  <main>...</main>
  <footer>...</footer>
</body>
```

Minimal footer:

```html
<footer>
  <a href="https://www.byu.edu/" aria-label="Brigham Young University home page">
    Brigham Young University
  </a>
  <p>
    <span>Provo, UT 84602, USA</span>
    <span>2026 © All Rights Reserved</span>
  </p>
  <nav aria-label="Legal links">
    <ul>
      <li><a href="#">Privacy Notice</a></li>
      <li><a href="#">Cookie Preferences</a></li>
    </ul>
  </nav>
</footer>
```

Enhanced footer with site-info band and layout utilities:

```html
<footer>
  <section class="grid">
    <section aria-labelledby="footer-contact-title">
      <h3 id="footer-contact-title">Contact</h3>
      <address>
        <p>BYU Speeches</p>
        <p>701 East University Parkway</p>
        <p>Provo, Utah 84602</p>
        <p><a href="tel:18888888888">888-888-8888</a></p>
      </address>
    </section>

    <section aria-labelledby="footer-related-title">
      <h3 id="footer-related-title">Related Links</h3>
      <nav aria-labelledby="footer-related-title">
        <ul>
          <li><a href="#">Give to Speeches</a></li>
          <li><a href="#">BYU Alumni</a></li>
          <li><a href="#">BYU Magazine</a></li>
        </ul>
        </nav>
    </section>

    <section aria-labelledby="footer-connect-title">
      <h3 id="footer-connect-title">Connect</h3>
      <nav aria-labelledby="footer-connect-title">
        <ul>
          <li><a href="#">Feedback</a></li>
          <li><a href="#">Help</a></li>
          <li><a href="#">Follow BYU Speeches</a></li>
        </ul>
        </nav>
    </section>
  </section>

  <section>
    <a href="https://www.byu.edu/" aria-label="Brigham Young University home page">
      Brigham Young University
    </a>
    <p>
      <span>Provo, UT 84602, USA</span>
      <span>2026 © All Rights Reserved</span>
    </p>
    <nav aria-label="Legal links">
      <ul>
        <li><a href="#">Privacy Notice</a></li>
        <li><a href="#">Cookie Preferences</a></li>
      </ul>
    </nav>
  </section>
</footer>
```

Use this component when a page needs a clear page footer with BYU branding and compact legal metadata. Add the optional site-info band when the footer also needs contact information or structured link groups.

## Variants

Social media links belong in the optional theme-aware site-info band when a site needs a compact "follow us" section.

Use semantic navigation and keep the accessible name on each icon-only link:

```html
<footer>
  <section class="grid">
    <section aria-labelledby="footer-social-title">
      <h3 id="footer-social-title">Follow</h3>
      <nav aria-labelledby="footer-social-title">
        <ul class="cluster">
          <li>
            <a href="https://www.youtube.com/byu" aria-label="BYU on YouTube">
              <span class="icon" aria-hidden="true">smart_display</span>
            </a>
          </li>
          <li>
            <a href="https://www.instagram.com/byu" aria-label="BYU on Instagram">
              <span class="icon" aria-hidden="true">photo_camera</span>
            </a>
          </li>
          <li>
            <a href="https://www.facebook.com/byu" aria-label="BYU on Facebook">
              <span class="icon" aria-hidden="true">thumb_up</span>
            </a>
          </li>
          <li>
            <a href="https://www.linkedin.com/school/brigham-young-university/" aria-label="BYU on LinkedIn">
              <span class="icon" aria-hidden="true">business_center</span>
            </a>
          </li>
        </ul>
        </nav>
    </section>
  </section>

  <section>
    <a href="https://www.byu.edu/" aria-label="Brigham Young University home page">
      Brigham Young University
    </a>
    <p>
      <span>Provo, UT 84602, USA</span>
      <span>2026 © All Rights Reserved</span>
    </p>
    <nav aria-label="Legal links">
      <ul>
        <li><a href="#">Privacy Notice</a></li>
        <li><a href="#">Cookie Preferences</a></li>
      </ul>
    </nav>
  </section>
</footer>
```

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js).

- FTR-001: The component styles the last top-level `<footer>` in `body` and any internal `<footer class="footer">` instance used for demos or tests.
- FTR-002: The minimal contract keeps the BYU link, address line, and legal links centered in one vertical stack across breakpoints.
- FTR-003: The enhanced contract uses one page footer with a theme-aware subtle site-info section above the blue legal section.
- FTR-004: Each site-info navigation group is wrapped in a section element so the column has a semantic block around its heading and navigation.
- FTR-005: The site-info section is layout-neutral; choose shared layout utilities such as `grid` and `cluster` on the content you place there.
- FTR-006: Social media links can live in that site-info section with `cluster` or another appropriate layout utility.
- FTR-007: The minimal contract expects the BYU home link first, followed by direct child legal copy and utility navigation.
- FTR-008: In the enhanced contract, the second section uses that same legal footer structure internally.
- FTR-009: Sticky-footer behavior comes from the surrounding page shell rather than from the footer component itself, and the default layout stylesheet now provides that shell behavior for standard pages.
- FTR-010: When the footer is a direct child of `body`, it expands to full bleed to read like page chrome instead of centered content.
## Accessibility

- Use a native top-level `<footer>` for real page-level content info and do not add a redundant `role="contentinfo"`.
- Keep the optional theme-aware site-info band inside the same footer instead of creating a second page-level footer.
- Use `address` only for real contact or ownership details.
- Keep footer navigation links short and task-oriented.
- Give icon-only social links an accessible name on the link itself and mark the icon glyph as decorative.
- Prefer text links for branding and ownership copy instead of hiding those labels in images.
- See MDN's [ARIA: contentinfo role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/contentinfo_role) for the landmark semantics and usage constraints.

## Migration Notes

Compared with the BYU footer web component, this footer now supports the minimal blue legal footer, the enhanced two-band footer with a theme-aware site-info band, utility-driven site-info layouts, documented social-link content in that band, and sticky-footer page-shell guidance.

The main documented gaps are:

- Double-width and triple-width column variants are not part of the current public contract.
- The site-info band expects semantic content, while layout choices come from shared layout utilities instead of footer-specific column variants.

When migrating from the BYU footer component, this footer now covers the core institutional/legal footer, the optional site-info band, a documented social-link treatment, utility-driven column layouts, and sticky-footer layout guidance.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--footer-background` | `<color>` | Sets the main footer background; change it when the global footer needs a different brand or contrast surface. |
| `--footer-border-color` | `<color>` | Sets the top border color for the main footer; change it when the footer needs more or less separation from page content. |
| `--footer-brand-link-size` | `<length>` | Sets the font size for prominent brand links in the footer; change it when institutional links should carry more or less hierarchy. |
| `--footer-color-border-subtle` | `<color>` | Sets --footer-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-color-primary-strong` | `<color>` | Sets --footer-color-primary-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-color-text` | `<color>` | Sets --footer-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-color-text-accent` | `<color>` | Sets --footer-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-color-text-accent-inverse` | `<color>` | Sets --footer-color-text-accent-inverse so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-control-border-width` | `<length>` | Sets --footer-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-font-weight-body-bold` | `<number>` | Sets --footer-font-weight-body-bold so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-font-weight-body-regular` | `<number>` | Sets --footer-font-weight-body-regular so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-landmark-padding-block` | `<length>` | Sets --footer-landmark-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-legal-size` | `<length>` | Sets the font size for legal and secondary footer text; change it when compliance copy needs to be more legible or more subdued. |
| `--footer-link-color` | `<color>` | Sets the default link color in the main footer; change it when footer links need a different contrast treatment on the footer background. |
| `--footer-link-hover-color` | `<color>` | Sets the hover color for main footer links; change it when interactive footer links need a stronger focus or hover cue. |
| `--footer-page-min-inline-size` | `<length>` | Sets --footer-page-min-inline-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-site-background` | `<color>` | Sets the background for the lower site-footer band; change it when secondary footer content should sit on a different surface. |
| `--footer-site-link-color` | `<color>` | Sets the link color in the lower site-footer band; change it to keep links accessible against the site-footer background. |
| `--footer-site-text-color` | `<color>` | Sets the text color in the lower site-footer band; change it when that band uses a different surface or contrast level. |
| `--footer-space-inline` | `<length>` | Sets --footer-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--footer-text-color` | `<color>` | Sets the default text color in the main footer; change it when the footer background changes or copy needs different emphasis. |

## Depends On

- `--color-accent-subtle`
- `--color-border-inverse`
- `--color-border-subtle`
- `--color-primary-strong`
- `--color-text`
- `--color-text-accent`
- `--color-text-accent-inverse`
- `--color-text-inverse`
- `--font-size`
- `--font-size-caption`
- `--font-weight-body-bold`
- `--font-weight-body-regular`
- `--layout-control-border-width`
- `--layout-landmark-padding-block`
- `--layout-page-min-inline-size`
- `--layout-space-inline`

---

<!-- Source: src/css/form.md -->

# Form

## Overview

The form composition layer normalizes native form grouping patterns that combine multiple controls into one horizontal affordance.

Use it for semantic search forms and grouped control wrappers. Individual controls still come from the input, button, select, checkbox, radio, switch, and related component stylesheets.

## Usage

```html
<form role="search">
  <input type="search" name="q" placeholder="Search" />
  <button type="submit">Search</button>
</form>
```

```html
<fieldset role="group">
  <legend>Amount</legend>
  <input type="number" name="amount" />
  <button type="button">Apply</button>
</fieldset>
```

Use `form[role="search"]` for compact search bars. Use `fieldset[role="group"]` when grouped controls need a native legend. Use `div[role="group"]` only when a fieldset would be semantically incorrect.

Unlike most component styles, labels and legends do not map these values through component-specific variables. They consume the shared `--form-label-*` variables directly. This is intentional: customize these variables on the form or a containing region so every label and legend in that form retains the same visual treatment.

## Behavior

- FRM-001: `form[role="search"]`, `fieldset[role="group"]`, and `div[role="group"]` render as single horizontal control groups.
- FRM-002: Adjacent controls overlap one border width so joins read as one divider.
- FRM-003: Interior control corners are square; only the first and last grouped controls keep the outer radius.
- FRM-004: `fieldset[role="group"]` resets native border, margin, and padding so it behaves like the other group wrappers.
- FRM-005: Inputs and text buttons in grouped controls grow and shrink together, while icon-only buttons retain their square content-based width.
- FRM-006: Native fieldsets that keep their border chrome derive their corner radius from `--form-control-radius`.
- FRM-007: Group wrappers fill their available inline space and contain their children’s intrinsic sizing so they do not force page-level horizontal overflow.
- FRM-008: Visible field labels and native legends consume the shared `--form-label-*` variables directly so their color, font size, and line height remain consistent across form control types.

## Accessibility

- Use `form[role="search"]` only for search behavior.
- Prefer `fieldset[role="group"]` with a visible `legend` when controls need a shared label.
- Keep grouped controls in logical source order.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--form-control-border-width` | `<length>` | Sets the border width used to join adjacent controls in semantic form groups; change it when grouped controls need to match a different control border rhythm. |
| `--form-control-radius` | `<length>` | Sets the fallback outer corner radius for grouped form controls; change it when a grouped control does not provide its own radius hook. |
| `--form-icon-button-inline-size` | `<length>` | Sets the square inline size of icon-only buttons inside grouped controls; change it when their typography or control padding requires a different footprint. |
| `--form-label-color` | `<color>` | Shared color for field labels and native legends. |
| `--form-label-font-size` | `<length>` | Shared font size for field labels and native legends. |
| `--form-label-line-height` | `<number>` | Shared line height for field labels and native legends. |
| `--grouped-control-radius` | `<length>` | Corner radius hook for controls inside native form groups. Buttons and inputs map this hook back to their component radius aliases so grouped controls keep compatible outer corners. |

## Depends On

- `--color-text-accent`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-min-height`
- `--layout-control-radius`

---

<!-- Source: src/css/header.md -->

# Header

## Overview

The header component converts the old BYU-style site header into a semantic contract built around the top-level page `<header>` or an internal `<header class="header">` testing hook.

Instead of the original `.byu-*` selector tree, the component styles the header through direct child structure:

- first child home link for the brand mark or logo
- a short supporting `<p>` line for the institutional or parent label
- a heading for the site or application title
- an optional breadcrumb `<nav aria-label="breadcrumb">`
- an optional `[data-header-actions]` action group
- an optional icon button with `popovertarget` and matching `nav[popover]` for the mobile menu

For exact styles, use [header.css](/Users/stuft2/Projects/design-tokens/src/css/header.css) as the source of truth.

## Usage

```html
<header>
  <a href="/" aria-label="Brigham Young University home">Y</a>
  <p><a href="/">Brigham Young University</a></p>
  <h1>Design Tokens</h1>
  <div data-header-actions aria-label="Header actions">
    <span class="icon" aria-hidden="true">account_circle</span>
    <a href="/signin">Sign In</a>
  </div>
  <nav aria-label="breadcrumb">
    <ol>
      <li><a href="https://it.byu.edu/">Office of IT</a></li>
      <li><span aria-current="page">Application Engineering</span></li>
    </ol>
  </nav>
  <button class="icon" type="button" popovertarget="site-navigation" aria-label="Open navigation menu">menu</button>
  <nav id="site-navigation" aria-label="Site" popover>
    <ul>
      <li><a href="/" aria-current="page">Home</a></li>
      <li><a href="/tokens/">Design Tokens</a></li>
      <li><a href="/components/">Components</a></li>
    </ul>
  </nav>
</header>

<nav aria-label="Site">
  <ul>
    <li><a href="/" aria-current="page">Home</a></li>
    <li><a href="/tokens/">Design Tokens</a></li>
    <li><a href="/components/">Components</a></li>
  </ul>
</nav>
```

Use this component when a page needs a strong branded header that identifies the parent organization and current site.

Use `[data-header-actions]` for page-level account or utility actions that belong in the branded header but are not primary site navigation. The action area is centered vertically to the right of the title stack. Use a normal anchor when sign-in navigates to another route. Use a native `<button>` only when sign-in opens an in-page flow, modal, or menu:

```html
<div data-header-actions aria-label="Header actions">
  <span class="icon" aria-hidden="true">account_circle</span>
  <a href="/signin">Sign In</a>
</div>
```

Use the existing [nav](/Users/stuft2/Projects/design-system/src/css/nav.md) component for the desktop primary menu below the header. When mobile navigation is needed, duplicate those primary links inside the header as a `popover` navigation menu and connect it to an icon button with `popovertarget`.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js).

- HDR-001: The component styles the first top-level `<header>` in `body` and any internal `<header class="header">` instance.
- HDR-002: The first child link is treated as the visual mark area and can contain text, an image, or an SVG.
- HDR-003: The top-level page header uses the available full-bleed width so long titles can wrap with balanced lines instead of forcing horizontal overflow.
- HDR-004: The supporting paragraph is a caption-style institutional label, not a second heading.
- HDR-005: The main title should be authored as a real heading so the page keeps a meaningful outline, and it remains left aligned with authored casing within the branded header.
- HDR-006: Breadcrumbs remain optional and inherit the existing classless breadcrumb navigation presentation.
- HDR-007: Header breadcrumb parent links and separators use brand inverse text color, while hover and current items use default inverse text color.
- HDR-008: Banner breadcrumbs scroll horizontally when the trail is wider than the available space instead of wrapping onto multiple lines.
- HDR-009: Header actions are optional, stay visually grouped, and align to the inline end of the title area.
- HDR-010: Header action links keep link semantics and presentation while staying legible on the branded header background.
- HDR-011: Header action buttons use an inverse outline treatment by default so real button actions remain visibly distinct from links.
- HDR-012: When both header actions and the mobile menu button are present, the action group sits before the menu button.
- HDR-013: The optional menu button is visible below `48rem` and opens the matching primary navigation popover through the native Popover API.
- HDR-014: A standalone `body > nav:not([popover])` remains the desktop primary navigation and is hidden below `48rem` when paired with the mobile header menu.
- HDR-015: The branded header has no outer margin, while keeping its own internal padding.
- HDR-016: When the header is a direct child of `body`, it expands to full bleed to read like page chrome instead of centered content.
- HDR-017: A one-line header title keeps the header compact, while a title that wraps onto multiple lines expands the header to fit its content.
## Accessibility

- Use a native top-level `<header>` for real page-level header content and do not add a redundant `role="banner"`.
- Use the internal `.header` hook only for demo or test pages that need header styling outside the document-level page header.
- Keep the first child link pointed at a stable home or parent destination.
- Prefer real heading text for the current site or application name instead of relying on a logo image alone.
- Keep breadcrumb links as real anchors and mark the current location with `aria-current`.
- Give the header action group an accessible label when the controls are not self-evident from surrounding context.
- Do not use the header action group for primary site navigation. Use a labeled `nav` when the content is a set of destinations.
- Keep the menu button label explicit with `aria-label`, and make sure its `popovertarget` value matches the primary popover navigation `id`.
- Use real links inside the primary navigation popover and mirror `aria-current` with the desktop primary navigation.
- Do not use this component for alerts, status messages, or marketing hero blocks.

## Migration Notes

Compared with the BYU header web component, this header currently supports the branded shell, subtitle line, breadcrumb trail, a mobile primary navigation popover, and composition with primary navigation below the header.

The main documented gaps are:

- Constrained header layouts are intentionally out of scope for now.
- Search and complete authenticated account states are not covered by this header contract.
- Nested links within the site title are not documented as a supported authored pattern.
- Search and richer account states remain separate work beyond the dedicated header action area.

When migrating from the BYU header component, use this header for the branded page shell, pair it with the existing navigation component below it on desktop, and add the native popover menu for mobile primary navigation. Treat search and richer account controls as separate work rather than assuming parity today.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--header-background` | `<color>` | Sets the header surface color and active menu contrast target; change it when the branded header needs a different primary surface. |
| `--header-caption-size` | `<length>` | Sets the uppercase caption or subtitle size in the header; change it when the secondary page label needs more or less hierarchy. |
| `--header-color-accent` | `<color>` | Sets --header-color-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-color-border-subtle` | `<color>` | Sets --header-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-color-focus-ring` | `<color>` | Sets --header-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-color-text` | `<color>` | Sets --header-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-color-text-accent-inverse` | `<color>` | Sets --header-color-text-accent-inverse so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-border-width` | `<length>` | Sets --header-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-gap` | `<length>` | Sets --header-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-min-height` | `<length>` | Sets --header-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-padding-block` | `<length>` | Sets --header-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-padding-inline` | `<length>` | Sets --header-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-control-radius` | `<length>` | Sets --header-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-focus-ring-size` | `<length>` | Sets --header-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-font-family-sans` | `Any` | Sets --header-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-font-size` | `<length>` | Sets --header-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-font-weight-body-bold` | `<number>` | Sets --header-font-weight-body-bold so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-font-weight-heading-2` | `<number>` | Sets --header-font-weight-heading-2 so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-landmark-padding-block` | `<length>` | Sets --header-landmark-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-line-height` | `<number>` | Sets --header-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-mark-size` | `<length>` | Sets the brand mark column width and mobile menu vertical offset; change it when the logo area should be larger or smaller. |
| `--header-menu-popover-width` | `<length>` | Sets the width of the header menu popover; change it when mobile or compact navigation needs a wider or narrower menu. |
| `--header-rule-color` | `<color>` | Sets the header divider color, mark divider, and active menu button border; change it when separators need different contrast. |
| `--header-rule-width` | `<length>` | Sets the thickness of header dividers; change it when the bottom rule and mark divider should read heavier or lighter. |
| `--header-safe-area-top` | `<length>` | Sets --header-safe-area-top so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-space-inline` | `<length>` | Sets --header-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--header-text-color` | `<color>` | Sets header text and action button foreground colors; change it when the header surface requires a different accessible foreground. |
| `--header-title-size` | `<length>` | Sets the main header title size; change it when page titles should be more compact or more prominent in the header. |
| `--header-title-weight` | `<number>` | Sets the main header title font weight; change it to make page titles feel lighter, stronger, or closer to body heading weight. |

## Depends On

- `--color-accent`
- `--color-border-inverse`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary-strong`
- `--color-text`
- `--color-text-accent-inverse`
- `--color-text-inverse`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--font-size-title`
- `--font-weight-body-bold`
- `--font-weight-heading-2`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-safe-area-top`
- `--layout-space-inline`
- `--layout-space-stack`
- `nav[aria-label="breadcrumb"]`
- `body > nav:not([popover])`
- `nav[popover]`

---

<!-- Source: src/css/icon.md -->

# Icon

## Overview

The icon component renders Material Symbols glyphs through a shared `.icon` element pattern.

The component styles a text element directly, so the icon name can remain in the DOM while the font converts it into the matching symbol.

## Usage

```html
<span class="icon" aria-hidden="true">search</span>
```

Use this component when the interface needs a compact visual symbol alongside text or as a standalone decorative control affordance.

Use visible text instead when the meaning would be unclear without a label.

For filled variants, add the `.fill` class to the same element.

```html
<span class="icon fill" aria-hidden="true">favorite</span>
```

The icon should use the shared `.icon` class so size and Material Symbols variable font settings stay consistent across components.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- ICO-001: Icons should align inline with nearby text and controls without requiring component-specific vertical offsets.
- ICO-002: Icons inherit the surrounding text color by default.
- ICO-003: Icons default to 150% of the default font size.
- ICO-004: Only components that own an icon treatment should expose a component-level icon color token, and that token should alias a theme semantic color by default.
- ICO-005: Filled icons should switch only the `FILL` axis and keep the same base sizing and font settings.
- ICO-006: Size, optical size, grade, and weight should come from the exposed custom properties rather than hardcoded per-instance values.
## Accessibility

- Mark decorative icons with `aria-hidden="true"` so they do not add noise to the accessible name.
- If an icon communicates meaning on its own, provide an accessible name on the interactive parent or add a text alternative.
- Do not rely on the icon alone to communicate critical state or action.
- Keep the source text content to a valid Material Symbols glyph name so the intended icon renders consistently.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--icon-fill` | `<number>` | Sets the Material Symbols fill axis; change it to switch icons between outlined and filled glyph styles. |
| `--icon-font-family` | `Any` | Sets the icon font family used by icon elements and generated symbols; change it only when swapping the icon font system. |
| `--icon-grad` | `<number>` | Sets the Material Symbols grade axis; change it to subtly thicken or lighten icon strokes without changing layout size. |
| `--icon-opsz` | `<number>` | Sets the Material Symbols optical size axis; change it when icons should be optimized for a different rendered size. |
| `--icon-size` | `<length>` | Sets the rendered icon font size; change it when icons should scale independently from surrounding text. |
| `--icon-wght` | `<number>` | Sets the Material Symbols weight axis; change it when icons need heavier or lighter strokes. |

## Depends On

- `--font-size`

---

<!-- Source: src/css/input.md -->

# Input

## Overview

The input component is a single-line control for short user-entered values such as names, titles, codes, search terms, and color values.

The component pattern uses a native `<label>` that wraps a native `<input>`, so the control can be styled without requiring a classed wrapper.

## Usage

```html
<label>
  <span data-role="label">Label</span>
  <input id="demo-input" type="text" placeholder="Type here" />
  <span data-role="message" data-invalid="This field is required."></span>
</label>
```

```html
<label>
  <span data-role="label">Rounded Search</span>
  <input id="demo-input-search" type="search" placeholder="Search tokens" />
</label>
```

Use this component when the user needs to enter a short, single-line value.

Use `type="color"` when the user needs to choose a color while keeping the same field height, border, radius, and focus treatment as other inputs.

Use a textarea instead when the expected response can span multiple lines.

The label should remain visible above the field, and the placeholder should act as an example rather than replacing the label.

The field should use native `<label>` and `<input>` elements so the control keeps browser form behavior, keyboard support, and autofill.

Wrap the visible label text in a `[data-role="label"]` element so required fields can render the red asterisk immediately after the label text.

For native validation, place a `[data-role="message"]` element directly after the input inside the same label. Pair that with native constraints such as `required`, `minlength`, `maxlength`, `pattern`, `min`, `max`, or `step`.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- INP-001: Single-line inputs should use the shared action padding and control minimum height so they match button height while still accommodating larger content.
- INP-002: Focus must remain clearly visible for keyboard users.
- INP-003: Comfortable and compact density should come from the layout theme tokens rather than input-specific spacing values.
- INP-004: Inputs can override the shared control radius with `--input-border-radius` when a field needs a different corner treatment.
- INP-005: Color inputs should keep the native color picker behavior while presenting the swatch inside the standard input shell.
- INP-006: Validation feedback should appear only after user interaction by using `:user-invalid` rather than showing errors on initial page load.
## Accessibility

- Use a native `<label>` so the field stays explicitly named.
- If the label does not wrap the input, associate them with matching `for` and `id` attributes.
- Do not rely on placeholder text as the only field description.
- Keep text contrast and focus indication strong enough to be visible in normal use.
- Provide helper text or error text outside the field when extra guidance is needed.
- When showing validation feedback, keep the message text in the DOM so it remains available to assistive technology.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--input-background` | `<color>` | Sets the input fill color for enabled and disabled states; change it when text fields need a filled, transparent, or disabled surface. |
| `--input-border-color` | `<color>` | Sets the text input border color, including validation overrides; change it to communicate neutral, focus-adjacent, or error state. |
| `--input-border-radius` | `<length>` | Sets text input corner radius and grouped-control radius; change it for pill search fields or sharper form controls. |
| `--input-color-accent-disabled` | `<color>` | Sets --input-color-accent-disabled so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-border-subtle` | `<color>` | Sets --input-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-error-strong` | `<color>` | Sets --input-color-error-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-focus-ring` | `<color>` | Sets --input-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-primary` | `<color>` | Sets --input-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text` | `<color>` | Sets --input-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text-accent` | `<color>` | Sets --input-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-color-text-subtle` | `<color>` | Sets --input-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-border-width` | `<length>` | Sets --input-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-gap` | `<length>` | Sets --input-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-min-height` | `<length>` | Sets --input-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-padding-block` | `<length>` | Sets --input-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-padding-inline` | `<length>` | Sets --input-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-control-radius` | `<length>` | Sets --input-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-focus-ring-size` | `<length>` | Sets --input-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-font-size` | `<length>` | Sets --input-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-font-size-caption` | `<length>` | Sets --input-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-line-height` | `<number>` | Sets --input-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--input-message-color` | `<color>` | Sets helper and validation message text color for inputs; change it when field messaging should move between subtle and error emphasis. |

## Depends On

- `--color-accent-disabled`
- `--color-border-subtle`
- `--color-error-strong`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-action-padding-block`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`

---

<!-- Source: src/css/layout.md -->

# Layout Tokens

## Overview

The theme system supports two density themes:

- `comfortable`: the default density theme
- `compact`: a denser theme for space-constrained or data-heavy interfaces

These themes are defined in [layout.css](/Users/stuft2/Projects/design-tokens/src/css/layout.css) and are applied with the `data-layout-theme` attribute.

## Usage

Apply a layout theme with a container attribute:

```html
<html data-layout-theme="comfortable">
```

```html
<section data-layout-theme="compact">
```

Use `comfortable` by default.

Use `compact` when:

- the interface is data-dense
- vertical space is limited
- users need to scan many rows or controls quickly

Do not use `compact` to compensate for weak layout decisions or overcrowded content. Simplify the UI first.

Use the shared layout tokens directly where possible:

```css
input,
select,
textarea,
button {
  min-height: var(--layout-control-min-height);
  padding-block: var(--layout-control-padding-block);
  padding-inline: var(--layout-control-padding-inline);
  border-radius: var(--layout-control-radius);
}
```

If a component needs local aliases, map them back to the shared layout tokens instead of redefining comfortable and compact values:

```css
:root {
  --input-padding-block: var(--layout-control-padding-block);
  --input-padding-inline: var(--layout-control-padding-inline);
  --input-min-height: var(--layout-control-min-height);
}
```

For exact shared layout values and computed token definitions, use [layout.css](/Users/stuft2/Projects/design-tokens/src/css/layout.css) as the source of truth.

## Native Layout Defaults

The shared layout stylesheet applies the default page-shell contract for full pages that use a top-level `header`, `main`, and `footer`.

- `body` resets default margin, uses `--layout-space-inline` for page-inline padding, stops shrinking at `--layout-page-min-inline-size`, and becomes a full-height flex column
- `body > main` grows to fill remaining vertical space, fills the available inline space regardless of its content width, centers the primary content column, and caps it at `--layout-max-inline-size`
- Plain `section` elements get block-end spacing from `--layout-section-margin-block-end`
- `section[id]` uses `--layout-anchor-scroll-offset` for anchor-link scroll positioning
- Top-level `main` landmarks get vertical padding from `--layout-landmark-padding-block`
- Top-level `footer` landmarks use half of `--layout-landmark-padding-block`; the branded page header component keeps its own internal padding while staying flush and full bleed

This means the page footer naturally stays at the bottom of the viewport on short pages without requiring an extra shell class. Override these defaults locally only when a page or component has a stronger layout requirement.

## Utility Classes

The shared layout stylesheet also provides a small utility layer for composition.

### `flow`

Margin-based vertical rhythm for document content that should keep normal block layout.

- Defaults `--flow-space` to `var(--layout-space-stack)`
- Applies block-start margin only between adjacent children
- Use when prose, headings, lists, or mixed semantic content should keep normal document flow

### `cluster`

Horizontal flex layout for peer items that should wrap and stay vertically aligned.

- Uses `var(--layout-space-inline)` for gap
- Keeps wrapped rows packed from the start with `align-content: flex-start`
- Resets `height` to `auto`
- Resets direct child margins to zero
- Removes `list-style` when applied directly to `ul`

### `justify-end`

Inline-end alignment utility for flex rows.

- Sets `justify-content: flex-end`
- Use with `cluster` or other flex containers when actions should align to the right/end

### `justify-between`

Distributed alignment utility for flex rows.

- Sets `justify-content: space-between`
- Use with `cluster` or other flex containers when leading content and trailing actions should sit on opposite sides

### `stack`

Vertical flex layout for simple one-dimensional grouping.

- Uses `var(--layout-space-stack)` for gap
- Removes `list-style` when applied directly to `ul`

### `sidebar`

Responsive two-part layout for a narrow supporting region paired with flexible main content.

- Defaults `--sidebar-target-width` to `20rem`
- Defaults `--sidebar-gap` to twice `var(--layout-space-inline)`
- Lets the first child act as the sidebar and the last child absorb remaining space
- Aligns child regions to the start so shorter sidebars keep their natural height
- Stacks child regions in source order below `48rem` and resets the first child's target-width basis so it keeps its natural height
- Uses wrapped sidebar/content columns at `48rem` and above

When the sidebar contains in-page navigation, put each link target ID on the content `section`, not on its heading. The shared `section[id]` rule applies `--layout-anchor-scroll-offset`, keeping the section heading visible below sticky primary navigation when the link is followed.

```html
<main class="sidebar">
  <nav class="toc" aria-label="On this page">
    <h2>On this page</h2>
    <ul>
      <li><a href="#color-preview">Color Preview</a></li>
    </ul>
  </nav>

  <div>
    <section id="color-preview" aria-labelledby="color-preview-title">
      <h2 id="color-preview-title">Color Preview</h2>
      <!-- Section content -->
    </section>
  </div>
</main>
```

### `center`

Centered content column using the shared layout width.

- Defaults `--center-max-inline-size` to `var(--layout-max-inline-size)`
- Defaults `--center-padding-inline` to `var(--layout-space-inline)`
- Uses `box-sizing: content-box` so padding does not reduce the configured maximum inline size
- When combined with `.sidebar` on the same element, fills the available inline size and uses `border-box` so its protected padding stays within the page boundary

### `grid`

Responsive grid for repeated sibling content.

- Defaults `--grid-column-gap` to `var(--layout-space-inline)`
- Defaults `--grid-row-gap` to `var(--layout-space-stack)`
- Defaults `--grid-min-column-size` to `16rem`
- Resets direct child `min-width` to `0` so wide content does not force overflow
- Uses `auto-fit` columns immediately, with each column at least `--grid-min-column-size` when space allows

### `switcher`

Adaptive flex layout for peers that should share a row when space allows and stack when space is constrained.

- Defaults `--switcher-target-width` to `20rem`
- Lets each direct child grow equally from the target width
- Resets direct child `min-inline-size` to `0` so wide content can shrink within the layout

### `cover`

Full-height vertical layout that centers the second child between optional leading and trailing content.

- Defaults `--cover-min-block-size` to `100dvh`
- Uses flex column layout
- Applies auto block margins to the second direct child

### `reel`

Horizontal scrolling row for media, cards, nav, or other items that should not wrap.

- Uses `var(--layout-space-inline)` for gap
- Uses the shared stack and inline spacing as internal scrollport padding so child shadows remain visible instead of being clipped at the Reel edges
- Allows inline overflow and hides vertical overflow
- Prevents direct children from shrinking so each item keeps its natural or assigned width

### `overflow-auto`

Overflow utility for elements that should show scrollbars only when content exceeds their bounds.

- Sets `overflow: auto`
- Use with an explicit size or max size so the browser has a boundary for overflow
- Allows scrolling in either axis when needed
- When the contents have no focusable controls, add `tabindex="0"`, `role="region"`, and an accessible name so keyboard users can enter and scroll the region

### `frame`

Aspect-ratio wrapper for media.

- Defaults `--frame-aspect-ratio` to `16 / 9`
- Clips overflowing media
- Sizes direct `img`, `video`, and `iframe` elements to fill the frame with `object-fit: cover`

### `masonry`

Multi-column layout for repeated content blocks when a staggered vertical flow is acceptable.

- Defaults `--masonry-min-column-size` to `16rem`
- Defaults `--masonry-column-gap` to `var(--layout-space-inline)`
- Defaults `--masonry-row-gap` to `var(--layout-space-stack)`
- Uses CSS columns for layout and applies `break-inside: avoid` to direct children
- Gives direct children `inline-size: 100%` and `margin-block-end: var(--masonry-row-gap)` so cards stack cleanly within each column

### `fluid`

Reset utility for making a container full width while keeping any existing padding.

- Removes default outer margin and any width cap on the element
- Use when an element should break out of a default content column without removing its local padding

### `flush`

Reset utility for removing default outer margin and inner padding.

- Removes default outer margin, inner padding, and any width cap on the element
- Use when an element should break out of a default content column and also clear built-in padding, such as `ul`

Use `fluid` when you want a container to span the available inline space while preserving padding. Use `flush` when you also need to remove built-in padding.

### `no-gap`

Reset utility for removing layout gaps.

- Sets `gap: 0`

## Native Primitives

The shared layout stylesheet also normalizes a small set of semantic HTML elements when they act like layout primitives.

### `main > header`

Direct child headers of the main landmark introduce the primary content area.

- Centers text so intro headings and supporting copy read as a page-level title block
- Leaves nested component and section headers to their local layout or component rules

### `<hr>`

Global subtle full-width divider that reads like a system border instead of the browser-default rule treatment.

- Uses `var(--layout-control-border-width)` and `var(--color-border-subtle)` for the line
- Resets native border chrome and outer margin
- Use when authors need an explicit divider between adjacent blocks, such as accordion items
- Keep spacing outside the `hr` itself so surrounding flow, utilities, or component structure control rhythm

## Authoring Rules

- Use shared layout tokens for density and rhythm before creating a new token.
- Keep component-specific aliases mapped back to shared tokens unless the component truly needs its own semantic token.
- Treat `1rem` as the base unit and size layout measurements against a `0.125rem` rhythm. That `0.125rem` rhythm comes from the underlying `2px` system, but token values should always be authored in `rem`, not `px`.
- The combined occupied space should land on that `0.125rem` rhythm even when the individual parts do not. Padding, border space, line height, and minimum height should work together to produce the intended step value.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/layout.spec.js).

- LAY-001: At `48rem` and wider, `.sidebar` lays out its children in a row, gives the first child `--sidebar-target-width` as its flex basis, and lets the last child absorb the remaining space.
- LAY-002: Below `48rem`, `.sidebar` stacks its children in source order and makes each child fill the available inline size.
- LAY-003: Below `48rem`, the first child resets its desktop target-width flex basis to `auto` so its block size follows its content instead of `--sidebar-target-width`.
- LAY-004: `.flow` preserves normal block layout and adds `--flow-space` only between adjacent children.
- LAY-005: `.cluster` creates a wrapping flex row, aligns peer items, removes direct child margins, and removes list markers when used on a list.
- LAY-006: `.justify-end` aligns flex items to the inline end.
- LAY-007: `.justify-between` distributes available inline space between flex items.
- LAY-008: `.stack` creates a vertical flex layout with the shared stack gap and removes list markers when used on a list.
- LAY-009: `.center` centers a content-box column, defaults its maximum inline size to `--layout-max-inline-size`, and preserves inline padding outside that width.
- LAY-010: `.grid` creates responsive equal-width columns from `--grid-min-column-size`, uses independent row and column gaps, and allows direct children to shrink without overflow.
- LAY-011: `.switcher` wraps equal-growth flex children from `--switcher-target-width` and allows their contents to shrink within the layout.
- LAY-012: `.cover` creates a full-height flex column and vertically centers its second direct child between optional leading and trailing content.
- LAY-013: `.reel` creates a padded, non-wrapping horizontal scroller whose direct children retain their natural or assigned inline size and whose padding keeps child shadows visible within the scrollport.
- LAY-014: `.overflow-auto` exposes browser-managed overflow scrolling on either axis when the element has a constrained size.
- LAY-015: `.frame` clips content to `--frame-aspect-ratio` and makes direct image, video, or iframe media fill the frame with `object-fit: cover`.
- LAY-016: `.masonry` uses CSS columns sized from `--masonry-min-column-size` and keeps each direct child intact while stacking it with the configured row gap.
- LAY-017: `.fluid` removes outer margin and maximum inline-size constraints while preserving the element's padding.
- LAY-018: `.flush` removes outer margin, inner padding, and maximum inline-size constraints.
- LAY-019: `.no-gap` removes the gap from any compatible grid or flex composition.
- LAY-020: An element composed with both `.sidebar` and `.center` fills its available inline size and includes the Center padding within that size so intrinsically wide sidebar content does not overflow the page.
- LAY-021: `--layout-surface-border-width` should match `--layout-control-border-width` in each layout theme while remaining a separate semantic token for bounded surfaces.
- LAY-022: A top-level `main` fills the available inline space up to the shared `--layout-max-inline-size` cap even when its contents have a narrow intrinsic width.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--grid-column-gap` | `<length>` | Column gap for the responsive grid utility. Defaults to `--layout-space-inline`. Use for: horizontal spacing between `.grid` columns Avoid for: vertical grid row spacing |
| `--grid-min-column-size` | `<length>` | Minimum column size for the responsive grid utility. Defaults to `16rem`. Use for: controlling when `.grid` items wrap into additional columns Avoid for: masonry or sidebar column sizing |
| `--grid-row-gap` | `<length>` | Row gap for the responsive grid utility. Defaults to `--layout-space-stack`. Use for: vertical spacing between `.grid` rows Avoid for: horizontal grid column spacing |
| `--layout-action-padding-block` | `<length>` | Vertical padding for action-style controls. Buttons use block padding that resolves with the reserved border to `0.75rem` of vertical occupied space per side. Use for: buttons, file chooser buttons, and similar action affordances that share the system action sizing Avoid for: text inputs, selects, or content spacing between separate components |
| `--layout-action-padding-inline` | `<length>` | Horizontal padding for action-style controls. This token is intentionally wider than `--layout-control-padding-inline` so buttons read as actions rather than text-entry fields. Comfortable action inline padding resolves to `2rem` after subtracting the reserved control border, which is `32px` when `1rem` is `16px`. Use for: `button`, `::file-selector-button`, and similar action affordances that should feel prominent and easy to target Avoid for: standard field padding or inter-component spacing |
| `--layout-anchor-scroll-offset` | `<length>` | Scroll offset for anchored elements such as `section[id]` so in-page navigation does not land underneath sticky UI. Use for: `scroll-margin-top` on anchor targets when a sticky header or nav is present Avoid for: physical layout spacing or visual padding inside sections |
| `--layout-control-border-width` | `<length-percentage>` | Default border width for standard controls. Use for: shared control borders when the system should apply one consistent border weight Avoid for: hairline dividers or expressive one-off borders |
| `--layout-control-gap` | `<length-percentage>` | Internal gap between items inside a composed control or small control group. Use for: icon and label spacing, inline control clusters, small grouped actions Avoid for: outer component margins |
| `--layout-control-icon-size` | `<length>` | Default icon size for icons that appear inside standard interactive controls. Control icons are slightly larger than the shared icon size so they hold their weight inside action and form controls. Use for: button icons, inline control affordances, and similar control-adjacent icons that should scale from the control type size Avoid for: standalone decorative icons or component-specific display icon treatments |
| `--layout-control-line-height-size` | `<length>` | Computed control line-height length used when layout sizing calculations need to combine body line-height with padding and borders. Derived from: `--font-size` and `--font-line-height-body` Use for: shared layout height and offset calculations Avoid for: direct text styling, which should use `--font-line-height-body` |
| `--layout-control-min-height` | `<length-percentage>` | Minimum height for standard form controls and similar interactive elements. Use for: buttons, inputs, selects, and textareas where a consistent control height is needed Avoid for: containers whose height is content-driven |
| `--layout-control-padding-block` | `<length>` | Vertical padding inside field-style controls. Control padding should be evaluated with the rest of the control sizing math, not in isolation. Text inputs use block padding that resolves with the reserved border to `1rem` of vertical occupied space per side. Use for: `input`, `select`, and `textarea` vertical padding Avoid for: spacing between separate components |
| `--layout-control-padding-inline` | `<length>` | Horizontal padding for field-style controls where content entry and scan efficiency matter. Use for: `input`, `select`, `textarea`, and similar controls that should feel content-driven and space-efficient Avoid for: buttons, button-like affordances, or inter-component spacing |
| `--layout-control-radius` | `<length-percentage>` | Corner radius for standard controls in each layout theme. Use for: default control corner treatment when the component follows the shared density system Avoid for: expressive component shapes that need their own semantic radius token |
| `--layout-focus-ring-size` | `<length-percentage>` | Default focus ring spread for interactive elements. Use for: focus-visible treatment on controls and actions Avoid for: static shadows or decorative halos |
| `--layout-landmark-padding-block` | `<length>` | Responsive vertical padding for top-level page landmarks when `<header>`, `<main>`, or `<footer>` are direct children of `<body>`. Use for: consistent top-level page breathing room, with `main` on the full value and page `header`/`footer` on half Avoid for: nested landmarks inside components or local section padding |
| `--layout-max-inline-size` | `<length-percentage>` | Maximum inline size for centered page and content containers. Use for: the default width cap shared by the top-level page shell and `.center` utility Avoid for: readable prose measure, which should be constrained independently |
| `--layout-page-min-inline-size` | `<length-percentage>` | Minimum inline size for the page shell. Use for: preventing full-page layouts from collapsing below the supported narrow viewport width Avoid for: component-level min-width decisions |
| `--layout-safe-area-top` | `<length>` | Top safe-area inset for devices with display cutouts such as iPhone notches. Use for: sticky top offsets or sticky container padding when content must clear the hardware inset Avoid for: ordinary spacing between content blocks on rectangular viewports |
| `--layout-section-margin-block-end` | `<length>` | Responsive block-end spacing applied to plain `<section>` elements so stacked document sections stay visually separated. Use for: default spacing between adjacent sections in long-form page layouts Avoid for: component-internal spacing or one-off card/list gaps |
| `--layout-shadow` | `Any` | Shared elevation shadow for raised layout surfaces. Use for: cards, popovers, and other raised regions that need the system elevation treatment Avoid for: dark mode, where the token resolves to none |
| `--layout-space-inline` | `<length-percentage>` | Horizontal spacing between peer elements arranged in a row. Use for: spacing between buttons, inline fields, and horizontal control groups Avoid for: text padding inside a control |
| `--layout-space-stack` | `<length-percentage>` | Vertical spacing between stacked elements such as labels, helper text, form rows, or grouped controls. Use for: vertical rhythm between related elements Avoid for: internal control padding |
| `--layout-sticky-offset` | `<length>` | Shared top offset for sticky elements inside page content. Use for: `top` on sticky content that should stay below persistent page chrome such as a sticky primary nav Avoid for: anchor scroll positioning or visual padding |
| `--layout-surface-border-width` | `<length>` | Default border width for bounded surfaces. Use for: cards, dialogs, code blocks, tooltips, and similar containers Avoid for: interactive control borders, hairline dividers, or expressive one-off borders |
| `--masonry-column-gap` | `<length>` | Column gap for the masonry utility. Defaults to `--layout-space-inline`. Use for: horizontal spacing between masonry columns Avoid for: vertical spacing between masonry items |
| `--masonry-min-column-size` | `<length>` | Minimum column size for the masonry utility. Defaults to `16rem`. Use for: controlling masonry column width Avoid for: responsive grid columns |
| `--masonry-row-gap` | `<length>` | Row gap for the masonry utility. Defaults to `--layout-space-stack`. Use for: block-end spacing between masonry items Avoid for: horizontal spacing between masonry columns |
| `--sidebar-gap` | `<length>` | Gap between sidebar and main content regions in the responsive sidebar utility. Defaults to twice `--layout-space-inline`. Use for: spacing the two `.sidebar` regions Avoid for: unrelated flex or grid gaps |
| `--sidebar-target-width` | `<length>` | Target width for the sidebar region in the responsive sidebar utility. Defaults to `20rem`. Use for: tuning the supporting column width in `.sidebar` layouts Avoid for: general page width constraints |
| `--switcher-target-width` | `<length>` | Target width for adaptive peers in the switcher utility. Defaults to `20rem`. Use for: controlling when `.switcher` children share a row or stack Avoid for: fixed child widths |

---

<!-- Source: src/css/loading.md -->

# Loading

## Overview

The loading component presents an indeterminate activity indicator while an action or content surface is waiting to finish.

The component styles nearly any element marked with `aria-busy="true"`. Native inputs, selects, and textareas are excluded because they do not reliably render generated content.

## Usage

For a button action that is still processing, combine `aria-busy="true"` with the native `disabled` attribute and keep a visible, action-specific label:

```html
<button disabled aria-busy="true" type="button">Saving…</button>
```

The `disabled` attribute prevents additional activation while `aria-busy="true"` exposes the loading state and adds the visual indicator.

For an inline status, apply the same state directly to the text container:

```html
<span aria-busy="true">Generating your report…</span>
```

For a card that is refreshing existing content, keep the content in place, mark the article as busy, and disable any controls that must not be activated during the update:

```html
<article aria-busy="true" aria-labelledby="busy-card-title">
  <header>
    <h3 id="busy-card-title">Quarterly update</h3>
  </header>

  <p>Content is being refreshed.</p>

  <footer>
    <button type="button" disabled>Publish</button>
  </footer>
</article>
```

The article loading treatment dims its direct child content to `48%` opacity, applies a `4px` blur, blocks pointer interaction, and centers the indicator over the existing layout. Because CSS pointer blocking does not prevent keyboard activation, native controls should use `disabled` when they must be unavailable.

The indicator inherits component defaults, but individual instances can override its color and size:

```html
<article
  aria-busy="true"
  style="--loading-color: currentColor; --loading-size: 2rem;"
></article>
```

Use this component when progress is indeterminate and the interface can only communicate that work is still underway.

Use a native `<progress>` element instead when the interface knows and can communicate how much work has completed.

The stylesheet does not determine when an operation begins or ends. The loading state remains present for as long as the rendered markup contains `aria-busy="true"` and disappears when a later render removes the attribute or changes its value.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- LOD-001: The component supports nearly any element marked with `aria-busy="true"`, including inline text, buttons, and articles.
- LOD-002: The indicator is generated with `::before` and does not require a loading class or child element.
- LOD-003: The default indicator is a `0.75rem` circular ring built from a conic gradient and radial mask.
- LOD-004: The ring rotates continuously while its visible arc grows and shrinks to communicate indeterminate progress.
- LOD-005: Buttons use `currentColor` by default so the indicator follows the current button variant.
- LOD-006: Button indicators use the same additional trailing spacing as inline button icons.
- LOD-007: Busy disabled buttons keep disabled visual styling and use the wait cursor.
- LOD-008: Busy articles use the neutral loading color, retain at least the shared minimum control height, and center the indicator over dimmed and blurred content.
- LOD-009: Removing `aria-busy="true"` or changing its value to `false` removes the generated indicator.
- LOD-010: Reduced-motion preferences should stop both animations and leave a static partial ring visible.
- LOD-011: `--loading-color` and `--loading-size` can override the default indicator appearance without changing its state or markup.
- LOD-012: Native inputs, selects, textareas, and the root HTML element should not receive a generated loading indicator.
## Accessibility

- Use `aria-busy="true"` only while the element is waiting for an operation or content update to finish.
- Pair busy buttons with the native `disabled` attribute when they must not be activated again; `aria-busy` does not disable interaction by itself.
- Keep a visible, action-specific button label such as `Saving…` or `Deleting…` rather than using a generic label such as `Loading`.
- Keep a busy article's accessible purpose clear through its heading, `aria-label`, or `aria-labelledby`.
- Disable native controls individually when they must not be activated; for controls without native disabled behavior, expose `aria-disabled="true"` and prevent activation in application code.
- Remove the busy state when the operation finishes so assistive technologies do not continue to treat the element as incomplete.
- Treat the generated ring as decorative; the semantic loading state comes from `aria-busy`, not from the visual animation.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--loading-arc` | `<angle>` | Sets the visible spinner arc angle; change it when a static loading indicator needs a shorter or longer ring. |
| `--loading-color` | `<color>` | Sets the spinner stroke color; change it when the indicator should differ from current text color. |
| `--loading-size` | `<length>` | Sets the inline and block size of loading indicators; change it when spinners need to fit a different control or container scale. |
| `--loading-stroke` | `<length>` | Sets the spinner ring thickness; change it when the loading indicator should appear heavier or lighter. |
| `--loading-tail` | `<angle>` | Sets the spinner arc's trailing-edge position; change it to rotate a static partial ring without transforming the indicator. |

## Depends On

- `--layout-control-border-width`

---

<!-- Source: src/css/nav.md -->

# Nav

## Overview

Nav is the default visual expression of a plain navigation element in this design system.

The component styles a native `<nav>` with a direct child `<ul>` or `<ol>` as a sticky horizontal row of links.

Users move to another destination through real links; no content is hidden behind tab panels.

Use breadcrumbs for hierarchy trails and pagination for paged result controls.

## Usage

```html
<nav aria-label="Site">
  <ul>
    <li><a href="/overview">Overview</a></li>
    <li><a href="/tokens" aria-current="page">Tokens</a></li>
    <li><a href="/components">Components</a></li>
  </ul>
</nav>
```

Use this pattern when users need to jump between peer destinations such as sections, pages, or documentation areas while keeping all content visible.

Do not use buttons when the interaction changes location instead of triggering an action.

Use `nav.toc` for in-page table-of-contents navigation:

```html
<nav class="toc" aria-label="On this page">
  <h2>On this page</h2>
  <ul>
    <li><a href="#overview">Overview</a></li>
    <li><a href="#usage">Usage</a></li>
  </ul>
</nav>
```

Current limitation: `.toc` does not automatically highlight a link as its target section becomes current during manual scrolling. CSS [`scroll-target-group`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-target-group) and `:target-current` can provide scroll-position-aware highlighting without JavaScript, but they are not yet Baseline Widely Available. Adopt them as a progressive enhancement when they reach that support level.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- NAV-001: Nav renders as a single horizontal row of links and allows horizontal overflow on smaller screens instead of wrapping onto multiple lines.
- NAV-002: Links should keep native link semantics instead of using tab roles or button behavior.
- NAV-003: Current-location items should be identified with `aria-current` and remain visually distinct from sibling links.
- NAV-004: The nav is sticky by default, and in-content sticky elements should inherit the shared layout offset so they stop below it instead of sliding underneath it.
- NAV-005: The direct child primary navigation uses a higher stack level than in-page navigation so page-level navs scroll underneath it.
- NAV-006: Comfortable and compact density come from the shared layout tokens for min-height, padding, and gap.
- NAV-007: `.toc` renders in-page navigation as a sticky table of contents at wider viewports without relying on accessible-name text for styling, and its links match dropdown navigation links with full control padding and a subtle background on hover or keyboard focus.
- NAV-008: Default nav styles activate only when the navigation has a direct child `ul` or `ol`, leaving navigation with a different markup contract untouched.
## Accessibility

- Use a native `<nav>` with a clear accessible name through `aria-label` or `aria-labelledby` when the page has more than one navigation landmark.
- Use `.toc` for table-of-contents styling and keep `aria-label` or `aria-labelledby` for the accessible name only.
- Keep destinations as real `<a>` elements so keyboard, history, and assistive technology behavior remain intact.
- Use `aria-current="page"` or `aria-current="location"` on the current destination when it remains a link.
- Do not add ARIA tab roles unless the interface is a real tabbed panel system with the expected keyboard behavior.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--nav-border-color` | `<color>` | Sets the bottom border color for navigation bars; change it when nav needs more or less separation from content. |
| `--nav-color-accent-subtle` | `<color>` | Sets --nav-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-color-focus-ring` | `<color>` | Sets --nav-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-control-border-width` | `<length>` | Sets --nav-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-control-gap` | `<length>` | Sets --nav-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-control-min-height` | `<length>` | Sets --nav-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-control-padding-block` | `<length>` | Sets --nav-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-control-padding-inline` | `<length>` | Sets --nav-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-current-background` | `<color>` | Sets the background behind the current nav item; change it when the selected page state needs a stronger or subtler surface. |
| `--nav-focus-ring-size` | `<length>` | Sets --nav-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-font-family-sans` | `Any` | Sets --nav-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-font-size` | `<length>` | Sets --nav-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-line-height` | `<number>` | Sets --nav-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-link-color` | `<color>` | Sets the default nav link color; change it when nav links should inherit a different page or header context. |
| `--nav-link-current-color` | `<color>` | Sets the current nav item text and underline color; change it when selected navigation should use a different accent. |
| `--nav-link-hover-color` | `<color>` | Sets the hover color for nav links; change it when navigation needs a clearer interactive cue. |
| `--nav-page-min-inline-size` | `<length>` | Sets --nav-page-min-inline-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-safe-area-top` | `<length>` | Sets --nav-safe-area-top so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-space-inline` | `<length>` | Sets --nav-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--nav-space-stack` | `<length>` | Sets the block gap used by table-of-contents navigation; change it when in-page navigation needs denser or looser item rhythm. |
| `--nav-sticky-offset` | `<length>` | Sets the sticky top offset for table-of-contents navigation; change it when in-page nav needs to clear custom persistent chrome. |

## Depends On

- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-focus-ring-size`
- `--layout-page-min-inline-size`
- `--layout-safe-area-top`
- `--layout-space-inline`
- `--layout-space-stack`
- `--layout-sticky-offset`

---

<!-- Source: src/css/pagination.md -->

# Pagination

## Overview

The pagination component presents table paging controls and summary text in a compact navigation row.

The component styles pagination-specific content inside a native `<nav class="pagination">`, with optional summary text in a `<p>` and page controls as links.

Pagination is still a navigation pattern, but it serves a narrower purpose than primary navigation: it moves through slices of a result set rather than between peer destinations in the product.

## Usage

```html
<nav class="pagination" aria-label="Pagination for search results">
  <p>1-10 of 42</p>
  <a href="?page=1" aria-label="Previous page">Previous</a>
  <a href="?page=3" aria-label="Next page">Next</a>
</nav>
```

Use this component when the interface needs to page through table results and keep the paging affordances grouped with the current range.

Use a different navigation pattern instead when the controls do not paginate tabular data.

Use a specific navigation label that identifies the paged result set.

Use real links for page changes so pagination remains navigable without JavaScript.

Visual grouping is acceptable, but the controls should continue to behave like links instead of action buttons.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js).

- PAG-001: Row alignment and wrapping are built into the pagination component, and controls align to the inline end by default.
- PAG-002: Summary text remains unwrapped so ranges stay easy to scan.
- PAG-003: Pagination links inherit the shared control height and horizontal rhythm without taking on button semantics.
- PAG-004: Pagination icons use `--pagination-icon-color`, which defaults to a theme text token and can be overridden by the component consumer.
- PAG-005: Comfortable and compact density should come from the shared layout tokens rather than pagination-specific theme branches.
## Accessibility

- Use a native `<nav>` so assistive technologies can announce the region as navigation.
- Keep `class="pagination"` on the navigation element so the component styles activate.
- Use a specific `aria-label` on the navigation element so assistive technologies can distinguish pagination regions when a page has more than one result set.
- Use descriptive link text or `aria-label` values so previous and next controls are clear out of context.
- Keep the summary text in the DOM so the current item range is available to all users.
- Do not replace links with non-semantic elements for page navigation.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--pagination-color-text` | `<color>` | Sets --pagination-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-min-height` | `<length>` | Sets --pagination-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-padding-block` | `<length>` | Sets --pagination-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-padding-inline` | `<length>` | Sets --pagination-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-icon-color` | `<color>` | Sets the color of pagination icons; change it when previous and next controls need to match a different navigation context. |
| `--pagination-space-inline` | `<length>` | Sets --pagination-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-text`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-space-inline`

---

<!-- Source: src/css/progress.md -->

# Progress

## Overview

The progress component styles the native `<progress>` element for determinate and indeterminate task progress.

Use it when the interface needs to show completion amount without naming every step, or when a stepper would be too long to scan comfortably. Use the stepper component instead when the user needs to understand a short sequence of named steps and their current position within that sequence.

## Usage

For known progress, provide `value` and `max`:

```html
<progress value="70" max="100">70%</progress>
```

For unknown or ongoing progress, omit `value`:

```html
<progress></progress>
```

Keep fallback text inside the element so older assistive technology and browsers without full progress support still have a readable value.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- PRG-001: The filled bar uses the primary color through `--progress-value-color`.
- PRG-002: The track uses the subtle primary color through `--progress-track-color`.
- PRG-003: Determinate progress uses the browser's native `value` and `max` behavior.
- PRG-004: Indeterminate progress animates a solid bar across the track when `value` is omitted.
- PRG-005: The indeterminate animation respects `prefers-reduced-motion: reduce` by stopping the animation and centering the bar.
- PRG-006: The component uses native progress pseudo-elements for Chromium, Safari, and Firefox.
## Accessibility

- Use `value` and `max` only when the amount of progress is known.
- Omit `value` for indeterminate work instead of setting a placeholder value.
- Include concise fallback text for determinate progress, such as `70%`.
- If the value is not intederminate, use `aria-valuenow` for assistive technologies.
- Add a visible label, `aria-label`, or `aria-labelledby` when surrounding text does not clearly identify what the progress bar represents.
- Do not use color alone as the only progress explanation when a precise value matters; include text nearby when users need the number.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--progress-border-radius` | `<length>` | Sets the rounding for progress tracks and clipping; change it to make progress bars pill-shaped or squared. |
| `--progress-height` | `<length>` | Sets the block size of progress bars; change it when progress indicators need more visual weight or denser layout. |
| `--progress-track-color` | `<color>` | Sets the unfilled track color for native and custom progress states; change it when the remaining portion needs different contrast. |
| `--progress-value-color` | `<color>` | Sets the filled progress color and native accent color; change it when completion should use a different brand or status color. |

## Depends On

- `--color-accent`
- `--color-primary`
- `--color-primary-subtle`
- `--layout-control-radius`

---

<!-- Source: src/css/radio.md -->

# Radio

## Overview

The radio component is a single-select form control for choosing exactly one option from a related set.

The component pattern uses a native `<fieldset>` with a native `<legend>` and native radio inputs inside wrapping `<label>` elements, so the group keeps its semantics without requiring classed wrappers.

## Usage

```html
<fieldset>
  <legend>Contact method</legend>
  <label>
    <input type="radio" name="contact-method" value="email" checked />
    Email
  </label>
  <label>
    <input type="radio" name="contact-method" value="phone" />
    Phone
  </label>
</fieldset>
```

Use this component when the user must pick one option from a small, always-visible set.

Use a select instead when the list is longer or should stay collapsed until interaction.

The group should use native `<fieldset>` and `<legend>` elements so assistive technology announces the shared question and the currently selected option in context.

Each radio should stay inside its own wrapping `<label>` so the full text remains clickable without extra helper markup.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- RDO-001: The group stacks options with shared layout theme spacing rather than radio-specific density values.
- RDO-002: Each option keeps native radio rendering and browser interaction while the accent color follows the shared primary token.
- RDO-003: Disabled options should dim through shared text tokens rather than bespoke disabled colors.
- RDO-004: Focus must remain clearly visible for keyboard users.
## Accessibility

- Use a native `<fieldset>` and `<legend>` for related radio questions instead of a plain container and heading.
- Give every radio in the group the same `name` so browsers enforce the single-selection rule.
- Wrap each radio in a native `<label>` so the label text enlarges the interactive target.
- Keep option text descriptive enough to make sense when announced on its own.
- Do not replace the native radio with custom scripted markup unless the product truly requires behavior the platform cannot provide.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--radio-color-primary` | `<color>` | Sets --radio-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-color-primary-subtle` | `<color>` | Sets --radio-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-color-text` | `<color>` | Sets --radio-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-color-text-accent` | `<color>` | Sets --radio-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-color-text-subtle` | `<color>` | Sets --radio-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-control-border-width` | `<length>` | Sets --radio-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-control-gap` | `<length>` | Sets --radio-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-focus-ring-size` | `<length>` | Sets --radio-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-font-family-sans` | `Any` | Sets --radio-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-font-size` | `<length>` | Sets --radio-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-line-height` | `<number>` | Sets --radio-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--radio-space-inline` | `<length>` | Sets --radio-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-primary`
- `--color-primary-subtle`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/range.md -->

# Range

## Overview

The range component is a native slider for choosing a value within a bounded numeric range.

Use a range when the user is choosing an approximate value within a span. Do not use it for precise numeric entry; use a native number input instead.

## Usage

```html
<label>
  <span data-role="label">Volume</span>
  <input type="range" min="0" max="100" value="50" />
  <span data-role="range-limits" aria-hidden="true">
    <span>0</span>
    <span>100</span>
  </span>
</label>
```

Use `[data-role="range-limits"]` when the minimum and maximum should stay visible below the slider.

## Accessibility

- Use a native `<label>` so the slider keeps an explicit accessible name.
- Keep the min and max in nearby text when they help users understand the scale.
- Do not add JavaScript-only value displays unless the page still works without them.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--range-color-accent-disabled` | `<color>` | Sets --range-color-accent-disabled so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-border-inverse` | `<color>` | Sets --range-color-border-inverse so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-border-subtle` | `<color>` | Sets --range-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-focus-ring` | `<color>` | Sets --range-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-primary` | `<color>` | Sets --range-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-text-accent` | `<color>` | Sets --range-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-color-text-subtle` | `<color>` | Sets --range-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-control-border-width` | `<length>` | Sets --range-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-control-gap` | `<length>` | Sets --range-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-control-min-height` | `<length>` | Sets --range-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-control-radius` | `<length>` | Sets --range-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-focus-ring-size` | `<length>` | Sets --range-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-font-size` | `<length>` | Sets --range-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-font-size-caption` | `<length>` | Sets --range-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-line-height` | `<number>` | Sets --range-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-space-inline` | `<length>` | Sets --range-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--range-thumb-size` | `<length>` | Sets the draggable thumb size for range inputs; change it when the handle needs a larger target or a lighter visual footprint. |
| `--range-track-size` | `<length>` | Sets the track thickness for range inputs; change it with thumb size so the thumb stays visually centered on the rail. |

## Depends On

- `--color-accent-disabled`
- `--color-border-inverse`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-min-height`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/select.md -->

# Select

## Overview

The select component supports native single-select fields for choosing one value from a predefined list.

The component pattern uses a native `<label>` that wraps a native `<select>`, so the control can be styled without requiring a classed wrapper.

## Usage

```html
<label>
  <span>Which BYU Creamery ice cream should we scoop?</span>
  <select required>
    <option value="" selected disabled>Select a flavor</option>
    <option>Graham Canyon</option>
    <option>Mint Brownie</option>
    <option>Peaches and Cream</option>
  </select>
</label>

```

Use this component when the user needs to choose one option from a known set and native browser form semantics should remain intact.

Use radios instead when a single small set should stay visible at once, checkboxes when users may choose more than one option, or a text input when users need to enter a freeform value.

The label should remain visible above the field rather than relying on the initial option as the only field description.

The field should use native `<label>` and `<select>` elements so the control keeps browser form behavior, keyboard support, and assistive technology semantics.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- SEL-001: Single-select fields render a control-owned downward chevron treatment while preserving native select semantics.
- SEL-002: Single-select fields reserve inline space for the chevron indicator so text and the icon do not collide.
- SEL-003: The chevron source is controlled by `--select-icon-source`, which should resolve to a complete background image so consumers can replace the default indicator without rewriting component selectors.
- SEL-004: The chevron offset, size, and reserved space should derive from shared layout theme tokens rather than hardcoded component-only measurements.
- SEL-005: Single-select fields can start with muted text color and switch to the default text color once the field becomes `:valid`.
- SEL-006: Multi-select fields and sized listboxes keep the browser-native listbox appearance instead of forcing a dropdown chevron treatment.
- SEL-007: Multi-select fields remain styled for exceptional or legacy cases, but checkboxes should be the default pattern for nearly all multi-choice fields.
- SEL-008: Focus must remain clearly visible for keyboard users.
- SEL-009: Comfortable and compact density should come from the layout theme tokens rather than select-specific spacing values.
## Accessibility

- Use a native `<label>` so the field stays explicitly named.
- If the label does not wrap the select, associate them with matching `for` and `id` attributes.
- Do not rely on the initial placeholder-like option as the only label for the field.
- Keep option text descriptive enough to make sense when announced on its own.
- Use native constraints such as `required` when the first option is only a prompt and not a valid selection.
- Prefer checkbox groups when users can choose multiple values.
- If an exceptional or legacy `multiple` select is necessary, use the `size` attribute so enough options remain visible without extra scrolling.
- If a select is meant to render as a listbox, keep the native `size` or `multiple` behavior rather than trying to force the single-select chevron treatment onto it.
- Intentionally do not try to style the native select menu or picker. Custom picker treatments can break assistive technology behavior, add maintenance cost, and become brittle across browsers and operating systems.
- Revisit this once the newer browser-native customizable select features are supported in Firefox and Safari. [Browser compatibility](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Customizable_select#browser_compatibility) already shows support across most major browsers, and it gives us a cleaner future opt-in path than replacing the native picker ourselves.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--select-color-border-subtle` | `<color>` | Sets --select-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-color-focus-ring` | `<color>` | Sets --select-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-color-primary` | `<color>` | Sets --select-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-color-text` | `<color>` | Sets --select-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-color-text-accent` | `<color>` | Sets --select-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-color-text-subtle` | `<color>` | Sets --select-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-border-width` | `<length>` | Sets --select-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-gap` | `<length>` | Sets --select-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-min-height` | `<length>` | Sets --select-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-padding-block` | `<length>` | Sets --select-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-padding-inline` | `<length>` | Sets --select-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-control-radius` | `<length>` | Sets --select-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-focus-ring-size` | `<length>` | Sets --select-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-font-size` | `<length>` | Sets --select-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--select-icon-offset` | `<length>` | Sets the inline offset between the select chevron and the control edge; change it when padding or icon alignment changes. |
| `--select-icon-size` | `<length>` | Sets the select chevron size; change it when the indicator should scale differently from the field text. |
| `--select-icon-source` | `<image> | none` | Sets the chevron image used by select fields; change it to swap the indicator artwork or color. |
| `--select-line-height` | `<number>` | Sets --select-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-icon-size`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/stepper.md -->

# Stepper

## Overview

The stepper component shows ordered progress through a short sequence of steps such as onboarding, checkout, or form completion.

The component styles a native ordered list inside a `.stepper` container and uses list item state attributes to distinguish complete, current, and upcoming steps.

## Usage

```html
<div class="stepper">
  <ol aria-label="Account setup progress">
    <li data-step-state="complete">
      <p>Account details</p>
    </li>
    <li aria-current="step">
      <p>Profile setup</p>
    </li>
    <li>
      <p>Review and submit</p>
    </li>
  </ol>
</div>
```

Use this component when the interface needs to show where the user is within a small, linear set of steps.

Use [progress.css](./progress.md) instead when the sequence is too long for a stepper to scan comfortably or when the user only needs overall completion rather than each named step.

Use nav instead when the sections are not strictly sequential or the user can move freely between them.

Each step label should stay short enough to scan quickly without wrapping into long blocks of text.

The current step should use `aria-current="step"` and completed steps should use `data-step-state="complete"` so visual state does not replace semantic structure.

Apply the `.stepper` class to the immediate parent wrapper so the component has an inline-size query container for its stacked layout.

Give the ordered list a descriptive accessible name with `aria-label` or `aria-labelledby` so assistive technologies can announce what progress the list represents.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- STP-001: The component uses the ordered list counter for default step numbers rather than requiring explicit numeric content in the markup.
- STP-002: Completed steps replace the number with a check icon and tint the connector line with the success color.
- STP-003: The completed-step check icon color is controlled by `--stepper-complete-icon-color`, which should alias a theme semantic token.
- STP-004: The current step increases emphasis with a stronger label weight and a brand-colored outer ring around the step indicator.
- STP-005: Upcoming steps use a strong surface fill and subtle border track so the completed and current states carry the strongest emphasis.
- STP-006: Comfortable and compact density come from the shared layout theme tokens rather than stepper-specific theme branches.
- STP-007: When the stepper container gets narrow enough, the layout stacks vertically and the connector line shifts from horizontal to vertical.
- STP-008: If the `.stepper` wrapper is omitted, the ordered list will not receive the component styles or container-query-driven stacked layout.
## Accessibility

- Use a native `<ol>` so assistive technologies can announce the total number of steps and the user’s position in the sequence.
- Keep the list's accessible name descriptive, such as `aria-label="Checkout progress"` or `aria-labelledby` pointing to a visible heading.
- Use `aria-current="step"` only on the active step.
- Do not use `aria-label` as a visual state hook on individual steps because that can override the accessible name.
- Keep visible step text meaningful on its own, since the indicator circle is decorative context rather than the primary label.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--stepper-active-color` | `<color>` | Sets the current-step indicator fill and outer ring color; change it when the active step should use a different brand or status accent. |
| `--stepper-color-accent` | `<color>` | Sets --stepper-color-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-color-text` | `<color>` | Sets --stepper-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-color-text-inverse` | `<color>` | Sets --stepper-color-text-inverse so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-complete-color` | `<color>` | Sets completed-step indicator fills and completed connector lines; change it when finished steps should use a different success treatment. |
| `--stepper-complete-font-size` | `<length>` | Sets the Material Symbols checkmark size for completed steps; change it when the check should feel larger or smaller inside the circle. |
| `--stepper-complete-icon-color` | `<color>` | Sets the checkmark color on completed steps; change it when the completed fill color requires a different contrast pairing. |
| `--stepper-gap` | `<length>` | Sets horizontal spacing between steps and factors into connector length; change it to make wide steppers more compact or more open. |
| `--stepper-icon-font-family` | `Any` | Sets --stepper-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-idle-color` | `<color>` | Sets the fill color for future step indicators; change it when inactive steps need more or less visual weight. |
| `--stepper-indicator-font-size` | `<length>` | Sets the number size inside idle and active step indicators; change it when step numbers should scale independently from labels. |
| `--stepper-indicator-size` | `<length>` | Sets the diameter of each step indicator and drives connector positioning; change it when targets or visual hierarchy need larger or smaller circles. |
| `--stepper-label-font-size` | `<length>` | Sets the text size for step labels; change it when step descriptions should be denser or more prominent. |
| `--stepper-line-offset` | `<length>` | Sets the horizontal inset between an indicator and its connector line; change it when connectors should start closer to or farther from circles. |
| `--stepper-line-thickness` | `<length>` | Sets connector line thickness in horizontal and stacked layouts; change it when progress lines need stronger or subtler emphasis. |
| `--stepper-ring-gap` | `<length>` | Sets the gap between the active indicator and its outer ring; change it to tune the current-step halo spacing. |
| `--stepper-ring-size` | `<length>` | Sets the thickness of the active-step outer ring; change it when the current step needs a stronger or lighter halo. |
| `--stepper-space-inline` | `<length>` | Sets --stepper-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-space-stack` | `<length>` | Sets --stepper-space-stack so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--stepper-stack-gap` | `<length>` | Sets vertical spacing between steps in the stacked container layout; change it when narrow steppers need more or less breathing room. |
| `--stepper-track-color` | `<color>` | Sets the connector color for incomplete step paths; change it when remaining progress should appear more or less prominent. |

## Depends On

- `--color-accent`
- `--color-accent-strong`
- `--color-border-subtle`
- `--color-primary`
- `--color-success`
- `--color-text`
- `--color-text-inverse`
- `--font-size`
- `--icon-font-family`
- `--layout-control-min-height`
- `--layout-focus-ring-size`
- `--layout-space-inline`
- `--layout-space-stack`
## Migrating From Unstack

The stepper is not a drop-in replacement for the Unstack stepper because the wrapper and completed-step state hook changed.

Update this Unstack markup:

```html
<ol aria-label="Progress">
  <li aria-label="complete">
    <p>Create Account</p>
  </li>
  <li aria-current="step">
    <p>Personal Information</p>
  </li>
  <li>
    <p>Summary</p>
  </li>
</ol>
```

To this component contract:

```html
<div class="stepper">
  <ol aria-label="Account setup progress">
    <li data-step-state="complete">
      <p>Create Account</p>
    </li>
    <li aria-current="step">
      <p>Personal Information</p>
    </li>
    <li>
      <p>Summary</p>
    </li>
  </ol>
</div>
```

Migration steps:

- Add the `.stepper` wrapper around the ordered list so the container-query stacked layout can activate.
- Replace the generic `aria-label="Progress"` with a descriptive accessible name, such as `aria-label="Account setup progress"` or `aria-labelledby` pointing to a visible heading.
- Replace `aria-label="complete"` on completed steps with `data-step-state="complete"` so visual state does not override the step's accessible name.
- Keep `aria-current="step"` on the current step.
- Include the required color, layout, typography, and icon tokens listed above before using the component.

---

<!-- Source: src/css/switch.md -->

# Switch

## Overview

The switch component is a binary form control for immediately toggling a setting on or off.

The component pattern uses a native checkbox input with `role="switch"` inside a wrapping `<label>`, so it keeps checkbox form behavior while assistive technology can announce the control as a switch.

## Usage

```html
<label>
  <input type="checkbox" role="switch" name="notifications-enabled" checked />
  Notifications
</label>
```

Use this component when the user is toggling a single setting.

Use a checkbox instead when the user is selecting one or more items from a set, or when the control represents agreement rather than an on/off state.

The input should stay inside its wrapping `<label>` so the full text remains clickable without extra helper markup.

For switches with an obvious visual state pair, opt into icons with `data-switch-icons` and provide Material Symbols glyph names for both states:

```html
<label>
  <input
    type="checkbox"
    role="switch"
    name="dark-mode"
    data-switch-icons
    data-switch-on-icon="dark_mode"
    data-switch-off-icon="light_mode"
  />
  Dark mode
</label>
```

The icon attributes are:

- `data-switch-icons`: opts the switch into icon rendering and replaces the default `Off` and `On` track text.
- `data-switch-off-icon`: Material Symbols glyph name shown when the switch is unchecked.
- `data-switch-on-icon`: Material Symbols glyph name shown when the switch is checked.

Both icon-name attributes should be present when using `data-switch-icons`. If either one is missing, that state has no visible track icon.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- SWT-001: The control uses native checkbox state, form submission, keyboard interaction, and disabled behavior.
- SWT-002: The switch styling only applies to checkbox inputs with `role="switch"`.
- SWT-003: The track shows `Off` when unchecked and `On` when checked.
- SWT-004: Switches with `data-switch-icons` replace the track text with the configured off and on icons.
- SWT-005: Checked switches use the shared primary token for the active track.
- SWT-006: Disabled switches dim through shared disabled surface and text tokens.
- SWT-007: Focus must remain clearly visible for keyboard users.
## Accessibility

- Use `type="checkbox"` with `role="switch"` for the input.
- Wrap the input in a native `<label>` or associate it with a label using `for` and `id`.
- Use concise label text that describes the setting being toggled.
- Treat track icons as decorative; the visible label still needs to describe the setting.
- Do not use a switch for multi-select lists; use the checkbox component instead.
- If helper or error text is needed, place it near the control and associate it with `aria-describedby`.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--switch-color-accent` | `<color>` | Sets --switch-color-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-border` | `<color>` | Sets --switch-color-border so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-border-strong` | `<color>` | Sets --switch-color-border-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-border-subtle` | `<color>` | Sets --switch-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-focus-ring` | `<color>` | Sets --switch-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-primary` | `<color>` | Sets --switch-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-text` | `<color>` | Sets --switch-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-text-inverse` | `<color>` | Sets --switch-color-text-inverse so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-color-text-subtle` | `<color>` | Sets --switch-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-control-border-width` | `<length>` | Sets --switch-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-focus-ring-size` | `<length>` | Sets --switch-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-font-family-sans` | `Any` | Sets --switch-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-font-size` | `<length>` | Sets --switch-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-font-size-caption` | `<length>` | Sets --switch-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-font-weight-body-regular` | `<number>` | Sets --switch-font-weight-body-regular so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-icon-fill` | `<number>` | Sets --switch-icon-fill so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-icon-font-family` | `Any` | Sets --switch-icon-font-family so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-icon-grad` | `<number>` | Sets --switch-icon-grad so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-icon-opsz` | `<number>` | Sets --switch-icon-opsz so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-icon-wght` | `<number>` | Sets --switch-icon-wght so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-line-height` | `<number>` | Sets --switch-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-space-inline` | `<length>` | Sets --switch-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--switch-thumb-size` | `<length>` | Sets the switch thumb diameter and checked-state travel distance; change it with track height to preserve alignment. |
| `--switch-track-background` | `<color>` | Sets the switch track fill for off, on, focus, and disabled states; change it when switch state colors need a different semantic treatment. |
| `--switch-track-height` | `<length>` | Sets the switch track height and influences thumb sizing and vertical alignment; change it to tune control density. |
| `--switch-track-width` | `<length>` | Sets the switch track width and available thumb travel; change it when the switch should look more compact or more spacious. |

## Depends On

- `--color-accent`
- `--color-accent-disabled`
- `--color-border`
- `--color-border-strong`
- `--color-border-subtle`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-inverse`
- `--color-text-subtle`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--font-weight-body-regular`
- `--icon-fill`
- `--icon-font-family`
- `--icon-grad`
- `--icon-opsz`
- `--icon-wght`
- `--layout-control-border-width`
- `--layout-control-min-height`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/table.md -->

# Table

## Overview

The table component presents structured, scan-friendly data in rows and columns.

The component should style a native `<table>` with proper table elements such as `<caption>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>`.

## Usage

```html
<table>
  <caption>Team Members</caption>
  <thead>
    <tr>
      <th scope="col" aria-sort="ascending">
        <a href="?sort=name">
          <span>Name</span>
        </a>
      </th>
      <th scope="col">Role</th>
      <th scope="col">Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alex Morgan</td>
      <td>Designer</td>
      <td>Active</td>
    </tr>
  </tbody>
</table>
```

Use this component when the user needs to compare values across multiple rows and columns.

Use a list, cards, or grouped sections instead when the content is primarily narrative, does not share consistent columns, or needs to reflow freely on small screens.

Column labels should stay short and specific so users can scan the header row quickly.

Use native table elements so the content keeps built-in semantics for row and column relationships.

Use the default table for data-heavy views that compare many rows, especially when the data has many columns or requires pagination. Wrap it in `.overflow-auto` so its intrinsic column width scrolls inside a bounded region instead of widening the page.

Use `.table-switcher` for a short, typically unpaginated list with a small, known set of fields. Each row should remain understandable as a self-contained record when its cells stack. Repeat each column heading in the corresponding cell's `data-label`; the wrapper uses its own inline size to switch the table into labeled row cards below `40rem`. Because `data-label` renders as plain generated text, it cannot contain a button or link that filters or sorts the table.

Both approaches are responsive. The default table preserves column alignment and scrolls within its bounded region, while the table switcher reformats rows for narrow containers. Keep data-heavy reporting and comparison tables in the default layout; if the results require pagination, the default table is probably the better fit.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js).

- TBL-001: Rows and cells should size from content and the shared table density tokens.
- TBL-002: Comfortable and compact density should come from `--table-row-min-height`, `--table-cell-padding-block`, and `--table-cell-padding-inline`.
- TBL-003: Tables fill their container with `width: 100%` and use the native automatic table layout so intrinsic column content can overflow a bounded wrapper when necessary.
- TBL-004: Header cells should remain visually distinct from body cells through semantic text color and optional inline alignment for labels and sort indicators.
- TBL-005: A header becomes clickable only when its direct child is a link. Plain header text and `th > span` wrappers should remain non-interactive.
- TBL-006: Header links should not use default underline or visited-link styling. They should inherit the table header presentation while keeping native link semantics.
- TBL-007: Functional header icons should appear only inside header links. Do not include sort or action icons in non-interactive headers.
- TBL-008: Icons inside table headers and cells inherit the surrounding table text color unless a nested icon style overrides that behavior.
- TBL-009: Divider treatment should use the shared border and surface tokens rather than table-specific color primitives.
- TBL-010: A table inside a bounded overflow container keeps that region keyboard accessible and programmatically named even when the table has no interactive content.
- TBL-011: A table directly inside `.table-switcher` uses its `max-content` width above `40rem` so wide columns can scroll, then stacks each body row below that container width.
- TBL-012: Stacked cells expose their `data-label` as a visible, non-interactive heading while the native table head remains available to assistive technology.
- TBL-013: A sortable header exposes its state with `aria-sort` on the `<th>` and places its sort link directly inside that header.
- TBL-014: Sortable headers generate an ascending, descending, or unsorted icon from `aria-sort="ascending"`, `aria-sort="descending"`, or `aria-sort="none"`; `aria-sort="other"` uses the unsorted icon for compatibility.
For exact table token values and layout-theme branches, use [table.css](/Users/stuft2/Projects/design-tokens/src/css/table.css) as the source of truth.
## Accessibility

- Use a native `<table>` only for tabular data where each cell relates to a row and column header.
- Include a `<caption>` when the table needs a visible or programmatic title.
- Use `<th scope="col">` for column headers and `<th scope="row">` for row headers when rows need a primary label.
- Keep header labels descriptive enough to make sense when announced with cell values by assistive technology.
- If a header is interactive, use a real `<a>` element so keyboard, focus, and navigation behavior remain intact.
- Put `aria-sort` on the column header, not the link. Use `none` on inactive sortable columns and `ascending` or `descending` only on the currently sorted column. Update the value when sorting changes; the visual icon is generated from that state and remains decorative.
- Give a bounded overflow wrapper `tabindex="0"`, `role="region"`, and a name that references the table caption so keyboard users can enter and scroll it.
- Use `.table-switcher` only for short, simple tables whose rows remain understandable as individual records. Keep paginated, data-heavy, comparison-heavy, sortable, selectable, or multi-level tables in their native scrolling layout.
- Every body cell in a responsive table needs a `data-label` matching its column heading; this visible duplicate supplements rather than replaces native header associations.
- Keep switcher `data-label` values to plain text. They cannot provide buttons or links for filtering or sorting; use the default table when column headings need interactive controls.
- Do not use tables for page layout or purely visual alignment.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--table-actions-cell-width` | `<length>` | Sets the fixed width for action columns; change it when row action controls need more or less reserved space. |
| `--table-background` | `<color>` | Sets the table and body cell background; change it when the table surface should differ from the page or header background. |
| `--table-body-text-color` | `<color>` | Sets body cell text color; change it when table data needs different contrast from surrounding content. |
| `--table-border-style` | `<custom-ident>` | Sets row divider line style; change it only when table separators should use a non-solid style. |
| `--table-border-width` | `<length>` | Sets row divider thickness and participates in density calculations; change it when table separators need a heavier or lighter rule. |
| `--table-cell-padding-block` | `Any` | Sets density-specific vertical cell padding before border compensation; change it to tune comfortable or compact row breathing room. |
| `--table-cell-padding-inline` | `Any` | Sets density-specific horizontal cell padding before compact-column adjustments; change it to tune table scan density. |
| `--table-cell-padding-inline-start` | `Any` | Sets the leading and trailing edge padding for special columns; change it when table edges should align differently from normal cells. |
| `--table-checkbox-cell-width` | `<length>` | Sets the fixed width for checkbox selection columns; change it when selection controls need more or less reserved space. |
| `--table-column-expand-width` | `<length>` | Sets the fixed width for expand columns; change it when disclosure or expansion controls need a wider label or target area. |
| `--table-divider-color` | `<color>` | Sets the base divider token used by table borders; change it to retheme row separation while leaving border style and width intact. |
| `--table-font-weight-body-bold` | `<number>` | Sets responsive cell-label emphasis; change it when stacked table headings need a different weight. |
| `--table-header-background` | `<color>` | Sets header cell background; change it when column headings should sit on a different surface from body cells. |
| `--table-header-column-gap` | `<length>` | Sets spacing between header label content and inline header controls such as sort icons; change it to tighten or loosen heading controls. |
| `--table-header-icon-fill` | `<number>` | Sets the sort indicator fill axis; change it to switch sortable-header icons between outlined and filled glyphs. |
| `--table-header-icon-font-family` | `Any` | Sets the font family for generated sort indicators; change it only when sortable headers use a different icon font. |
| `--table-header-icon-grad` | `<number>` | Sets the sort indicator grade axis; change it to subtly thicken or lighten sortable-header icons. |
| `--table-header-icon-opsz` | `<number>` | Sets the sort indicator optical size axis; change it when sortable-header icons need different optical tuning. |
| `--table-header-icon-size` | `<length>` | Sets the rendered sort indicator size; change it when sortable-header icons should scale independently from other icons. |
| `--table-header-icon-wght` | `<number>` | Sets the sort indicator weight axis; change it when sortable-header icons need heavier or lighter strokes. |
| `--table-header-text-color` | `<color>` | Sets header cell text color; change it when column headings need stronger or subtler emphasis. |
| `--table-row-min-height` | `<length>` | Sets the minimum row height for comfortable and compact density; change it to adjust row target size and vertical rhythm. |

## Depends On

- `--color-accent-subtle`
- `--color-border-subtle`
- `--color-text`
- `--color-text-subtle`
- `--font-weight-body-bold`
- `--icon-fill`
- `--icon-font-family`
- `--icon-grad`
- `--icon-opsz`
- `--icon-size`
- `--icon-wght`
- `--layout-control-border-width`
- `--layout-control-gap`

---

<!-- Source: src/css/textarea.md -->

# Textarea

## Overview

The textarea component is a multi-line text control for longer freeform responses such as notes, comments, and descriptions.

The component pattern uses a native `<label>` that wraps a native `<textarea>`, so the control can be styled without requiring a classed wrapper.

## Usage

```html
<label>
  <span data-role="label">Notes</span>
  <textarea
    rows="4"
    required
    minlength="20"
    maxlength="280"
    placeholder="Add details"
    aria-describedby="notes-feedback"
  ></textarea>
  <span id="notes-feedback" data-role="feedback">
    <span id="notes-error" data-role="message" data-invalid="Enter at least 20 characters."></span>
    <span id="notes-limit" data-role="limit">280 character max</span>
  </span>
</label>
```

Use this component when the user needs to enter content that can span multiple lines.

Use an input instead when the expected response is short and single-line.

The label should remain visible above the field, and the placeholder should act as an example rather than replacing the label.

The field should use native `<label>` and `<textarea>` elements so the control keeps browser form behavior, keyboard support, and expected text editing behavior.

Wrap the visible label text in a `[data-role="label"]` element so required fields can render the red asterisk immediately after the label text.

When a character limit is shown, place a `[data-role="feedback"]` element directly after the textarea. Use `[data-role="message"]` for validation text and `[data-role="limit"]` for a static character-limit hint. Pair those with native constraints such as `required`, `minlength`, or `maxlength`, and associate the textarea with that supporting text using `aria-describedby`.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- TXA-001: The field uses shared control padding, border, and typography tokens, with a textarea radius that defaults to half the shared control radius.
- TXA-002: Placeholder text stays muted while entered text uses the default foreground color.
- TXA-003: Focus must remain clearly visible for keyboard users.
- TXA-004: The field allows vertical resizing so users can expand the control for longer responses.
- TXA-005: Comfortable and compact density should come from the layout theme tokens rather than textarea-specific theme branches.
- TXA-006: Validation feedback should appear only after user interaction by using `:user-invalid` rather than showing errors on initial page load.
- TXA-007: Character limits should be expressed as static supporting text unless JavaScript is intentionally introduced for a live count.
## Accessibility

- Use a native `<label>` so the field stays explicitly named.
- If the label does not wrap the textarea, associate them with matching `for` and `id` attributes.
- Do not rely on placeholder text as the only field description.
- Keep focus indication and text contrast strong enough to remain visible in normal use.
- When showing a counter or error text, keep that supporting text in the DOM and associate it with the textarea through `aria-describedby`.
- Preserve native textarea behavior rather than replacing it with a scripted text surface unless the behavior truly requires it.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--textarea-border-color` | `<color>` | Sets the textarea border color, including error overrides; change it when multiline fields need neutral or validation-state emphasis. |
| `--textarea-border-radius` | `<length>` | Sets textarea corner radius; change it when multiline fields should be sharper or softer than single-line inputs. |
| `--textarea-color-error-strong` | `<color>` | Sets --textarea-color-error-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-color-focus-ring` | `<color>` | Sets --textarea-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-color-primary` | `<color>` | Sets --textarea-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-color-text` | `<color>` | Sets --textarea-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-color-text-accent` | `<color>` | Sets --textarea-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-color-text-subtle` | `<color>` | Sets --textarea-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-control-border-width` | `<length>` | Sets --textarea-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-control-gap` | `<length>` | Sets --textarea-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-control-padding-block` | `<length>` | Sets --textarea-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-control-padding-inline` | `<length>` | Sets --textarea-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-focus-ring-size` | `<length>` | Sets --textarea-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-font-size` | `<length>` | Sets --textarea-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-font-size-caption` | `<length>` | Sets --textarea-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-line-height` | `<number>` | Sets --textarea-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--textarea-message-color` | `<color>` | Sets helper and validation message text color for textareas; change it when field messaging should move between subtle and error emphasis. |
| `--textarea-space-inline` | `<length>` | Sets --textarea-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-border-subtle`
- `--color-error-strong`
- `--color-focus-ring`
- `--color-primary`
- `--color-text`
- `--color-text-accent`
- `--color-text-subtle`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-control-radius`
- `--layout-focus-ring-size`
- `--layout-space-inline`

---

<!-- Source: src/css/tooltip.md -->

# Tooltip

## Overview

The tooltip component displays a short supplemental message when an element is hovered or focused.

Add `data-tooltip` and `aria-description` to the element that owns the message. `data-tooltip` supplies the CSS-generated visual content, while `aria-description` makes the same message available as an accessible description. Their values must be identical. The component does not require additional tooltip markup.

Use tooltips for concise, nonessential clarification. Put required instructions, validation messages, errors, and other information needed to complete a task directly in the interface.

## Usage

Attach the tooltip to a naturally focusable element whenever possible. This gives pointer and keyboard users access to the same visual message.

```html
<button
  type="button"
  data-tooltip="Save your changes"
  aria-description="Save your changes"
>
  Save
</button>
```

Keep tooltip text short. Longer messages wrap when they reach the component's maximum width.

## Placement

Tooltips appear above their element by default. Set `data-placement` to `bottom`, `left`, or `right` to choose another side.

```html
<button data-tooltip="Shown above" aria-description="Shown above">Top</button>
<button data-tooltip="Shown below" aria-description="Shown below" data-placement="bottom">Bottom</button>
<button data-tooltip="Shown to the left" aria-description="Shown to the left" data-placement="left">Left</button>
<button data-tooltip="Shown to the right" aria-description="Shown to the right" data-placement="right">Right</button>
```

Placement is explicit. The component does not detect viewport edges or automatically switch sides.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js).

- TTP-001: `data-tooltip` supplies the displayed text.
- TTP-002: `aria-description` supplies the accessible description and must contain the same text as `data-tooltip`.
- TTP-003: Hovering the owning element reveals the tooltip.
- TTP-004: Focusing the owning element reveals the tooltip.
- TTP-005: Removing both hover and focus hides the tooltip.
- TTP-006: Tooltip opacity transitions over `0.15s` when its visibility state changes.
- TTP-007: Messages use their natural width up to `20rem` or the available viewport width, whichever is smaller.
- TTP-008: Long messages and unbroken strings wrap within that maximum width.
- TTP-009: The `::before` pseudo-element renders the message box.
- TTP-010: The `::after` pseudo-element renders the pointer.
- TTP-011: `data-placement` changes the position of both pseudo-elements.
- TTP-012: Tooltip content cannot contain links, controls, formatting, or other HTML.
## Accessibility

This component is a supplemental visual enhancement, not an implementation of the unfinished WAI-ARIA tooltip interaction pattern.

- Pair `data-tooltip` with an identical `aria-description` so the message is available as an accessible description instead of relying on CSS-generated content alone.
- Ensure the owning element is keyboard-focusable. Prefer native interactive elements over adding `tabindex` to static elements.
- Preserve a visible focus indicator on the owning element.
- Do not add `role="tooltip"` to the owning element. That role is intended for a separate tooltip container, which this component does not create.
- Do not use `aria-label` for supplemental tooltip text. It replaces the element's accessible name instead of providing an accessible description.
- Do not add `aria-haspopup` or `aria-expanded`; this component does not expose a popup control or expanded state.
- Do not place interactive or essential content in a tooltip.
- Do not use a tooltip as the accessible name of an icon-only control unless the control also provides that name programmatically.

Because the generated tooltip uses `pointer-events: none`, users cannot move the pointer onto it. It also has no independent Escape dismissal behavior. Consequently, this component does not by itself satisfy every requirement of [WCAG 2.2 Success Criterion 1.4.13: Content on Hover or Focus](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html) when the tooltip obscures other content.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--tooltip-background` | `<color>` | Sets tooltip bubble background for default and inverted themes; change it when tooltip surfaces need different contrast from the page. |
| `--tooltip-border-color` | `<color>` | Sets tooltip border color; change it when the bubble needs clearer separation from nearby content or inverted surfaces. |
| `--tooltip-border-radius` | `<length>` | Sets tooltip bubble corner radius; change it to align tooltip shape with the rest of the surface system. |
| `--tooltip-border-width` | `<length>` | Sets the tooltip surface border width; change it when the tooltip bubble needs a stronger or subtler edge. |
| `--tooltip-color` | `<color>` | Sets tooltip text color; change it when the tooltip background requires a different accessible foreground. |
| `--tooltip-font-family-sans` | `Any` | Sets --tooltip-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--tooltip-font-size-caption` | `<length>` | Sets --tooltip-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--tooltip-line-height` | `<number>` | Sets --tooltip-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--tooltip-margin` | `<length>` | Sets the gap between the trigger and tooltip for all placements; change it when tooltips should sit closer to or farther from the anchor. |
| `--tooltip-max-size` | `<length>` | Sets the maximum tooltip width while respecting viewport gutters; change it when tooltip copy needs narrower or wider wrapping. |
| `--tooltip-padding` | `<length>` | Sets the internal tooltip padding; change it when tooltip content should feel denser or more spacious. |
| `--tooltip-shadow` | `Any` | Sets the tooltip elevation shadow; change it to tune how strongly the bubble floats above content. |

## Depends On

- `--color-accent-subtle`
- `--color-border-subtle-inverse`
- `--color-primary-strong`
- `--color-text`
- `--color-text-inverse`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size-caption`
- `--layout-control-radius`
- `--layout-shadow`
- `--layout-space-inline`
- `--layout-space-stack`
- `--layout-surface-border-width`

---

<!-- Source: src/css/typography.md -->

# Typography Tokens

## Overview

The system uses IBM Plex Sans as the default web font for interface text, headings, and body copy.

Typography tokens are defined in [typography.css](/Users/stuft2/Projects/design-system/src/css/typography.css).

IBM Plex Sans is a variable font, so these tokens can use weight values between `100` and `700`.

## Usage

Use the shared typography tokens directly when a component needs text styling that should stay aligned with the system:

- Use `--font-family-sans` for default UI text and controls.
- Use `--font-size` and `--font-line-height-body` for standard control text.
- Use `--font-size-caption` for helper text, native captions, caption-like metadata, and compact supporting copy.
- Use `--font-size-title` for compact page or component titles that should not use the full page-heading scale.
- Use the heading size tokens for semantic heading levels instead of hardcoding absolute sizes.
- Use `--font-line-height-heading` for semantic heading levels instead of hardcoding heading line-height values.
- Use the body weight tokens for inline emphasis and prose-level text roles.
- Use the heading weight tokens for semantic heading levels instead of hardcoding numeric weights.

For exact shared typography values, use [typography.css](/Users/stuft2/Projects/design-system/src/css/typography.css) as the source of truth.

## Authoring Rules

- Use shared typography tokens before creating component-level font, weight, or line-height values.
- Keep the default UI font family centralized so components and documentation examples inherit the same base text treatment.
- Use the shared default link treatment so links use the subtle text accent color in light mode, keep the text accent color in dark mode, remove underline by default, and show the strong text accent underline hover state unless a component intentionally overrides it.
- Use the shared body emphasis tokens so inline `em`, `i`, `b`, and `strong` elements render with the documented IBM Plex Sans body weights.
- Let global text elements such as `body`, `p`, `small`, `blockquote`, `caption`, and `figcaption` inherit their default typography from this layer unless a component has a stronger semantic reason to override them.
- Balance blockquote wrapping so centered quotations distribute text more evenly across lines.
- Treat direct child paragraphs in direct child `main` headers as caption text and size them from `--font-size-caption`.
- Uppercase `h1` text so top-level page headings keep the intended title presentation from authored lowercase text.
- Prefer semantic size tokens for headings, titles, captions, and supporting text instead of scattering raw `rem` values through components.
- Derive typography size tokens from `--font-size` so theme authors configure one size source.
- Prefer semantic weight tokens for documented text roles instead of scattering raw numeric font weights through components.
- Derive body and heading weight tokens from `--font-weight-base` so theme authors configure one weight source.
- Do not create a token for a text style unless it reflects a reusable design decision.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--font-family-sans` | `Any` | Default sans-serif font family for application UI, form controls, headings, and body copy. Use for: default UI text and content that should inherit the IBM Plex Sans system font Avoid for: icon fonts or display typography that needs a distinct semantic decision |
| `--font-line-height-body` | `<number>` | Default unitless line-height multiplier for standard body text and interactive controls. Use for: readable body text, control text, and line-height values that should scale with local font size Avoid for: dense data text that needs a separate semantic type token |
| `--font-line-height-heading` | `<number>` | Heading line height for semantic heading levels. Use for: `h1` through `h6` and equivalent heading treatments Avoid for: body copy, control text, captions, and supporting text that should use `--font-line-height-body` |
| `--font-size` | `<length-percentage>` | Default font size for standard interactive controls. Use for: `input`, `select`, `textarea`, and button text when they share the default control type scale Avoid for: headings or component-specific display typography |
| `--font-size-caption` | `<length>` | Caption text size for native `caption`, `figcaption`, and caption-like metadata. Derived from: `--font-size` Use for: table captions, figure captions, helper text, range limits, eyebrow metadata, compact supporting labels, and `small` Avoid for: larger header caption text, which should calculate from this token |
| `--font-size-heading-1` | `<length>` | Heading 1 size. Derived from: `--font-size` Use for: `h1` and equivalent top-level page headings Avoid for: component titles or lower-level section headings |
| `--font-size-heading-2` | `<length>` | Heading 2 size. Derived from: `--font-size` Use for: `h2` and equivalent second-level headings Avoid for: top-level page titles or lower-level section headings |
| `--font-size-heading-3` | `<length>` | Heading 3 size. Derived from: `--font-size` Use for: `h3` and equivalent third-level headings Avoid for: body text or compact labels |
| `--font-size-heading-4` | `<length>` | Heading 4 size. Derived from: `--font-size` Use for: `h4` and equivalent fourth-level headings Avoid for: non-heading uppercase labels |
| `--font-size-heading-5` | `<length>` | Heading 5 size. Derived from: `--font-size` Use for: `h5` and equivalent fifth-level headings Avoid for: replacing body text emphasis |
| `--font-size-heading-6` | `<length>` | Heading 6 size. Derived from: `--font-size` Use for: `h6` and equivalent sixth-level headings Avoid for: standard body copy |
| `--font-size-title` | `<length>` | Compact title size for branded headers and other title treatments that sit below the full page-heading scale. Derived from: `--font-size` Use for: application or site titles inside component chrome Avoid for: semantic page headings that should use the heading size tokens |
| `--font-weight-base` | `<number>` | Authored base text weight for IBM Plex Sans. Use for: the single configurable weight source that body and heading weights derive from Avoid for: direct component styling when a semantic body or heading weight token exists |
| `--font-weight-body-bold` | `<number>` | Bold body text weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: inline strong emphasis within body copy Avoid for: heading levels that have their own weight tokens |
| `--font-weight-body-italic` | `<number>` | Body italic weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: italicized body text when the content should retain the standard body weight Avoid for: relying on weight alone to communicate emphasis without italic styling |
| `--font-weight-body-regular` | `<number>` | Default body text weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: standard body copy and default paragraph text Avoid for: emphasized headings or strong action labels |
| `--font-weight-heading-1` | `<number>` | Heading 1 weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: `h1` and equivalent top-level page headings Avoid for: lower heading levels or emphasized body text |
| `--font-weight-heading-2` | `<number>` | Heading 2 weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: `h2` and equivalent second-level headings Avoid for: body text or smaller heading levels |
| `--font-weight-heading-3` | `<number>` | Heading 3 weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: `h3` and equivalent third-level headings Avoid for: body text or lower-emphasis labels |
| `--font-weight-heading-4` | `<number>` | Heading 4 weight for IBM Plex Sans. Derived from: `--font-weight-body-bold` Use for: `h4` and equivalent fourth-level headings Avoid for: replacing semantic body emphasis styles |
| `--font-weight-heading-5` | `<number>` | Heading 5 weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: `h5` and equivalent fifth-level headings Avoid for: stronger heading levels that require more emphasis |
| `--font-weight-heading-6` | `<number>` | Heading 6 weight for IBM Plex Sans. Derived from: `--font-weight-base` Use for: `h6` and equivalent sixth-level headings Avoid for: standard body copy when the regular body token should be used instead |

---

<!-- Source: src/js/card.md -->

# Dismissible alert cards

`card.js` makes opted-in notification cards dismissible without generating DOM elements. CSS generates the close control when an `<article data-variant>` has `data-closable="true"`. Activating the generated control removes the article from the document.

## Usage

Load the script with `defer` and opt the alert into dismissal:

```html
<article data-variant="error" data-closable="true">Uploaded file could not be processed.</article>

<script src="card.js" defer></script>
```

The `close` glyph and its control region are generated by the article's `::after` pseudo-element in `card.css`. JavaScript makes the article keyboard focusable and adds an accessible dismissal description without adding child elements. Clicking the generated control region or pressing Enter or Space while the alert is focused removes it.

Cards inserted after the script runs, including cards added through HTMX swaps, are prepared automatically through a document-level mutation observer.

Only an `<article data-variant data-closable="true">` is dismissible. Alerts without the true value, other cards, and elements that merely use `data-variant` are not affected.