create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/tests/support/abi-ctx.ts

@@ -0,0 +1,136 @@
+/**
+ * A Theme ABI v2 RenderContext for tests: the shape the platform hands `render(request, ctx)`,
+ * backed by in-memory ABI records. Records every data call so a test can assert the plan.
+ */
+import type { RenderContext } from '@tanqory/theme-abi'
+import manifestJson from '../../lib/abi/generated/manifest.json'
+
+type Obj = Record<string, unknown>
+const manifest = manifestJson as unknown as {
+  routes: Record<string, string>
+  templates: Record<string, { route: string; regions: string[] }>
+  regions: Record<string, { scope: string }>
+  contentVersion: number
+}
+
+export const money = (amount: string, currencyCode = 'USD') => ({ amount, currencyCode })
+export const conn = <T,>(nodes: T[]) => ({ nodes, pageInfo: { hasNextPage: false } })
+
+export function product(handle: string, title: string, price = '49.00') {
+  return {
+    id: `p-${handle}`, handle, title, descriptionHtml: `<p>${title} description</p>`, tags: [], availableForSale: true, vendor: 'Halden', productType: 'Home',
+    featuredImage: { url: `https://cdn.example/${handle}.jpg`, altText: title, width: 800, height: 800 },
+    images: [{ url: `https://cdn.example/${handle}.jpg`, altText: title, width: 800, height: 800 }],
+    options: [{ name: 'Title', values: ['Default Title'] }],
+    variants: conn([{ id: `v-${handle}`, title: 'Default Title', availableForSale: true, price: money(price), compareAtPrice: null, selectedOptions: [{ name: 'Title', value: 'Default Title' }], sku: `SKU-${handle}` }]),
+    priceRange: { minVariantPrice: money(price), maxVariantPrice: money(price) },
+    seo: {},
+  }
+}
+
+export function collection(handle: string, title: string, products: ReturnType<typeof product>[]) {
+  return { id: `c-${handle}`, handle, title, descriptionHtml: '', image: null, products: { ...conn(products), totalCount: products.length }, seo: {} }
+}
+
+export function menu(handle: string, items: [string, string][]) {
+  return { handle, title: handle, items: items.map(([title, url], i) => ({ id: `${handle}-${i}`, title, url, type: 'HTTP', items: [] })) }
+}
+
+export const SHOP = {
+  name: 'Halden & Co.', description: 'Linen and stoneware', primaryDomain: { url: 'https://shop.example' },
+  paymentSettings: { currencyCode: 'USD', enabledPresentmentCurrencies: ['USD'] }, shipsToCountries: ['US', 'TH'], brand: null,
+}
+
+export interface Store {
+  shop?: Obj
+  menus?: ReturnType<typeof menu>[]
+  products?: ReturnType<typeof product>[]
+  collections?: ReturnType<typeof collection>[]
+  /** The store's PUBLISHED policies (ABI `Policy`); an unpublished one is simply absent. */
+  policies?: { handle: string; title: string; body: string; url: string }[]
+  cart?: Obj | null
+}
+
+/** The page the platform composes: regions in template order, from `regions` (shared) / the template's own. */
+export function pageOf(template: string, sections: { region: string; sections: Obj[] }[]) {
+  const order = manifest.templates[template]!.regions
+  return { contentVersion: manifest.contentVersion, template, regions: order.flatMap((r) => sections.filter((s) => s.region === r)) }
+}
+
+export function abiCtx(o: {
+  kind: string
+  handle?: string
+  template?: string
+  url?: string
+  params?: Record<string, string>
+  page: ReturnType<typeof pageOf>
+  settings?: Obj
+  store?: Store
+  mode?: 'serve' | 'preview'
+}): { ctx: RenderContext; ops: string[] } {
+  const ops: string[] = []
+  const s = o.store ?? {}
+  const rec = <T,>(op: string, v: T) => { ops.push(op); return Promise.resolve(v) }
+  const products = s.products ?? []
+  const collections = s.collections ?? []
+  const menus = Object.fromEntries((s.menus ?? []).map((m) => [m.handle, m]))
+  const byHandle = <T extends { handle: string }>(list: T[], h: string) => list.find((x) => x.handle === h) ?? null
+  const canonical = o.url ?? `https://shop.example/${o.kind === 'home' ? '' : `${o.kind}s/${o.handle ?? ''}`}`
+  const resource = (): Obj => {
+    switch (o.kind) {
+      case 'product': return { kind: 'product', product: byHandle(products, o.handle ?? '') }
+      case 'collection': return { kind: 'collection', collection: byHandle(collections, o.handle ?? '') }
+      case 'policy': return { kind: 'policy', policy: byHandle(s.policies ?? [], o.handle ?? '') }
+      case 'cart': return { kind: 'cart', cart: s.cart ?? null }
+      default: return { kind: o.kind }
+    }
+  }
+  const ctx = {
+    abi: '2.0',
+    mode: o.mode ?? 'serve',
+    route: { kind: o.kind, ...(o.handle ? { handle: o.handle } : {}), template: o.template ?? manifest.routes[o.kind], params: o.params ?? {}, canonical },
+    request: { method: 'GET', url: canonical, headers: {}, hasCart: false, isSignedIn: false, isPreview: o.mode === 'preview' },
+    locale: { language: 'en', country: 'US', market: 'us', currency: 'USD', availableLanguages: ['en'], timeZone: 'UTC' },
+    consent: { known: false, analytics: false, marketing: false, functional: true },
+    capabilities: new Set(['data:shop', 'data:localization', 'data:catalog', 'data:content', 'data:search', 'data:cart', 'data:products.recommendations']),
+    content: { revision: 'sha256:test', contentVersion: manifest.contentVersion, settings: o.settings ?? {}, page: o.page },
+    data: {
+      dataVersion: 'test',
+      // The platform resolves every `resolve: true` setting into refs; the theme's planner reads them, and
+      // fetches in round 2 what the snapshot did not answer. Tests leave refs empty: round 2 is exercised.
+      snapshot: () => rec('snapshot', { shop: s.shop ?? SHOP, menus, resource: resource(), refs: {}, pixels: [], denied: [] }),
+      shop: { get: () => rec('shop.get', s.shop ?? SHOP), menus: (h?: string[]) => rec(`shop.menus:${(h ?? []).join(',')}`, h ? (s.menus ?? []).filter((m) => h.includes(m.handle)) : s.menus ?? []) },
+      catalog: {
+        product: (h: string) => rec(`catalog.product:${h}`, byHandle(products, h)),
+        collection: (h: string) => rec(`catalog.collection:${h}`, byHandle(collections, h)),
+        collections: () => rec('catalog.collections', conn(collections)),
+        search: (a: { query: string }) => rec(`catalog.search:${a.query}`, { query: a.query, products: conn(products), pages: conn([]), articles: conn([]), collections: conn([]) }),
+        recommendations: (h: string) => rec(`catalog.recommendations:${h}`, products.filter((p) => p.handle !== h).slice(0, 4)),
+      },
+      content: { page: (h: string) => rec(`content.page:${h}`, null), blog: (h: string) => rec(`content.blog:${h}`, null), policy: (h: string) => rec(`content.policy:${h}`, byHandle(s.policies ?? [], h)) },
+      customer: { accountUrl: (p?: string) => `/account${p ? `/${p}` : ''}` },
+    },
+    assets: { base: 'https://shop.example/a/test/client', manifest: { main: { file: 'assets/main.js', kind: 'script', isEntry: true, css: ['assets/main.css'], imports: [], integrity: 'sha256-x' }, 'assets/main.css': { file: 'assets/main.css', kind: 'style', integrity: 'sha256-y' } } },
+    cache: { hint() {} },
+    log: { debug() {}, info() {}, warn() {}, error: (msg: string, f?: unknown) => { throw new Error(`${msg} ${JSON.stringify(f)}`) } },
+    now: () => Date.UTC(2026, 9, 13),
+    release: { id: 'r', artifactDigest: 'd' },
+    actions: undefined,
+    signal: new AbortController().signal,
+  } as unknown as RenderContext
+  return { ctx, ops }
+}
+
+/** The server HTML split into what a test reads. */
+export async function serverHtml(render: (r: Request, c: RenderContext) => Promise<Response>, ctx: RenderContext) {
+  const res = await render(new Request(ctx.request.url), ctx)
+  const html = await res.text()
+  return {
+    status: res.status,
+    html,
+    headers: res.headers,
+    root: html.match(/<div id="root">([\s\S]*)<\/div>\s*<\/body>/)?.[1] ?? '',
+    state: html.match(/<script type="application\/json" id="tq-state">([\s\S]*?)<\/script>/)?.[1] ?? '',
+    rules: html.match(/<style id="tq-style-rules">([\s\S]*?)<\/style>/)?.[1] ?? '',
+  }
+}

