\n \n \n`;\n\nexport default async function (req: Request): Promise {\n const { pathname } = new URL(req.url);\n\n // view-source link → redirect to this val\n if (pathname === \"/source\") {\n return new Response(null, {\n status: 302,\n headers: { Location: parseVal().links.self.val },\n });\n }\n\n // serve any val file (transpiled to JS for .ts/.tsx) so the browser can run\n // the client bundle and its relative imports (./app.tsx, ../mod.ts, ...).\n if (pathname.endsWith(\".ts\") || pathname.endsWith(\".tsx\")) {\n return serveFile(pathname, import.meta.url);\n }\n\n return new Response(html, {\n headers: { \"content-type\": \"text/html; charset=utf-8\" },\n });\n}\n",[],[456,448],"preview","f0f91022-793e-452e-a4a9-9717a44e4e16","client.tsx","019f624e-0dc9-701d-a888-3eb400442221",["D",1784060710350],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client\";\nimport { Preview } from \"./app.tsx\";\n\nconst root = document.getElementById(\"root\")!;\ncreateRoot(root).render();\n",[],[456,458],"7549b764-54d8-4e1f-b971-70bed8f4919f","app.tsx","019f624e-0dc9-701d-a888-38eecc264607",["D",1784061317926],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\n\n// The real library — imported, never modified.\nimport { Button, cn, KylaProvider, tw, useKylaMode } from \"../mod.ts\";\nimport type { ColorToken } from \"../src/theme/tw.ts\";\nimport type { Mode } from \"../src/theme/provider.tsx\";\n\nconst VARIANTS = [\"primary\", \"subtle\", \"ghost\", \"danger\"] as const;\nconst SIZES = [\"sm\", \"md\", \"lg\"] as const;\n\nconst COLOR_TOKENS: ColorToken[] = [\n \"base\",\n \"elevated\",\n \"recessed\",\n \"fg\",\n \"fg-muted\",\n \"line\",\n \"hairline\",\n \"accent\",\n \"accent-fg\",\n \"danger\",\n];\n\n/** A titled section on an elevated card. */\nfunction Section({\n title,\n subtitle,\n children,\n}: {\n title: string;\n subtitle?: string;\n children: React.ReactNode;\n}) {\n return (\n \n

\n {title}\n

\n {subtitle && (\n

\n {subtitle}\n

\n )}\n

{children}

\n \n );\n}\n\n/** Small monospace label. */\nfunction Tag({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n\n/** Light / dark / system switcher, driven by the library's own mode hook. */\nfunction ModeSwitcher() {\n const { mode, setMode } = useKylaMode();\n const modes: Mode[] = [\"light\", \"dark\", \"system\"];\n return (\n

\n Mode\n \n {modes.map((m) => (\n setMode(m)}\n className={cn(\n \"rounded-md px-3 py-1 text-sm font-medium capitalize transition\",\n m === mode\n ? cn(tw.bg(\"accent\"), tw.text(\"accent-fg\"))\n : cn(tw.text(\"fg\"), tw.bg(\"elevated\", \"hover\")),\n )}\n >\n {m}\n \n ))}\n

\n \n );\n}\n\nfunction ButtonMatrix() {\n return (\n

\n {/* variants × sizes */}\n {VARIANTS.map((variant) => (\n

\n \n {variant}\n \n variant=\"{variant}\"\n

\n {SIZES.map((size) => (\n \n ))}\n \n

\n ))}\n

\n );\n}\n\nfunction TokenSwatches() {\n return (\n

\n {COLOR_TOKENS.map((token) => (\n \n \n

\n {token}\n

\n --kyla-{token}\n

\n ))}\n \n );\n}\n\nfunction WipBanner() {\n return (\n \n

\n 🚧 Preview / work in progress. This page renders the\n {\" \"}\n current{\" \"}\n Kylä UI surface — one component (Button) plus the theme system. Palette\n values are provisional and more components are on the way.\n

\n \n );\n}\n\nexport function Preview() {\n return (\n \n \n

\n {/* header */}\n

\n Kylä UI\n

\n Consistently styled components for Val Town apps. (Kylä ·\n Finnish for “village”.)\n

\n \n

\n\n \n\n \n \n \n\n \n

\n alert(\"Saved! (from Kylä Button)\")}\n >\n Save\n \n \n \n \n

\n \n\n \n \n \n\n \n

\n ✅ In place\n

Styling core — cn / tw / variants
KylaProvider + light / dark / system mode
Semantic design tokens
Button

\n 🔜 To come\n

The rest of the v1 component set
The real, AA-checked palette
Spacing / radius / type scales
Radix-backed components (e.g. Dialog)

\n \n\n \n Preview is illustrative — not a stable API.\n \n view source\n \n \n

\n \n \n );\n}\n",[],[456,465],"e751100d-bf89-46e2-be6a-fe5d0b88ad95",["D",1784060710350],[285,286,287],[456],["D",1784060710350],[],[18,79],"10fa431e-08af-4454-8b09-191120bc679a","val-town-style-guide.md","019f624e-0dc9-701d-a888-2aec8ef86e7d",["D",1784060710350],"# Val Town UI style guide — design tokens reference\n\nResearch reference for ADR-0005\n(`docs/adr/0005-val-town-visual-language-default-theme.md`) and the\nscales/palette PRD (`docs/issues/structural-scales-palette/spec.md`). Extracted\n2026-07-06.\n\n## What was found, and from where\n\nVal Town's marketing/app site is a **Remix SSR** application, so a plain HTTP\n`GET` of each `https://www.val.town/_ui/` page returns the **real,\nserver-rendered component markup** — every element with its full Tailwind\nutility class list. The token layer lives in the site's compiled Tailwind **v4**\nstylesheet, linked from every page and served from\n`https://static2.esm.town/assets/tailwind-.css` (current hash at\nextraction time: `tailwind-Dy1Hj0e7.css`). That file contains the Tailwind v4\n`@theme` block (the full `--color-*` scale in **oklch**, plus `--spacing`,\n`--radius-*`, `--text-*`, `--font-weight-*`) **and** Val Town's own semantic\ncolor aliases split across the light `@theme`/`:root` layer and a `.dark {…}`\nblock.\n\n**This is the primary, authoritative source** and it is machine-readable\nend-to-end: component class lists → utility classes → resolved token values, all\nfrom the live site.\n\nA **secondary** source — the val **`dcm31/townie-mobile`**, `frontend/style.css`\n(read via the Val Town MCP `read_file`) — is the distilled token set its author\nhand-fed to Fable. It agrees with the live site on the design _language_\n(slate + sky, IBM Plex Sans, iA Writer Quattro eyebrows, dark-ink-on-accent, 8px\nradius) but its literal hex values are **Tailwind v3** (e.g.\n`--vt-sky: #38bdf8`), which differ numerically from the live site's Tailwind\n**v4** oklch derivations (`sky-400` → `#00bcff`). Reconciliation is called out\nbelow.\n\n### Colour-space note\n\nThe live tokens are **oklch** (Tailwind v4). Every hex in this doc is a\n**computed** oklch→sRGB conversion (D65, standard sRGB transfer). Hexes are\nlabelled as computed; the oklch string is the source-of-truth value. Contrast\nratios are likewise computed from those sRGB values.\n\n### Reconciliation: townie-mobile (v3 hex) vs live `_ui` (v4 oklch)\n\n| Role | townie `style.css` (v3 literal) | live `_ui` (v4 oklch → computed hex) | Agree? |\n| ----------- | --------------------------------------- | --------------------------------------------------- | -------------------------------------- |\n| Accent | `--vt-sky #38bdf8` (sky-400) | `sky-400` `oklch(74.6% .16 232.661)` → `#00bcff` | Same token name; v4 hex more saturated |\n| Deep accent | `--vt-sky-deep #0369a1` (sky-700) | `sky-700` `oklch(50% .134 242.749)` → `#0069a8` | Same name, v4 slightly different |\n| Border | `--vt-border #e2e8f0` (slate-200) | `slate-200` `oklch(92.9% .013 255.508)` → `#e2e8f0` | **Identical** |\n| Accent-fg | send btn `text-sky-950` on `bg-sky-400` | primary btn `text-sky-950` on `bg-sky-400` | **Identical convention** |\n\nBoth confirm **VT = Tailwind slate + sky**. Treat the **live `_ui` v4 oklch\nvalues as current source of truth**; townie's hexes are the older/hand-distilled\nvariant.\n\n---\n\n## 1. Color palette\n\n### 1a. Val Town semantic aliases (the actual theme layer)\n\nVT defines exactly **five** semantic color tokens, each aliased to a raw scale\nstep, with a light default (in the `@theme`/root layer) and a `.dark` override.\nSource: `tailwind-Dy1Hj0e7.css`, `:root`/`@theme` and `.dark{…}` blocks\n(verbatim property names).\n\n| Semantic token | Light → raw | Light hex (computed) | Dark → raw | Dark hex (computed) |\n| -------------------- | ------------------- | -------------------- | ------------------- | ------------------- |\n| `--color-background` | `--color-white` | `#ffffff` | `--color-black` | `#000000` |\n| `--color-text` | `--color-black` | `#000000` | `--color-white` | `#ffffff` |\n| `--color-border` | `--color-slate-200` | `#e2e8f0` | `--color-slate-700` | `#314158` |\n| `--color-muted` | `--color-gray-600` | `#4a5565` | `--color-gray-300` | `#d1d5dc` |\n| `--color-shadow` | `--color-gray-50` | `#f8fafc`* | `--color-gray-900` | `#101828`* |\n\nVerbatim:\n`.dark{--color-text:var(--color-white);--color-background:var(--color-black);--color-border:var(--color-slate-700);--color-muted:var(--color-gray-300);--color-shadow:var(--color-gray-900)}`\nand light\n`--color-text:var(--color-black);--color-background:var(--color-white);--color-border:var(--color-slate-200);--color-muted:var(--color-gray-600);--color-shadow:var(--color-gray-50)`.\n(*`--color-shadow` gray hexes are approximate; used as a shadow tint, not a\nsurface.)\n\nNotable: **dark-mode background is true black** (`#000`) with true-white text —\nan OLED-style maximum-contrast choice, not a dark-gray. There is **no** semantic\ntoken for elevated / recessed surfaces or for accent — those come from raw\n`sky-*`/`slate-*` utilities in the components (§1b, §5).\n\n### 1b. Raw scale steps used across components (Tailwind v4 oklch)\n\nEvery value below is a class observed in live `_ui` component markup. oklch is\nthe source value; hex is computed. Full scales for slate/sky/rose/emerald/gray\nexist in the file; these are the steps actually referenced.\n\n**Neutrals — `slate` (structure) and `gray` (muted text)**\n\n| Token | oklch | Hex (computed) | Role in `_ui` |\n| ----------- | --------------------------- | -------------- | ------------------------------------------------------- |\n| `white` | `#fff` | `#ffffff` | Base surface (light) |\n| `slate-50` | `oklch(98.4% .003 247.858)` | `#f8fafc` | Secondary button fill (light); read-only input bg |\n| `slate-100` | `oklch(96.8% .007 247.896)` | `#f1f5f9` | Default button fill; soft/filled input fill (light) |\n| `slate-200` | `oklch(92.9% .013 255.508)` | `#e2e8f0` | **Border** (`--color-border` light) |\n| `slate-300` | `oklch(86.9% .022 252.894)` | `#cad5e2` | Input border (light); hover border on filled input |\n| `slate-400` | `oklch(70.4% .04 256.788)` | `#90a1b9` | Input hover border (light) |\n| `slate-700` | `oklch(37.2% .044 257.287)` | `#314158` | **Border** (`--color-border` dark); input border (dark) |\n| `slate-800` | `oklch(27.9% .041 260.031)` | `#1d293d` | Default button fill (dark); soft input fill (dark) |\n| `slate-900` | `oklch(20.8% .042 265.755)` | `#0f172b` | Secondary button fill (dark); read-only input bg (dark) |\n| `slate-950` | `oklch(12.9% .042 264.695)` | `#020618` | (deepest neutral) |\n| `gray-300` | `oklch(87.2% .01 258.338)` | `#d1d5dc` | **Muted text** (`--color-muted` dark) |\n| `gray-600` | `oklch(44.6% .03 256.802)` | `#4a5565` | **Muted text** (`--color-muted` light) |\n| `black` | `#000` | `#000000` | Text (light); base (dark) |\n\n**Accent — `sky`**\n\n| Token | oklch | Hex (computed) | Role in `_ui` |\n| --------- | --------------------------- | -------------- | ---------------------------------------------- |\n| `sky-50` | `oklch(97.7% .013 236.62)` | `#f0f9ff` | Secondary/clear button hover fill (light) |\n| `sky-100` | `oklch(95.1% .026 236.824)` | `#dff2fe` | Default button hover fill; active card (light) |\n| `sky-200` | `oklch(90.1% .058 230.902)` | `#b8e6fe` | Default button active; accent text (dark) |\n| `sky-300` | `oklch(82.8% .111 230.318)` | `#74d4ff` | **Input focus ring** |\n| `sky-400` | `oklch(74.6% .16 232.661)` | `#00bcff` | **Primary button fill (light)** — the accent |\n| `sky-500` | `oklch(68.5% .169 237.323)` | `#00a6f4` | **Button focus ring**; input focus border |\n| `sky-700` | `oklch(50% .134 242.749)` | `#0069a8` | **Primary button fill (dark)** |\n| `sky-800` | `oklch(44.3% .11 240.79)` | `#00598a` | Accent text on light (hover/aria-current) |\n| `sky-950` | `oklch(29.3% .066 243.157)` | `#052f4a` | **Text on `sky-400` primary fill (light)** |\n\n**Danger — `rose`; Success — `emerald`**\n\n| Token | oklch | Hex (computed) | Role |\n| ------------- | --------------------------- | -------------- | ----------------------------------------- |\n| `rose-50` | `oklch(96.9% .015 12.422)` | `#fff1f2` | Private privacy-badge bg |\n| `rose-300` | `oklch(81% .117 11.638)` | `#ffa1ad` | **Danger button fill (light)** |\n| `rose-400` | `oklch(71.2% .194 13.428)` | `#ff637e` | Danger button hover; focus ring |\n| `rose-800` | `oklch(45.5% .188 13.697)` | `#a50036` | **Danger button fill (dark)**; badge text |\n| `rose-950` | `oklch(27.1% .105 12.094)` | `#4d0218` | **Text on danger fill (light)** |\n| `emerald-100` | `oklch(95% .052 163.051)` | `#d0fae5` | Public privacy-badge bg |\n| `emerald-400` | `oklch(76.5% .177 163.223)` | `#00d492` | **Success/green button fill (light)** |\n| `emerald-950` | `oklch(26.2% .051 172.552)` | `#002c22` | Text on success fill (light) |\n\nAlso referenced: `red-300`/`red-700` for input invalid rings; `amber-*` and\n`blue-*` for callout variants; `orange-*` for the \"unlisted\" privacy badge.\n\n---\n\n## 2. Spacing scale\n\n`--spacing: .25rem` → **base unit 4px** (Tailwind v4 default; all\n`gap-*`/`p-*`/`h-*`/`w-*` utilities are multiples of it). No bespoke VT spacing\ntokens. Container widths are also defined\n(`--container-xs 20rem … --container-7xl 80rem`) if a max-width scale is needed.\n\nComponent-level spacing is captured per component in §5.\n\n---\n\n## 3. Border-radius scale\n\nFrom the `@theme` block (verbatim):\n\n| Token | rem | px | Where used in `_ui` |\n| -------------- | --------- | ------- | ------------------------------------------------------------------------------ |\n| `--radius-xs` | `.125rem` | 2px | — |\n| `--radius-sm` | `.25rem` | 4px | — |\n| `--radius-md` | `.375rem` | 6px | — |\n| `--radius-lg` | `.5rem` | **8px** | **Buttons, inputs, selects, textareas, cards, sidebar panels** (the workhorse) |\n| `--radius-xl` | `.75rem` | 12px | Large buttons; callouts |\n| `--radius-2xl` | `1rem` | 16px | — |\n| `--radius-3xl` | `1.5rem` | 24px | — |\n| `rounded-full` | 9999px | — | Privacy badges, pills |\n\nCanonical control radius = **8px (`rounded-lg`)**; large controls step up to\n12px (`rounded-xl`). Matches townie's \"8px radius.\"\n\n---\n\n## 4. Typography\n\n**Font families** (from `tailwind-.css` `html` rule + `app.css`\n`@font-face`)\n\n| Role | Stack | Source |\n| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |\n| Sans (body/UI) | `\"IBM Plex Sans\", -apple-system, sans-serif` | `html,:host{…font-family:IBM Plex Sans,-apple-system,sans-serif;line-height:1.5}` |\n| Mono | `\"iA Writer Mono\", \"Menlo\", \"Consolas\", \"ui-monospace\", monospace` | `--font-mono` |\n| Eyebrow / display | `\"iA Writer Quattro\"` (weights 400/700, normal+italic) | `app.css` `@font-face` blocks |\n\n**Type scale** (`--text-*` with paired `--line-height`, verbatim)\n\n| Token | size | line-height (computed) | approx px |\n| ----------- | ----------------- | ---------------------------- | --------- |\n| `text-xs` | `.75rem` (12px) | `calc(1 / .75)` = 1.333 | 12 / 16 |\n| `text-sm` | `.875rem` (14px) | `calc(1.25 / .875)` = 1.429 | 14 / 20 |\n| `text-base` | `1rem` (16px) | `1.5` | 16 / 24 |\n| `text-lg` | `1.125rem` (18px) | `calc(1.75 / 1.125)` = 1.556 | 18 / 28 |\n| `text-xl` | `1.25rem` (20px) | `calc(1.75 / 1.25)` = 1.4 | 20 / 28 |\n| `text-2xl` | `1.5rem` (24px) | `calc(2 / 1.5)` = 1.333 | 24 / 32 |\n| `text-3xl` | `1.875rem` (30px) | `1.2` | 30 / 36 |\n\nControls (buttons/inputs) default to `text-sm` (14/20). `text-[11px]` is used\nfor privacy badges. Default body line-height is `1.5`.\n\n**Font weights** (`--font-weight-*`): normal 400, medium 500, semibold 600, bold\n700, extrabold 800. Buttons are **`font-bold` (700)**; badges are\n**`font-semibold` (600)**; inputs/selects `font-normal` (400).\n\n---\n\n## 5. Component-level styling specs\n\nAll class lists below are verbatim from live `_ui` SSR markup\n(`www.val.town/_ui/`), condensed to the meaningful tokens (dropped the\nlong `[&:not([disabled])]:` guards where they only wrap a hover/active listed\nhere).\n\n### Button (`/_ui/button`)\n\n**Base:**\n`inline-flex items-center justify-center gap-x-2 shrink-0 whitespace-nowrap\nselect-none cursor-pointer disabled:cursor-not-allowed disabled:opacity-50 outline-0\nfocus-visible:ring-2 transition font-bold`\n\n**Sizes:** `sm` = `text-sm h-8 px-3 rounded-lg` · `md`(default) =\n`text-sm h-10 px-4\nrounded-lg` · `lg` = `text-base h-12 px-5 rounded-xl`.\nIcon-only appends `!px-0 w-8` (sm) / `w-10` (md).\n\n**Focus ring:** `ring-2 ring-sky-500` (rose-400 for danger, emerald-500 for\ngreen, slate-700 for blend).\n\n| Variant | Light fill / text / border | Light hover → active | Dark fill / text | Dark hover → active |\n| ----------- | --------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |\n| `default` | `bg-slate-100 text-slate-800` | `bg-sky-100 text-sky-800` → `bg-sky-200` | `bg-slate-800 text-slate-200` | `bg-sky-900 text-sky-200` → `bg-slate-800` |\n| `primary` | `bg-sky-400 text-sky-950` border-transparent | `bg-sky-500` → `bg-sky-600` | `bg-sky-700 text-white` | `bg-sky-600` → `bg-sky-700` |\n| `secondary` | `bg-slate-50 text-black border-slate-200` | `bg-sky-50 text-sky-800 border-sky-200` → `bg-sky-100` | `bg-slate-900 text-white border-slate-800` | `bg-sky-900 text-sky-200 border-sky-500` → `bg-slate-800` |\n| `clear` | `text-black` (no fill) | `text-sky-800 bg-sky-500/10` → `bg-sky-500/5` | `text-white` | `text-sky-200 bg-sky-500/40` → `bg-sky-500/20` |\n| `danger` | `bg-rose-300 text-rose-950` border-transparent | `bg-rose-400` → `bg-rose-500` | `bg-rose-800 text-white` | `bg-rose-700` → `bg-rose-800` |\n| `green` | `bg-emerald-400 text-emerald-950` border-transparent | `bg-emerald-500` → `bg-emerald-600` | `bg-emerald-700 text-white` | `bg-emerald-600` → `bg-emerald-700` |\n| `blend` | `mix-blend-color-burn bg-slate-500 text-black border-slate-700` | `bg-slate-600` → `bg-slate-700` | `mix-blend-color-dodge bg-slate-500 text-white border-slate-400` | `bg-slate-400` → `bg-slate-300` |\n\nKey convention: **primary/danger/green fills use a dark-ink-on-bright-color\npairing in light mode** (`text-sky-950`/`text-rose-950`/`text-emerald-950`) and\nflip to **white ink on a deeper fill in dark mode** (`text-white` on\n`sky-700`/`rose-800`/`emerald-700`).\n\n### Input / Select / Textarea (`/_ui/input`, `/select`, `/textarea`)\n\n**Base:**\n`block w-full border outline-0 transition disabled:cursor-not-allowed\ndisabled:opacity-50 text-sm h-10 px-3 rounded-lg`.\nsm = `h-8 px-2`.\n\n- **Default variant:** `bg-background text-black border-slate-300`, hover\n `border-slate-400`; dark `text-white border-slate-700`, hover\n `border-slate-600`. (Note it uses the semantic `bg-background` token, so field\n bg = white/black by mode.)\n- **Filled/soft variant:** `bg-slate-100 text-black border-transparent`, hover\n `border-slate-300`; dark `bg-slate-800 text-white`, hover `border-slate-700`.\n- **Focus:** `focus-visible:ring-2 focus-visible:ring-sky-300` +\n `focus-visible:border-sky-500`.\n- **Invalid** (`aria-invalid`/`user-invalid`): `ring-red-300 border-red-300`\n (dark `ring-red-700 border-red-700`), hover `border-red-400`.\n- **Read-only:** `read-only:bg-slate-50` (dark `bg-slate-900`).\n- **Disabled:** `opacity-50 cursor-not-allowed`.\n- **Select** adds `appearance-none pr-10 cursor-pointer`; **Textarea** adds\n `h-auto py-2`; a `code` content variant adds `font-mono`.\n\n### Card (`/_ui/card`)\n\nSurface uses `bg-background`, `border`, `rounded-lg`, `transition`; hover\n`hover:border-blue-400 dark:hover:border-blue-600 hover:shadow-lg` (note: cards\nhover **blue**, not sky). BigCard is the larger variant.\n\n### Callout (`/_ui/callout`)\n\n**Base:**\n`flex flex-wrap items-center gap-2 pl-4 pr-2 py-2 min-h-12 text-sm rounded-xl\nborder`.\nColor variants (light → dark):\n\n- info/blue: `text-blue-800 bg-blue-50 border-blue-100` →\n `text-blue-200 bg-blue-950 border-blue-900`\n- warning/amber: `text-amber-800 bg-amber-100 border-amber-200` →\n `text-amber-100 bg-amber-950 border-amber-900`\n\n### Privacy Badge (`/_ui/privacy-badge`)\n\n**Base:**\n`inline-flex items-center justify-center font-semibold text-[11px] h-5\nmin-w-[56px] rounded-full px-2`.\nVariants:\n\n- public: `text-emerald-800 bg-emerald-100 saturate-50`\n- private: `text-rose-800 bg-rose-50`\n- unlisted: `text-orange-800 bg-orange-50`\n\n### Dropdown / panel (`/_ui/dropdown`)\n\nFloating panel: `bg-background rounded-lg shadow-lg` (width `w-64`, margin\n`m-2`).\n\n### Shadows\n\nTailwind defaults (`shadow-lg` on cards/panels/dropdowns). The `--color-shadow`\nsemantic token (gray-50 light / gray-900 dark) tints shadow color per mode.\ntownie additionally used custom `0 2px 12px rgba(15,23,42,.05)` composer shadows\n(slate-tinted).\n\n---\n\n## 6. Mapping onto Kylä tokens\n\nKylä `--kyla-*` → Val Town values. **Both light and dark are now\nprimary-sourced** from the live `_ui` Tailwind v4 theme (semantic aliases +\ncomponent usage). Hexes are computed from oklch.\n\n| Kylä token | VT source | Light | Dark | Notes |\n| ------------------------------ | -------------------------------------- | ------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--kyla-base` | `--color-background` | `#ffffff` (white) | `#000000` (**true black**) | VT dark base is pure black (OLED), not gray. |\n| `--kyla-elevated` | _(no VT token)_ | `#ffffff` + shadow | `#0f172b` (`slate-900`) | VT has no elevated-fill token in light; raise via `shadow-lg`. In dark, `slate-900` (secondary-button fill) is the natural raised surface. See Gaps. |\n| `--kyla-recessed` | component `bg-slate-100`/`bg-slate-50` | `#f1f5f9` (`slate-100`) | `#1d293d` (`slate-800`) | Filled input / default-button wells. `slate-50 #f8fafc` is a shallower recess (secondary btn, read-only). |\n| `--kyla-fg` | `--color-text` | `#000000` | `#ffffff` | true-black / true-white. |\n| `--kyla-fg-muted` | `--color-muted` | `#4a5565` (`gray-600`) | `#d1d5dc` (`gray-300`) | VT's real, now-sourced muted token — AA-safe both modes (§7). Supersedes the earlier `slate-700` guess; the two are near-equivalent (`gray-600` 7.56:1, `slate-700` 10.36:1) — either is fine, `gray-600` is the literal VT value. Definitely **not** `slate-400`. |\n| `--kyla-line` | `--color-border` | `#e2e8f0` (`slate-200`) | `#314158` (`slate-700`) | The one VT border token. Note controls use `slate-300`/`slate-700` for _field_ borders — a touch stronger than the panel border. |\n| `--kyla-hairline` | _(no VT token)_ | `#f1f5f9` (`slate-100`) | `#1d293d` (`slate-800`) | VT has no lighter-than-border token; propose one step lighter (light) / the elevated fill (dark). See Gaps. |\n| `--kyla-accent` | primary button fill | `#00bcff` (`sky-400`) | `#0069a8` (`sky-700`) | VT's accent **changes by mode**: bright sky-400 in light, deeper sky-700 in dark. Focus rings use `sky-500 #00a6f4`. |\n| `--kyla-accent-fg` | primary button text | `#052f4a` (`sky-950`, dark ink) | `#ffffff` (white) | Dark ink on the bright light-mode fill; white on the deep dark-mode fill. **Never white on sky-400** (§7). |\n| `--kyla-danger` | danger button fill | `#ffa1ad` (`rose-300`) | `#a50036` (`rose-800`) | Pale rose w/ dark ink (light) → deep rose w/ white (dark). |\n| `--kyla-danger-fg` _(implied)_ | danger button text | `#4d0218` (`rose-950`) | `#ffffff` | Kylä has no danger-fg token — see Gaps. |\n| `--kyla-radius` | `--radius-lg` | `8px` | `8px` | Scale 2/4/6/8/12/16/24; large controls 12px. |\n\nScale-level (needed by the PRD):\n\n| Concept | VT value (light = dark unless noted) |\n| --------------- | ----------------------------------------------------------------------- |\n| Spacing base | `--spacing: .25rem` = 4px |\n| Radius scale | 2 / 4 / 6 / 8 / 12 / 16 / 24 px (`xs…3xl`); control default 8 |\n| Sans | `\"IBM Plex Sans\", -apple-system, sans-serif` |\n| Mono | `\"iA Writer Mono\", \"Menlo\", \"Consolas\", \"ui-monospace\", monospace` |\n| Eyebrow/display | `\"iA Writer Quattro\"` (400/700) |\n| Body type | `text-base` 16px / lh 1.5; controls `text-sm` 14/20 |\n| Weights | 400 / 500 / 600 / 700 / 800; buttons 700, badges 600 |\n| Hues | accent = sky · danger = rose · success = emerald · neutral = slate/gray |\n\n---\n\n## 7. Gaps and AA concerns\n\n### Gaps — Kylä tokens with no direct VT semantic equivalent\n\n- **`--kyla-elevated`, `--kyla-recessed`, `--kyla-hairline`:** VT's semantic\n layer is only `background / text / border / muted / shadow`. There is **no**\n token for a second surface level. In light mode VT elevates by shadow over the\n same white; recessed/hairline surfaces come from raw `slate-50`/`slate-100`\n fills at the component level. The proposed values are the observed component\n fills, not named VT tokens — reasonable but an extrapolation.\n- **`--kyla-danger-fg` / accent-fg split:** VT expresses \"ink on a colored fill\"\n per component (dark-950 in light, white in dark) rather than as a token. Also,\n VT uses several distinct accent roles a single\n `--kyla-accent`/`--kyla-accent-fg` can't hold: **fill** (`sky-400`/`sky-700`),\n **focus ring** (`sky-500`, inputs `sky-300`), and **accent text on a surface**\n (`sky-800` light / `sky-200` dark, used for hover/aria-current). Consider\n `--kyla-accent-ring` and `--kyla-accent-text` in addition to fill+fg.\n\n### VT tokens/roles Kylä has no home for\n\n- **`--color-shadow`** (gray-50 light / gray-900 dark) — a mode-aware shadow\n tint; Kylä has no shadow token.\n- **Field border ≠ panel border:** inputs use `slate-300`/`slate-700`, panels\n use `slate-200`/`slate-700` (`--color-border`). Kylä's single `--kyla-line`\n flattens this.\n- **Semantic status set beyond danger:** VT ships `emerald` (success/green\n button, public badge), `amber`/`blue` (callouts), `orange` (unlisted badge).\n Kylä has only `danger`.\n- **`blend` button** (`mix-blend-color-burn`/`-dodge`) — a mode-adaptive\n technique, no token.\n\n### WCAG AA (ratios **computed** from oklch→sRGB; 4.5:1 body, 3:1 large/UI)\n\n| Foreground | Background | Ratio | Verdict |\n| ------------------------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------- |\n| `text` black | `background` white (light) | **21.0:1** | Pass AAA |\n| `text` white | `background` black (dark) | **21.0:1** | Pass AAA |\n| `muted` gray-600 | white (light) | **7.56:1** | Pass |\n| `muted` gray-300 | black (dark) | **14.26:1** | Pass |\n| primary `sky-950` | `sky-400` fill (light) | **6.37:1** | Pass |\n| primary white | `sky-700` fill (dark) | **5.86:1** | Pass |\n| default `slate-800` | `slate-100` fill (light) | **13.34:1** | Pass |\n| default-hover `sky-800` | `sky-100` (light) | **6.53:1** | Pass |\n| danger `rose-950` | `rose-300` fill (light) | **8.19:1** | Pass |\n| danger white | `rose-800` fill (dark) | **7.92:1** | Pass |\n| green `emerald-950` | `emerald-400` fill (light) | **7.83:1** | Pass |\n| `slate-700` (field border/text) | white | **10.36:1** | Pass |\n| **white** | **`sky-400`** (anti-pattern) | **2.18:1** | **FAIL** — do not put white on the light accent; VT correctly uses `sky-950`. |\n\nTakeaways for Kylä:\n\n1. Every default VT foreground/surface pairing clears AA comfortably (5.9–21:1)\n in **both** modes — safe to adopt wholesale.\n2. `--kyla-accent-fg` must be **dark ink (`sky-950`) in light** and **white in\n dark**; a single fixed value can't serve both because `sky-400` needs dark\n ink (white fails at 2.18:1) while `sky-700` needs white.\n3. `--kyla-fg-muted` = `gray-600` (light) / `gray-300` (dark) is AA-safe; keep\n the mode split rather than one value.\n4. Note the deliberate **true-black dark background** — visually aggressive\n (21:1); fine for AA, but worth a conscious call vs a softer\n `slate-950 #020618` if Kylä prefers less glare.\n\n---\n\n## 8. Sources\n\n**Primary — live `_ui` (Remix SSR, plain HTTPS GET; class lists verbatim):**\n\n1. `https://www.val.town/_ui/button`, `/callout`, `/card`, `/dropdown`,\n `/input`, `/select`, `/textarea`, `/forms`, `/privacy-badge` —\n server-rendered component markup with full Tailwind class lists (cited per\n component in §5).\n2. `https://static2.esm.town/assets/tailwind-Dy1Hj0e7.css` — compiled Tailwind\n v4 stylesheet: the `@theme` `--color-*` (oklch) / `--spacing` / `--radius-*`\n / `--text-*` / `--font-weight-*` tokens, the `html` font-family rule, and\n VT's semantic aliases in the root layer + `.dark{…}` block (all quoted\n verbatim in §1a, §3, §4). Hash read from the pages' ``\n tags.\n3. `https://static2.esm.town/assets/_app-*.css` — `@font-face` for iA Writer\n Quattro (400/700, normal+italic).\n\n**Secondary — distilled token set (via Val Town MCP `read_file`):** 4.\n`dcm31/townie-mobile` → `frontend/style.css` — `--vt-sky #38bdf8`,\n`--vt-sky-deep\n #0369a1`, `--vt-border #e2e8f0` (Tailwind **v3** hexes), IBM\nPlex Sans body, iA Writer Quattro eyebrow (10px/700/0.14em uppercase).\nReconciled against the live v4 values in the intro; agrees on token names and\nthe dark-ink-on-accent convention, differs on exact hex.\n\n**Value resolution / conversion:** 5. oklch→sRGB hex and all §7 contrast ratios\nare **computed** (D65 sRGB), not read from a source. oklch strings in §1 are the\nsource-of-truth values.\n\n**Informal, non-verbatim signal (not used for any concrete value in this doc):**\n6. `https://www.val.town/secret-styleguide` — Val Town's broader internal\ncomponent library (Tag, Alert, Link, Pagination, Table, Tooltip, Card/\nProjectCard/BigCard, and ~20 more, many product-specific). Unlike the `_ui/*`\npages, this one does not expose Tailwind class attributes to a plain fetch —\nonly rendered layout/component names are recoverable. Cited in the\n`v1-component-set` PRD's VT Parallelism Audit purely as a qualitative signal\n(e.g. confirming Card is really \"ProjectCard,\" or that \"Tag\" is the closer\nanalog to a generic Badge) — never as a source of hex/class values the way §1–§5\nare.\n\nNothing here is invented: every token traces to a CSS property name or a\ncomponent class list; every hex/ratio is a labelled computation from a sourced\noklch value.\n",[],[18,90,479],["D",1784060710350],[282],[18,90],"8fe8f09b-5940-4ff9-85b6-f3c675b202fa","spec.md","019f624e-0dc9-701d-a888-1de7d15dfe10","019f624e-0dc9-701d-a888-2334f1f83dda",["D",1784060710350],"# PRD: v1 zero-dependency component set\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Builds out the rest of the v1 component inventory (see the\n> [roadmap](../../roadmap.md)), following the `Button` reference. Depends on the\n> [structural scales & palette](../structural-scales-palette/spec.md) foundation\n> for spacing/type. Excludes the Radix-backed `Dialog`\n> ([its own PRD](../dialog-radix/spec.md)).\n\n## Problem Statement\n\nKylä ships exactly one component (`Button`). To build a real app — even the todo\nStarter — a consumer needs text, layout, form, and container primitives. Without\nthem they drop to raw HTML styled with hand-written Twind, which reintroduces\nthe per-app inconsistency Kylä exists to prevent, and loses the bounded\naccessibility guarantees (label association, focus ring, semantic elements) that\ncome baked into Kylä components.\n\n## Solution\n\nShip the v1 zero-dependency visual component set plus the one styled-native\ncomponent, each authored exactly like `Button`: typed variant props mapped to\ntokens via `variants()`, a semantic HTML element, forwarded ref + rest props, a\ntoken-based visible focus ring where interactive, an escape-hatch `className`\nmerged last via `cn()`, and ADR-0003's bounded accessibility baseline. Spacing\nand type come from the structural scale tokens, so the set is consistent with\nitself and with anything built on top of it.\n\n**Inventory:** `Text`/`Heading`, `Card`, `Input`, `Textarea`, `Label`, `Badge`,\n`Stack`, `Box`, `Divider`, and styled-native `Select` — plus a **revision slice\nfor** `Button`, closing the VT variant/state coverage gap flagged by ADR-0005's\ncoverage-parity clause (the roadmap marks `Button` \"Built,\" but built ≠ at\nparity).\n\n## User Stories\n\n1. As a consumer, I want a `Text` component with typed size/weight/tone props,\n so that body copy uses the type scale without me choosing `text-*` classes.\n2. As a consumer, I want a `Heading` component (or `Text as=\"h1\">`), so that\n headings are semantic and on-scale.\n3. As a consumer, I want a `Card` with surface and padding variants, so that I\n can group content on an elevated surface consistently.\n4. As a consumer, I want an `Input` with a visible token focus ring and disabled\n state, so that text entry looks and behaves on-system.\n5. As a consumer, I want a `Textarea` matching `Input`, so that multi-line entry\n is consistent with single-line.\n6. As a consumer, I want a `Label` that associates with a field via `htmlFor`,\n so that clicking the label focuses the input and screen readers announce it.\n7. As a consumer, I want a `Badge` with typed tones, so that I can show\n status/labels on-system.\n8. As a consumer, I want a `Stack` layout primitive with a direction and a gap\n drawn from the spacing scale, so that I lay out children without hand-writing\n flex + gap classes.\n9. As a consumer, I want a `Box` primitive, so that I have a styled generic\n container with the escape hatch when no semantic component fits.\n10. As a consumer, I want a `Divider`, so that I can separate content with an\n on-system hairline.\n11. As a consumer, I want a `Select` that looks on-system but keeps native\n ``; sizes matching `Input`. VT adds\n `appearance-none pr-10 cursor-pointer` (§5) — match that base styling.\n- **Dependency:** consumes the scale tokens from the\n [scales PRD](../structural-scales-palette/spec.md). If that lands first,\n components reference scale tokens directly; the spacing/type props map onto\n those steps.\n- **Accessibility (ADR-0003):** real `` ↔ field `id` association;\n correct semantic elements; token visible focus; no broken native keyboard\n behavior; AA contrast inherited from the default palette. Anything needing\n custom ARIA is out — that's the Radix tier.\n- **Public surface unchanged in shape:** finished components + `cn()` +\n Provider. No headless primitives exposed.\n\n## VT Parallelism Audit (ADR-0005 coverage parity)\n\nPer-component record of what the ADR-0005 coverage-parity clause requires: does\na VT counterpart exist, what does it cover, and where does Kylä's plan match,\nintentionally diverge, or have a real gap. Sourced primarily from\n`docs/reference/val-town-style-guide.md` §5 (verbatim `_ui` classes — the\nauthoritative source). Where a component's only VT signal comes from\n`val.town/secret-styleguide` (Val Town's broader internal component library, not\nthe sourced `_ui` reference), that's called out explicitly as informal — that\npage doesn't expose class attributes over a plain fetch, so nothing from it is a\nverbatim spec the way §5's `_ui` entries are.\n\n| Kylä component | VT counterpart | Parity status |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Button` | `/_ui/button` | **Gap, tracked** — [ticket 04](issues/04-button-variant-parity.md): 4 of 7 color variants covered, icon-only sizing missing. |\n| `Text`/`Heading` | No componentized VT equivalent; VT's type scale/weights (§4) apply directly. `secret-styleguide`'s \"Page Heading\" is a same-shaped signal (large heading at two sizes) but not a sourced spec. | **No gap to close** — use VT's type-scale steps for `size`/`weight`; there's no VT variant count to match since VT doesn't ship this as a reusable component. |\n| `Card` | `/_ui/card` — in VT's own internal library this is the \"ProjectCard\"/\"BigCard\" family (`secret-styleguide`), i.e. a domain-specific project tile, not a generic container primitive. | **Real mismatch, not a coverage gap.** VT's card is flat `bg-background` + `border`, elevating only via `hover:shadow-lg` + `hover:border-blue-400` (§5) — it never uses a raised or inset _fill_. Kylä's `surface: elevated/recessed` assumes a fill-based hierarchy that has no VT counterpart anywhere. This is ADR-0005's already-recorded intentional divergence (Kylä keeps its own richer surface hierarchy), but it means the component's _default_ rendering, not just its token palette, needs a deliberate call — see the Implementation Decisions bullet above. |\n| `Input`/`Textarea` | `/_ui/input`, `/_ui/textarea` | **Gap:** filled/soft variant and `read-only` treatment (§5) not yet in the pinned surface. |\n| `Label` | No dedicated VT primitive — VT associates labels inline within its field markup rather than shipping a standalone component. | **No gap to close** — Kylä's standalone `Label` is a Kylä-only primitive (needed because Kylä's components are more granular than VT's field markup), not a port. |\n| `Badge` | No generic VT Badge. `/_ui/privacy-badge` is a narrow, product-specific analog (public/private/unlisted only). `secret-styleguide`'s \"Tag\" (5 states: neutral/danger/positive/warning/fun, at 3 sizes) is the closer _conceptual_ analog but isn't a sourced spec. | **No gap tracked here** — tone set stays a Kylä design call. If revisited later: `positive` would map onto the already-landed `success` token; `warning`/`fun` have no home in Kylä's current token vocabulary and shouldn't be invented ad hoc inside a component PRD. |\n| `Stack`/`Box`/`Divider` | No VT primitive equivalent. `secret-styleguide`'s \"Bento layout system\" is the nearest signal (a product-layout grid for arranging project cards), not a reusable primitive. | **No gap to close** — Kylä-only design calls, same reasoning as `Badge`. |\n| `Select` | `/_ui/select` | **Gap:** `appearance-none pr-10 cursor-pointer` (§5) not yet in the pinned surface. |\n\nTakeaway: three components (`Text`/`Heading`, `Label`, `Stack`/`Box`/`Divider`)\nand `Badge` have no VT surface to port at all — that's a legitimate parity\nverdict, not an unaudited hole. `Card` is the one case where \"port VT's values\"\nand \"keep Kylä's structure\" actively pull in different directions and needs an\nexplicit default decision, not just a token mapping.\n\n## Testing Decisions\n\n- **What makes a good test:** it asserts the component's _external_ output and\n behavior — the rendered element, the token classes it emits, and its\n accessibility wiring — never the internal `variants()`/`cn()` call. Testing\n the emitted class string via the rendered HTML also guards the silent Twind\n \"missing `color:` hint\" failure, since a dropped hint shows up as an absent\n token class.\n- **Seam (highest available):** **server-render the component to an HTML\n string** (`renderToStaticMarkup`) and assert on the markup. Uniform across the\n set.\n - Assert the semantic element (``, `

