@happyvertical/smrt-ui 0.55.16 → 0.55.18

package/dist/svelte/playground/StylelessPreview.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+import Alert from '../../components/feedback/Alert.svelte';
+import Input from '../../components/forms/Input.svelte';
+import Select from '../../components/forms/Select.svelte';
+import Tabs from '../../components/nav/Tabs.svelte';
+import Badge from '../../components/ui/Badge.svelte';
+import Button from '../../components/ui/Button.svelte';
+import Card from '../../components/ui/Card.svelte';
+import Chip from '../../components/ui/Chip.svelte';
+import unstyledCss from '../../styles/unstyled.css?inline';
+
+// Native checkbox, outside the catalogue, so the toggle itself is never stripped.
+let styleless = $state(false);
+let active = $state('overview');
+
+// Svelte does not interpolate text inside a style element, so the stylesheet is
+// appended to the document head imperatively while the toggle is on.
+$effect(() => {
+  if (!styleless) return;
+  const style = document.createElement('style');
+  style.setAttribute('data-smrt-styleless', '');
+  style.textContent = unstyledCss;
+  document.head.appendChild(style);
+  return () => style.remove();
+});
+const tabs = [
+  { id: 'overview', label: 'Overview' },
+  { id: 'activity', label: 'Activity' },
+  { id: 'settings', label: 'Settings' },
+];
+</script>
+
+
+
+<div class="workbench">
+  <header>
+    <div>
+      <p class="eyebrow">Styleless mode</p>
+      <h4>Layout kept, look removed</h4>
+    </div>
+    <label class="toggle">
+      <input type="checkbox" bind:checked={styleless} />
+      Apply unstyled.css
+    </label>
+  </header>
+
+  <p class="note">
+    With the toggle on, every component below keeps its layout and loses its
+    themed look. The page chrome is not a smrt component, so it is unaffected.
+  </p>
+
+  <div class="catalogue">
+    <section>
+      <h5>Buttons and badges</h5>
+      <div class="row">
+        <Button>Primary</Button>
+        <Button variant="secondary">Secondary</Button>
+        <Badge>Draft</Badge>
+        <Chip label="Filter" />
+      </div>
+    </section>
+
+    <section>
+      <h5>Card</h5>
+      <Card>
+        {#snippet header()}<strong>Workspace</strong>{/snippet}
+        <p>Card body text keeps its spacing and flow.</p>
+        {#snippet footer()}<Button size="sm">Open</Button>{/snippet}
+      </Card>
+    </section>
+
+    <section>
+      <h5>Alert</h5>
+      <Alert title="Information">The index refreshes in the background.</Alert>
+    </section>
+
+    <section>
+      <h5>Form controls</h5>
+      <div class="row">
+        <Input name="styleless-name" placeholder="Name" />
+        <Select name="styleless-role">
+          <option value="owner">Owner</option>
+          <option value="member">Member</option>
+        </Select>
+      </div>
+    </section>
+
+    <section>
+      <h5>Tabs</h5>
+      <Tabs {tabs} {active} onchange={(id) => (active = id)} />
+    </section>
+  </div>
+</div>
+
+<style>
+@layer smrt.reset, smrt.structure, smrt.theme;
+@layer smrt.theme {
+  .workbench { display: grid; gap: var(--smrt-spacing-6); color: var(--smrt-color-on-surface); }
+  header { display: flex; align-items: center; justify-content: space-between; gap: var(--smrt-spacing-3); padding-bottom: var(--smrt-spacing-4); border-bottom: 1px solid var(--smrt-color-outline-variant); }
+  h4, h5, p { margin: 0; }
+  h4 { font: var(--smrt-typography-headline-small-font); }
+  h5 { margin-bottom: var(--smrt-spacing-3); font: var(--smrt-typography-title-medium-font); }
+  .eyebrow { color: var(--smrt-color-primary); font: var(--smrt-typography-label-small-font); letter-spacing: .1em; text-transform: uppercase; }
+  .note { color: var(--smrt-color-on-surface-variant); font: var(--smrt-typography-body-medium-font); }
+  .toggle { display: inline-flex; align-items: center; gap: var(--smrt-spacing-2); }
+  .catalogue { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: var(--smrt-spacing-5); }
+  .catalogue > section { display: grid; align-content: start; gap: var(--smrt-spacing-2); }
+  .row { display: flex; flex-wrap: wrap; align-items: center; gap: var(--smrt-spacing-3); }
+}
+</style>

package/dist/svelte/playground/StylelessPreview.svelte.d.ts

@@ -0,0 +1,4 @@
+declare const StylelessPreview: import("svelte").Component<Record<string, never>, {}, "">;
+type StylelessPreview = ReturnType<typeof StylelessPreview>;
+export default StylelessPreview;
+//# sourceMappingURL=StylelessPreview.svelte.d.ts.map

package/dist/svelte/playground/StylelessPreview.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StylelessPreview.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/playground/StylelessPreview.svelte.ts"],"names":[],"mappings":"AA+GA,QAAA,MAAM,gBAAgB,2DAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/svelte/playground.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../../src/svelte/playground.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYA,wBAyGE"}
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../../src/svelte/playground.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,wBAmHE"}

package/dist/svelte/playground.js

@@ -6,6 +6,7 @@ const loadCollections = () => import('./playground/CollectionsPreview.svelte');
 const loadCalendar = () => import('./playground/CalendarPreview.svelte');
 const loadCapture = () => import('./playground/CapturePreview.svelte');
 const loadPermissionPicker = () => import('./playground/PermissionPickerPreview.svelte');
+const loadStyleless = () => import('./playground/StylelessPreview.svelte');
 export default {
     packageName: '@happyvertical/smrt-ui',
     displayName: 'UI Foundation',
@@ -100,5 +101,14 @@ export default {
             tags: ['forms', 'camera', 'signature', 'files'],
             modes: { mock: { label: 'Interactive' } },
         },
+        {
+            id: 'styleless-mode',
+            title: 'Styleless Mode',
+            description: 'Toggle unstyled.css across the catalogue: components keep layout and drop their themed look, so consumer CSS can restyle them.',
+            loadComponent: loadStyleless,
+            order: 10,
+            tags: ['styling', 'styleless', 'layers', 'restyling'],
+            modes: { mock: { label: 'Interactive' } },
+        },
     ],
 };

package/dist/test-support/setup.js

@@ -40,3 +40,12 @@ if (typeof HTMLDialogElement !== 'undefined') {
         };
     }
 }