package/templates/nova/tests/support/block-stories.tsx

@@ -0,0 +1,13 @@
+import type { StoryObj } from './case'
+import { defaultsOf, type Schema } from '@tanqory/theme-kit'
+
+/** A block's Playground case: the block schema's defaults under the case's own values. */
+export function blockPlayground<P extends object>(schema: Schema, extra: Partial<P> = {}, _parent?: string): StoryObj<P> {
+  return { name: 'Playground', args: { ...defaultsOf(schema), ...extra } as P } as unknown as StoryObj<P>
+}
+
+export const blockFrame = (S: () => JSX.Element) => (
+  <div style={{ padding: 32, maxWidth: 720 }}>
+    <S />
+  </div>
+)

package/templates/nova/tests/support/case.tsx

@@ -0,0 +1,102 @@
+/**
+ * Test cases without a component workbench. A case file (`*.cases.tsx`) exports
+ * a `meta` default and named cases; `cases.test.tsx` renders every case inside
+ * <NovaProvider>, runs its `play` and checks it with axe.
+ *
+ * The shapes follow the Component Story Format so the cases read the same way
+ * they were written: `args`, `render`, `decorators`, `parameters.nova`, `play`.
+ */
+import { createElement, type ComponentType, type ReactNode } from 'react'
+import { render } from '@testing-library/react'
+import userEventLib from '@testing-library/user-event'
+import { vi } from 'vitest'
+
+export { expect } from 'vitest'
+export { within, waitFor, screen, fireEvent } from '@testing-library/react'
+export const userEvent = userEventLib
+export const fn = vi.fn
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type PropsOf<C> = C extends ComponentType<infer P> ? P : Record<string, any>
+type ArgsOf<M> = M extends { component: infer C } ? PropsOf<C> : M extends { args: infer A } ? A : Record<string, any>
+
+export interface NovaParams {
+  locale?: string
+  mode?: 'storefront' | 'editor'
+  scheme?: 'light' | 'dark'
+  motion?: 'standard' | 'reduced'
+  theme?: object
+}
+
+export interface CaseContext<A = any> {
+  args: A
+  globals: Record<string, any>
+  parameters: Record<string, any> & { nova?: NovaParams }
+  canvasElement: HTMLElement
+}
+
+export type CaseComponent = () => JSX.Element
+export type Decorator<A = any> = (Story: CaseComponent, ctx: CaseContext<A>) => ReactNode
+
+export interface Meta<C = any> {
+  title?: string
+  component?: C
+  args?: Partial<PropsOf<C>>
+  parameters?: Record<string, any>
+  decorators?: Decorator<PropsOf<C>>[]
+  render?: (args: PropsOf<C>, ctx: CaseContext<PropsOf<C>>) => ReactNode
+  play?: (ctx: CaseContext<PropsOf<C>>) => Promise<void> | void
+  tags?: string[]
+  globals?: Record<string, any>
+}
+
+export interface StoryObj<M = any> {
+  name?: string
+  args?: Partial<ArgsOf<M>>
+  render?: (args: ArgsOf<M>, ctx: CaseContext<ArgsOf<M>>) => ReactNode
+  play?: (ctx: CaseContext<ArgsOf<M>>) => Promise<void> | void
+  parameters?: Record<string, any> & { nova?: NovaParams }
+  decorators?: Decorator<ArgsOf<M>>[]
+  tags?: string[]
+  globals?: Record<string, any>
+}
+
+export type CaseModule = { default: Meta } & Record<string, unknown>
+
+/** The named cases of a module (every named export that is an object). */
+export function casesOf(mod: CaseModule): [string, StoryObj][] {
+  return Object.entries(mod).filter(([k, v]) => k !== 'default' && v !== null && typeof v === 'object' && !Array.isArray(v)) as [string, StoryObj][]
+}
+
+/** The args a case renders with: meta args under the case's own. */
+export function caseArgs(mod: CaseModule, name: string): Record<string, unknown> {
+  const story = mod[name] as StoryObj | undefined
+  if (!story) throw new Error(`no case "${name}"`)
+  return { ...(mod.default.args ?? {}), ...(story.args ?? {}) }
+}
+
+/**
+ * Render one case. `wrap` is the outermost decorator (the NovaProvider), applied
+ * after the case's and the meta's own — the same order a workbench uses.
+ */
+export async function runCase(mod: CaseModule, story: StoryObj, wrap: Decorator): Promise<CaseContext> {
+  const meta = mod.default
+  const args = { ...(meta.args ?? {}), ...(story.args ?? {}) }
+  const ctx: CaseContext = {
+    args,
+    globals: { ...(meta.globals ?? {}), ...(story.globals ?? {}) },
+    parameters: { ...(meta.parameters ?? {}), ...(story.parameters ?? {}) },
+    canvasElement: document.body,
+  }
+  const draw = story.render ?? meta.render
+  let Current: CaseComponent = () => (draw ? draw(args, ctx) : meta.component ? createElement(meta.component as ComponentType<any>, args) : null) as JSX.Element
+  for (const dec of [...(story.decorators ?? []), ...(meta.decorators ?? []), wrap]) {
+    const Inner: CaseComponent = Current
+    Current = (): JSX.Element => dec(Inner, ctx) as JSX.Element
+  }
+  const { container } = render(createElement(Current))
+  ctx.canvasElement = container
+  const play = story.play ?? meta.play
+  if (play) await play(ctx)
+  return ctx
+}

