[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_610":611,"_612":613},"routes/_app.x.$handle.$name",{"_98":97,"_32":45,"_106":88,"_27":107,"_13":14,"_108":-5,"_11":109,"_110":111,"_112":113,"_114":115,"_116":117,"_20":-5,"_118":-5,"_119":-5,"_120":25,"_121":122,"_123":124,"_125":-5,"_126":-5,"_127":128},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":25},"version",101,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":20,"_35":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":33,"_34":20,"_35":36},"deleted",false,"deletedHere","path","docs/roadmap.md","latestPath","fileId","45b8411a-798a-11f1-b04a-1607ee4eb77e","name","roadmap.md","fileType","content","# Kylä UI — Roadmap\n\nThe dependency-ordered plan for reaching v1. Each row links a PRD in the\n[issue tracker](issues/); vocabulary is in [`../CONTEXT.md`](../CONTEXT.md) and the\nload-bearing decisions are in [`adr/`](adr/). This doc is the synthesis — the\n\"what next and in what order\" — not a re-spec of any single feature.\n\n## Built\n\n- **Styling foundation** — `cn`, `tw` (token utilities with the mandatory `color:`\n hint), `variants`, `KylaProvider` + Mode, provisional token stylesheet.\n- **`Button`** — the reference component (typed variants → tokens, semantic\n element, forwarded ref, escape-hatch `className`, token focus ring).\n- **Substrate proof** — `nbbaier/kyla-ui-spike`, all four spikes green (Radix\n Dialog under the React-18.2.0 pin, Twind + CSS-var tokens, Provider injection,\n `light-dark()` + `data-mode`).\n\n## Planned — dependency order\n\nEach PRD is `ready-for-agent`. Later rows assume earlier ones.\n\n| # | Feature | PRD | Depends on | Why it's here |\n|---|---------|-----|-----------|----------------|\n| 1 | **Structural scales & palette** | [`structural-scales-palette`](issues/structural-scales-palette/PRD.md) | — | Highest-leverage deferred item: fixed spacing/radius/type scales + real AA-checked palette. Where consistency actually lives; unblocks the set. Establishes the first test harness. |\n| 2 | **v1 zero-dep component set** | [`v1-component-set`](issues/v1-component-set/PRD.md) | 1 | Text/Heading, Card, Input, Textarea, Label, Badge, Stack, Box, Divider, Select — the rest of the importable core, following the `Button` pattern. |\n| 3 | **Dialog (Radix-backed)** | [`dialog-radix`](issues/dialog-radix/PRD.md) | 2 | First headless-backed component, behind its own import path, out of the barrel. Exercises the hybrid split (ADR-0002) in real code. |\n| — | **Preview shell conventions** | [`gallery`](issues/gallery/PRD.md) (folded in) | — | Bring the `preview/` HTML shell in line with platform conventions (real `.html` file, no inline `\n \n \n

