create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/src/styles/tokens.css

@@ -0,0 +1,600 @@
+/* ============================================================================
+ * Design tokens — nova · Direction B "Refined Minimal Commerce"
+ *
+ * @tanqory/nova-ui copy. Started as themes/nova/assets/tokens.css (the
+ * approved, gate-checked implementation of Nova 01) so the lab and the
+ * storefront share ONE styling system. Once the storefront consumes nova-ui,
+ * this file is the one to edit and the theme's copy goes away.
+ *
+ * SOURCE OF TRUTH: the approved Claude Design package in `design/`
+ * (`Nova 01 Style System.dc.html`, package 2026-09-27). Values here are
+ * transcribed from its `renderVals()` tables — `tokens`, `typeScale`, `radii`,
+ * `radiusMap`, `gaps`, `sectionSpace`, `containers`, `ratios`, `motion`,
+ * `dark`. Do not "improve" them — change the design first.
+ *
+ * Quiet confidence: neutral #FFFFFF / #111111, one family (Geist), one accent —
+ * the merchant's. Product imagery is the only saturated thing on the page.
+ *
+ * Four rules the whole system leans on:
+ *   1. HIERARCHY BEFORE CHROME. Type → space → image → surface → border →
+ *      shadow. Cards are un-bordered by default; shadows exist only for things
+ *      that float over content (popover, drawer, modal, floating bar).
+ *   2. SEMANTIC, NEVER RAW. Sections pick a role/preset; they never invent a
+ *      colour, a width or a spacing value. If a value has no token, add one.
+ *   3. PRIMARY IS THE MERCHANT'S. The brand slot moves Primary + its derived
+ *      hover/active/contrast, selected-variant outline and link hover. The
+ *      FOCUS RING IS NEVER THE BRAND (#0B57D0 fixed) so it cannot vanish into
+ *      a brand fill. Neutrals, feedback colours and borders stay fixed.
+ *   4. BUILT TO BE CONFIGURED. Every default holds at the extremes of the
+ *      global settings (pill + uppercase + large scale, and the opposite).
+ *
+ * NAMING CONTRACT: `--color-*`, `--space-*` and `--z-*` are consumed by the AI
+ * theme generator (ai-api `dna-storefront`, which writes `ai-tokens.css`).
+ * Those prefixes must not be renamed without coordinating with that generator.
+ *
+ * Name notes (design → code, recorded in docs/DESIGN-GAPS.md):
+ *   design `--color-border-strong` (#111, selected/emphasis) = code
+ *   `--color-border-emphasis`; design `--color-border-input` (#8A8A88, the
+ *   3:1 control boundary) = code `--color-border-strong` (+ the alias
+ *   `--color-border-input`). The code names predate the package and are read
+ *   in ~200 rules; the roles are identical.
+ * ============================================================================ */
+
+:root {
+  /* ── Colour roles ──────────────────────────────────────────────────────
+   * `--color-brand*` is the merchant slot; everything else is fixed.
+   */
+
+  /* Brand slot — the one colour a merchant owns. Accepts hex or oklch().
+     hover = mix(brand, black 12%), active = mix(brand, black 22%) — the
+     defaults below are those mixes of #111111; lib/theme-settings.ts derives
+     them for any other brand colour. */
+  --color-brand: #111111;
+  --color-brand-hover: #2e2e2e;
+  --color-brand-active: #000000;
+  /* Label colour on a brand fill: the better of #FFF / #111 (derived). */
+  --color-brand-contrast: #ffffff;
+
+  /* Primary (solid) button. By default it IS the brand colour (design:
+     "--color-button-primary-bg → --color-brand"). Theme settings → Accent
+     re-points all five at once, with label colours chosen for AA on each
+     shade (lib/theme-settings.ts). */
+  --color-button: var(--color-brand);
+  --color-button-text: var(--color-brand-contrast);
+  --color-button-hover: var(--color-brand-hover);
+  --color-button-hover-text: var(--color-brand-contrast);
+  --color-button-active: var(--color-brand-active);
+  /* Sticky header backdrop; follows the page background in either scheme. */
+  --header-bg: color-mix(in srgb, var(--color-bg) 86%, transparent);
+
+  /* Ink — three rungs, all ≥ 4.5:1 on every light surface. */
+  --color-fg: #111111;          /* Text Primary — 18.9:1 */
+  /* Design prints #5E5E5C / #737371 beside the roles "≥ 7:1" and "≥ 4.5:1";
+     those hexes measure 6.5:1 and 4.3:1 on the muted surface. Roles are the
+     contract (tests/contrast-and-shape.test.ts), so both are the lightest
+     neutral that clears the role on every light surface. */
+  --color-fg-muted: #4f4f4d;    /* Supporting copy, meta — ≥ 7:1 everywhere */
+  --color-fg-subtle: #6c6c6a;   /* Placeholder, disabled label — ≥ 4.5:1 everywhere */
+  --color-fg-inverse: #ffffff;
+
+  /* Surfaces */
+  --color-bg: #ffffff;              /* page — pure white; the brand tints it, not us */
+  --color-bg-muted: #f4f4f3;        /* chips, alternate sections, panels, skeletons */
+  --color-bg-elevated: #ffffff;     /* drawers, modals, popovers */
+  --color-bg-inverse: #111111;      /* inverse sections, tooltip, footer */
+  /* Tile behind product media, independent of section backgrounds, so a
+     white-background packshot can sit on a white page. (NEW in B.) */
+  --color-media-bg: #f4f4f3;
+  --color-skeleton: #f0f0ee;       /* Nova 14 · 14.2 skeleton blocks */
+
+  /* Lines */
+  --color-border: #e8e8e6;          /* decorative dividers only */
+  --color-border-strong: #8a8a88;   /* input & control boundary — ≥ 3:1 */
+  --color-border-input: var(--color-border-strong);
+  --color-border-emphasis: #111111; /* selected, active, emphasis */
+  --color-border-inverse: rgba(255, 255, 255, 0.16);
+  /* 12A · chrome control spec: region/currency trigger resting border (hover → --color-border-input). */
+  --color-border-control: #d6d6d3;
+
+  /* Pressed / hovered rungs of the muted surface (02 UI Primitives). */
+  --color-bg-muted-hover: #ececea;
+  --color-bg-muted-active: #e3e3e1;
+
+  /* Feedback — status is never colour alone; these pair with an icon or text. */
+  --color-success: #1e7b45;
+  --color-success-surface: #eaf5ee;
+  --color-warning: #8a5a00;
+  --color-warning-ink: #8a5a00;
+  --color-warning-surface: #fff4db;
+  --color-danger: #b42318;
+  --color-danger-active: #8e1b12;
+  --color-danger-surface: #fdecea;
+  --color-danger-surface-active: #f9d9d5;
+  --color-info: #0b57d0;            /* NEW in B */
+  --color-info-surface: #eaf1fd;
+
+  /* Commerce */
+  --color-sale: #b42318;      /* sale price + sale badge only */
+  --color-sale-contrast: #ffffff; /* label on a sale badge (Round 2 · 01) */
+  --color-sold-out: #737371;  /* sold-out price / label */
+
+  /* Focus ring — fixed blue, never the brand, so it never disappears into a
+     brand fill (design rule; the previous theme bound it to --color-brand). */
+  --color-focus: #0b57d0;
+
+  /* Overlays */
+  --color-overlay-scrim: rgba(17, 17, 17, 0.4);          /* drawer / modal scrim */
+  --color-overlay-gradient: linear-gradient(
+    180deg,
+    rgba(0, 0, 0, 0) 0%,
+    rgba(0, 0, 0, 0.45) 100%
+  );                                                     /* text-on-image base */
+  --hero-scrim: rgba(0, 0, 0, 0.45);
+  /* 12B · the quiet control cluster on media (slideshow, video pause, marquee
+     pause): ink at 72% — white glyphs stay ≥ 4.5:1 over the lightest frame. */
+  --color-media-control: rgba(17, 17, 17, 0.72);
+  --color-media-control-hover: rgba(17, 17, 17, 0.86);
+  /* Marks drawn ON photos (a comparison divider) stay white in both schemes. */
+  --color-on-media: #ffffff;
+  /* 12F · hotspot numbers on a look image: ink on white, white on ink (active) — both schemes. */
+  --color-on-media-ink: #111111;
+  /* Round 2 · D16: minimum darkness at the text edge of an image, whatever
+     overlayOpacity says — 0.45 when only large text and buttons sit on the
+     image (3:1), 0.62 once body copy does (4.5:1 on the lightest photo). */
+  --overlay-text-floor-large: 0.45;
+  --overlay-text-floor-body: 0.62;
+
+  /* Round 2 · D3: theme-side editor frames are neutral — no hue, so they are
+     never mistaken for info, brand, error or focus, and they invert in dark. */
+  --color-editor-frame: var(--color-fg-subtle);
+
+  /* ── Typography ────────────────────────────────────────────────────────
+   * One family. Geist for display AND body (merchant setting, curated list);
+   * Geist Mono for SKU / order numbers / codes only — never UI chrome.
+   * Long-script fallbacks are part of the stack, not an afterthought.
+   */
+  --font-display: 'Geist', 'Noto Sans Thai', 'Noto Sans Arabic', system-ui, -apple-system,
+    'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  --font-body: var(--font-display);
+  --font-mono: 'Geist Mono', ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, monospace;
+
+  /* Type scale — design `typeScale`: the `m` column at 390, the `d` column
+     from 1024 up (the design draws its desktop frames at 1200 with the full
+     desktop sizes), linear between. The compact / large rungs live in
+     styles.css under `[data-type-scale]`. Body is fixed at 15 and never scales. */
+  --type-display: clamp(2.5rem, calc(2.5rem + (100vw - 24.375rem) * 0.05047), 4.5rem); /* 40 at 390 → 72 from 1024 */
+  --type-h1: clamp(2rem, calc(2rem + (100vw - 24.375rem) * 0.02524), 3rem); /* 32 at 390 → 48 from 1024 */
+  --type-h2: clamp(1.5rem, calc(1.5rem + (100vw - 24.375rem) * 0.01262), 2rem); /* 24 at 390 → 32 from 1024 */
+  --type-h3: clamp(1.25rem, calc(1.25rem + (100vw - 24.375rem) * 0.00631), 1.5rem); /* 20 at 390 → 24 from 1024 */
+  --type-h4: clamp(1.125rem, calc(1.125rem + (100vw - 24.375rem) * 0.00315), 1.25rem); /* 18 at 390 → 20 from 1024 */
+  --type-h5: clamp(1rem, calc(1rem + (100vw - 24.375rem) * 0.00158), 1.0625rem); /* 16 at 390 → 17 from 1024 */
+  --type-h6: 0.9375rem;     /* 15 — one weight step heavier than body */
+  --type-body-lg: 1.0625rem; /* 17 */
+  /* Nova 11 · B12: long-form body — 16 / 17 / 18 by typeScale (compact /
+     default / large, styles.css), always 17 below 640; leading 1.75. */
+  --text-body-lg: 1.0625rem;
+  --type-body: 0.9375rem;    /* 15 */
+  --type-body-sm: 0.8125rem; /* 13 */
+  --type-caption: 0.8125rem; /* 13 (12 at 390 — see the 640 breakpoint) */
+  --type-label: 0.75rem;     /* 12, line-height 1 */
+  --type-eyebrow: 0.75rem;   /* 12, uppercase, +0.06em */
+  --type-product-title: 0.875rem;                  /* 14 on a card */
+  --type-product-title-pdp: clamp(1.5rem, calc(1.5rem + (100vw - 24.375rem) * 0.01893), 2.25rem); /* 24 at 390 → 36 from 1024 */
+  --leading-product-title: 1.4;
+  --type-price: 0.9375rem;              /* 15 card */
+  --type-price-pdp: 1.25rem;            /* 20 PDP */
+  --type-price-compare: 0.8125rem;      /* 13 card */
+  --type-price-compare-pdp: 1rem;       /* 16 PDP */
+  --type-button: 0.875rem;              /* 14 md */
+  --type-button-sm: 0.8125rem;          /* 13 */
+  --type-button-lg: 0.9375rem;          /* 15 */
+  --type-nav: 0.875rem;                 /* 14; 18 in the mobile drawer */
+  --type-nav-mobile: 1.125rem;
+
+  --leading-display: 1;
+  --leading-h1: 1.05;
+  --leading-h2: 1.1;
+  --leading-h3: 1.2;
+  --leading-h4: 1.3;
+  --leading-h5: 1.4;
+  --leading-h6: 1.4;
+  --leading-caption: 1.5;
+  --leading-tight: 1.25;
+  --leading-snug: 1.4;
+  --leading-base: 1.6;
+  --leading-relaxed: 1.6;
+  --leading-loose: 1.75;
+  /* Round 2 · D17: one long-script body leading for Thai and Arabic. */
+  --leading-body-script: 1.75;
+  --leading-rtl: var(--leading-body-script); /* [dir='rtl'] body (was 1.7) */
+
+  /* Tracking tightens with size and relaxes to 0 at ≤ 20px. */
+  --tracking-display: -0.035em;
+  --tracking-h1: -0.03em;
+  --tracking-h2: -0.02em;
+  --tracking-h3: -0.015em;
+  --tracking-base: 0;
+  --tracking-button: 0;
+  --tracking-h6: 0;
+  --tracking-eyebrow: 0.06em;
+
+  --weight-body: 400;
+  --weight-medium: 500;
+  --weight-heading: 500;   /* headingWeight: 400 · 500 · 600 */
+  --weight-strong: 600;
+
+  /* ── Space — 4px base, 10 steps ───────────────────────────────────────── */
+  --space-0: 0;
+  --space-1: 0.25rem;   /*   4 */
+  --space-2: 0.5rem;    /*   8 */
+  --space-3: 0.75rem;   /*  12 */
+  --space-4: 1rem;      /*  16 */
+  --space-5: 1.5rem;    /*  24 */
+  --space-6: 2rem;      /*  32 */
+  --space-7: 3rem;      /*  48 */
+  --space-8: 4rem;      /*  64 */
+  --space-9: 6rem;      /*  96 */
+  --space-10: 8rem;     /* 128 */
+
+  /* Gap scale — design `gaps` (xxs 4 → 2xl 48). */
+  --gap-xxs: var(--space-1);  /* icon↔label, swatch gaps */
+  --gap-xs: var(--space-2);   /* inline groups, eyebrow→heading */
+  --gap-sm: var(--space-3);   /* card text stack, heading→text */
+  --gap-md: var(--space-4);   /* form fields, grid gap */
+  --gap-lg: var(--space-5);   /* text→button, drawer padding */
+  --gap-xl: var(--space-6);   /* header↔grid, any→image */
+  --gap-2xl: var(--space-7);  /* between content groups in a section */
+  --gap-component: var(--space-2);
+  --gap-content: var(--space-4);   /* 16 on mobile; 24 from 640 up */
+  --page-gutter: 1rem;             /* 16 → 24 → 40 */
+
+  /* Section vertical rhythm — design `sectionSpace`, 390 column first:
+     none 0 · sm 32 · md 48 · lg 64 (default) · xl 88; desktop values at 1024. */
+  --section-none: 0;
+  --section-sm: 2rem;        /* 32 */
+  --section-md: 3rem;        /* 48 */
+  --section-lg: 4rem;        /* 64 — the default */
+  --section-xl: 5.5rem;      /* 88 */
+  --section-pad-y: var(--section-lg);
+  --section-pad-x: var(--page-gutter);
+
+  /* Containers — design `containers`. `standard` is the page width
+     (pageWidth: standard 1280 · wide 1536); `wide` is the widest a section may
+     ask for. */
+  --container-full: 100%;
+  --container-wide: 1536px;
+  --container-standard: 1280px;
+  --container-content: 960px;
+  --container-narrow: 640px;
+
+  /* ── Grid ─────────────────────────────────────────────────────────────── */
+  --grid-columns: 4;
+  --grid-gap: 0.75rem;   /* 12 mobile → 16 desktop ("tight 16px grid") */
+  --grid-products: 2;
+
+  /* ── Radius — design `radii` + `radiusMap` ───────────────────────────── */
+  --radius-none: 0;
+  --radius-sm: 4px;     /* badge */
+  --radius-md: 8px;     /* button, input, chip, media, popover, toast */
+  --radius-lg: 12px;    /* modal / drawer inner corners */
+  --radius-pill: 999px; /* pill corners, count badge, toggle */
+  --radius-circle: 50%; /* swatches, avatars, icon buttons */
+  --radius-media: var(--radius-md);   /* product & collection media — follows cardCorners */
+  --radius-overlay: var(--radius-lg); /* fixed; drawers square on the attached edge */
+  --radius-badge: var(--radius-sm);   /* badgeTreatment: square 0 · rounded 4 · pill */
+
+  --border-width: 1px;
+  --border-subtle: var(--border-width) solid var(--color-border);
+  --border-default: var(--border-width) solid var(--color-border-strong);
+  --border-strong: var(--border-width) solid var(--color-border-emphasis);
+
+  --border-width-control: 1.5px;  /* checkbox / radio box, drawn chevrons, state rings */
+  --underline-offset: 3px;        /* inline links */
+  --underline-offset-lg: 4px;     /* standalone links, tertiary buttons, nav */
+  /* Round 2 · D12: one min-height per row kind, all widths; rows grow when
+     text wraps. */
+  --row-height-sm: 44px;          /* facet and select rows */
+  --row-height-md: 56px;          /* accordion, FAQ, footer menu, drawer lists */
+  --row-height: var(--row-height-md);
+
+  --focus-ring-width: 2px;
+  --focus-ring-offset: 2px;
+
+  /* Shadows — overlays only; nothing in the page flow casts one. */
+  --shadow-popover: 0 4px 16px rgba(17, 17, 17, 0.1);
+  --shadow-drawer: -8px 0 32px rgba(17, 17, 17, 0.14);
+  --shadow-modal: 0 16px 48px rgba(17, 17, 17, 0.18);
+  --shadow-floating: 0 2px 12px rgba(17, 17, 17, 0.12);
+  /* Nova 13 · 00 overlay foundations — every overlay surface reads these
+     (Nova 02's shadow-modal / shadow-popover stay for older surfaces). */
+  --overlay-shadow: 0 16px 48px rgba(17, 17, 17, 0.14);
+  --overlay-hairline: 1px solid var(--color-border); /* dark: the +1 surface step border */
+  --overlay-popover-shadow: 0 8px 24px rgba(17, 17, 17, 0.12);
+  --overlay-toast-shadow: 0 8px 24px rgba(17, 17, 17, 0.16);
+  --overlay-radius-dialog: 12px;
+  --overlay-radius-sheet: 16px;
+  --overlay-radius-popover: 12px;
+  --overlay-radius-toast: 10px;
+  --overlay-radius-alert: 8px;
+  --overlay-dialog-in: 180ms;   /* fade + 8px rise */
+  --overlay-slide-in: 240ms;    /* drawer, sheet */
+  --overlay-popover-in: 120ms;  /* fade */
+
+  /* ── Motion — design `motion` ─────────────────────────────────────────── */
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --ease-exit: cubic-bezier(0.4, 0, 1, 1);
+  --ease-enter: cubic-bezier(0, 0, 0.2, 1);
+  --duration-fast: 120ms;   /* hover colour, underline, image crossfade */
+  --duration-base: 200ms;   /* modal, accordion, tabs, toast, add-to-cart */
+  --duration-slow: 320ms;   /* gallery slide, mega menu */
+  --duration-drawer: 280ms; /* drawer in (200 out = --duration-base) */
+  --duration-exit: 160ms;   /* toast out */
+
+  /* ── Icons ────────────────────────────────────────────────────────────── */
+  --icon-sm: 16px;   /* inline / meta */
+  --icon-md: 20px;   /* default UI */
+  --icon-lg: 24px;   /* header / nav */
+  --icon-stroke: 1.6px;   /* iconStyle: line 1.6 · bold 2.0 */
+  --touch-target: 44px;
+
+  /* Partner logos are normalised to one height so mixed aspect ratios sit on
+     one baseline. */
+  --logo-height: 32px;
+
+  /* ── Media ratios — design `ratios` ───────────────────────────────────── */
+  --ratio-product: 1 / 1;        /* productMediaRatio: square · portrait 4:5 · natural */
+  --ratio-collection: 4 / 5;
+  --ratio-hero: 21 / 9;          /* text-first hero image */
+  --ratio-hero-mobile: 4 / 5;
+  /* Nova 11 · A1: one hero height ladder, shared by hero and video-hero
+     (option IDs small · medium · large · fullscreen, default medium). */
+  --hero-height-small: 400px;
+  --hero-height-medium: 560px;
+  --hero-height-large: 720px;
+  --hero-height-fullscreen: max(560px, calc(100svh - var(--header-height)));
+  /* Nova 11 · B9: collection banners stay shorter than heroes. */
+  --banner-height-compact: 320px;
+  --banner-height-md: 440px;
+  --banner-height-lg: 560px;
+  --banner-height-compact-mobile: 280px; /* 390: 280 / 360 / 480 */
+  --banner-height-md-mobile: 360px;
+  --banner-height-lg-mobile: 480px;
+  /* Nova 12B · 00 shared hero system. Display by headerSize (390 → 1024+):
+     small 32 → 48 · medium 40 → 72 · large 44 → 80, weight 500, −3.5%.
+     medium IS the Nova 01 display role: the canonical hero frame ("72 / 1.0")
+     and the 390 frame ("Display steps 72 → 40") agree with it; the 12B shared
+     panel's "medium 64" is the outlier (see CONTRACT_QUESTIONS). */
+  --hero-display-small: clamp(2rem, calc(2rem + (100vw - 24.375rem) * 0.02524), 3rem);
+  --hero-display-medium: var(--type-display);
+  /* collection-banner titles stay one step quieter (12B · 06 canvas: 64 → 40). */
+  --banner-display-medium: clamp(2.5rem, calc(2.5rem + (100vw - 24.375rem) * 0.03785), 4rem);
+  --hero-display-large: clamp(2.75rem, calc(2.75rem + (100vw - 24.375rem) * 0.05678), 5rem);
+  /* Copy inset on media: 64 / 56 desktop · 24 / 16 at 390 (never closer than 16). */
+  --hero-inset-inline: 1rem;
+  --hero-inset-block: 1.5rem;
+  /* textWidth: narrow 560 · medium 720 · wide 880; body measure 46ch. */
+  --hero-measure-narrow: 560px;
+  --hero-measure-medium: 720px;
+  --hero-measure-wide: 880px;
+  --hero-body-measure: 46ch;
+  --hero-radius: var(--radius-lg);      /* contained · text-first media: 12 */
+  /* Text over moving video: the body floor plus an 18% base wash (frames vary). */
+  --hero-video-wash: 0.18;
+  --duration-hero: 400ms;               /* slide fade / slide, video fade-in */
+  /* 12B · marquee: text 14 / 20 / 48 (390: 14 / 20 / 32), band 40 / 56 / 96. */
+  --marquee-text-small: 0.875rem;
+  --marquee-text-medium: 1.25rem;
+  --marquee-text-large: 2rem;
+  --marquee-height-small: 40px;
+  --marquee-height-medium: 56px;
+  --marquee-height-large: 72px;
+  /* 12B · promo-banner band: 48 / 40 inset desktop, 20 / 24 at 390; radius 12. */
+  --promo-pad-inline: 1.25rem;
+  --promo-pad-block: 1.5rem;
+  --countdown-unit: 3.5rem;             /* unit box 56 at 390 → 64 */
+  /* ── Nova 12C · merchandising — one card, one carousel, one price hierarchy. */
+  --card-gap-x: 0.5rem;                 /* 8 at 390 → 16 desktop (column gap) */
+  --card-gap-y: 1.75rem;                /* 28 at 390 → 40 desktop (row gap) */
+  --card-swatch: 12px;                  /* card colour dots */
+  --carousel-arrow: 40px;               /* header-row arrows, never over products */
+  --carousel-peek: 2.3;                 /* cards visible at 390 (a peek shows there is more) */
+  --swatch-size: 32px;                  /* PDP swatch dot in a 44 target */
+  --pdp-buybox: 440px;                  /* purchase column */
+  --pdp-thumb: 64px;                    /* thumbnail column / row */
+  --pdp-sticky-top: 1.5rem;             /* buy box sticks 24 below the viewport top */
+  /* 12C product-title block: h1 32 / 1.15 (390: 24). */
+  --pdp-title: clamp(1.5rem, calc(1.5rem + (100vw - 24.375rem) * 0.01262), 2rem);
+  --pdp-price: 1.25rem;                 /* 20 */
+  --pdp-compare: 1rem;                  /* 16, struck */
+  --filter-sidebar: 14rem;              /* 224 facet column */
+  --ratio-editorial: 4 / 3;      /* image-with-text, blog */
+  --ratio-square: 1 / 1;         /* multicolumn, logos grid */
+  --ratio-logo: 3 / 1;           /* logo-list, max-height 40 */
+  --logo-height-header: 32px;    /* ≤ 64 desktop · ≤ 40 tablet · ≤ 32 phone */
+  --logo-height-footer: 40px;
+  --header-height: 56px;
+
+  /* ── Layer (z-index) — Round 2 · D10, one ladder ─────────────────────────
+     Components never set a raw z-index. `--z-raised` is for stacking inside
+     one component (media under its caption); `--z-header` is the sticky rung
+     under its older name, kept because the AI generator reads `--z-*`. */
+  --z-base: 0;
+  --z-raised: 1;
+  --z-sticky: 100;     /* sticky header, collection toolbar, sticky add to cart */
+  --z-header: var(--z-sticky);
+  --z-dropdown: 200;   /* mega menu, select listbox, filter popover */
+  --z-consent: 250;    /* cookie consent — non-modal, below every overlay */
+  --z-overlay: 300;    /* scrim + drawers, search modal */
+  --z-modal: 400;      /* modal, lightbox, a drawer opened from inside one */
+  --z-popover: 500;    /* tooltip / popover / listbox inside a modal */
+  --z-toast: 600;
+  --z-skip-link: 700;
+
+  /* ── Component bindings — what the global settings move ───────────────── */
+  --btn-radius: var(--radius-md);     /* buttonCorners: square 0 · rounded 8 · pill */
+  --btn-height: var(--touch-target);  /* 44 md — touch target, not a style choice */
+  --btn-height-sm: 36px;
+  --btn-height-lg: 52px;
+  --btn-pad-x: 1.25rem;               /* 20 md */
+  --btn-pad-x-sm: 0.875rem;           /* 14 sm */
+  --button-px-lg: 1.75rem;            /* 28 lg — Round 2 · D14 (14 · 20 · 28) */
+  --btn-pad-x-lg: var(--button-px-lg);
+  --btn-font-weight: var(--weight-medium);
+
+  --input-radius: var(--radius-md);   /* inputCorners: square · rounded · pill (textarea caps at lg) */
+  /* Round 2 · D14: md matches the md button; lg (16px text, no iOS zoom) for
+     search, account and checkout fields. The 48 rung is retired. */
+  --input-height-md: 44px;
+  --input-height-lg: 52px;
+  --input-height: var(--input-height-md);
+  --input-pad-x: 0.875rem;
+  --input-border: var(--border-default); /* the 3:1 control boundary, not the hairline */
+
+  --card-radius: var(--radius-md);    /* cardCorners: square 0 · rounded 8 · soft 12 — visible only with outlineCards */
+  --card-pad: var(--space-2);         /* 8 inside an outlined card */
+  --card-border: var(--border-subtle);
+
+  /* Round 2 · D15: the toggle's off track is the 3:1 control boundary. */
+  --toggle-track-off: var(--color-border-input);
+
+  /* Round 2 · D13: gap between the header (or breadcrumbs) and the first
+     section of a title-led template; hero-led templates start at 0. */
+  --space-page-top: 1.5rem;           /* 24 below 640 · 40 at 640–1023 · 56 from 1024 (Nova 11 · B5) */
+
+  /* Nova 11 · B5: the theme's two breakpoints. Custom properties cannot be
+     read inside @media, so the media queries repeat these values; the tokens
+     are the reference the design and the AI read. */
+  --bp-tablet: 640px;
+  --bp-desktop: 1024px;
+
+  /* Runtime-measured, not a design token: the mobile sticky purchase /
+     checkout bar writes its own height here so the toast can clear it. */
+  --sticky-bar-height: 0px;
+}
+
+/* ── Responsive scale ──────────────────────────────────────────────────────
+ * 390 is the reference phone; 640–1023 tablet; 1024+ desktop (1440 reference).
+ */
+@media (min-width: 640px) {
+  :root {
+    --page-gutter: 1.5rem;   /* 24 */
+    --header-height: 60px;
+    --grid-columns: 8;
+    --grid-gap: 1rem;        /* 16 */
+    --grid-products: 3;
+    --section-sm: 2.5rem;    /* 40 */
+    --section-md: 4rem;      /* 64 */
+    --section-lg: 5.5rem;    /* 88 */
+    --section-xl: 7.5rem;    /* 120 */
+    --gap-content: var(--space-5);  /* 24 */
+    --logo-height-header: 40px;
+    --space-page-top: 2.5rem; /* 40 */
+    --hero-inset-inline: 2.5rem;
+    --hero-inset-block: 2.5rem;
+    --promo-pad-inline: 2.5rem;
+    --promo-pad-block: 2rem;
+  }
+}
+
+@media (min-width: 1024px) {
+  :root {
+    --page-gutter: 2.5rem;   /* 40 */
+    --header-height: 72px;
+    --grid-columns: 12;
+    --grid-gap: 1rem;        /* 16 — B keeps the grid tight */
+    --grid-products: 3;
+    --section-sm: 3rem;      /* 48 */
+    --section-md: 5rem;      /* 80 */
+    --section-lg: 7rem;      /* 112 */
+    --section-xl: 10rem;     /* 160 */
+    --space-page-top: 3.5rem; /* 56 */
+    --hero-inset-inline: 4rem;   /* 64 */
+    --hero-inset-block: 3.5rem;  /* 56 */
+    --marquee-text-large: 3rem;  /* 48 */
+    --marquee-height-large: 96px;
+    --promo-pad-inline: 3rem;    /* 48 */
+    --promo-pad-block: 2.5rem;   /* 40 */
+    --countdown-unit: 4rem;
+    --card-gap-x: 1rem;
+    --card-gap-y: 2.5rem;
+  }
+}
+
+@media (min-width: 1280px) {
+  :root {
+    --grid-products: 4;
+  }
+}
+
+/* ── Dark scheme — Round 2 · D1: a supported, opt-in setting ──────────────
+ * Theme settings → Colour → Colour scheme (`colorScheme`) writes
+ * `data-scheme='dark'` on the root; the default is light. Design `dark` table
+ * + 03 · 3.14. A merchant background/text pair from theme settings wins over
+ * this (lib/theme-settings.ts writes with !important).
+ */
+:root[data-scheme='dark'] {
+  --color-bg: #0e0e0e;
+  --color-bg-muted: #1c1c1c;
+  --color-bg-elevated: #151515;     /* one step above bg; overlays add a 1px border */
+  --color-bg-inverse: #f2f2f0;
+  --color-media-bg: #1c1c1c;
+  --color-skeleton: #1c1c1c;
+  --color-bg-muted-hover: #262626;
+  --color-bg-muted-active: #303030;
+  --color-fg: #f2f2f0;
+  --color-fg-muted: #a8a8a5;
+  --color-fg-subtle: #8c8c89;
+  --color-fg-inverse: #111111;
+  --color-border: #2a2a2a;
+  --color-border-strong: #6e6e6b;
+  --color-border-emphasis: #f2f2f0;
+  --color-border-inverse: rgba(17, 17, 17, 0.16);
+  --color-border-control: #3a3a38;
+  --color-brand: #f2f2f0;
+  --color-brand-hover: #dcdcda;
+  --color-brand-active: #c8c8c6;
+  --color-brand-contrast: #111111;
+  --color-sale: #ff8a7a;
+  --color-sale-contrast: #0e0e0e;   /* ink label on the light sale fill */
+  /* Nova 11 · B1 — the design's `-bg` is this theme's `-surface`. */
+  --color-success: #7fd49b;
+  --color-success-surface: #12301f;
+  --color-warning: #f2c46b;
+  --color-warning-ink: #f2c46b;
+  --color-warning-surface: #3a2a0c;
+  --color-danger: #ff8a7a;
+  --color-danger-surface: #3a1512;
+  --color-info: #7aa7ff;
+  --color-info-surface: #12233f;
+  --color-focus: #7aa7ff;
+  --color-overlay-scrim: rgba(0, 0, 0, 0.6);
+  color-scheme: dark;
+}
+
+/* ── Reduced motion ────────────────────────────────────────────────────────
+ * The OS preference wins over the `motion` setting: colour-only hovers,
+ * fades instead of slides, no shimmer, no autoplay.
+ * Never reset `transform` here: elements parked off-screen with it (the skip
+ * link, closed drawers) would land on top of the page and swallow clicks.
+ */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Forced reduced motion — the lab (and an editor preview) can pin the
+   reduced-motion branch without the OS setting. Same rule as the media query. */
+[data-motion='reduced'] *,
+[data-motion='reduced'] *::before,
+[data-motion='reduced'] *::after {
+  animation-duration: 0.01ms !important;
+  animation-iteration-count: 1 !important;
+  transition-duration: 0.01ms !important;
+  scroll-behavior: auto !important;
+}

package/templates/nova/src/styles/viewport.ts

@@ -0,0 +1,23 @@
+import { useCallback, useSyncExternalStore } from 'react'
+
+/** Phone layouts (Nova 01 breakpoint: below 640). */
+export const PHONE_QUERY = '(max-width: 639.98px)'
+
+/**
+ * A media query, live. A client-only render reads it at the first render (so a phone never flashes
+ * the desktop surface before swapping). A server-rendered page hydrates with `false` — the value the
+ * server rendered — and switches right after, so the hydrated tree matches the server HTML (reading
+ * matchMedia in the first hydrating render was a hydration mismatch on every phone). False on the
+ * server and where matchMedia is missing.
+ */
+export function useMediaQuery(query: string): boolean {
+  return useSyncExternalStore(
+    useCallback((onChange: () => void) => {
+      const mq = typeof window !== 'undefined' ? window.matchMedia?.(query) : undefined
+      mq?.addEventListener?.('change', onChange)
+      return () => mq?.removeEventListener?.('change', onChange)
+    }, [query]),
+    () => (typeof window !== 'undefined' ? Boolean(window.matchMedia?.(query).matches) : false),
+    () => false,
+  )
+}