package/templates/nova/tests/support/contracts.ts

@@ -0,0 +1,30 @@
+import type { AcceptedDeviation, ValidateOptions } from '../../scripts/compiler/contracts/validate'
+import theme from '../../theme.config'
+import { BLOCK_SCHEMAS } from './sections'
+import { promotionPopupSchema } from '../../config/promotion-popup.schema'
+
+/** The design families Nova implements in full (every section in them is built). */
+export const IMPLEMENTED_FAMILIES = ['12A', '12B', '12C', '12D', '12E', '12F', '12G', '13'] as const
+
+/**
+ * Differences between code and contract that are ACCEPTED, each with the
+ * reason. Keep this list short and reviewed: every entry is a place where the
+ * code knowingly differs from the approved contract.
+ */
+export const ACCEPTED_DEVIATIONS: readonly AcceptedDeviation[] = [
+  {
+    code: 'invalid-block',
+    where: 'block:footer-line@footer',
+    reason:
+      "army #7740 (main #467): LINE's Add friend button in the footer was added after the approved 12A design, which has no footer-line row. An addition, not a change: no locked id, key or option moves. Lock it when the design package gains the block.",
+  },
+]
+
+/** Everything the contract validator compares: the theme's own schemas. */
+export const VALIDATION_INPUT: ValidateOptions = {
+  families: IMPLEMENTED_FAMILIES,
+  sections: theme.sections.map((s) => s.schema),
+  blocks: BLOCK_SCHEMAS,
+  globals: [promotionPopupSchema],
+  accepted: ACCEPTED_DEVIATIONS,
+}

