Design tokens

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, never declared

Defaults

45 components take a default variant or size

Decision

ADR-020; 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

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 serves the themes those tokens sit on. A design-system document that sets all of this from one JSON file is planned.

Hooks

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>

More on tokens, hooks and defaults together: the design-system guide.

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.

Size (10)

Control heights, icon sizes and interactive targets.

Type roles (35)

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

Elevation (8)

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

Shape (9)

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

Layers (8)

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

Opacity (3)

Disabled, muted and scrim opacities.

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.

Icons (2)

Icon stroke and style.

Status (20)

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

Data-viz (36)

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

Next: every component token and its fallback.