@juwel-development/design-system 1.1.0 → 2.1.0

package/src/Theme/Palette.ts

@@ -23,29 +23,49 @@ export type PaletteTokens = {
   muted: string;
   /** Hairlines and dividers. */
   border: string;
+  /** The boundary of a control with no fill of its own, so it is the only thing separating the
+   *  control from the surface. Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against `surface`
+   *  in the same theme. */
+  controlBorder: string;
+  /** The structural rule that marks where a block's structure is, weightier than `border`'s hairline
+   *  dividers and lighter than `controlBorder`'s control edge. It serves three consumers: a table's
+   *  heavier top line above the first row, a checklist's tick, and a page section's join to the
+   *  section before it. A mid-neutral, so it structures without boxing. Constraint: at least 3:1
+   *  against `surface` in the same theme. */
+  rule: string;
+  /** The plate behind content that has not painted - an image still loading, or one that failed and
+   *  is showing its alt text. Constraint: at least 4.5:1 against `foreground` in the same theme,
+   *  because a failed image renders its alt text on this plate and that text must stay legible. That
+   *  keeps it near `surface` rather than a mid grey. */
+  backing: string;
 
   /** The main call-to-action fill. */
   primary: string;
   primaryHover: string;
   /** Text and icons drawn on top of `primary`. */
   primaryForeground: string;
-  /** Focus ring for primary surfaces - lighter than the fill so it reads against it. */
-  primaryRing: string;
 
   /** The alternative action fill, for choices that sit beside a primary one. */
   secondary: string;
   secondaryHover: string;
   secondaryForeground: string;
-  secondaryRing: string;
 
-  /** Fill for controls that cannot be interacted with. */
+  /** The tone a control takes when it cannot be interacted with - its fill, or its border when
+   *  the fill is transparent. */
   disabled: string;
   /** Kept distinct from `disabled` so a disabled control still absorbs hover rather than
    *  appearing to respond to it. */
   disabledHover: string;
 
-  /** Focus ring for surfaces that have no fill of their own, such as a ghost button. */
-  ring: string;
+  /** The one focus ring, drawn by every focusable primitive regardless of variant - a focus ring
+   *  states keyboard position, not the control's importance. Constraint (WCAG 2.2 SC 1.4.11): at
+   *  least 3:1 against `surface` in the same theme. */
+  focusRing: string;
+
+  /** The colour of a prose link. A link is told apart by its underline, never by hue, so this
+   *  carries the text threshold, not the 3:1 the ring takes. Constraint (WCAG 2.2 SC 1.4.3): at
+   *  least 4.5:1 against `surface` in the same theme. */
+  link: string;
 
   /** Status colours. Not yet consumed by a component - they complete the role set so the
    *  first Alert or Toast has names to reach for instead of inventing them. */
@@ -60,21 +80,24 @@ export const light: PaletteTokens = {
   foreground: '#0f172a',
   muted: '#64748b',
   border: '#e2e8f0',
+  controlBorder: '#64748b',
+  rule: '#808fa3',
+  backing: '#f1f5f9',
 
   primary: '#8b5cf6',
   primaryHover: '#7c3aed',
   primaryForeground: '#f8fafc',
-  primaryRing: '#a78bfa',
 
   secondary: '#0ea5e9',
   secondaryHover: '#0284c7',
   secondaryForeground: '#f8fafc',
-  secondaryRing: '#38bdf8',
 
   disabled: '#94a3b8',
   disabledHover: '#64748b',
 
-  ring: '#94a3b8',
+  focusRing: '#475569',
+
+  link: '#2563eb',
 
   success: '#10b981',
   warning: '#f59e0b',
@@ -93,21 +116,24 @@ export const dark: PaletteTokens = {
   foreground: '#f8fafc',
   muted: '#94a3b8',
   border: '#334155',
+  controlBorder: '#94a3b8',
+  rule: '#5b6a80',
+  backing: '#1e293b',
 
   primary: '#7c3aed',
   primaryHover: '#8b5cf6',
   primaryForeground: '#f8fafc',
-  primaryRing: '#a78bfa',
 
   secondary: '#0284c7',
   secondaryHover: '#0ea5e9',
   secondaryForeground: '#f8fafc',
-  secondaryRing: '#38bdf8',
 
   disabled: '#475569',
   disabledHover: '#334155',
 
-  ring: '#64748b',
+  focusRing: '#cbd5e1',
+
+  link: '#60a5fa',
 
   success: '#34d399',
   warning: '#fbbf24',

package/src/Theme/renderTokens.ts

@@ -7,6 +7,18 @@ const GENERATED_HEADER = `/* GENERATED from src/Theme/Palette.ts by \`npm run bu
  * values inside @theme directly would freeze them at build time and the .dark overrides would
  * never reach the utilities. */`;
 
+const GENERATED_LIGHT_HEADER = `/* GENERATED from src/Theme/Palette.ts by \`npm run build:tokens\` - do not edit by hand.
+ *
+ * The light-only variant (issue #62): the light values live in :root and the @theme inline block
+ * maps each onto a Tailwind colour. It carries no dark rule, so a light-only consumer imports it
+ * instead of tokens.css and bundles no second theme it cannot remove. */`;
+
+const GENERATED_DARK_HEADER = `/* GENERATED from src/Theme/Palette.ts by \`npm run build:tokens\` - do not edit by hand.
+ *
+ * The dark-only variant (issue #62): the dark values live in :root, ungated, and the @theme inline
+ * block maps each onto a Tailwind colour. A dark-only consumer imports it instead of tokens.css; it
+ * is the only theme, so no class toggle or variant is needed to select it. */`;
+
 /* The library performs exactly one motion - a colour transition - so its motion contract is this
    single token. 150ms matches Tailwind's default, so it changes nothing visually; its job is to
    have a name a consumer theme and the reduced-motion query can reach.
@@ -23,6 +35,153 @@ const MOTION = `:root {
   }
 }`;
 
+/* The ring's width and offset are not colours: like motion they live in :root only, never in
+   @theme inline, so a consumer can re-point them. Constraint: both > 0 - a zero width is no
+   indicator, a zero offset drops the ring onto the fill where the 3:1-against-surface rule fails.
+   See docs/adr/0002-focus-ring-token-contract.md. */
+const FOCUS_RING = `:root {
+  --focus-ring-width: 3px;
+  --focus-ring-offset: 2px;
+}`;
+
+/* Radius is not a colour: like motion and the focus-ring dimensions it lives in :root only, never
+   in @theme inline. One token names the corner every control reads; 0.5rem is exactly what
+   rounded-lg resolved to, so nothing changes visually while it keeps tracking the root font size.
+   No structure radius, no value constraint - both deliberate; see docs/adr/0003-radius-token-contract.md. */
+const RADIUS = `:root {
+  --radius-control: 0.5rem;
+}`;
+
+/* The control's minimum width is not a colour: like radius it lives in :root only, never in
+   @theme inline, so a consumer theme can re-point it. One token names the floor primary and
+   secondary share; 10.5rem is exactly what min-w-42 resolved to, so nothing changes visually while
+   it keeps tracking the root font size. ghost owns a distinct zero - an intentional role, not this
+   token set to 0 - so it keeps its literal min-w-0 and does not read this. */
+const CONTROL_MIN_WIDTH = `:root {
+  --control-min-width: 10.5rem;
+}`;
+
+/* The library's underline is not a colour: like the focus-ring dimensions it lives in :root only,
+   never @theme inline. Not prose's alone - every Link treatment that draws a line draws it from these.
+   Constraint: --underline-thickness-hover > --underline-thickness (the thicken on hover is the only
+   cue telling a prose link apart, never hue) and both > 0. The pair names a rest state and a thickened
+   one, so only prose - whose line is always on screen - reads the -hover token; a line that merely
+   appears on hover takes --underline-thickness. Either way the change is instant, decoration being off
+   the transition allowlist. See docs/adr/0006-link-treatment-contract.md. */
+const UNDERLINE = `:root {
+  --underline-offset: 0.18em;
+  --underline-thickness: 1px;
+  --underline-thickness-hover: 2px;
+}`;
+
+/* Typography is not a colour and, unlike the blocks above, not :root-only: Tailwind 4's --font-*,
+   --text-*, --leading-* and --tracking-* are theme namespaces, so its own @theme block generates the
+   font-primary/text-display/leading-body/tracking-label utilities a sealed recipe reaches. No
+   Tailwind built-in is re-pointed; only new role names. See docs/adr/0004-typography-token-contract.md. */
+const TYPOGRAPHY = `@theme {
+  /* Both faces default to inherit, so the library ships no @font-face and no face and a one-face
+     consumer renders as today. --font-primary is carried by content, --font-secondary by labels; a
+     component sets font-variant-numeric: tabular-nums only on a --font-primary carrying tnum and
+     font-variant-caps: small-caps only on a --font-secondary carrying smcp - both fail silently otherwise. */
+  --font-primary: inherit;
+  --font-secondary: inherit;
+
+  /* Type roles, not a scale: one role per job, so a component asks for what its text is, never a rung.
+     display > title > subtitle are the three heading steps H1-H3 bind to; H4-H6 share body and split
+     by weight, so there is no fourth role. display is the hero and must out-scale every subpage head. */
+  --text-display: clamp(3rem, 7vw, 6rem);
+  --leading-display: 1.05;
+  --text-title: clamp(2.25rem, 5vw, 4.25rem);
+  --leading-title: 1.1;
+  --text-subtitle: clamp(1.5rem, 3vw, 2.25rem);
+  --leading-subtitle: 1.2;
+
+  /* The reading block's opening paragraph (Prose #21): sized above body and below subtitle, led
+     tighter than body's 1.6 but not as tight as a heading's 1.2 - it is running text, not a head, so
+     it keeps running-text leading. A role, not a rung: one lede per block, nothing to choose. Reusing
+     subtitle was rejected in ADR 0004 - it welds the lede's size to H3's and its leading to a head's. */
+  --text-lede: 1.25rem;  /* 20px */
+  --leading-lede: 1.4;
+  --text-body: 1.0625rem;  /* 17px */
+  --leading-body: 1.6;
+  --text-small: 0.9375rem;  /* 15px floor: below it tabular figures stop comparing column to column */
+  --text-label: 0.8125rem;  /* 13px floor: below it the tracking reads as damage, not a device */
+
+  /* Two quantities on one property that must not collapse: --tracking-label is a fixed letter-spaced
+     style, --tracking-optical a correction that varies with size. The names say which is which, so the
+     distinction survives without the ADR in hand. Scope: the title role and above - H1, H2 and the page
+     head's h1 - and never below it, where the correction would read as damage. See the ADR. */
+  --tracking-label: 0.14em;
+  --tracking-optical: -0.02em;
+}`;
+
+/* The reading measure is in ch, not rem, so the character count stays held when the body size moves
+   under it; --measure-display is narrower because bigger type wants fewer characters per line, and
+   --measure-wide slightly wider - the standfirst of a page head (PageHead #18) is an opening statement,
+   not a reading column, so it runs a little past the reading measure by design. All three in ch and,
+   having no Tailwind namespace, in :root beside radius, read as max-w-[var(--measure)]. */
+const MEASURE = `:root {
+  --measure: 66ch;
+  --measure-display: 36ch;
+  --measure-wide: 72ch;
+}`;
+
+/* Three spacing roles, not a ladder: --space-stack is the sibling gap in a stack, --space-region the air
+   around a region of a page - a form's region groups and the shell's bars, above and below the header and
+   the footer and between the header's nav items (#14/#15) - and --space-band the vertical air inside a page
+   section (#9). All three in em so they track the type ramp, not a fixed length. Three names a reader could
+   line up stack < region < band is exactly where "roles, not rungs" is tested - and it holds: each is bound
+   to one job with nothing to choose between, not to a step on a ramp a component picks from. A numbered
+   scale (--space-1..4) was rejected for that reason - ADR 0003/0004. em has no Tailwind namespace, so like
+   --measure these sit in :root. The gutter is a spacing role too but not a --space-* one and not in em -
+   see GUTTER below. */
+const SPACING = `:root {
+  --space-stack: 0.5em;
+  --space-region: 1.5em;
+  --space-band: 4em;
+}`;
+
+/* The gutter is the horizontal inset holding content off the viewport edge (#9), and the one spacing role
+   measured against the screen rather than the type: it answers to how much room there is, not how large
+   the words are, so it is in rem/vw and never em. A clamp() lets it grow with the viewport with no
+   breakpoint, the device --text-display already uses. Not a --space-* role and no Tailwind namespace, so
+   it sits in :root beside the space roles, read as px-[var(--gutter)]. */
+const GUTTER = `:root {
+  --gutter: clamp(1.5rem, 5vw, 4rem);
+}`;
+
+/* The fold is the least height a first screen takes (CONTEXT.md): measured against the screen not the
+   type, so in vh/rem and never em, in :root beside the gutter with no Tailwind namespace, read as
+   min-h-[var(--fold-height)]. Constraint: the vh component is < 100vh - a fold that exactly fills the
+   screen guarantees top-heaviness, so the next section's hairline must sit just inside it, and the
+   floor is enforced against the library's own value (ADR 0004), never a consumer's. */
+const FOLD = `:root {
+  --fold-height: min(70vh, 40rem);
+}`;
+
+/* Four aspect roles in a @theme block like typography: --aspect-* is a Tailwind 4 namespace, so it
+   generates the aspect-portrait utilities Figure reaches rather than a :root value. Named shapes, not
+   a ladder - ADR 0003/0004 rejected a radius and spacing scale (see SPACING) because a scale lets a
+   component pick a rung with no rule saying which; four shapes with distinct jobs and no ordering do not. */
+const ASPECT = `@theme {
+  --aspect-portrait:  4 / 5;
+  --aspect-square:    1 / 1;
+  --aspect-landscape: 3 / 2;
+  --aspect-wide:     16 / 9;
+}`;
+
+/* The checklist tick's two dimensions are not colours: like the underline and focus-ring dimensions
+   they live in :root only, never @theme inline, so a brand can re-point them. They are named rather
+   than recipe literals because of ADR 0004's test - whether the library sets the property. The tick is
+   drawn as a `::before` pseudo-element, the strongest possible case of an element a consumer cannot
+   reach: no `className` gets near it, so a value overriding it would have to fight a utility class on
+   an element that is not in the tree at all, and the value therefore needs a name. With `rule` that is
+   three names a brand re-points to get a different marker, and no member of Checklist gains a prop. */
+const TICK = `:root {
+  --tick-length: 0.9rem;
+  --tick-thickness: 1px;
+}`;
+
 const toKebabCase = (name: string): string =>
   name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 
@@ -34,21 +193,76 @@ const declarations = (
     .map((name) => `  --color-${toKebabCase(name)}: ${value(name)};`)
     .join('\n');
 
+// The library no longer declares --color-ring but still reads it as a fallback, so a consumer's
+// existing value keeps working; the plain hex in the palette is the default and what the contrast
+// test checks. See docs/adr/0002-focus-ring-token-contract.md.
+const raw = (tokens: PaletteTokens) => (name: string) => {
+  const value = tokens[name as keyof PaletteTokens];
+  return name === 'focusRing' ? `var(--color-ring, ${value})` : value;
+};
+const reference = () => (name: string) => `var(--color-${toKebabCase(name)})`;
+
+// Only the combined tokens.css carries the dark set; this gates it behind .dark and defines dark:.
+const DARK_VARIANT = `/* Dark mode is driven by a \`.dark\` class rather than prefers-color-scheme, so a story or a
+   screenshot can be taken under either theme on demand. */
+@custom-variant dark (&:where(.dark, .dark *));`;
+
+// The @theme inline colour map and every non-colour token block: identical across all three
+// variants, since the map references the role variables :root declares rather than any hex.
+const colourMapAndTail = (): string => `@theme inline {
+${declarations(light, reference())}
+}
+
+/* Motion is not a colour: it is carried in :root only, never mapped into @theme inline. */
+${MOTION}
+
+/* The focus ring's dimensions are not colours either, and sit in :root beside the motion block. */
+${FOCUS_RING}
+
+/* Radius is not a colour either: one token for the corner every control reads, beside the others. */
+${RADIUS}
+
+/* The control minimum width is not a colour either, and sits in :root beside radius. */
+${CONTROL_MIN_WIDTH}
+
+/* The library's underline dimensions are not colours either, and sit in :root beside radius. They are
+   not prose's alone: every Link treatment that draws a line draws it from these (docs/adr/0006). */
+${UNDERLINE}
+
+/* Typography is a set of Tailwind theme namespaces, not colours: its own @theme block generates the
+   utilities, so it is not carried in @theme inline with the palette. */
+${TYPOGRAPHY}
+
+/* The aspect roles are Tailwind theme namespaces like typography, so they take their own @theme block
+   after it and are not carried in @theme inline with the palette. */
+${ASPECT}
+
+/* The reading measure has no Tailwind namespace, so it sits in :root beside radius. */
+${MEASURE}
+
+/* Spacing has no Tailwind namespace either - --spacing is a single base multiplier ADR 0004 forbids
+   re-pointing - so the three roles sit in :root beside the measure. */
+${SPACING}
+
+/* The gutter has no Tailwind namespace either, so it sits in :root beside the space roles. */
+${GUTTER}
+
+/* The fold height has no Tailwind namespace either, so it sits in :root beside the gutter. */
+${FOLD}
+
+/* The checklist tick's dimensions are not colours either, and sit in :root beside the underline block. */
+${TICK}
+`;
+
 /**
- * Renders the stylesheet form of the palette. Shared by the build script and the test that pins
- * `src/tokens.css` to it, so a palette edit that was never regenerated fails the suite instead of
- * silently shipping stale colours.
+ * Renders the combined stylesheet form of the palette: the light set in `:root`, the dark set under
+ * `.dark`, the `dark:` custom variant, then the shared colour map and non-colour tokens. This is
+ * the default `src/tokens.css`, unchanged by issue #62. Shared by the build script and the test that
+ * pins `src/tokens.css` to it, so a palette edit that was never regenerated fails the suite.
  */
-export const renderTokens = (): string => {
-  const raw = (tokens: PaletteTokens) => (name: string) =>
-    tokens[name as keyof PaletteTokens];
-  const reference = () => (name: string) => `var(--color-${toKebabCase(name)})`;
+export const renderTokens = (): string => `${GENERATED_HEADER}
 
-  return `${GENERATED_HEADER}
-
-/* Dark mode is driven by a \`.dark\` class rather than prefers-color-scheme, so a story or a
-   screenshot can be taken under either theme on demand. */
-@custom-variant dark (&:where(.dark, .dark *));
+${DARK_VARIANT}
 
 :root {
 ${declarations(light, raw(light))}
@@ -58,11 +272,34 @@ ${declarations(light, raw(light))}
 ${declarations(dark, raw(dark))}
 }
 
-@theme inline {
-${declarations(light, reference())}
+${colourMapAndTail()}`;
+
+/* The single-theme variants (issue #62) share one shape: the chosen set unconditionally in `:root`,
+   then the shared colour map and non-colour tokens - no `.dark` rule and no `dark:` variant. They
+   differ only in header and which palette set lands in `:root`, so both render through here. */
+const renderSingleTheme = (
+  header: string,
+  tokens: PaletteTokens,
+): string => `${header}
+
+:root {
+${declarations(tokens, raw(tokens))}
 }
 
-/* Motion is not a colour: it is carried in :root only, never mapped into @theme inline. */
-${MOTION}
-`;
-};
+${colourMapAndTail()}`;
+
+/**
+ * Renders the light-only variant (issue #62): the light set in `:root`, no `.dark` rule and no
+ * `dark:` variant, so a light-only consumer's bundle carries no dark theme it cannot remove. Pinned
+ * to `src/tokens.light.css` by the same regeneration test that pins {@link renderTokens}.
+ */
+export const renderLightTokens = (): string =>
+  renderSingleTheme(GENERATED_LIGHT_HEADER, light);
+
+/**
+ * Renders the dark-only variant (issue #62): the dark set in `:root`, ungated since it is the only
+ * theme. A dark-only consumer imports this instead of the default. Pinned to `src/tokens.dark.css`
+ * by the same regeneration test that pins {@link renderTokens}.
+ */
+export const renderDarkTokens = (): string =>
+  renderSingleTheme(GENERATED_DARK_HEADER, dark);

package/src/index.ts

@@ -1,6 +1,30 @@
 import './styles.css';
 
-export type { IButtonProps } from 'Interaction/Button/Button';
+export { Brandmark } from 'Display/Brandmark/Brandmark';
+export { Checklist } from 'Display/Checklist/Checklist';
+export { DefinitionList } from 'Display/DefinitionList/DefinitionList';
+export { Figure } from 'Display/Figure/Figure';
+export { Rail } from 'Display/Rail/Rail';
+export { Table } from 'Display/Table/Table';
+export { Eyebrow } from 'Display/Typography/Eyebrow/Eyebrow';
+export { H1 } from 'Display/Typography/H1/H1';
+export { H2 } from 'Display/Typography/H2/H2';
+export { H3 } from 'Display/Typography/H3/H3';
+export { H4 } from 'Display/Typography/H4/H4';
+export { H5 } from 'Display/Typography/H5/H5';
+export { H6 } from 'Display/Typography/H6/H6';
+export { P } from 'Display/Typography/P/P';
+export { Prose } from 'Display/Typography/Prose/Prose';
 export { Button } from 'Interaction/Button/Button';
+export { Input } from 'Interaction/Input/Input';
+export { Link } from 'Interaction/Link/Link';
+export { TextArea } from 'Interaction/TextArea/TextArea';
+export { Footer } from 'Layout/Footer/Footer';
+export type { FormState } from 'Layout/Form/Form';
+export { Form } from 'Layout/Form/Form';
+export { Header } from 'Layout/Header/Header';
+export { Hero } from 'Layout/Hero/Hero';
+export { PageHead } from 'Layout/PageHead/PageHead';
+export { Section } from 'Layout/Section/Section';
 export type { PaletteTokens } from 'Theme/Palette';
 export { dark, light } from 'Theme/Palette';

package/src/styles.dark.css

@@ -0,0 +1,9 @@
+/* Component-level styles for the design system, dark theme only (issue #62). */
+@import "tailwindcss";
+@import "./tokens.dark.css";
+
+/* Scan the component sources explicitly so their utilities are generated no matter
+   which host imports this stylesheet. Tailwind's automatic content detection is
+   anchored to the consumer and skips node_modules, so a host pulling the components
+   in through a package would otherwise render them unstyled. */
+@source ".";

package/src/styles.light.css

@@ -0,0 +1,9 @@
+/* Component-level styles for the design system, light theme only (issue #62). */
+@import "tailwindcss";
+@import "./tokens.light.css";
+
+/* Scan the component sources explicitly so their utilities are generated no matter
+   which host imports this stylesheet. Tailwind's automatic content detection is
+   anchored to the consumer and skips node_modules, so a host pulling the components
+   in through a package would otherwise render them unstyled. */
+@source ".";

package/src/tokens.css

@@ -14,17 +14,19 @@
   --color-foreground: #0f172a;
   --color-muted: #64748b;
   --color-border: #e2e8f0;
+  --color-control-border: #64748b;
+  --color-rule: #808fa3;
+  --color-backing: #f1f5f9;
   --color-primary: #8b5cf6;
   --color-primary-hover: #7c3aed;
   --color-primary-foreground: #f8fafc;
-  --color-primary-ring: #a78bfa;
   --color-secondary: #0ea5e9;
   --color-secondary-hover: #0284c7;
   --color-secondary-foreground: #f8fafc;
-  --color-secondary-ring: #38bdf8;
   --color-disabled: #94a3b8;
   --color-disabled-hover: #64748b;
-  --color-ring: #94a3b8;
+  --color-focus-ring: var(--color-ring, #475569);
+  --color-link: #2563eb;
   --color-success: #10b981;
   --color-warning: #f59e0b;
   --color-error: #d63384;
@@ -36,17 +38,19 @@
   --color-foreground: #f8fafc;
   --color-muted: #94a3b8;
   --color-border: #334155;
+  --color-control-border: #94a3b8;
+  --color-rule: #5b6a80;
+  --color-backing: #1e293b;
   --color-primary: #7c3aed;
   --color-primary-hover: #8b5cf6;
   --color-primary-foreground: #f8fafc;
-  --color-primary-ring: #a78bfa;
   --color-secondary: #0284c7;
   --color-secondary-hover: #0ea5e9;
   --color-secondary-foreground: #f8fafc;
-  --color-secondary-ring: #38bdf8;
   --color-disabled: #475569;
   --color-disabled-hover: #334155;
-  --color-ring: #64748b;
+  --color-focus-ring: var(--color-ring, #cbd5e1);
+  --color-link: #60a5fa;
   --color-success: #34d399;
   --color-warning: #fbbf24;
   --color-error: #f48fb1;
@@ -58,17 +62,19 @@
   --color-foreground: var(--color-foreground);
   --color-muted: var(--color-muted);
   --color-border: var(--color-border);
+  --color-control-border: var(--color-control-border);
+  --color-rule: var(--color-rule);
+  --color-backing: var(--color-backing);
   --color-primary: var(--color-primary);
   --color-primary-hover: var(--color-primary-hover);
   --color-primary-foreground: var(--color-primary-foreground);
-  --color-primary-ring: var(--color-primary-ring);
   --color-secondary: var(--color-secondary);
   --color-secondary-hover: var(--color-secondary-hover);
   --color-secondary-foreground: var(--color-secondary-foreground);
-  --color-secondary-ring: var(--color-secondary-ring);
   --color-disabled: var(--color-disabled);
   --color-disabled-hover: var(--color-disabled-hover);
-  --color-ring: var(--color-ring);
+  --color-focus-ring: var(--color-focus-ring);
+  --color-link: var(--color-link);
   --color-success: var(--color-success);
   --color-warning: var(--color-warning);
   --color-error: var(--color-error);
@@ -87,3 +93,106 @@
     --motion-duration-color: 0ms;
   }
 }
+
+/* The focus ring's dimensions are not colours either, and sit in :root beside the motion block. */
+:root {
+  --focus-ring-width: 3px;
+  --focus-ring-offset: 2px;
+}
+
+/* Radius is not a colour either: one token for the corner every control reads, beside the others. */
+:root {
+  --radius-control: 0.5rem;
+}
+
+/* The control minimum width is not a colour either, and sits in :root beside radius. */
+:root {
+  --control-min-width: 10.5rem;
+}
+
+/* The library's underline dimensions are not colours either, and sit in :root beside radius. They are
+   not prose's alone: every Link treatment that draws a line draws it from these (docs/adr/0006). */
+:root {
+  --underline-offset: 0.18em;
+  --underline-thickness: 1px;
+  --underline-thickness-hover: 2px;
+}
+
+/* Typography is a set of Tailwind theme namespaces, not colours: its own @theme block generates the
+   utilities, so it is not carried in @theme inline with the palette. */
+@theme {
+  /* Both faces default to inherit, so the library ships no @font-face and no face and a one-face
+     consumer renders as today. --font-primary is carried by content, --font-secondary by labels; a
+     component sets font-variant-numeric: tabular-nums only on a --font-primary carrying tnum and
+     font-variant-caps: small-caps only on a --font-secondary carrying smcp - both fail silently otherwise. */
+  --font-primary: inherit;
+  --font-secondary: inherit;
+
+  /* Type roles, not a scale: one role per job, so a component asks for what its text is, never a rung.
+     display > title > subtitle are the three heading steps H1-H3 bind to; H4-H6 share body and split
+     by weight, so there is no fourth role. display is the hero and must out-scale every subpage head. */
+  --text-display: clamp(3rem, 7vw, 6rem);
+  --leading-display: 1.05;
+  --text-title: clamp(2.25rem, 5vw, 4.25rem);
+  --leading-title: 1.1;
+  --text-subtitle: clamp(1.5rem, 3vw, 2.25rem);
+  --leading-subtitle: 1.2;
+
+  /* The reading block's opening paragraph (Prose #21): sized above body and below subtitle, led
+     tighter than body's 1.6 but not as tight as a heading's 1.2 - it is running text, not a head, so
+     it keeps running-text leading. A role, not a rung: one lede per block, nothing to choose. Reusing
+     subtitle was rejected in ADR 0004 - it welds the lede's size to H3's and its leading to a head's. */
+  --text-lede: 1.25rem;  /* 20px */
+  --leading-lede: 1.4;
+  --text-body: 1.0625rem;  /* 17px */
+  --leading-body: 1.6;
+  --text-small: 0.9375rem;  /* 15px floor: below it tabular figures stop comparing column to column */
+  --text-label: 0.8125rem;  /* 13px floor: below it the tracking reads as damage, not a device */
+
+  /* Two quantities on one property that must not collapse: --tracking-label is a fixed letter-spaced
+     style, --tracking-optical a correction that varies with size. The names say which is which, so the
+     distinction survives without the ADR in hand. Scope: the title role and above - H1, H2 and the page
+     head's h1 - and never below it, where the correction would read as damage. See the ADR. */
+  --tracking-label: 0.14em;
+  --tracking-optical: -0.02em;
+}
+
+/* The aspect roles are Tailwind theme namespaces like typography, so they take their own @theme block
+   after it and are not carried in @theme inline with the palette. */
+@theme {
+  --aspect-portrait:  4 / 5;
+  --aspect-square:    1 / 1;
+  --aspect-landscape: 3 / 2;
+  --aspect-wide:     16 / 9;
+}
+
+/* The reading measure has no Tailwind namespace, so it sits in :root beside radius. */
+:root {
+  --measure: 66ch;
+  --measure-display: 36ch;
+  --measure-wide: 72ch;
+}
+
+/* Spacing has no Tailwind namespace either - --spacing is a single base multiplier ADR 0004 forbids
+   re-pointing - so the three roles sit in :root beside the measure. */
+:root {
+  --space-stack: 0.5em;
+  --space-region: 1.5em;
+  --space-band: 4em;
+}
+
+/* The gutter has no Tailwind namespace either, so it sits in :root beside the space roles. */
+:root {
+  --gutter: clamp(1.5rem, 5vw, 4rem);
+}
+
+/* The fold height has no Tailwind namespace either, so it sits in :root beside the gutter. */
+:root {
+  --fold-height: min(70vh, 40rem);
+}
+
+/* The checklist tick's dimensions are not colours either, and sit in :root beside the underline block. */
+:root {
+  --tick-length: 0.9rem;
+  --tick-thickness: 1px;
+}