themelia-ui 1.0.0

package/dist/styles/FACTORS.md

@@ -0,0 +1,65 @@
+# The scale chain
+
+Four factors for the whole kit. There is no per-component factor.
+
+```
+--scale            everything
+  ├── --space-scale     gaps and padding   (defaults to --scale)
+  ├── --density-scale   heights and rows   (defaults to --scale)
+  └── --text-scale      all typography     (defaults to --scale)
+```
+
+`--scale` is the one-knob default: geometry, spacing, icons, prose, and control labels move
+together. `UIProvider`'s `typography.scale` overrides `--text-scale` at one scope when type
+must move independently. It applies to every type role, including control labels, so the
+same `sm` role cannot render at two sizes merely because one instance sits in a button.
+
+```css
+/* everything denser */
+:root { --scale: 0.875; }
+
+/* tighter spacing, same control heights */
+:root { --space-scale: 0.875; }
+
+/* larger type, control geometry untouched */
+:root { --text-scale: 1.125; }
+```
+
+Density presets set `--space-scale` and `--density-scale` per scope, so a region can be
+denser than the page without shrinking readable type:
+
+```html
+<div data-density="compact">…</div>
+```
+
+Use `UIProvider config={{ scale: 0.875 }}` only when the entire interface—including its
+type ramp—should move together.
+
+## Why there is no `--button-scale`
+
+There was, and 44 more like it. Every family declared its own factor defaulting to the
+global one, so a consumer could scale one family alone. It read well and cost 215 tokens —
+close to half the theming layer — because carrying the multiplication meant minting a name
+for every measurement in every family:
+
+```css
+/* before: one name per measurement, per family */
+--accordion-scale: var(--scale);
+--accordion-media-gap: calc(0.75rem * var(--accordion-scale));
+
+/* after: the step already carries the factor */
+gap: var(--space-lg);
+```
+
+`--space-lg` **is** `calc(0.75rem * var(--space-scale))`. The family version was the same
+number wearing a different hat: of the 385 references that carried a family factor, 217
+turned out to be a spacing step that already had a name.
+
+The ability to scale one family alone is genuinely gone. It was traded for a theming layer
+a person can read, which is the thing a consumer actually reaches for first.
+
+`scripts/verify-factors.mjs` fails if a per-family factor reappears, if a declaration
+multiplies two factors directly, or if an ordinary CSS property multiplies an
+already-scaled token by another factor. At scale 0.5 a squared factor is 0.25, which reads
+as a rendering bug rather than a maths one. Separate additive terms remain valid because
+each term carries its factor exactly once.

package/dist/styles/SCOPES.md

@@ -0,0 +1,37 @@
+# Why derived tokens are not declared on `:root`
+
+A custom property's `var()` references are substituted **where the property is declared**.
+So a derived token declared once at `:root`:
+
+```css
+:root {
+  --action: calc(var(--height-action) * var(--density-scale));
+  --button-default-bg: var(--primary);
+}
+```
+
+…resolves `--density-scale` and `--primary` at `:root`, and the RESULT is what inherits.
+Setting `--density-scale: 0.875` or `--primary: red` on a nested element changes nothing —
+`--action` is already `calc(2.25rem * 1)` and `--button-default-bg` is already the root
+colour. Scoped density and scoped theming are impossible.
+
+Declaring them at every **scope boundary** instead makes each boundary re-derive from its
+own inputs, and descendants inherit that scope's values:
+
+```css
+:root,
+[data-ui-scope],
+[data-density],
+[data-theme],
+.light,
+.dark {
+  --action: calc(var(--height-action) * var(--density-scale));
+}
+```
+
+`<UIProvider>` renders `[data-ui-scope]`, so any provider — nested or not — re-derives the
+whole system from whatever it overrides. `[data-density]` and `[data-theme]` do the same
+for the CSS-only path, where a consumer sets the attribute without a provider.
+
+This is not `*`: re-deriving on every element in the document would be wasteful. Only
+elements that can CHANGE an input need to recompute.

