Documentation
Architecture

Design axes

Spacing, radius, typography, elevation and motion: five independent data attributes that reshape every component in a subtree, with no variant.

Five design axes change how the whole library looks: spacing, radius, typography, elevation and motion. Each axis is a data-* attribute that you set on any element. Its descendants inherit the level you choose, the same way they inherit a palette.

<html data-density="compact" data-radius="flat" data-elevation="flat">

An axis only changes tokens. No component has a variant, a prop or a class for it: a button, a field or a dialog reads the same tokens at every level.

axisattributelevels
Spacingdata-densitycompact, snug, default, comfortable, spacious
Radiusdata-radiusflat, subtle, default, rounded, full
Typographydata-textsmall, default, large
Elevationdata-elevationflat, subtle, default, raised
Motiondata-motionnone, fast, default, expressive

The default level of an axis is the absence of its attribute. To return a subtree to the default, remove the attribute; there is no "default" value.

Independent and nested

The axes are independent. A dense, square, flat dashboard and a spacious, rounded settings page are two combinations of the same components. The axes also nest: a compact toolbar can sit inside a spacious page, and the toolbar follows its own level.

<main data-density="spacious" data-radius="rounded">
    <nav data-density="compact">…</nav>
</main>

Spacing

Spacing sets --spacing, the unit of Tailwind's numeric scale. Every p-*, gap-*, m-* and numeric size follows it, and so does the control height (h-control, nine steps of --spacing).

level--spacing
compact0.2rem
snug0.225rem
default0.25rem
comfortable0.275rem
spacious0.3rem

Radius

Radius sets the corner tokens. Each corner in the library uses the member that matches its role:

  • rounded-sm, rounded-md and rounded-lg are the scale: small marks (checkbox), items and blocks, and containers (popup, dialog).
  • rounded-control is a standalone control: a button, a field or a navigation trigger.
  • rounded-pill is a shape that is a pill by style: a badge, a switch or the drawer handle.
  • rounded-full is an intrinsic circle, such as an avatar, a radio, a slider thumb or a track. It never changes.
levelsmmdlgcontrolpill
flat00000
subtle2px4px8px4px4px
default4px8px16px8pxpill
rounded6px12px20px12pxpill
full8px16px24pxpillpill

At full, buttons become pills and containers stay capped at 24px. A field is capped at half the control height, so a one-line field is a pill, and a textarea keeps round corners instead of turning into a stadium.

Typography

Typography scales every text-* size by --text-scale. Line heights keep Tailwind's ratios, so they follow the size.

level--text-scaletext-sm
small0.87512.25px
default114px
large1.12515.75px

Icons follow the text, not the spacing. An icon sits beside a label, so it keeps its proportion to the label. The icon sizes (size-icon-xs, size-icon-sm, size-icon, size-icon-lg) scale with data-text, and data-density leaves them alone. An explicit size-* on an icon still overrides the default of its context.

Elevation

Elevation sets the shadows. At flat there are no shadows, and every layer (popup, dialog, tabset) is told apart by its border. subtle moves each shadow one step down Tailwind's scale, and raised moves it one step up.

Motion

Motion multiplies every duration: transitions, the enter and exit animations of popups, dialogs and drawers, the skeleton pulse and the progress bar.

levelmultiplier
none0, so everything is instant
fast0.5
default1
expressive1.5

Reduced motion always wins. When the user's system asks for reduced motion, the level is none, whatever data-motion says.

Popups and portals

Popups, dialogs and drawers render in a portal under <body>, outside the subtree that opened them. An axis set on a subtree does not reach them. To make the whole interface follow an axis, set it on <html>.

Switching

There is no built-in control for the axes. To try a level, set the attribute on <html> from your browser's devtools. To let people choose, wire your own control that sets the attribute and persists the choice, the way next-themes does for data-theme.

Compared with shadcn/ui

shadcn/ui offers several styles, each a stylesheet that redefines every component's classes. A style bundles spacing, radius, type and focus together, and you choose it when you install. In Fragiola the five axes are separate, change at runtime and apply per subtree, and each component is written once.