\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",[],[212,382],"bd982d70-d147-4681-9ef1-354e2a19b0a3","client.tsx","42cc926a-7987-11f1-814e-1607ee4eb77e",["D",1783375727322],"/** @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",[],[212,390],"4ff971c2-fb5e-4c5f-a8f7-d5d7cc872908","app.tsx","42cc23d4-7987-11f1-814e-1607ee4eb77e",["D",1783375727322],"/** @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

{title}

\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

{token}

\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 current Kylä UI surface — one component (Button) plus the theme\n system. Palette 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",[],[212,397],["D",1783375727322],[263,264,265],[212],"05e39f36-2b11-441b-96a4-059c779a90c3",["D",1783378956774],[],[218,33],"7bfbe88f-a1d2-4bed-ba24-1cf295c3ee4b","reference","c798cbce-798e-11f1-b338-1607ee4eb77e",98,["D",1783378956608],[],[218,411],"038da3d7-0063-4fc7-a84e-8136fa147344","PRD.md","45c41f76-798a-11f1-99dd-1607ee4eb77e","45627c76-798a-11f1-b04a-1607ee4eb77e",87,["D",1783377020803],"# PRD: v1 zero-dependency component set\n\nStatus: ready-for-agent\nLabels: 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/PRD.md)\n> foundation for spacing/type. Excludes the Radix-backed `Dialog`\n> ([its own PRD](../dialog-radix/PRD.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 the\nper-app inconsistency Kylä exists to prevent, and loses the bounded accessibility\nguarantees (label association, focus ring, semantic elements) that come baked into\nKylä 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 and\ntype come from the structural scale tokens, so the set is consistent with itself\nand 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`.\n\n## User Stories\n\n1. As a consumer, I want a `Text` component with typed size/weight/tone props, 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 headings are semantic and on-scale.\n3. As a consumer, I want a `Card` with surface and padding variants, so that I can group content on an elevated surface consistently.\n4. As a consumer, I want an `Input` with a visible token focus ring and disabled 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 is consistent with single-line.\n6. As a consumer, I want a `Label` that associates with a field via `htmlFor`, 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 status/labels on-system.\n8. As a consumer, I want a `Stack` layout primitive with a direction and a gap drawn from the spacing scale, so that I lay out children without hand-writing flex + gap classes.\n9. As a consumer, I want a `Box` primitive, so that I have a styled generic 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 on-system hairline.\n11. As a consumer, I want a `Select` that looks on-system but keeps native ``; sizes matching `Input`.\n- **Dependency:** consumes the scale tokens from the\n [scales PRD](../structural-scales-palette/PRD.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()` + Provider.\n No headless primitives exposed.\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 the\n 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 string**\n (`renderToStaticMarkup`) and assert on the markup. Uniform across the 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/PRD.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- **`Dialog`** and any Radix-backed component — [separate PRD](../dialog-radix/PRD.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 — [separate PRD](../gallery/PRD.md).\n- Defining the scales themselves — [scales PRD](../structural-scales-palette/PRD.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",[],[218,426,427,418],"issues","v1-component-set","d85a6580-b615-42a1-b715-f4de6d7e3e91","452a7b3c-798a-11f1-97fb-1607ee4eb77e",82,["D",1783377020147],[259],[218,426,427],"b61562b2-a446-4e10-b068-ccce576bc998","45dcb4a0-798a-11f1-9f6a-1607ee4eb77e","458c169e-798a-11f1-80ac-1607ee4eb77e",100,["D",1783378956793],"# PRD: Structural scales & real palette\n\nStatus: ready-for-agent\nLabels: 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.\n> This PRD turns the provisional token stylesheet into a real, fixed structural\n> foundation. It is the prerequisite for the [v1 component set](../v1-component-set/PRD.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 a\nsingle `--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. Every\ncomponent built this way re-decides spacing and type independently, which is\nexactly 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) — plus\na real, AA-verified color palette bound to the existing semantic tokens. Because\nthe structural scales are fixed and consumed by every component, spacing and type\nbecome 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, CONTEXT.md).\n\nThe default palette carries AA contrast as a quiet guarantee (ADR-0003), verified\nmechanically rather than by eye.\n\n## User Stories\n\n1. As a consumer, I want a fixed spacing scale exposed as tokens, so that padding and gaps are consistent across every component and every app without me choosing pixel values.\n2. As a consumer, I want a fixed type scale (size + line-height), so that text 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 express brand while keeping the rest of the system fixed.\n4. As a consumer, I want a graduated radius scale derived from the overridable `--kyla-radius`, so that rounding stays proportional when I change the base radius.\n5. As a consumer, I want the default palette to meet WCAG AA contrast in both 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 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 stay fixed, so that I cannot accidentally break visual consistency by overriding them.\n8. As a component author, I want a sanctioned, typed way to reference scale tokens, so that I compose spacing and type from the scale instead of raw Twind numbers.\n9. As a component author, I want the scale accessors to sit alongside the existing `tw` color helpers, so that authoring one component uses one consistent vocabulary.\n10. As a component author, I want the type scale to bundle line-height with 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 that a future palette edit that breaks contrast fails CI rather than shipping.\n12. As a maintainer, I want the scale definitions to live in one place (`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 resolved with `light-dark()` where mode-dependent, so that mode still flips with zero JS.\n14. As an end user, I want legible text and comfortable spacing in whatever mode 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 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 to\n  the Val Town UI style guide** — they are *ported*, not invented here. Concrete\n  values come from the VT style-guide research/reference doc under `docs/` (see\n  [ADR-0005](../../adr/0005-val-town-visual-language-default-theme.md)). This PRD's\n  job is to bind those values to the `--kyla-*` tokens and the scale accessors,\n  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 AA-passing\n  both modes). Values are Tailwind v4 steps, applied via `light-dark(light, dark)`:\n   - `base` = white / **`slate-950` `#020618`** (a deliberate softening of VT's true-black\n     `#000` — see ADR-0005); `elevated` = white+shadow / `slate-900`; `recessed` =\n     `slate-100` / `slate-800`.\n   - `fg` = black / white; `fg-muted` = `gray-600` / `gray-300` (VT's literal `--color-muted`;\n     **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 (never white on\n     `sky-400` — fails at 2.18:1); `accent-ring` = `sky-500`; `accent-text` = `sky-800` /\n     `sky-200`.\n   - `danger` = `rose-300` / `rose-800`; `danger-fg` = `rose-950` / white. `success` =\n     `emerald-400` / `emerald-700`; `success-fg` = `emerald-950` / white.\n   - `radius` (base) = **8px** (`rounded-lg`); spacing base = 4px; font = `\"IBM Plex Sans\",\n     -apple-system, sans-serif` (needs shell/Provider font loading — flag for delivery).\n- **New tokens (ADR-0005):** this PRD adds `accent-ring`, `accent-text`, `danger-fg`,\n  `success`, `success-fg` to the `ColorToken` union and the token stylesheet, alongside the\n  existing set. All are structural (not part of the 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 for\n  both modes, keeping the `light-dark()` structure. Every *sanctioned* foreground/\n  surface pairing (`fg` on `base`/`elevated`/`recessed`, `accent-fg` on `accent`,\n  `danger-fg` on `danger`, `success-fg` on `success`, `fg-muted` on surfaces used\n  for secondary text) must meet WCAG AA: 4.5:1 for body text, 3:1 for large text\n  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 because\n  the guarantee (\"AA holds\") is a property of the values, computable without a\n  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 [v1 component set PRD](../v1-component-set/PRD.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, ratios,\n  and hex values). Those choices should be made here and encoded as the token\n  values; downstream PRDs consume them by name and must not re-decide them.\n- Because scale token *names* become load-bearing across the component set, treat\n  a rename as a breaking change under ADR-0004 once components depend on them.\n",[],[218,426,442,418],"structural-scales-palette","2c4f93b5-35b4-46eb-9524-1075f5cb6327",84,["D",1783377020429],[257],[218,426,442],"423e3792-fbbb-4398-8f4c-7b4ee4b23ea0","45edca42-798a-11f1-afe8-1607ee4eb77e","457d5078-798a-11f1-80ac-1607ee4eb77e",92,["D",1783377020896],"# PRD: Starter — remixable todo app\n\nStatus: ready-for-agent\nLabels: ready-for-agent\n\n> Ships the **Starter** defined in [CONTEXT.md](../../../CONTEXT.md): a separate,\n> remixable demo val showing idiomatic end-to-end use of Kylä UI. It depends on\n> the [component set](../v1-component-set/PRD.md) (and ideally\n> [Dialog](../dialog-radix/PRD.md)); the Starter depends on the library, never the\n> 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 route,\npersistence, the Provider + client hydration, an app shell, and a Mode toggle —\ni.e. no honest demonstration that Kylä works as a whole for building an actual app.\n\n## Solution\n\nShip **`kyla-ui-starter`**: a small but genuine **todo app** that imports Kylä UI\nand is built entirely from its components. It has a real HTTP route, `std/sqlite`\npersistence, `KylaProvider` + client hydration, an app shell, a Mode toggle, and a\nview-source link. Remixing it and editing is the intended way to start a new Kylä\napp. Building it also dogfoods the library and surfaces gaps in 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 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 / delete, persisted), so that it demonstrates real behavior, not a static mock.\n3. As a new developer, I want the Starter to persist todos with `std/sqlite`, so 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 see how a Kylä app is served on Val Town.\n5. As a new developer, I want the Starter wrapped in `KylaProvider` with client hydration, so that I see the correct Provider + CSR wiring (Twind before first paint, tokens injected, Mode owned).\n6. As a new developer, I want the whole UI built from Kylä components, so that I 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 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 running app to its code.\n9. As a new developer, I want the Starter pinned to a known-good Kylä Release, so that a fresh remix renders correctly and isn't broken by an in-flight library change.\n10. As a maintainer, I want the Starter to depend on the library (never the reverse), so that the dependency direction stays clean.\n11. As a maintainer, I want the Starter built from real components, so that it 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 that the app is actually usable.\n13. As an end user, I want my todos to persist across reloads, so that the demo 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, toggle\n  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()`. Using\n  `Dialog` (e.g. a confirm-delete) is encouraged once it ships, to demonstrate the\n  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 and\n  assert the todo lifecycle: adding a todo returns/lists it, toggling flips its\n  completed state, deleting removes it, and the list reflects persisted state on a\n  fresh request. Optionally assert the served shell is a `200` HTML page that\n  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 via\n  the platform's skill finder); the `preview/index.tsx` handler is the reference\n  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/PRD.md)), not the Starter.\n\n## Further Notes\n\n- The Starter is the honest integration test of the whole v1: if composing it into\n  a real app is awkward, that's a signal to fix the component set, not to work\n  around it in the Starter.\n- Keep it \"tiny but genuine\" — enough to be a real app, small enough to read in one\n  sitting, since developers will copy it as their baseline.\n",[],[218,426,456,418],"starter","70836efb-efb6-44dd-98b2-39a9303b508b",83,["D",1783377020339],[255],[218,426,456],"20643885-194e-499d-afcb-56081079d9aa","45e698c6-798a-11f1-95f7-1607ee4eb77e","454cee9c-798a-11f1-97fb-1607ee4eb77e",91,["D",1783377020808],"# PRD: Gallery — self-hosted docs surface\n\nStatus: ready-for-agent\nLabels: 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 the\n> Mode toggle. Grows as the [component set](../v1-component-set/PRD.md) and\n> [Dialog](../dialog-radix/PRD.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 tokens,\nProvider mode, Radix hydration) renders correctly on Val Town. Today that surface\nonly exists as `preview/`, which is explicitly labelled work-in-progress and \"not\na stable API,\" carries a 🚧 banner, and is framed as illustrative rather than\ncanonical. There is no blessed docs surface a consumer can point to.\n\n## Solution\n\nPromote `preview/` into the real **Gallery** served at `kyla-ui`'s HTTP route: it\nrenders every shipped component across its variants/sizes/tones, shows the design\ntoken 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 that I can see every component before importing it.\n2. As a consumer, I want each component shown in all its variants/sizes/tones, 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 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 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 uses the components.\n6. As a maintainer, I want the Gallery served from `kyla-ui` itself (co-located with source), so that the library documents itself and the docs can never drift from the code they import.\n7. As a maintainer, I want the Gallery to import the real library and never 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 + tokens + Provider + Radix render correctly on Val Town, so that a broken render path is visible immediately.\n9. As a maintainer, I want adding a new component to the Gallery to be a small, 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 (focus rings, Dialog open/close), so that it doubles as a manual behavior check.\n11. As an end user of the docs, I want the Gallery to load without a build step, 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 browser,\n  `std/catch` for client-error surfacing, `serveFile` for transpiled `.ts/.tsx`,\n  and the `/source` redirect. The Gallery **imports** the library from `mod.ts`\n  (and Dialog's own path) and modifies nothing — the preview's core invariant.\n- **Shell conventions (folded-in cleanup — see issue\n  [`01-preview-shell-conventions`](issues/01-preview-shell-conventions.md)):** the\n  Gallery adopts the *corrected* shell, not today's template-literal one — a real\n  `index.html` static file served via `serveFile`, and no inline `<style>` block\n  (Twind utility classes only, per project convention). This cleanup is small and\n  can land early against `preview/` before the full Gallery is built; the Gallery\n  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 the\n  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 (the\n  sketch's alternative) is deferred until the component set stabilizes; hand-\n  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 the\n  blessed Gallery; the corrected shell (above) is kept.\n- **Dialog:** once [Dialog](../dialog-radix/PRD.md) ships, the Gallery is where its\n  open/close/focus-trap behavior is manually verifiable in-browser (the behavior\n  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 proof —\n  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 palette\n  and Dialog interactions are the higher-fidelity checks; run them in a real\n  browser against the live Gallery. Not required for the PRD's automated 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/PRD.md).\n- Building the components themselves — [component set PRD](../v1-component-set/PRD.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 an\n  unstyled element. Keep it exercising real components in real Modes.\n",[],[218,426,470,418],"gallery","2b988b37-5c4f-4ff7-aed7-4efa4cca8c77","01-preview-shell-conventions.md","45d4ff80-798a-11f1-950b-1607ee4eb77e","45a5c9e0-798a-11f1-80ac-1607ee4eb77e",89,["D",1783377020859],"# 01 · Bring the preview shell in line with platform conventions\n\nStatus: ready-for-agent\nLabels: ready-for-agent\n\nImplementation issue under the [Gallery PRD](../PRD.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` ships a\n   real `frontend/index.html` static file served via `serveFile()`, satisfying the\n   same \"Twind must load before first paint\" requirement (ADR-0001) with a\n   `<script>` tag in that static file. Template-literal HTML gets no syntax\n   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 preview…\"\n   placeholder). Project convention is Twind/Tailwind utility classes only — no\n   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 errors\n  (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",[],[218,426,470,426,472],"92a7eda9-25fb-4409-9008-b01d2d410386",85,["D",1783377020590],[252],[218,426,470,426],"217cca91-a478-4fc0-b891-d1f7c65035ee",81,["D",1783377020017],[251,253],[218,426,470],"37cb5ba6-3feb-4612-9d7e-cbefa96b482d","45ccb3ca-798a-11f1-8ef5-1607ee4eb77e","453bae52-798a-11f1-97fb-1607ee4eb77e",88,["D",1783377020818],"# PRD: Dialog (Radix-backed)\n\nStatus: ready-for-agent\nLabels: 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/PRD.md) for surrounding styled pieces\n> and on the [scales & palette](../structural-scales-palette/PRD.md) for 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 import\npath, kept out of the barrel so it only loads when used, with the React-18.2.0\n`?deps=` pin propagated through Radix's transitive graph — are unexercised in the\nreal codebase.\n\n## Solution\n\nBring **`Dialog`** into the library as the first Radix-backed component. It lives\nbehind its own import path (a root re-export, e.g. `dialog.tsx`) kept **out** of\nthe `mod.ts` barrel, so consumers who never use it never load Radix. It is styled\nentirely from the token system like every other component; its behavior and\naccessibility (focus trap, ESC, `aria-*`, portal) are delegated to Radix. The\npublic surface stays styling-only — Radix primitives remain internal so a later\nRadix→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 match the rest of my Kylä app.\n2. As a consumer, I want to import `Dialog` from its own path, so that apps that 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 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, 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 inside the modal, including through the portal, so that light/dark mode is correct everywhere.\n6. As a consumer, I want to override the content's `className`, so that I can size or position a specific dialog without forking.\n7. As a consumer pinning a version, I want `Dialog` to work under the pinned React 18.2.0, so that Radix's transitive deps don't hit the `useState` null mismatch.\n8. As a component author, I want Radix primitives kept internal to the Dialog 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 the zero-dep core stays zero-dep.\n10.   As a maintainer, I want the React-version pin applied at Radix's import, so 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 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 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 Radix's\n  own guarantees. Testing that Radix traps focus is testing Radix, not 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 — token\n     utility classes present on overlay/content, `className` override wins, title/\n     description associated, close affordance present. This catches the silent\n     Twind hint failure the same way as the rest of the set.\n   - **Behavior backstop (browser):** open/close, focus-trap, ESC, and\n     in-portal token resolution are interaction guarantees best confirmed in a\n     real browser — via the [Gallery](../gallery/PRD.md) once Dialog is listed\n     there. Treat this as the higher-fidelity seam for _behavior_, not a unit\n     test of Radix 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/PRD.md); the spike val is the reference\n  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 Radix\n  configuration proves brittle in the library, capture it as an ADR update rather\n  than a local workaround.\n- Because `Dialog` defines the _pattern_ for every future Radix-backed component,\n  keep the internal/exposed boundary crisp — it's what protects the Radix→Base UI\n  option.\n",[],[218,426,498,418],"dialog-radix","5eec4490-fa6a-4d69-a14b-b33255dd6e81",80,["D",1783377019910],[249],[218,426,498],"a2c9ad46-23a8-460e-94fa-f026945b61c3",79,["D",1783377019794],[248,250,254,256,258],[218,426],"77ad0601-a1d3-41a5-b58e-81ba37ac5b0a","2026-06-18-design-and-foundation.md","cde8b7ca-6b54-11f1-b7ac-1607ee4eb77e","cdcfbd74-6b54-11f1-bde2-1607ee4eb77e",60,["D",1781814740095],"# Handoff — Kylä UI design + foundation (2026-06-18)\n\nPicking up the `nbbaier/kyla-ui` component library for Val Town. This thread did the\ndesign grilling, proved the runtime substrate, and built the styling foundation + the\nfirst component (`Button`). This doc is a pointer map + \"what's next\", not a re-spec —\nthe 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, **Implementation\n  status** section, open spikes (all ✅), and the \"Deliberately 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 dir via\n  `vt`). `nbbaier/kyla-ui-spike` (throwaway substrate proof — all 4 spikes green\n  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`), `src/components/`\n  (`button`). Layout rationale is in the sketch's 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 — `bg-[color:var(--…)]`,\n   never `bg-[var(--…)]` (the latter silently renders nothing; no error). Always go\n   through the `tw.*` builders in `src/theme/tw.ts`, which bake it in. (ADR-0001.)\n2. **Twind lives in the HTML shell**, not the Provider (must load before first paint).\n   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. (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 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 eyeball\n   all variant/size combos + hover/focus in a browser. (Quick loop-closer.)\n2. **Real palette + structural scales** — replace provisional tokens with AA-checked\n   surface/fg/border ramps + spacing/radius/type scales. Highest-leverage deferred item.\n3. **More components** — `Card`, `Text`/`Heading`, `Input`, `Textarea`, `Label`, `Badge`,\n   `Stack`, `Box`, `Divider`, then native-styled `Select`. Reuse the Button pattern.\n4. **`Dialog` (Radix)** — first component behind its own import path: `src/components/dialog.tsx`\n   + a root `dialog.ts` re-export, kept OUT of `mod.ts` (ADR-0002). Exercises the split.\n5. **Gallery** — the library's self-hosted docs HTTP route (CONTEXT.md → \"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` 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 `delete_file`\n  it. Used twice this thread; clean and fast.\n- For anything UI/platform-specific on Val Town, pull the official skill via the valtown\n  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, view-source) for\n  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 Starter\n  todo app and/or the Gallery route.\n- **rams** (or **impeccable**) — accessibility / visual-design review once there are\n  enough components and the real palette to evaluate.\n",[],[218,518,510],"handoffs","a7030e21-e7a7-4098-b3a8-8ab22885d8dc",59,["D",1781814739944],[246],[218,518],"5558b951-2837-4501-8b52-afc9e8a76d20","triage-labels.md","a548ab54-775c-11f1-8e89-1607ee4eb77e","a519c118-775c-11f1-8e89-1607ee4eb77e",74,["D",1783373248995],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those roles 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 corresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n",[],[218,533,525],"agents","a1933360-a4f8-45d2-a1b1-d6860fdcc1bd","issue-tracker.md","a560b8ac-775c-11f1-88a1-1607ee4eb77e",75,["D",1783373249023],"# Issue tracker: Local Markdown\n\nIssues and PRDs for this repo live as markdown files in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues/<feature-slug>/`\n- The PRD is `docs/issues/<feature-slug>/PRD.md`\n- Implementation issues are `docs/issues/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)\n- Comments and conversation history append to the bottom of the file under a `## 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 needed).\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 the issue number directly.\n",[],[218,533,535],"0c04518c-d15d-4f19-bddc-51398c1928d3","domain.md","a52e4908-775c-11f1-a7d7-1607ee4eb77e",64,["D",1783137521705],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when exploring 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 `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 multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them 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, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than silently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[218,533,543],"e1da9f80-ef2b-4841-92f9-45fc459f2a2d",63,["D",1783137521569],[242,243,244],[218,533],"9562286b-c88f-4fe3-a983-0432193f6c3f","0005-val-town-visual-language-default-theme.md","c7b195b4-798e-11f1-aabb-1607ee4eb77e","bc9c5da4-6b46-11f1-aeb1-1607ee4eb77e",99,["D",1783378956766],"# Default theme adopts the Val Town visual language\n\nKylä UI ships **one opinionated default theme** (CONTEXT.md → Theme; ADR-0001). Until now its palette and scales were provisional placeholders, implicitly derived from our Cloudflare Kumo lineage. We decide that the default theme's **values** — color palette (light + dark), the spacing / radius / type scales, and the component-level styling those map to — **conform to the Val Town UI style guide** (`val.town/_ui`), so that an app built with Kylä looks native to Val 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 what the `--kyla-*` tokens resolve to; it does not change how the system is built or how consumers call it:\n\n- **Architecture stays Kumo-modeled.** Semantic tokens as CSS custom properties (ADR-0001), the hybrid headless foundation (ADR-0002), primitives + components — all unchanged. The token indirection is precisely what lets us retarget the look without touching components.\n- **API vocabulary stays Kylä's own.** Kylä keeps its Kumo-style variant model — `Button` `variant` = `primary | subtle | ghost | danger`, `size` = `sm | md | lg`, etc. — which deliberately differs from `val.town/_ui`'s own class vocabulary. Adopting VT's *values* does not rename Kylä's *props*. (This is consistent with the note in the Gallery's preview-shell issue: the divergence recorded there was about **names**, not **palette**.)\n- **Positioning (ADR-0003) is reinforced, not changed.** \"Lead with consistency\" now means consistency *with the surrounding Val Town platform*, not just 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 `docs/reference/val-town-style-guide.md`, so downstream PRDs consume concrete numbers rather than \"conform to VT\" prose. Primary sources (Val Town's site is Remix, server-rendered, so the component markup and its compiled token CSS are fetchable over plain HTTPS):\n\n- `https://www.val.town/_ui/*` — the live style-guide pages (button, callout, card, dropdown, input, select, textarea, forms, privacy-badge); SSR markup gives each component's verbatim utility classes.\n- `https://static2.esm.town/assets/tailwind-*.css` — the compiled Tailwind v4 stylesheet the pages link: the `@theme` token scale (`--color-*` oklch ramp, `--spacing`, `--radius-*`, `--text-*`, fonts, weights) and VT's semantic aliases split across `:root`/`.dark`.\n- `https://www.val.town/x/dcm31/townie-mobile/code/frontend/style.css` — a hand-distilled token artifact billed by its author as Val Town's style guide (\"gave Fable our style guide\"); used as a corroborating cross-check (it is 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, and it forfeits the chance to make Kylä apps look like they belong on their host platform. A bespoke look is a liability, not a feature, for this audience.\n- **Adopt VT's values *and* its class vocabulary** — rejected/deferred: API-breaking, and Kylä's typed variant model is more expressive than raw utility classes. Revisit only if there's a concrete reason to mirror VT's prop names; it is explicitly **not** part of this decision.\n- **Adopt VT's values as the default theme; keep Kylä's architecture and API** — **chosen.**\n\n## Consequences\n\n- The `structural-scales-palette` PRD is reframed: instead of *designing* a palette + scales, it **ports** the Val Town style guide's palette and scales into the token stylesheet, sourced from the reference doc above. This is why the decision must be recorded before that PRD is implemented.\n- The `v1-component-set` PRD uses `val.town/_ui` as the styling reference for its per-component variant→token maps (button sizing/radius, input styling, badge tones), so components read as VT-native — not just the palette.\n- **AA contrast (ADR-0003) remains the stricter constraint.** Every sanctioned foreground/surface pairing must meet WCAG AA in both modes. If VT's guide has a pairing that falls short, Kylä's AA guarantee wins and that token value is adjusted; the contrast test enforces this regardless of source.\n- **Kylä keeps its own surface hierarchy.** The extraction (`docs/reference/val-town-style-guide.md`) found VT's *semantic* layer is thinner than Kylä's — VT names only `background / text / border / muted / shadow` and elevates by shadow over a single surface. Kylä retains its structural `base` → `elevated` → `recessed` hierarchy and `hairline` (CONTEXT.md); where VT has no named token, those values are sourced from VT's slate component fills. So the default theme is **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 accent in three roles a single `accent`/`accent-fg` can't hold (fill, focus-ring, accent-text-on-surface), and ships a success tone. The canonical `--kyla-*` vocabulary therefore gains `accent-ring`, `accent-text`, `danger-fg`, and a `success`/`success-fg` tone (updating CONTEXT.md's token list and the `ColorToken` union). These are **structural** additions — the consumer override surface stays small.\n- **One deliberate deviation from VT:** the dark-mode `base` uses `slate-950` (`#020618`), a considered softening of VT's literal true-black (`#000`, 21:1) to reduce large-surface glare. Recorded here so it reads as a choice, not an extraction error; every other default tracks VT.\n- The consumer **override surface** (`--kyla-accent`, `--kyla-radius`, font) is unchanged; its *defaults* become the VT values, and a consumer can still rebrand within that small surface.\n- If Val Town revises its style guide, Kylä tracks it by re-running the extraction and retuning token values — a values change under the existing Release contract (ADR-0004), not an API change.\n",[],[218,564,556],"adr","e212033c-6c56-41c7-af04-c89fa2adbb32","0004-version-pinned-upgrade-contract.md","bcb00034-6b46-11f1-9b3f-1607ee4eb77e",16,["D",1781808698266],"# Upgrade contract: main-as-release-line, version pinning\n\nKylä UI is consumed by importing its val from esm.town, where an unpinned import (`.../kyla-ui/mod.ts`) auto-redirects to the val's latest version and a consumer can freeze onto a specific version with `?v=NNN`. esm.town does **not** offer branch-name import URLs, so the intuitive \"consumers track a long-lived `stable` branch\" model is not available.\n\nWe therefore make **`main` the stable/release line**: all development happens on feature/dev branches, and a **Release is a merge into `main`.** Because raw work never lands on `main`, HEAD-of-`main` is always a Release. Consumers then have two contracts:\n\n- **Track latest** — import the unpinned URL; always get the newest Release, so fixes auto-propagate (the upside of consumption-by-import).\n- **Freeze** — pin `?v=NNN` from the README's release table; upgrade deliberately by changing the number.\n\n## Considered Options\n\n- **Long-lived `stable` branch consumers import** — rejected: esm.town has no documented branch-import URL, so it isn't realizable.\n- **Live HEAD with raw development on the imported line** — rejected: any work-in-progress push would reach unpinned consumers; keeping development off `main` is what makes the unpinned URL safe.\n\n## Consequences\n\n- Unpinned consumers receive a new Release the instant a branch merges — *including a breaking one*. The release table plus brief per-release notes are how a consumer decides whether to pin. There is no staging window between merge and propagation.\n- Every merge to `main` mints a new `?v=NNN`; the README maps human release names to those version numbers.\n- For v1 (sole consumer is the maintainer) this can be operated loosely, but the convention costs nothing now and makes external consumption safe later.\n",[],[218,564,566],"ea4fd87e-bcb2-4e20-861a-aba8afe03304","0003-consistency-first-bounded-accessibility.md","bcc6125c-6b46-11f1-9996-1607ee4eb77e",19,["D",1781808698311],"# Consistency-first positioning, bounded accessibility\n\nKylä UI is modeled on Cloudflare Kumo, whose headline value is accessibility. We deliberately invert the emphasis: **Kylä leads with visual consistency** — the felt pain for the Val Town audience (people shipping apps fast without a designer) is that hand-assembled UIs look inconsistent, not that they fail an audit. Accessibility remains a real but *quiet* guarantee underneath, with a deliberately bounded scope for v1.\n\nThe accessibility commitment is exactly: **correct semantic HTML** (native `<button>`, real `<label htmlFor>`/`<input id>` association, `<h1–h6>` headings), **token-based visible focus**, **not breaking native keyboard behavior**, and **WCAG-AA contrast on the default theme** (a property of the Theme, set once). Anything requiring custom ARIA roles/state is *not* hand-rolled — it is built on a Headless Primitive (Radix), which is the dividing line of ADR-0002.\n\n## Why record this\n\nA contributor seeing the Kumo lineage will reasonably assume accessibility is the headline and try to chase full WCAG-AA across the hand-rolled zero-dep components. That is a deliberate non-goal for v1, not an oversight: the bounded promise is one we can actually keep, and \"needs more than semantic HTML\" is precisely the signal a component belongs in the Radix tier. Full WCAG auditing is additive and can be revisited later; it should not silently expand v1 scope.\n",[],[218,564,574],"8d26c6c2-8f00-4fbc-b9e7-b54df1c77b6b","0002-hybrid-headless-foundation.md","bcb42b28-6b46-11f1-8453-1607ee4eb77e",17,["D",1781808698290],"# Hybrid headless foundation, Radix-first\n\nKumo builds every component on Base UI headless primitives for accessibility. On Val Town a headless library is an unvetted heavy ESM dependency loaded from a CDN at runtime, so we take it selectively: **simple visual components (Button, Card, Stack, Text, Input, Badge) are hand-rolled with zero dependencies**, and **only the genuinely hard interactive components (Dialog, Popover, Menu, Tabs) build on a third-party headless library.** This keeps the common case dependency-free and fast on Val Town while still inheriting accessibility where it is expensive to get right.\n\nThe library is **Radix first** — chosen over the maintainer's preferred Base UI purely because Radix has a longer track record loading from CDNs — used to prove the pattern works on Val Town. A Base-UI-backed variant is a likely later step once viability is demonstrated.\n\n## Consequences\n\n- Open validation task before committing: confirm a Radix primitive (e.g. Dialog) imports via esm.sh with React pinned to 18.2.0 and hydrates cleanly on Val Town's CSR setup.\n- Swapping the headless library later is contained per-component, not a global rewrite — which is what makes \"Radix now, Base UI later\" affordable.\n",[],[218,564,582],"d6f37f45-94c5-4872-aab2-12b78ab40b37","0001-no-build-styling-architecture.md","bcbd4aa0-6b46-11f1-9db1-1607ee4eb77e",27,["D",1781813485081],"# No-build styling architecture\n\nKylä UI targets Val Town, which has no build step or bundler. Cloudflare Kumo — our model — achieves visual consistency with Tailwind v4 semantic tokens compiled at build time, which we cannot use. We therefore deliver consistency at runtime: **semantic design values are defined as CSS custom properties** (a token stylesheet served by the `kyla-ui` val, using `light-dark()` for automatic dark mode), and **components apply them via runtime Twind arbitrary-value utilities** (e.g. `bg-[var(--kyla-base)]`). Styles are delivered with a deliberate split (confirmed by the `kyla-ui-spike`): the **Twind script lives in the HTML shell** (it must load before first paint or utilities FOUC, so it cannot be React-injected), while the **token stylesheet is injected by the Provider at runtime** (idempotently). The Starter ships the shell tag; the Provider guarantees the tokens — so \"styles are present\" is a guarantee, not a setup checklist (a manual two-tag `<head>` setup is the documented escape hatch).\n\n## Considered Options\n\n- **Tailwind v4 + build step (the Kumo way)** — rejected: requires a bundler/PostCSS, which Val Town does not provide.\n- **Twind with a named-token theme config** (`bg-kyla-base`) — rejected: every consumer app would have to load an identical Twind runtime config or components render wrong; that coupling is a sharp, silent failure mode.\n- **Pure CSS component classes** (`.kyla-button`) — rejected: self-contained but abandons Tailwind/Twind ergonomics and composable variants, and strays from the Val Town idiom.\n\n## Consequences\n\n- Arbitrary-value Twind syntax is noisier, but it lives inside library source; consumers only write `<Button>`.\n- Components only render correctly where Twind is running and the token stylesheet is loaded — hence the Provider (see ADR-0002's sibling delivery decision) is load-bearing.\n- The `light-dark()` CSS function handles dark mode without `dark:` variants, keeping component source theme-agnostic.\n- **Authoring rule (proven by the spike):** semantic-color utilities must carry the `color:` type hint — `bg-[color:var(--kyla-base)]`, `text-[color:var(--kyla-fg)]`, `border-[color:var(--kyla-line)]`. A bare `bg-[var(--…)]` is type-ambiguous and Twind silently emits nothing (the failure is invisible — no error, just an unstyled element). Lengths are unambiguous, so `rounded-[var(--kyla-radius)]` needs no hint. Because the omission fails silently, component authors must not hand-write these strings; the `cn()`/variant layer should emit token utilities through a tiny helper so the hint can never be forgotten.\n",[],[218,564,590],"5952a1d0-5e01-4609-a8ae-f86b41871f4b",15,["D",1781808698135],[236,237,238,239,240],[218,564],["D",1781808698019],[235,241,245,247,260,261],[218],["D",1781804868537],["D",1789701064442],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"ctx",{"_80":-5,"_126":643,"_644":645,"_646":647,"_648":25,"_649":25,"_650":25,"_651":124,"_652":-5,"_653":-7,"_654":-7,"_655":61,"_656":25,"_657":25,"_658":-5,"_659":25,"_660":25,"_661":25,"_662":-5},"ENV",{"_614":615,"_616":617,"_618":88,"_619":620,"_621":622,"_623":624,"_625":626,"_627":628,"_629":630,"_631":632,"_633":634,"_635":636,"_637":638,"_639":640,"_641":642},"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>

Diff · v101