package/dist/styles/TOKENS.md

@@ -0,0 +1,143 @@
+# The token contract
+
+Only the first two layers are the theme. The third is where components keep their own
+measurements, and it is not a place a theme author needs to go.
+
+<!-- token-report:start -->
+```text
+themes/default.css      55 tokens   what a rebrand touches
+tokens/*.css           111 tokens   ramps and ladders behind the theme
+global contract        166 tokens   themes plus token ramps
+styles/theming/*.css   170 tokens   cross-cutting wiring (14 files)
+*.module.css           278 tokens   component-owned and runtime transport
+component total        429 tokens
+```
+
+The component total contains 102 responsive
+transport variables written by `Stack`, `Grid`, `GridCell`, `AdaptiveGrid`, `Split`,
+`Bleed`, and `AspectRatio`. They are
+runtime prop values carried into breakpoint fallback chains, not theme extension points.
+The remaining classifications are 196 earns its name, 96 extension point, 5 keyframe holder, 30 runtime hook.
+<!-- token-report:end -->
+
+**Quote the global contract count above, not the component total.** They answer
+different questions and only the first is a theme surface: a theme author sets the
+contract and every component follows, because a component token is either derived from it
+or a measurement a rebrand has no opinion about.
+
+**A component's variables live with the component.** `theming/tooltip.css` declaring three
+arrow measurements read by exactly one stylesheet was never theming; it was tooltip's CSS
+filed under the wrong heading. Forty such files moved to their modules, keeping the same
+scope-selector block so the cascade is unchanged. What a file in `theming/` has to earn now
+is being read by *many* components.
+
+`scripts/verify-token-budget.mjs` holds these numbers, and looks in both trees — a check
+scoped to one directory stops covering a token the moment it moves to where it belongs. It
+fails on a dead token, a PASS-THROUGH (a second name for another token, doing no arithmetic
+and never re-pointed — see below), an override nothing reads, a runtime token no stylesheet
+declares, a colour literal below `tokens/`, and a length off the 2px grid.
+
+## What earns a component token
+
+One of three things, and a name that does none of them is noise:
+
+* **arithmetic** — `--heatmap-pitch: calc(var(--heatmap-cell) + var(--space-2xs))`
+* **a variant or scope re-points it** — `--badge-hue`, declared once per tone
+* **JS writes it** — `style={{ "--micro-bar": "62%" }}`, the interface a chart arrives through
+
+`--sidebar-p: var(--space-md)` does none. Read six times, it is still one name standing in
+front of one step, and all six readers can say `--space-md`. Eighty-two of those were
+removed in one pass with no pixel changing; `verify:token-budget` now fails on them.
+
+Two exemptions, both load-bearing. A **family with a member re-declared in another file**
+is an extension point — inlining `--text-role-main` breaks the auth panel that re-points it
+for its own subtree. And a token **named in TSX or a test** has a reader a `var()` scan
+cannot see.
+
+## What a theme owns
+
+`themes/default.css` is generated from `scripts/theme-manifest.mjs` — edit the manifest,
+run `npm run tokens:theme`. It is shadcn-shaped on purpose, so a shadcn theme drops in.
+
+**Colour** resolves through the ramp in `tokens/palette.css`; there are no literals in the
+theme file, so a rebrand moves the ramp rather than forty separate values.
+
+```css
+--background --foreground --card --popover --primary --secondary
+--muted --accent --destructive --border --input --ring
+--chart-1…5 --sidebar-*
+```
+
+**Edge** — the three properties that describe every border in the kit, kept together
+because they are one decision:
+
+```css
+--border: var(--neutral-200);   /* colour */
+--border-width: 1px;            /* weight */
+--radius: 0.625rem;             /* corner  */
+```
+
+**Shape** derives from `--radius`, and the ROLES are what components ask for. A component
+never picks a step off the scale; it names what it is, so a retheme moves every surface
+together:
+
+| role | used by |
+|---|---|
+| `--radius-surface` | cards, dialogs, popovers, menus |
+| `--radius-control` | buttons, inputs, tabs, badges |
+| `--radius-inner` | menu rows, chips, calendar cells — nested inside a control |
+| `--radius-pill` | switches, avatars, pills |
+
+## What the ramps own
+
+`tokens/` holds the ladders the theme resolves against: the colour ramp, the type scale
+(`--text-xs` … `--text-2xl` and its paired line heights), the spacing scale, the content
+widths, and the raw tunables — `--height-action`, `--control-x`, `--row-x/y`,
+`--surface-x/y`, `--icon`, `--avatar`, `--scale`.
+
+**Spacing sits on a 2px grid.** Every length under `4rem` is a multiple of `0.125rem`.
+This is not decoration: `--menu-row-px: calc(0.6875rem * var(--space-scale))` was 11px,
+next to a 12px row inset, and nobody reviewing one menu ever saw the mismatch.
+
+**Type is exempt from the grid**, because a type ramp is geometric — `0.75`, `0.8125`,
+`0.875`, `1`, `1.125` — and lands off a 2px grid by construction. `0.8125rem` is the
+`--text-pxs` step, not a stray 13px.
+
+## What components own
+
+**A component reads the theme directly.** `background-color: var(--foreground)` in the
+module, not `--tooltip-bg: var(--foreground)` somewhere else and `var(--tooltip-bg)` here.
+The second form is a name with one reader, and 376 of them is not a design system, it is a
+layer of indirection nobody asked for. Tooltip declared twelve tokens; it declares three.
+
+Where a component does need to adjust a theme value, it does the arithmetic in its own
+rule — `calc(var(--space-lg) * 2)` — rather than minting a name for the result.
+
+A token earns a NAME only when one of these is true:
+
+| | |
+|---|---|
+| **read by two or more rules** | naming it is what keeps them equal |
+| **an extension point** | another file re-declares it, so inlining kills the override |
+| **read from TS/TSX** | a runtime hook; the indirection is the API |
+| **an `--animate-*`** | CSS Modules scope keyframe names; inlined, the animation dies |
+| **a bare length a module may not hold** | `verify-composition` forbids raw px in a module |
+
+Everything else belongs in the rule that uses it. It may still not hold a colour literal —
+colour always resolves through the palette.
+
+And a token that earns a name lives with whatever owns it: in the component's own module if
+one component reads it, in `styles/theming/` only if many do.
+
+**An extension point is anything another file re-declares**, and that includes a one-line
+rule: `.columns4 { --choice-card-min: 9rem; }` is how a variant re-points a token, and
+inlining the default silently kills all three column variants. `verify-token-budget` reads
+declarations after a `{` or `;`, not only at a line start, precisely because that is the
+form these take.
+
+There is no per-component scale factor. See [FACTORS.md](./FACTORS.md) for what replaced
+the 45 of them.
+
+See [FACTORS.md](./FACTORS.md) for how the four global factors compose without family
+factors, and [SCOPES.md](./SCOPES.md) for why derived values are declared at every scope
+boundary rather than once at `:root`.

