# Design tokens

> The Texuli token contract v2: 159 system tokens in 11 families with their defaults, 365 component tokens and the scope model, generated from the registries.

Language: en
Canonical: https://texuli.com/tokens/
Markdown: https://texuli.com/tokens.md (this page). Every texuli.com page has a Markdown twin at its URL plus `.md` (the home page is https://texuli.com/index.md), and any page URL answers `Accept: text/markdown` with its twin instead of HTML.
Last Updated: 2026-11-13

---

Every size, space, radius, shadow, layer and type role a Texuli component paints is a `--tx-*` custom property. Set them on a scope and the components follow, with no CSS of your own.

System tokens

159 in 11 families: 123 declared once in `@texuli/tokens/base.css`, 36 data-viz tokens emitted per theme

Component tokens

[365 for 57 components](https://texuli.com/tokens/components/), never declared

Defaults

45 components take a default variant or size

Decision

[ADR-020](https://github.com/DailybotHQ/texuli/blob/main/docs/DECISIONS.md#adr-020-token-contract-v2-additive-families-and-a-real-component-tier); additive: nothing existing is renamed

## The scope model

- **A token scope** is any element matching `:where(:root, [data-tx-theme], [data-tx-scope])`: the document root, an element with a theme, or an element marked `data-tx-scope`. `base.css` declares every system default on each scope, inside `@layer tx.base` with zero specificity, so derived values (space steps, radius steps, type roles) resolve against the nearest theme and its density.
- **One fallback level.** A system token is read plain (`var(--tx-space-4)`). A component token carries exactly one fallback, its registry default: `var(--tx-button-radius, var(--tx-shape-radius-lg))`.
- **Component tokens are undeclared** until a theme, design system or host sets one on its scope, so they cost no bytes on a page that does not use them.
- **Set tokens on a scope, never globally,** so two design systems can share a page.

```
[data-tx-scope="acme"] {
  --tx-button-radius: 9999px;
  --tx-card-padding-inline: 1.5rem;
  --tx-dialog-z-index: 80;
}
```

## How design systems and agents drive them

| Channel | Reaches | Set with |
| --- | --- | --- |
| Component tokens | Sizes, spaces, radii, borders, shadows, layers and type of each component | Custom properties on a scope (`--tx-button-radius`) |
| System tokens | Every component at once: the space scale, control sizes, radii, elevation, type roles | Custom properties on a scope (`--tx-space-unit`, `--tx-shape-radius-lg`) |
| Hooks | A closed look per component (pill buttons, glass cards) | `data-tx-*-style` attributes on any ancestor |
| Defaults | The default `variant` and `size` props | `setDesignDefaults` from `texuli/defaults` |

Agents work from the same closed vocabulary. `getComponentTokensJsonSchema()` from `@texuli/tokens/components` is a JSON Schema of every component and key, so a token set an agent writes can be validated before it reaches a page, and `validateDesignDefaults` drops and reports any default outside the vocabulary. The [Texuli MCP](https://texuli.com/mcp-server/) serves the themes those tokens sit on. A design-system document that sets all of this from one JSON file is planned.

### Hooks

| Attribute | Values | Sets |
| --- | --- | --- |
| `data-tx-button-style` | square, default, pill | `--tx-button-radius` |
| `data-tx-card-style` | solid, bordered, glass | `--tx-card-elevation and --tx-card-background` |
| `data-tx-input-style` | compact, default, comfortable | `--tx-input-height and --tx-input-padding-inline` |
| `data-tx-focus-ring-style` | ring, outline, glow, inset | `--tx-focus-ring-offset on the focused element` |

## setDesignDefaults

CSS cannot choose a default variant or size, so `texuli/defaults` carries them in a Svelte context. A component uses its design default only when its own prop is undefined; nested providers merge, the inner one winning per component and prop. Pass a function to keep the defaults reactive.

```
<script lang="ts">
  import { setDesignDefaults } from 'texuli/defaults';

  setDesignDefaults({ button: { variant: 'outline', size: 'sm' }, card: { variant: 'flat' } });
</script>
```

The defaults vocabulary

| Component | variant | size |
| --- | --- | --- |
| `accordion` | default, bordered | — |
| `avatar` | — | xs, sm, md, lg |
| `badge` | default, secondary, outline, success, warning, destructive, info, neutral | — |
| `breadcrumb` | — | sm, md, lg |
| `button` | default, secondary, outline, ghost, destructive, link | sm, md, lg, icon |
| `card` | elevated, flat | — |
| `chip` | default, secondary, outline, success, warning, destructive, info, neutral | — |
| `choice` | — | sm, md |
| `code` | inline, block | — |
| `combobox` | outline, soft | sm, md, lg |
| `command` | outline, soft | sm, md, lg |
| `copy-button` | — | sm, md |
| `date` | — | sm, md |
| `dialog` | — | sm, md, lg, xl |
| `empty` | — | sm, md |
| `file-upload` | default, compact | — |
| `icon` | — | xs, sm, md, lg |
| `icon-button` | default, secondary, outline, ghost, destructive, link | sm, md, lg, icon |
| `label` | — | sm, md |
| `menu` | default, soft | sm, md, lg |
| `navigation` | — | sm, md, lg |
| `number-field` | — | sm, md, lg |
| `pagination` | outline, soft | sm, md, lg |
| `pin-input` | — | sm, md, lg |
| `popover` | elevated, flat | sm, md, lg |
| `progress` | — | sm, md, lg |
| `radio-group` | default, card | sm, md |
| `rating` | — | sm, md, lg |
| `resizable` | plain, bordered | — |
| `resizable-handle` | — | sm, md |
| `scroll-area` | — | sm, md, lg |
| `select` | outline, soft | sm, md, lg |
| `separator` | default, subtle, strong | — |
| `sheet` | — | sm, md, lg, xl |
| `sidebar` | default, inset | — |
| `skeleton` | — | sm, md, lg |
| `slider` | — | sm, md, lg |
| `spinner` | — | sm, md, lg |
| `stat` | elevated, flat | — |
| `tabs` | line, pills, enclosed | — |
| `tag` | default, secondary, outline, success, warning, destructive, info, neutral | — |
| `toggle` | default, outline | sm, md, lg |
| `toggle-group` | default, outline | sm, md, lg |
| `toolbar` | default, outline, ghost | sm, md |
| `tree` | default, bordered | — |

More on tokens, hooks and defaults together: [the design-system guide](https://github.com/DailybotHQ/texuli/blob/main/packages/texuli/docs/design-system.md).

## System families

Each family with its tokens and the default `base.css` declares. Data-viz is the exception: each theme emits it, and the column names the theme source.

### Space (14)

The 0.25rem spacing scale, scaled by --tx-density.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-space-unit | calc(0.25rem * var(--tx-density, 1)) | The 0.25rem step, scaled by the theme density. |
| --tx-space-0 | 0px | No space. |
| --tx-space-1 | calc(var(--tx-space-unit) * 1) | 0.25rem at density 1. |
| --tx-space-2 | calc(var(--tx-space-unit) * 2) | 0.5rem at density 1. |
| --tx-space-3 | calc(var(--tx-space-unit) * 3) | 0.75rem at density 1. |
| --tx-space-4 | calc(var(--tx-space-unit) * 4) | 1rem at density 1. |
| --tx-space-5 | calc(var(--tx-space-unit) * 5) | 1.25rem at density 1. |
| --tx-space-6 | calc(var(--tx-space-unit) * 6) | 1.5rem at density 1. |
| --tx-space-7 | calc(var(--tx-space-unit) * 7) | 1.75rem at density 1. |
| --tx-space-8 | calc(var(--tx-space-unit) * 8) | 2rem at density 1. |
| --tx-space-9 | calc(var(--tx-space-unit) * 9) | 2.25rem at density 1. |
| --tx-space-10 | calc(var(--tx-space-unit) * 10) | 2.5rem at density 1. |
| --tx-space-11 | calc(var(--tx-space-unit) * 11) | 2.75rem at density 1. |
| --tx-space-12 | calc(var(--tx-space-unit) * 12) | 3rem at density 1. |

### Size (10)

Control heights, icon sizes and interactive targets.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-size-control-xs | 1.75rem | Compact control height (toolbar small buttons). |
| --tx-size-control-sm | 2rem | Small control height (button, select, toggle sm). |
| --tx-size-control-md | 2.25rem | Default control height (button, input, select md). |
| --tx-size-control-lg | 2.75rem | Large control height (button, select, toggle lg). |
| --tx-size-icon-xs | 0.75rem | Extra small icon (12 px, Icon size xs). |
| --tx-size-icon-sm | 1rem | Small icon (16 px, Icon size sm, icons inside buttons). |
| --tx-size-icon-md | 1.25rem | Default icon (20 px, Icon size md, alert and toast icons). |
| --tx-size-icon-lg | 1.5rem | Large icon (24 px, Icon size lg). |
| --tx-size-target-min | 24px | The smallest interactive target anywhere (WCAG 2.2). |
| --tx-size-target-touch | max(2.75rem, 44px) | The interactive target below 640 px (button sm, md and icon on small screens). |

### Type roles (35)

Family, size, line height, weight and tracking per role, mapped from the theme type scale.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-type-display-family | var(--tx-font-heading, var(--tx-font-sans, system-ui, sans-serif)) | Hero and display text. Font family. |
| --tx-type-display-size | var(--tx-font-size-4xl, 2.25rem) | Hero and display text. Font size. |
| --tx-type-display-line | 1.1 | Hero and display text. Line height. |
| --tx-type-display-weight | var(--tx-font-weight-bold, 700) | Hero and display text. Font weight. |
| --tx-type-display-tracking | var(--tx-letter-spacing-heading, 0) | Hero and display text. Letter spacing. |
| --tx-type-title-family | var(--tx-font-heading, var(--tx-font-sans, system-ui, sans-serif)) | Page titles and KPI values. Font family. |
| --tx-type-title-size | var(--tx-font-size-2xl, 1.5rem) | Page titles and KPI values. Font size. |
| --tx-type-title-line | 1.2 | Page titles and KPI values. Line height. |
| --tx-type-title-weight | var(--tx-font-weight-heading, 600) | Page titles and KPI values. Font weight. |
| --tx-type-title-tracking | var(--tx-letter-spacing-heading, 0) | Page titles and KPI values. Letter spacing. |
| --tx-type-heading-family | var(--tx-font-heading, var(--tx-font-sans, system-ui, sans-serif)) | Dialog, sheet and section headings. Font family. |
| --tx-type-heading-size | var(--tx-font-size-lg, 1.125rem) | Dialog, sheet and section headings. Font size. |
| --tx-type-heading-line | 1.3 | Dialog, sheet and section headings. Line height. |
| --tx-type-heading-weight | var(--tx-font-weight-heading, 600) | Dialog, sheet and section headings. Font weight. |
| --tx-type-heading-tracking | var(--tx-letter-spacing-heading, 0) | Dialog, sheet and section headings. Letter spacing. |
| --tx-type-body-family | var(--tx-font-sans, system-ui, sans-serif) | Running text. Font family. |
| --tx-type-body-size | var(--tx-font-size-base, 1rem) | Running text. Font size. |
| --tx-type-body-line | 1.5 | Running text. Line height. |
| --tx-type-body-weight | var(--tx-font-weight-body, 400) | Running text. Font weight. |
| --tx-type-body-tracking | var(--tx-letter-spacing-body, 0) | Running text. Letter spacing. |
| --tx-type-label-family | var(--tx-font-sans, system-ui, sans-serif) | Control labels and button text. Font family. |
| --tx-type-label-size | var(--tx-font-size-sm, 0.875rem) | Control labels and button text. Font size. |
| --tx-type-label-line | 1.25 | Control labels and button text. Line height. |
| --tx-type-label-weight | var(--tx-font-weight-medium, 500) | Control labels and button text. Font weight. |
| --tx-type-label-tracking | var(--tx-letter-spacing-body, 0) | Control labels and button text. Letter spacing. |
| --tx-type-caption-family | var(--tx-font-sans, system-ui, sans-serif) | Descriptions, hints and captions. Font family. |
| --tx-type-caption-size | var(--tx-font-size-xs, 0.75rem) | Descriptions, hints and captions. Font size. |
| --tx-type-caption-line | 1.35 | Descriptions, hints and captions. Line height. |
| --tx-type-caption-weight | var(--tx-font-weight-body, 400) | Descriptions, hints and captions. Font weight. |
| --tx-type-caption-tracking | var(--tx-letter-spacing-body, 0) | Descriptions, hints and captions. Letter spacing. |
| --tx-type-code-family | var(--tx-font-mono, ui-monospace, monospace) | Inline and block code. Font family. |
| --tx-type-code-size | 0.875em | Inline and block code. Font size. |
| --tx-type-code-line | 1.5 | Inline and block code. Line height. |
| --tx-type-code-weight | var(--tx-font-weight-body, 400) | Inline and block code. Font weight. |
| --tx-type-code-tracking | 0 | Inline and block code. Letter spacing. |

### Elevation (8)

A six-step shadow ladder over the theme soft and float shadows, plus glass.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-elevation-0 | none | Flush with the surface. |
| --tx-elevation-1 | var(--tx-shadow-soft, none) | Resting surfaces: cards, inputs, stats. |
| --tx-elevation-2 | var(--tx-shadow-soft, none) | Raised controls: slider thumbs, active tabs. |
| --tx-elevation-3 | var(--tx-shadow-float, none) | Floating layers: menus, popovers, tooltips. |
| --tx-elevation-4 | var(--tx-shadow-float, none) | Modal layers: dialogs and sheets. |
| --tx-elevation-5 | var(--tx-shadow-float, none) | Notifications: toasts. |
| --tx-surface-glass-alpha | var(--tx-glass-opacity, 82%) | Glass surface fill opacity. |
| --tx-surface-glass-blur | var(--tx-glass-blur, 16px) | Glass surface backdrop blur. |

### Shape (9)

The radius scale derived from --tx-radius and the radius scale, and border widths.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-shape-radius-none | 0px | Square corners. |
| --tx-shape-radius-xs | max(0px, var(--tx-radius, 0.625rem) - var(--tx-radius-step-6, 6px)) | The theme radius minus 6 px times the radius scale. |
| --tx-shape-radius-sm | max(0px, var(--tx-radius, 0.625rem) - var(--tx-radius-step-4, 4px)) | The theme radius minus 4 px times the radius scale. |
| --tx-shape-radius-md | max(0px, var(--tx-radius, 0.625rem) - var(--tx-radius-step-2, 2px)) | The theme radius minus 2 px times the radius scale. |
| --tx-shape-radius-lg | var(--tx-radius, 0.625rem) | The theme radius. |
| --tx-shape-radius-xl | calc(var(--tx-radius, 0.625rem) + var(--tx-radius-step-4, 4px)) | The theme radius plus 4 px times the radius scale. |
| --tx-shape-radius-full | 9999px | Pill and circle corners. |
| --tx-border-width-thin | var(--tx-border-width, 1px) | Hairline borders. |
| --tx-border-width-thick | calc(var(--tx-border-width, 1px) * 2) | Emphasis borders (drop zones, slider thumbs). |

### Layers (8)

Stacking order for sticky chrome, popovers, overlays, dialogs and toasts.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-z-base | 0 | In-flow content. |
| --tx-z-sticky | 40 | Sticky chrome and navigation menus. |
| --tx-z-popover | 50 | Popovers, menus, selects, comboboxes, date panels. |
| --tx-z-tooltip | 50 | Tooltips. |
| --tx-z-overlay | 60 | Sheets, drawers and their scrims. |
| --tx-z-modal | 60 | Dialogs and alert dialogs. |
| --tx-z-toast | 60 | The toast viewport. |
| --tx-z-top | 70 | Skip links and shell chrome above every layer. |

### Opacity (3)

Disabled, muted and scrim opacities.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-opacity-disabled | 0.5 | Disabled controls. |
| --tx-opacity-muted | 0.7 | Decorative icons such as select and menu chevrons. |
| --tx-opacity-scrim | 45% | Opacity of the dialog and sheet --tx-scrim. |

### Layout (14)

Content widths, container breakpoints, grid columns and gutters. CSS cannot read custom properties inside @media or @container conditions, so the breakpoints are values for tooling and design-system exports.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-layout-content-max | 72ch | Readable prose width (content layouts). Rem, ch and % layout widths do not multiply --tx-density; gutters still read the space scale. |
| --tx-layout-wide-max | 80rem | Wide page sections (marketing layouts). |
| --tx-layout-full-max | 100% | Full-bleed sections. |
| --tx-layout-breakpoint-sm | 36rem | Small container breakpoint (2 grid columns). |
| --tx-layout-breakpoint-md | 56rem | Medium container breakpoint (3 grid columns). |
| --tx-layout-breakpoint-lg | 72rem | Large container breakpoint (4 grid columns). |
| --tx-layout-grid-columns-base | 1 | Grid columns at the base breakpoint. |
| --tx-layout-grid-columns-sm | 2 | Grid columns at the sm breakpoint. |
| --tx-layout-grid-columns-md | 3 | Grid columns at the md breakpoint. |
| --tx-layout-grid-columns-lg | 4 | Grid columns at the lg breakpoint. |
| --tx-layout-grid-gutter-base | var(--tx-space-4) | Grid gutter at the base breakpoint. |
| --tx-layout-grid-gutter-sm | var(--tx-space-4) | Grid gutter at the sm breakpoint. |
| --tx-layout-grid-gutter-md | var(--tx-space-4) | Grid gutter at the md breakpoint. |
| --tx-layout-grid-gutter-lg | var(--tx-space-4) | Grid gutter at the lg breakpoint. |

### Icons (2)

Icon stroke and style.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-icon-stroke | 2 | Icon stroke width (the Icon component default). |
| --tx-icon-style | outline | Icon style: outline or filled. |

### Status (20)

One status set over the semantic roles, shared by badges, alerts, toasts and charts.

| Token | Default | Meaning |
| --- | --- | --- |
| --tx-status-success | var(--tx-success) | The success fill (badges, alerts, charts). |
| --tx-status-success-foreground | var(--tx-success-foreground) | Text on the success fill. |
| --tx-status-success-soft | var(--tx-success-soft) | The soft success fill. |
| --tx-status-success-soft-foreground | var(--tx-success-soft-foreground) | Text on the soft success fill. |
| --tx-status-warning | var(--tx-warning) | The warning fill (badges, alerts, charts). |
| --tx-status-warning-foreground | var(--tx-warning-foreground) | Text on the warning fill. |
| --tx-status-warning-soft | var(--tx-warning-soft) | The soft warning fill. |
| --tx-status-warning-soft-foreground | var(--tx-warning-soft-foreground) | Text on the soft warning fill. |
| --tx-status-danger | var(--tx-destructive) | The danger fill (badges, alerts, charts). |
| --tx-status-danger-foreground | var(--tx-destructive-foreground) | Text on the danger fill. |
| --tx-status-danger-soft | var(--tx-destructive-soft) | The soft danger fill. |
| --tx-status-danger-soft-foreground | var(--tx-destructive-soft-foreground) | Text on the soft danger fill. |
| --tx-status-info | var(--tx-info) | The info fill (badges, alerts, charts). |
| --tx-status-info-foreground | var(--tx-info-foreground) | Text on the info fill. |
| --tx-status-info-soft | var(--tx-info-soft) | The soft info fill. |
| --tx-status-info-soft-foreground | var(--tx-info-soft-foreground) | Text on the soft info fill. |
| --tx-status-neutral | var(--tx-secondary) | The neutral fill (badges, alerts, charts). |
| --tx-status-neutral-foreground | var(--tx-secondary-foreground) | Text on the neutral fill. |
| --tx-status-neutral-soft | var(--tx-muted) | The soft neutral fill. |
| --tx-status-neutral-soft-foreground | var(--tx-muted-foreground) | Text on the soft neutral fill. |

### Data-viz (36)

Chart categorical, sequential and diverging colors with grid and axis, emitted per theme.

| Token | Theme source | Meaning |
| --- | --- | --- |
| --tx-chart-1 | theme.charts.categorical | Categorical series color 1. |
| --tx-chart-1-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 1. |
| --tx-chart-2 | theme.charts.categorical | Categorical series color 2. |
| --tx-chart-2-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 2. |
| --tx-chart-3 | theme.charts.categorical | Categorical series color 3. |
| --tx-chart-3-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 3. |
| --tx-chart-4 | theme.charts.categorical | Categorical series color 4. |
| --tx-chart-4-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 4. |
| --tx-chart-5 | theme.charts.categorical | Categorical series color 5. |
| --tx-chart-5-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 5. |
| --tx-chart-6 | theme.charts.categorical | Categorical series color 6. |
| --tx-chart-6-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 6. |
| --tx-chart-7 | theme.charts.categorical | Categorical series color 7. |
| --tx-chart-7-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 7. |
| --tx-chart-8 | theme.charts.categorical | Categorical series color 8. |
| --tx-chart-8-foreground | on-color(theme.charts.categorical) | AA foreground ink on categorical series color 8. |
| --tx-chart-sequential-1 | theme.charts.sequential | Sequential ramp step 1. |
| --tx-chart-sequential-2 | theme.charts.sequential | Sequential ramp step 2. |
| --tx-chart-sequential-3 | theme.charts.sequential | Sequential ramp step 3. |
| --tx-chart-sequential-4 | theme.charts.sequential | Sequential ramp step 4. |
| --tx-chart-sequential-5 | theme.charts.sequential | Sequential ramp step 5. |
| --tx-chart-sequential-6 | theme.charts.sequential | Sequential ramp step 6. |
| --tx-chart-sequential-7 | theme.charts.sequential | Sequential ramp step 7. |
| --tx-chart-sequential-8 | theme.charts.sequential | Sequential ramp step 8. |
| --tx-chart-sequential-9 | theme.charts.sequential | Sequential ramp step 9. |
| --tx-chart-diverging-1 | theme.charts.diverging | Diverging ramp step 1. |
| --tx-chart-diverging-2 | theme.charts.diverging | Diverging ramp step 2. |
| --tx-chart-diverging-3 | theme.charts.diverging | Diverging ramp step 3. |
| --tx-chart-diverging-4 | theme.charts.diverging | Diverging ramp step 4. |
| --tx-chart-diverging-5 | theme.charts.diverging | Diverging ramp step 5. |
| --tx-chart-diverging-6 | theme.charts.diverging | Diverging ramp step 6. |
| --tx-chart-diverging-7 | theme.charts.diverging | Diverging ramp step 7. |
| --tx-chart-diverging-8 | theme.charts.diverging | Diverging ramp step 8. |
| --tx-chart-diverging-9 | theme.charts.diverging | Diverging ramp step 9. |
| --tx-chart-grid | theme.charts.grid or the border role | Chart grid lines. |
| --tx-chart-axis | theme.charts.axis or the muted foreground role | Chart axes and ticks. |

Next: [every component token and its fallback](https://texuli.com/tokens/components/).