`, `<select>`, `<hr>`,\n    heading tags for `Heading`).\n  - Assert token utility classes are present for the chosen variant/tone (e.g.\n    `Badge tone=\"danger\"` emits `bg-[color:var(--kyla-danger)]`).\n  - Assert accessibility wiring: `Label htmlFor` matches an `Input id`; `Input`\n    forwards `type`; `disabled`/`aria-invalid` render; the focus-ring classes\n    are present on interactive components.\n  - Assert `className` wins over the component's own conflicting class (the\n    `cn()` contract).\n- **Modules tested:** every component in `src/components/`.\n- **Prior art:** the harness established by the\n  [scales PRD](../structural-scales-palette/spec.md); if this ships first, it\n  establishes the render-to-HTML harness itself. `Button` is the reference for\n  what a component's rendered output should look like.\n\n## Out of Scope\n\n- `Button` **'s polymorphic rendering** (VT's Router Link / external-link button\n  forms) — needs a Slot-style primitive Kylä doesn't have yet. Flagged by the\n  variant-parity audit, not built here.\n- `Dialog` and any Radix-backed component —\n  [separate PRD](../dialog-radix/spec.md).\n- v1.1+ deferred components: `Checkbox`, `Radio`, `Spinner`, `Alert`, then\n  `Popover`, `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`.\n- The **Gallery** rendering of these components —\n  [separate PRD](../gallery/spec.md).\n- Defining the scales themselves —\n  [scales PRD](../structural-scales-palette/spec.md).\n\n## Further Notes\n\n- Building the set will dogfood the scale tokens and likely surface gaps (as\n  `Button` surfaced the state-prefixed token-utility gap). Feed those back into\n  the scales/`tw` layer rather than working around them in a component.\n- Keep each component small enough that the `Button` pattern stays legible; the\n  uniformity is the point.\n",[],[18,97,496,489],"v1-component-set","63a5819c-ccc6-4706-aa83-067eb96f6f28","04-button-variant-parity.md","019f624e-0dc9-701d-a888-143392cda24d","019f624e-0dc9-701d-a888-18ab160f33b2",["D",1784060710350],"# 04 · Button variant & state coverage parity with VT\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nA **revision** to the existing `Button` (`src/components/button.tsx`), not a\nrewrite: close the coverage gap between Kylä's 4 shipped variants and VT's 7\n(`docs/reference/val-town-style-guide.md` §5), plus VT's icon-only sizing\nconvention. Kylä's prop _names_ stay its own (ADR-0005) — this ticket ports\n_coverage_, not vocabulary.\n\nEnd-to-end behavior:\n\n- `variant` gains an unbordered filled-neutral member (mirrors VT `default`:\n  `bg-slate-100`/`text-slate-800` light, `bg-slate-800`/`text-slate-200` dark —\n  i.e. `--kyla-recessed`/`--kyla-fg`), named `neutral`.\n- `variant` gains a `success`-backed member (mirrors VT `green`), using the\n  `success`/`success-fg` tokens already landed in v152 — no token work needed.\n- `variant` gains `blend`, reproducing VT's mode-adaptive technique\n  (`mix-blend-color-burn` light / `mix-blend-color-dodge` dark) over\n  `--kyla-recessed`, so the button visually tints to whatever surface it sits\n  on.\n- `subtle` and `ghost` are re-verified (not renamed) for behavioral parity with\n  VT's `secondary` (border + hover-tint) and `clear` (text-only + translucent\n  hover) — note any intentional divergence found.\n- `size` gains icon-only handling: square dimensions per size step (VT's\n  `!px-0 w-8`/`w-10` pattern) instead of padded text sizing.\n- Every new/changed variant keeps the existing token-based focus ring, disabled\n  state, forwarded ref, and `className`-wins contract unchanged.\n\n## Acceptance criteria\n\n- [ ] `Button`'s `variant` union covers `neutral`, a `success`-backed variant,\n      and `blend`, each emitting the correct token utility classes (asserted via\n      rendered markup) and passing AA in both modes using only already-landed\n      tokens (`success`, `success-fg`, `accent-ring`, `accent-text`,\n      `danger-fg`).\n- [ ] Icon-only sizing is available and renders square dimensions matching VT's\n      icon-only pattern per size step.\n- [ ] `subtle`/`ghost` remain behaviorally equivalent to VT's\n      `secondary`/`clear`; any intentional divergence is called out in this\n      ticket's Comments.\n- [ ] All existing guarantees (forwarded ref, `type=\"button\"` default,\n      `className` wins, token focus ring, disabled state) still hold for every\n      variant, old and new.\n- [ ] Render-to-HTML tests (reusing the harness from ticket 01) cover every\n      variant × the icon-only path.\n- [ ] `preview/app.tsx`'s `VARIANTS`/button matrix is updated to include the new\n      variants, so the preview page stops under-representing the component (the\n      trigger for this ticket).\n\n## Out of scope\n\n- Polymorphic rendering (VT's Router Link / external-link button forms) — needs\n  a Slot-style primitive Kylä doesn't have yet; flagged in the parent PRD's Out\n  of Scope, not built here.\n- Renaming any existing variant to match VT's literal names — ADR-0005 keeps\n  Kylä's own vocabulary.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness this ticket's tests reuse.\n\nNot blocked by the scales/palette PRD's remaining tickets — `success`,\n`success-fg`, `danger-fg`, `accent-ring`, `accent-text` already landed in v152\n(see\n[structural-scales-palette issue 01](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)).\n",[],[18,97,496,97,498],"220d900c-a196-4d3a-878f-28e04c0bcabb","03-form-field-primitives.md","019f624e-0dc9-701d-a888-12f24a926548",["D",1784060710350],"# 03 · Form field primitives — Label, Input, Textarea, Select\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nShip the interactive form set with the ADR-0003 bounded-accessibility baseline,\nso consumers get on-system fields with a visible token focus ring and correct\nlabel association without hand-wiring ARIA.\n\nEnd-to-end behavior:\n\n- `Label` associates with a field via `htmlFor` ↔ field `id`.\n- `Input` and `Textarea` share sizes matching `Button`, carry a token visible\n  focus ring (`tw.ring`/`tw.ringOffset`), and wire an `invalid` state to\n  `aria-invalid` and the `danger` token. `Input` forwards `type`.\n- `Select` is a styled-native `<select>` (sizes matching `Input`) that keeps\n  native keyboard behavior with zero added dependencies.\n- Each follows the `Button` authoring contract (`variants()`, semantic element,\n  `forwardRef` + rest props, `className` merged last via `cn()`) and is exported\n  from the `mod.ts` barrel.\n\n## Acceptance criteria\n\n- [ ] `Label`, `Input`, `Textarea`, `Select` render their correct semantic\n      elements, forward refs/rest props, and are exported from `mod.ts`.\n- [ ] `Label htmlFor` matches an `Input id` (association asserted via rendered\n      markup); `Input` forwards `type`.\n- [ ] Focus-ring classes are present on the interactive components; `disabled`\n      and `aria-invalid` render, with `invalid` mapped to the `danger` token.\n- [ ] `className` wins over conflicting classes; render-to-HTML tests cover\n      element + a11y wiring + token classes and pass under `deno test`.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness and the `Button`-pattern reference.\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the `danger` / focus-ring tokens.\n- [Fixed spacing scale + graduated radius scale, with typed accessors](../../structural-scales-palette/issues/02-spacing-and-radius-scales.md)\n  — provides the spacing tokens the field sizes map onto.\n",[],[18,97,496,97,506],"b01a33be-580c-465d-a07f-a38bc8ce89c1","02-layout-and-container-primitives.md","019f624e-0dc9-701d-a888-0e1409b96a57",["D",1784060710350],"# 02 · Layout & container primitives — Stack, Box, Divider, Card, Badge\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nShip the non-interactive visual set — layout primitives and containers — each\nauthored on the `Button` pattern and consuming the spacing-scale tokens so\nlayout stays on-system by construction.\n\nEnd-to-end behavior:\n\n- **Layout:** `Stack` (typed `direction` row/column, `gap` from the spacing\n  scale, alignment), `Box` (minimal styled generic container, no required\n  variants), and `Divider` (orientation, uses the `hairline`/`line` token).\n- **Containers:** `Card` (typed `surface` = `elevated`/`recessed`, `padding`\n  from the spacing scale) and `Badge` (typed `tone` set, `size`). Per the parent\n  PRD's VT Parallelism Audit: VT's card has no elevated/recessed _fill_ — it's\n  flat (`base`) + `border`, elevating only via `hover:border-blue-400` +\n  `hover:shadow-lg`. `Card`'s **default** `surface` must render that\n  flat/bordered look, not a raised fill; `elevated`/`recessed` stay available as\n  explicit, Kylä-only opt-ins.\n- Every component maps typed props → token classes via `variants()`, uses a\n  semantic element, forwards ref + rest props, merges `className` last via\n  `cn()`, and is exported from the `mod.ts` barrel.\n\n## Acceptance criteria\n\n- [ ] `Stack`, `Box`, `Divider`, `Card`, and `Badge` are exported from `mod.ts`,\n      each forwarding refs/rest props.\n- [ ] `Stack` gap and `Card` padding consume spacing-scale tokens; `Divider`\n      uses the hairline token; a bad variant value is a compile error.\n- [ ] `Card surface` and `Badge tone` emit the expected token utility classes\n      (e.g. `Badge tone=\"danger\"` emits the danger color class), asserted via\n      rendered markup.\n- [ ] `Card`'s default `surface` (no prop passed) renders the flat/bordered\n      VT-parity look (`base` surface + border + hover border/shadow), not a\n      raised `elevated` fill.\n- [ ] `className` wins over each component's conflicting class; render-to-HTML\n      tests cover element + token classes and pass under `deno test`.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness and the `Button`-pattern reference for\n  the set.\n- [Fixed spacing scale + graduated radius scale, with typed accessors](../../structural-scales-palette/issues/02-spacing-and-radius-scales.md)\n  — provides the spacing tokens `Stack`/`Card` consume.\n",[],[18,97,496,97,513],"85ee1cb8-fbff-4387-bf2d-bf28a7168633","01-render-harness-and-typography.md","019f624e-0dc9-701d-a888-08760ba4b319",["D",1784060710350],"# 01 · Render-to-HTML harness + Text / Heading\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nStand up the render-to-HTML test harness for the component set and ship the\nfirst two components — `Text` and `Heading` — authored exactly like `Button`.\nConsumers get typed typography whose sizes come from the type scale and whose\ntones come from the palette; every later component slice reuses the harness this\nticket establishes.\n\nEnd-to-end behavior:\n\n- `Text` and `Heading` with typed `size` (type-scale steps), `weight`, and\n  `tone` (`fg`/`fg-muted`/`accent`/`danger`) props, a polymorphic `as` for the\n  element, `forwardRef` + rest props, and an escape-hatch `className` merged\n  last via `cn()`. Both are exported from the `mod.ts` barrel.\n- A `renderToStaticMarkup` harness that renders a component to an HTML string\n  for assertions — the uniform seam for the whole set. If this slice lands\n  before the scales PRD's own tests, it establishes the render-to-HTML harness\n  itself.\n\n## Acceptance criteria\n\n- [ ] `Text` and `Heading` render the correct semantic element (`Heading` emits\n      the right heading tag; `Text` a sensible default), forward refs/rest\n      props, and are exported from `mod.ts`.\n- [ ] `size`/`weight`/`tone` map to token utility classes drawn from the type\n      scale and palette; a bad prop value is a compile error via typed unions.\n- [ ] `className` wins over the component's own conflicting class (the `cn()`\n      contract), asserted against the rendered markup.\n- [ ] A reusable render-to-HTML harness exists; `Text`/`Heading` tests assert\n      element + token classes + `className`-wins and pass under `deno test`.\n\n## Blocked by\n\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the palette tones and the `tw.*` color accessor pattern.\n- [Type scale (size + line-height) + overridable font, with loading](../../structural-scales-palette/issues/03-type-scale-and-font.md)\n  — provides the type-scale steps `Text`/`Heading` map onto.\n",[],[18,97,496,97,520],"5749f2de-72d2-43cd-9edd-507be119247f",["D",1784060710350],[276,277,278,279],[18,97,496,97],"63853d63-bf1f-4fdb-b719-4a76b36e7b6c",["D",1784060710350],[275,280],[18,97,496],"3c647453-9556-42be-85a3-dc3e4ec7f6c7","019f624e-0dc9-701d-a888-03182541e9cf","019f624e-0dc9-701d-a888-061da5210880",["D",1784060710350],"# PRD: Structural scales & real palette\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> The highest-leverage item on the [roadmap](../../roadmap.md): the spacing /\n> radius / type scale is where visual consistency actually lives. This PRD turns\n> the provisional token stylesheet into a real, fixed structural foundation. It\n> is the prerequisite for the [v1 component set](../v1-component-set/spec.md).\n\n## Problem Statement\n\nKylä's whole promise is that apps look coherent by default. But today the token\nsystem only ships semantic **color** tokens with _provisional_ hex values, plus\na single `--kyla-radius`. There is no spacing scale, no type scale, and no\ngraduated radius scale, and the palette has never been checked for AA contrast.\n\nThe consequence is already visible: the preview page hand-writes `px-4 py-2`,\n`text-lg`, `gap-6`, `mt-5`, `text-[10px]` — raw Twind numbers chosen ad hoc.\nEvery component built this way re-decides spacing and type independently, which\nis exactly the inconsistency Kylä exists to eliminate. Consumers who trust the\ndefault theme also have no guarantee that foreground/background pairings are\nlegible.\n\n## Solution\n\nShip a real, opinionated, **fixed** set of structural scales — spacing, radius,\nand type (size + line-height, with the font family and any needed weights) —\nplus a real, AA-verified color palette bound to the existing semantic tokens.\nBecause the structural scales are fixed and consumed by every component, spacing\nand type become consistent by construction. The consumer override surface stays\ndeliberately small (`--kyla-accent`, `--kyla-radius`, `--kyla-font`); everything\nstructural stays fixed — that fixedness _is_ the consistency (ADR-0001,\nCONTEXT.md).\n\nThe default palette carries AA contrast as a quiet guarantee (ADR-0003),\nverified mechanically rather than by eye.\n\n## User Stories\n\n1. As a consumer, I want a fixed spacing scale exposed as tokens, so that\n   padding and gaps are consistent across every component and every app without\n   me choosing pixel values.\n2. As a consumer, I want a fixed type scale (size + line-height), so that text\n   hierarchy is coherent without me hand-picking `text-*` classes.\n3. As a consumer, I want a font-family token I can override, so that I can\n   express brand while keeping the rest of the system fixed.\n4. As a consumer, I want a graduated radius scale derived from the overridable\n   `--kyla-radius`, so that rounding stays proportional when I change the base\n   radius.\n5. As a consumer, I want the default palette to meet WCAG AA contrast in both\n   light and dark mode, so that my app is legible without me auditing colors.\n6. As a consumer, I want the small override surface (accent, radius, font) to be\n   documented and stable, so that I know exactly what I may safely redefine.\n7. As a consumer, I want structural tokens (spacing, type, surfaces, borders) to\n   stay fixed, so that I cannot accidentally break visual consistency by\n   overriding them.\n8. As a component author, I want a sanctioned, typed way to reference scale\n   tokens, so that I compose spacing and type from the scale instead of raw\n   Twind numbers.\n9. As a component author, I want the scale accessors to sit alongside the\n   existing `tw` color helpers, so that authoring one component uses one\n   consistent vocabulary.\n10. As a component author, I want the type scale to bundle line-height with\n    size, so that I cannot set a size without its intended leading.\n11. As a maintainer, I want the palette's AA guarantee enforced by a test, so\n    that a future palette edit that breaks contrast fails CI rather than\n    shipping.\n12. As a maintainer, I want the scale definitions to live in one place\n    (`tokens.ts`), so that the design foundation has a single source of truth.\n13. As a maintainer, I want the scales expressed as CSS custom properties\n    resolved with `light-dark()` where mode-dependent, so that mode still flips\n    with zero JS.\n14. As an end user, I want legible text and comfortable spacing in whatever mode\n    my OS prefers, so that the app is usable by default.\n15. As a consumer upgrading, I want the scale token _names_ to be stable, so\n    that a Release that retunes values doesn't break my component usage.\n\n## Implementation Decisions\n\n- **Source of values (ADR-0005):** the palette and structural scales **conform\n  to the Val Town UI style guide** — they are _ported_, not invented here.\n  Concrete values come from the VT style-guide research/reference doc under\n  `docs/` (see\n  [ADR-0005](../../adr/0005-val-town-visual-language-default-theme.md)). This\n  PRD's job is to bind those values to the `--kyla-*` tokens and the scale\n  accessors, and to hold the AA line where a VT pairing falls short.\n- **Resolved default values** (from\n  [`val-town-style-guide.md`](../../reference/val-town-style-guide.md) §6; all\n  AA-passing both modes). Values are Tailwind v4 steps, applied via\n  `light-dark(light, dark)`:\n  - `base` = white / **`slate-950` `#020618`** (a deliberate softening of VT's\n    true-black `#000` — see ADR-0005); `elevated` = white+shadow / `slate-900`;\n    `recessed` = `slate-100` / `slate-800`.\n  - `fg` = black / white; `fg-muted` = `gray-600` / `gray-300` (VT's literal\n    `--color-muted`; **not** slate-400, which fails AA).\n  - `line` = `slate-200` / `slate-700`; `hairline` = `slate-100` / `slate-800`.\n  - `accent` = `sky-400` / `sky-700`; `accent-fg` = **`sky-950` ink** / white\n    (never white on `sky-400` — fails at 2.18:1); `accent-ring` = `sky-500`;\n    `accent-text` = `sky-800` / `sky-200`.\n  - `danger` = `rose-300` / `rose-800`; `danger-fg` = `rose-950` / white.\n    `success` = `emerald-400` / `emerald-700`; `success-fg` = `emerald-950` /\n    white.\n  - `radius` (base) = **8px** (`rounded-lg`); spacing base = 4px; font =\n    `\"IBM Plex Sans\",\n-apple-system, sans-serif` (needs shell/Provider font\n    loading — flag for delivery).\n- **New tokens (ADR-0005):** this PRD adds `accent-ring`, `accent-text`,\n  `danger-fg`, `success`, `success-fg` to the `ColorToken` union and the token\n  stylesheet, alongside the existing set. All are structural (not part of the\n  override surface).\n- **Modules touched:** `src/theme/tokens.ts` (add scale custom properties) and\n  `src/theme/tw.ts` (add typed scale accessors alongside the existing color\n  helpers). A new pure module for the AA-contrast check (used by tests) may be\n  added under `src/theme/`.\n- **Scale tokens to define** (names fixed by this PRD; exact numeric values are\n  the design deliverable _within_ this PRD):\n  - **Spacing:** a fixed stepped scale, `--kyla-space-*`. Monotonic, small step\n    count, built on a consistent base unit.\n  - **Type:** `--kyla-text-*` steps, each carrying a size **and** a line-height,\n    plus `--kyla-font` (overridable) and weight tokens if components need them.\n  - **Radius:** keep `--kyla-radius` as the single overridable base; derive a\n    small graduated set (`--kyla-radius-sm/md/lg`) from it.\n- **Override surface (formalized):** consumer-overridable = `--kyla-accent`,\n  `--kyla-radius`, `--kyla-font` (and their direct derivations). Everything else\n  — surfaces, foreground, borders, spacing scale, type scale — is structural and\n  stays fixed. Document this split in `tokens.ts` and CONTEXT.md's Override\n  Surface note.\n- **Accessor shape:** scale accessors follow the `tw.*` pattern. Lengths need no\n  `color:` hint (per the spike finding, only colors do), so spacing/radius/type\n  accessors emit bare arbitrary-value classes (e.g. `p-[var(--kyla-space-4)]`),\n  while a typo in the step is a compile error via a TypeScript union — mirroring\n  how `ColorToken` already guards color tokens.\n- **Palette:** replace every provisional hex with the resolved VT value above\n  for both modes, keeping the `light-dark()` structure. Every _sanctioned_\n  foreground/ surface pairing (`fg` on `base`/`elevated`/`recessed`, `accent-fg`\n  on `accent`, `danger-fg` on `danger`, `success-fg` on `success`, `fg-muted` on\n  surfaces used for secondary text) must meet WCAG AA: 4.5:1 for body text, 3:1\n  for large text and UI/border affordances.\n\n## Testing Decisions\n\n- **What makes a good test here:** it asserts an _external guarantee_ of the\n  foundation, not a specific hex or pixel. Two guarantees are worth testing:\n  contrast and scale integrity.\n- **Seam (highest available):** the token stylesheet string plus a **pure\n  contrast function** over resolved color values. This is the natural seam\n  because the guarantee (\"AA holds\") is a property of the values, computable\n  without a browser.\n  - Enumerate every sanctioned fg/surface pairing and assert its computed\n    contrast ratio meets the AA threshold in **both** modes. This is the load-\n    bearing test — it's what lets a future palette edit fail loudly.\n  - Assert the spacing and type scales exist, are monotonic, and expose the\n    documented step count.\n  - Assert the override tokens (`--kyla-accent`, `--kyla-radius`, `--kyla-font`)\n    are present and that structural tokens are present.\n- **Modules tested:** `tokens.ts` (via the parsed stylesheet) and the contrast\n  helper.\n- **Prior art:** none — this PRD establishes the repo's first test harness. Keep\n  it a plain Deno test so later component PRDs can reuse the pattern.\n\n## Out of Scope\n\n- The Kumo-style **named-theme system** / multiple consumer-defined themes\n  (theming v2 — deferred by the sketch).\n- Per-component **variant → token maps** (which tones `Badge`/`Button` expose,\n  etc.) — that lives with the\n  [v1 component set PRD](../v1-component-set/spec.md).\n- Any new components.\n- Dark-mode raster image handling.\n\n## Further Notes\n\n- This PRD front-loads a genuine design decision (the actual step counts,\n  ratios, and hex values). Those choices should be made here and encoded as the\n  token values; downstream PRDs consume them by name and must not re-decide\n  them.\n- Because scale token _names_ become load-bearing across the component set,\n  treat a rename as a breaking change under ADR-0004 once components depend on\n  them.\n",[],[18,97,541,489],"structural-scales-palette","4112060b-f596-4e4a-a6bb-70f949b36ef9","04-formalize-override-surface.md","019f624e-0dc9-701d-a887-fa684def40a5","019f624e-0dc9-701d-a887-ff1c7aef2ace",["D",1784060710350],"# Formalize the override surface + structural-token presence test\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nSeal the foundation: make the override/structural split explicit and enforced\nnow that every token family (palette, spacing, radius, type/font) exists.\n\nEnd-to-end behavior:\n\n- **Documentation:** record the split in `tokens.ts` and in CONTEXT.md's\n  Override Surface note. Consumer-overridable = `--kyla-accent`,\n  `--kyla-radius`, `--kyla-font` (and their direct derivations); everything else\n  — surfaces, foreground, borders, spacing scale, type scale — is structural and\n  stays fixed. That fixedness is the consistency (ADR-0001, CONTEXT.md).\n- **Presence test** (reusing the harness from slice 01): assert the three\n  override tokens are present, and that the structural tokens across all\n  families are present. This encodes the stable-names contract — scale token\n  _names_ are load-bearing across the component set, so a rename becomes a\n  detectable breaking change under ADR-0004.\n\nThis slice adds no new values or accessors; it documents and locks the surface\nthe prior three slices produced.\n\n## Acceptance criteria\n\n- [ ] `tokens.ts` and CONTEXT.md's Override Surface note both state the override\n      vs. structural split, listing `--kyla-accent`, `--kyla-radius`,\n      `--kyla-font` as the overridable surface.\n- [ ] A test asserts the three override tokens are present and that the\n      structural tokens across surfaces, foreground, borders, spacing, radius,\n      and type are all present.\n- [ ] The presence test fails if a documented token name is removed or renamed,\n      giving the stable-names contract teeth — passing under `deno test`.\n\n## Blocked by\n\n- [02 — Fixed spacing scale + graduated radius scale](./02-spacing-and-radius-scales.md)\n- [03 — Type scale + overridable font](./03-type-scale-and-font.md)\n\n(Depends on every token family existing so the presence test can assert the full\nset. Slice 01 is a transitive blocker.)\n",[],[18,97,541,97,543],"cc568f6d-4428-44c6-b3f8-abd4f16f0351","03-type-scale-and-font.md","019f624e-0dc9-701d-a887-f55212b282f9",["D",1784060710350],"# Type scale (size + line-height) + overridable font, with loading\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nShip the fixed type scale and the overridable font, end-to-end — tokens, typed\naccessor, and the font actually loading in the running app.\n\nEnd-to-end behavior:\n\n- **Type scale:** `--kyla-text-*` steps, each carrying **both** a size and its\n  paired line-height, defined in the token stylesheet. Structural and fixed.\n  Weight tokens are added if components need them.\n- **Font:** `--kyla-font` is the overridable font-family token (default\n  `\"IBM Plex Sans\", -apple-system, sans-serif`), part of the small consumer\n  override surface. The IBM Plex Sans webfont is actually loaded via the\n  shell/Provider so the default renders as intended — this is the delivery\n  concern the PRD flags; without it the token points at a font that never\n  arrives.\n- **Accessor:** a typed type accessor alongside the `tw.*` helpers that bundles\n  line-height with size, so an author cannot set a size without its intended\n  leading. A typo'd step is a compile error via a TypeScript union.\n- **Tests** (reusing the harness from slice 01): assert the type steps exist,\n  are monotonic by size, and that each step carries a line-height; assert\n  `--kyla-font` is present.\n\nExact steps and values come from the PRD Implementation Decisions and\n`docs/reference/val-town-style-guide.md` §4 (size/line-height pairs; weights\n400/500/600/700/800; body `text-base` 16/1.5, controls `text-sm` 14/20).\n\n## Acceptance criteria\n\n- [ ] `--kyla-text-*` steps each pair a size with a line-height in the token\n      stylesheet; the scale is fixed/structural and monotonic by size.\n- [ ] The typed type accessor bundles size + line-height so a size cannot be set\n      without its leading; a bad step name is a compile error.\n- [ ] `--kyla-font` is an overridable token defaulting to the IBM Plex Sans\n      stack, and the webfont is loaded via the shell/Provider so the default\n      actually renders.\n- [ ] Weight tokens are exposed if components need them.\n- [ ] Tests assert the type steps exist, are monotonic, each carries a\n      line-height, and `--kyla-font` is present — passing under `deno test`.\n\n## Blocked by\n\n- [01 — Real palette + first contrast test harness](./01-real-palette-and-contrast-harness.md)\n  (provides the test harness and the `tw.*` accessor pattern).\n",[],[18,97,541,97,551],"95baef2e-8014-4fc4-80ad-f0459547a743","02-spacing-and-radius-scales.md","019f624e-0dc9-701d-a887-f21240744840",["D",1784060710350],"# Fixed spacing scale + graduated radius scale, with typed accessors\n\nStatus: claimed Labels: ready-for-agent\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nShip the two fixed length scales — spacing and radius — as tokens plus\nsanctioned, typed accessors, so component authors compose them from the scale\ninstead of raw Twind numbers.\n\nEnd-to-end behavior:\n\n- **Spacing:** a fixed, monotonic, stepped `--kyla-space-*` scale with a small\n  step count on a consistent 4px base unit, defined in the token stylesheet.\n  These are structural (not overridable).\n- **Radius:** keep `--kyla-radius` as the single consumer-overridable base, and\n  derive a small graduated set (`--kyla-radius-sm/md/lg`) from it so rounding\n  stays proportional when a consumer changes the base radius.\n- **Accessors:** add typed scale accessors alongside the existing `tw.*` color\n  helpers. Lengths need no `color:` hint, so these emit bare arbitrary-value\n  classes (e.g. `p-[var(--kyla-space-4)]`, `rounded-[var(--kyla-radius-md)]`). A\n  typo'd step is a compile error via a TypeScript union, mirroring how\n  `ColorToken` guards color tokens. The existing single `tw.radius` accessor is\n  superseded by the graduated form.\n- **Tests** (reusing the harness from slice 01): assert the spacing and radius\n  tokens exist, are monotonic, expose the documented step count, and that the\n  graduated radii derive from the overridable base.\n\nExact step counts and numeric values come from the PRD Implementation Decisions\nand `docs/reference/val-town-style-guide.md` §2–§3 (spacing base 4px; radius\nscale 2/4/6/8/12/16/24, control default 8px).\n\n## Acceptance criteria\n\n- [x] `--kyla-space-*` is a fixed, monotonic stepped scale on a 4px base with\n      the documented step count, defined in the token stylesheet.\n- [x] `--kyla-radius` remains the single overridable base;\n      `--kyla-radius-sm/md/lg` are derived from it and stay proportional when\n      the base changes.\n- [x] Typed spacing and radius accessors sit alongside the `tw.*` color helpers,\n      emit bare arbitrary-value classes (no `color:` hint), and make a bad step\n      name a compile error.\n- [x] Tests assert both scales exist, are monotonic, expose the documented step\n      count, and that graduated radii derive from the base — passing under\n      `deno test`.\n\n## Blocked by\n\n- [01 — Real palette + first contrast test harness](./01-real-palette-and-contrast-harness.md)\n  (provides the test harness and the expanded `tw.*` accessor pattern).\n\n## Comments\n\n- Implemented the 13-step 4px spacing scale and proportional `sm` / `md` / `lg`\n  radius derivations from the 8px base.\n- Added typed `tw.space(...)` and `tw.radius(...)` accessors with runtime tests\n  and `@ts-expect-error` checks for invalid steps; migrated existing radius\n  consumers to the graduated accessor.\n- Focused theme checks and the full `deno task test` pass (8 tests). The\n  repo-wide lint/typecheck gates still report pre-existing issues in\n  `preview/index.tsx`, React default imports, and `src/utils/variants.ts`.\n- The workspace has Val Town branch state in `.vt/state.json` but no `.git`\n  repository, so this remains claimed pending the branch's normal Release merge.\n",[],[18,97,541,97,558],"bde6abee-e177-40d9-8b76-9988adf49c24","01-real-palette-and-contrast-harness.md","019f624e-0dc9-701d-a887-ed0c8121a850",["D",1784060710350],"# Real palette + first contrast test harness\n\nStatus: done Labels: done Landed: v152\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nReplace the provisional token palette with the real, AA-verified Val Town\nvalues, and stand up the repo's first test harness by proving that palette meets\nAA contrast. This is the foundational slice every later scale slice builds on.\n\nEnd-to-end behavior:\n\n- The token stylesheet resolves every semantic color token to its real VT value\n  in **both** modes via `light-dark()` (mode still flips with zero JS).\n  Provisional hexes are gone; the values conform to the VT style guide\n  (ADR-0005), with the one sanctioned deviation (dark-mode `base` = `slate-950`\n  `#020618`, not true black).\n- The color-token vocabulary expands to cover VT's accent + status roles: the\n  new structural tokens `accent-ring`, `accent-text`, `danger-fg`, `success`,\n  `success-fg` join the existing set, in both the stylesheet and the typed\n  `ColorToken` union so `tw.*` color helpers can reference them.\n- A pure, browser-free contrast function computes the WCAG contrast ratio\n  between two resolved color values. It is the natural seam for the guarantee\n  (\"AA holds\"), computable without a DOM.\n- The repo's first Deno test parses the token stylesheet, enumerates every\n  _sanctioned_ foreground/surface pairing, and asserts each meets its AA\n  threshold in **both** modes. This is the load-bearing test — a future palette\n  edit that breaks contrast fails CI rather than shipping.\n\nResolved values and the full sanctioned-pairing list come from the PRD's\nImplementation Decisions and `docs/reference/val-town-style-guide.md` §6–§7 —\nbind those values, do not re-decide them. Keep the harness a plain Deno test so\nlater scale slices reuse the pattern.\n\n## Acceptance criteria\n\n- [x] Every semantic color token resolves to its real VT value in both modes via\n      `light-dark()`; no provisional hexes remain, and no `dark:` variants are\n      introduced.\n- [x] Dark-mode `base` uses the sanctioned `slate-950` softening, not true\n      black.\n- [x] `accent-ring`, `accent-text`, `danger-fg`, `success`, `success-fg` are\n      added to both the stylesheet and the `ColorToken` union; existing `tw.*`\n      color helpers reach them.\n- [x] A pure contrast function returns the correct WCAG ratio for known pairs\n      and takes no DOM/browser dependency.\n- [x] A Deno test enumerates every sanctioned fg/surface pairing and asserts AA\n      (4.5:1 body, 3:1 large/UI) in both light and dark; it fails if any pairing\n      regresses.\n- [x] The test suite runs with `deno test` and passes (needs `--allow-import`\n      for the val.town types pulled by `deno.json`).\n\n## Blocked by\n\nNone - can start immediately.\n",[],[18,97,541,97,565],"5a511b86-19de-4215-b493-017fa2b704a3",["D",1784060710350],[269,270,271,272],[18,97,541,97],"e4fdd766-3c5f-4250-92a9-0948e97df94f",["D",1784060710350],[268,273],[18,97,541],"73e02b06-4e84-4f30-ba31-960df1b0a13b","019f624e-0dc9-701d-a887-e4b1b2bb6d23","019f624e-0dc9-701d-a887-e8c5a0332ee9",["D",1784060710350],"# PRD: Starter — remixable todo app\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Ships the **Starter** defined in [CONTEXT.md](../../../CONTEXT.md): a\n> separate, remixable demo val showing idiomatic end-to-end use of Kylä UI. It\n> depends on the [component set](../v1-component-set/spec.md) (and ideally\n> [Dialog](../dialog-radix/spec.md)); the Starter depends on the library, never\n> the reverse.\n\n## Problem Statement\n\nCONTEXT.md's on-ramp for a new app is \"remix the Starter, then edit.\" But the\nStarter doesn't exist. A developer who wants to build with Kylä has only the\nGallery (which shows components in isolation) and the README snippet (a single\nButton). There's no genuine, end-to-end example wiring together a real HTTP\nroute, persistence, the Provider + client hydration, an app shell, and a Mode\ntoggle — i.e. no honest demonstration that Kylä works as a whole for building an\nactual app.\n\n## Solution\n\nShip **`kyla-ui-starter`**: a small but genuine **todo app** that imports Kylä\nUI and is built entirely from its components. It has a real HTTP route,\n`std/sqlite` persistence, `KylaProvider` + client hydration, an app shell, a\nMode toggle, and a view-source link. Remixing it and editing is the intended way\nto start a new Kylä app. Building it also dogfoods the library and surfaces gaps\nin the component set.\n\n## User Stories\n\n1. As a new Kylä developer, I want a remixable Starter val, so that I can begin\n   a real app by copying a working example instead of assembling one.\n2. As a new developer, I want the Starter to be a genuine todo app (add / toggle\n   / delete, persisted), so that it demonstrates real behavior, not a static\n   mock.\n3. As a new developer, I want the Starter to persist todos with `std/sqlite`, so\n   that I see the idiomatic Val Town persistence pattern.\n4. As a new developer, I want the Starter to serve a real HTTP route, so that I\n   see how a Kylä app is served on Val Town.\n5. As a new developer, I want the Starter wrapped in `KylaProvider` with client\n   hydration, so that I see the correct Provider + CSR wiring (Twind before\n   first paint, tokens injected, Mode owned).\n6. As a new developer, I want the whole UI built from Kylä components, so that I\n   learn the components by seeing them composed in a real app.\n7. As a new developer, I want a Mode toggle in the Starter, so that I see how to\n   give an app a first-class light/dark toggle via `useKylaMode()`.\n8. As a new developer, I want a view-source link, so that I can jump from the\n   running app to its code.\n9. As a new developer, I want the Starter pinned to a known-good Kylä Release,\n   so that a fresh remix renders correctly and isn't broken by an in-flight\n   library change.\n10. As a maintainer, I want the Starter to depend on the library (never the\n    reverse), so that the dependency direction stays clean.\n11. As a maintainer, I want the Starter built from real components, so that it\n    doubles as an integration check that the set composes into an app.\n12. As an end user of the demo, I want to add, complete, and remove todos, so\n    that the app is actually usable.\n13. As an end user, I want my todos to persist across reloads, so that the demo\n    behaves like a real app.\n\n## Implementation Decisions\n\n- **Separate val:** `kyla-ui-starter` (per CONTEXT.md), distinct from `kyla-ui`.\n  It **imports** Kylä UI; the library never imports it.\n- **CSR-only** (sketch/ADR-0001): an HTML shell loads Twind before first paint,\n  a client entry hydrates the app, and `KylaProvider` wraps it (owning tokens +\n  Mode). Same shell mechanics the Gallery/preview use (importmap for `npm:`\n  specifiers, `std/catch`, `serveFile`).\n- **Persistence:** `std/sqlite` (project-scoped DB) for the todo list.\n- **HTTP route:** serves the shell and handles todo mutations — list, add,\n  toggle complete, delete — round-tripping through sqlite.\n- **UI built from Kylä components:** app shell, `Card`, `Input`, `Button`,\n  `Text`/`Heading`, `Stack`, etc., plus the Mode toggle via `useKylaMode()`.\n  Using `Dialog` (e.g. a confirm-delete) is encouraged once it ships, to\n  demonstrate the own-import-path pattern.\n- **Version pinning (decided here):** the Starter **pins** its Kylä import to a\n  known-good `?v=NNN` Release, so a remix is a stable starting point rather than\n  tracking `main` mid-change (ADR-0004). Document which Release it targets; bump\n  deliberately.\n- **view-source link** to the Starter val, matching the preview/Gallery pattern.\n\n## Testing Decisions\n\n- **What makes a good test:** it drives the app's _external_ HTTP behavior — the\n  todo operations round-tripping through sqlite — not the internal React tree or\n  the library's internals (those are the component PRDs' concern).\n- **Seam (HTTP, highest available for the app):** exercise the route endpoints\n  and assert the todo lifecycle: adding a todo returns/lists it, toggling flips\n  its completed state, deleting removes it, and the list reflects persisted\n  state on a fresh request. Optionally assert the served shell is a `200` HTML\n  page that boots the client entry.\n- **Modules tested:** the Starter's HTTP handler + its sqlite data access.\n- **Prior art:** Val Town `std/sqlite` HTTP-handler patterns (fetch a template\n  via the platform's skill finder); the `preview/index.tsx` handler is the\n  reference for the serve-shell-and-files structure on Val Town.\n\n## Out of Scope\n\n- Auth / multi-user / per-user todo lists.\n- Isomorphic SSR + hydration for SEO (sketch defers this; CSR-only for v1).\n- Demonstrations beyond the todo app (other example apps).\n- The **Gallery** / component docs — those live in the library\n  ([Gallery PRD](../gallery/spec.md)), not the Starter.\n\n## Further Notes\n\n- The Starter is the honest integration test of the whole v1: if composing it\n  into a real app is awkward, that's a signal to fix the component set, not to\n  work around it in the Starter.\n- Keep it \"tiny but genuine\" — enough to be a real app, small enough to read in\n  one sitting, since developers will copy it as their baseline.\n",[],[18,97,586,489],"starter","5649262a-0f68-4134-b369-e3bf6ab4be74","03-todo-ui-and-mode-toggle.md","019f624e-0dc9-701d-a887-dd08d4b7cc7c","019f624e-0dc9-701d-a887-e3957b9225a3",["D",1784060710350],"# 03 · Todo UI + Mode toggle\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nWire the todo UI — built entirely from Kylä components — to the CRUD route, and\ngive the app a first-class light/dark toggle via the library's own Mode\nownership. This is where the Starter becomes usable and dogfoods the component\nset as a whole.\n\nEnd-to-end behavior:\n\n- The full add / toggle / delete todo UI composed from Kylä components (`Card`,\n  `Input`, `Button`, `Text`/`Heading`, `Stack`, etc.), wired to the CRUD route.\n- A Mode toggle driven by `useKylaMode()` (not a hand-rolled toggle).\n- Optional: a confirm-delete `Dialog` once it ships, to demonstrate the\n  own-import-path pattern (soft dependency — not required to land this ticket).\n\n## Acceptance criteria\n\n- [ ] An end user can add, complete, and remove todos through a UI built\n      entirely from Kylä components.\n- [ ] A Mode toggle driven by `useKylaMode()` flips the app between light/dark.\n- [ ] The UI reflects persisted state from the CRUD route (reload shows saved\n      todos).\n\n## Blocked by\n\n- [01 — Served, hydrated skeleton app](./01-served-hydrated-skeleton.md)\n- [02 — Todo persistence + CRUD over HTTP](./02-todo-persistence-and-crud.md)\n\nSoft dependency (not blocking):\n[Dialog](../../dialog-radix/issues/01-dialog-radix-component.md) enables the\noptional confirm-delete example.\n",[],[18,97,586,97,588],"0fc2370e-7bd6-4f37-865d-e9cf144b94b3","02-todo-persistence-and-crud.md","019f624e-0dc9-701d-a887-dab48627d833",["D",1784060710350],"# 02 · Todo persistence + CRUD over HTTP\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nGive the Starter a real, persisted todo lifecycle behind its HTTP route, so the\ndemo behaves like an actual app and doubles as the honest integration check the\nPRD calls for.\n\nEnd-to-end behavior:\n\n- `std/sqlite` (project-scoped DB) data access for the todo list.\n- Route handlers that list, add, toggle-complete, and delete todos, each\n  round-tripping through sqlite. The list reflects persisted state on a fresh\n  request.\n- HTTP-seam tests that drive the route's **external** behavior — not the React\n  tree or the library internals.\n\n## Acceptance criteria\n\n- [ ] The route persists todos via `std/sqlite`; adding a todo lists it,\n      toggling flips its completed state, and deleting removes it.\n- [ ] The list reflects persisted state on a fresh request (survives reload).\n- [ ] HTTP-seam tests assert the full add/toggle/delete/list lifecycle and pass\n      under `deno test`.\n\n## Blocked by\n\n- [01 — Served, hydrated skeleton app](./01-served-hydrated-skeleton.md) —\n  provides the served val + HTTP route this builds on.\n",[],[18,97,586,97,596],"1b225c90-b936-4a68-869b-34ef43db5c6b","01-served-hydrated-skeleton.md","019f624e-0dc9-701d-a887-d46868c69c31",["D",1784060710350],"# 01 · Served, hydrated skeleton app\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nStand up the `kyla-ui-starter` val as a served, hydrated skeleton that proves\nthe whole render/hydration path end-to-end before any todo logic exists. This is\nthe tracer bullet: a fresh remix boots correctly against a pinned Kylä release.\n\nEnd-to-end behavior:\n\n- A separate val, `kyla-ui-starter`, that **imports** Kylä UI (the library never\n  imports it).\n- CSR-only shell (ADR-0001): an `index.html` static file loads Twind before\n  first paint, a client entry hydrates the app, and `KylaProvider` wraps it\n  (owning tokens + Mode). Same shell mechanics the Gallery/preview use\n  (importmap for `npm:` specifiers, `std/catch`, `serveFile`).\n- A minimal screen built from Kylä components, served at the app's HTTP route,\n  with a view-source link back to the val.\n- The Kylä import is **pinned** to a known-good `?v=NNN` Release (ADR-0004);\n  document which Release it targets.\n\n## Acceptance criteria\n\n- [ ] `kyla-ui-starter` is a separate val that imports Kylä UI and is served at\n      an HTTP route returning a `200` HTML page that boots the client entry.\n- [ ] Twind loads before first paint; `KylaProvider` wraps the hydrated app and\n      owns tokens + Mode; the visible screen is built from Kylä components.\n- [ ] A view-source link points back to the Starter val.\n- [ ] The Kylä import is pinned to a documented known-good `?v=` Release.\n\n## Blocked by\n\n- [v1-component-set 01 — Render-to-HTML harness + Text / Heading](../../v1-component-set/issues/01-render-harness-and-typography.md)\n- [v1-component-set 02 — Layout & container primitives](../../v1-component-set/issues/02-layout-and-container-primitives.md)\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n",[],[18,97,586,97,603],"e271dad2-c59f-4af0-8e81-f1cd8c5b1845",["D",1784060710350],[263,264,265],[18,97,586,97],"24bef4d3-bba3-49c5-b4bc-683e0fdcefa9",["D",1784060710350],[262,266],[18,97,586],"1e44051b-f5d7-4f5b-bd0c-0dd88f64ffff","019f624e-0dc9-701d-a887-ce083c59315d","019f624e-0dc9-701d-a887-d3e5a786999c",["D",1784060710350],"# PRD: Gallery — self-hosted docs surface\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Promotes the WIP `preview/` into the real **Gallery** — a first-class term in\n> [CONTEXT.md](../../../CONTEXT.md): the library's self-hosted documentation at\n> its own HTTP route, rendering every component in its variants and Modes with\n> the Mode toggle. Grows as the [component set](../v1-component-set/spec.md) and\n> [Dialog](../dialog-radix/spec.md) land.\n\n## Problem Statement\n\nKylä is meant to **document itself**: CONTEXT.md defines the Gallery as an HTTP\nroute on `kyla-ui` that renders every component in its variants and Modes — both\nliving docs and the in-browser proof that the whole stack (Twind + CSS-var\ntokens, Provider mode, Radix hydration) renders correctly on Val Town. Today\nthat surface only exists as `preview/`, which is explicitly labelled\nwork-in-progress and \"not a stable API,\" carries a 🚧 banner, and is framed as\nillustrative rather than canonical. There is no blessed docs surface a consumer\ncan point to.\n\n## Solution\n\nPromote `preview/` into the real **Gallery** served at `kyla-ui`'s HTTP route:\nit renders every shipped component across its variants/sizes/tones, shows the\ndesign token swatches, and carries the Mode toggle driven by the library's own\n`useKylaMode()`. It imports the real library and never modifies it. It is the\ncanonical proof-of-render on Val Town and the seed of a fuller docs site later.\n\n## User Stories\n\n1. As a consumer evaluating Kylä, I want a live Gallery at the library's URL, so\n   that I can see every component before importing it.\n2. As a consumer, I want each component shown in all its variants/sizes/tones,\n   so that I can pick the right props by seeing them.\n3. As a consumer, I want a Mode toggle (light/dark/system) in the Gallery, so\n   that I can verify how components look in each Mode.\n4. As a consumer, I want the token swatches shown, so that I can see the\n   semantic palette the system is built on.\n5. As a consumer, I want a view-source link, so that I can read how the Gallery\n   uses the components.\n6. As a maintainer, I want the Gallery served from `kyla-ui` itself (co-located\n   with source), so that the library documents itself and the docs can never\n   drift from the code they import.\n7. As a maintainer, I want the Gallery to import the real library and never\n   modify it, so that it's an honest proof-of-render, not a mock.\n8. As a maintainer, I want the Gallery to be the in-browser proof that Twind +\n   tokens + Provider + Radix render correctly on Val Town, so that a broken\n   render path is visible immediately.\n9. As a maintainer, I want adding a new component to the Gallery to be a small,\n   obvious edit, so that the docs stay current as the set grows.\n10. As a contributor, I want the Gallery to exercise the interactive components\n    (focus rings, Dialog open/close), so that it doubles as a manual behavior\n    check.\n11. As an end user of the docs, I want the Gallery to load without a build step,\n    so that it works on Val Town's runtime like any consumer app.\n\n## Implementation Decisions\n\n- **Home:** served from `kyla-ui`'s HTTP route (the val documents itself). Reuse\n  the shell _mechanics_ from `preview/`: Twind loaded before first paint\n  (ADR-0001), the importmap that maps `npm:` specifiers to esm.sh for the\n  browser, `std/catch` for client-error surfacing, `serveFile` for transpiled\n  `.ts/.tsx`, and the `/source` redirect. The Gallery **imports** the library\n  from `mod.ts` (and Dialog's own path) and modifies nothing — the preview's\n  core invariant.\n- **Shell conventions (folded-in cleanup — see issue\n  [`01-preview-shell-conventions`](issues/01-preview-shell-conventions.md)):**\n  the Gallery adopts the _corrected_ shell, not today's template-literal one — a\n  real `index.html` static file served via `serveFile`, and no inline `<style>`\n  block (Twind utility classes only, per project convention). This cleanup is\n  small and can land early against `preview/` before the full Gallery is built;\n  the Gallery then inherits it.\n- **Content:** one section per shipped component showing its full variant/size/\n  tone matrix, plus the token swatches and the interactive examples. The Mode\n  toggle is driven by `useKylaMode()` (not a hand-rolled toggle) — dogfooding\n  the Provider's Mode ownership.\n- **Generation approach (open question in the sketch — decided here):**\n  **hand-written** sections per component for v1. A metadata-driven generator\n  (the sketch's alternative) is deferred until the component set stabilizes;\n  hand- written is lower-risk and needs no new metadata layer.\n- **Relationship to `preview/`:** this supersedes `preview/` as the canonical\n  surface. The WIP banner and \"not a stable API\" framing are dropped once it's\n  the blessed Gallery; the corrected shell (above) is kept.\n- **Dialog:** once [Dialog](../dialog-radix/spec.md) ships, the Gallery is where\n  its open/close/focus-trap behavior is manually verifiable in-browser (the\n  behavior backstop that PRD refers to).\n\n## Testing Decisions\n\n- **What makes a good test:** it asserts the Gallery's _external_ HTTP behavior\n  — that the route serves, and that the served markup contains the expected\n  proof — not the internal React tree.\n- **Seam (HTTP, highest available for a served surface):** fetch the Gallery\n  route and assert:\n  - a `200` with an HTML content-type;\n  - each shipped component's section is present;\n  - token utility classes (e.g. `bg-[color:var(--kyla-…)]`) appear in the served\n    markup — a direct check that the render path emits the hinted classes rather\n    than silently dropping them.\n- **Behavior (browser, optional backstop):** the Mode toggle flipping the\n  palette and Dialog interactions are the higher-fidelity checks; run them in a\n  real browser against the live Gallery. Not required for the PRD's automated\n  seam.\n- **Modules tested:** the Gallery's HTTP handler.\n- **Prior art:** the existing `preview/index.tsx` handler (shell + `serveFile` +\n  `/source`) is the working reference for serving on Val Town.\n\n## Out of Scope\n\n- **Metadata-driven Gallery generation** (deferred; hand-written for v1).\n- A fuller prose/MDX docs site (the Gallery is its seed, not its replacement).\n- The **Starter** val — [separate PRD](../starter/spec.md).\n- Building the components themselves —\n  [component set PRD](../v1-component-set/spec.md).\n\n## Further Notes\n\n- The Gallery is load-bearing beyond docs: because the Twind \"missing `color:`\n  hint\" failure is _invisible_, the Gallery is the fastest place a human spots\n  an unstyled element. Keep it exercising real components in real Modes.\n",[],[18,97,624,489],"gallery","370155dd-1396-4a3e-8540-916224d14e68","03-gallery-dialog-backstop.md","019f624e-0dc9-701d-a887-c6eb7ac036b9","019f624e-0dc9-701d-a887-c8f8dd92b218",["D",1784060710350],"# 03 · Wire Dialog into the Gallery as the behavior backstop\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Gallery — self-hosted docs surface](../spec.md)\n\n## What to build\n\nAdd `Dialog` to the Gallery so its interactive behavior is manually verifiable\nin-browser — the behavior backstop the [Dialog PRD](../../dialog-radix/spec.md)\nrefers to (open/close, focus-trap, ESC, in-portal token resolution), which the\nrender-seam test deliberately does not cover.\n\nEnd-to-end behavior:\n\n- A Gallery section that imports `Dialog` from its own path (not the barrel) and\n  renders a real, openable example exercising trigger/content/title/description/\n  close.\n- The example confirms, in a real browser against the live Gallery, that the\n  dialog opens/closes, traps focus, closes on ESC and overlay click, and that\n  token custom properties resolve correctly through the Radix portal in both\n  Modes.\n\n## Acceptance criteria\n\n- [ ] The Gallery renders an openable `Dialog` example imported from Dialog's\n      own path (Dialog stays out of the `mod.ts` barrel).\n- [ ] Open/close, focus-trap, ESC, and overlay-click close are manually\n      verifiable in-browser against the live Gallery.\n- [ ] In-portal token resolution is correct in both light and dark Mode (no\n      wrong-theme flash inside the modal).\n\n## Blocked by\n\n- [02 — Promote preview into the canonical Gallery](./02-gallery-build.md)\n- [dialog-radix 01 — Dialog behind its own import path](../../dialog-radix/issues/01-dialog-radix-component.md)\n",[],[18,97,624,97,626],"79a20be5-9f5e-4dc7-9bb5-e48a1350e307","02-gallery-build.md","019f624e-0dc9-701d-a887-c337e8203578",["D",1784060710350],"# 02 · Promote preview into the canonical Gallery\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Gallery — self-hosted docs surface](../spec.md)\n\n## What to build\n\nPromote the WIP `preview/` into the real **Gallery** served at `kyla-ui`'s HTTP\nroute: the blessed, self-hosted docs surface that renders every shipped\ncomponent in its variants and Modes, and the in-browser proof that Twind +\ntokens + Provider render correctly on Val Town.\n\nEnd-to-end behavior:\n\n- Served from `kyla-ui`'s HTTP route, reusing the _corrected_ shell mechanics\n  (Twind before first paint, importmap for `npm:` specifiers, `std/catch`,\n  `serveFile`, `/source` redirect). The Gallery **imports** the library from\n  `mod.ts` (and Dialog's own path) and modifies nothing.\n- One **hand-written** section per shipped component showing its full\n  variant/size/tone matrix, plus the design-token swatches.\n- A Mode toggle driven by the library's own `useKylaMode()` (not a hand-rolled\n  toggle).\n- The `preview/` WIP framing is dropped — the 🚧 banner and \"not a stable API\"\n  language go away once this is the canonical Gallery.\n- An HTTP-seam test asserts the route's external behavior.\n\nDialog's in-browser behavior backstop is a follow-up\n([03](./03-gallery-dialog-backstop.md)).\n\n## Acceptance criteria\n\n- [ ] The Gallery is served from `kyla-ui`'s HTTP route using the corrected\n      shell (real `index.html`, no inline `<style>`), imports the real library,\n      and modifies nothing.\n- [ ] Each shipped component has a hand-written section rendering its full\n      variant/size/tone matrix; token swatches are shown.\n- [ ] A Mode toggle driven by `useKylaMode()` flips the palette across\n      light/dark/system.\n- [ ] The `preview/` WIP banner and \"not a stable API\" framing are removed.\n- [ ] An HTTP-seam test asserts a `200` HTML response, that each shipped\n      component's section is present, and that token utility classes (e.g.\n      `bg-[color:var(--kyla-…)]`) appear in the served markup — passing under\n      `deno test`.\n\n## Blocked by\n\n- [01 — Bring the preview shell in line with platform conventions](./01-preview-shell-conventions.md)\n  — the Gallery inherits the corrected shell.\n- [v1-component-set 02 — Layout & container primitives](../../v1-component-set/issues/02-layout-and-container-primitives.md)\n  — components to render.\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n  — components to render.\n",[],[18,97,624,97,634],"48ffdc4c-0d71-40de-80fb-c549b91ce31d","01-preview-shell-conventions.md","019f624e-0dc9-701d-a887-be24fddb6dc7",["D",1784060710350],"# 01 · Bring the preview shell in line with platform conventions\n\nStatus: ready-for-agent Labels: ready-for-agent\n\nImplementation issue under the [Gallery PRD](../spec.md). The Gallery adopts the\ncorrected shell this issue produces, so this can land early against `preview/`\nbefore the full Gallery is built. Target: `nbbaier/kyla-ui`, file\n`preview/index.tsx`.\n\n## Context\n\n`preview/`'s route was reviewed against Val Town's documented React/HTTP\nconventions. Two deviations in the HTML shell built inside `preview/index.tsx`:\n\n1. **HTML shell is a template-literal string, not a real file.** The full\n   `<!doctype html>` document is built as a JS template literal and returned via\n   `new Response(html, ...)`. Val Town's own `templates/react-hono-starter`\n   ships a real `frontend/index.html` static file served via `serveFile()`,\n   satisfying the same \"Twind must load before first paint\" requirement\n   (ADR-0001) with a `<script>` tag in that static file. Template-literal HTML\n   gets no syntax highlighting, linting, or type checking.\n2. **Inline `<style>` block in the shell.** The template literal includes a\n   `<style>` tag (body margin reset + the `#root:empty::before` \"Loading\n   preview…\" placeholder). Project convention is Twind/Tailwind utility classes\n   only — no inline `<style>` tags or hand-written CSS.\n\n## Proposed fix\n\n- Extract the shell markup into a real `preview/index.html` file, keeping the\n  Twind `<script>` tag, the importmap (for the `npm:clsx` / `npm:tailwind-merge`\n  specifiers), and the `std/catch` error-reporting script exactly as they are\n  today.\n- Update `preview/index.tsx` to serve that file via\n  `serveFile(\"/preview/index.html\", import.meta.url)` instead of the inline\n  template string. Keep the existing `/source` redirect and the `.ts/.tsx`\n  passthrough (for `client.tsx`, `app.tsx`, `../mod.ts`, etc.) unchanged.\n- Replace the inline `<style>` block with Twind utility classes. The\n  `#root:empty::before` loading-placeholder trick has no direct Tailwind\n  equivalent for `:empty` — either keep one minimal, clearly-commented `<style>`\n  rule just for that, or (preferred, if simple) render an explicit loading\n  placeholder element inside `#root` in the HTML so Twind classes style it\n  directly and the `<style>` tag can be dropped entirely.\n\n## Acceptance criteria\n\n- `preview/index.tsx` no longer contains a template-literal HTML string.\n- No inline `<style>` tag remains, or the one narrow exception is commented with\n  why Twind can't express it.\n- Twind script, `catch` script, importmap, and `/source` redirect all still\n  present and working.\n- `preview/` route verified via `fetch_val_endpoint` after the change — the page\n  still renders the Button / token / mode-switcher showcase with no console\n  errors (check `get_logs`).\n\n## Out of scope\n\n- Kylä UI's Button variant names (`primary`/`subtle`/`ghost`/`danger`) and size\n  scale (`sm`/`md`/`lg`) intentionally differ from `val.town/_ui`'s own\n  vocabulary — a deliberate design choice (modeled on Cloudflare Kumo per\n  CONTEXT.md), not a bug to fix.\n",[],[18,97,624,97,641],"850f1aea-4e23-499f-a3aa-5d41eda861f9",["D",1784060710350],[257,258,259],[18,97,624,97],"9a79d304-05a0-4c57-9689-b8d9bdbd0de5",["D",1784060710350],[256,260],[18,97,624],"d1ab2005-d20f-4ee9-aaae-7727c7a1fffe","019f624e-0dc9-701d-a887-b417a3469bf1","019f624e-0dc9-701d-a887-b9a054ca3514",["D",1784060710350],"# PRD: Dialog (Radix-backed)\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Brings the first Radix-backed component into the library, exercising the\n> hybrid-headless split (ADR-0002) and the version-pinned distribution contract\n> (ADR-0004) in real code — not just the throwaway spike. Depends on the\n> [v1 component set](../v1-component-set/spec.md) for surrounding styled pieces\n> and on the [scales & palette](../structural-scales-palette/spec.md) for\n> tokens.\n\n## Problem Statement\n\nKylä's architecture bets on a **hybrid foundation**: hand-roll simple visual\ncomponents with zero dependencies, and build the hard interactive ones on a\nheadless library (ADR-0002). That bet is currently proven only in a separate\nthrowaway val (`nbbaier/kyla-ui-spike`). No hard interactive component ships in\nthe library, so the load-bearing mechanics — Radix imported behind its own\nimport path, kept out of the barrel so it only loads when used, with the\nReact-18.2.0 `?deps=` pin propagated through Radix's transitive graph — are\nunexercised in the real codebase.\n\n## Solution\n\nBring **`Dialog`** into the library as the first Radix-backed component. It\nlives behind its own import path (a root re-export, e.g. `dialog.tsx`) kept\n**out** of the `mod.ts` barrel, so consumers who never use it never load Radix.\nIt is styled entirely from the token system like every other component; its\nbehavior and accessibility (focus trap, ESC, `aria-*`, portal) are delegated to\nRadix. The public surface stays styling-only — Radix primitives remain internal\nso a later Radix→Base UI swap isn't an API break.\n\n## User Stories\n\n1. As a consumer, I want a `Dialog` component styled on-system, so that modals\n   match the rest of my Kylä app.\n2. As a consumer, I want to import `Dialog` from its own path, so that apps that\n   don't use it never pay Radix's download/parse cost.\n3. As a consumer, I want the `Dialog` to trap focus and close on ESC and overlay\n   click, so that it's accessible without me wiring ARIA by hand.\n4. As a consumer, I want `Dialog` to compose the way I'd expect (trigger,\n   content, title, description, close), so that I can build real modals.\n5. As a consumer, I want the token theme (surfaces, accent, radius) to apply\n   inside the modal, including through the portal, so that light/dark mode is\n   correct everywhere.\n6. As a consumer, I want to override the content's `className`, so that I can\n   size or position a specific dialog without forking.\n7. As a consumer pinning a version, I want `Dialog` to work under the pinned\n   React 18.2.0, so that Radix's transitive deps don't hit the `useState` null\n   mismatch.\n8. As a component author, I want Radix primitives kept internal to the Dialog\n   module, so that swapping to Base UI later doesn't change the public API.\n9. As a maintainer, I want `Dialog` excluded from the `mod.ts` barrel, so that\n   the zero-dep core stays zero-dep.\n10. As a maintainer, I want the React-version pin applied at Radix's import, so\n    that the spike's mismatch finding is encoded in shipping code.\n11. As an end user, I want a modal that manages focus and keyboard correctly, so\n    that I can use it with assistive tech.\n12. As an end user, I want the dialog's colors to match my OS light/dark\n    preference, so that it doesn't flash the wrong theme.\n\n## Implementation Decisions\n\n- **Modules built:** `src/components/dialog.tsx` (styled composition over Radix)\n  plus a root re-export path (e.g. `dialog.tsx` at the repo root) that is the\n  consumer's import URL. **Not** added to `mod.ts` (ADR-0002/0004).\n- **React pin (spike finding, load-bearing):** import Radix with\n  `?deps=react@18.2.0,react-dom@18.2.0` so the pin propagates through Radix's\n  whole transitive graph and defuses the React-mismatch `useState` null error.\n- **Public API is styling-only:** expose a composed, token-styled Dialog surface\n  (root/trigger/content/overlay/title/description/close). Radix's own primitives\n  are an internal implementation detail and are not re-exported, so a later\n  Radix→Base UI variant is not an API break.\n- **Tokens through the portal:** content uses the `elevated` surface, overlay a\n  scrim, focus ring from tokens; verify token custom properties resolve inside\n  the Radix portal (the spike confirmed `light-dark()` resolves in-portal).\n- **Radix first** (proven on VT); a Base-UI-backed variant stays deferred.\n- **Twind hint discipline still applies** inside the portal — all colors go\n  through the `tw` helpers (ADR-0001), no bare `[var(--…)]` color utilities.\n\n## Testing Decisions\n\n- **What makes a good test:** it verifies **our** contribution — that we mounted\n  Radix with the right props and token styling — and does **not** re-test\n  Radix's own guarantees. Testing that Radix traps focus is testing Radix, not\n  Kylä.\n- **Two-level seam:**\n  - **Primary (server-render, uniform with the component set):** render the\n    Dialog's trigger/closed surface (and the content in an open-by-default\n    configuration where feasible) to an HTML string and assert our wiring —\n    token utility classes present on overlay/content, `className` override wins,\n    title/ description associated, close affordance present. This catches the\n    silent Twind hint failure the same way as the rest of the set.\n  - **Behavior backstop (browser):** open/close, focus-trap, ESC, and in-portal\n    token resolution are interaction guarantees best confirmed in a real browser\n    — via the [Gallery](../gallery/spec.md) once Dialog is listed there. Treat\n    this as the higher-fidelity seam for _behavior_, not a unit test of Radix\n    internals.\n- **Modules tested:** `src/components/dialog.tsx` (render seam).\n- **Prior art:** the render-to-HTML harness from the\n  [v1 component set](../v1-component-set/spec.md); the spike val is the\n  reference for the working Radix + React-pin + portal configuration.\n\n## Out of Scope\n\n- Other Radix-backed components (`Popover`, `Menu`, `Tabs`, `Tooltip`,\n  `Combobox`, `Toast`) — v1.1+.\n- The **Base UI** variant (deferred until Radix proves the path).\n- Adding `Dialog` to the barrel (deliberately excluded).\n\n## Further Notes\n\n- This PRD is the real-code payoff of the spike. If anything in the spike's\n  Radix configuration proves brittle in the library, capture it as an ADR update\n  rather than a local workaround.\n- Because `Dialog` defines the _pattern_ for every future Radix-backed\n  component, keep the internal/exposed boundary crisp — it's what protects the\n  Radix→Base UI option.\n",[],[18,97,662,489],"dialog-radix","5348002d-8b27-45a4-8256-99f438aaf038","01-dialog-radix-component.md","019f624e-0dc9-701d-a887-aff39149fa1c","019f624e-0dc9-701d-a887-b367f8bffbce",["D",1784060710350],"# 01 · Dialog behind its own import path (Radix + React pin + token styling)\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Dialog (Radix-backed)](../spec.md)\n\n## What to build\n\nBring `Dialog` into the library as the first Radix-backed component, encoding\nthe hybrid-headless split (ADR-0002) and the version-pinned distribution\ncontract (ADR-0004) in shipping code. This ticket defines the pattern every\nfuture Radix-backed component follows, so keep the internal/exposed boundary\ncrisp.\n\nEnd-to-end behavior:\n\n- A token-styled `Dialog` composition over Radix\n  (root/trigger/content/overlay/title/description/close), styled entirely from\n  the token system; behavior and accessibility (focus trap, ESC, `aria-*`,\n  portal) delegated to Radix.\n- Served from its **own root re-export path** (e.g. `dialog.tsx`) and kept\n  **out** of the `mod.ts` barrel, so consumers who never use it never load\n  Radix.\n- Radix imported with `?deps=react@18.2.0,react-dom@18.2.0` so the pin\n  propagates through Radix's transitive graph and defuses the React-mismatch\n  `useState` null error found in the spike.\n- Public surface is styling-only — Radix primitives stay internal (not\n  re-exported) so a later Radix→Base UI swap is not an API break. Content uses\n  the `elevated` surface, overlay a scrim, focus ring from tokens; token custom\n  properties resolve inside the portal. All colors go through the `tw` helpers\n  (ADR-0001).\n- A render-seam test asserts **our** wiring — token utility classes on\n  overlay/content, `className` override wins, title/description associated,\n  close affordance present — and does not re-test Radix's own guarantees.\n\nThe in-browser behavior backstop (open/close, focus-trap, ESC, in-portal token\nresolution) is verified via the [Gallery](../../gallery/spec.md), not here.\n\n## Acceptance criteria\n\n- [ ] `Dialog` renders a token-styled composition over Radix; overlay/content\n      carry token utility classes via the `tw` helpers (no bare `[var(--…)]`\n      color utilities).\n- [ ] `Dialog` is importable from its own root re-export path and is **not**\n      exported from `mod.ts`.\n- [ ] Radix is imported with the `?deps=react@18.2.0,react-dom@18.2.0` pin; the\n      dialog renders under the pinned React without the `useState` null\n      mismatch.\n- [ ] Radix primitives are not re-exported; the public surface is styling-only.\n- [ ] A render-seam test asserts token classes on overlay/content, `className`\n      override wins, title/description association, and close affordance —\n      passing under `deno test`.\n\n## Blocked by\n\n- [v1-component-set 01 — Render-to-HTML harness + Text / Heading](../../v1-component-set/issues/01-render-harness-and-typography.md)\n  — provides the render-seam harness the test reuses.\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n  — provides the surrounding styled pieces real modals compose with.\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the surface/scrim/focus tokens resolved through the portal.\n",[],[18,97,662,97,664],"ae41f606-d715-44f7-b51d-57580e07a2e9",["D",1784060710350],[253],[18,97,662,97],"b1c145fa-f886-41ad-93c5-e1daa12847a2",["D",1784060710350],[252,254],[18,97,662],["D",1784060710350],[251,255,261,267,274],[18,97],"cf3d9206-37a6-49c5-8ec8-e79a98e89a49","2026-06-18-design-and-foundation.md","019f624e-0dc9-701d-a887-a447747c39d5",["D",1784060710350],"# Handoff — Kylä UI design + foundation (2026-06-18)\n\nPicking up the `nbbaier/kyla-ui` component library for Val Town. This thread did\nthe design grilling, proved the runtime substrate, and built the styling\nfoundation + the first component (`Button`). This doc is a pointer map + \"what's\nnext\", not a re-spec — the real content lives in the artifacts referenced below.\n\n## Read these first (don't duplicate them)\n\n- [`CONTEXT.md`](../../CONTEXT.md) — glossary / shared language.\n- [`docs/v1-design-sketch.md`](../v1-design-sketch.md) — the design hub,\n  **Implementation status** section, open spikes (all ✅), and the \"Deliberately\n  deferred\" list.\n- [`docs/adr/0001..0004`](../adr/) — the load-bearing decisions and _why_.\n- [`README.md`](../../README.md) — consumer-facing quick start.\n\n## State of the world\n\n- **Two vals.** `nbbaier/kyla-ui` (the library; locally synced to this working\n  dir via `vt`). `nbbaier/kyla-ui-spike` (throwaway substrate proof — all 4\n  spikes green in-browser; keep it around as a live sandbox).\n- **Foundation built & verified on the runtime:** `mod.ts` barrel + `src/utils/`\n  (`cn`, `variants`), `src/theme/` (`tokens`, `tw`, `provider`),\n  `src/components/` (`button`). Layout rationale is in the sketch's\n  Implementation status.\n- **`Button`** ships with `variant` × `size`, token focus ring, ref forwarding,\n  escape-hatch `className`. Verified by server-render (`renderToStaticMarkup`).\n- Everything is pushed; `vt status` was clean at handoff time.\n\n## Gotchas that will bite you if forgotten\n\n1. **The `color:` hint is mandatory** for token color utilities —\n   `bg-[color:var(--…)]`, never `bg-[var(--…)]` (the latter silently renders\n   nothing; no error). Always go through the `tw.*` builders in\n   `src/theme/tw.ts`, which bake it in. (ADR-0001.)\n2. **Twind lives in the HTML shell**, not the Provider (must load before first\n   paint). The Provider injects only the token stylesheet. (ADR-0001.)\n3. **Pin React to 18.2.0 everywhere**, including Radix via\n   `?deps=react@18.2.0,react-dom@18.2.0`, or you hit the `useState` null error.\n   (ADR-0002.)\n4. **`cn(componentClasses, className)` call order** is the contract — caller's\n   `className` must come last to win.\n5. **Token values in `src/theme/tokens.ts` are provisional** — not the real\n   palette yet.\n\n## Suggested next steps (roughly in order)\n\n1. **See `Button` live** — add a showcase row to `kyla-ui-spike`'s `App.tsx` to\n   eyeball all variant/size combos + hover/focus in a browser. (Quick\n   loop-closer.)\n2. **Real palette + structural scales** — replace provisional tokens with\n   AA-checked surface/fg/border ramps + spacing/radius/type scales.\n   Highest-leverage deferred item.\n3. **More components** — `Card`, `Text`/`Heading`, `Input`, `Textarea`, `Label`,\n   `Badge`, `Stack`, `Box`, `Divider`, then native-styled `Select`. Reuse the\n   Button pattern.\n4. **`Dialog` (Radix)** — first component behind its own import path:\n   `src/components/dialog.tsx`\n   - a root `dialog.ts` re-export, kept OUT of `mod.ts` (ADR-0002). Exercises\n     the split.\n5. **Gallery** — the library's self-hosted docs HTTP route (CONTEXT.md →\n   \"Gallery\").\n6. **Starter** — `kyla-ui-starter`: a tiny todo app (CONTEXT.md → \"Starter\").\n\n## How to work in this repo\n\n- Edit locally, then `vt push` (and `vt pull` first if needed). `vt status`\n  shows drift.\n- **Smoke-test pattern that works without a browser:** create a throwaway\n  `src/_smoke.ts(x)` in the val, `run_file` it (use `renderToStaticMarkup` from\n  `react-dom@18.2.0/server` to render components to a class string), then\n  `delete_file` it. Used twice this thread; clean and fast.\n- For anything UI/platform-specific on Val Town, pull the official skill via the\n  valtown MCP `find_val_town_skills` tool rather than working from memory.\n\n## Suggested skills for the next session\n\n- **valtown:react-ui** — the canonical conventions (Twind, React pin,\n  view-source) for any component or Gallery work.\n- **grill-with-docs** — if revisiting design decisions (palette, theming v2, new\n  components' APIs); it updates `CONTEXT.md` / ADRs inline.\n- **valtown:sqlite-storage** + **valtown:http-endpoints** — when building the\n  Starter todo app and/or the Gallery route.\n- **rams** (or **impeccable**) — accessibility / visual-design review once there\n  are enough components and the real palette to evaluate.\n",[],[18,103,683],["D",1784060710350],[249],[18,103],"f3736471-a0be-4a2f-a0ea-9b9c180b9dc1","triage-labels.md","019f624e-0dc9-701d-a887-9faeeb522497",["D",1784060710350],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those\nroles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning                                  |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |\n| `needs-info`               | `needs-info`         | Waiting on reporter for more information |\n| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |\n| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |\n| `wontfix`                  | `wontfix`            | Will not be actioned                     |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the\ncorresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n\n## Completion\n\nThe five roles above are _triage_ states — none marks work as finished. This\nrepo adds one local completion label beyond that vocabulary:\n\n| Label  | Meaning                                                                  |\n| ------ | ------------------------------------------------------------------------ |\n| `done` | Work merged to `main` and shipped in a Release (see `issue-tracker.md`). |\n",[],[18,109,693],"40d5f176-e03d-4972-8f43-a119f9aeba78","issue-tracker.md","019f624e-0dc9-701d-a887-9b3c9f2732ef",["D",1784060710350],"# Issue tracker: Local Markdown\n\nIssues and specs (you may know a spec as a PRD) for this repo live as markdown\nfiles in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues/<feature-slug>/`\n- The spec is `docs/issues/<feature-slug>/spec.md`\n- Implementation issues are `docs/issues/<feature-slug>/issues/<NN>-<slug>.md`,\n  numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file\n  (see `triage-labels.md` for the role strings)\n- A ticket is **done** when its work merges to `main` (which cuts a Release per\n  ADR-0004): set `Status: done` and add a `Landed: v<NNN>` line recording the\n  Release version\n- Comments and conversation history append to the bottom of the file under a\n  `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues/<feature-slug>/` (creating the directory if\nneeded).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or\nthe issue number directly.\n\n## Wayfinding operations\n\nUsed by `/wayfinder`. The **map** is a file with one **child** file per ticket.\n\n- **Map**: `docs/issues/<effort>/map.md` — the Notes / Decisions-so-far / Fog\n  body.\n- **Child ticket**: `docs/issues/<effort>/issues/NN-<slug>.md`, numbered from\n  `01`, with the question in the body. A `Type:` line records the ticket type\n  (`research`/`prototype`/`grilling`/`task`); a `Status:` line records\n  `claimed`/`resolved`.\n- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked\n  when every file it lists is `resolved`.\n- **Frontier**: scan `docs/issues/<effort>/issues/` for files that are open,\n  unblocked, and unclaimed; first by number wins.\n- **Claim**: set `Status: claimed` and save before any work.\n- **Resolve**: append the answer under an `## Answer` heading, set\n  `Status: resolved`, then append a context pointer (gist + link) to the map's\n  Decisions-so-far in `map.md`.\n",[],[18,109,700],"8432c231-b9c7-4976-bd70-669d9b7c0492","domain.md","019f624e-0dc9-701d-a887-949a68cdf323",["D",1784060710350],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when\nexploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one\n  `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In\n  multi-context repos, also check `src/<context>/docs/adr/` for context-scoped\n  decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their\nabsence; don't suggest creating them upfront. The `/domain-modeling` skill\n(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates\nthem lazily when terms or decisions actually get resolved.\n\n## File structure\n\nSingle-context repo (most repos):\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│   ├── 0001-event-sourced-orders.md\n│   └── 0002-postgres-for-write-model.md\n└── src/\n```\n\nMulti-context repo (presence of `CONTEXT-MAP.md` at the root):\n\n```\n/\n├── CONTEXT-MAP.md\n├── docs/adr/                          ← system-wide decisions\n└── src/\n    ├── ordering/\n    │   ├── CONTEXT.md\n    │   └── docs/adr/                  ← context-specific decisions\n    └── billing/\n        ├── CONTEXT.md\n        └── docs/adr/\n```\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal,\na hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift\nto synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either\nyou're inventing language the project doesn't use (reconsider) or there's a real\ngap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than\nsilently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[18,109,707],["D",1784060710350],[245,246,247],[18,109],"9836fc1e-bd44-4eea-8e3a-2eaf80d84e7c","0005-val-town-visual-language-default-theme.md","019f624e-0dc9-701d-a887-8e3ac4464334",["D",1784060710350],"# Default theme adopts the Val Town visual language\n\nKylä UI ships **one opinionated default theme** (CONTEXT.md → Theme; ADR-0001).\nUntil now its palette and scales were provisional placeholders, implicitly\nderived from our Cloudflare Kumo lineage. We decide that the default theme's\n**values** — color palette (light + dark), the spacing / radius / type scales,\nand the component-level styling those map to — **conform to the Val Town UI\nstyle guide** (`val.town/_ui`), so that an app built with Kylä looks native to\nVal Town rather than like a foreign design system dropped onto the platform.\n\nThis is a decision about **values, not architecture and not API**. It changes\nwhat the `--kyla-*` tokens resolve to; it does not change how the system is\nbuilt or how consumers call it:\n\n- **Architecture stays Kumo-modeled.** Semantic tokens as CSS custom properties\n  (ADR-0001), the hybrid headless foundation (ADR-0002), primitives + components\n  — all unchanged. The token indirection is precisely what lets us retarget the\n  look without touching components.\n- **API vocabulary stays Kylä's own.** Kylä keeps its Kumo-style variant model —\n  `Button` `variant` = `primary | subtle | ghost | danger`, `size` =\n  `sm | md | lg`, etc. — which deliberately differs from `val.town/_ui`'s own\n  class vocabulary. Adopting VT's _values_ does not rename Kylä's _props_. (This\n  is consistent with the note in the Gallery's preview-shell issue: the\n  divergence recorded there was about **names**, not **palette**.)\n- **Positioning (ADR-0003) is reinforced, not changed.** \"Lead with consistency\"\n  now means consistency _with the surrounding Val Town platform_, not just\n  internal self-consistency.\n\n## Source of truth for the values\n\nThe values are extracted from Val Town's own style guide and captured in\n`docs/reference/val-town-style-guide.md`, so downstream PRDs consume concrete\nnumbers rather than \"conform to VT\" prose. Primary sources (Val Town's site is\nRemix, server-rendered, so the component markup and its compiled token CSS are\nfetchable over plain HTTPS):\n\n- `https://www.val.town/_ui/*` — the live style-guide pages (button, callout,\n  card, dropdown, input, select, textarea, forms, privacy-badge); SSR markup\n  gives each component's verbatim utility classes.\n- `https://static2.esm.town/assets/tailwind-*.css` — the compiled Tailwind v4\n  stylesheet the pages link: the `@theme` token scale (`--color-*` oklch ramp,\n  `--spacing`, `--radius-*`, `--text-*`, fonts, weights) and VT's semantic\n  aliases split across `:root`/`.dark`.\n- `https://www.val.town/x/dcm31/townie-mobile/code/frontend/style.css` — a\n  hand-distilled token artifact billed by its author as Val Town's style guide\n  (\"gave Fable our style guide\"); used as a corroborating cross-check (it is\n  Tailwind v3, so the live `_ui` v4 values are treated as source of truth).\n\n## Considered Options\n\n- **Invent an opinionated palette/scale (Kumo-flavored)** — rejected: arbitrary,\n  and it forfeits the chance to make Kylä apps look like they belong on their\n  host platform. A bespoke look is a liability, not a feature, for this\n  audience.\n- **Adopt VT's values _and_ its class vocabulary** — rejected/deferred:\n  API-breaking, and Kylä's typed variant model is more expressive than raw\n  utility classes. Revisit only if there's a concrete reason to mirror VT's prop\n  names; it is explicitly **not** part of this decision.\n- **Adopt VT's values as the default theme; keep Kylä's architecture and API** —\n  **chosen.**\n\n## Consequences\n\n- The `structural-scales-palette` PRD is reframed: instead of _designing_ a\n  palette + scales, it **ports** the Val Town style guide's palette and scales\n  into the token stylesheet, sourced from the reference doc above. This is why\n  the decision must be recorded before that PRD is implemented.\n- **Coverage parity is the bar, not just palette adoption.** The\n  `v1-component-set` PRD uses `val.town/_ui` as the styling reference for its\n  per-component variant→token maps (button sizing/radius, input styling, badge\n  tones) — but \"conforms to VT\" means matching the _set_ of variants, states,\n  and techniques VT ships per component (color variants, icon-only sizing,\n  hover/active/disabled states, mode-adaptive techniques like `blend`'s\n  `mix-blend-mode`), not only porting palette hex/oklch values onto whatever\n  variant list a component already happens to have. Kylä's prop _names_ stay its\n  own (previous bullet); the _coverage_ those names collectively provide must\n  match VT's per-component surface, checked against\n  `docs/reference/val-town-style-guide.md`. This applies retroactively: a\n  component the roadmap already marks \"Built\" (e.g. `Button`, shipped with 4 of\n  VT's 7 button variants) is still subject to this bar and gets a revision\n  slice, not a pass.\n- **AA contrast (ADR-0003) remains the stricter constraint.** Every sanctioned\n  foreground/surface pairing must meet WCAG AA in both modes. If VT's guide has\n  a pairing that falls short, Kylä's AA guarantee wins and that token value is\n  adjusted; the contrast test enforces this regardless of source.\n- **Kylä keeps its own surface hierarchy.** The extraction\n  (`docs/reference/val-town-style-guide.md`) found VT's _semantic_ layer is\n  thinner than Kylä's — VT names only\n  `background / text / border / muted / shadow` and elevates by shadow over a\n  single surface. Kylä retains its structural `base` → `elevated` → `recessed`\n  hierarchy and `hairline` (CONTEXT.md); where VT has no named token, those\n  values are sourced from VT's slate component fills. So the default theme is\n  **VT's palette under Kylä's structure**, not a strict subset of VT's tokens.\n- **The token vocabulary expands to cover VT's accent + status roles.** VT uses\n  accent in three roles a single `accent`/`accent-fg` can't hold (fill,\n  focus-ring, accent-text-on-surface), and ships a success tone. The canonical\n  `--kyla-*` vocabulary therefore gains `accent-ring`, `accent-text`,\n  `danger-fg`, and a `success`/`success-fg` tone (updating CONTEXT.md's token\n  list and the `ColorToken` union). These are **structural** additions — the\n  consumer override surface stays small.\n- **One deliberate deviation from VT:** the dark-mode `base` uses `slate-950`\n  (`#020618`), a considered softening of VT's literal true-black (`#000`, 21:1)\n  to reduce large-surface glare. Recorded here so it reads as a choice, not an\n  extraction error; every other default tracks VT.\n- The consumer **override surface** (`--kyla-accent`, `--kyla-radius`, font) is\n  unchanged; its _defaults_ become the VT values, and a consumer can still\n  rebrand within that small surface.\n- If Val Town revises its style guide, Kylä tracks it by re-running the\n  extraction and retuning token values — a values change under the existing\n  Release contract (ADR-0004), not an API change.\n",[],[18,114,717],"d33068a0-6a32-4871-8788-7ba6a4cf5309","0004-version-pinned-upgrade-contract.md","019f624e-0dc9-701d-a887-89e515e9ff83",["D",1784060710350],"# Upgrade contract: main-as-release-line, version pinning\n\nKylä UI is consumed by importing its val from esm.town, where an unpinned import\n(`.../kyla-ui/mod.ts`) auto-redirects to the val's latest version and a consumer\ncan freeze onto a specific version with `?v=NNN`. esm.town does **not** offer\nbranch-name import URLs, so the intuitive \"consumers track a long-lived `stable`\nbranch\" model is not available.\n\nWe therefore make **`main` the stable/release line**: all development happens on\nfeature/dev branches, and a **Release is a merge into `main`.** Because raw work\nnever lands on `main`, HEAD-of-`main` is always a Release. Consumers then have\ntwo contracts:\n\n- **Track latest** — import the unpinned URL; always get the newest Release, so\n  fixes auto-propagate (the upside of consumption-by-import).\n- **Freeze** — pin `?v=NNN` from the README's release table; upgrade\n  deliberately by changing the number.\n\n## Considered Options\n\n- **Long-lived `stable` branch consumers import** — rejected: esm.town has no\n  documented branch-import URL, so it isn't realizable.\n- **Live HEAD with raw development on the imported line** — rejected: any\n  work-in-progress push would reach unpinned consumers; keeping development off\n  `main` is what makes the unpinned URL safe.\n\n## Consequences\n\n- Unpinned consumers receive a new Release the instant a branch merges —\n  _including a breaking one_. The release table plus brief per-release notes are\n  how a consumer decides whether to pin. There is no staging window between\n  merge and propagation.\n- Every merge to `main` mints a new `?v=NNN`; the README maps human release\n  names to those version numbers.\n- For v1 (sole consumer is the maintainer) this can be operated loosely, but the\n  convention costs nothing now and makes external consumption safe later.\n",[],[18,114,724],"e6004a73-ad49-4c09-984d-9868f4ec22d3","0003-consistency-first-bounded-accessibility.md","019f624e-0dc9-701d-a887-8594f31c0577",["D",1784060710350],"# Consistency-first positioning, bounded accessibility\n\nKylä UI is modeled on Cloudflare Kumo, whose headline value is accessibility. We\ndeliberately invert the emphasis: **Kylä leads with visual consistency** — the\nfelt pain for the Val Town audience (people shipping apps fast without a\ndesigner) is that hand-assembled UIs look inconsistent, not that they fail an\naudit. Accessibility remains a real but _quiet_ guarantee underneath, with a\ndeliberately bounded scope for v1.\n\nThe accessibility commitment is exactly: **correct semantic HTML** (native\n`<button>`, real `<label htmlFor>`/`<input id>` association, `<h1–h6>`\nheadings), **token-based visible focus**, **not breaking native keyboard\nbehavior**, and **WCAG-AA contrast on the default theme** (a property of the\nTheme, set once). Anything requiring custom ARIA roles/state is _not_\nhand-rolled — it is built on a Headless Primitive (Radix), which is the dividing\nline of ADR-0002.\n\n## Why record this\n\nA contributor seeing the Kumo lineage will reasonably assume accessibility is\nthe headline and try to chase full WCAG-AA across the hand-rolled zero-dep\ncomponents. That is a deliberate non-goal for v1, not an oversight: the bounded\npromise is one we can actually keep, and \"needs more than semantic HTML\" is\nprecisely the signal a component belongs in the Radix tier. Full WCAG auditing\nis additive and can be revisited later; it should not silently expand v1 scope.\n",[],[18,114,731],"6c310252-b9d9-4e99-b12e-03bf62dc4db8","0002-hybrid-headless-foundation.md","019f624e-0dc9-701d-a887-8272ac1647c4",["D",1784060710350],"# Hybrid headless foundation, Radix-first\n\nKumo builds every component on Base UI headless primitives for accessibility. On\nVal Town a headless library is an unvetted heavy ESM dependency loaded from a\nCDN at runtime, so we take it selectively: **simple visual components (Button,\nCard, Stack, Text, Input, Badge) are hand-rolled with zero dependencies**, and\n**only the genuinely hard interactive components (Dialog, Popover, Menu, Tabs)\nbuild on a third-party headless library.** This keeps the common case\ndependency-free and fast on Val Town while still inheriting accessibility where\nit is expensive to get right.\n\nThe library is **Radix first** — chosen over the maintainer's preferred Base UI\npurely because Radix has a longer track record loading from CDNs — used to prove\nthe pattern works on Val Town. A Base-UI-backed variant is a likely later step\nonce viability is demonstrated.\n\n## Consequences\n\n- Open validation task before committing: confirm a Radix primitive (e.g.\n  Dialog) imports via esm.sh with React pinned to 18.2.0 and hydrates cleanly on\n  Val Town's CSR setup.\n- Swapping the headless library later is contained per-component, not a global\n  rewrite — which is what makes \"Radix now, Base UI later\" affordable.\n",[],[18,114,738],"559d033f-30d8-4d7d-be49-beaf756d0122","0001-no-build-styling-architecture.md","019f624e-0dc8-76d1-b9c6-9b87a2b2be4e",["D",1784060710350],"# No-build styling architecture\n\nKylä UI targets Val Town, which has no build step or bundler. Cloudflare Kumo —\nour model — achieves visual consistency with Tailwind v4 semantic tokens\ncompiled at build time, which we cannot use. We therefore deliver consistency at\nruntime: **semantic design values are defined as CSS custom properties** (a\ntoken stylesheet served by the `kyla-ui` val, using `light-dark()` for automatic\ndark mode), and **components apply them via runtime Twind arbitrary-value\nutilities** (e.g. `bg-[var(--kyla-base)]`). Styles are delivered with a\ndeliberate split (confirmed by the `kyla-ui-spike`): the **Twind script lives in\nthe HTML shell** (it must load before first paint or utilities FOUC, so it\ncannot be React-injected), while the **token stylesheet is injected by the\nProvider at runtime** (idempotently). The Starter ships the shell tag; the\nProvider guarantees the tokens — so \"styles are present\" is a guarantee, not a\nsetup checklist (a manual two-tag `<head>` setup is the documented escape\nhatch).\n\n## Considered Options\n\n- **Tailwind v4 + build step (the Kumo way)** — rejected: requires a\n  bundler/PostCSS, which Val Town does not provide.\n- **Twind with a named-token theme config** (`bg-kyla-base`) — rejected: every\n  consumer app would have to load an identical Twind runtime config or\n  components render wrong; that coupling is a sharp, silent failure mode.\n- **Pure CSS component classes** (`.kyla-button`) — rejected: self-contained but\n  abandons Tailwind/Twind ergonomics and composable variants, and strays from\n  the Val Town idiom.\n\n## Consequences\n\n- Arbitrary-value Twind syntax is noisier, but it lives inside library source;\n  consumers only write `<Button>`.\n- Components only render correctly where Twind is running and the token\n  stylesheet is loaded — hence the Provider (see ADR-0002's sibling delivery\n  decision) is load-bearing.\n- The `light-dark()` CSS function handles dark mode without `dark:` variants,\n  keeping component source theme-agnostic.\n- **Authoring rule (proven by the spike):** semantic-color utilities must carry\n  the `color:` type hint — `bg-[color:var(--kyla-base)]`,\n  `text-[color:var(--kyla-fg)]`, `border-[color:var(--kyla-line)]`. A bare\n  `bg-[var(--…)]` is type-ambiguous and Twind silently emits nothing (the\n  failure is invisible — no error, just an unstyled element). Lengths are\n  unambiguous, so `rounded-[var(--kyla-radius)]` needs no hint. Because the\n  omission fails silently, component authors must not hand-write these strings;\n  the `cn()`/variant layer should emit token utilities through a tiny helper so\n  the hint can never be forgotten.\n",[],[18,114,745],["D",1784060710350],[239,240,241,242,243],[18,114],["D",1784060710350],[238,244,248,250,281,283],[18],["D",1781804868537],["D",1789701064442],{"_11":12,"_167":84},{"_11":12,"_163":-5,"_83":84,"_31":82,"_164":165,"_166":30},{"_39":153,"_13":16,"_33":36,"_154":117,"_155":73,"_156":157,"_158":121,"_159":117,"_160":42,"_161":14,"_162":12},"ctx",{"_52":-5,"_187":795,"_796":797,"_798":799,"_800":30,"_801":30,"_802":30,"_803":24,"_804":-5,"_805":-7,"_806":-7,"_807":26,"_808":30,"_809":30,"_810":-5,"_811":30,"_812":30,"_813":30,"_814":-5},"ENV",{"_766":767,"_768":769,"_770":74,"_771":772,"_773":774,"_775":776,"_777":778,"_779":780,"_781":782,"_783":784,"_785":786,"_787":788,"_789":790,"_791":792,"_793":794},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","71c1b20804b3232a7e513be260cfffc1932a9e97","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]
</article></body></html>

History · docs