package/dist/styles/base.css

@@ -0,0 +1,160 @@
+/*
+ * Base reset.
+ *
+ * ── Why this is more than the source kit's `@layer base` block ──────────────────────
+ * Upstream that block held only three rules, because Tailwind's Preflight was silently
+ * supplying the rest. Dropping Tailwind drops Preflight, and every component in the kit
+ * was authored against it — so the parts the components actually depend on are ported
+ * here. Without them a `ghost` button renders on the UA's `buttonface` grey instead of
+ * transparent, and form controls fall back to system fonts and colours.
+ *
+ * This is a deliberate, minimal subset — not a normalize.css — covering only what the
+ * components rely on: the border reset, form-control inheritance, and replaced-element
+ * defaults.
+ */
+@layer base {
+	/*
+	 * Border reset. Components declare `border: var(--border-width) solid transparent` and then set only
+	 * `border-color` per variant, which requires a zero-width solid border by default.
+	 */
+	*,
+	*::before,
+	*::after {
+		box-sizing: border-box;
+		border: 0 solid var(--border);
+	}
+
+	* {
+		margin: 0;
+	}
+
+	html {
+		font-family: var(--font-sans);
+		line-height: var(--text-sm--line-height);
+		-webkit-text-size-adjust: 100%;
+		tab-size: 4;
+	}
+
+	body {
+		background-color: var(--background);
+		color: var(--foreground);
+		font-size: var(--text-sm);
+		line-height: var(--text-sm--line-height);
+		-webkit-font-smoothing: antialiased;
+		-moz-osx-font-smoothing: grayscale;
+	}
+
+	code,
+	kbd,
+	samp,
+	pre {
+		font-family: var(--font-mono);
+		font-size: 1em;
+	}
+
+	/* Headings carry no intrinsic scale; the typography components own that. */
+	h1, h2, h3, h4, h5, h6 {
+		font-size: inherit;
+		font-weight: inherit;
+	}
+
+	a {
+		color: inherit;
+		text-decoration: inherit;
+	}
+
+	b, strong { font-weight: bolder; }
+	small { font-size: 80%; }
+	sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
+	sub { bottom: -0.25em; }
+	sup { top: -0.5em; }
+
+	table {
+		border-collapse: collapse;
+		border-color: inherit;
+		text-indent: 0;
+	}
+
+	/*
+	 * Form controls. The UA gives these their own font, colour, and `buttonface`
+	 * background; every component in the kit assumes they inherit instead.
+	 */
+	button,
+	input,
+	optgroup,
+	select,
+	textarea {
+		font: inherit;
+		font-feature-settings: inherit;
+		font-variation-settings: inherit;
+		letter-spacing: inherit;
+		color: inherit;
+		background-color: transparent;
+		border-radius: 0;
+		opacity: 1;
+		padding: 0;
+	}
+
+	button,
+	input[type="button"],
+	input[type="reset"],
+	input[type="submit"] {
+		appearance: button;
+		background-color: transparent;
+		background-image: none;
+	}
+
+	/* A disabled control still shows the pointer cue components apply themselves. */
+	button:not(:disabled),
+	[role="button"]:not(:disabled) {
+		cursor: pointer;
+	}
+
+	:disabled {
+		cursor: default;
+	}
+
+	::placeholder {
+		opacity: 1;
+		color: var(--muted-foreground);
+	}
+
+	textarea {
+		resize: vertical;
+	}
+
+	::-webkit-search-decoration {
+		-webkit-appearance: none;
+	}
+
+	::-webkit-inner-spin-button,
+	::-webkit-outer-spin-button {
+		height: auto;
+	}
+
+	/*
+	 * Replaced elements default to inline, which leaves a descender gap under every
+	 * icon and image sitting in a flex row.
+	 */
+	img,
+	svg,
+	video,
+	canvas,
+	audio,
+	iframe,
+	embed,
+	object {
+		display: block;
+		vertical-align: middle;
+	}
+
+	img,
+	video {
+		max-width: 100%;
+		height: auto;
+	}
+
+	[hidden]:not([hidden="until-found"]) {
+		display: none !important;
+	}
+}

