[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_351":352,"_353":354},"routes/_app.x.$handle.$name",{"_99":98,"_33":46,"_107":89,"_28":108,"_13":14,"_109":-5,"_11":110,"_111":112,"_113":114,"_115":116,"_117":118,"_20":-5,"_119":-5,"_120":-5,"_121":27,"_122":123,"_124":27,"_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",{"_44":45,"_33":46,"_39":47,"_48":-5,"_49":27,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":-5,"_58":27,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68,"_69":70,"_71":-5,"_72":73,"_74":73,"_75":76,"_77":76,"_78":76,"_79":73,"_80":73,"_81":82,"_83":84,"_85":86,"_87":27},"version",37,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":27,"_28":29,"_30":29},"file",{"_31":32,"_33":34,"_35":20,"_36":38,"_39":40,"_41":14,"_42":43,"_24":27},"previous",{"_31":32,"_33":34,"_35":20,"_36":37},"deleted",true,"deletedHere",false,"path","docs/v1-design-sketch.md","latestPath","fileId","c4ebc472-6b50-11f1-92e8-1607ee4eb77e","name","v1-design-sketch.md","fileType","content","# Kylä UI — v1 Design Sketch\n\nA high-level sketch of the v1 design, produced from a design interview. This is the\nhub: vocabulary lives in [`../CONTEXT.md`](../CONTEXT.md), and each consequential\ndecision has an ADR in [`adr/`](./adr/). This doc summarizes the shape and records\nwhat is **deliberately deferred**.\n\n> Modeled on [Cloudflare Kumo](https://github.com/cloudflare/kumo) — semantic tokens,\n> headless foundation, primitives + components — ported onto Val Town's **no-build**\n> reality. Where Kumo uses Tailwind v4 + codegen, Kylä uses runtime CSS variables + Twind.\n\n## Positioning\n\n**Lead with consistency, not accessibility.** The felt pain for the Val Town\naudience (shipping apps fast, no designer) is inconsistent, hand-assembled UI.\nAccessibility is a real but *quiet, bounded* guarantee underneath. See\n[ADR-0003](./adr/0003-consistency-first-bounded-accessibility.md).\n\n## Shape\n\n- **Two vals.** `kyla-ui` — the importable library, which also serves its own\n **Gallery** (docs) at its HTTP route. `kyla-ui-starter` — a remixable, genuine\n **todo app** (real HTTP route + `std/sqlite`) showing idiomatic end-to-end use.\n The Starter depends on the library; never the reverse.\n- **CSR-only for v1.** Target is interactive apps (dashboards, tools, forms) where\n SEO/first-paint don't matter. Components authored pure so isomorphic stays\n possible later, without paying its tax now.\n\n## Styling — [ADR-0001](./adr/0001-no-build-styling-architecture.md)\n\n- Semantic tokens as `--kyla-*` **CSS custom properties** using `light-dark()`;\n applied via runtime **Twind arbitrary-value** utilities (`bg-[var(--kyla-base)]`).\n No build, no bundler.\n- Token vocabulary: surfaces `base → elevated → recessed`; foreground `fg`,\n `fg-muted`; borders `line`, `hairline`; `accent`, `danger`; `radius`.\n- One opinionated theme. Small consumer **override surface** (`--kyla-accent`,\n `--kyla-radius`, font); structural tokens stay fixed — that fixedness *is* the\n consistency. A Kumo-style named-theme system is a deliberate later step.\n\n## Style delivery & theming\n\n- **`KylaProvider`** guarantees Twind + token stylesheet are present (a manual\n two-tag `` setup is the documented fallback).\n- The Provider **owns Mode**: sets `data-mode=\"light|dark|system\"`, exposes\n `useKylaMode()` (persistence opt-in); `system` falls through to OS via\n `light-dark()`. Apps get a first-class light/dark toggle for free.\n\n## Components — [ADR-0002](./adr/0002-hybrid-headless-foundation.md)\n\n- **Hybrid foundation.** Hand-roll simple visual components with zero deps; build\n on a headless library only for hard interactive ones. **Radix first** (proven\n on VT), Base UI as a likely faithful-to-Kumo later variant.\n- **v1 inventory:**\n - Zero-dep visual: `Button`, `Text`/`Heading`, `Card`, `Input`, `Textarea`,\n `Label`, `Badge`, `Stack`, `Box`, `Divider`\n - Styled native: `Select`\n - Radix-backed (the headless proof): `Dialog`\n - Deferred to v1.1+: `Checkbox`, `Radio`, `Spinner`, `Alert`, then\n `Popover`, `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`, …\n- **API:** typed **variant** props (`variant`, `size`, `tone`) mapping to tokens\n internally; escape-hatch `className` merged last via exported `cn()`; refs +\n rest props forwarded. Public surface = finished components + `cn()` + Provider.\n Radix primitives stay **internal** (so Radix→Base UI later isn't an API break).\n- **Accessibility (bounded):** correct semantic HTML, real ``/`id`\n association, token-based visible focus, no broken native keyboard behavior,\n AA contrast on the default theme. Anything needing custom ARIA → Radix tier.\n\n## Distribution — [ADR-0004](./adr/0004-version-pinned-upgrade-contract.md)\n\n- **Module layout:** barrel `mod.ts` for the zero-dep core; heavy `dialog.tsx`\n behind its own import path so Radix only loads when used.\n- **Upgrade contract:** `main` is the release line; development happens on\n branches; a **Release** is a merge to `main`. Unpinned import = latest Release\n (fixes auto-propagate); `?v=NNN` to freeze; README release table maps names →\n versions. (esm.town has no branch-import URLs, hence version pinning.)\n\n## Open verification spikes\n\nBuilt and **fully verified in-browser** as one throwaway val: **`nbbaier/kyla-ui-spike`**\n(`frontend/{App,KylaProvider,tokens}.tsx`). All four green:\n\n1. ✅ **Radix `Dialog`** — imports via esm.sh with React 18.2.0 (the\n `?deps=react@18.2.0,react-dom@18.2.0` pin propagates through Radix's whole\n transitive graph, defusing the React-mismatch `useState` null error) and\n renders/opens/closes/focus-traps cleanly under CSR.\n2. ✅ **Twind + CSS-var tokens** — surfaces render stepped, accent applies.\n3. ✅ **`KylaProvider` runtime token injection** — styles exist only because the\n Provider injected the stylesheet. (Twind stays in the *shell* since it must\n load before first paint; only the token stylesheet is Provider-injected.)\n4. ✅ **`light-dark()` + `data-mode`** — mode toggle flips the palette; resolves\n even inside the Radix portal.\n\n### Load-bearing finding (the spike's main payoff)\n\nOn Val Town's runtime **Twind, semantic-color utilities must carry the `color:`\ntype hint** — `bg-[color:var(--kyla-base)]`, `text-[color:var(--kyla-fg)]`,\n`border-[color:var(--kyla-line)]`. A bare `bg-[var(--…)]` is type-ambiguous and\nTwind **silently emits nothing** — no error, just an unstyled element. Lengths\nare fine bare (`rounded-[var(--kyla-radius)]`). Because the failure is invisible,\nthe `cn()`/variant layer must emit token utilities through a helper so authors\ncan't forget the hint. (Baked into ADR-0001.)\n\n## Deliberately deferred (not yet designed)\n\nThese were identified but intentionally not resolved in this sketch. The\n**spacing / radius / type scale** is the highest-leverage — it's where visual\nconsistency actually lives.\n\n- **Structural scales** — the spacing, radius, and typographic scales (the\n fixed tokens carrying most of the consistency). Currently undefined.\n- **Variant→token maps** — concrete `variant`/`size`/`tone` value sets per\n component (e.g. what tones `Button`/`Badge` expose).\n- **`KylaProvider` API** — its precise prop surface beyond \"owns styles + Mode\".\n- **Gallery generation** — hand-written vs generated from component metadata.\n- **Theming v2** — a Kumo-style named-theme system (multiple consumer-defined\n themes) once there's demand.\n- **Base UI variant** — a Base-UI-backed build once Radix proves the path.\n- **Isomorphic rendering** — SSR + hydration for content/landing pages, if needed.\n","# Kylä UI — v1 Design Sketch\n\nA high-level sketch of the v1 design, produced from a design interview. This is the\nhub: vocabulary lives in [`../CONTEXT.md`](../CONTEXT.md), and each consequential\ndecision has an ADR in [`adr/`](./adr/). This doc summarizes the shape and records\nwhat is **deliberately deferred**.\n\n> Modeled on [Cloudflare Kumo](https://github.com/cloudflare/kumo) — semantic tokens,\n> headless foundation, primitives + components — ported onto Val Town's **no-build**\n> reality. Where Kumo uses Tailwind v4 + codegen, Kylä uses runtime CSS variables + Twind.\n\n## Positioning\n\n**Lead with consistency, not accessibility.** The felt pain for the Val Town\naudience (shipping apps fast, no designer) is inconsistent, hand-assembled UI.\nAccessibility is a real but *quiet, bounded* guarantee underneath. See\n[ADR-0003](./adr/0003-consistency-first-bounded-accessibility.md).\n\n## Implementation status\n\n- **Substrate spike** — `nbbaier/kyla-ui-spike`, all four spikes green (see below).\n- **Styling foundation** — built in `kyla-ui` and verified on the runtime:\n - `src/cn.ts` — `twMerge(clsx())`, versions pinned (clsx@2.1.1, tailwind-merge@3.6.0);\n empirically confirmed to dedupe `[color:var(--…)]` token classes. Contract:\n `cn(componentClasses, className)` — caller's `className` wins.\n - `src/theme.ts` — `tw.bg/text/border/ring(token)` builders that bake in the\n `color:` hint, plus the `ColorToken` union (typo = compile error).\n - `src/variants.ts` — hand-rolled cva-style `variants()` (no external dep).\n - `src/tokens.ts` — token stylesheet (provisional values).\n - `src/provider.tsx` — `KylaProvider` + `useKylaMode`.\n - `mod.ts` — public barrel (Radix kept out).\n- **Next** — real palette/scales, then the first component (`Button`).\n\n## Shape\n\n- **Two vals.** `kyla-ui` — the importable library, which also serves its own\n **Gallery** (docs) at its HTTP route. `kyla-ui-starter` — a remixable, genuine\n **todo app** (real HTTP route + `std/sqlite`) showing idiomatic end-to-end use.\n The Starter depends on the library; never the reverse.\n- **CSR-only for v1.** Target is interactive apps (dashboards, tools, forms) where\n SEO/first-paint don't matter. Components authored pure so isomorphic stays\n possible later, without paying its tax now.\n\n## Styling — [ADR-0001](./adr/0001-no-build-styling-architecture.md)\n\n- Semantic tokens as `--kyla-*` **CSS custom properties** using `light-dark()`;\n applied via runtime **Twind arbitrary-value** utilities (`bg-[var(--kyla-base)]`).\n No build, no bundler.\n- Token vocabulary: surfaces `base → elevated → recessed`; foreground `fg`,\n `fg-muted`; borders `line`, `hairline`; `accent`, `danger`; `radius`.\n- One opinionated theme. Small consumer **override surface** (`--kyla-accent`,\n `--kyla-radius`, font); structural tokens stay fixed — that fixedness *is* the\n consistency. A Kumo-style named-theme system is a deliberate later step.\n\n## Style delivery & theming\n\n- **`KylaProvider`** guarantees Twind + token stylesheet are present (a manual\n two-tag `` setup is the documented fallback).\n- The Provider **owns Mode**: sets `data-mode=\"light|dark|system\"`, exposes\n `useKylaMode()` (persistence opt-in); `system` falls through to OS via\n `light-dark()`. Apps get a first-class light/dark toggle for free.\n\n## Components — [ADR-0002](./adr/0002-hybrid-headless-foundation.md)\n\n- **Hybrid foundation.** Hand-roll simple visual components with zero deps; build\n on a headless library only for hard interactive ones. **Radix first** (proven\n on VT), Base UI as a likely faithful-to-Kumo later variant.\n- **v1 inventory:**\n - Zero-dep visual: `Button`, `Text`/`Heading`, `Card`, `Input`, `Textarea`,\n `Label`, `Badge`, `Stack`, `Box`, `Divider`\n - Styled native: `Select`\n - Radix-backed (the headless proof): `Dialog`\n - Deferred to v1.1+: `Checkbox`, `Radio`, `Spinner`, `Alert`, then\n `Popover`, `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`, …\n- **API:** typed **variant** props (`variant`, `size`, `tone`) mapping to tokens\n internally; escape-hatch `className` merged last via exported `cn()`; refs +\n rest props forwarded. Public surface = finished components + `cn()` + Provider.\n Radix primitives stay **internal** (so Radix→Base UI later isn't an API break).\n- **Accessibility (bounded):** correct semantic HTML, real ``/`id`\n association, token-based visible focus, no broken native keyboard behavior,\n AA contrast on the default theme. Anything needing custom ARIA → Radix tier.\n\n## Distribution — [ADR-0004](./adr/0004-version-pinned-upgrade-contract.md)\n\n- **Module layout:** barrel `mod.ts` for the zero-dep core; heavy `dialog.tsx`\n behind its own import path so Radix only loads when used.\n- **Upgrade contract:** `main` is the release line; development happens on\n branches; a **Release** is a merge to `main`. Unpinned import = latest Release\n (fixes auto-propagate); `?v=NNN` to freeze; README release table maps names →\n versions. (esm.town has no branch-import URLs, hence version pinning.)\n\n## Open verification spikes\n\nBuilt and **fully verified in-browser** as one throwaway val: **`nbbaier/kyla-ui-spike`**\n(`frontend/{App,KylaProvider,tokens}.tsx`). All four green:\n\n1. ✅ **Radix `Dialog`** — imports via esm.sh with React 18.2.0 (the\n `?deps=react@18.2.0,react-dom@18.2.0` pin propagates through Radix's whole\n transitive graph, defusing the React-mismatch `useState` null error) and\n renders/opens/closes/focus-traps cleanly under CSR.\n2. ✅ **Twind + CSS-var tokens** — surfaces render stepped, accent applies.\n3. ✅ **`KylaProvider` runtime token injection** — styles exist only because the\n Provider injected the stylesheet. (Twind stays in the *shell* since it must\n load before first paint; only the token stylesheet is Provider-injected.)\n4. ✅ **`light-dark()` + `data-mode`** — mode toggle flips the palette; resolves\n even inside the Radix portal.\n\n### Load-bearing finding (the spike's main payoff)\n\nOn Val Town's runtime **Twind, semantic-color utilities must carry the `color:`\ntype hint** — `bg-[color:var(--kyla-base)]`, `text-[color:var(--kyla-fg)]`,\n`border-[color:var(--kyla-line)]`. A bare `bg-[var(--…)]` is type-ambiguous and\nTwind **silently emits nothing** — no error, just an unstyled element. Lengths\nare fine bare (`rounded-[var(--kyla-radius)]`). Because the failure is invisible,\nthe `cn()`/variant layer must emit token utilities through a helper so authors\ncan't forget the hint. (Baked into ADR-0001.)\n\n## Deliberately deferred (not yet designed)\n\nThese were identified but intentionally not resolved in this sketch. The\n**spacing / radius / type scale** is the highest-leverage — it's where visual\nconsistency actually lives.\n\n- **Structural scales** — the spacing, radius, and typographic scales (the\n fixed tokens carrying most of the consistency). Currently undefined.\n- **Variant→token maps** — concrete `variant`/`size`/`tone` value sets per\n component (e.g. what tones `Button`/`Badge` expose).\n- **`KylaProvider` API** — its precise prop surface beyond \"owns styles + Mode\".\n- **Gallery generation** — hand-written vs generated from component metadata.\n- **Theming v2** — a Kumo-style named-theme system (multiple consumer-defined\n themes) once there's demand.\n- **Base UI variant** — a Base-UI-backed build once Radix proves the path.\n- **Isomorphic rendering** — SSR + hydration for content/landing pages, if needed.\n","createdAt",["D",1781813888241],"branchVersion","branchId","687a9437-44a8-49ca-94d7-3277b6842513","id","a2eea118-e17c-4a68-9fa4-155c6cf32150","kyla-ui",["D",1781804868537],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Components for consistently styled web apps on Val Town","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","a2eea118e17c4a689fa4155c6cf32150","tursoHostname","a2eea118e17c4a689fa4155c6cf32150-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789701064442],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_99":98,"_106":102},"org",{"_99":98,"_100":-5,"_101":102,"_18":56,"_103":104,"_105":27},"branch",{"_13":88,"_33":89,"_44":43,"_90":45,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":-5,"_96":46,"_97":98},"isOwned",269,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_44":45,"_33":46,"_39":346,"_48":-5,"_49":27,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":-5,"_58":27,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68,"_69":347,"_71":-5,"_72":73,"_74":73,"_75":76,"_77":76,"_78":76,"_79":73,"_80":73,"_81":348,"_83":349,"_85":350,"_87":27},"tree",[214,221,227,228,229,230,231,232,233],"files",[214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233],"counts",{"_203":62,"_204":205,"_206":152,"_207":208,"_209":210},"contents",[129,130,131,132,133,134,135,136,137],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_44":197,"_33":198,"_31":199,"_141":-5,"_42":43,"_41":200,"_143":25,"_39":201,"_13":62,"_35":195,"_36":-5,"_24":27,"_147":-5,"_28":202},{"_44":190,"_33":191,"_31":192,"_141":-5,"_42":43,"_41":193,"_143":25,"_39":194,"_13":62,"_35":195,"_36":-5,"_24":27,"_147":-5,"_28":196},{"_44":183,"_33":184,"_31":185,"_141":-5,"_42":43,"_41":186,"_143":25,"_39":187,"_13":152,"_35":20,"_36":188,"_24":27,"_147":-5,"_28":189},{"_44":176,"_33":177,"_31":178,"_141":-5,"_42":43,"_41":179,"_143":27,"_39":180,"_13":172,"_35":20,"_36":181,"_24":27,"_147":-5,"_28":182},{"_44":169,"_33":170,"_31":171,"_141":-5,"_42":43,"_41":172,"_143":27,"_39":173,"_13":152,"_35":20,"_36":174,"_24":27,"_147":-5,"_28":175},{"_44":162,"_33":163,"_31":164,"_141":-5,"_42":43,"_41":165,"_143":27,"_39":166,"_13":152,"_35":20,"_36":167,"_24":27,"_147":-5,"_28":168},{"_44":155,"_33":156,"_31":157,"_141":-5,"_42":43,"_41":158,"_143":27,"_39":159,"_13":152,"_35":20,"_36":160,"_24":27,"_147":-5,"_28":161},{"_44":149,"_33":150,"_31":151,"_141":-5,"_42":43,"_41":152,"_143":27,"_39":153,"_13":62,"_35":145,"_36":108,"_24":27,"_147":-5,"_28":154},{"_44":138,"_33":139,"_31":140,"_141":-5,"_42":43,"_41":142,"_143":27,"_39":144,"_13":62,"_35":145,"_36":146,"_24":27,"_147":-5,"_28":148},"3feede67-c3e6-4eae-bd6d-08da29e9b52d","mod.ts","92255786-6b52-11f1-8262-1607ee4eb77e","parentId",34,"latest",["D",1781813780838],"script","/**\n * Kylä UI — public barrel for the zero-dependency core.\n *\n * Radix-backed components (e.g. Dialog) are intentionally NOT re-exported here;\n * they live behind their own import paths so Radix only loads when used (ADR-0002).\n */\nexport { cn } from \"./src/cn.ts\";\nexport { type ColorToken, tw } from \"./src/theme.ts\";\nexport { variants } from \"./src/variants.ts\";\nexport { KylaProvider, type Mode, useKylaMode } from \"./src/provider.tsx\";\n","label",[139],"4230de32-5649-499d-aa10-24a52c073266","main.ts","d1fffa9c-6b3d-11f1-a8da-1607ee4eb77e",1,["D",1781804868548],[150],"5dfdaa24-b105-402d-9d10-36b545ece0ac","deno.json","47d67822-6b3e-11f1-bad1-1607ee4eb77e",8,["D",1781805628403],"{\n\t\"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"lint\": {\n\t\t\"files\": {\n\t\t\t\"include\": [\"deno:/https/esm.town/**/*\"]\n\t\t},\n\t\t\"rules\": { \"exclude\": [\"no-explicit-any\"] }\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\",\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@2.5.0\"\n\t}\n}\n",[156],"c74adb8c-16a0-4216-9ecf-edc4e22537b5","biome.json","47e1e748-6b3e-11f1-8b36-1607ee4eb77e",9,["D",1781805628422],"{\n \"$schema\": \"https://biomejs.dev/schemas/2.5.0/schema.json\",\n \"vcs\": { \"enabled\": true, \"clientKind\": \"git\", \"useIgnoreFile\": true },\n \"files\": { \"ignoreUnknown\": false },\n \"formatter\": { \"enabled\": true, \"indentStyle\": \"tab\" },\n \"linter\": { \"enabled\": true, \"rules\": { \"recommended\": true } },\n \"javascript\": { \"formatter\": { \"quoteStyle\": \"double\" } },\n \"assist\": {\n \"enabled\": true,\n \"actions\": { \"source\": { \"organizeImports\": \"on\" } }\n }\n}",[163],"2e06ce19-f677-4c33-9b42-7238549a5681","README.md","ec9dd180-6b3d-11f1-89a3-1607ee4eb77e",3,["D",1781804941550],"# Kylä UI\n\nA component library for building web apps on Val Town.",[170],"c0337397-a3af-4f93-884e-f82ce0cfb4e8","CONTEXT.md","bce56486-6b46-11f1-8898-1607ee4eb77e",23,["D",1781813006665],"# Kylä UI — Context\n\nA glossary of the core terms in this project. Implementation details live in code and ADRs, not here.\n\n> \"Kylä\" is Finnish for \"village.\"\n\n## Glossary\n\n### Kylä UI\n\nThe component library itself: a Val Town val (`nbbaier/kyla-ui`) that exports React components, a styling system, and any helpers needed to build consistently styled web apps. It is **consumed by import** (`import { ... } from \"https://esm.town/v/nbbaier/kyla-ui/...\"`), not by remixing. This val is the source of truth for visual consistency across apps. It **also serves its own Gallery** (docs) at its HTTP route — the library documents itself, co-located with its source.\n\n### Starter\n\nA separate, remixable demo val (`kyla-ui-starter` or similar) that shows idiomatic *end-to-end* use of Kylä UI: a tiny but genuine **todo app** with a real HTTP route and `std/sqlite`, a working app shell, Provider + hydration wiring, and view-source link. A new app begins by remixing the Starter, then editing. The Starter **depends on** Kylä UI; the library never depends on the Starter. (Component reference/docs live in the library's Gallery, not the Starter.)\n\n### Gallery\n\nThe library's self-hosted documentation surface: an HTTP route on `kyla-ui` that renders every component in its variants and Modes, with the Mode toggle. It is both living docs and the in-browser proof that the stack renders correctly on Val Town (Twind + CSS-var tokens, Provider mode, Radix `Dialog` hydration). The seed of a fuller docs site later.\n\n### Release\n\nA blessed version of Kylä UI, produced by merging a development branch into `main`. `main` is the stable line: raw development never happens on it, so HEAD-of-`main` is always a Release. Each Release corresponds to a concrete Val Town version number (`?v=NNN`). A consumer tracks Releases by importing the unpinned URL (always latest Release) or freezes onto one by pinning its `?v=NNN`, which the README's release table maps by name.\n\n### Consumer\n\nA web app (a val) built with Kylä UI. Gets visual consistency by importing the library rather than copying its code.\n\n### Semantic Token\n\nA named, intent-based design value (e.g. \"base surface,\" \"default foreground,\" \"line/border,\" \"danger\") rather than a raw value (e.g. \"blue-500\"). Components reference semantic tokens only; they never hard-code raw colors. Tokens are the unit of visual consistency and the surface through which a Theme is applied. (Modeled on Cloudflare Kumo's semantic-token system.)\n\nCanonical token vocabulary (CSS custom properties, all prefixed `--kyla-`):\n\n- **Surfaces** (hierarchy): `base` → `elevated` → `recessed`\n- **Foreground:** `fg`, `fg-muted`\n- **Borders:** `line`, `hairline`\n- **Accent / status:** `accent`, `danger` (and siblings as needed)\n- **Shape:** `radius`\n\nOf these, the consumer-facing Override Surface for v1 is intentionally small (e.g. `--kyla-accent`, `--kyla-radius`, font); the rest are structural and stay fixed.\n\n### Theme\n\nA complete set of values bound to the Semantic Tokens, producing a coherent look. A consumer switches the active theme without touching component code. Light/dark is one axis of theming; brand/variant overrides are another.\n\nFor v1, Kylä ships **one opinionated theme** with automatic light/dark, and exposes a deliberately small **Override Surface** — a few tokens (e.g. accent, radius, font) a consumer may redefine to express brand. Structural tokens (surface hierarchy, spacing, borders) stay fixed; that fixedness *is* the consistency. A fuller named-theme system (multiple consumer-defined Themes, à la Kumo's theme configs) is a deliberate later step, not a v1 feature.\n\n### Variant\n\nA named, typed dimension of a component's appearance exposed as a prop (e.g. `variant=\"primary\"`, `size=\"sm\"`, `tone=\"danger\"`). Variants map to Semantic Tokens internally; they are the consumer's primary, discoverable means of varying a component while staying on-system. An escape-hatch `className` always merges last, letting an app deviate locally without forking. For v1 the public surface is finished components plus a `cn()` helper and the Provider — the underlying Headless Primitives stay internal.\n\n### Mode\n\nThe light/dark axis of a Theme. Modeled as `data-mode=\"light\" | \"dark\" | \"system\"`, where `system` falls through to the OS preference via CSS `light-dark()` (zero JS). Mode is **owned by the Provider** — it sets `data-mode` and exposes a hook to read/set it (persistence opt-in) — so apps get a first-class light/dark toggle without hand-rolling one (a common source of inconsistency and flash-of-wrong-theme bugs).\n\n### Headless Primitive\n\nThe behavior-and-accessibility layer of an interactive component (focus management, keyboard nav, ARIA), independent of its visual styling. For the hard interactive components (Dialog, Popover, Menu, Tabs), Kylä builds on a third-party headless primitive library rather than hand-rolling. Simple visual components (Button, Card, Stack, Text, Input, Badge) have no separate Headless Primitive — they are styled directly.\n\n",[177],"1c7f3876-c7c1-4d67-8ed9-16bd851ecf3f",".vtignore","47ce4d8c-6b3e-11f1-8eca-1607ee4eb77e",13,["D",1781805649048],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor\n.claude",[184],"da3f4f02-c070-4df1-9bc5-96c25fc6eefd","src","91e38b30-6b52-11f1-bb7a-1607ee4eb77e",28,["D",1781813780417],"directory",[191],"61b715f9-32d9-45da-bff6-008ae80a2386","docs","bc8b0c5c-6b46-11f1-aeb1-1607ee4eb77e",14,["D",1781808698019],[198],"pulls","branches",7,"forks","envVars",{"_211":62,"_213":62},"connections",{"_211":62,"_212":62},"count","unfilledCount","emptyCount",{"_44":197,"_33":198,"_31":199,"_141":-5,"_42":43,"_41":200,"_143":25,"_39":343,"_13":62,"_35":195,"_36":-5,"_24":27,"_147":-5,"_235":344,"_28":345},{"_44":338,"_33":313,"_31":307,"_141":199,"_42":43,"_41":339,"_143":25,"_39":340,"_13":62,"_35":195,"_36":-5,"_24":27,"_147":-5,"_235":341,"_28":342},{"_44":330,"_33":331,"_31":332,"_141":307,"_42":43,"_41":333,"_143":27,"_39":334,"_13":301,"_35":20,"_36":335,"_24":27,"_147":-5,"_235":336,"_28":337},{"_44":322,"_33":323,"_31":324,"_141":307,"_42":43,"_41":325,"_143":27,"_39":326,"_13":62,"_35":20,"_36":327,"_24":27,"_147":-5,"_235":328,"_28":329},{"_44":314,"_33":315,"_31":316,"_141":307,"_42":43,"_41":317,"_143":27,"_39":318,"_13":62,"_35":20,"_36":319,"_24":27,"_147":-5,"_235":320,"_28":321},{"_44":304,"_33":305,"_31":306,"_141":307,"_42":43,"_41":308,"_143":27,"_39":309,"_13":62,"_35":20,"_36":310,"_24":27,"_147":-5,"_235":311,"_28":312},{"_44":299,"_33":34,"_31":32,"_141":199,"_42":43,"_41":14,"_143":27,"_39":300,"_13":301,"_35":20,"_36":38,"_24":27,"_147":-5,"_235":302,"_28":303},{"_44":190,"_33":191,"_31":192,"_141":-5,"_42":43,"_41":193,"_143":25,"_39":296,"_13":62,"_35":195,"_36":-5,"_24":27,"_147":-5,"_235":297,"_28":298},{"_44":288,"_33":289,"_31":290,"_141":192,"_42":43,"_41":291,"_143":27,"_39":292,"_13":62,"_35":145,"_36":293,"_24":27,"_147":-5,"_235":294,"_28":295},{"_44":280,"_33":281,"_31":282,"_141":192,"_42":43,"_41":283,"_143":27,"_39":284,"_13":62,"_35":145,"_36":285,"_24":27,"_147":-5,"_235":286,"_28":287},{"_44":272,"_33":273,"_31":274,"_141":192,"_42":43,"_41":275,"_143":27,"_39":276,"_13":62,"_35":145,"_36":277,"_24":27,"_147":-5,"_235":278,"_28":279},{"_44":264,"_33":265,"_31":266,"_141":192,"_42":43,"_41":267,"_143":27,"_39":268,"_13":62,"_35":145,"_36":269,"_24":27,"_147":-5,"_235":270,"_28":271},{"_44":256,"_33":257,"_31":258,"_141":192,"_42":43,"_41":259,"_143":27,"_39":260,"_13":62,"_35":145,"_36":261,"_24":27,"_147":-5,"_235":262,"_28":263},{"_44":183,"_33":184,"_31":185,"_141":-5,"_42":43,"_41":186,"_143":25,"_39":253,"_13":152,"_35":20,"_36":188,"_24":27,"_147":-5,"_235":254,"_28":255},{"_44":176,"_33":177,"_31":178,"_141":-5,"_42":43,"_41":179,"_143":27,"_39":250,"_13":172,"_35":20,"_36":181,"_24":27,"_147":-5,"_235":251,"_28":252},{"_44":169,"_33":170,"_31":171,"_141":-5,"_42":43,"_41":172,"_143":27,"_39":247,"_13":152,"_35":20,"_36":174,"_24":27,"_147":-5,"_235":248,"_28":249},{"_44":162,"_33":163,"_31":164,"_141":-5,"_42":43,"_41":165,"_143":27,"_39":244,"_13":152,"_35":20,"_36":167,"_24":27,"_147":-5,"_235":245,"_28":246},{"_44":155,"_33":156,"_31":157,"_141":-5,"_42":43,"_41":158,"_143":27,"_39":241,"_13":152,"_35":20,"_36":160,"_24":27,"_147":-5,"_235":242,"_28":243},{"_44":149,"_33":150,"_31":151,"_141":-5,"_42":43,"_41":152,"_143":27,"_39":238,"_13":62,"_35":145,"_36":108,"_24":27,"_147":-5,"_235":239,"_28":240},{"_44":138,"_33":139,"_31":140,"_141":-5,"_42":43,"_41":142,"_143":27,"_39":234,"_13":62,"_35":145,"_36":146,"_24":27,"_147":-5,"_235":236,"_28":237},["D",1781813780838],"children",[],[139],["D",1781804868548],[],[150],["D",1781805628403],[],[156],["D",1781805628422],[],[163],["D",1781804941550],[],[170],["D",1781813006665],[],[177],["D",1781805649048],[],[184],"a88539c6-46fe-4845-a806-43b03dc6c285","variants.ts","92020682-6b52-11f1-80b8-1607ee4eb77e",30,["D",1781813780594],"import { cn } from \"./cn.ts\";\n\ntype VariantShape = Record>;\ntype Selection = { [K in keyof V]?: keyof V[K] };\n\n/**\n * Minimal cva-style helper: maps typed variant props to token-based class strings.\n *\n * Hand-rolled to avoid an external dependency (per ADR-0002's keep-the-common-case\n * dependency-free posture). Supports a `base` string, `variants` maps, optional\n * `defaultVariants`, and a trailing `className` escape hatch (merged last via cn()).\n *\n * Example:\n * const button = variants({\n * base: cn(tw.radius, \"px-4 py-2 font-medium\"),\n * variants: {\n * variant: { primary: cn(tw.bg(\"accent\"), tw.text(\"accent-fg\")), ... },\n * size: { sm: \"text-sm px-3 py-1.5\", md: \"text-base\" },\n * },\n * defaultVariants: { variant: \"primary\", size: \"md\" },\n * });\n * button({ variant: \"primary\", size: \"sm\", className });\n */\nexport function variants(config: {\n\tbase?: string;\n\tvariants?: V;\n\tdefaultVariants?: Selection;\n}) {\n\treturn (props: Selection & { className?: string } = {}): string => {\n\t\tconst { className, ...selected } = props;\n\t\tconst classes: string[] = [];\n\t\tif (config.base) classes.push(config.base);\n\t\tif (config.variants) {\n\t\t\tfor (const key in config.variants) {\n\t\t\t\tconst chosen =\n\t\t\t\t\t(selected as Selection)[key] ?? config.defaultVariants?.[key];\n\t\t\t\tif (chosen != null) {\n\t\t\t\t\tconst cls = config.variants[key][chosen as string];\n\t\t\t\t\tif (cls) classes.push(cls);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn cn(...classes, className);\n\t};\n}\n",[],[191,257],"a07a6ebd-703a-4afd-a63a-79fe4d242aaa","tokens.ts","920ac18c-6b52-11f1-a416-1607ee4eb77e",31,["D",1781813780622],"/**\n * The Kylä token stylesheet, as a string the Provider injects at runtime.\n *\n * Semantic design values as CSS custom properties (ADR-0001). `light-dark()`\n * resolves against the CSS `color-scheme` property, so toggling `color-scheme`\n * via `data-mode` flips every token at once — no `dark:` variants.\n *\n * Surface hierarchy (conventional): in light mode `elevated` is the *brightest*\n * (cards lift toward the light), `base` is the page, `recessed` is an inset well;\n * dark mode inverts brightness.\n *\n * NOTE: these values are provisional. The real, AA-checked palette + spacing /\n * radius / type scales are a deferred design task (see v1-design-sketch.md).\n */\nexport const tokenCSS = `\n:root {\n color-scheme: light dark;\n\n /* surfaces — base (page) / elevated (cards) / recessed (wells) */\n --kyla-base: light-dark(#f3f4f6, #0b0b0c);\n --kyla-elevated: light-dark(#ffffff, #1c1c21);\n --kyla-recessed: light-dark(#e2e5ea, #050506);\n\n /* foreground */\n --kyla-fg: light-dark(#18181b, #f4f4f5);\n --kyla-fg-muted: light-dark(#71717a, #a1a1aa);\n\n /* borders */\n --kyla-line: light-dark(#d8dbe0, #2a2a30);\n --kyla-hairline: light-dark(#e9ebef, #1c1c21);\n\n /* accent / status */\n --kyla-accent: light-dark(#4f46e5, #818cf8);\n --kyla-accent-fg: light-dark(#ffffff, #0b0b0c);\n --kyla-danger: light-dark(#dc2626, #f87171);\n\n /* shape */\n --kyla-radius: 10px;\n}\n\n/* data-mode overrides the OS preference by pinning color-scheme */\n[data-mode=\"light\"] { color-scheme: light; }\n[data-mode=\"dark\"] { color-scheme: dark; }\n[data-mode=\"system\"] { color-scheme: light dark; }\n\nhtml, body { margin: 0; }\n`;\n",[],[191,265],"dd208b02-ab6e-4f61-8514-050ecc4bdd3e","theme.ts","92125ad2-6b52-11f1-8a2f-1607ee4eb77e",32,["D",1781813780618],"/**\n * Token utilities — the only sanctioned way to apply semantic colors.\n *\n * Authors compose styles from these instead of hand-writing `[color:var(--…)]`,\n * which makes the silent \"forgot the color: hint\" failure (see ADR-0001 — a bare\n * `bg-[var(--…)]` is type-ambiguous and Twind emits nothing) structurally\n * impossible. The TypeScript union also makes a typo'd token a compile error.\n */\nexport type ColorToken =\n\t| \"base\"\n\t| \"elevated\"\n\t| \"recessed\"\n\t| \"fg\"\n\t| \"fg-muted\"\n\t| \"line\"\n\t| \"hairline\"\n\t| \"accent\"\n\t| \"accent-fg\"\n\t| \"danger\";\n\nconst color = (prop: string, name: ColorToken): string =>\n\t`${prop}-[color:var(--kyla-${name})]`;\n\n/**\n * Token class builders. Usage: `cn(tw.bg(\"elevated\"), tw.border(\"line\"), \"p-6\")`.\n * Color builders emit the required `color:` hint; `radius` is a length and needs\n * no hint.\n */\nexport const tw = {\n\tbg: (t: ColorToken) => color(\"bg\", t),\n\ttext: (t: ColorToken) => color(\"text\", t),\n\tborder: (t: ColorToken) => color(\"border\", t),\n\tring: (t: ColorToken) => color(\"ring\", t),\n\t/** border-radius token (a length — no `color:` hint needed) */\n\tradius: \"rounded-[var(--kyla-radius)]\",\n} as const;\n",[],[191,273],"eb920d40-d5ae-444d-b40d-7a303057cc98","provider.tsx","92200010-6b52-11f1-80b8-1607ee4eb77e",33,["D",1781813780697],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, {\n\tcreateContext,\n\tuseContext,\n\tuseEffect,\n\tuseState,\n} from \"https://esm.sh/react@18.2.0\";\nimport { tokenCSS } from \"./tokens.ts\";\n\n/**\n * The Kylä root. Guarantees the styling substrate is present and owns Mode.\n *\n * - Injects the token stylesheet into at runtime (idempotent). Twind itself\n * must live in the HTML shell since it has to load before first paint (ADR-0001);\n * only the tokens are Provider-injected.\n * - Owns Mode via `data-mode` on and exposes `useKylaMode()`. `system`\n * falls through to the OS preference via `light-dark()` (zero JS).\n */\nexport type Mode = \"light\" | \"dark\" | \"system\";\n\nconst ModeContext = createContext<{ mode: Mode; setMode: (m: Mode) => void }>({\n\tmode: \"system\",\n\tsetMode: () => {},\n});\n\nexport function useKylaMode() {\n\treturn useContext(ModeContext);\n}\n\nconst TOKENS_ID = \"kyla-tokens\";\n\nexport function KylaProvider({\n\tchildren,\n\tdefaultMode = \"system\",\n}: {\n\tchildren: React.ReactNode;\n\tdefaultMode?: Mode;\n}) {\n\tconst [mode, setMode] = useState(defaultMode);\n\n\t// Inject the token stylesheet once. Idempotent: guards against double-inject.\n\tuseEffect(() => {\n\t\tif (document.getElementById(TOKENS_ID)) return;\n\t\tconst style = document.createElement(\"style\");\n\t\tstyle.id = TOKENS_ID;\n\t\tstyle.textContent = tokenCSS;\n\t\tdocument.head.appendChild(style);\n\t}, []);\n\n\t// Reflect Mode onto the document so `data-mode` selectors take effect.\n\tuseEffect(() => {\n\t\tdocument.documentElement.setAttribute(\"data-mode\", mode);\n\t}, [mode]);\n\n\treturn (\n\t\t\n\t\t\t{children}\n\t\t\n\t);\n}\n",[],[191,281],"cfbb8ed9-c113-4e57-ae9b-e6b871597c83","cn.ts","91f4e2d6-6b52-11f1-a883-1607ee4eb77e",29,["D",1781813780533],"import { type ClassValue, clsx } from \"npm:clsx@2.1.1\";\nimport { twMerge } from \"npm:tailwind-merge@3.6.0\";\n\n/**\n * Merge class strings with conflict resolution.\n *\n * `clsx` flattens conditionals/arrays and drops falsy values; `twMerge` keeps only\n * the winning class when two conflict. This matters on Val Town: Twind injects CSS\n * rules in first-seen order, so source order — not className order — would otherwise\n * decide a tie. `cn()` resolves the conflict *in the class string itself*, so the\n * outcome is deterministic regardless of Twind's injection order. The\n * `[color:var(--…)]` hint our token utilities carry (ADR-0001) is also what lets\n * twMerge group and dedupe background/text/border *colors* independently of\n * size/width utilities — verified empirically on the Val Town runtime.\n *\n * Call order is the contract: a component passes its own classes FIRST and the\n * caller's escape-hatch `className` LAST — `cn(componentClasses, className)` — so\n * the caller reliably overrides. Versions are pinned so merge behavior is\n * reproducible (bare `npm:` specifiers resolve to \"latest\" and could shift).\n */\nexport function cn(...inputs: ClassValue[]): string {\n\treturn twMerge(clsx(inputs));\n}\n",[],[191,289],["D",1781813780417],[222,223,224,225,226],[191],"060b2c50-41e2-4ffd-8b9f-a79471739d40",["D",1781813888241],2,[],[198,34],"e212033c-6c56-41c7-af04-c89fa2adbb32","0004-version-pinned-upgrade-contract.md","bcb00034-6b46-11f1-9b3f-1607ee4eb77e","bc9c5da4-6b46-11f1-aeb1-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",[],[198,313,305],"adr","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 `

Diff · v37