@codenhub/styles 0.0.4 → 0.1.0

package/docs/usage/composing.md

@@ -0,0 +1,218 @@
+---
+title: Composing
+description: Combining intent, presentation, and aesthetic on a component, and the axis-support matrix.
+---
+
+# Composing the three axes
+
+See [Concepts](../concepts.md#the-three-axes) for what each axis means. This
+page covers how they combine in markup, what the presentation classes mean in
+depth, which components support which axis, and elevation.
+
+## Combining axes
+
+```html
+<div class="soft">
+  <button class="btn primary">Soft primary button</button>
+  <span class="badge success">Soft success badge</span>
+  <button class="btn primary ghost edged">Outlined; the element wins</button>
+</div>
+```
+
+A declaration on the element always beats one inherited from a container, so
+a container sets the default look for its subtree and any element opts out.
+
+Intent classes do not cascade. `.primary` and its siblings stay on the
+element that shows the intent, because a container silently recoloring every
+descendant is a trap rather than a feature — see
+[Theming → Intent tokens](./theming.md#intent-tokens). Use `.neutral` to opt
+an element back out of an inherited intent context. Presentation and
+[material tokens](./customizing.md#material-tokens) do cascade, so a
+container can set the look of its whole subtree while any element overrides
+it.
+
+## Presentation
+
+Presentation has two independent axes. `.solid`, `.soft`, and `.ghost`
+decide how much intent fills a component; `.edged` and `.edgeless` decide
+whether it draws a boundary. They set
+[presentation tokens](./customizing.md#presentation-tokens) and nothing
+else, so they work on the component itself or on any ancestor.
+
+| Class       | Look                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `.solid`    | Intent-colored fill with contrast text.                    |
+| `.soft`     | Lightly tinted fill with intent-colored text.              |
+| `.ghost`    | No fill at rest, with intent-colored text.                 |
+| `.edged`    | Intent-colored boundary at the aesthetic's material width. |
+| `.edgeless` | No boundary.                                               |
+
+Values each class ships:
+
+| Class       | `--ui-fill` | `--ui-fg-on-fill` | `--ui-border` |
+| ----------- | ----------- | ----------------- | ------------- |
+| `.solid`    | `100%`      | `100%`            |               |
+| `.soft`     | `12%`       | `0%`              |               |
+| `.ghost`    | `0%`        | `0%`              |               |
+| `.edged`    |             |                   | `100%`        |
+| `.edgeless` |             |                   | `0%`          |
+
+The combinations mean exactly what they spell:
+
+```html
+<button class="btn primary">Solid, the button default</button>
+<button class="btn soft edged">Tinted with a border</button>
+<button class="btn primary ghost edged">Outline</button>
+<button class="btn ghost">Ghost; picks up a tint on hover</button>
+<input class="ipt soft edgeless" />
+<!-- A field sunk into the page -->
+```
+
+A fill class never decides an edge and an edge class never decides a fill.
+Use `.solid.edgeless` for a filled box with no line — and prefer it on a
+neutral one, because a capped fill leaves the box translucent and the edge
+blend then paints a second coat of the same tint rather than disappearing
+into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
+
+The edge is the silhouette and nothing else. Rules _inside_ a component that
+has an inside are a separate switch — see
+[Content and layout → Table rules](./content-and-layout.md#table-rules) —
+because tying them to this axis made them arrive by implication rather than
+by request.
+
+With no presentation class in scope, each component keeps its own default:
+buttons are filled, alerts and badges are tinted, surfaces and controls are
+neutral and bordered.
+
+| Component                                       | Reads                                       |
+| ----------------------------------------------- | ------------------------------------------- |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`   | Fill, text, border, and border width.       |
+| `.kbd`                                          | Fill, text, border, and border width.       |
+| `.data-table`                                   | Header fill and text, border, border width. |
+| `.ipt`, `.textarea`, `.select`, `.text-control` | Border, border width, and a capped fill.    |
+| `.input-group`                                  | Border, border width, and a capped fill.    |
+| `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
+| `.switch`                                       | Border, border width, and a capped fill.    |
+| `.quote`                                        | Fill, text, border, and width.              |
+| `.code`, `.pre`, `.tooltip`                     | Fill, text, border, and material.           |
+| `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
+
+Text controls and toggles cap a **cascaded** fill at `6%`, keeping typed
+text legible when a `.solid` container reaches a field nobody classed. A
+fill class written on the control itself names its own cap instead, because
+that is a consumer describing what they want: `.soft` takes `12%` and
+`.solid` takes `20%`. A switch caps at `40%`, where its three fills separate
+far enough to read on a track.
+
+| On a text control | fill |
+| ----------------- | ---- |
+| `.ghost`          | 0%   |
+| cascaded `.solid` | 6%   |
+| `.soft`           | 12%  |
+| `.solid`          | 20%  |
+
+The same split governs the edge: a cascaded `.edgeless` is floored and the
+element's own is honoured — except on `.checkbox` and `.radio`, which never
+drop their line at all. See [Forms](./forms.md) for the full toggle and text
+control reference.
+
+A tooltip bubble is filled, over a tinted ground. An intent fills it with
+that intent's own color: `.tooltip.primary` is the primary color, black on a
+light page and white on a dark one, and `.tooltip.destructive` is a red
+bubble.
+
+With no intent the bubble is `--color-tooltip`, the one plate in the package
+chosen per theme rather than derived from an intent. Composed like
+everything else it was `20%` of the page's ink over the surface tone, which
+steps _lighter_ than the surface on a dark page and _darker_ on a light
+one — so the dark bubble read as lifted and the light one as a mid-grey
+slab two steps darker than every card on the screen. The token states each
+direction instead: near-white over a light page, a mid grey over a dark
+one. `--color-tooltip-contrast` is its ink.
+
+Near-white is only 1.04:1 against a light page, so the bubble draws a
+hairline as well, and floors it: a container's `.solid` or `.edgeless`
+cannot take the boundary away from a bubble nobody classed, while
+`.tooltip.edgeless` still can. The ground keeps the bubble opaque at every
+fill, so a cascaded presentation leaves it readable over whatever it floats
+above. It reads the material tokens too, so an [aesthetic](./aesthetics.md)
+in scope shapes the bubble like any other component. See
+[Tooltips](./tooltips.md) for the full tooltip reference.
+
+## Component axis reference
+
+This table is the authoritative axis map for demonstrated components. "Shape"
+means the component reads applicable radius, border-width, shadow, hover, or
+clip/edge material tokens; an aesthetic may intentionally affect only the
+materials that component draws.
+
+Presentation is two independent axes, so they get a column each. A `Yes` means
+the class changes what the component computes, which
+`tests/browser/axes.spec.ts` asserts against `registry.json` in both
+directions: an axis marked `Yes` must move, and an axis marked `No` must not.
+
+| Components                                                | Intent | Fill | Edge | Aesthetic material |
+| --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`             | Yes    | Yes  | Yes  | Shape              |
+| `.loader`                                                 | Yes    | No   | No   | No                 |
+| `.kbd`, `.data-table`                                     | Yes    | Yes  | Yes  | Radius and edge    |
+| `.quote`                                                  | Yes    | Yes  | Yes  | Edge width         |
+| `.divider`, `.skeleton`                                   | Yes    | No   | No   | No                 |
+| `.ipt`, `.textarea`, `.select`, `.text-control`           | Yes    | Yes  | Yes  | Shape              |
+| `.input-group`                                            | Yes    | Yes  | Yes  | Shape              |
+| `.surface`                                                | Yes    | Yes  | Yes  | Shape              |
+| `.checkbox`, `.radio`                                     | Yes    | Yes  | No   | Radius and edge    |
+| `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
+| `.progress`                                               | Yes    | No   | No   | No                 |
+| `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
+| `.tooltip`                                                | Yes    | Yes  | Yes  | Shape and overlay  |
+| `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
+
+`.checkbox` and `.radio` are the only components that read one axis and not
+the other. Their line is the only thing marking an unchecked box, so it is
+drawn whatever the edge class says, from a container or from the element
+itself. `.edgeless` on either is unsupported rather than merely discouraged.
+
+Every other text control floors a _cascaded_ `.edgeless` and honours its own:
+a `.edgeless` toolbar will not erase the line of a field nobody classed, while
+`.ipt.edgeless` is a consumer describing what they want and gets it.
+
+Intent aliases such as `.danger` and `.error` occupy the same intent axis as
+`.destructive`; they do not add component behavior. State and modifier
+classes such as `.interactive`, `.loading`, `.invalid`, `.compact`, and
+`.vertical` sit above this map and are documented with their component.
+
+## Elevation
+
+Depth is a modifier, not an axis. Nothing is raised until an
+[aesthetic](./aesthetics.md) draws depth or one of these classes asks for it.
+
+| Class             | Alias       | Depth                                                                    |
+| ----------------- | ----------- | ------------------------------------------------------------------------ |
+| `.elevation-none` | `.flat`     | Removes part-based elevation; glass surfaces keep their complete shadow. |
+| `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
+| `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
+
+Both names in a row are equivalent, interchangeable classes — `.elevation-sm`
+and `.raised` are aliases, not a canonical form and a deprecated one, the way
+`.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md`
+naming matches the raw `--elevation-*` tokens in
+[Theming](./theming.md#foundation-tokens) for the same weight of depth, even
+though the two are read from different places.
+
+Each is one unitless multiplier over whatever shadow geometry is in scope, so
+the same class reads as a soft blur on a plain page and as a hard offset slab
+under `.neobrutalism` — the aesthetic decides what depth looks like, the
+class decides how much of it this element takes.
+
+```html
+<article class="card elevation-sm">Lifted</article>
+<div class="elevation-md panel">A menu surface</div>
+<article class="card elevation-none">Flat, whatever the page or container says</article>
+```
+
+The multiplier is a plain number, so it inherits: a container lifts or
+flattens a whole region and any element inside it still opts out on itself.
+Spread is deliberately left out of the multiplication, because an aesthetic
+that draws its edge as an inset ring spends spread on it and scaling that
+would erase the edge.

package/docs/usage/content-and-layout.md

@@ -0,0 +1,200 @@
+---
+title: Content and layout
+description: Layout helpers, content chips and tables, surfaces, and typography utilities.
+---
+
+# Content and layout
+
+## Layout
+
+Layout helpers use the shared `--layout-gap` token. `.tight` sets it to
+`0.5rem` and `.loose` sets it to `1.5rem` within a view, stack, cluster, or
+auto-grid.
+
+- `.view` is a flex container; `.vertical` and `.horizontal` set its
+  direction, and horizontal views wrap with centered cross-axis alignment.
+- `.stack` is a vertical flex stack.
+- `.cluster` is a wrapping horizontal flex row; `.between` adds
+  `space-between` alignment.
+- `.auto-grid` is a responsive auto-fit grid using `--layout-grid-min`.
+- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views,
+  stacks, clusters, and auto-grids.
+- `.section` adds responsive block padding and an inline gutter.
+- `.section-content` centers content at `--container-max`; `.narrow` and
+  `.wide` select the corresponding container tokens.
+- `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It
+  takes intent, but presentation classes do not affect it.
+
+The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no
+compatibility aliases.
+
+## Content
+
+| Class           | Purpose                                                                                  | Intent affects         |
+| --------------- | ---------------------------------------------------------------------------------------- | ---------------------- |
+| `.table-wrap`   | Full-width horizontal overflow wrapper for wide tables.                                  | Nothing.               |
+| `.data-table`   | Rounded nested table styling for captions, heads, footers, cells, and rows.              | Head, border, hover.   |
+| `.ruled`        | On `.data-table`. Draws a rule between body rows.                                        | Rule color.            |
+| `.ruleless`     | On `.data-table`. Draws no lines inside the table at all.                                | Nothing.               |
+| `.kbd`          | Inline keyboard-input styling.                                                           | Surface, border, text. |
+| `.quote`        | Block quote styling; a nested `cite` is set upright and takes the quotation's own color. | Bar, surface, text.    |
+| `.quote-inline` | Inline quotation styling.                                                                | Nothing.               |
+| `.code`         | Inline code formatting.                                                                  | Surface.               |
+| `.pre`          | Scrollable block code formatting with larger padding.                                    | Surface.               |
+
+### Table rules
+
+A table draws three kinds of line, and `.ruled` and `.ruleless` move all of
+them together:
+
+| Class       | Head and foot boundaries | Rules between body rows |
+| ----------- | ------------------------ | ----------------------- |
+| `.ruleless` | No                       | No                      |
+| _no class_  | Yes                      | No                      |
+| `.ruled`    | Yes                      | Yes                     |
+
+```html
+<table class="data-table">Head and foot boundaries only</table>
+<table class="data-table ruled">Every row separated</table>
+<table class="data-table ruleless">No lines inside the table at all</table>
+```
+
+The boundaries under a head and above a foot separate the parts of a table
+from each other, so they are drawn by default where the row rules are not.
+Rules between body rows used to arrive on their own, because the
+component's published edge default is `edged` and the edge axis wrote the
+rules along with the boundary — so whether you got them depended on a
+registry default rather than on anything in your markup.
+
+`--ui-rule` is the token behind both classes, so a container can set the
+answer for a whole region without classing each table:
+
+```html
+<section style="--ui-rule: 100%">
+  <table class="data-table">Ruled by the region</table>
+</section>
+```
+
+The frame around the table is the edge axis and is asked for the same way:
+`.data-table` publishes `edgeless`, so `.edged` draws one. None of the
+three switches reaches the others — `.data-table.ruleless.edged` is a
+framed table with no lines inside it, and `.data-table.ruled` is a
+frameless one with every row separated.
+
+A table's rows deliberately inherit its intent instead of resetting it, so
+`.data-table.success` tints throughout. A row carrying its own intent still
+wins:
+
+```html
+<table class="data-table success">
+  <tbody>
+    <tr>
+      <td>Inherits the table intent</td>
+    </tr>
+    <tr class="destructive">
+      <td>Overrides it for this row</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+This is the one place intent cascades, because a table's rows are parts of
+the table rather than independent components.
+
+`.data-table`, `.kbd`, `.code`, and `.pre` also read
+[presentation](./composing.md#presentation). A table applies it to its
+header, its rules and its border; a chip to its whole plate:
+
+```html
+<table class="data-table success soft edged">...</table>
+<table class="data-table">A ghost table: rules and type, no header plate</table>
+<kbd class="kbd primary solid">Ctrl</kbd>
+<kbd class="kbd primary soft edged">Shift</kbd>
+```
+
+`.ghost` means two different things on these components, and both are worth
+knowing before you reach for it.
+
+On `.data-table` it removes the header plate along with the body tint, so
+`.data-table.ghost` is boundaries and type alone. The component rests at
+`soft`, so that is something to ask for rather than the default.
+
+On `.kbd`, `.code`, and `.pre` it is **not supported**. All three rest on
+`--intent-subtle`, and that ground draws the plate whatever the fill says —
+so `.ghost` took the fill away and changed nothing visible. Worse, the
+ground alone is a near-page tint: a ghost chip measured the same `#e5e5e5`
+for neutral and primary on the light page, and `#f5f5f5` at 1.04:1 against
+it for secondary. All three rest at `.soft` instead, which puts a real `12%`
+of the intent over the ground and separates them.
+
+Use `.table-wrap` around `.data-table` when table width may exceed its
+container:
+
+```html
+<div class="table-wrap">
+  <table class="data-table">
+    <thead>
+      <tr>
+        <th>Package</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>styles</td>
+        <td>Ready</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## Surfaces
+
+| Class                | Purpose                                                                      |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `.card`              | Bordered container, surface radius, padded. Rests at elevation `1`.          |
+| `.panel`             | Flush container for sidebars, toolbars, and wells. No elevation.             |
+| `.interactive`       | On `.card`. Adds pointer cursor, hover and press response, and a focus ring. |
+| `.p-sm`, `.compact`  | On `.card` or `.panel`. Reduces padding.                                     |
+| `.p-lg`, `.spacious` | On `.card` or `.panel`. Increases padding.                                   |
+| `.flush`             | On `.card` or `.panel`. Removes padding, for edge-to-edge content.           |
+
+Both read intent, [presentation](./composing.md#presentation), and
+[material tokens](./customizing.md#material-tokens). A plain `.card` is a
+neutral bordered container; only an explicit presentation tints it. Resting
+at elevation `1` is not a visible shadow by itself — nothing draws depth
+until an [aesthetic](./aesthetics.md) supplies shadow geometry or
+`.elevation-sm`/`.elevation-md` asks for it; see
+[Composing → Elevation](./composing.md#elevation).
+
+On the base look, `.card.interactive` scales down slightly on press
+(`--ui-active-transform`, `scale(0.97)`); an [aesthetic](./aesthetics.md)
+substitutes its own press gesture, and `prefers-reduced-motion` turns it off.
+
+```html
+<article class="card">Neutral card</article>
+<article class="card success soft">Tinted success card</article>
+<article class="card primary ghost edged">Intent border, no fill</article>
+<a class="card interactive" href="/package">Responds to hover and press</a>
+<aside class="panel">Flush panel</aside>
+```
+
+`.interactive` is styling only. Use a real interactive element and give it
+an accessible name; a `<div class="card interactive">` is not focusable or
+operable by keyboard.
+
+## Typography utilities
+
+All typography classes and `.selection-contrast` are `@utility` classes.
+
+| Class                 | Purpose                                                      |
+| --------------------- | ------------------------------------------------------------ |
+| `.text-display`       | Large display headings.                                      |
+| `.text-title-lg`      | Large section titles.                                        |
+| `.text-title`         | Default section titles.                                      |
+| `.text-title-sm`      | Smaller titles or card titles.                               |
+| `.text-label-lg`      | Large label text.                                            |
+| `.text-label`         | Default label text.                                          |
+| `.text-body`          | Default body copy.                                           |
+| `.selection-contrast` | Inverts `::selection` colors to primary-contrast background. |

package/docs/usage/customizing.md

@@ -0,0 +1,213 @@
+---
+title: Customizing
+description: Presentation and material token reference, and aesthetic knobs.
+---
+
+# Customizing
+
+Presentation tokens decide how much of an intent shows. Material tokens
+decide what a component is made of. Aesthetic tokens are the small set of
+named knobs a shipped aesthetic exposes to scale its own look.
+
+## Presentation tokens
+
+Presentation tokens describe _how much_ of an intent a component shows,
+never _which_ intent it shows. They are unitless numbers and percentages, so
+they carry no color and inherit safely: a container sets them once and every
+component below resolves them against its own intent.
+
+| Token             | Purpose                                                                    |
+| ----------------- | -------------------------------------------------------------------------- |
+| `--ui-fill`       | Percentage of the intent color mixed into the background.                  |
+| `--ui-fg-on-fill` | Percentage blended from the intent readable tone toward its contrast tone. |
+| `--ui-border`     | Percentage of the intent color mixed into the border color.                |
+
+A component resolves them with `color-mix` from its published default. Hover
+is derived by adding `--hover-step` to the resting fill and using
+`--intent-hover`; there are no per-presentation hover tokens.
+
+No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A
+filled box with no line is `.solid.edgeless`, which is worth reaching for on
+a neutral component: neutral caps its fill, so the box stays translucent and
+a border over it paints a second coat of the same tint instead of blending
+into it.
+
+```css
+background: color-mix(in oklab, var(--color-primary) var(--ui-fill, 100%), transparent);
+```
+
+Two choices there are deliberate. Mixing toward `transparent` rather than a
+background token lets a tinted surface adapt to whatever it is placed on.
+Mixing in `oklab` keeps the wide-gamut token palette intact and blends
+perceptually, where `srgb` would clip it.
+
+A computed color therefore reaches the page as a resolved `color-mix` result
+rather than the token's own `oklch` syntax. It is the same color; code that
+compares computed color strings should compare colors instead.
+
+> **Presentation token contract**: only presentation classes and consumer
+> overrides set these tokens; components only read them. Setting a value
+> that no presentation class produces is supported but unvalidated. See
+> [Composing](./composing.md) for the classes that ship these values.
+
+## Material tokens
+
+Material tokens describe what a component is _made of_ rather than which
+intent it shows or how strongly. They control shape, borders, shadows,
+translucency, filters, and transforms.
+
+Components read each with a fallback, so leaving them unset produces the
+default look. Setting them on a container restyles the whole subtree. Only
+shadow geometry is split into colorless parts that inherit safely;
+color-capable inputs such as `--ui-ink` and `--ui-surface-shadow` may
+include their own colors.
+
+| Token                   | Purpose                                                                                                       | Fallback             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `--ui-radius`           | Corner radius for controls.                                                                                   | `--radius-control`   |
+| `--ui-radius-surface`   | Corner radius for surfaces.                                                                                   | `--radius-surface`   |
+| `--ui-border-width`     | Edge thickness.                                                                                               | `--border-width`     |
+| `--ui-border-max`       | Ceiling on computed edge width.                                                                               | `100px`              |
+| `--ui-ink`              | Neutral line color when no intent is set.                                                                     | `--color-border`     |
+| `--ui-rule`             | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row. | unset                |
+| `--ui-shadow-x`         | Shadow horizontal offset.                                                                                     | `0px`                |
+| `--ui-shadow-y`         | Shadow vertical offset.                                                                                       | `0px`                |
+| `--ui-shadow-blur`      | Shadow blur radius.                                                                                           | `0px`                |
+| `--ui-shadow-spread`    | Shadow spread radius.                                                                                         | `0px`                |
+| `--ui-shadow-inset`     | The `inset` keyword for an inner ring.                                                                        | Empty                |
+| `--ui-hover-shadow-x`   | Shadow horizontal offset while hovered.                                                                       | `--ui-shadow-x`      |
+| `--ui-hover-shadow-y`   | Shadow vertical offset while hovered.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-shadow-x`  | Shadow horizontal offset while pressed.                                                                       | `--ui-shadow-x`      |
+| `--ui-active-shadow-y`  | Shadow vertical offset while pressed.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-transform` | Transform while pressed. `none` under `prefers-reduced-motion`.                                               | `scale(0.97)`        |
+| `--ui-shadow-ink`       | Percentage of shadow color taken from intent ink.                                                             | `0%`                 |
+| `--ui-shadow-edge`      | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.         | Unset                |
+| `--ui-elevation`        | Unitless multiplier over shadow geometry.                                                                     | `1`                  |
+| `--ui-surface-shadow`   | Complete multi-layer shadow accepted by surfaces only.                                                        | Unset                |
+| `--ui-surface-ground`   | Ground a surface sits on.                                                                                     | `--color-background` |
+| `--ui-bg-alpha`         | Multiplier over fill for translucent materials.                                                               | `1`                  |
+| `--ui-backdrop`         | Backdrop filter accepted by surfaces only.                                                                    | `none`               |
+| `--ui-hover-transform`  | Transform while an interactive element is hovered.                                                            | `none`               |
+| `--ui-clip`             | Structural component silhouette.                                                                              | `none`               |
+| `--ui-clip-tight`       | Compact component silhouette.                                                                                 | `--ui-clip`          |
+| `--ui-focus-inset`      | Inset focus layer width.                                                                                      | Unset                |
+
+```html
+<section style="--ui-radius: 0; --ui-border-width: 3px">
+  <button class="btn primary">Square and heavy</button>
+  <input class="ipt" placeholder="Matches" />
+</section>
+```
+
+> **Material token contract**: components read these; aesthetic classes and
+> consumer overrides set them.
+
+### Shape and ring composition
+
+Clipping removes borders, outlines, and outer shadows. An aesthetic that uses
+a clip can replace the border with an inset shadow by setting
+`--ui-shadow-inset` and the four shadow geometry parts. Set
+`--ui-border-max: 0px` when that ring replaces the component border.
+Focusable components restore the clipped focus outline through
+`--ui-focus-inset`.
+
+Declare `--ui-shadow-edge` when that ring _is_ the border. The ring then
+takes the element's edge color, which carries the edge axis as its alpha, so
+`.edged` draws it and `.edgeless` does not — the same answer a real border
+gives. Without it the ring paints on every component the aesthetic reaches
+and the edge classes have no effect. Use `--ui-shadow-ink` instead when the
+shadow is depth cast in the intent's own ink, such as a hard offset slab,
+which an `.edgeless` element still gets.
+
+The token is read for its presence, not its value: declare it empty to
+switch the ring on, and `initial` to switch it back off in an aesthetic
+nested inside one that declares it.
+
+```css
+.stepped {
+  --ui-clip: polygon(/* structural silhouette */);
+  --ui-clip-tight: none;
+  --ui-border-max: 0px;
+  --ui-shadow-inset: inset;
+  --ui-shadow-edge: ;
+  --ui-shadow-x: 0px;
+  --ui-shadow-y: 0px;
+  --ui-shadow-blur: 0px;
+  --ui-shadow-spread: 4px;
+  --ui-focus-inset: var(--focus-ring-width);
+}
+```
+
+Variables named `--shape-*` are internal composition outputs. Do not set or
+read them; only the `--ui-*` inputs above are public.
+
+## Aesthetic tokens
+
+The shipped [aesthetic classes](./aesthetics.md) set material tokens for you.
+Only aesthetics with a token listed below expose an aesthetic-specific
+token. Tune all other behavior through the shared material tokens above.
+Listed tokens are available only where that aesthetic's stylesheet is
+imported.
+
+| Token                    | Aesthetic       | Purpose                                                     | Default                           |
+| ------------------------ | --------------- | ----------------------------------------------------------- | --------------------------------- |
+| `--neo-offset`           | `.neobrutalism` | Hard shadow offset and distance the press travels.          | `4px`                             |
+| `--glass-radius`         | `.glass`        | Control corner radius.                                      | `0.75rem`                         |
+| `--glass-radius-surface` | `.glass`        | Surface corner radius.                                      | `1rem`                            |
+| `--pixel-unit`           | `.pixel`        | One pixel of the grid. The corner cut and the ring are one. | `4px`                             |
+| `--font-pixel`           | `.pixel`        | Consumer-supplied pixel font stack.                         | Falls back to the monospace stack |
+| `--tile-radius`          | `.chunky-tile`  | Corner radius, on controls and surfaces alike.              | `0.75rem`                         |
+| `--tile-lift`            | `.chunky-tile`  | Depth of the seated bar, and how far a press travels.       | `4px`                             |
+| `--font-rounded`         | `.chunky-tile`  | Consumer-supplied rounded font stack.                       | Falls back to the page stack      |
+
+All four aesthetics reach the same way: each knob is _read_ with its default
+as a `var()` fallback rather than declared, so it resolves once into a
+private on the aesthetic's own class (`--_pixel-unit`, `--_neo-offset`,
+`--_tile-radius`, `--_tile-lift`, and so on). Set a knob on the element
+carrying the aesthetic class, or on any ancestor including `:root`:
+
+```html
+<section class="pixel" style="--pixel-unit: 6px">
+  <button class="btn primary">Chunkier</button>
+</section>
+```
+
+```html
+<html class="pixel" style="--pixel-unit: 6px">
+  <body>
+    <button class="btn primary">Also chunkier, set from the root</button>
+  </body>
+</html>
+```
+
+Knobs and material tokens reach in opposite directions, and telling them
+apart matters. A knob resolves once at the aesthetic's own class and
+inherits down already-resolved, so it reaches the aesthetic **from above**:
+setting it on the element or any ancestor works, but setting it on a
+_descendant_ of the aesthetic class changes nothing — the value has already
+been read. `--ui-radius` and the other material tokens above are read fresh
+by each component as it draws, so they reach **at or below** the element
+carrying them, which is how you round one card differently from its
+neighbours without touching the knob at all.
+
+Shipped aesthetics set the shared material tokens above. `.neobrutalism` and
+`.pixel` set `--ui-ink` for their neutral outline; intent classes still
+override the intent slots on each component.
+
+## Component internals
+
+Component classes may define scoped implementation variables such as
+`--button-*`, `--surface-*`, `--control-*`, `--feedback-*`, and `--tooltip-*`.
+These variables are internal wiring for class composition and are not the
+public token contract.
+
+Consumers should customize broad behavior through color, foundation, motion,
+elevation, radius, layout, and focus tokens first. The only supported
+component-scoped input is `--progress-value` on the `.progress` element,
+because consumers must provide a value such as `64%`.
+
+`--layout-gap` replaces the removed `--layout-stack-gap` and
+`--layout-cluster-gap` tokens. No compatibility aliases are provided.
+
+Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete
+look and its documented exceptions.