package/dist/styles/fields.css

@@ -0,0 +1,166 @@
+/*
+ * The shared field surface.
+ *
+ * ── Why this is global rather than a module ─────────────────────────────────────────
+ * Every text control wears the same surface: one height, one border, one radius, one
+ * focus ring, one invalid state, one disabled treatment. Expressing that in each
+ * component's own module means five copies that drift the moment one is edited.
+ *
+ * A control opts in with `data-field-control`, and then styles only what is genuinely its
+ * own — a textarea's resize behaviour, a select's chevron. Adding a control later gets the
+ * surface for free and cannot get it subtly wrong.
+ *
+ * Layered as `components` so a consumer's unlayered CSS still wins, exactly like a module.
+ */
+@layer components {
+	[data-field-control] {
+		width: 100%;
+		min-width: 0;
+		height: var(--field-h);
+		padding-inline: var(--field-px);
+		padding-block: var(--field-py);
+		border: var(--border-width) solid var(--input);
+		border-radius: var(--radius-control);
+		background-color: var(--field-bg);
+		color: var(--foreground);
+		font: inherit;
+		/*
+		 * 16px on small screens is load-bearing, not cosmetic: iOS Safari zooms the viewport
+		 * when a focused field's text is under 16px. It drops to the reading size from `md`,
+		 * where no such zoom exists.
+		*/
+		font-size: var(--text-base);
+		line-height: var(--text-base--line-height);
+		box-shadow: var(--shadow-xs);
+		outline: none;
+		transition:
+			color var(--duration-fast) var(--ease-in-out),
+			border-color var(--duration-fast) var(--ease-in-out),
+			box-shadow var(--duration-fast) var(--ease-in-out);
+	}
+
+	@media (min-width: 48rem) {
+		[data-field-control] {
+			font-size: var(--text-sm);
+			line-height: var(--text-sm--line-height);
+		}
+	}
+
+	[data-field-control]::placeholder {
+		color: var(--muted-foreground);
+	}
+
+	[data-field-control]:focus-visible {
+		border-color: var(--ring);
+		box-shadow: var(--focus-ring);
+	}
+
+	/*
+	 * Invalid is expressed with `aria-invalid`, so the styling and the announcement can
+	 * never disagree — a red border with nothing said to a screen reader is the usual way
+	 * that happens.
+	 */
+	[data-field-control][aria-invalid="true"] {
+		border-color: var(--invalid-ring-border);
+		box-shadow: var(--invalid-ring);
+	}
+
+	/*
+	 * Focus wins the RING; invalid keeps the BORDER. Both signals, neither lost.
+	 *
+	 * The invalid rule is later than the focus rule and at the same weight, so it took the
+	 * box-shadow with it: an invalid field painted exactly the same focused and unfocused,
+	 * which is a field a keyboard user cannot find. `tests/interaction.spec.ts` calls that
+	 * "focus painted nothing" and it named /form-binding's first input the moment
+	 * `aria-invalid` started reaching controls at all — the rule had been unreachable rather
+	 * than correct.
+	 */
+	[data-field-control][aria-invalid="true"]:focus-visible {
+		box-shadow: var(--focus-ring);
+	}
+
+	[data-field-control]:disabled {
+		cursor: not-allowed;
+		opacity: var(--disabled-opacity);
+	}
+
+	/* Autofill repaints the background white in Chrome; this keeps the surface intact. */
+	[data-field-control]:autofill,
+	[data-field-control]:-webkit-autofill {
+		-webkit-text-fill-color: var(--foreground);
+		box-shadow: var(--shadow-xs), inset 0 0 0 100px var(--background);
+	}
+
+	/*
+	 * ── The shell ───────────────────────────────────────────────────────────────
+	 * A container that wears the field surface on behalf of the control inside it, so a
+	 * leading icon or a trailing action reads as part of one field rather than a box
+	 * inside a box. Used by FieldShell and the combobox chips container, which is why it
+	 * lives here rather than inside either one's module.
+	 *
+	 * InputGroup still carries its own copy under its own token family. It differs in one
+	 * respect that matters — its addons run to the edge, so it has no inline padding of
+	 * its own — and the control-padding rules it layers on top depend on beating this
+	 * sheet's `padding-inline: 0`, which is source order within the components layer
+	 * rather than anything guaranteed. Folding it in is worth doing, but not as a
+	 * side effect of adding a combobox.
+	 */
+	[data-field-shell] {
+		display: flex;
+		align-items: center;
+		/* Inline affordances — a leading icon, a trailing action, a unit suffix. */
+		gap: var(--space-sm);
+		min-height: var(--field-h);
+		padding-inline: var(--field-px);
+		border: var(--border-width) solid var(--input);
+		border-radius: var(--radius-control);
+		background-color: var(--field-bg);
+		box-shadow: var(--shadow-xs);
+		transition:
+			border-color var(--duration-fast) var(--ease-in-out),
+			box-shadow var(--duration-fast) var(--ease-in-out);
+	}
+
+	/*
+	 * `:has()` on the control's own state rather than `:focus-within`: a trailing button
+	 * receiving focus must not light the field up as though the text cursor were in it.
+	 */
+	[data-field-shell]:has([data-field-control]:focus-visible) {
+		border-color: var(--ring);
+		box-shadow: var(--focus-ring);
+	}
+
+	[data-field-shell]:has([data-field-control][aria-invalid="true"]),
+	[data-field-shell][aria-invalid="true"] {
+		border-color: var(--invalid-ring-border);
+		box-shadow: var(--invalid-ring);
+	}
+
+	/* The same rule for a shell, which wears the ring on its control's behalf. */
+	[data-field-shell]:has([data-field-control][aria-invalid="true"]):has(
+			[data-field-control]:focus-visible
+		),
+	[data-field-shell][aria-invalid="true"]:has([data-field-control]:focus-visible) {
+		box-shadow: var(--focus-ring);
+	}
+
+	[data-field-shell]:has([data-field-control]:disabled) {
+		cursor: not-allowed;
+		opacity: var(--disabled-opacity);
+	}
+
+	/* A control inside a field shell gives up its own chrome; the shell wears it. */
+	[data-field-shell] [data-field-control] {
+		height: auto;
+		border: 0;
+		border-radius: 0;
+		background: none;
+		box-shadow: none;
+		padding-inline: 0;
+	}
+
+	[data-field-shell] [data-field-control]:focus-visible,
+	[data-field-shell] [data-field-control][aria-invalid="true"] {
+		box-shadow: none;
+	}
+}