+// jsdom has no Web Animations API. Svelte's `animate:` directive (list FLIP)
+// and transitions call `element.getAnimations()`; an empty list is accurate
+// here because jsdom never runs CSS animations.
+if (typeof Element !== 'undefined' &&
+    typeof Element.prototype.getAnimations !== 'function') {
+    Element.prototype.getAnimations = function getAnimations() {
+        return [];
+    };
+}

package/dist/theme/ThemeProvider.svelte

@@ -200,8 +200,11 @@ $effect(() => {
 </div>
 
 <style>
+@layer smrt.reset, smrt.structure, smrt.theme;
+@layer smrt.theme {
   .smrt-theme-root {
     /* Ensure theme variables cascade to all children */
     display: contents;
   }
+}
 </style>

package/dist/themes/CUSTOM_THEME_GUIDE.md

@@ -318,6 +318,46 @@ npm install ./packages/my-brand-theme
 <ThemeSwitcher variant="segmented" />
 ```
 
+## Required Tokens
+
+A theme is complete only when it defines every token the components consume. The list below is generated from the `var(--smrt-*)` references in the packages' `.svelte` files; `src/themes/__tests__/required-tokens.test.ts` asserts every preset and `createTheme()` output defines each one.
+
+<!-- smrt-required-tokens:start -->
+
+### Required tokens (generated)
+
+Every theme (presets and `createTheme()` output) must define these names. Generated by
+`scripts/generate-smrt-required-tokens.mjs`; do not edit by hand. Component-private
+`--smrt-<component>-*` knobs are excluded.
+
+- **color** (40): `--smrt-color-background`, `--smrt-color-error`, `--smrt-color-error-container`, `--smrt-color-inverse-on-surface`, `--smrt-color-inverse-surface`, `--smrt-color-on-background`, `--smrt-color-on-error`, `--smrt-color-on-error-container`, `--smrt-color-on-primary`, `--smrt-color-on-primary-container`, `--smrt-color-on-secondary`, `--smrt-color-on-secondary-container`, `--smrt-color-on-success-container`, `--smrt-color-on-surface`, `--smrt-color-on-surface-variant`, `--smrt-color-on-tertiary`, `--smrt-color-on-tertiary-container`, `--smrt-color-on-warning-container`, `--smrt-color-outline`, `--smrt-color-outline-variant`, `--smrt-color-primary`, `--smrt-color-primary-container`, `--smrt-color-scrim`, `--smrt-color-secondary`, `--smrt-color-secondary-container`, `--smrt-color-shadow`, `--smrt-color-success`, `--smrt-color-success-container`, `--smrt-color-surface`, `--smrt-color-surface-container`, `--smrt-color-surface-container-high`, `--smrt-color-surface-container-highest`, `--smrt-color-surface-container-low`, `--smrt-color-surface-container-lowest`, `--smrt-color-surface-dim`, `--smrt-color-surface-variant`, `--smrt-color-tertiary`, `--smrt-color-tertiary-container`, `--smrt-color-warning`, `--smrt-color-warning-container`
+- **control** (4): `--smrt-control-height`, `--smrt-control-height-small`, `--smrt-control-radius`, `--smrt-control-radius-small`
+- **duration** (6): `--smrt-duration-fast`, `--smrt-duration-medium1`, `--smrt-duration-normal`, `--smrt-duration-short2`, `--smrt-duration-short3`, `--smrt-duration-short4`
+- **easing** (3): `--smrt-easing-emphasized`, `--smrt-easing-emphasized-decelerate`, `--smrt-easing-standard`
+- **elevation** (5): `--smrt-elevation-1`, `--smrt-elevation-2`, `--smrt-elevation-3`, `--smrt-elevation-4`, `--smrt-elevation-5`
+- **focus** (3): `--smrt-focus-ring-color`, `--smrt-focus-ring-offset`, `--smrt-focus-ring-width`
+- **font** (2): `--smrt-font-family`, `--smrt-font-family-mono`
+- **glass** (4): `--smrt-glass-blur`, `--smrt-glass-saturation`, `--smrt-glass-surface`, `--smrt-glass-surface-strong`
+- **hairline** (4): `--smrt-hairline`, `--smrt-hairline-color`, `--smrt-hairline-strong`, `--smrt-hairline-strong-color`
+- **inset** (1): `--smrt-inset-highlight`
+- **radius** (11): `--smrt-radius-2xl`, `--smrt-radius-extra-large`, `--smrt-radius-extra-small`, `--smrt-radius-full`, `--smrt-radius-large`, `--smrt-radius-lg`, `--smrt-radius-md`, `--smrt-radius-medium`, `--smrt-radius-sm`, `--smrt-radius-small`, `--smrt-radius-xl`
+- **scrollbar** (2): `--smrt-scrollbar-thumb`, `--smrt-scrollbar-track`
+- **spacing** (19): `--smrt-spacing-0_5`, `--smrt-spacing-1`, `--smrt-spacing-10`, `--smrt-spacing-11`, `--smrt-spacing-12`, `--smrt-spacing-1_5`, `--smrt-spacing-2`, `--smrt-spacing-2xl`, `--smrt-spacing-3`, `--smrt-spacing-3xl`, `--smrt-spacing-4`, `--smrt-spacing-5`, `--smrt-spacing-6`, `--smrt-spacing-8`, `--smrt-spacing-lg`, `--smrt-spacing-md`, `--smrt-spacing-sm`, `--smrt-spacing-xl`, `--smrt-spacing-xs`
+- **state** (5): `--smrt-state-disabled`, `--smrt-state-dragged`, `--smrt-state-hover`, `--smrt-state-pressed`, `--smrt-state-selected`
+- **surface** (6): `--smrt-surface-control`, `--smrt-surface-ground`, `--smrt-surface-overlay`, `--smrt-surface-panel`, `--smrt-surface-raised`, `--smrt-surface-sunken`
+- **touch** (1): `--smrt-touch-target-min`
+- **typography** (56): `--smrt-typography-body-large-font`, `--smrt-typography-body-large-line-height`, `--smrt-typography-body-large-size`, `--smrt-typography-body-large-tracking`, `--smrt-typography-body-medium-font`, `--smrt-typography-body-medium-line-height`, `--smrt-typography-body-medium-size`, `--smrt-typography-body-medium-tracking`, `--smrt-typography-body-medium-weight`, `--smrt-typography-body-small-font`, `--smrt-typography-body-small-line-height`, `--smrt-typography-body-small-size`, `--smrt-typography-body-small-weight`, `--smrt-typography-display-medium-line-height`, `--smrt-typography-display-medium-size`, `--smrt-typography-display-small-size`, `--smrt-typography-headline-large-line-height`, `--smrt-typography-headline-large-size`, `--smrt-typography-headline-large-weight`, `--smrt-typography-headline-medium-line-height`, `--smrt-typography-headline-medium-size`, `--smrt-typography-headline-medium-weight`, `--smrt-typography-headline-small-font`, `--smrt-typography-headline-small-line-height`, `--smrt-typography-headline-small-size`, `--smrt-typography-headline-small-weight`, `--smrt-typography-label-large-font`, `--smrt-typography-label-large-size`, `--smrt-typography-label-large-tracking`, `--smrt-typography-label-large-weight`, `--smrt-typography-label-medium-font`, `--smrt-typography-label-medium-size`, `--smrt-typography-label-medium-tracking`, `--smrt-typography-label-medium-weight`, `--smrt-typography-label-small-font`, `--smrt-typography-label-small-line-height`, `--smrt-typography-label-small-size`, `--smrt-typography-label-small-tracking`, `--smrt-typography-label-small-weight`, `--smrt-typography-title-large-font`, `--smrt-typography-title-large-line-height`, `--smrt-typography-title-large-size`, `--smrt-typography-title-medium-font`, `--smrt-typography-title-medium-font-family`, `--smrt-typography-title-medium-line-height`, `--smrt-typography-title-medium-size`, `--smrt-typography-title-medium-tracking`, `--smrt-typography-title-medium-weight`, `--smrt-typography-title-small-font`, `--smrt-typography-title-small-size`, `--smrt-typography-title-small-tracking`, `--smrt-typography-title-small-weight`, `--smrt-typography-weight-bold`, `--smrt-typography-weight-medium`, `--smrt-typography-weight-normal`, `--smrt-typography-weight-semibold`
+- **z** (7): `--smrt-z-index-dialog`, `--smrt-z-index-dropdown`, `--smrt-z-index-modal`, `--smrt-z-index-overlay`, `--smrt-z-index-sticky`, `--smrt-z-index-toast`, `--smrt-z-index-tooltip`
+
+<!-- smrt-required-tokens:end -->
+
+## Runtime overrides
+
+`ThemeProvider` layers user choices over a theme without touching the theme itself:
+`borderRadius` (control radius tokens), `primaryColor` (full derived primary set, also
+available as `derivePrimaryOverrides(color, scheme)`), `density` and `contrast`. See the
+ThemeProvider props table in the README for the exact behaviour.
+
 ## Best Practices
 
 1. **Extend a base theme**: Start with `extend: 'material'` or another base to get sensible defaults

package/dist/themes/README.md

@@ -74,6 +74,9 @@ const autoTheme = createThemeFromColor('#6366f1', 'indigo', 'Indigo Theme');
 registerTheme(autoTheme);
 ```
 
+Generated dark themes use tonal primary colors so primary text and icon
+containers remain readable even when the brand seed is very dark.
+
 ### Full Custom Theme with All Options
 
 ```typescript
@@ -302,8 +305,29 @@ import '@happyvertical/smrt-ui/themes/styles/happyvertical.css';
 | `borderRadius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Border radius scale |
 | `overrides` | `Record<string, string>` | `{}` | Custom CSS variable overrides |
 | `persist` | `boolean` | `true` | Persist to localStorage |
+| `density` | `'comfortable' \| 'touch'` | - | Default control target size (`--smrt-control-target-min`); persisted |
+| `contrast` | `'auto' \| 'standard' \| 'more'` | `'auto'` | `auto` follows `prefers-contrast: more`; persisted when explicit |
 | `storageKey` | `string` | `'smrt-theme'` | localStorage key |
 
+Behaviour notes (state exposed on context: `contrast`, `isChangingScheme`):
+
+- `borderRadius` other than `md` is emitted inline as `--smrt-control-radius` /
+  `--smrt-control-radius-small` (one scale step smaller for the small radius);
+  `md` leaves the preset's own control radius in place. The generic
+  `--smrt-radius-*` scale is not changed.
+- `primaryColor` emits the whole derived set for the resolved scheme through
+  `derivePrimaryOverrides(color, scheme)` (also exported): `color-primary`, `on-primary`
+  (best of white/black), `primary-container`, `on-primary-container`, `inverse-primary`,
+  and the focus ring, accent, caret and selection tokens.
+- After the resolved scheme changes post-mount, `data-smrt-theme-changing` is set on
+  the root and `<html>` for one `--smrt-duration-scheme`, so styles can crossfade.
+  Never on first paint; skipped under `prefers-reduced-motion: reduce`.
+- Contrast: `data-contrast="standard|more|forced"` on `<html>` and the root;
+  `forced-colors: active` also sets `data-forced-colors`. Contract for components in
+  forced-colors mode: do not paint over system colours, hairlines become `CanvasText`
+  and focus rings `Highlight` (component side: #3867 follow-up).
+- `themeScript()` stamps `data-contrast` and (when persisted) `data-density` pre-paint.
+
 ## Theme Switching
 
 Use the context to switch themes programmatically:
@@ -605,6 +629,133 @@ All themes expose CSS custom properties:
 --smrt-easing-standard
 ```
 
+### One vocabulary: `--smrt-*` only
+
+`--smrt-*` is the only token namespace. Component CSS consumes these tokens and
+nothing else; the legacy `--color-*`, `--spacing-*`, `--radius-*`, `--md-sys-*`
+families were removed (issue #3822). Three rules follow:
+
+- **Consume a token, don't invent one.** Use `var(--smrt-color-primary)` etc. Hard
+  colour or spacing literals belong in a theme, not a component.
+- **A component-private variable is `--smrt-<component>-<name>`**, declared on the
+  component root (for example `--smrt-toast-viewport-inset`). A parent or app may set
+  it. It is not a theme token and should not be read from outside the component.
+- **Overrides go through a theme or a documented hook**, never a `:global` rule or
+  `!important`. Unlayered app CSS still wins over the component's own styles.
+
+`packages/smrt-ui/src/styles/tokens.css` defines the theme-invariant baseline only
+(spacing, radius, duration, touch targets). Colour and typography come from a theme.
+
+The lint gate `scripts/check-smrt-token-vocabulary.mjs` runs in `pnpm lint` and fails
+on any custom property outside `--smrt-*` in `packages/*/src`. The one-time rewrite
+was `scripts/codemod-smrt-tokens.mjs`; it is idempotent, so re-run it after a rebase
+instead of hand-merging renamed names.
+
+### Premium baseline token vocabulary
+
+Every preset and every `createTheme()` result defines all of these in both schemes
+(sections of `Theme` in `types.ts`; defaults derived in `derive.ts`; emitted by
+`generateThemeVariables`). Themes and presets define them; **components only consume
+them**. Do not redeclare a theme token on a component root (CSS or `style:`): the
+required-tokens scanner (`scripts/smrt-token-scan-lib.mjs`) treats any `--smrt-*` name
+a component defines on its own root as component-private and drops it from the required
+list repo-wide. A per-variant override uses a component-prefixed name that falls back to
+the theme token, for example `background: color-mix(in srgb, currentColor
+calc(var(--smrt-button-state-hover, var(--smrt-state-hover)) * 100%), transparent)`.
+
+| Token | Meaning | Consumed by |
+| --- | --- | --- |
+| `--smrt-surface-ground` | Page ground | `body`/shell background |
+| `--smrt-surface-panel` | Cards, sidebars, panels on the ground | `background` of Card, sidebars, header, footer |
+| `--smrt-surface-control` | Input and control fill | `background` of Input, Select, Textarea, Button (outlined/tonal) |
+| `--smrt-surface-raised` | Menus, popovers, dialogs above panels | `background` of overlays |
+| `--smrt-surface-sunken` | Wells and recessed regions | `background` of tables headers, code, inset areas |
+| `--smrt-surface-overlay` | Modal scrim | `background` of Modal/Drawer backdrops |
+| `--smrt-hairline-color` / `-strong-color` | Quiet and strong edge colours | `border-color`, `outline-color`, dividers |
+| `--smrt-hairline` / `--smrt-hairline-strong` | `1px solid` edge shorthands | `border`, `border-top` etc. on panels (quiet) and controls (strong) |
+| `--smrt-inset-highlight` | Top inner light line (`none` on light) | `box-shadow` (layer with an elevation) on raised dark surfaces |
+| `--smrt-state-{hover,pressed,selected,focus,dragged,disabled}` | Unitless state-layer opacities, 0 to 1 | Mix percentage of a state overlay (`calc(var(--smrt-state-hover) * 100%)`); `disabled` as `opacity` |
+| `--smrt-shadow-color` | `rgb(r g b)` shadow base, per scheme | `box-shadow` colour: `rgb(from var(--smrt-shadow-color) r g b / 0.2)` |
+| `--smrt-elevation-0..5` | Existing shadow scale | `box-shadow` |
+| `--smrt-control-radius` / `-radius-small` | Control corner radii | `border-radius` of controls |
+| `--smrt-control-height` / `-height-small` | Control heights | `min-height`/`block-size` of controls |
+| `--smrt-control-weight` | Control label weight | `font-weight` of buttons and inputs |
+| `--smrt-control-border` | Control edge shorthand (`var(--smrt-hairline-strong)`) | `border` of controls |
+| `--smrt-control-target-min` | Density-driven minimum hit size (set by ThemeProvider `density`) | `min-height`/`min-width` of interactive controls |
+| `--smrt-control-hit-size` | Hit area of small icon controls | `inline-size`/`block-size` of icon buttons |
+| `--smrt-focus-ring-{color,width,offset}` | Focus indicator | `outline: var(--smrt-focus-ring-width) solid var(--smrt-focus-ring-color)`, `outline-offset` on `:focus-visible` |
+| `--smrt-accent-color` | Native control accent | `accent-color` (checkbox, radio, range, date pickers) |
+| `--smrt-selection-{background,color}` | Text selection | `::selection` |
+| `--smrt-caret-color` | Text caret | `caret-color` |
+| `--smrt-scrollbar-{thumb,track}` | Scrollbar colours | `scrollbar-color: thumb track` |
+| `--smrt-glass-blur` / `-saturation` | Backdrop filter amounts (`0px`/`100%` outside Glass) | `backdrop-filter: blur(var(--smrt-glass-blur)) saturate(var(--smrt-glass-saturation))` |
+| `--smrt-glass-surface` / `-surface-strong` | Translucent (Glass) or opaque surface fills; opacity is part of the colour | `background` of floating chrome and overlays |
+| `--smrt-glass-border` | Glass edge colour | `border-color` of glass surfaces |
+| `--smrt-duration-scheme` | Scheme crossfade duration | `transition-duration` when the colour scheme changes |
+| `--smrt-font-feature-settings` | OpenType features (`"tnum" 1, "cv11" 1` on Inter presets) | `font-feature-settings` on the root and numeric cells |
+
+#### Semantic info colour
+
+`ColorPalette` carries an info family beside success, warning and error:
+`--smrt-color-info`, `--smrt-color-on-info`, `--smrt-color-info-container` and
+`--smrt-color-on-info-container`. Presets without a distinct information hue define
+it as their tertiary family (Material, Glass, Studio, Day Shift); **smrt** uses a
+steel blue (`#2c6a96` light, `#6fa8d6` dark) so Information no longer shares amber
+with Warning. `createTheme()` follows a supplied `tertiary` unless `info` is also
+given. Components that show information status (for example `Alert` `variant="info"`)
+should consume these, not tertiary.
+
+#### Preset identities on the baseline
+
+| Preset | Dark ladder (ground / panel / control / raised) | Depth | State layers (hover / pressed / selected) | Controls |
+| --- | --- | --- | --- | --- |
+| Material | `#121316` / `#1b1c20` / `#26282c` / `#34363a` (M3 tonal, no borders needed; control border is transparent) | contact + ambient; dark adds the inset highlight | .08 / .12 / .12 | radius md / sm, 2.75rem |
+| Glass | `#0b0b0f` ground; panel 72% and popover 88% frosted glass, input a recessed 28% black well; blur 20px, saturation 180% | softest, widest ambient | .10 / .14 / .14 | radius lg / md, 2.75rem |
+| Studio | `#131416` / `#131416` / `#1c1d20` / `#292a2d` (flat, crisp hairlines, panel equals ground) | elevation 1 is the hairline; tight shadows | .06 / .10 / .10 | radius 0.375rem / sm, 2.5rem |
+| smrt | `#0b0c0e` / `#121417` / `#181b1f` / `#1d2126` (instrument dark, amber signal, steel-blue info) | elevation 1 is the hairline; calm two-layer shadows (no far-spread) | .10 / .16 / .14 | radius sm, 2.5rem |
+| Day Shift | enamel ground, faceplate panel, control a hair lighter, raised = faceplate; hairlines are the bezel | elevation 1 is the bezel hairline; minimal | .06 / .10 / .10 | radius md (6px) / sm, 2.5rem |
+
+Elevation 2 to 5 are two-layer shadows built with `shadow()` in `shared.ts`: a contact
+layer (`0 1px 2px`) plus an ambient layer (`0 Npx Mpx` with negative spread), both
+`color-mix`ed from `--smrt-shadow-color`. Dark schemes prepend
+`var(--smrt-inset-highlight)`. Weight is 500 on every preset. Native chrome follows the
+baseline: accent and caret are primary, selection is the primary container, and the
+scrollbar thumb is the strong hairline over a transparent track.
+
+`--smrt-glass-border-opacity` and `--smrt-glass-background-opacity` are deprecated: still emitted (from `GlassEffects.borderOpacity`/`backgroundOpacity`, `1` when unset) for one release and removed in the next minor; the former
+tokens, and the ThemeProvider-local `--smrt-glass-surface`/`--smrt-glass-border`,
+were folded into the glass surface colours above.
+
+### Typography
+
+`themes/styles/base.css` (import once at the app entry) maps headings to type roles
+inside `@layer smrt.structure`, scoped under `body` and `.smrt-theme-root`, so presets'
+display faces reach plain markup. Hosts restyle with unlayered CSS.
+
+| Element | Role |
+| --- | --- |
+| `h1` | `display-small` |
+| `h2` | `headline-large` |
+| `h3` | `headline-medium` |
+| `h4` | `headline-small` |
+| `h5` | `title-large` |
+| `h6` | `title-medium` |
+
+Each heading takes `font-family`, `font-size`, `line-height`, `font-weight` and
+`letter-spacing` from the role's typography tokens (for example `--smrt-typography-headline-large-size`), and a `margin-block` from
+`--smrt-spacing-*` (first children lose the top margin). Utilities
+`.smrt-{display,headline,title,body,label}-{large,medium,small}` apply the same five
+properties to any element.
+
+Tabular figures: the root sets `font-feature-settings: var(--smrt-font-feature-settings)`,
+and `table`, `time`, `[data-smrt-component="DataTable"]`, `[data-smrt-component="Badge"]`
+and `.smrt-tabular` set `font-variant-numeric: tabular-nums`.
+
+Preset rhythm: display tracking tightens with size (about -0.02em at display, -0.01em at
+headline, 0 at title), labels weigh 500 (Day Shift keeps its documented bold B612 labels),
+body is 400, and display plus headline roles use the preset's display face where it has one
+(smrt: Space Grotesk; Day Shift: its documented stack).
+
 ## Advanced Usage
 
 ### Build-Time Theming