[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_780":781,"_782":783},"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",158,"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/adr/0005-val-town-visual-language-default-theme.md","latestPath","fileId","c7b195b4-798e-11f1-aabb-1607ee4eb77e","name","0005-val-town-visual-language-default-theme.md","fileType","content","# 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","# 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- **Coverage parity is the bar, not just palette adoption.** 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) — but \"conforms to VT\" means matching the *set* of variants, states, and techniques VT ships per component (color variants, icon-only sizing, hover/active/disabled states, mode-adaptive techniques like `blend`'s `mix-blend-mode`), not only porting palette hex/oklch values onto whatever variant list a component already happens to have. Kylä's prop *names* stay its own (previous bullet); the *coverage* those names collectively provide must match VT's per-component surface, checked against `docs/reference/val-town-style-guide.md`. This applies retroactively: a component the roadmap already marks \"Built\" (e.g. `Button`, shipped with 4 of VT's 7 button variants) is still subject to this bar and gets a revision slice, not a pass.\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","createdAt",["D",1783577301418],"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",1789614083669],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},"branch",{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"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",{"_43":44,"_32":45,"_38":775,"_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":776,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":777,"_82":778,"_84":779,"_86":25},"tree",[233,279,283,295,296,297,298,299,300,301,302],"files",[233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300,301,302],"counts",{"_222":61,"_223":224,"_225":157,"_226":227,"_228":229},"contents",[129,130,131,132,133,134,135,136,137,138,139],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles",true,"grants","orgs","customDomains",{},{"_43":216,"_32":217,"_30":218,"_143":-5,"_41":42,"_40":219,"_145":124,"_38":220,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_27":221},{"_43":210,"_32":211,"_30":212,"_143":-5,"_41":42,"_40":213,"_145":124,"_38":214,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_27":215},{"_43":203,"_32":204,"_30":205,"_143":-5,"_41":42,"_40":206,"_145":124,"_38":207,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_27":209},{"_43":196,"_32":197,"_30":198,"_143":-5,"_41":42,"_40":199,"_145":124,"_38":200,"_13":157,"_34":20,"_35":201,"_24":25,"_150":-5,"_27":202},{"_43":190,"_32":191,"_30":192,"_143":-5,"_41":42,"_40":193,"_145":25,"_38":194,"_13":147,"_34":20,"_35":188,"_24":25,"_150":-5,"_27":195},{"_43":183,"_32":184,"_30":185,"_143":-5,"_41":42,"_40":186,"_145":25,"_38":187,"_13":180,"_34":20,"_35":188,"_24":25,"_150":-5,"_27":189},{"_43":175,"_32":176,"_30":177,"_143":-5,"_41":42,"_40":178,"_145":25,"_38":179,"_13":180,"_34":20,"_35":181,"_24":25,"_150":-5,"_27":182},{"_43":167,"_32":168,"_30":169,"_143":-5,"_41":42,"_40":170,"_145":25,"_38":171,"_13":172,"_34":20,"_35":173,"_24":25,"_150":-5,"_27":174},{"_43":160,"_32":161,"_30":162,"_143":-5,"_41":42,"_40":163,"_145":25,"_38":164,"_13":157,"_34":20,"_35":165,"_24":25,"_150":-5,"_27":166},{"_43":152,"_32":153,"_30":154,"_143":-5,"_41":42,"_40":155,"_145":25,"_38":156,"_13":157,"_34":20,"_35":158,"_24":25,"_150":-5,"_27":159},{"_43":140,"_32":141,"_30":142,"_143":-5,"_41":42,"_40":144,"_145":25,"_38":146,"_13":147,"_34":148,"_35":149,"_24":25,"_150":-5,"_27":151},"c704bd8b-1c4c-434f-83f7-34691d4f1cd1","mod.ts","92255786-6b52-11f1-8262-1607ee4eb77e","parentId",55,"latest",["D",1781814540942],2,"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/utils/cn.ts\";\nexport { variants } from \"./src/utils/variants.ts\";\nexport { type ColorToken, type State, tw } from \"./src/theme/tw.ts\";\nexport { KylaProvider, type Mode, useKylaMode } from \"./src/theme/provider.tsx\";\n\n// Components\nexport { Button, type ButtonProps } from \"./src/components/button.tsx\";\n","label",[141],"5dfdaa24-b105-402d-9d10-36b545ece0ac","deno.json","47d67822-6b3e-11f1-bad1-1607ee4eb77e",8,["D",1781805628403],1,"{\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",[153],"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}",[161],"399b091b-4f55-485d-9ec9-ff6e0c5c1552","README.md","ec9dd180-6b3d-11f1-89a3-1607ee4eb77e",152,["D",1783561973686],6,"# Kylä UI\n\nA component library for building **consistently styled** web apps on Val Town.\nKylä is Finnish for \"village.\"\n\nMost Val Town apps are assembled fast and without a designer, so they end up\nlooking inconsistent. Kylä gives you opinionated, on-system components so your\napp looks coherent by default. Accessibility (semantic HTML, label association,\nvisible focus, AA contrast) is a quiet guarantee underneath.\n\nBuilt for Val Town's reality: **no build step**. Components are React, styled\nwith runtime [Twind](https://twind.style) + semantic CSS-variable tokens, and\nconsumed by import — no bundler, no codegen.\n\n## Quick start\n\n1. Your HTML shell must load Twind (it has to be present before first paint):\n\n ```html\n \n ```\n\n2. Wrap your app in `KylaProvider` (it injects the design tokens and owns\n light/dark mode), then use components:\n\n ```tsx\n /** @jsxImportSource https://esm.sh/react@18.2.0 */\n import {\n \tButton,\n \tKylaProvider,\n } from \"https://esm.town/v/nbbaier/kyla-ui/mod.ts\";\n\n export function App() {\n \treturn (\n \t\t\n \t\t\t\n \t\t\n \t);\n }\n ```\n\nTo pin a version, append `?v=NNN` to the import URL; the unpinned URL always\ntracks the latest release (see\n[ADR-0004](docs/adr/0004-version-pinned-upgrade-contract.md)).\n\n## Status\n\nEarly. The styling foundation (`cn`, `tw`, `variants`, `KylaProvider`) and the\nfirst component (`Button`) are in place; the rest of the v1 component set and\nthe real design palette are still to come.\n\n## Components\n\n- `Button` — `variant`: `primary | subtle | ghost | danger`, `size`:\n `sm | md | lg`.\n\n## Project docs\n\n- [`CONTEXT.md`](CONTEXT.md) — the glossary / shared language.\n- [`docs/roadmap.md`](docs/roadmap.md) — the dependency-ordered plan to v1 +\n status.\n- [`docs/adr/`](docs/adr/) — architecture decision records.\n\nThe substrate (Radix + Twind + tokens + Provider on Val Town) is proven in a\nseparate spike val, `nbbaier/kyla-ui-spike`.",[168],"136f8bfb-2e84-40b8-8998-d7761e4d6d80","CONTEXT.md","bce56486-6b46-11f1-8898-1607ee4eb77e",103,["D",1783378956847],4,"# 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:** `accent`, `accent-fg`, `accent-ring`, `accent-text`\n- **Status:** `danger`, `danger-fg`, `success`, `success-fg`\n- **Shape:** `radius`\n\nThe default theme's values conform to the Val Town UI style guide (see [ADR-0005](docs/adr/0005-val-town-visual-language-default-theme.md)); Kylä keeps its own richer surface hierarchy over VT's palette.\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",[176],"abcd1780-813c-4dc0-a97a-f7aaf10b008c","CLAUDE.md","a53286c6-775c-11f1-abf2-1607ee4eb77e",150,["D",1783560200004],"## Working on changes\n\nDevelopment happens on a Val Town **val branch**, never directly on `main`. `main`\nis the stable release line — HEAD-of-`main` is always a Release (a concrete\n`?v=NNN`), so raw work never lands on it. Branch off `main`, do the work on the\nbranch, and land it by merging the branch into `main`, which cuts the next Release.\nSee [ADR-0004](docs/adr/0004-version-pinned-upgrade-contract.md) for the rationale\nand the consumer-facing pinning contract.\n\n## Agent skills\n\n### Issue tracker\n\nIssues and PRDs live as local markdown files under `docs/issues//`; no external tracker. See `docs/agents/issue-tracker.md`.\n\n### Triage labels\n\nUses the default five-role label vocabulary unchanged (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.\n\n### Domain docs\n\nSingle-context layout: `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.\n",[184],"d766b8ce-7f7a-459b-a107-b895fc5ff7c9","AGENTS.md","9b865e5e-7770-11f1-b136-1607ee4eb77e",151,["D",1783560200021],[191],"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",[197],"da3f4f02-c070-4df1-9bc5-96c25fc6eefd","src","91e38b30-6b52-11f1-bb7a-1607ee4eb77e",28,["D",1781813780417],"directory",[204],"aac8fba5-9942-4296-93bc-56339f5fdbb7","preview","019f397a-0ad7-770b-b0dd-ab97f904224e",78,["D",1783375727322],[211],"61b715f9-32d9-45da-bff6-008ae80a2386","docs","bc8b0c5c-6b46-11f1-aeb1-1607ee4eb77e",14,["D",1781808698019],[217],"pulls","branches",7,"forks","envVars",{"_230":61,"_232":61},"connections",{"_230":61,"_231":61},"count","unfilledCount","emptyCount",{"_43":216,"_32":217,"_30":218,"_143":-5,"_41":42,"_40":219,"_145":124,"_38":772,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":773,"_27":774},{"_43":767,"_32":734,"_30":730,"_143":218,"_41":42,"_40":768,"_145":124,"_38":769,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":770,"_27":771},{"_43":759,"_32":760,"_30":761,"_143":730,"_41":42,"_40":762,"_145":25,"_38":763,"_13":147,"_34":20,"_35":764,"_24":25,"_150":-5,"_304":765,"_27":766},{"_43":751,"_32":752,"_30":753,"_143":730,"_41":42,"_40":754,"_145":25,"_38":755,"_13":61,"_34":20,"_35":756,"_24":25,"_150":-5,"_304":757,"_27":758},{"_43":743,"_32":744,"_30":745,"_143":730,"_41":42,"_40":746,"_145":25,"_38":747,"_13":61,"_34":20,"_35":748,"_24":25,"_150":-5,"_304":749,"_27":750},{"_43":735,"_32":736,"_30":737,"_143":730,"_41":42,"_40":738,"_145":25,"_38":739,"_13":61,"_34":20,"_35":740,"_24":25,"_150":-5,"_304":741,"_27":742},{"_43":729,"_32":33,"_30":31,"_143":730,"_41":42,"_40":14,"_145":25,"_38":731,"_13":157,"_34":20,"_35":37,"_24":25,"_150":-5,"_304":732,"_27":733},{"_43":724,"_32":707,"_30":701,"_143":218,"_41":42,"_40":725,"_145":124,"_38":726,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":727,"_27":728},{"_43":716,"_32":717,"_30":718,"_143":701,"_41":42,"_40":719,"_145":25,"_38":720,"_13":61,"_34":20,"_35":721,"_24":25,"_150":-5,"_304":722,"_27":723},{"_43":708,"_32":709,"_30":710,"_143":701,"_41":42,"_40":711,"_145":25,"_38":712,"_13":373,"_34":20,"_35":713,"_24":25,"_150":-5,"_304":714,"_27":715},{"_43":698,"_32":699,"_30":700,"_143":701,"_41":42,"_40":702,"_145":25,"_38":703,"_13":147,"_34":20,"_35":704,"_24":25,"_150":-5,"_304":705,"_27":706},{"_43":693,"_32":692,"_30":686,"_143":218,"_41":42,"_40":694,"_145":124,"_38":695,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":696,"_27":697},{"_43":683,"_32":684,"_30":685,"_143":686,"_41":42,"_40":687,"_145":25,"_38":688,"_13":61,"_34":20,"_35":689,"_24":25,"_150":-5,"_304":690,"_27":691},{"_43":678,"_32":472,"_30":505,"_143":218,"_41":42,"_40":679,"_145":124,"_38":680,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":681,"_27":682},{"_43":673,"_32":658,"_30":652,"_143":505,"_41":42,"_40":674,"_145":124,"_38":675,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":676,"_27":677},{"_43":668,"_32":472,"_30":662,"_143":652,"_41":42,"_40":669,"_145":124,"_38":670,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":671,"_27":672},{"_43":659,"_32":660,"_30":661,"_143":662,"_41":42,"_40":663,"_145":25,"_38":664,"_13":61,"_34":20,"_35":665,"_24":25,"_150":-5,"_304":666,"_27":667},{"_43":650,"_32":464,"_30":651,"_143":652,"_41":42,"_40":653,"_145":25,"_38":654,"_13":61,"_34":20,"_35":655,"_24":25,"_150":-5,"_304":656,"_27":657},{"_43":645,"_32":614,"_30":608,"_143":505,"_41":42,"_40":646,"_145":124,"_38":647,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":648,"_27":649},{"_43":640,"_32":472,"_30":618,"_143":608,"_41":42,"_40":641,"_145":124,"_38":642,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":643,"_27":644},{"_43":632,"_32":633,"_30":634,"_143":618,"_41":42,"_40":635,"_145":25,"_38":636,"_13":61,"_34":20,"_35":637,"_24":25,"_150":-5,"_304":638,"_27":639},{"_43":624,"_32":625,"_30":626,"_143":618,"_41":42,"_40":627,"_145":25,"_38":628,"_13":61,"_34":20,"_35":629,"_24":25,"_150":-5,"_304":630,"_27":631},{"_43":615,"_32":616,"_30":617,"_143":618,"_41":42,"_40":619,"_145":25,"_38":620,"_13":61,"_34":20,"_35":621,"_24":25,"_150":-5,"_304":622,"_27":623},{"_43":606,"_32":464,"_30":607,"_143":608,"_41":42,"_40":609,"_145":25,"_38":610,"_13":61,"_34":20,"_35":611,"_24":25,"_150":-5,"_304":612,"_27":613},{"_43":601,"_32":570,"_30":564,"_143":505,"_41":42,"_40":602,"_145":124,"_38":603,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":604,"_27":605},{"_43":596,"_32":472,"_30":574,"_143":564,"_41":42,"_40":597,"_145":124,"_38":598,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":599,"_27":600},{"_43":588,"_32":589,"_30":590,"_143":574,"_41":42,"_40":591,"_145":25,"_38":592,"_13":61,"_34":20,"_35":593,"_24":25,"_150":-5,"_304":594,"_27":595},{"_43":580,"_32":581,"_30":582,"_143":574,"_41":42,"_40":583,"_145":25,"_38":584,"_13":61,"_34":20,"_35":585,"_24":25,"_150":-5,"_304":586,"_27":587},{"_43":571,"_32":572,"_30":573,"_143":574,"_41":42,"_40":575,"_145":25,"_38":576,"_13":61,"_34":20,"_35":577,"_24":25,"_150":-5,"_304":578,"_27":579},{"_43":562,"_32":464,"_30":563,"_143":564,"_41":42,"_40":565,"_145":25,"_38":566,"_13":61,"_34":20,"_35":567,"_24":25,"_150":-5,"_304":568,"_27":569},{"_43":557,"_32":518,"_30":512,"_143":505,"_41":42,"_40":558,"_145":124,"_38":559,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":560,"_27":561},{"_43":552,"_32":472,"_30":522,"_143":512,"_41":42,"_40":553,"_145":124,"_38":554,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":555,"_27":556},{"_43":544,"_32":545,"_30":546,"_143":522,"_41":42,"_40":547,"_145":25,"_38":548,"_13":172,"_34":20,"_35":549,"_24":25,"_150":-5,"_304":550,"_27":551},{"_43":536,"_32":537,"_30":538,"_143":522,"_41":42,"_40":539,"_145":25,"_38":540,"_13":147,"_34":20,"_35":541,"_24":25,"_150":-5,"_304":542,"_27":543},{"_43":528,"_32":529,"_30":530,"_143":522,"_41":42,"_40":531,"_145":25,"_38":532,"_13":180,"_34":20,"_35":533,"_24":25,"_150":-5,"_304":534,"_27":535},{"_43":519,"_32":520,"_30":521,"_143":522,"_41":42,"_40":523,"_145":25,"_38":524,"_13":356,"_34":20,"_35":525,"_24":25,"_150":-5,"_304":526,"_27":527},{"_43":510,"_32":464,"_30":511,"_143":512,"_41":42,"_40":513,"_145":25,"_38":514,"_13":180,"_34":20,"_35":515,"_24":25,"_150":-5,"_304":516,"_27":517},{"_43":504,"_32":473,"_30":466,"_143":505,"_41":42,"_40":506,"_145":124,"_38":507,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":508,"_27":509},{"_43":499,"_32":472,"_30":477,"_143":466,"_41":42,"_40":500,"_145":124,"_38":501,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":502,"_27":503},{"_43":491,"_32":492,"_30":493,"_143":477,"_41":42,"_40":494,"_145":25,"_38":495,"_13":61,"_34":20,"_35":496,"_24":25,"_150":-5,"_304":497,"_27":498},{"_43":483,"_32":484,"_30":485,"_143":477,"_41":42,"_40":486,"_145":25,"_38":487,"_13":61,"_34":20,"_35":488,"_24":25,"_150":-5,"_304":489,"_27":490},{"_43":474,"_32":475,"_30":476,"_143":477,"_41":42,"_40":478,"_145":25,"_38":479,"_13":61,"_34":20,"_35":480,"_24":25,"_150":-5,"_304":481,"_27":482},{"_43":463,"_32":464,"_30":465,"_143":466,"_41":42,"_40":467,"_145":25,"_38":468,"_13":61,"_34":20,"_35":469,"_24":25,"_150":-5,"_304":470,"_27":471},{"_43":458,"_32":457,"_30":451,"_143":218,"_41":42,"_40":459,"_145":124,"_38":460,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":461,"_27":462},{"_43":448,"_32":449,"_30":450,"_143":451,"_41":42,"_40":452,"_145":25,"_38":453,"_13":61,"_34":20,"_35":454,"_24":25,"_150":-5,"_304":455,"_27":456},{"_43":440,"_32":441,"_30":442,"_143":218,"_41":42,"_40":443,"_145":25,"_38":444,"_13":157,"_34":20,"_35":445,"_24":25,"_150":-5,"_304":446,"_27":447},{"_43":210,"_32":211,"_30":212,"_143":-5,"_41":42,"_40":213,"_145":124,"_38":437,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":438,"_27":439},{"_43":430,"_32":431,"_30":432,"_143":212,"_41":42,"_40":213,"_145":25,"_38":433,"_13":61,"_34":148,"_35":434,"_24":25,"_150":-5,"_304":435,"_27":436},{"_43":423,"_32":424,"_30":425,"_143":212,"_41":42,"_40":213,"_145":25,"_38":426,"_13":61,"_34":148,"_35":427,"_24":25,"_150":-5,"_304":428,"_27":429},{"_43":415,"_32":416,"_30":417,"_143":212,"_41":42,"_40":213,"_145":25,"_38":418,"_13":61,"_34":419,"_35":420,"_24":25,"_150":-5,"_304":421,"_27":422},{"_43":203,"_32":204,"_30":205,"_143":-5,"_41":42,"_40":206,"_145":124,"_38":412,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":413,"_27":414},{"_43":407,"_32":406,"_30":400,"_143":205,"_41":42,"_40":408,"_145":124,"_38":409,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":410,"_27":411},{"_43":397,"_32":398,"_30":399,"_143":400,"_41":42,"_40":401,"_145":25,"_38":402,"_13":373,"_34":148,"_35":403,"_24":25,"_150":-5,"_304":404,"_27":405},{"_43":392,"_32":360,"_30":354,"_143":205,"_41":42,"_40":393,"_145":124,"_38":394,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":395,"_27":396},{"_43":385,"_32":386,"_30":387,"_143":354,"_41":42,"_40":170,"_145":25,"_38":388,"_13":61,"_34":148,"_35":389,"_24":25,"_150":-5,"_304":390,"_27":391},{"_43":377,"_32":378,"_30":379,"_143":354,"_41":42,"_40":380,"_145":25,"_38":381,"_13":157,"_34":148,"_35":382,"_24":25,"_150":-5,"_304":383,"_27":384},{"_43":368,"_32":369,"_30":370,"_143":354,"_41":42,"_40":371,"_145":25,"_38":372,"_13":373,"_34":148,"_35":374,"_24":25,"_150":-5,"_304":375,"_27":376},{"_43":361,"_32":362,"_30":363,"_143":354,"_41":42,"_40":170,"_145":25,"_38":364,"_13":61,"_34":148,"_35":365,"_24":25,"_150":-5,"_304":366,"_27":367},{"_43":351,"_32":352,"_30":353,"_143":354,"_41":42,"_40":170,"_145":25,"_38":355,"_13":356,"_34":148,"_35":357,"_24":25,"_150":-5,"_304":358,"_27":359},{"_43":346,"_32":337,"_30":331,"_143":205,"_41":42,"_40":347,"_145":124,"_38":348,"_13":61,"_34":208,"_35":-5,"_24":25,"_150":-5,"_304":349,"_27":350},{"_43":338,"_32":339,"_30":340,"_143":331,"_41":42,"_40":341,"_145":25,"_38":342,"_13":157,"_34":148,"_35":343,"_24":25,"_150":-5,"_304":344,"_27":345},{"_43":328,"_32":329,"_30":330,"_143":331,"_41":42,"_40":332,"_145":25,"_38":333,"_13":157,"_34":148,"_35":334,"_24":25,"_150":-5,"_304":335,"_27":336},{"_43":196,"_32":197,"_30":198,"_143":-5,"_41":42,"_40":199,"_145":124,"_38":325,"_13":157,"_34":20,"_35":201,"_24":25,"_150":-5,"_304":326,"_27":327},{"_43":190,"_32":191,"_30":192,"_143":-5,"_41":42,"_40":193,"_145":25,"_38":322,"_13":147,"_34":20,"_35":188,"_24":25,"_150":-5,"_304":323,"_27":324},{"_43":183,"_32":184,"_30":185,"_143":-5,"_41":42,"_40":186,"_145":25,"_38":319,"_13":180,"_34":20,"_35":188,"_24":25,"_150":-5,"_304":320,"_27":321},{"_43":175,"_32":176,"_30":177,"_143":-5,"_41":42,"_40":178,"_145":25,"_38":316,"_13":180,"_34":20,"_35":181,"_24":25,"_150":-5,"_304":317,"_27":318},{"_43":167,"_32":168,"_30":169,"_143":-5,"_41":42,"_40":170,"_145":25,"_38":313,"_13":172,"_34":20,"_35":173,"_24":25,"_150":-5,"_304":314,"_27":315},{"_43":160,"_32":161,"_30":162,"_143":-5,"_41":42,"_40":163,"_145":25,"_38":310,"_13":157,"_34":20,"_35":165,"_24":25,"_150":-5,"_304":311,"_27":312},{"_43":152,"_32":153,"_30":154,"_143":-5,"_41":42,"_40":155,"_145":25,"_38":307,"_13":157,"_34":20,"_35":158,"_24":25,"_150":-5,"_304":308,"_27":309},{"_43":140,"_32":141,"_30":142,"_143":-5,"_41":42,"_40":144,"_145":25,"_38":303,"_13":147,"_34":148,"_35":149,"_24":25,"_150":-5,"_304":305,"_27":306},["D",1781814540942],"children",[],[141],["D",1781805628403],[],[153],["D",1781805628422],[],[161],["D",1783561973686],[],[168],["D",1783378956847],[],[176],["D",1783560200004],[],[184],["D",1783560200021],[],[191],["D",1781805649048],[],[197],"f24cfd4b-6c74-4682-a63a-3e680149f3d1","variants.ts","92020682-6b52-11f1-80b8-1607ee4eb77e","56dc5a24-6b54-11f1-9b1d-1607ee4eb77e",52,["D",1781814540726],"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",[],[204,337,329],"utils","8575e997-6c6a-4504-9624-72ede1f62363","cn.ts","91f4e2d6-6b52-11f1-a883-1607ee4eb77e",56,["D",1781814541006],"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",[],[204,337,339],"14b26de5-d175-4ba4-8abe-7f94001d8ac4",48,["D",1781814540380],[293,294],[204,337],"be83edc6-6987-4e3e-8279-9e4d121b09a2","tw.ts","92125ad2-6b52-11f1-8a2f-1607ee4eb77e","56fb5e2e-6b54-11f1-95d4-1607ee4eb77e",["D",1783561973686],3,"/**\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 *\n * Each color builder takes an optional state prefix so prefixed utilities keep the\n * hint too — `tw.bg(\"recessed\", \"hover\")` → `hover:bg-[color:var(--kyla-recessed)]`.\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| \"accent-ring\"\n\t| \"accent-text\"\n\t| \"danger\"\n\t| \"danger-fg\"\n\t| \"success\"\n\t| \"success-fg\";\n\n/** Common interaction states a token utility may be scoped to. */\nexport type State = \"hover\" | \"focus\" | \"focus-visible\" | \"active\" | \"disabled\";\n\nconst color = (prop: string, name: ColorToken, on?: State): string =>\n\t`${on ? `${on}:` : \"\"}${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 (optionally state-prefixed);\n * `radius` is a length and needs no hint.\n */\nexport const tw = {\n\tbg: (t: ColorToken, on?: State) => color(\"bg\", t, on),\n\ttext: (t: ColorToken, on?: State) => color(\"text\", t, on),\n\tborder: (t: ColorToken, on?: State) => color(\"border\", t, on),\n\tring: (t: ColorToken, on?: State) => color(\"ring\", t, on),\n\tringOffset: (t: ColorToken, on?: State) => color(\"ring-offset\", t, on),\n\t/** border-radius token (a length — no `color:` hint needed) */\n\tradius: \"rounded-[var(--kyla-radius)]\",\n} as const;\n",[],[204,360,352],"theme","96e6551b-8e2f-4ea5-a258-e21a28e27f08","tokens_test.ts","e650bcd8-7b38-11f1-a19c-1607ee4eb77e",["D",1783561973686],"/**\n * The repo's first test harness — the load-bearing AA-contrast guarantee.\n *\n * It parses the token stylesheet, enumerates every *sanctioned* foreground /\n * surface pairing, and asserts each meets its WCAG AA threshold in **both** light\n * and dark mode. A future palette edit that breaks contrast fails here rather than\n * shipping. Kept a plain `deno test` so later scale slices reuse the pattern.\n */\nimport { assert, assertAlmostEquals } from \"jsr:@std/assert@1\";\nimport { contrastRatio } from \"./contrast.ts\";\nimport { tokenCSS } from \"./tokens.ts\";\n\ntype Mode = \"light\" | \"dark\";\ntype Palette = Record>;\n\n/** Parse `--kyla-NAME: light-dark(, );` declarations into a palette. */\nfunction parsePalette(css: string): Palette {\n\tconst re =\n\t\t/--kyla-([\\w-]+):\\s*light-dark\$\\s*(#[0-9a-fA-F]{3,6})\\s*,\\s*(#[0-9a-fA-F]{3,6})\\s*\$/g;\n\tconst palette: Palette = {};\n\tfor (const [, name, light, dark] of css.matchAll(re)) {\n\t\tpalette[name] = { light, dark };\n\t}\n\treturn palette;\n}\n\nconst palette = parsePalette(tokenCSS);\nconst MODES: Mode[] = [\"light\", \"dark\"];\n\n// WCAG AA: 4.5:1 for body text. Every sanctioned pairing here is text-on-surface.\nconst AA_BODY = 4.5;\n\n/**\n * The sanctioned foreground/surface pairings (PRD §Palette): body text and\n * secondary text on every surface, and ink on each colored fill. Anything not\n * listed here is not a promised pairing and is intentionally not asserted.\n */\nconst SURFACES = [\"base\", \"elevated\", \"recessed\"] as const;\nconst PAIRINGS: Array<{ fg: string; bg: string; min: number }> = [\n\t...SURFACES.map((bg) => ({ fg: \"fg\", bg, min: AA_BODY })),\n\t...SURFACES.map((bg) => ({ fg: \"fg-muted\", bg, min: AA_BODY })),\n\t{ fg: \"accent-fg\", bg: \"accent\", min: AA_BODY },\n\t{ fg: \"danger-fg\", bg: \"danger\", min: AA_BODY },\n\t{ fg: \"success-fg\", bg: \"success\", min: AA_BODY },\n];\n\nDeno.test(\"contrastRatio returns the correct WCAG ratio for known pairs\", () => {\n\tassertAlmostEquals(contrastRatio(\"#000000\", \"#ffffff\"), 21, 0.05);\n\tassertAlmostEquals(contrastRatio(\"#ffffff\", \"#ffffff\"), 1, 0.001);\n\t// #767676 on white is the canonical WCAG AA boundary example (~4.54:1).\n\tassertAlmostEquals(contrastRatio(\"#767676\", \"#ffffff\"), 4.54, 0.05);\n\t// Order-independent.\n\tassertAlmostEquals(\n\t\tcontrastRatio(\"#052f4a\", \"#00bcff\"),\n\t\tcontrastRatio(\"#00bcff\", \"#052f4a\"),\n\t\t0.001,\n\t);\n});\n\nDeno.test(\"every sanctioned fg/surface pairing meets AA in both modes\", () => {\n\tfor (const mode of MODES) {\n\t\tfor (const { fg, bg, min } of PAIRINGS) {\n\t\t\tassert(palette[fg], `missing token --kyla-${fg}`);\n\t\t\tassert(palette[bg], `missing token --kyla-${bg}`);\n\t\t\tconst ratio = contrastRatio(palette[fg][mode], palette[bg][mode]);\n\t\t\tassert(\n\t\t\t\tratio >= min,\n\t\t\t\t`${fg} on ${bg} (${mode}) is ${ratio.toFixed(2)}:1, below AA ${min}:1`,\n\t\t\t);\n\t\t}\n\t}\n});\n\nDeno.test(\"palette expands the color vocabulary with the new semantic tokens\", () => {\n\tfor (const name of [\n\t\t\"accent-ring\",\n\t\t\"accent-text\",\n\t\t\"danger-fg\",\n\t\t\"success\",\n\t\t\"success-fg\",\n\t]) {\n\t\tassert(palette[name], `expected --kyla-${name} in the token stylesheet`);\n\t}\n});\n\nDeno.test(\"dark-mode base uses the sanctioned slate-950 softening, not true black\", () => {\n\tassert(palette.base, \"missing --kyla-base\");\n\tassertEqualsHex(palette.base.dark, \"#020618\");\n\tassert(\n\t\tpalette.base.dark.toLowerCase() !== \"#000000\",\n\t\t\"dark base must be softened slate-950, not true black\",\n\t);\n});\n\nfunction assertEqualsHex(actual: string, expected: string): void {\n\tassert(\n\t\tactual.toLowerCase() === expected.toLowerCase(),\n\t\t`expected ${expected}, got ${actual}`,\n\t);\n}\n",[],[204,360,362],"cce7eb4a-c5e5-4ff5-a192-c28363c40d74","tokens.ts","920ac18c-6b52-11f1-a416-1607ee4eb77e",157,["D",1783576242797],5,"/**\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 * Palette: the real Val Town values, ported (not invented) from the VT UI style\n * guide and AA-verified in both modes (ADR-0005; see\n * docs/reference/val-town-style-guide.md §6–§7). The AA guarantee is enforced by\n * tokens_test.ts — a pairing that regresses fails the suite. The one sanctioned\n * deviation from VT is the dark-mode `base`: `slate-950 #020618`, a deliberate\n * softening of VT's true-black `#000` to cut glare.\n *\n * NOTE: the spacing, graduated-radius, and type scales are still provisional /\n * pending — see slices 02–03 of the `structural-scales-palette` PRD under\n * docs/issues/. `--kyla-radius` below is the provisional base until slice 02.\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(#ffffff, #020618);\n --kyla-elevated: light-dark(#ffffff, #0f172b);\n --kyla-recessed: light-dark(#f1f5f9, #1d293d);\n\n /* foreground */\n --kyla-fg: light-dark(#000000, #ffffff);\n --kyla-fg-muted: light-dark(#4a5565, #d1d5dc);\n\n /* borders */\n --kyla-line: light-dark(#e2e8f0, #314158);\n --kyla-hairline: light-dark(#f1f5f9, #1d293d);\n\n /* accent */\n --kyla-accent: light-dark(#00bcff, #0069a8);\n --kyla-accent-fg: light-dark(#052f4a, #ffffff);\n --kyla-accent-ring: light-dark(#00a6f4, #00a6f4);\n --kyla-accent-text: light-dark(#00598a, #b8e6fe);\n\n /* status — danger / success */\n --kyla-danger: light-dark(#ffa1ad, #a50036);\n --kyla-danger-fg: light-dark(#4d0218, #ffffff);\n --kyla-success: light-dark(#00d492, #007a55);\n --kyla-success-fg: light-dark(#002c22, #ffffff);\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`;",[],[204,360,369],"8c1e2920-c51a-43b7-81b7-9c313b4da7f7","provider.tsx","92200010-6b52-11f1-80b8-1607ee4eb77e",51,["D",1781814540691],"/** @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",[],[204,360,378],"f7fd6af9-a62c-46ba-8f22-efd656d4b274","contrast.ts","e6508772-7b38-11f1-a19c-1607ee4eb77e",["D",1783561973686],"/**\n * Pure WCAG contrast utilities over resolved sRGB colors — no DOM, no browser.\n *\n * This is the natural seam for the palette's AA guarantee: \"AA holds\" is a\n * property of the resolved color values, computable without a browser. The token\n * stylesheet resolves each semantic token to a concrete hex per mode (via\n * `light-dark()`); these helpers turn those hexes into WCAG contrast ratios so a\n * test can assert every sanctioned foreground/surface pairing stays legible.\n */\n\n/** An sRGB color as integer channels in the range 0–255. */\nexport type RGB = [r: number, g: number, b: number];\n\n/** Parse a `#rgb` or `#rrggbb` hex string into sRGB channels (0–255). */\nexport function parseHex(hex: string): RGB {\n\tconst h = hex.trim().replace(/^#/, \"\");\n\tconst full =\n\t\th.length === 3\n\t\t\t? h\n\t\t\t\t\t.split(\"\")\n\t\t\t\t\t.map((c) => c + c)\n\t\t\t\t\t.join(\"\")\n\t\t\t: h;\n\tif (!/^[0-9a-fA-F]{6}$/.test(full)) {\n\t\tthrow new Error(`Invalid hex color: ${hex}`);\n\t}\n\treturn [\n\t\tparseInt(full.slice(0, 2), 16),\n\t\tparseInt(full.slice(2, 4), 16),\n\t\tparseInt(full.slice(4, 6), 16),\n\t];\n}\n\n/** WCAG relative luminance of an sRGB color (0 = black, 1 = white). */\nexport function relativeLuminance([r, g, b]: RGB): number {\n\tconst linear = (channel: number): number => {\n\t\tconst s = channel / 255;\n\t\treturn s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;\n\t};\n\treturn 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);\n}\n\n/**\n * WCAG contrast ratio between two colors (hex strings), in the range 1–21.\n * Order-independent: `contrastRatio(a, b) === contrastRatio(b, a)`.\n */\nexport function contrastRatio(a: string, b: string): number {\n\tconst la = relativeLuminance(parseHex(a));\n\tconst lb = relativeLuminance(parseHex(b));\n\tconst lighter = Math.max(la, lb);\n\tconst darker = Math.min(la, lb);\n\treturn (lighter + 0.05) / (darker + 0.05);\n}\n",[],[204,360,386],"05fe2e2c-2444-41d7-938d-50483f27ebd6",50,["D",1781814540580],[287,288,289,290,291],[204,360],"93ec1eab-46e1-47b1-b539-e4c9392cc4c9","button.tsx","8569cf08-6b53-11f1-a668-1607ee4eb77e","56eb3bb6-6b54-11f1-95d4-1607ee4eb77e",54,["D",1781814540720],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { forwardRef } from \"https://esm.sh/react@18.2.0\";\nimport { cn } from \"../utils/cn.ts\";\nimport { tw } from \"../theme/tw.ts\";\nimport { variants } from \"../utils/variants.ts\";\n\n/**\n * Button — the first zero-dependency component, and the reference for how every\n * component is authored: typed variant props mapped to token classes via\n * `variants()`, a semantic `\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",[],[211,431],["D",1783375727322],[280,281,282],[211],"05e39f36-2b11-441b-96a4-059c779a90c3","roadmap.md","45b8411a-798a-11f1-b04a-1607ee4eb77e",101,["D",1783378956774],"# 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, **conforming to the Val Town UI style guide** ([ADR-0005](adr/0005-val-town-visual-language-default-theme.md)). 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 `

{title}

Diff · v158