package/dist/styles/forced-colors.css

@@ -0,0 +1,45 @@
+/*
+ * Windows High Contrast Mode — putting the focus ring back.
+ *
+ * The kit draws every focus ring with `box-shadow: var(--focus-ring)` and, because a
+ * native outline cannot follow a rounded corner the way a shadow can, 47 component modules
+ * set `outline: none` beside it. In forced-colors mode Chromium DROPS box-shadow
+ * altogether, so the pair leaves nothing at all.
+ *
+ * Measured on 90 controls under `forced-colors: active`: 51 of them changed ZERO pixels on
+ * focus — `tabs--tab`, `select--component`, `accordion-trigger--component`,
+ * `button--component` among them. Focusing a tab was literally invisible. That is WCAG
+ * 2.4.7 failing in the one mode whose users chose it because they need contrast.
+ *
+ * ── Why this file, and why this layer ────────────────────────────────────────────────
+ * `outline: none` is written inside `@layer components`, so the restoration has to come
+ * from a layer that outranks it, and `utilities` is the only one after it. That layer's
+ * charter is caller-supplied class hooks, which this is not — hence its own file, named
+ * for what it does, rather than growing the utilities sheet into a place where rules go
+ * when nothing else fits.
+ *
+ * `Highlight` and `HighlightText` are system colours: in forced-colors mode the user's own
+ * palette is the only palette, and naming a token here would be overridden anyway.
+ */
+@layer utilities {
+	@media (forced-colors: active) {
+		/*
+		 * `:focus-visible` alone, not `:focus`. The kit's rings are all focus-visible, and
+		 * matching plain focus would ring a control the pointer just clicked — which is the
+		 * behaviour every one of those 47 `outline: none` rules exists to avoid.
+		 */
+		*:focus-visible {
+			outline: 2px solid Highlight;
+			outline-offset: 2px;
+		}
+
+		/*
+		 * A field's ring is drawn on its SHELL, not on the control, so the control itself is
+		 * what takes focus and the shell is what should show it.
+		 */
+		[data-field-shell]:has([data-field-control]:focus-visible) {
+			outline: 2px solid Highlight;
+			outline-offset: 2px;
+		}
+	}
+}