package/templates/nova/tests/support/foundation-pages.tsx

@@ -0,0 +1,260 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import type { StoryObj } from './case'
+import foundations from '../../.tanqory/contracts/nova-01.json'
+import { contrastRatio, THEME_DEFAULTS, type NovaThemeSettings } from '../../src/styles/theme'
+import { NovaProvider } from '../../src/styles/NovaProvider'
+import { Button } from '../../src/components/base/Button'
+import { Badge } from '../../src/components/base/Badge'
+import { Input } from '../../src/components/base/Input'
+import { Chip } from '../../src/components/base/Chip'
+import { Icon } from '../../src/styles/Icon'
+import { Container } from '../../src/styles/Container'
+
+/**
+ * Foundations render FROM the approved Nova 01 tables (generated/nova-01.json)
+ * beside the live computed token, so the page itself shows any drift.
+ */
+const F = foundations as unknown as {
+  colors: { n: string; v: string; role: string; r: string }[]
+  typeScale: { k: string; c: number; d: number; l: number; m: number; lh: string; w: number; tr: string }[]
+  typeRules: { t: string; d: string }[]
+  radii: { k: string; v: string }[]
+  radiusMap: { c: string; d: string; t: string; m: string }[]
+  gaps: { k: string; v: number }[]
+  sectionSpace: { k: string; d: string; m: string }[]
+  containers: { k: string; v: string }[]
+  ratios: { k: string; v: string; n: string }[]
+  motion: { k: string; d: string; e: string; p: string; r: string }[]
+  principles: { t: string; d: string }[]
+  tokens: { family: string; name: string; value: string }[]
+  dark: { k: string; l: string; d: string }[]
+}
+
+/** Design names that the code keeps under their pre-package names (Nova 01 → tokens.css header). */
+const CODE_NAME: Record<string, string> = { '--color-border-strong': '--color-border-emphasis', '--color-success-bg': '--color-success-surface', '--color-warning-bg': '--color-warning-surface', '--color-danger-bg': '--color-danger-surface', '--color-button-primary-bg': '--color-button', '--color-button-secondary-border': '--color-border-input' }
+
+export const page = { padding: 'clamp(16px, 4vw, 32px)', display: 'grid', gap: 32, maxWidth: 1200, minWidth: 0, gridTemplateColumns: 'minmax(0, 1fr)' } as const
+export const mono = { fontFamily: 'var(--font-mono)', fontSize: 12 } as const
+export const muted = { color: 'var(--color-fg-muted)', fontSize: 13 } as const
+
+export function Table({ head, rows }: { head: string[]; rows: ReactNode[][] }) {
+  return (
+    <div style={{ overflowX: 'auto', maxWidth: '100%' }} tabIndex={0} role="region" aria-label={head.join(', ')}>
+    <table style={{ borderCollapse: 'collapse', width: '100%', fontSize: 13 }}>
+      <thead>
+        <tr>{head.map((h) => <th key={h} style={{ textAlign: 'start', padding: '8px 12px 8px 0', borderBottom: '1px solid var(--color-fg)', ...mono }}>{h}</th>)}</tr>
+      </thead>
+      <tbody>
+        {rows.map((r, i) => (
+          <tr key={i}>{r.map((c, j) => <td key={j} style={{ padding: '10px 12px 10px 0', borderBottom: '1px solid var(--color-border)', verticalAlign: 'top' }}>{c}</td>)}</tr>
+        ))}
+      </tbody>
+    </table>
+    </div>
+  )
+}
+
+type Story = StoryObj
+
+function ColourPage() {
+  const ref = useRef<HTMLDivElement>(null)
+  const [vals, setVals] = useState<Record<string, string>>({})
+  useEffect(() => {
+    if (!ref.current) return
+    const cs = getComputedStyle(ref.current)
+    setVals(Object.fromEntries(F.colors.map((c) => CODE_NAME[c.n] ?? c.n).map((n) => [n, cs.getPropertyValue(n).trim()])))
+  }, [])
+  const norm = (v: string) => v.toLowerCase().replace(/\s/g, '')
+  return (
+    <div ref={ref} style={page}>
+      <h1 className="nv-h2">Colour roles</h1>
+      <p style={muted}>Design value from Nova 01 beside the live token. "≠" marks a deliberate deviation recorded in tokens.css (two inks darkened so the role's contrast promise holds on every surface).</p>
+      <Table
+        head={['swatch', 'token', 'role', 'design', 'code', 'on bg']}
+        rows={F.colors.map((c) => {
+          const code = CODE_NAME[c.n] ?? c.n
+          const live = vals[code] ?? ''
+          const same = norm(live) === norm(c.v) || !live.startsWith('#')
+          return [
+            <span style={{ display: 'block', width: 40, height: 28, borderRadius: 4, background: `var(${code})`, boxShadow: 'inset 0 0 0 1px rgba(0,0,0,.08)' }} />,
+            <code style={mono}>{c.n}{code !== c.n ? ` → ${code}` : ''}</code>,
+            c.role,
+            <code style={mono}>{c.v}</code>,
+            <code style={mono}>{live}{same ? '' : '  ≠'}</code>,
+            live.startsWith('#') && live.length === 7 ? `${contrastRatio(live, '#ffffff').toFixed(1)}:1` : '',
+          ]
+        })}
+      />
+      <h2 className="nv-h3">Dark scheme (opt-in)</h2>
+      <Table head={['token', 'light', 'dark']} rows={F.dark.map((d) => [<code style={mono}>{d.k}</code>, <code style={mono}>{d.l}</code>, <code style={mono}>{d.d}</code>])} />
+    </div>
+  )
+}
+export const Colors: Story = { render: () => <ColourPage /> }
+
+export const Typography: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Type scale · Geist</h1>
+      <Table
+        head={['role', 'compact', 'default', 'large', '390', 'lh', 'wt', 'tracking', 'specimen']}
+        rows={F.typeScale.map((t) => [
+          <code style={mono}>{t.k}</code>, t.c, t.d, t.l, t.m, t.lh, t.w, t.tr,
+          <span style={{ fontSize: Math.min(t.d, 48), lineHeight: t.lh, fontWeight: t.w, letterSpacing: t.tr === '0' ? 0 : t.tr.replace('−', '-') }}>Linen, washed</span>,
+        ])}
+      />
+      <div style={{ display: 'grid', gap: 8 }}>
+        {F.typeRules.map((r) => <p key={r.t}><strong style={{ fontWeight: 500 }}>{r.t}.</strong> <span style={muted}>{r.d}</span></p>)}
+      </div>
+      <div lang="th" style={{ display: 'grid', gap: 8 }}>
+        <p className="nv-h3">ผ้าลินินยิ่งซักยิ่งนุ่ม</p>
+        <p>ซักน้ำเย็น ตากในที่ร่ม ไม่ต้องรีด เส้นใยลินินจะนุ่มขึ้นทุกครั้งที่ซัก และแข็งแรงขึ้นเมื่อเปียก</p>
+      </div>
+      <div dir="rtl" lang="ar" style={{ display: 'grid', gap: 8 }}>
+        <p className="nv-h3">الكتان يتحسن مع كل غسلة</p>
+        <p>اغسل بماء بارد وجفف على الحبل ولا تستخدم المكواة.</p>
+      </div>
+    </div>
+  ),
+}
+
+export const Spacing: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Gaps</h1>
+      <Table head={['token', 'px', '']} rows={F.gaps.map((g) => [<code style={mono}>--gap-{g.k}</code>, g.v, <span style={{ display: 'block', height: 12, width: g.v * 4, background: 'var(--color-fg)' }} />])} />
+      <h2 className="nv-h3">Section spacing (shared IDs none · small · medium · large · xl)</h2>
+      <Table head={['rung', 'desktop', '390']} rows={F.sectionSpace.map((s) => [s.k, s.d, s.m])} />
+    </div>
+  ),
+}
+
+export const Radius: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Radius</h1>
+      <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
+        {F.radii.map((r) => (
+          <figure key={r.k} style={{ margin: 0, textAlign: 'center' }}>
+            <div style={{ width: 72, height: 72, background: 'var(--color-bg-muted)', border: '1px solid var(--color-border-input)', borderRadius: r.v }} />
+            <figcaption style={{ ...mono, marginTop: 6 }}>{r.k} {r.v}</figcaption>
+          </figure>
+        ))}
+      </div>
+      <Table head={['component', 'default', 'token', 'setting']} rows={F.radiusMap.map((r) => [r.c, r.d, <code style={mono}>{r.t}</code>, r.m])} />
+    </div>
+  ),
+}
+
+export const Motion: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Motion</h1>
+      <Table head={['what', 'duration', 'easing', 'property', 'reduced motion']} rows={F.motion.map((m) => [m.k, m.d, <code style={mono}>{m.e}</code>, m.p, m.r])} />
+    </div>
+  ),
+}
+
+type ThemeArgs = Required<NovaThemeSettings>
+export const ThemeSettings: StoryObj<ThemeArgs> = {
+  args: { ...THEME_DEFAULTS, colorPrimary: '#111111' },
+  parameters: { docs: { description: { story: 'Level 1 theme settings with their persisted IDs (e.g. buttonRadius none · small · medium · pill). A default rung writes nothing.' } } },
+  render: (args) => (
+    <NovaProvider theme={args} locale="en">
+      <div style={page}>
+        <h1 className="nv-h1">Settings preview</h1>
+        <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', alignItems: 'center' }}>
+          <Button>Add to cart</Button>
+          <Button variant="secondary">View all</Button>
+          <Button variant="tertiary">Learn more</Button>
+          <Chip selected>Selected</Chip>
+          <Badge tone="sale">−21%</Badge>
+          <Badge tone="new">New</Badge>
+          <Icon name="bag" size="lg" />
+        </div>
+        <div style={{ maxWidth: 320 }}><Input placeholder="you@example.com" aria-label="Email" /></div>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: 16 }}>
+          {[0, 1, 2].map((i) => <div key={i} style={{ aspectRatio: '1', background: 'var(--color-media-bg)', borderRadius: 'var(--radius-media)' }} />)}
+        </div>
+      </div>
+    </NovaProvider>
+  ),
+}
+
+export const Borders: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Borders</h1>
+      <p style={muted}>Hairlines separate; they never decorate. Controls use the 3:1 input grey; focus is a fixed 2px ring that is never the brand.</p>
+      <Table
+        head={['role', 'token', 'sample']}
+        rows={[
+          ['Decorative divider', '--color-border · --border-subtle', <span style={{ display: 'block', width: 160, borderTop: 'var(--border-subtle)' }} />],
+          ['Control boundary (≥ 3:1)', '--color-border-input · --input-border', <span style={{ display: 'block', width: 160, height: 32, border: 'var(--input-border)', borderRadius: 'var(--input-radius)' }} />],
+          ['Region control (12A)', '--color-border-control', <span style={{ display: 'block', width: 160, height: 32, border: '1px solid var(--color-border-control)', borderRadius: 'var(--radius-md)' }} />],
+          ['Selected / emphasis', '--color-border-emphasis · --border-strong', <span style={{ display: 'block', width: 160, borderTop: 'var(--border-strong)' }} />],
+          ['Checkbox / radio stroke', '--border-width-control (1.5px)', <span style={{ display: 'block', width: 20, height: 20, border: 'var(--border-width-control) solid var(--color-border-input)', borderRadius: 'var(--radius-sm)' }} />],
+          ['Focus ring', '--color-focus · 2px + 2px offset', <span style={{ display: 'block', width: 120, height: 32, borderRadius: 'var(--radius-md)', outline: '2px solid var(--color-focus)', outlineOffset: 2 }} />],
+        ]}
+      />
+    </div>
+  ),
+}
+
+export const Elevation: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Elevation</h1>
+      <p style={muted}>Nothing in the page flow casts a shadow. Shadows exist only for surfaces that float over content, and every floating surface sits on one z-index ladder.</p>
+      <div style={{ display: 'flex', gap: 24, flexWrap: 'wrap' }}>
+        {(['popover', 'floating', 'drawer', 'modal'] as const).map((k) => (
+          <figure key={k} style={{ margin: 0, display: 'grid', gap: 8 }}>
+            <div style={{ width: 160, height: 96, background: 'var(--color-bg-elevated)', borderRadius: 'var(--radius-md)', boxShadow: `var(--shadow-${k})` }} />
+            <figcaption style={mono}>--shadow-{k}</figcaption>
+          </figure>
+        ))}
+      </div>
+      <h2 className="nv-h3">Layers (one ladder)</h2>
+      <Table head={['token', 'value']} rows={F.tokens.filter((t) => t.family === 'layer').map((t) => [<code style={mono}>{t.name}</code>, t.value])} />
+    </div>
+  ),
+}
+
+export const Breakpoints: Story = {
+  render: () => (
+    <div style={page}>
+      <h1 className="nv-h2">Breakpoints &amp; containers</h1>
+      <Table
+        head={['width', 'role', 'page gutter']}
+        rows={[
+          ['390', 'reference phone (below 640: phone layout)', '16'],
+          ['640 · --bp-tablet', 'tablet', '24'],
+          ['1024 · --bp-desktop', 'desktop layout (nav, mega menu, 12-column grids)', '40'],
+          ['1280', 'reference desktop · standard container', '40'],
+        ]}
+      />
+      <h2 className="nv-h3">Containers</h2>
+      <Table head={['width', 'max']} rows={F.containers.map((c) => [c.k, c.v])} />
+      <h2 className="nv-h3">Media ratios</h2>
+      <div style={{ display: 'flex', gap: 16, alignItems: 'end', flexWrap: 'wrap' }}>
+        {F.ratios.map((r) => (
+          <figure key={r.k} style={{ margin: 0, width: 140 }}>
+            <div style={{ aspectRatio: r.v, background: 'var(--color-media-bg)', borderRadius: 'var(--radius-media)' }} />
+            <figcaption style={{ ...mono, marginTop: 6 }}>{r.k} {r.v}</figcaption>
+          </figure>
+        ))}
+      </div>
+      <h2 className="nv-h3">Container</h2>
+      <div style={{ display: 'grid', gap: 8 }}>
+        {(['narrow', 'content', 'standard', 'wide', 'full'] as const).map((w) => (
+          <Container key={w} width={w}>
+            <div style={{ background: 'var(--color-fg)', color: 'var(--color-bg)', fontFamily: 'var(--font-mono)', fontSize: 11, padding: '4px 8px' }}>{w}</div>
+          </Container>
+        ))}
+      </div>
+    </div>
+  ),
+}
+
+/** Nova 01 principles (shown on Colors). */
+export const PRINCIPLES = F.principles