`, `<select>`, `<hr>`,\n    heading tags for `Heading`).\n  - Assert token utility classes are present for the chosen variant/tone (e.g.\n    `Badge tone=\"danger\"` emits `bg-[color:var(--kyla-danger)]`).\n  - Assert accessibility wiring: `Label htmlFor` matches an `Input id`; `Input`\n    forwards `type`; `disabled`/`aria-invalid` render; the focus-ring classes\n    are present on interactive components.\n  - Assert `className` wins over the component's own conflicting class (the\n    `cn()` contract).\n- **Modules tested:** every component in `src/components/`.\n- **Prior art:** the harness established by the\n  [scales PRD](../structural-scales-palette/spec.md); if this ships first, it\n  establishes the render-to-HTML harness itself. `Button` is the reference for\n  what a component's rendered output should look like.\n\n## Out of Scope\n\n- `Button` **'s polymorphic rendering** (VT's Router Link / external-link button\n  forms) — needs a Slot-style primitive Kylä doesn't have yet. Flagged by the\n  variant-parity audit, not built here.\n- `Dialog` and any Radix-backed component —\n  [separate PRD](../dialog-radix/spec.md).\n- v1.1+ deferred components: `Checkbox`, `Radio`, `Spinner`, `Alert`, then\n  `Popover`, `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`.\n- The **Gallery** rendering of these components —\n  [separate PRD](../gallery/spec.md).\n- Defining the scales themselves —\n  [scales PRD](../structural-scales-palette/spec.md).\n\n## Further Notes\n\n- Building the set will dogfood the scale tokens and likely surface gaps (as\n  `Button` surfaced the state-prefixed token-utility gap). Feed those back into\n  the scales/`tw` layer rather than working around them in a component.\n- Keep each component small enough that the `Button` pattern stays legible; the\n  uniformity is the point.\n",[176,85,88,75],"8d937677-ed43-4f12-a3b9-e14e9a3359dd",["D",1784075151835],[176,85,88,85],"pulls","branches",7,"forks","envVars",{"_81":26,"_195":26},"connections",{"_81":26,"_194":26},"unfilledCount","emptyCount",{"_33":759,"_13":176,"_73":474,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":760,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":761,"_17":762},{"_33":755,"_13":726,"_73":721,"_43":474,"_35":36,"_170":40,"_171":24,"_37":756,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":757,"_17":758},{"_33":748,"_13":749,"_73":750,"_43":721,"_35":36,"_170":40,"_171":24,"_37":751,"_39":26,"_76":21,"_173":752,"_77":30,"_174":-5,"_278":753,"_17":754},{"_33":741,"_13":742,"_73":743,"_43":721,"_35":36,"_170":40,"_171":24,"_37":744,"_39":26,"_76":21,"_173":745,"_77":30,"_174":-5,"_278":746,"_17":747},{"_33":734,"_13":735,"_73":736,"_43":721,"_35":36,"_170":40,"_171":24,"_37":737,"_39":26,"_76":21,"_173":738,"_77":30,"_174":-5,"_278":739,"_17":740},{"_33":727,"_13":728,"_73":729,"_43":721,"_35":36,"_170":40,"_171":24,"_37":730,"_39":26,"_76":21,"_173":731,"_77":30,"_174":-5,"_278":732,"_17":733},{"_33":718,"_13":719,"_73":720,"_43":721,"_35":36,"_170":40,"_171":24,"_37":722,"_39":26,"_76":21,"_173":723,"_77":30,"_174":-5,"_278":724,"_17":725},{"_33":714,"_13":699,"_73":694,"_43":474,"_35":36,"_170":40,"_171":24,"_37":715,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":716,"_17":717},{"_33":707,"_13":708,"_73":709,"_43":694,"_35":36,"_170":40,"_171":24,"_37":710,"_39":26,"_76":21,"_173":711,"_77":30,"_174":-5,"_278":712,"_17":713},{"_33":700,"_13":701,"_73":702,"_43":694,"_35":36,"_170":40,"_171":24,"_37":703,"_39":26,"_76":21,"_173":704,"_77":30,"_174":-5,"_278":705,"_17":706},{"_33":691,"_13":692,"_73":693,"_43":694,"_35":36,"_170":40,"_171":24,"_37":695,"_39":26,"_76":21,"_173":696,"_77":30,"_174":-5,"_278":697,"_17":698},{"_33":687,"_13":686,"_73":681,"_43":474,"_35":36,"_170":40,"_171":24,"_37":688,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":689,"_17":690},{"_33":678,"_13":679,"_73":680,"_43":681,"_35":36,"_170":40,"_171":24,"_37":682,"_39":26,"_76":21,"_173":683,"_77":30,"_174":-5,"_278":684,"_17":685},{"_33":674,"_13":85,"_73":169,"_43":474,"_35":36,"_170":40,"_171":24,"_37":675,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":676,"_17":677},{"_33":670,"_13":657,"_73":652,"_43":169,"_35":36,"_170":40,"_171":24,"_37":671,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":672,"_17":673},{"_33":666,"_13":85,"_73":661,"_43":652,"_35":36,"_170":40,"_171":24,"_37":667,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":668,"_17":669},{"_33":658,"_13":659,"_73":660,"_43":661,"_35":36,"_170":40,"_171":24,"_37":662,"_39":26,"_76":21,"_173":663,"_77":30,"_174":-5,"_278":664,"_17":665},{"_33":650,"_13":75,"_73":651,"_43":652,"_35":36,"_170":40,"_171":24,"_37":653,"_39":26,"_76":21,"_173":654,"_77":30,"_174":-5,"_278":655,"_17":656},{"_33":646,"_13":619,"_73":614,"_43":169,"_35":36,"_170":40,"_171":24,"_37":647,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":648,"_17":649},{"_33":642,"_13":85,"_73":623,"_43":614,"_35":36,"_170":40,"_171":24,"_37":643,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":644,"_17":645},{"_33":635,"_13":636,"_73":637,"_43":623,"_35":36,"_170":40,"_171":24,"_37":638,"_39":26,"_76":21,"_173":639,"_77":30,"_174":-5,"_278":640,"_17":641},{"_33":628,"_13":629,"_73":630,"_43":623,"_35":36,"_170":40,"_171":24,"_37":631,"_39":26,"_76":21,"_173":632,"_77":30,"_174":-5,"_278":633,"_17":634},{"_33":620,"_13":621,"_73":622,"_43":623,"_35":36,"_170":40,"_171":24,"_37":624,"_39":26,"_76":21,"_173":625,"_77":30,"_174":-5,"_278":626,"_17":627},{"_33":612,"_13":75,"_73":613,"_43":614,"_35":36,"_170":40,"_171":24,"_37":615,"_39":26,"_76":21,"_173":616,"_77":30,"_174":-5,"_278":617,"_17":618},{"_33":608,"_13":581,"_73":576,"_43":169,"_35":36,"_170":40,"_171":24,"_37":609,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":610,"_17":611},{"_33":604,"_13":85,"_73":585,"_43":576,"_35":36,"_170":40,"_171":24,"_37":605,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":606,"_17":607},{"_33":597,"_13":598,"_73":599,"_43":585,"_35":36,"_170":40,"_171":24,"_37":600,"_39":26,"_76":21,"_173":601,"_77":30,"_174":-5,"_278":602,"_17":603},{"_33":590,"_13":591,"_73":592,"_43":585,"_35":36,"_170":40,"_171":24,"_37":593,"_39":26,"_76":21,"_173":594,"_77":30,"_174":-5,"_278":595,"_17":596},{"_33":582,"_13":583,"_73":584,"_43":585,"_35":36,"_170":40,"_171":24,"_37":586,"_39":26,"_76":21,"_173":587,"_77":30,"_174":-5,"_278":588,"_17":589},{"_33":574,"_13":75,"_73":575,"_43":576,"_35":36,"_170":40,"_171":24,"_37":577,"_39":26,"_76":21,"_173":578,"_77":30,"_174":-5,"_278":579,"_17":580},{"_33":570,"_13":536,"_73":531,"_43":169,"_35":36,"_170":40,"_171":24,"_37":571,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":572,"_17":573},{"_33":566,"_13":85,"_73":540,"_43":531,"_35":36,"_170":40,"_171":24,"_37":567,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":568,"_17":569},{"_33":559,"_13":560,"_73":561,"_43":540,"_35":36,"_170":40,"_171":24,"_37":562,"_39":26,"_76":21,"_173":563,"_77":30,"_174":-5,"_278":564,"_17":565},{"_33":552,"_13":553,"_73":554,"_43":540,"_35":36,"_170":40,"_171":24,"_37":555,"_39":26,"_76":21,"_173":556,"_77":30,"_174":-5,"_278":557,"_17":558},{"_33":545,"_13":546,"_73":547,"_43":540,"_35":36,"_170":40,"_171":24,"_37":548,"_39":26,"_76":21,"_173":549,"_77":30,"_174":-5,"_278":550,"_17":551},{"_33":537,"_13":538,"_73":539,"_43":540,"_35":36,"_170":40,"_171":24,"_37":541,"_39":26,"_76":21,"_173":542,"_77":30,"_174":-5,"_278":543,"_17":544},{"_33":529,"_13":75,"_73":530,"_43":531,"_35":36,"_170":40,"_171":24,"_37":532,"_39":26,"_76":21,"_173":533,"_77":30,"_174":-5,"_278":534,"_17":535},{"_33":168,"_13":88,"_73":87,"_43":169,"_35":36,"_170":40,"_171":24,"_37":526,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":527,"_17":528},{"_33":183,"_13":85,"_73":84,"_43":87,"_35":36,"_170":40,"_171":24,"_37":523,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":524,"_17":525},{"_33":516,"_13":517,"_73":518,"_43":84,"_35":36,"_170":40,"_171":24,"_37":519,"_39":26,"_76":21,"_173":520,"_77":30,"_174":-5,"_278":521,"_17":522},{"_33":509,"_13":510,"_73":511,"_43":84,"_35":36,"_170":40,"_171":24,"_37":512,"_39":26,"_76":21,"_173":513,"_77":30,"_174":-5,"_278":514,"_17":515},{"_33":502,"_13":503,"_73":504,"_43":84,"_35":36,"_170":40,"_171":24,"_37":505,"_39":26,"_76":21,"_173":506,"_77":30,"_174":-5,"_278":507,"_17":508},{"_33":495,"_13":496,"_73":497,"_43":84,"_35":36,"_170":40,"_171":24,"_37":498,"_39":26,"_76":21,"_173":499,"_77":30,"_174":-5,"_278":500,"_17":501},{"_33":179,"_13":75,"_73":74,"_43":87,"_35":36,"_170":40,"_171":24,"_37":492,"_39":26,"_76":21,"_173":181,"_77":30,"_174":-5,"_278":493,"_17":494},{"_33":488,"_13":487,"_73":482,"_43":474,"_35":36,"_170":40,"_171":24,"_37":489,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":490,"_17":491},{"_33":479,"_13":480,"_73":481,"_43":482,"_35":36,"_170":126,"_171":24,"_37":483,"_39":82,"_76":21,"_173":484,"_77":30,"_174":-5,"_278":485,"_17":486},{"_33":471,"_13":472,"_73":473,"_43":474,"_35":36,"_170":40,"_171":24,"_37":475,"_39":26,"_76":21,"_173":476,"_77":30,"_174":-5,"_278":477,"_17":478},{"_33":467,"_13":452,"_73":446,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":468,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":469,"_17":470},{"_33":460,"_13":461,"_73":462,"_43":446,"_35":36,"_170":126,"_171":24,"_37":463,"_39":82,"_76":276,"_173":464,"_77":30,"_174":-5,"_278":465,"_17":466},{"_33":453,"_13":454,"_73":455,"_43":446,"_35":36,"_170":40,"_171":24,"_37":456,"_39":26,"_76":276,"_173":457,"_77":30,"_174":-5,"_278":458,"_17":459},{"_33":443,"_13":444,"_73":445,"_43":446,"_35":36,"_170":40,"_171":24,"_37":447,"_39":26,"_76":448,"_173":449,"_77":30,"_174":-5,"_278":450,"_17":451},{"_33":439,"_13":330,"_73":340,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":440,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":441,"_17":442},{"_33":435,"_13":413,"_73":408,"_43":340,"_35":36,"_170":40,"_171":24,"_37":436,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":437,"_17":438},{"_33":428,"_13":429,"_73":430,"_43":408,"_35":36,"_170":40,"_171":24,"_37":431,"_39":26,"_76":276,"_173":432,"_77":30,"_174":-5,"_278":433,"_17":434},{"_33":421,"_13":422,"_73":423,"_43":408,"_35":36,"_170":126,"_171":24,"_37":424,"_39":82,"_76":276,"_173":425,"_77":30,"_174":-5,"_278":426,"_17":427},{"_33":414,"_13":415,"_73":416,"_43":408,"_35":36,"_170":126,"_171":24,"_37":417,"_39":40,"_76":276,"_173":418,"_77":30,"_174":-5,"_278":419,"_17":420},{"_33":405,"_13":406,"_73":407,"_43":408,"_35":36,"_170":126,"_171":24,"_37":409,"_39":40,"_76":276,"_173":410,"_77":30,"_174":-5,"_278":411,"_17":412},{"_33":401,"_13":400,"_73":395,"_43":340,"_35":36,"_170":82,"_171":24,"_37":402,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":403,"_17":404},{"_33":392,"_13":393,"_73":394,"_43":395,"_35":36,"_170":126,"_171":24,"_37":396,"_39":40,"_76":276,"_173":397,"_77":30,"_174":-5,"_278":398,"_17":399},{"_33":388,"_13":352,"_73":347,"_43":340,"_35":36,"_170":40,"_171":24,"_37":389,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":390,"_17":391},{"_33":381,"_13":382,"_73":383,"_43":347,"_35":36,"_170":40,"_171":24,"_37":384,"_39":26,"_76":276,"_173":385,"_77":30,"_174":-5,"_278":386,"_17":387},{"_33":374,"_13":375,"_73":376,"_43":347,"_35":36,"_170":40,"_171":24,"_37":377,"_39":26,"_76":276,"_173":378,"_77":30,"_174":-5,"_278":379,"_17":380},{"_33":367,"_13":368,"_73":369,"_43":347,"_35":36,"_170":126,"_171":24,"_37":370,"_39":82,"_76":276,"_173":371,"_77":30,"_174":-5,"_278":372,"_17":373},{"_33":360,"_13":361,"_73":362,"_43":347,"_35":36,"_170":126,"_171":24,"_37":363,"_39":82,"_76":276,"_173":364,"_77":30,"_174":-5,"_278":365,"_17":366},{"_33":353,"_13":354,"_73":355,"_43":347,"_35":36,"_170":40,"_171":24,"_37":356,"_39":26,"_76":276,"_173":357,"_77":30,"_174":-5,"_278":358,"_17":359},{"_33":344,"_13":345,"_73":346,"_43":347,"_35":36,"_170":40,"_171":24,"_37":348,"_39":26,"_76":276,"_173":349,"_77":30,"_174":-5,"_278":350,"_17":351},{"_33":339,"_13":331,"_73":325,"_43":340,"_35":36,"_170":40,"_171":24,"_37":341,"_39":26,"_76":86,"_173":-5,"_77":30,"_174":-5,"_278":342,"_17":343},{"_33":332,"_13":333,"_73":334,"_43":325,"_35":36,"_170":40,"_171":24,"_37":335,"_39":26,"_76":276,"_173":336,"_77":30,"_174":-5,"_278":337,"_17":338},{"_33":322,"_13":323,"_73":324,"_43":325,"_35":36,"_170":40,"_171":24,"_37":326,"_39":26,"_76":276,"_173":327,"_77":30,"_174":-5,"_278":328,"_17":329},{"_33":315,"_13":316,"_73":317,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":318,"_39":26,"_76":21,"_173":319,"_77":30,"_174":-5,"_278":320,"_17":321},{"_33":309,"_13":310,"_73":311,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":312,"_39":26,"_76":21,"_173":306,"_77":30,"_174":-5,"_278":313,"_17":314},{"_33":302,"_13":303,"_73":304,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":305,"_39":26,"_76":21,"_173":306,"_77":30,"_174":-5,"_278":307,"_17":308},{"_33":295,"_13":296,"_73":297,"_43":-5,"_35":36,"_170":126,"_171":24,"_37":298,"_39":82,"_76":21,"_173":299,"_77":30,"_174":-5,"_278":300,"_17":301},{"_33":288,"_13":289,"_73":290,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":291,"_39":26,"_76":21,"_173":292,"_77":30,"_174":-5,"_278":293,"_17":294},{"_33":281,"_13":282,"_73":283,"_43":-5,"_35":36,"_170":40,"_171":24,"_37":284,"_39":26,"_76":21,"_173":285,"_77":30,"_174":-5,"_278":286,"_17":287},{"_33":272,"_13":273,"_73":274,"_43":-5,"_35":36,"_170":126,"_171":24,"_37":275,"_39":82,"_76":276,"_173":277,"_77":30,"_174":-5,"_278":279,"_17":280},"4def3fda-1765-4d81-bec4-1c62c9e7de82","mod.ts","019f632a-69d4-710e-80e2-cd9f72b88c81",["D",1784076371562],"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 */\n\n// Components\nexport { Button, type ButtonProps } from \"./src/components/button.tsx\";\nexport {\n  Heading,\n  type HeadingLevel,\n  type HeadingProps,\n  Text,\n  type TextProps,\n  type TextTone,\n} from \"./src/components/text.tsx\";\nexport { KylaProvider, type Mode, useKylaMode } from \"./src/theme/provider.tsx\";\nexport {\n  type ColorToken,\n  type FontWeightToken,\n  type RadiusToken,\n  type SpaceProperty,\n  type SpaceToken,\n  type State,\n  tw,\n  type TypeToken,\n} from \"./src/theme/tw.ts\";\nexport { cn } from \"./src/utils/cn.ts\";\nexport { variants } from \"./src/utils/variants.ts\";\n","children",[],[273],"079ed122-62c9-4baa-b243-8ea35082022e","deno.json","019f632a-69d4-710e-80e2-cb2ae713e438",["D",1784075151835],"{\n  \"compilerOptions\": {\n    \"lib\": [\n      \"dom\",\n      \"dom.iterable\",\n      \"dom.asynciterable\",\n      \"deno.ns\",\n      \"deno.unstable\"\n    ],\n    \"noImplicitAny\": false,\n    \"strict\": false,\n    \"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n  },\n  \"experimental\": {\n    \"unstable-node-globals\": true,\n    \"unstable-sloppy-imports\": true,\n    \"unstable-temporal\": true,\n    \"unstable-worker-options\": true\n  },\n  \"fmt\": {\n    \"exclude\": [\".vt/\"]\n  },\n  \"lint\": {\n    \"include\": [\"mod.ts\", \"preview/\", \"src/\"],\n    \"rules\": {\n      \"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n    }\n  },\n  \"tasks\": {\n    \"fmt\": \"deno fmt\",\n    \"fmt:check\": \"deno fmt --check\",\n    \"lint\": \"deno lint\",\n    \"typecheck\": \"deno check --allow-import=esm.town,www.val.town,esm.sh,jsr.io mod.ts preview src\",\n    \"test\": \"deno test --allow-import=esm.town,www.val.town,esm.sh,jsr.io\",\n    \"check\": \"deno task fmt:check && deno task lint && deno task typecheck && deno task test\"\n  },\n  \"lock\": false,\n  \"nodeModulesDir\": \"auto\"\n}\n",[],[282],"2adcb6c4-3db3-446f-ad45-99bb741f7c46","README.md","019f632a-69d4-710e-80e2-c76f50b01210",["D",1784075151835],"# 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   <script src=\"https://cdn.twind.style\" crossorigin></script>\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     Button,\n     KylaProvider,\n   } from \"https://esm.town/v/nbbaier/kyla-ui/mod.ts\";\n\n   export function App() {\n     return (\n       <KylaProvider>\n         <Button variant=\"primary\" onClick={() => alert(\"hi\")}>Save</Button>\n       </KylaProvider>\n     );\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`), real\nAA-checked palette, structural spacing/radius/type scales, and first component\n(`Button`) are in place. The rest of the v1 component set is 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`.\n",[],[289],"e6bd7c35-e130-4d9d-97a2-5d95337aba29","CONTEXT.md","019f632a-69d4-710e-80e2-c25ffa618701",["D",1784076371562],"# Kylä UI — Context\n\nA glossary of the core terms in this project. Implementation details live in\ncode 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\nReact components, a styling system, and any helpers needed to build consistently\nstyled web apps. It is **consumed by import**\n(`import { ... } from \"https://esm.town/v/nbbaier/kyla-ui/...\"`), not by\nremixing. This val is the source of truth for visual consistency across apps. It\n**also serves its own Gallery** (docs) at its HTTP route — the library documents\nitself, co-located with its source.\n\n### Starter\n\nA separate, remixable demo val (`kyla-ui-starter` or similar) that shows\nidiomatic _end-to-end_ use of Kylä UI: a tiny but genuine **todo app** with a\nreal HTTP route and `std/sqlite`, a working app shell, Provider + hydration\nwiring, and view-source link. A new app begins by remixing the Starter, then\nediting. The Starter **depends on** Kylä UI; the library never depends on the\nStarter. (Component reference/docs live in the library's Gallery, not the\nStarter.)\n\n### Gallery\n\nThe library's self-hosted documentation surface: an HTTP route on `kyla-ui` that\nrenders every component in its variants and Modes, with the Mode toggle. It is\nboth living docs and the in-browser proof that the stack renders correctly on\nVal Town (Twind + CSS-var tokens, Provider mode, Radix `Dialog` hydration). The\nseed of a fuller docs site later.\n\n### Release\n\nA blessed version of Kylä UI, produced by merging a development branch into\n`main`. `main` is the stable line: raw development never happens on it, so\nHEAD-of-`main` is always a Release. Each Release corresponds to a concrete Val\nTown version number (`?v=NNN`). A consumer tracks Releases by importing the\nunpinned URL (always latest Release) or freezes onto one by pinning its\n`?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\nlibrary rather than copying its code.\n\n### Semantic Token\n\nA named, intent-based design value (e.g. \"base surface,\" \"default foreground,\"\n\"line/border,\" \"danger\") rather than a raw value (e.g. \"blue-500\"). Components\nreference semantic tokens only; they never hard-code raw colors. Tokens are the\nunit of visual consistency and the surface through which a Theme is applied.\n(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`, `danger-text`, `success`, `success-fg`\n- **Shape:** `radius`\n\nThe default theme's values conform to the Val Town UI style guide (see\n[ADR-0005](docs/adr/0005-val-town-visual-language-default-theme.md)); Kylä keeps\nits own richer surface hierarchy over VT's palette.\n\nOf these, the consumer-facing Override Surface for v1 is exactly\n`--kyla-accent`, `--kyla-radius`, and `--kyla-font`; the rest are structural and\noutside the supported theme override surface.\n\n### Theme\n\nA complete set of values bound to the Semantic Tokens, producing a coherent\nlook. A consumer switches the active theme without touching component code.\nLight/dark is one axis of theming; brand/variant overrides are another.\n\nFor v1, Kylä ships **one opinionated theme** with automatic light/dark, and\nexposes a deliberately small **Override Surface**: consumers may redefine\n`--kyla-accent`, `--kyla-radius`, and `--kyla-font` (with the graduated radius\ntokens deriving directly from `--kyla-radius`). Everything else is structural\nand fixed as the supported consumer contract: the surface hierarchy, foreground\nand border roles, status roles, spacing scale, type sizes and line-heights, and\nfont weights. Because these values are CSS custom properties, consumers can\ntechnically redefine them, but doing so is an unsupported escape hatch rather\nthan part of the Theme API. That stable contract _is_ the consistency. A fuller\nnamed-theme system (multiple consumer-defined Themes, à la Kumo's theme configs)\nis 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.\n`variant=\"primary\"`, `size=\"sm\"`, `tone=\"danger\"`). Variants map to Semantic\nTokens internally; they are the consumer's primary, discoverable means of\nvarying a component while staying on-system. An escape-hatch `className` always\nmerges last, letting an app deviate locally without forking. For v1 the public\nsurface is finished components plus a `cn()` helper and the Provider — the\nunderlying Headless Primitives stay internal.\n\n### Mode\n\nThe light/dark axis of a Theme. Modeled as\n`data-mode=\"light\" | \"dark\" | \"system\"`, where `system` falls through to the OS\npreference via CSS `light-dark()` (zero JS). Mode is **owned by the Provider** —\nit sets `data-mode` and exposes a hook to read/set it (persistence opt-in) — so\napps get a first-class light/dark toggle without hand-rolling one (a common\nsource of inconsistency and flash-of-wrong-theme bugs).\n\n### Headless Primitive\n\nThe behavior-and-accessibility layer of an interactive component (focus\nmanagement, keyboard nav, ARIA), independent of its visual styling. For the hard\ninteractive components (Dialog, Popover, Menu, Tabs), Kylä builds on a\nthird-party headless primitive library rather than hand-rolling. Simple visual\ncomponents (Button, Card, Stack, Text, Input, Badge) have no separate Headless\nPrimitive — they are styled directly.\n",[],[296],"80c65449-8268-4624-b5fd-01b38fd2419c","CLAUDE.md","019f632a-69d4-710e-80e2-bdf01bdc686a",["D",1784075151835],"## Working on changes\n\nDevelopment happens on a Val Town **val branch**, never directly on `main`.\n`main` is the stable release line — HEAD-of-`main` is always a Release (a\nconcrete `?v=NNN`), so raw work never lands on it. Branch off `main`, do the\nwork on the branch, and land it by merging the branch into `main`, which cuts\nthe next Release. See\n[ADR-0004](docs/adr/0004-version-pinned-upgrade-contract.md) for the rationale\nand the consumer-facing pinning contract.\n\n**Exception: docs-only changes push straight to `main`.** Changes confined to\n`docs/**` (specs, ADRs, roadmap, reference docs) carry no code/version surface,\nso they don't need a branch + merge cycle — push them directly. Any change that\ntouches `src/`, `mod.ts`, or other shipped code still follows the branch flow\nabove.\n\n### Val Town branch workflow\n\n- Before starting, verify the checkout with `vt status`, then branch from the\n  stable line with `vt checkout main` followed by\n  `vt checkout -b <feature-prefix>-NN-<slug>`; use a short prefix derived from\n  the spec/feature (for example, `scales-03-type-scale-and-font`).\n- Keep implementation work on that branch. `vt push` is the Val Town commit for\n  the branch; finish by running `vt status` and confirming local state matches\n  remote state.\n- A ticket is not landed when it is merely pushed to a work branch. Merge the\n  branch into `main` to cut the next Release, then record the `Landed: vNNN`\n  version and `Status: done` in the issue file.\n\n## Agent skills\n\n### Issue tracker\n\nIssues and specs live as local markdown files under\n`docs/issues/<feature-slug>/`; no external tracker. See\n`docs/agents/issue-tracker.md`.\n\n### Triage labels\n\nUses the default five-role label vocabulary unchanged (`needs-triage`,\n`needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See\n`docs/agents/triage-labels.md`.\n\n### Domain docs\n\nSingle-context layout: `CONTEXT.md` + `docs/adr/` at the repo root. See\n`docs/agents/domain.md`.\n",[],[303],"bc67344f-63c2-4b41-b1d4-216d27d3609f","AGENTS.md","019f632a-69d4-710e-80e2-b84842d73487",["D",1784075151835],[],[310],"11731f08-1734-4460-a3ca-4f177abb3fd3",".vtignore","019f632a-69d4-710e-80e2-b766669d1e53",["D",1784075151835],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor\n.claude",[],[316],"12e5b37f-834f-45a3-b385-90eb49da0de2","variants.ts","019f632a-69d4-710e-80e2-ab7e297b283f","019f632a-69d4-710e-80e2-af72c74dc25d",["D",1784075151835],"import { cn } from \"./cn.ts\";\n\ntype VariantShape = Record<string, Record<string, string>>;\ntype Selection<V extends VariantShape> = { [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(\"md\"), \"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<V extends VariantShape>(config: {\n  base?: string;\n  variants?: V;\n  defaultVariants?: Selection<V>;\n}) {\n  return (props: Selection<V> & { className?: string } = {}): string => {\n    const selected: Selection<V> = props;\n    const classes: string[] = [];\n    if (config.base) classes.push(config.base);\n    if (config.variants) {\n      for (const key in config.variants) {\n        const chosen = selected[key] ?? config.defaultVariants?.[key];\n        if (chosen != null) {\n          const cls = config.variants[key][chosen];\n          if (cls) classes.push(cls);\n        }\n      }\n    }\n    return cn(...classes, props.className);\n  };\n}\n",[],[330,331,323],"src","utils","a2c1e616-91ba-4d35-9f30-025145cf6b4a","cn.ts","019f632a-69d4-710e-80e2-a77aa45c734a",["D",1784075151835],"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  return twMerge(clsx(inputs));\n}\n",[],[330,331,333],"fffe5f38-8d2f-4040-a44f-697048265241","019f632a-69d4-710e-80e2-b2cc015d94f6",["D",1784075151835],[263,264],[330,331],"97eabf3a-275f-4cbd-bd37-69f8ef3623db","tw_test.ts","019f632a-69d4-710e-80e2-9d4d228a57d6","019f632a-69d4-710e-80e2-a33741cd7dfc",["D",1784075151835],"import { assertEquals } from \"jsr:@std/assert@1\";\nimport { tw } from \"./tw.ts\";\n\nDeno.test(\"spacing accessors emit bare arbitrary-value classes\", () => {\n  assertEquals(tw.space(\"4\"), \"p-[var(--kyla-space-4)]\");\n  assertEquals(tw.space(\"p\", \"4\"), \"p-[var(--kyla-space-4)]\");\n  assertEquals(tw.space(\"gap\", \"6\"), \"gap-[var(--kyla-space-6)]\");\n  assertEquals(tw.space(\"space-x\", \"2\"), \"space-x-[var(--kyla-space-2)]\");\n});\n\nDeno.test(\"radius accessors emit derived bare arbitrary-value classes\", () => {\n  assertEquals(tw.radius(\"sm\"), \"rounded-[var(--kyla-radius-sm)]\");\n  assertEquals(tw.radius(\"md\"), \"rounded-[var(--kyla-radius-md)]\");\n  assertEquals(tw.radius(\"lg\"), \"rounded-[var(--kyla-radius-lg)]\");\n  assertEquals(tw.radius(), \"rounded-[var(--kyla-radius-md)]\");\n});\n\nDeno.test(\"type accessors bundle size and line-height\", () => {\n  assertEquals(\n    tw.type(\"sm\"),\n    \"text-[length:var(--kyla-text-sm)] leading-[var(--kyla-text-sm-line-height)]\",\n  );\n  assertEquals(\n    tw.type(\"3xl\"),\n    \"text-[length:var(--kyla-text-3xl)] leading-[var(--kyla-text-3xl-line-height)]\",\n  );\n});\n\nDeno.test(\"weight accessors emit bare arbitrary-value classes\", () => {\n  assertEquals(\n    tw.weight(\"semibold\"),\n    \"font-[weight:var(--kyla-font-weight-semibold)]\",\n  );\n});\n\n// These calls intentionally verify that the accessor arguments are unions.\n// @ts-expect-error \"7\" is not one of the fixed spacing steps.\ntw.space(\"7\");\n// @ts-expect-error \"xl\" is not one of the graduated radius roles.\ntw.radius(\"xl\");\n// @ts-expect-error \"4xl\" is not one of the fixed type steps.\ntw.type(\"4xl\");\n// @ts-expect-error \"black\" is not one of the fixed font weights.\ntw.weight(\"black\");\n",[],[330,352,345],"theme","9aa72636-50a2-4b28-a557-4c6681394eca","tw.ts","019f632a-69d4-710e-80e2-990d6582e072",["D",1784075151835],"/**\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 */\nimport type {\n  COLOR_TOKENS,\n  FONT_WEIGHT_STEPS,\n  RADIUS_STEPS,\n  SPACE_STEPS,\n  TYPE_STEPS,\n} from \"./tokens.ts\";\n\nexport type ColorToken = (typeof COLOR_TOKENS)[number];\n\n/** Common interaction states a token utility may be scoped to. */\nexport type State = \"hover\" | \"focus\" | \"focus-visible\" | \"active\" | \"disabled\";\n\n/** Fixed spacing steps, each representing a multiple of the 4px base unit. */\nexport type SpaceToken = (typeof SPACE_STEPS)[number];\n\n/** The graduated radius roles derived from `--kyla-radius`. */\nexport type RadiusToken = (typeof RADIUS_STEPS)[number];\n\n/** Fixed type steps, each paired with its intended line-height. */\nexport type TypeToken = (typeof TYPE_STEPS)[number];\n\n/** Fixed font weights from the Val Town typography scale. */\nexport type FontWeightToken = (typeof FONT_WEIGHT_STEPS)[number];\n\n/**\n * Twind spacing utilities that consume a spacing token. Component dimensions\n * such as width and height are intentionally outside this accessor contract.\n */\nexport type SpaceProperty =\n  | \"p\"\n  | \"px\"\n  | \"py\"\n  | \"pt\"\n  | \"pr\"\n  | \"pb\"\n  | \"pl\"\n  | \"m\"\n  | \"mx\"\n  | \"my\"\n  | \"mt\"\n  | \"mr\"\n  | \"mb\"\n  | \"ml\"\n  | \"gap\"\n  | \"gap-x\"\n  | \"gap-y\"\n  | \"space-x\"\n  | \"space-y\";\n\nconst color = (prop: string, name: ColorToken, on?: State): string =>\n  `${on ? `${on}:` : \"\"}${prop}-[color:var(--kyla-${name})]`;\n\nconst length = (prop: string, family: string, name: string): string =>\n  `${prop}-[var(--kyla-${family}-${name})]`;\n\nconst typeScale = (step: TypeToken): string =>\n  [\n    // `text-*` is shared by color and font-size utilities, so the length hint\n    // makes the CSS variable's intended role explicit to Twind.\n    `text-[length:var(--kyla-text-${step})]`,\n    length(\"leading\", \"text\", `${step}-line-height`),\n  ].join(\" \");\n\nfunction space(step: SpaceToken): string;\nfunction space(prop: SpaceProperty, step: SpaceToken): string;\nfunction space(\n  propOrStep: SpaceProperty | SpaceToken,\n  step?: SpaceToken,\n): string {\n  const prop = step === undefined ? \"p\" : propOrStep as SpaceProperty;\n  const token = step ?? propOrStep as SpaceToken;\n  return length(prop, \"space\", token);\n}\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 * Length builders intentionally emit bare arbitrary-value classes: lengths\n * are unambiguous to Twind and do not need the color hint.\n */\nexport const tw = {\n  bg: (t: ColorToken, on?: State) => color(\"bg\", t, on),\n  text: (t: ColorToken, on?: State) => color(\"text\", t, on),\n  border: (t: ColorToken, on?: State) => color(\"border\", t, on),\n  ring: (t: ColorToken, on?: State) => color(\"ring\", t, on),\n  ringOffset: (t: ColorToken, on?: State) => color(\"ring-offset\", t, on),\n  /**\n   * Fixed spacing token. With one argument it emits padding for the token;\n   * pass a Twind spacing property first for other uses, e.g.\n   * `tw.space(\"gap\", \"4\")`.\n   */\n  space,\n  /** border-radius token (a length — no `color:` hint needed) */\n  radius: (t: RadiusToken = \"md\") => length(\"rounded\", \"radius\", t),\n  /** type token — always applies the paired size and line-height */\n  type: typeScale,\n  /** fixed font-weight token */\n  weight: (t: FontWeightToken) => `font-[weight:var(--kyla-font-weight-${t})]`,\n} as const;\n",[],[330,352,354],"3a8417f5-3861-4fc2-a462-5ef0f6a6de9b","tokens_test.ts","019f632a-69d4-710e-80e2-97622aca861d",["D",1784076371562],"/**\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, assertEquals } from \"jsr:@std/assert@1\";\nimport { contrastRatio } from \"./contrast.ts\";\nimport {\n  COLOR_TOKENS,\n  FONT_WEIGHT_STEPS,\n  RADIUS_STEPS,\n  SPACE_STEPS,\n  tokenCSS,\n  TYPE_STEPS,\n} from \"./tokens.ts\";\n\ntype Mode = \"light\" | \"dark\";\ntype Palette = Record<string, Record<Mode, string>>;\n\n/** Parse `--kyla-NAME: light-dark(<light>, <dark>);` declarations into a palette. */\nfunction parsePalette(css: string): Palette {\n  const re =\n    /--kyla-([\\w-]+):\\s*light-dark\$\\s*(#[0-9a-fA-F]{3,6})\\s*,\\s*(#[0-9a-fA-F]{3,6})\\s*\$/g;\n  const palette: Palette = {};\n  for (const [, name, light, dark] of css.matchAll(re)) {\n    palette[name] = { light, dark };\n  }\n  return 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, the status/accent *text* roles on every\n * surface, and ink on each colored fill. Anything not listed here is not a\n * 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  ...SURFACES.map((bg) => ({ fg: \"fg\", bg, min: AA_BODY })),\n  ...SURFACES.map((bg) => ({ fg: \"fg-muted\", bg, min: AA_BODY })),\n  ...SURFACES.map((bg) => ({ fg: \"accent-text\", bg, min: AA_BODY })),\n  ...SURFACES.map((bg) => ({ fg: \"danger-text\", bg, min: AA_BODY })),\n  { fg: \"accent-fg\", bg: \"accent\", min: AA_BODY },\n  { fg: \"danger-fg\", bg: \"danger\", min: AA_BODY },\n  { fg: \"success-fg\", bg: \"success\", min: AA_BODY },\n];\n\nDeno.test(\"contrastRatio returns the correct WCAG ratio for known pairs\", () => {\n  assertAlmostEquals(contrastRatio(\"#000000\", \"#ffffff\"), 21, 0.05);\n  assertAlmostEquals(contrastRatio(\"#ffffff\", \"#ffffff\"), 1, 0.001);\n  // #767676 on white is the canonical WCAG AA boundary example (~4.54:1).\n  assertAlmostEquals(contrastRatio(\"#767676\", \"#ffffff\"), 4.54, 0.05);\n  // Order-independent.\n  assertAlmostEquals(\n    contrastRatio(\"#052f4a\", \"#00bcff\"),\n    contrastRatio(\"#00bcff\", \"#052f4a\"),\n    0.001,\n  );\n});\n\nDeno.test(\"every sanctioned fg/surface pairing meets AA in both modes\", () => {\n  for (const mode of MODES) {\n    for (const { fg, bg, min } of PAIRINGS) {\n      assert(palette[fg], `missing token --kyla-${fg}`);\n      assert(palette[bg], `missing token --kyla-${bg}`);\n      const ratio = contrastRatio(palette[fg][mode], palette[bg][mode]);\n      assert(\n        ratio >= min,\n        `${fg} on ${bg} (${mode}) is ${ratio.toFixed(2)}:1, below AA ${min}:1`,\n      );\n    }\n  }\n});\n\nDeno.test(\"palette expands the color vocabulary with the new semantic tokens\", () => {\n  for (const name of COLOR_TOKENS) {\n    assert(palette[name], `expected --kyla-${name} in the token stylesheet`);\n  }\n});\n\nDeno.test(\"dark-mode base uses the sanctioned slate-950 softening, not true black\", () => {\n  assert(palette.base, \"missing --kyla-base\");\n  assertEqualsHex(palette.base.dark, \"#020618\");\n  assert(\n    palette.base.dark.toLowerCase() !== \"#000000\",\n    \"dark base must be softened slate-950, not true black\",\n  );\n});\n\nfunction assertEqualsHex(actual: string, expected: string): void {\n  assert(\n    actual.toLowerCase() === expected.toLowerCase(),\n    `expected ${expected}, got ${actual}`,\n  );\n}\n\ntype LengthScale = Record<string, number>;\n\nfunction parsePixelScale(css: string, family: string): LengthScale {\n  const scale: LengthScale = {};\n  const re = new RegExp(\n    `--kyla-${family}-([\\\\w-]+):\\\\s*([0-9]+)px\\\\s*;`,\n    \"g\",\n  );\n  for (const [, name, value] of css.matchAll(re)) {\n    scale[name] = Number(value);\n  }\n  return scale;\n}\n\nDeno.test(\"spacing scale is the fixed monotonic 4px-based step set\", () => {\n  const spacing = parsePixelScale(tokenCSS, \"space\");\n  assertEquals(Object.keys(spacing), [...SPACE_STEPS]);\n\n  let previous = -1;\n  for (const step of SPACE_STEPS) {\n    const value = spacing[step];\n    assert(value >= 0, `space-${step} must be non-negative`);\n    assert(value >= previous, `space-${step} must be monotonic`);\n    assertEquals(value, Number(step) * 4);\n    previous = value;\n  }\n});\n\nDeno.test(\"radius scale derives sm/md/lg from the overridable base\", () => {\n  assert(\n    /--kyla-radius:\\s*8px\\s*;/.test(tokenCSS),\n    \"expected an 8px overridable base radius\",\n  );\n\n  assertEquals(RADIUS_STEPS.length, 3);\n\n  const expectedDerivations: Record<(typeof RADIUS_STEPS)[number], string> = {\n    sm: \"calc(var(--kyla-radius) * 0.5)\",\n    md: \"var(--kyla-radius)\",\n    lg: \"calc(var(--kyla-radius) * 1.5)\",\n  };\n  for (const step of RADIUS_STEPS) {\n    assert(\n      tokenCSS.includes(\n        `--kyla-radius-${step}: ${expectedDerivations[step]};`,\n      ),\n      `radius-${step} must derive from --kyla-radius`,\n    );\n  }\n});\n\ntype TypeScale = Record<string, { size: number; lineHeight: string }>;\n\nfunction parseTypeScale(css: string): TypeScale {\n  const scale: TypeScale = {};\n  for (const step of TYPE_STEPS) {\n    const size = css.match(\n      new RegExp(`--kyla-text-${step}:\\\\s*([0-9.]+)rem\\\\s*;`),\n    );\n    const lineHeight = css.match(\n      new RegExp(`--kyla-text-${step}-line-height:\\\\s*([^;]+);`),\n    );\n    if (size && lineHeight) {\n      scale[step] = { size: Number(size[1]), lineHeight: lineHeight[1].trim() };\n    }\n  }\n  return scale;\n}\n\nDeno.test(\"type scale is the fixed monotonic VT size and line-height set\", () => {\n  const typeScale = parseTypeScale(tokenCSS);\n  assertEquals(Object.keys(typeScale), [...TYPE_STEPS]);\n\n  let previousSize = 0;\n  for (const step of TYPE_STEPS) {\n    const pair = typeScale[step];\n    assert(pair.size > previousSize, `text-${step} must be monotonic by size`);\n    assert(pair.lineHeight.length > 0, `text-${step} must have a line-height`);\n    previousSize = pair.size;\n  }\n});\n\nDeno.test(\"font and weight tokens expose the VT typography foundation\", () => {\n  assert(\n    tokenCSS.includes(\n      '--kyla-font: \"IBM Plex Sans\", -apple-system, sans-serif;',\n    ),\n    \"expected the overridable IBM Plex Sans font token\",\n  );\n\n  for (const [index, name] of FONT_WEIGHT_STEPS.entries()) {\n    const value = String(400 + index * 100);\n    assert(\n      tokenCSS.includes(`--kyla-font-weight-${name}: ${value};`),\n      `expected --kyla-font-weight-${name}`,\n    );\n  }\n});\n\nconst OVERRIDE_TOKENS = [\"accent\", \"radius\", \"font\"] as const;\n\nconst STRUCTURAL_TOKENS = [\n  // Semantic palette roles other than the overridable accent.\n  \"base\",\n  \"elevated\",\n  \"recessed\",\n  \"fg\",\n  \"fg-muted\",\n  \"line\",\n  \"hairline\",\n  \"accent-fg\",\n  \"accent-ring\",\n  \"accent-text\",\n  \"danger\",\n  \"danger-fg\",\n  \"danger-text\",\n  \"success\",\n  \"success-fg\",\n  // Direct radius derivations remain structural even though the base is not.\n  ...RADIUS_STEPS.map((step) => `radius-${step}`),\n  ...SPACE_STEPS.map((step) => `space-${step}`),\n  ...TYPE_STEPS.flatMap((step) => [\n    `text-${step}`,\n    `text-${step}-line-height`,\n  ]),\n  ...FONT_WEIGHT_STEPS.map((weight) => `font-weight-${weight}`),\n] as const;\n\nDeno.test(\"override surface and structural token names are all present\", () => {\n  for (const name of OVERRIDE_TOKENS) {\n    assert(\n      tokenCSS.includes(`--kyla-${name}:`),\n      `expected overridable token --kyla-${name}`,\n    );\n  }\n\n  for (const name of STRUCTURAL_TOKENS) {\n    assert(\n      tokenCSS.includes(`--kyla-${name}:`),\n      `expected structural token --kyla-${name}`,\n    );\n  }\n});\n",[],[330,352,361],"befa7636-c335-4a84-b715-af5e3314b551","tokens.ts","019f632a-69d4-710e-80e2-928d94afaf12",["D",1784076371562],"/**\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 * Structural scales: spacing is fixed as Kylä's supported consumer contract\n * on the Val Town/Tailwind 4px base unit. \"Fixed\" means these values are not\n * supported theme override inputs; because they are CSS custom properties, a\n * consumer can still redefine them at their own risk.\n * The radius scale is derived from the one consumer-overridable base so the\n * proportions remain intact when a consumer changes --kyla-radius. The\n * consumer override surface is exactly --kyla-accent, --kyla-radius, and\n * --kyla-font (plus the direct radius derivations). Every other token below —\n * surfaces, foregrounds, borders, status roles, spacing, type sizes/leading,\n * and font weights — is structural and outside the supported override surface.\n */\nexport const COLOR_TOKENS = [\n  \"base\",\n  \"elevated\",\n  \"recessed\",\n  \"fg\",\n  \"fg-muted\",\n  \"line\",\n  \"hairline\",\n  \"accent\",\n  \"accent-fg\",\n  \"accent-ring\",\n  \"accent-text\",\n  \"danger\",\n  \"danger-fg\",\n  \"danger-text\",\n  \"success\",\n  \"success-fg\",\n] as const;\n\nexport const SPACE_STEPS = [\n  \"0\",\n  \"1\",\n  \"2\",\n  \"3\",\n  \"4\",\n  \"5\",\n  \"6\",\n  \"8\",\n  \"10\",\n  \"12\",\n  \"16\",\n  \"20\",\n  \"24\",\n] as const;\n\nexport const RADIUS_STEPS = [\"sm\", \"md\", \"lg\"] as const;\n\nexport const TYPE_STEPS = [\n  \"xs\",\n  \"sm\",\n  \"base\",\n  \"lg\",\n  \"xl\",\n  \"2xl\",\n  \"3xl\",\n] as const;\n\nexport const FONT_WEIGHT_STEPS = [\n  \"normal\",\n  \"medium\",\n  \"semibold\",\n  \"bold\",\n  \"extrabold\",\n] as const;\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  /* consumer-overridable; all other palette roles are structural */\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  /*\n   * danger is a fill; danger-text is danger on a surface, the counterpart to\n   * accent-text. The fill is far too pale in light mode to double as text\n   * (rose-300 on white is 1.4:1), so the two roles cannot share one token.\n   */\n  --kyla-danger:      light-dark(#ffa1ad, #a50036);\n  --kyla-danger-fg:   light-dark(#4d0218, #ffffff);\n  --kyla-danger-text: light-dark(#a50036, #ffc9d4);\n  --kyla-success:     light-dark(#00d492, #007a55);\n  --kyla-success-fg:  light-dark(#002c22, #ffffff);\n\n  /*\n   * Typography — --kyla-font is consumer-overridable. The type sizes, their\n   * paired line-heights, and weights are structural so components share one\n   * hierarchy. Values are the VT style-guide scale (§4).\n   */\n  --kyla-font: \"IBM Plex Sans\", -apple-system, sans-serif;\n  --kyla-text-xs: 0.75rem;\n  --kyla-text-xs-line-height: 1rem;\n  --kyla-text-sm: 0.875rem;\n  --kyla-text-sm-line-height: 1.25rem;\n  --kyla-text-base: 1rem;\n  --kyla-text-base-line-height: 1.5rem;\n  --kyla-text-lg: 1.125rem;\n  --kyla-text-lg-line-height: 1.75rem;\n  --kyla-text-xl: 1.25rem;\n  --kyla-text-xl-line-height: 1.75rem;\n  --kyla-text-2xl: 1.5rem;\n  --kyla-text-2xl-line-height: 2rem;\n  --kyla-text-3xl: 1.875rem;\n  --kyla-text-3xl-line-height: 2.25rem;\n\n  --kyla-font-weight-normal: 400;\n  --kyla-font-weight-medium: 500;\n  --kyla-font-weight-semibold: 600;\n  --kyla-font-weight-bold: 700;\n  --kyla-font-weight-extrabold: 800;\n\n  /*\n   * Structural spacing — fixed supported contract on a 4px base, following the\n   * compact VT/Tailwind steps used by the component style guide. These are not\n   * supported theme overrides, though CSS custom properties remain mutable.\n   */\n  --kyla-space-0:  0px;\n  --kyla-space-1:  4px;\n  --kyla-space-2:  8px;\n  --kyla-space-3:  12px;\n  --kyla-space-4:  16px;\n  --kyla-space-5:  20px;\n  --kyla-space-6:  24px;\n  --kyla-space-8:  32px;\n  --kyla-space-10: 40px;\n  --kyla-space-12: 48px;\n  --kyla-space-16: 64px;\n  --kyla-space-20: 80px;\n  --kyla-space-24: 96px;\n\n  /*\n   * Shape — --kyla-radius is the one consumer-overridable base. The graduated\n   * values are direct derivations, so changing the base preserves\n   * the 4px / 8px / 12px proportions used by the VT style guide.\n   */\n  --kyla-radius:    8px;\n  --kyla-radius-sm: calc(var(--kyla-radius) * 0.5);\n  --kyla-radius-md: var(--kyla-radius);\n  --kyla-radius-lg: calc(var(--kyla-radius) * 1.5);\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 {\n  margin: 0;\n  font-family: var(--kyla-font);\n}\n`;\n",[],[330,352,368],"54e7f57a-a05b-4c7f-a3ce-61a09de9145b","provider.tsx","019f632a-69d4-710e-80e2-8e5dfad917e8",["D",1784075151835],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport {\n  createContext,\n  type ReactNode,\n  useContext,\n  useEffect,\n  useState,\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 <head> at runtime (idempotent). Twind itself\n *   must live in the HTML shell since it has to load before first paint (ADR-0001);\n *   the Provider injects tokens and the default IBM Plex Sans stylesheet.\n * - Owns Mode via `data-mode` on <html> 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  mode: \"system\",\n  setMode: () => {},\n});\n\nexport function useKylaMode() {\n  return useContext(ModeContext);\n}\n\nconst TOKENS_ID = \"kyla-tokens\";\nconst FONT_STYLESHEET_ID = \"kyla-font-stylesheet\";\nconst FONT_STYLESHEET_HREF =\n  \"https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700;800&display=swap\";\n\nexport function KylaProvider({\n  children,\n  defaultMode = \"system\",\n}: {\n  children: ReactNode;\n  defaultMode?: Mode;\n}) {\n  const [mode, setMode] = useState<Mode>(defaultMode);\n\n  // Inject the token stylesheet once. Idempotent: guards against double-inject.\n  useEffect(() => {\n    if (!document.getElementById(TOKENS_ID)) {\n      const style = document.createElement(\"style\");\n      style.id = TOKENS_ID;\n      style.textContent = tokenCSS;\n      document.head.appendChild(style);\n    }\n\n    if (!document.getElementById(FONT_STYLESHEET_ID)) {\n      const link = document.createElement(\"link\");\n      link.id = FONT_STYLESHEET_ID;\n      link.rel = \"stylesheet\";\n      link.href = FONT_STYLESHEET_HREF;\n      document.head.appendChild(link);\n    }\n  }, []);\n\n  // Reflect Mode onto the document so `data-mode` selectors take effect.\n  useEffect(() => {\n    document.documentElement.setAttribute(\"data-mode\", mode);\n  }, [mode]);\n\n  return (\n    <ModeContext.Provider value={{ mode, setMode }}>\n      {children}\n    </ModeContext.Provider>\n  );\n}\n",[],[330,352,375],"246b0c29-0d3a-4cb0-8981-9d6f02a4a7c9","contrast.ts","019f632a-69d4-710e-80e2-8991cede6c9d",["D",1784075151835],"/**\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  const h = hex.trim().replace(/^#/, \"\");\n  const full = h.length === 3\n    ? h\n      .split(\"\")\n      .map((c) => c + c)\n      .join(\"\")\n    : h;\n  if (!/^[0-9a-fA-F]{6}$/.test(full)) {\n    throw new Error(`Invalid hex color: ${hex}`);\n  }\n  return [\n    parseInt(full.slice(0, 2), 16),\n    parseInt(full.slice(2, 4), 16),\n    parseInt(full.slice(4, 6), 16),\n  ];\n}\n\n/** WCAG relative luminance of an sRGB color (0 = black, 1 = white). */\nexport function relativeLuminance([r, g, b]: RGB): number {\n  const linear = (channel: number): number => {\n    const s = channel / 255;\n    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;\n  };\n  return 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  const la = relativeLuminance(parseHex(a));\n  const lb = relativeLuminance(parseHex(b));\n  const lighter = Math.max(la, lb);\n  const darker = Math.min(la, lb);\n  return (lighter + 0.05) / (darker + 0.05);\n}\n",[],[330,352,382],"9fc9fbd9-8d33-4fdf-be13-df6567af6429",["D",1784075151835],[256,257,258,259,260,261],[330,352],"6a527f9a-af4a-4905-a1d9-a2081880b9af","render.ts","f8a7897e-7fe4-11f1-8217-1607ee4eb77e","f8537f78-7fe4-11f1-a5ab-1607ee4eb77e",["D",1784076371562],"/**\n * The render-to-HTML seam for component tests.\n *\n * Components are asserted through their *external* output — the semantic element\n * they emit, the token classes they carry, and their accessibility wiring — never\n * through their internal `variants()`/`cn()` calls. Server-rendering to a string\n * is the highest seam that still sees all of that, and it is uniform across the\n * whole component set.\n *\n * Asserting the emitted class string also guards ADR-0001's silent Twind failure:\n * a token utility that loses its `color:`/`length:` hint emits no CSS at all, which\n * surfaces here as an absent class rather than as an invisible styling bug.\n */\nimport type { ReactNode } from \"https://esm.sh/react@18.2.0\";\nimport { renderToStaticMarkup as render } from \"https://esm.sh/react-dom@18.2.0/server?deps=react@18.2.0&no-dts\";\n\n/**\n * Render an element to a static HTML string.\n *\n * The runtime import is `no-dts` (react-dom/server ships types Deno can't resolve\n * over esm.sh), so the signature is restored by annotation at this one boundary\n * instead of at every call site.\n */\nexport const renderToStaticMarkup: (element: ReactNode) => string = render;\n",[],[330,400,393],"testing","3740eb2e-fdce-4b2f-a913-f85b2b0a1ae0",["D",1784075682034],[254],[330,400],"bc23a988-2544-44fe-88f4-ce939daf4f4f","text_test.ts","f867b3da-7fe4-11f1-a5ab-1607ee4eb77e","019f632a-69d4-710e-80e2-8704f8ef7051",["D",1784076371562],"import {\n  assert,\n  assertMatch,\n  assertNotMatch,\n  assertStringIncludes,\n} from \"jsr:@std/assert@1\";\nimport { createElement } from \"https://esm.sh/react@18.2.0\";\nimport { FONT_WEIGHT_STEPS, TYPE_STEPS } from \"../theme/tokens.ts\";\nimport { renderToStaticMarkup } from \"../testing/render.ts\";\nimport { Heading, Text, type TextTone } from \"./text.tsx\";\n\nDeno.test(\"Text renders a paragraph by default and honors the polymorphic `as`\", () => {\n  assertMatch(renderToStaticMarkup(createElement(Text, null, \"Body\")), /^<p /);\n  assertMatch(\n    renderToStaticMarkup(createElement(Text, { as: \"span\" }, \"Inline\")),\n    /^<span /,\n  );\n});\n\nDeno.test(\"Text maps size to the paired type-scale size and line-height tokens\", () => {\n  const html = renderToStaticMarkup(\n    createElement(Text, { size: \"lg\" }, \"Body\"),\n  );\n\n  assertStringIncludes(html, \"text-[length:var(--kyla-text-lg)]\");\n  assertStringIncludes(html, \"leading-[var(--kyla-text-lg-line-height)]\");\n});\n\nDeno.test(\"Text maps weight to a font-weight token\", () => {\n  assertStringIncludes(\n    renderToStaticMarkup(createElement(Text, { weight: \"bold\" }, \"Body\")),\n    \"font-[weight:var(--kyla-font-weight-bold)]\",\n  );\n});\n\nDeno.test(\"Text covers every step of the type and weight scales\", () => {\n  // The props' unions derive from these constants, so a step added to a scale\n  // without a matching variant entry would type-check and then emit nothing at\n  // all — `variants()` skips an unknown key silently.\n  for (const size of TYPE_STEPS) {\n    assertStringIncludes(\n      renderToStaticMarkup(createElement(Text, { size }, \"Body\")),\n      `text-[length:var(--kyla-text-${size})]`,\n    );\n  }\n\n  for (const weight of FONT_WEIGHT_STEPS) {\n    assertStringIncludes(\n      renderToStaticMarkup(createElement(Text, { weight }, \"Body\")),\n      `font-[weight:var(--kyla-font-weight-${weight})]`,\n    );\n  }\n});\n\nDeno.test(\"Text tones resolve to the text-on-surface color tokens\", () => {\n  const toneToken: Record<TextTone, string> = {\n    \"fg\": \"fg\",\n    \"fg-muted\": \"fg-muted\",\n    // `accent`/`danger` are *fill* tokens; text tones must use the AA-verified\n    // text-on-surface roles instead, or they render unreadably on a surface.\n    \"accent\": \"accent-text\",\n    \"danger\": \"danger-text\",\n  };\n\n  for (\n    const [tone, token] of Object.entries(toneToken) as [TextTone, string][]\n  ) {\n    assertStringIncludes(\n      renderToStaticMarkup(createElement(Text, { tone }, \"Body\")),\n      `text-[color:var(--kyla-${token})]`,\n    );\n  }\n});\n\nDeno.test(\"Text emits its size and its tone together\", () => {\n  // `text-*` is shared by font-size and color utilities. Without the\n  // `length:`/`color:` hints (ADR-0001) twMerge would treat these as conflicting\n  // and silently drop one, so assert both survive the same render.\n  const html = renderToStaticMarkup(\n    createElement(Text, { size: \"sm\", tone: \"fg-muted\" }, \"Body\"),\n  );\n\n  assertStringIncludes(html, \"text-[length:var(--kyla-text-sm)]\");\n  assertStringIncludes(html, \"text-[color:var(--kyla-fg-muted)]\");\n});\n\nDeno.test(\"Text className wins over the component's own conflicting tone\", () => {\n  const html = renderToStaticMarkup(\n    createElement(\n      Text,\n      { tone: \"fg\", className: \"text-[color:var(--kyla-accent-text)]\" },\n      \"Body\",\n    ),\n  );\n\n  assertStringIncludes(html, \"text-[color:var(--kyla-accent-text)]\");\n  assertNotMatch(html, /text-\\[color:var\$--kyla-fg\$\\]/);\n});\n\nDeno.test(\"Text forwards rest props to the underlying element\", () => {\n  const html = renderToStaticMarkup(\n    createElement(Text, { id: \"intro\", \"data-testid\": \"t\" }, \"Body\"),\n  );\n\n  assertStringIncludes(html, 'id=\"intro\"');\n  assertStringIncludes(html, 'data-testid=\"t\"');\n});\n\nDeno.test(\"Heading renders the heading tag for its level\", () => {\n  for (const level of [1, 2, 3, 4, 5, 6] as const) {\n    assertMatch(\n      renderToStaticMarkup(createElement(Heading, { level }, \"Title\")),\n      new RegExp(`^<h${level} `),\n    );\n  }\n});\n\nDeno.test(\"Heading defaults to h2\", () => {\n  assertMatch(\n    renderToStaticMarkup(createElement(Heading, null, \"Title\")),\n    /^<h2 /,\n  );\n});\n\nDeno.test(\"Heading sizes descend with its level and stay on the type scale\", () => {\n  const sizes = ([1, 2, 3, 4, 5, 6] as const).map((level) => {\n    const html = renderToStaticMarkup(\n      createElement(Heading, { level }, \"Title\"),\n    );\n    const match = html.match(/text-\\[length:var\$--kyla-text-([\\w-]+)\$\\]/);\n    assert(match, `h${level} emitted no type-scale size`);\n    return match[1];\n  });\n\n  assert(\n    new Set(sizes).size === sizes.length,\n    `each level needs its own step, got ${sizes.join(\", \")}`,\n  );\n  assertStringIncludes(sizes[0], \"3xl\");\n});\n\nDeno.test(\"Heading is semibold by default and lets an explicit weight win\", () => {\n  assertStringIncludes(\n    renderToStaticMarkup(createElement(Heading, null, \"Title\")),\n    \"font-[weight:var(--kyla-font-weight-semibold)]\",\n  );\n  assertStringIncludes(\n    renderToStaticMarkup(\n      createElement(Heading, { weight: \"normal\" }, \"Title\"),\n    ),\n    \"font-[weight:var(--kyla-font-weight-normal)]\",\n  );\n});\n\nDeno.test(\"Heading keeps its semantic level when size is overridden\", () => {\n  // A small h1 is still an h1 — styling must not rewrite the document outline.\n  const html = renderToStaticMarkup(\n    createElement(Heading, { level: 1, size: \"base\" }, \"Title\"),\n  );\n\n  assertMatch(html, /^<h1 /);\n  assertStringIncludes(html, \"text-[length:var(--kyla-text-base)]\");\n  assertNotMatch(html, /text-\\[length:var\$--kyla-text-3xl\$\\]/);\n});\n",[],[330,413,406],"components","c5120315-35c1-4858-b74d-ea1e0ff942e7","text.tsx","f88da5f4-7fe4-11f1-a374-1607ee4eb77e",["D",1784076371562],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport {\n  type ComponentPropsWithoutRef,\n  type ElementType,\n  forwardRef,\n  type ReactElement,\n  type Ref,\n} from \"https://esm.sh/react@18.2.0\";\nimport { FONT_WEIGHT_STEPS, TYPE_STEPS } from \"../theme/tokens.ts\";\nimport { type FontWeightToken, tw, type TypeToken } from \"../theme/tw.ts\";\nimport { variants } from \"../utils/variants.ts\";\n\n/**\n * Text / Heading — typed typography, authored on the `Button` pattern: typed\n * variant props mapped to token classes via `variants()`, a semantic element,\n * forwarded ref + rest props, and an escape-hatch `className` merged last.\n *\n * Sizes are type-scale steps and tones are palette roles, so body copy stays on\n * the scale without a consumer ever choosing a raw `text-*` class.\n */\n\n/**\n * Text tones are text-*on a surface*, so they resolve to the AA-verified\n * text roles — `accent-text`/`danger-text` — not to the `accent`/`danger`\n * *fills*, which are far too pale in light mode to read as text.\n */\nexport type TextTone = \"fg\" | \"fg-muted\" | \"accent\" | \"danger\";\n\n/**\n * Build a variant map covering *every* step of a scale.\n *\n * Deriving the keys from the scale constant is what keeps the map honest: a step\n * added to `TYPE_STEPS` widens the prop's union and lands here in the same move.\n * A hand-written map would let the union grow past the map, and `variants()`\n * skips a missing key silently — the class-absent failure ADR-0001 warns about.\n */\nconst perStep = <T extends string>(\n  steps: readonly T[],\n  toClass: (step: T) => string,\n): Record<T, string> =>\n  Object.fromEntries(steps.map((step) => [step, toClass(step)])) as Record<\n    T,\n    string\n  >;\n\nconst textClasses = variants({\n  variants: {\n    size: perStep(TYPE_STEPS, tw.type),\n    weight: perStep(FONT_WEIGHT_STEPS, tw.weight),\n    tone: {\n      \"fg\": tw.text(\"fg\"),\n      \"fg-muted\": tw.text(\"fg-muted\"),\n      \"accent\": tw.text(\"accent-text\"),\n      \"danger\": tw.text(\"danger-text\"),\n    },\n  },\n  defaultVariants: { size: \"base\", weight: \"normal\", tone: \"fg\" },\n});\n\ntype TextOwnProps = {\n  size?: TypeToken;\n  weight?: FontWeightToken;\n  tone?: TextTone;\n  className?: string;\n};\n\nexport type TextProps<T extends ElementType = \"p\"> =\n  & { as?: T }\n  & TextOwnProps\n  & Omit<ComponentPropsWithoutRef<T>, keyof TextOwnProps | \"as\">;\n\n/** A polymorphic component keeps `as`'s element type flowing into its rest props. */\ntype PolymorphicText = <T extends ElementType = \"p\">(\n  props: TextProps<T> & { ref?: Ref<Element> },\n) => ReactElement;\n\nconst TextImpl = forwardRef(\n  (\n    { as, size, weight, tone, className, ...rest }: TextProps,\n    ref: Ref<Element>,\n  ) => {\n    const Component = (as ?? \"p\") as ElementType;\n    return (\n      <Component\n        ref={ref}\n        className={textClasses({ size, weight, tone, className })}\n        {...rest}\n      />\n    );\n  },\n);\nTextImpl.displayName = \"Text\";\n\nexport const Text = TextImpl as PolymorphicText;\n\n/** Heading levels, each mapping to its own semantic tag. */\nexport type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;\n\n/**\n * Each level's default step on the type scale. `level` drives the *semantics*;\n * `size` is a separate prop so a consumer can down-size an `h1` without\n * demoting it in the document outline.\n */\nconst LEVEL_SIZE: Record<HeadingLevel, TypeToken> = {\n  1: \"3xl\",\n  2: \"2xl\",\n  3: \"xl\",\n  4: \"lg\",\n  5: \"base\",\n  6: \"sm\",\n};\n\nexport type HeadingProps<T extends ElementType = \"h2\"> =\n  & { level?: HeadingLevel }\n  & TextProps<T>;\n\ntype PolymorphicHeading = <T extends ElementType = \"h2\">(\n  props: HeadingProps<T> & { ref?: Ref<Element> },\n) => ReactElement;\n\nconst HeadingImpl = forwardRef(\n  (\n    { level = 2, as, size, weight, ...rest }: HeadingProps,\n    ref: Ref<Element>,\n  ) => (\n    <Text\n      ref={ref}\n      as={as ?? `h${level}`}\n      size={size ?? LEVEL_SIZE[level]}\n      weight={weight ?? \"semibold\"}\n      {...rest}\n    />\n  ),\n);\nHeadingImpl.displayName = \"Heading\";\n\nexport const Heading = HeadingImpl as PolymorphicHeading;\n",[],[330,413,415],"facb4c9a-c5c8-4b7a-841b-6380d61bda2e","button_test.ts","019f632a-69d4-710e-80e2-820ce5cba237",["D",1784076371562],"import { assertStringIncludes } from \"jsr:@std/assert@1\";\nimport { createElement } from \"https://esm.sh/react@18.2.0\";\nimport { renderToStaticMarkup } from \"../testing/render.ts\";\nimport { Button } from \"./button.tsx\";\n\nDeno.test(\"Button uses the accent-ring token for its visible focus ring\", () => {\n  const html = renderToStaticMarkup(createElement(Button, null, \"Save\"));\n\n  assertStringIncludes(\n    html,\n    \"focus-visible:ring-[color:var(--kyla-accent-ring)]\",\n  );\n});\n\nDeno.test(\"danger Button uses the danger foreground token\", () => {\n  const html = renderToStaticMarkup(\n    createElement(Button, { variant: \"danger\" }, \"Delete\"),\n  );\n\n  assertStringIncludes(\n    html,\n    \"text-[color:var(--kyla-danger-fg)]\",\n  );\n});\n\nDeno.test(\"Button markup consumes structural spacing tokens\", () => {\n  const html = renderToStaticMarkup(\n    createElement(Button, { size: \"lg\" }, \"Continue\"),\n  );\n\n  assertStringIncludes(html, \"gap-[var(--kyla-space-2)]\");\n  assertStringIncludes(html, \"px-[var(--kyla-space-6)]\");\n  // Fixed control heights are component dimensions, outside the spacing scale.\n  assertStringIncludes(html, \"h-11\");\n});\n",[],[330,413,422],"bb44445f-22f5-4035-9da3-31d1834285b6","button.tsx","019f632a-69d4-710e-80e2-7c6e7076c93d",["D",1784075151835],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport {\n  type ButtonHTMLAttributes,\n  forwardRef,\n} 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 `<button>`, forwarded ref + rest props, a token-based\n * visible focus ring, and an escape-hatch `className` that wins (ADR-0003's\n * accessibility baseline + the variant API from the design sketch).\n */\nconst buttonClasses = variants({\n  base: cn(\n    tw.radius(\"md\"),\n    tw.weight(\"medium\"),\n    \"inline-flex items-center justify-center transition\",\n    tw.space(\"gap\", \"2\"),\n    // visible focus ring, token-based (ADR-0003)\n    \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2\",\n    tw.ring(\"accent-ring\", \"focus-visible\"),\n    tw.ringOffset(\"base\", \"focus-visible\"),\n    // disabled state\n    \"disabled:opacity-50 disabled:pointer-events-none\",\n  ),\n  variants: {\n    variant: {\n      primary: cn(tw.bg(\"accent\"), tw.text(\"accent-fg\"), \"hover:opacity-90\"),\n      subtle: cn(\n        tw.bg(\"elevated\"),\n        tw.text(\"fg\"),\n        \"border\",\n        tw.border(\"line\"),\n        tw.bg(\"recessed\", \"hover\"),\n      ),\n      ghost: cn(tw.text(\"fg\"), tw.bg(\"recessed\", \"hover\")),\n      danger: cn(tw.bg(\"danger\"), tw.text(\"danger-fg\"), \"hover:opacity-90\"),\n    },\n    size: {\n      // Heights are component dimensions, not spacing. The structural spacing\n      // contract covers padding/gaps, so only the horizontal padding is tokenized.\n      sm: cn(\"h-8\", tw.space(\"px\", \"3\"), tw.type(\"sm\")),\n      md: cn(\"h-10\", tw.space(\"px\", \"4\"), tw.type(\"sm\")),\n      lg: cn(\"h-11\", tw.space(\"px\", \"6\"), tw.type(\"base\")),\n    },\n  },\n  defaultVariants: { variant: \"primary\", size: \"md\" },\n});\n\nexport type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {\n  variant?: \"primary\" | \"subtle\" | \"ghost\" | \"danger\";\n  size?: \"sm\" | \"md\" | \"lg\";\n};\n\nexport const Button = forwardRef<HTMLButtonElement, ButtonProps>(\n  ({ variant, size, className, type, ...rest }, ref) => (\n    <button\n      ref={ref}\n      // default to type=\"button\" so a Button in a form doesn't submit by accident\n      type={type ?? \"button\"}\n      className={buttonClasses({ variant, size, className })}\n      {...rest}\n    />\n  ),\n);\nButton.displayName = \"Button\";\n",[],[330,413,429],"d3cc275d-2368-4f9a-8439-4fc2a5425be1",["D",1784075151835],[249,250,251,252],[330,413],"e2639dbb-fc64-4d90-acce-a76ddd05832a",["D",1784075151835],[248,253,255,262],[330],"5a2c7c5d-6b91-4931-872f-d4141ca62661","index.tsx","019f632a-69d4-710e-80e2-75ec2fc475f9","019f632a-69d4-710e-80e2-79a562548746",["D",1784075151835],"http","/**\n * Kylä UI — preview endpoint (WORK IN PROGRESS).\n *\n * A client-rendered showcase of the current component set. This is a *preview*\n * only: it imports the real library from src/ and does NOT modify anything about\n * the library itself. As more components land, add them to preview/app.tsx.\n *\n * Val Town has no build step, so we serve an HTML shell that loads Twind (required\n * before first paint — see ADR-0001) and then boots the React app. The client\n * entry (and everything it imports) is served transpiled-to-JS via serveFile.\n */\nimport { parseVal, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\n\nconst html = `<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>Kylä UI — component preview (WIP)</title>\n    \n    <script src=\"https://cdn.twind.style\" crossorigin></script>\n    \n    <script src=\"https://esm.town/v/std/catch\"></script>\n    \n    <script type=\"importmap\">\n      {\n        \"imports\": {\n          \"npm:clsx@2.1.1\": \"https://esm.sh/clsx@2.1.1\",\n          \"npm:tailwind-merge@3.6.0\": \"https://esm.sh/tailwind-merge@3.6.0\"\n        }\n      }\n    </script>\n    <style>\n      html, body { margin: 0; min-height: 100%; }\n      #root:empty::before {\n        content: \"Loading preview…\";\n        display: block;\n        padding: 3rem;\n        font: 14px/1.5 var(--kyla-font, ui-sans-serif), system-ui, sans-serif;\n        color: #71717a;\n      }\n    </style>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/preview/client.tsx\"></script>\n  </body>\n</html>`;\n\nexport default function (req: Request): Promise<Response> | Response {\n  const { pathname } = new URL(req.url);\n\n  // view-source link → redirect to this val\n  if (pathname === \"/source\") {\n    return new Response(null, {\n      status: 302,\n      headers: { Location: parseVal().links.self.val },\n    });\n  }\n\n  // serve any val file (transpiled to JS for .ts/.tsx) so the browser can run\n  // the client bundle and its relative imports (./app.tsx, ../mod.ts, ...).\n  if (pathname.endsWith(\".ts\") || pathname.endsWith(\".tsx\")) {\n    return serveFile(pathname, import.meta.url);\n  }\n\n  return new Response(html, {\n    headers: { \"content-type\": \"text/html; charset=utf-8\" },\n  });\n}\n",[],[452,444],"preview","1f6f5113-5d5c-4414-8c31-22b09c724e2c","client.tsx","019f632a-69d4-710e-80e2-706eba6b3324",["D",1784075151835],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client\";\nimport { Preview } from \"./app.tsx\";\n\nconst root = document.getElementById(\"root\")!;\ncreateRoot(root).render(<Preview />);\n",[],[452,454],"45e0b33e-c9bc-4020-b63f-fc16d05cf07c","app.tsx","019f632a-69d4-710e-80e2-6cf1e8c8d284",["D",1784076371562],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport type { ReactNode } from \"https://esm.sh/react@18.2.0\";\n\n// The real library — imported, never modified.\nimport {\n  Button,\n  cn,\n  Heading,\n  KylaProvider,\n  Text,\n  type TextTone,\n  tw,\n  useKylaMode,\n} from \"../mod.ts\";\nimport {\n  COLOR_TOKENS,\n  FONT_WEIGHT_STEPS,\n  RADIUS_STEPS,\n  SPACE_STEPS,\n  TYPE_STEPS,\n} from \"../src/theme/tokens.ts\";\nimport type { Mode } from \"../src/theme/provider.tsx\";\n\nconst VARIANTS = [\"primary\", \"subtle\", \"ghost\", \"danger\"] as const;\nconst SIZES = [\"sm\", \"md\", \"lg\"] as const;\nconst HEADING_LEVELS = [1, 2, 3, 4, 5, 6] as const;\nconst TONES: TextTone[] = [\"fg\", \"fg-muted\", \"accent\", \"danger\"];\n\n/** A titled section on an elevated card. */\nfunction Section({\n  title,\n  subtitle,\n  children,\n}: {\n  title: string;\n  subtitle?: string;\n  children: ReactNode;\n}) {\n  return (\n    <section\n      className={cn(\n        tw.bg(\"elevated\"),\n        tw.border(\"line\"),\n        tw.radius(\"md\"),\n        \"border p-6\",\n      )}\n    >\n      <h2 className={cn(tw.text(\"fg\"), \"text-lg font-semibold m-0\")}>\n        {title}\n      </h2>\n      {subtitle && (\n        <p className={cn(tw.text(\"fg-muted\"), \"text-sm mt-1 mb-0\")}>\n          {subtitle}\n        </p>\n      )}\n      <div className=\"mt-5\">{children}</div>\n    </section>\n  );\n}\n\n/** Small monospace label. */\nfunction Tag({ children }: { children: ReactNode }) {\n  return (\n    <code\n      className={cn(\n        tw.bg(\"recessed\"),\n        tw.text(\"fg-muted\"),\n        \"text-xs px-1.5 py-0.5 rounded\",\n      )}\n    >\n      {children}\n    </code>\n  );\n}\n\n/** Light / dark / system switcher, driven by the library's own mode hook. */\nfunction ModeSwitcher() {\n  const { mode, setMode } = useKylaMode();\n  const modes: Mode[] = [\"light\", \"dark\", \"system\"];\n  return (\n    <div className=\"inline-flex items-center gap-2\">\n      <span className={cn(tw.text(\"fg-muted\"), \"text-sm\")}>Mode</span>\n      <div\n        className={cn(\n          tw.bg(\"recessed\"),\n          tw.border(\"line\"),\n          \"inline-flex gap-1 rounded-lg border p-1\",\n        )}\n      >\n        {modes.map((m) => (\n          <button\n            key={m}\n            type=\"button\"\n            onClick={() => setMode(m)}\n            className={cn(\n              \"rounded-md px-3 py-1 text-sm font-medium capitalize transition\",\n              m === mode\n                ? cn(tw.bg(\"accent\"), tw.text(\"accent-fg\"))\n                : cn(tw.text(\"fg\"), tw.bg(\"elevated\", \"hover\")),\n            )}\n          >\n            {m}\n          </button>\n        ))}\n      </div>\n    </div>\n  );\n}\n\nfunction ButtonMatrix() {\n  return (\n    <div className=\"flex flex-col gap-6\">\n      {/* variants × sizes */}\n      {VARIANTS.map((variant) => (\n        <div key={variant} className=\"flex flex-col gap-2\">\n          <div className=\"flex items-center gap-2\">\n            <span\n              className={cn(tw.text(\"fg\"), \"text-sm font-medium capitalize\")}\n            >\n              {variant}\n            </span>\n            <Tag>variant=\"{variant}\"</Tag>\n          </div>\n          <div className=\"flex flex-wrap items-center gap-3\">\n            {SIZES.map((size) => (\n              <Button key={size} variant={variant} size={size}>\n                {variant} {size}\n              </Button>\n            ))}\n            <Button variant={variant} disabled>\n              disabled\n            </Button>\n          </div>\n        </div>\n      ))}\n    </div>\n  );\n}\n\n/** A labelled row inside a matrix: what it is, and the prop that produced it. */\nfunction Row({\n  label,\n  children,\n}: {\n  label: ReactNode;\n  children: ReactNode;\n}) {\n  return (\n    <div className=\"flex flex-col gap-2\">\n      <Tag>{label}</Tag>\n      {children}\n    </div>\n  );\n}\n\nfunction HeadingMatrix() {\n  return (\n    <div className=\"flex flex-col gap-4\">\n      {HEADING_LEVELS.map((level) => (\n        <Row key={level} label={`level={${level}}`}>\n          <Heading level={level}>Heading level {level}</Heading>\n        </Row>\n      ))}\n    </div>\n  );\n}\n\nfunction TextMatrix() {\n  return (\n    <div className=\"flex flex-col gap-6\">\n      <Row label=\"size\">\n        <div className=\"flex flex-col gap-2\">\n          {TYPE_STEPS.map((size) => (\n            <Text key={size} size={size}>\n              {size} — the quick brown fox jumps over the lazy dog\n            </Text>\n          ))}\n        </div>\n      </Row>\n\n      <Row label=\"weight\">\n        <div className=\"flex flex-col gap-2\">\n          {FONT_WEIGHT_STEPS.map((weight) => (\n            <Text key={weight} weight={weight}>\n              {weight} — the quick brown fox jumps over the lazy dog\n            </Text>\n          ))}\n        </div>\n      </Row>\n\n      <Row label=\"tone\">\n        <div className=\"flex flex-col gap-2\">\n          {TONES.map((tone) => (\n            <Text key={tone} tone={tone}>\n              {tone} — the quick brown fox jumps over the lazy dog\n            </Text>\n          ))}\n        </div>\n      </Row>\n    </div>\n  );\n}\n\nfunction TokenSwatches() {\n  return (\n    <div className=\"grid grid-cols-2 sm:grid-cols-3 md:grid-cols-5 gap-3\">\n      {COLOR_TOKENS.map((token) => (\n        <div\n          key={token}\n          className={cn(\n            tw.border(\"line\"),\n            tw.radius(\"md\"),\n            \"border overflow-hidden\",\n          )}\n        >\n          <div\n            className={cn(tw.bg(token), \"h-12 w-full\")}\n            style={{ borderBottom: \"1px solid var(--kyla-hairline)\" }}\n          />\n          <div className={cn(tw.bg(\"elevated\"), \"px-2 py-1.5\")}>\n            <div className={cn(tw.text(\"fg\"), \"text-xs font-medium\")}>\n              {token}\n            </div>\n            <div className={cn(tw.text(\"fg-muted\"), \"text-[10px]\")}>\n              --kyla-{token}\n            </div>\n          </div>\n        </div>\n      ))}\n    </div>\n  );\n}\n\nfunction StructuralScaleSummary() {\n  return (\n    <div className={cn(tw.text(\"fg-muted\"), tw.space(\"mt\", \"4\"))}>\n      <p className=\"m-0\">\n        <strong className={cn(tw.text(\"fg\"), tw.weight(\"medium\"))}>\n          Structural scales\n        </strong>\n      </p>\n      <p className={cn(tw.type(\"sm\"), tw.space(\"mt\", \"1\"), \"mb-0\")}>\n        Spacing: {SPACE_STEPS.join(\", \")} (4px base) · Radius:{\" \"}\n        {RADIUS_STEPS.join(\", \")} (8px base) · Type: {TYPE_STEPS.join(\", \")}\n      </p>\n    </div>\n  );\n}\n\nfunction WipBanner() {\n  return (\n    <div\n      className={cn(\n        tw.border(\"accent\"),\n        tw.radius(\"md\"),\n        \"border border-dashed px-4 py-3\",\n      )}\n      style={{\n        background:\n          \"color-mix(in srgb, var(--kyla-accent) 10%, var(--kyla-elevated))\",\n      }}\n    >\n      <p className={cn(tw.text(\"fg\"), \"text-sm m-0\")}>\n        🚧 <strong>Preview / work in progress.</strong> This page renders the\n        {\" \"}\n        <em>current</em>{\" \"}\n        Kylä UI surface — Text, Heading, and Button, plus the shipped theme,\n        AA-checked palette, and structural scales. More components are on the\n        way.\n      </p>\n    </div>\n  );\n}\n\nexport function Preview() {\n  return (\n    <KylaProvider defaultMode=\"system\">\n      <main\n        className={cn(tw.bg(\"base\"), tw.text(\"fg\"), \"min-h-screen\")}\n      >\n        <div className=\"mx-auto max-w-4xl px-6 py-10 flex flex-col gap-8\">\n          {/* header */}\n          <header className=\"flex flex-wrap items-start justify-between gap-4\">\n            <div>\n              <h1 className={cn(tw.text(\"fg\"), \"text-3xl font-bold m-0\")}>\n                Kylä UI\n              </h1>\n              <p className={cn(tw.text(\"fg-muted\"), \"mt-1 mb-0\")}>\n                Consistently styled components for Val Town apps. (Kylä ·\n                Finnish for “village”.)\n              </p>\n            </div>\n            <ModeSwitcher />\n          </header>\n\n          <WipBanner />\n\n          <Section\n            title=\"Heading\"\n            subtitle=\"level drives the semantic tag (h1–h6) and its default step on the type scale. size is a separate prop, so a heading can be re-sized without being demoted in the document outline.\"\n          >\n            <HeadingMatrix />\n          </Section>\n\n          <Section\n            title=\"Text\"\n            subtitle=\"Typed size / weight / tone, all drawn from the type scale and palette — no raw text-* classes at the call site.\"\n          >\n            <TextMatrix />\n          </Section>\n\n          <Section\n            title=\"Button\"\n            subtitle=\"4 variants × 3 sizes, plus the disabled state.\"\n          >\n            <ButtonMatrix />\n          </Section>\n\n          <Section\n            title=\"Interactive\"\n            subtitle=\"Buttons carry a token-based visible focus ring — tab to them, or click.\"\n          >\n            <div className=\"flex flex-wrap gap-3\">\n              <Button\n                variant=\"primary\"\n                onClick={() => alert(\"Saved! (from Kylä Button)\")}\n              >\n                Save\n              </Button>\n              <Button variant=\"subtle\">Cancel</Button>\n              <Button variant=\"ghost\">Learn more</Button>\n              <Button variant=\"danger\">Delete</Button>\n            </div>\n          </Section>\n\n          <Section\n            title=\"Design tokens\"\n            subtitle=\"Semantic CSS variables the whole system is built on. Toggle mode above to watch them flip via light-dark().\"\n          >\n            <TokenSwatches />\n            <StructuralScaleSummary />\n          </Section>\n\n          <Section\n            title=\"Roadmap\"\n            subtitle=\"What's built today vs. what the v1 sketch still calls for.\"\n          >\n            <div className=\"grid sm:grid-cols-2 gap-6 text-sm\">\n              <div>\n                <div className={cn(tw.text(\"fg\"), \"font-medium mb-2\")}>\n                  ✅ In place\n                </div>\n                <ul className={cn(tw.text(\"fg-muted\"), \"m-0 pl-5 space-y-1\")}>\n                  <li>Styling core — cn / tw / variants</li>\n                  <li>KylaProvider + light / dark / system mode</li>\n                  <li>Semantic design tokens</li>\n                  <li>Real AA-checked palette</li>\n                  <li>Spacing / radius / type scales</li>\n                  <li>Button</li>\n                  <li>Text / Heading</li>\n                </ul>\n              </div>\n              <div>\n                <div className={cn(tw.text(\"fg\"), \"font-medium mb-2\")}>\n                  🔜 To come\n                </div>\n                <ul className={cn(tw.text(\"fg-muted\"), \"m-0 pl-5 space-y-1\")}>\n                  <li>The rest of the v1 component set</li>\n                  <li>Radix-backed components (e.g. Dialog)</li>\n                </ul>\n              </div>\n            </div>\n          </Section>\n\n          <footer\n            className={cn(\n              tw.text(\"fg-muted\"),\n              tw.border(\"hairline\"),\n              \"border-t pt-6 text-sm flex items-center justify-between\",\n            )}\n          >\n            <span>Preview is illustrative — not a stable API.</span>\n            <a href=\"/source\" className={cn(tw.text(\"accent\"), \"underline\")}>\n              view source\n            </a>\n          </footer>\n        </div>\n      </main>\n    </KylaProvider>\n  );\n}\n",[],[452,461],"a3b8a0b2-a446-4a31-b799-bdfde868c81b",["D",1784075151835],[244,245,246],[452],"f983eb2f-7f41-4cf9-a578-6c2de85ebce4","roadmap.md","019f632a-69d4-710e-80e2-65b144d1d0d5","019f632a-69d4-710e-80e2-69a57668a786",["D",1784075151835],"# Kylä UI — Roadmap\n\nThe dependency-ordered plan for reaching v1. Each row links a spec in the\n[issue tracker](issues/); vocabulary is in [`../CONTEXT.md`](../CONTEXT.md) and\nthe load-bearing decisions are in [`adr/`](adr/). This doc is the synthesis —\nthe \"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\n  `color:` hint), `variants`, `KylaProvider` + Mode, the real AA-checked\n  palette, and shipped structural spacing/radius/type scales.\n- **Structural scales & palette** — the\n  [`structural-scales-palette`](issues/structural-scales-palette/spec.md)\n  foundation is complete and consumed by `Button`.\n- **`Button`** — the reference component (typed variants → tokens, semantic\n  element, forwarded ref, escape-hatch `className`, token focus ring). \"Built\"\n  means the pattern is proven, not that it's at VT coverage parity — see\n  ADR-0005's coverage-parity clause and item 2 below.\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 spec is `ready-for-agent`. Later rows assume earlier ones.\n\n| # | Feature                       | Spec                                                  | Depends on                | Why it's here                                                                                                                                                                                                                           |\n| - | ----------------------------- | ----------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 2 | **v1 zero-dep component set** | [`v1-component-set`](issues/v1-component-set/spec.md) | Shipped scales foundation | Text/Heading, Card, Input, Textarea, Label, Badge, Stack, Box, Divider, Select — the rest of the importable core, following the `Button` pattern — plus a `Button` revision slice closing its VT variant/state coverage gap (ADR-0005). |\n| 3 | **Dialog (Radix-backed)**     | [`dialog-radix`](issues/dialog-radix/spec.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/spec.md) (folded in)       | —                         | Bring the `preview/` HTML shell in line with platform conventions (real `.html` file, no inline `<style>`). The Gallery adopts the corrected shell. Can land early, independent of the full set.                                        |\n| 4 | **Gallery**                   | [`gallery`](issues/gallery/spec.md)                   | 2, (3)                    | Promote `preview/` into the real self-hosted docs surface at `kyla-ui`'s route — every component in its variants and Modes. Also the fastest place a human spots the invisible Twind-hint failure.                                      |\n| 5 | **Starter**                   | [`starter`](issues/starter/spec.md)                   | 2, (3)                    | `kyla-ui-starter`: a remixable todo app (real HTTP route + `std/sqlite`, Provider + hydration) showing idiomatic end-to-end use. The honest integration test of v1.                                                                     |\n\nParenthesized deps are \"benefits from\" rather than \"blocked by\": the Gallery and\nStarter can ship against the zero-dep set and add Dialog once it lands.\n\n## Testing seam (shared)\n\nHighest seam that still catches the invisible Twind \"missing `color:` hint\"\nfailure, testing external output rather than the `variants()`/`cn()` internals:\n\n- **Components (2, 3):** server-render to an HTML string\n  (`renderToStaticMarkup`) and assert on the markup (semantic element, token\n  classes present, a11y wiring, `className` wins). Genuinely-Radix behavior\n  (focus trap, ESC) is left to a browser backstop in the Gallery, not re-tested.\n- **Scales & palette (1):** a pure AA-contrast check over the token stylesheet.\n- **Gallery / Starter (4, 5):** HTTP-level — fetch the route and assert the\n  served response (status, per-component sections / todo CRUD round-trip).\n\nThe scales/palette work established the Deno test harness; later component work\nextends it at the seams above.\n\n## Deferred beyond v1\n\nIntentionally not designed yet (carried forward from the design work):\n\n- **Theming v2** — a Kumo-style named-theme system (multiple consumer-defined\n  themes) once there's demand. v1 ships one opinionated theme + a small override\n  surface (`--kyla-accent`, `--kyla-radius`, font).\n- **Base UI variant** — a Base-UI-backed build once Radix proves the path.\n- **Isomorphic rendering** — SSR + hydration for content/landing pages, if\n  needed. v1 is **CSR-only** (target is interactive apps where SEO/first-paint\n  don't matter; components authored pure so isomorphic stays possible later\n  without paying its tax now).\n- **Metadata-driven Gallery generation** — v1's Gallery is hand-written.\n- **v1.1+ components** — `Checkbox`, `Radio`, `Spinner`, `Alert`, then\n  `Popover`, `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`.\n",[],[176,472],"6684ffd5-ea1c-47b1-8a81-3870ab135520","val-town-style-guide.md","019f632a-69d4-710e-80e2-5cff0abe8532","019f632a-69d4-710e-80e2-63f0ff1133c3",["D",1784076371562],"# Val Town UI style guide — design tokens reference\n\nResearch reference for ADR-0005\n(`docs/adr/0005-val-town-visual-language-default-theme.md`) and the\nscales/palette PRD (`docs/issues/structural-scales-palette/spec.md`). Extracted\n2026-07-06.\n\n## What was found, and from where\n\nVal Town's marketing/app site is a **Remix SSR** application, so a plain HTTP\n`GET` of each `https://www.val.town/_ui/<component>` page returns the **real,\nserver-rendered component markup** — every element with its full Tailwind\nutility class list. The token layer lives in the site's compiled Tailwind **v4**\nstylesheet, linked from every page and served from\n`https://static2.esm.town/assets/tailwind-<hash>.css` (current hash at\nextraction time: `tailwind-Dy1Hj0e7.css`). That file contains the Tailwind v4\n`@theme` block (the full `--color-*` scale in **oklch**, plus `--spacing`,\n`--radius-*`, `--text-*`, `--font-weight-*`) **and** Val Town's own semantic\ncolor aliases split across the light `@theme`/`:root` layer and a `.dark {…}`\nblock.\n\n**This is the primary, authoritative source** and it is machine-readable\nend-to-end: component class lists → utility classes → resolved token values, all\nfrom the live site.\n\nA **secondary** source — the val **`dcm31/townie-mobile`**, `frontend/style.css`\n(read via the Val Town MCP `read_file`) — is the distilled token set its author\nhand-fed to Fable. It agrees with the live site on the design _language_\n(slate + sky, IBM Plex Sans, iA Writer Quattro eyebrows, dark-ink-on-accent, 8px\nradius) but its literal hex values are **Tailwind v3** (e.g.\n`--vt-sky: #38bdf8`), which differ numerically from the live site's Tailwind\n**v4** oklch derivations (`sky-400` → `#00bcff`). Reconciliation is called out\nbelow.\n\n### Colour-space note\n\nThe live tokens are **oklch** (Tailwind v4). Every hex in this doc is a\n**computed** oklch→sRGB conversion (D65, standard sRGB transfer). Hexes are\nlabelled as computed; the oklch string is the source-of-truth value. Contrast\nratios are likewise computed from those sRGB values.\n\n### Reconciliation: townie-mobile (v3 hex) vs live `_ui` (v4 oklch)\n\n| Role        | townie `style.css` (v3 literal)         | live `_ui` (v4 oklch → computed hex)                | Agree?                                 |\n| ----------- | --------------------------------------- | --------------------------------------------------- | -------------------------------------- |\n| Accent      | `--vt-sky #38bdf8` (sky-400)            | `sky-400` `oklch(74.6% .16 232.661)` → `#00bcff`    | Same token name; v4 hex more saturated |\n| Deep accent | `--vt-sky-deep #0369a1` (sky-700)       | `sky-700` `oklch(50% .134 242.749)` → `#0069a8`     | Same name, v4 slightly different       |\n| Border      | `--vt-border #e2e8f0` (slate-200)       | `slate-200` `oklch(92.9% .013 255.508)` → `#e2e8f0` | **Identical**                          |\n| Accent-fg   | send btn `text-sky-950` on `bg-sky-400` | primary btn `text-sky-950` on `bg-sky-400`          | **Identical convention**               |\n\nBoth confirm **VT = Tailwind slate + sky**. Treat the **live `_ui` v4 oklch\nvalues as current source of truth**; townie's hexes are the older/hand-distilled\nvariant.\n\n---\n\n## 1. Color palette\n\n### 1a. Val Town semantic aliases (the actual theme layer)\n\nVT defines exactly **five** semantic color tokens, each aliased to a raw scale\nstep, with a light default (in the `@theme`/root layer) and a `.dark` override.\nSource: `tailwind-Dy1Hj0e7.css`, `:root`/`@theme` and `.dark{…}` blocks\n(verbatim property names).\n\n| Semantic token       | Light → raw         | Light hex (computed) | Dark → raw          | Dark hex (computed) |\n| -------------------- | ------------------- | -------------------- | ------------------- | ------------------- |\n| `--color-background` | `--color-white`     | `#ffffff`            | `--color-black`     | `#000000`           |\n| `--color-text`       | `--color-black`     | `#000000`            | `--color-white`     | `#ffffff`           |\n| `--color-border`     | `--color-slate-200` | `#e2e8f0`            | `--color-slate-700` | `#314158`           |\n| `--color-muted`      | `--color-gray-600`  | `#4a5565`            | `--color-gray-300`  | `#d1d5dc`           |\n| `--color-shadow`     | `--color-gray-50`   | `#f8fafc`*           | `--color-gray-900`  | `#101828`*          |\n\nVerbatim:\n`.dark{--color-text:var(--color-white);--color-background:var(--color-black);--color-border:var(--color-slate-700);--color-muted:var(--color-gray-300);--color-shadow:var(--color-gray-900)}`\nand light\n`--color-text:var(--color-black);--color-background:var(--color-white);--color-border:var(--color-slate-200);--color-muted:var(--color-gray-600);--color-shadow:var(--color-gray-50)`.\n(*`--color-shadow` gray hexes are approximate; used as a shadow tint, not a\nsurface.)\n\nNotable: **dark-mode background is true black** (`#000`) with true-white text —\nan OLED-style maximum-contrast choice, not a dark-gray. There is **no** semantic\ntoken for elevated / recessed surfaces or for accent — those come from raw\n`sky-*`/`slate-*` utilities in the components (§1b, §5).\n\n### 1b. Raw scale steps used across components (Tailwind v4 oklch)\n\nEvery value below is a class observed in live `_ui` component markup. oklch is\nthe source value; hex is computed. Full scales for slate/sky/rose/emerald/gray\nexist in the file; these are the steps actually referenced.\n\n**Neutrals — `slate` (structure) and `gray` (muted text)**\n\n| Token       | oklch                       | Hex (computed) | Role in `_ui`                                           |\n| ----------- | --------------------------- | -------------- | ------------------------------------------------------- |\n| `white`     | `#fff`                      | `#ffffff`      | Base surface (light)                                    |\n| `slate-50`  | `oklch(98.4% .003 247.858)` | `#f8fafc`      | Secondary button fill (light); read-only input bg       |\n| `slate-100` | `oklch(96.8% .007 247.896)` | `#f1f5f9`      | Default button fill; soft/filled input fill (light)     |\n| `slate-200` | `oklch(92.9% .013 255.508)` | `#e2e8f0`      | **Border** (`--color-border` light)                     |\n| `slate-300` | `oklch(86.9% .022 252.894)` | `#cad5e2`      | Input border (light); hover border on filled input      |\n| `slate-400` | `oklch(70.4% .04 256.788)`  | `#90a1b9`      | Input hover border (light)                              |\n| `slate-700` | `oklch(37.2% .044 257.287)` | `#314158`      | **Border** (`--color-border` dark); input border (dark) |\n| `slate-800` | `oklch(27.9% .041 260.031)` | `#1d293d`      | Default button fill (dark); soft input fill (dark)      |\n| `slate-900` | `oklch(20.8% .042 265.755)` | `#0f172b`      | Secondary button fill (dark); read-only input bg (dark) |\n| `slate-950` | `oklch(12.9% .042 264.695)` | `#020618`      | (deepest neutral)                                       |\n| `gray-300`  | `oklch(87.2% .01 258.338)`  | `#d1d5dc`      | **Muted text** (`--color-muted` dark)                   |\n| `gray-600`  | `oklch(44.6% .03 256.802)`  | `#4a5565`      | **Muted text** (`--color-muted` light)                  |\n| `black`     | `#000`                      | `#000000`      | Text (light); base (dark)                               |\n\n**Accent — `sky`**\n\n| Token     | oklch                       | Hex (computed) | Role in `_ui`                                  |\n| --------- | --------------------------- | -------------- | ---------------------------------------------- |\n| `sky-50`  | `oklch(97.7% .013 236.62)`  | `#f0f9ff`      | Secondary/clear button hover fill (light)      |\n| `sky-100` | `oklch(95.1% .026 236.824)` | `#dff2fe`      | Default button hover fill; active card (light) |\n| `sky-200` | `oklch(90.1% .058 230.902)` | `#b8e6fe`      | Default button active; accent text (dark)      |\n| `sky-300` | `oklch(82.8% .111 230.318)` | `#74d4ff`      | **Input focus ring**                           |\n| `sky-400` | `oklch(74.6% .16 232.661)`  | `#00bcff`      | **Primary button fill (light)** — the accent   |\n| `sky-500` | `oklch(68.5% .169 237.323)` | `#00a6f4`      | **Button focus ring**; input focus border      |\n| `sky-700` | `oklch(50% .134 242.749)`   | `#0069a8`      | **Primary button fill (dark)**                 |\n| `sky-800` | `oklch(44.3% .11 240.79)`   | `#00598a`      | Accent text on light (hover/aria-current)      |\n| `sky-950` | `oklch(29.3% .066 243.157)` | `#052f4a`      | **Text on `sky-400` primary fill (light)**     |\n\n**Danger — `rose`; Success — `emerald`**\n\n| Token         | oklch                       | Hex (computed) | Role                                      |\n| ------------- | --------------------------- | -------------- | ----------------------------------------- |\n| `rose-50`     | `oklch(96.9% .015 12.422)`  | `#fff1f2`      | Private privacy-badge bg                  |\n| `rose-300`    | `oklch(81% .117 11.638)`    | `#ffa1ad`      | **Danger button fill (light)**            |\n| `rose-400`    | `oklch(71.2% .194 13.428)`  | `#ff637e`      | Danger button hover; focus ring           |\n| `rose-800`    | `oklch(45.5% .188 13.697)`  | `#a50036`      | **Danger button fill (dark)**; badge text |\n| `rose-950`    | `oklch(27.1% .105 12.094)`  | `#4d0218`      | **Text on danger fill (light)**           |\n| `emerald-100` | `oklch(95% .052 163.051)`   | `#d0fae5`      | Public privacy-badge bg                   |\n| `emerald-400` | `oklch(76.5% .177 163.223)` | `#00d492`      | **Success/green button fill (light)**     |\n| `emerald-950` | `oklch(26.2% .051 172.552)` | `#002c22`      | Text on success fill (light)              |\n\nAlso referenced: `red-300`/`red-700` for input invalid rings; `amber-*` and\n`blue-*` for callout variants; `orange-*` for the \"unlisted\" privacy badge.\n\n---\n\n## 2. Spacing scale\n\n`--spacing: .25rem` → **base unit 4px** (Tailwind v4 default; all\n`gap-*`/`p-*`/`h-*`/`w-*` utilities are multiples of it). No bespoke VT spacing\ntokens. Container widths are also defined\n(`--container-xs 20rem … --container-7xl 80rem`) if a max-width scale is needed.\n\nComponent-level spacing is captured per component in §5.\n\n---\n\n## 3. Border-radius scale\n\nFrom the `@theme` block (verbatim):\n\n| Token          | rem       | px      | Where used in `_ui`                                                            |\n| -------------- | --------- | ------- | ------------------------------------------------------------------------------ |\n| `--radius-xs`  | `.125rem` | 2px     | —                                                                              |\n| `--radius-sm`  | `.25rem`  | 4px     | —                                                                              |\n| `--radius-md`  | `.375rem` | 6px     | —                                                                              |\n| `--radius-lg`  | `.5rem`   | **8px** | **Buttons, inputs, selects, textareas, cards, sidebar panels** (the workhorse) |\n| `--radius-xl`  | `.75rem`  | 12px    | Large buttons; callouts                                                        |\n| `--radius-2xl` | `1rem`    | 16px    | —                                                                              |\n| `--radius-3xl` | `1.5rem`  | 24px    | —                                                                              |\n| `rounded-full` | 9999px    | —       | Privacy badges, pills                                                          |\n\nCanonical control radius = **8px (`rounded-lg`)**; large controls step up to\n12px (`rounded-xl`). Matches townie's \"8px radius.\"\n\n---\n\n## 4. Typography\n\n**Font families** (from `tailwind-<hash>.css` `html` rule + `app.css`\n`@font-face`)\n\n| Role              | Stack                                                              | Source                                                                            |\n| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |\n| Sans (body/UI)    | `\"IBM Plex Sans\", -apple-system, sans-serif`                       | `html,:host{…font-family:IBM Plex Sans,-apple-system,sans-serif;line-height:1.5}` |\n| Mono              | `\"iA Writer Mono\", \"Menlo\", \"Consolas\", \"ui-monospace\", monospace` | `--font-mono`                                                                     |\n| Eyebrow / display | `\"iA Writer Quattro\"` (weights 400/700, normal+italic)             | `app.css` `@font-face` blocks                                                     |\n\n**Type scale** (`--text-*` with paired `--line-height`, verbatim)\n\n| Token       | size              | line-height (computed)       | approx px |\n| ----------- | ----------------- | ---------------------------- | --------- |\n| `text-xs`   | `.75rem` (12px)   | `calc(1 / .75)` = 1.333      | 12 / 16   |\n| `text-sm`   | `.875rem` (14px)  | `calc(1.25 / .875)` = 1.429  | 14 / 20   |\n| `text-base` | `1rem` (16px)     | `1.5`                        | 16 / 24   |\n| `text-lg`   | `1.125rem` (18px) | `calc(1.75 / 1.125)` = 1.556 | 18 / 28   |\n| `text-xl`   | `1.25rem` (20px)  | `calc(1.75 / 1.25)` = 1.4    | 20 / 28   |\n| `text-2xl`  | `1.5rem` (24px)   | `calc(2 / 1.5)` = 1.333      | 24 / 32   |\n| `text-3xl`  | `1.875rem` (30px) | `1.2`                        | 30 / 36   |\n\nControls (buttons/inputs) default to `text-sm` (14/20). `text-[11px]` is used\nfor privacy badges. Default body line-height is `1.5`.\n\n**Font weights** (`--font-weight-*`): normal 400, medium 500, semibold 600, bold\n700, extrabold 800. Buttons are **`font-bold` (700)**; badges are\n**`font-semibold` (600)**; inputs/selects `font-normal` (400).\n\n---\n\n## 5. Component-level styling specs\n\nAll class lists below are verbatim from live `_ui` SSR markup\n(`www.val.town/_ui/<page>`), condensed to the meaningful tokens (dropped the\nlong `[&:not([disabled])]:` guards where they only wrap a hover/active listed\nhere).\n\n### Button (`/_ui/button`)\n\n**Base:**\n`inline-flex items-center justify-center gap-x-2 shrink-0 whitespace-nowrap\nselect-none cursor-pointer disabled:cursor-not-allowed disabled:opacity-50 outline-0\nfocus-visible:ring-2 transition font-bold`\n\n**Sizes:** `sm` = `text-sm h-8 px-3 rounded-lg` · `md`(default) =\n`text-sm h-10 px-4\nrounded-lg` · `lg` = `text-base h-12 px-5 rounded-xl`.\nIcon-only appends `!px-0 w-8` (sm) / `w-10` (md).\n\n**Focus ring:** `ring-2 ring-sky-500` (rose-400 for danger, emerald-500 for\ngreen, slate-700 for blend).\n\n| Variant     | Light fill / text / border                                      | Light hover → active                                   | Dark fill / text                                                 | Dark hover → active                                       |\n| ----------- | --------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |\n| `default`   | `bg-slate-100 text-slate-800`                                   | `bg-sky-100 text-sky-800` → `bg-sky-200`               | `bg-slate-800 text-slate-200`                                    | `bg-sky-900 text-sky-200` → `bg-slate-800`                |\n| `primary`   | `bg-sky-400 text-sky-950` border-transparent                    | `bg-sky-500` → `bg-sky-600`                            | `bg-sky-700 text-white`                                          | `bg-sky-600` → `bg-sky-700`                               |\n| `secondary` | `bg-slate-50 text-black border-slate-200`                       | `bg-sky-50 text-sky-800 border-sky-200` → `bg-sky-100` | `bg-slate-900 text-white border-slate-800`                       | `bg-sky-900 text-sky-200 border-sky-500` → `bg-slate-800` |\n| `clear`     | `text-black` (no fill)                                          | `text-sky-800 bg-sky-500/10` → `bg-sky-500/5`          | `text-white`                                                     | `text-sky-200 bg-sky-500/40` → `bg-sky-500/20`            |\n| `danger`    | `bg-rose-300 text-rose-950` border-transparent                  | `bg-rose-400` → `bg-rose-500`                          | `bg-rose-800 text-white`                                         | `bg-rose-700` → `bg-rose-800`                             |\n| `green`     | `bg-emerald-400 text-emerald-950` border-transparent            | `bg-emerald-500` → `bg-emerald-600`                    | `bg-emerald-700 text-white`                                      | `bg-emerald-600` → `bg-emerald-700`                       |\n| `blend`     | `mix-blend-color-burn bg-slate-500 text-black border-slate-700` | `bg-slate-600` → `bg-slate-700`                        | `mix-blend-color-dodge bg-slate-500 text-white border-slate-400` | `bg-slate-400` → `bg-slate-300`                           |\n\nKey convention: **primary/danger/green fills use a dark-ink-on-bright-color\npairing in light mode** (`text-sky-950`/`text-rose-950`/`text-emerald-950`) and\nflip to **white ink on a deeper fill in dark mode** (`text-white` on\n`sky-700`/`rose-800`/`emerald-700`).\n\n### Input / Select / Textarea (`/_ui/input`, `/select`, `/textarea`)\n\n**Base:**\n`block w-full border outline-0 transition disabled:cursor-not-allowed\ndisabled:opacity-50 text-sm h-10 px-3 rounded-lg`.\nsm = `h-8 px-2`.\n\n- **Default variant:** `bg-background text-black border-slate-300`, hover\n  `border-slate-400`; dark `text-white border-slate-700`, hover\n  `border-slate-600`. (Note it uses the semantic `bg-background` token, so field\n  bg = white/black by mode.)\n- **Filled/soft variant:** `bg-slate-100 text-black border-transparent`, hover\n  `border-slate-300`; dark `bg-slate-800 text-white`, hover `border-slate-700`.\n- **Focus:** `focus-visible:ring-2 focus-visible:ring-sky-300` +\n  `focus-visible:border-sky-500`.\n- **Invalid** (`aria-invalid`/`user-invalid`): `ring-red-300 border-red-300`\n  (dark `ring-red-700 border-red-700`), hover `border-red-400`.\n- **Read-only:** `read-only:bg-slate-50` (dark `bg-slate-900`).\n- **Disabled:** `opacity-50 cursor-not-allowed`.\n- **Select** adds `appearance-none pr-10 cursor-pointer`; **Textarea** adds\n  `h-auto py-2`; a `code` content variant adds `font-mono`.\n\n### Card (`/_ui/card`)\n\nSurface uses `bg-background`, `border`, `rounded-lg`, `transition`; hover\n`hover:border-blue-400 dark:hover:border-blue-600 hover:shadow-lg` (note: cards\nhover **blue**, not sky). BigCard is the larger variant.\n\n### Callout (`/_ui/callout`)\n\n**Base:**\n`flex flex-wrap items-center gap-2 pl-4 pr-2 py-2 min-h-12 text-sm rounded-xl\nborder`.\nColor variants (light → dark):\n\n- info/blue: `text-blue-800 bg-blue-50 border-blue-100` →\n  `text-blue-200 bg-blue-950 border-blue-900`\n- warning/amber: `text-amber-800 bg-amber-100 border-amber-200` →\n  `text-amber-100 bg-amber-950 border-amber-900`\n\n### Privacy Badge (`/_ui/privacy-badge`)\n\n**Base:**\n`inline-flex items-center justify-center font-semibold text-[11px] h-5\nmin-w-[56px] rounded-full px-2`.\nVariants:\n\n- public: `text-emerald-800 bg-emerald-100 saturate-50`\n- private: `text-rose-800 bg-rose-50`\n- unlisted: `text-orange-800 bg-orange-50`\n\n### Dropdown / panel (`/_ui/dropdown`)\n\nFloating panel: `bg-background rounded-lg shadow-lg` (width `w-64`, margin\n`m-2`).\n\n### Shadows\n\nTailwind defaults (`shadow-lg` on cards/panels/dropdowns). The `--color-shadow`\nsemantic token (gray-50 light / gray-900 dark) tints shadow color per mode.\ntownie additionally used custom `0 2px 12px rgba(15,23,42,.05)` composer shadows\n(slate-tinted).\n\n---\n\n## 6. Mapping onto Kylä tokens\n\nKylä `--kyla-*` mapped from Val Town values. The VT source columns and notes\npreserve the live `_ui` Tailwind v4 research (semantic aliases + component\nusage); the light/dark columns report Kylä's shipped values, including\ndocumented sanctioned deviations. Hexes are computed from oklch unless noted.\n\n| Kylä token           | VT source                              | Kylä light                      | Kylä dark                 | Notes                                                                                                                                                                                                                                                              |\n| -------------------- | -------------------------------------- | ------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--kyla-base`        | `--color-background`                   | `#ffffff` (white)               | `#020618` (`slate-950`)   | VT's source value is true black `#000000`; Kylä ships the ADR-0005 sanctioned slate-950 softening to reduce glare.                                                                                                                                                 |\n| `--kyla-elevated`    | _(no VT token)_                        | `#ffffff` + shadow              | `#0f172b` (`slate-900`)   | VT has no elevated-fill token in light; raise via `shadow-lg`. In dark, `slate-900` (secondary-button fill) is the natural raised surface. See Gaps.                                                                                                               |\n| `--kyla-recessed`    | component `bg-slate-100`/`bg-slate-50` | `#f1f5f9` (`slate-100`)         | `#1d293d` (`slate-800`)   | Filled input / default-button wells. `slate-50 #f8fafc` is a shallower recess (secondary btn, read-only).                                                                                                                                                          |\n| `--kyla-fg`          | `--color-text`                         | `#000000`                       | `#ffffff`                 | true-black / true-white.                                                                                                                                                                                                                                           |\n| `--kyla-fg-muted`    | `--color-muted`                        | `#4a5565` (`gray-600`)          | `#d1d5dc` (`gray-300`)    | VT's real, now-sourced muted token — AA-safe both modes (§7). Supersedes the earlier `slate-700` guess; the two are near-equivalent (`gray-600` 7.56:1, `slate-700` 10.36:1) — either is fine, `gray-600` is the literal VT value. Definitely **not** `slate-400`. |\n| `--kyla-line`        | `--color-border`                       | `#e2e8f0` (`slate-200`)         | `#314158` (`slate-700`)   | The one VT border token. Note controls use `slate-300`/`slate-700` for _field_ borders — a touch stronger than the panel border.                                                                                                                                   |\n| `--kyla-hairline`    | _(no VT token)_                        | `#f1f5f9` (`slate-100`)         | `#1d293d` (`slate-800`)   | VT has no lighter-than-border token; Kylä ships one step lighter (light) / the elevated fill (dark). See Gaps.                                                                                                                                                     |\n| `--kyla-accent`      | primary button fill                    | `#00bcff` (`sky-400`)           | `#0069a8` (`sky-700`)     | VT's accent **changes by mode**: bright sky-400 in light, deeper sky-700 in dark. Focus rings use `sky-500 #00a6f4`.                                                                                                                                               |\n| `--kyla-accent-fg`   | primary button text                    | `#052f4a` (`sky-950`, dark ink) | `#ffffff` (white)         | Dark ink on the bright light-mode fill; white on the deep dark-mode fill. **Never white on sky-400** (§7).                                                                                                                                                         |\n| `--kyla-accent-ring` | focus ring                             | `#00a6f4` (`sky-500`)           | `#00a6f4` (`sky-500`)     | Dedicated focus affordance rather than overloading the fill token.                                                                                                                                                                                                 |\n| `--kyla-accent-text` | accent text on surfaces                | `#00598a` (`sky-800`)           | `#b8e6fe` (`sky-200`)     | Mode-aware accent text used separately from filled-button ink.                                                                                                                                                                                                     |\n| `--kyla-danger`      | danger button fill                     | `#ffa1ad` (`rose-300`)          | `#a50036` (`rose-800`)    | Pale rose w/ dark ink (light) → deep rose w/ white (dark).                                                                                                                                                                                                         |\n| `--kyla-danger-fg`   | danger button text                     | `#4d0218` (`rose-950`)          | `#ffffff`                 | Shipped semantic ink token for the danger fill.                                                                                                                                                                                                                    |\n| `--kyla-danger-text` | danger text on surfaces                | `#a50036` (`rose-800`)          | `#ffc9d4` (`rose-200`)    | Mode-aware danger text, the counterpart to `--kyla-accent-text`; the `danger` fill is 1.4:1 on white and cannot double as text. Light is VT's sourced badge-text value (`rose-800`, §5); dark has no VT source and mirrors `accent-text`'s 200-step choice.        |\n| `--kyla-success`     | success/green button fill              | `#00d492` (`emerald-400`)       | `#007a55` (`emerald-700`) | Shipped semantic success fill.                                                                                                                                                                                                                                     |\n| `--kyla-success-fg`  | success/green button text              | `#002c22` (`emerald-950`)       | `#ffffff`                 | Shipped semantic ink token for the success fill.                                                                                                                                                                                                                   |\n| `--kyla-radius`      | `--radius-lg`                          | `8px`                           | `8px`                     | Consumer-overridable base for the shipped `sm` / `md` / `lg` derivations.                                                                                                                                                                                          |\n\nScale-level (needed by the PRD):\n\n| Concept         | VT value (light = dark unless noted)                                    |\n| --------------- | ----------------------------------------------------------------------- |\n| Spacing base    | `--spacing: .25rem` = 4px                                               |\n| Radius scale    | 2 / 4 / 6 / 8 / 12 / 16 / 24 px (`xs…3xl`); control default 8           |\n| Sans            | `\"IBM Plex Sans\", -apple-system, sans-serif`                            |\n| Mono            | `\"iA Writer Mono\", \"Menlo\", \"Consolas\", \"ui-monospace\", monospace`      |\n| Eyebrow/display | `\"iA Writer Quattro\"` (400/700)                                         |\n| Body type       | `text-base` 16px / lh 1.5; controls `text-sm` 14/20                     |\n| Weights         | 400 / 500 / 600 / 700 / 800; buttons 700, badges 600                    |\n| Hues            | accent = sky · danger = rose · success = emerald · neutral = slate/gray |\n\nKylä deliberately exposes a supported subset of those upstream scales. The\ndelivered spacing steps are `0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24` on the\n4px base. Its radius roles are `sm`, `md`, and `lg`, derived as 4px / 8px / 12px\nfrom the consumer-overridable 8px base. `src/theme/tokens.ts` remains the\nexecutable source of truth for these names and values.\n\n---\n\n## 7. Gaps and AA concerns\n\n### Gaps — Kylä tokens with no direct VT semantic equivalent\n\n- **`--kyla-elevated`, `--kyla-recessed`, `--kyla-hairline`:** VT's semantic\n  layer is only `background / text / border / muted / shadow`. There is **no**\n  token for a second surface level. In light mode VT elevates by shadow over the\n  same white; recessed/hairline surfaces come from raw `slate-50`/`slate-100`\n  fills at the component level. Kylä's shipped values are the observed component\n  fills, not named VT tokens — a deliberate extrapolation retained in the\n  current palette.\n- **Filled-role foreground split:** VT expresses \"ink on a colored fill\" per\n  component (dark-950 in light, white in dark) rather than as a token. Also, VT\n  uses several distinct accent roles a single `--kyla-accent`/`--kyla-accent-fg`\n  can't hold: **fill** (`sky-400`/`sky-700`), **focus ring** (`sky-500`, inputs\n  `sky-300`), and **accent text on a surface** (`sky-800` light / `sky-200`\n  dark, used for hover/aria-current). Kylä therefore ships `--kyla-accent-fg`,\n  `--kyla-accent-ring`, and `--kyla-accent-text` as separate roles.\n\n### VT tokens/roles Kylä has no home for\n\n- **`--color-shadow`** (gray-50 light / gray-900 dark) — a mode-aware shadow\n  tint; Kylä has no shadow token.\n- **Field border ≠ panel border:** inputs use `slate-300`/`slate-700`, panels\n  use `slate-200`/`slate-700` (`--color-border`). Kylä's single `--kyla-line`\n  flattens this.\n- **Semantic status set beyond the shipped danger/success pair:** VT also uses\n  `amber`/`blue` (callouts) and `orange` (unlisted badge), which Kylä does not\n  currently expose as semantic roles.\n- **`blend` button** (`mix-blend-color-burn`/`-dodge`) — a mode-adaptive\n  technique, no token.\n\n### WCAG AA (ratios **computed** from oklch→sRGB; 4.5:1 body, 3:1 large/UI)\n\n| Foreground                      | Background                   | Ratio       | Verdict                                                                       |\n| ------------------------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------- |\n| `text` black                    | `background` white (light)   | **21.0:1**  | Pass AAA                                                                      |\n| `text` white                    | `background` black (dark)    | **21.0:1**  | Pass AAA                                                                      |\n| `muted` gray-600                | white (light)                | **7.56:1**  | Pass                                                                          |\n| `muted` gray-300                | black (dark)                 | **14.26:1** | Pass                                                                          |\n| primary `sky-950`               | `sky-400` fill (light)       | **6.37:1**  | Pass                                                                          |\n| primary white                   | `sky-700` fill (dark)        | **5.86:1**  | Pass                                                                          |\n| default `slate-800`             | `slate-100` fill (light)     | **13.34:1** | Pass                                                                          |\n| default-hover `sky-800`         | `sky-100` (light)            | **6.53:1**  | Pass                                                                          |\n| danger `rose-950`               | `rose-300` fill (light)      | **8.19:1**  | Pass                                                                          |\n| danger white                    | `rose-800` fill (dark)       | **7.92:1**  | Pass                                                                          |\n| green `emerald-950`             | `emerald-400` fill (light)   | **7.83:1**  | Pass                                                                          |\n| `slate-700` (field border/text) | white                        | **10.36:1** | Pass                                                                          |\n| **white**                       | **`sky-400`** (anti-pattern) | **2.18:1**  | **FAIL** — do not put white on the light accent; VT correctly uses `sky-950`. |\n\nTakeaways for Kylä:\n\n1. Every default VT foreground/surface pairing clears AA comfortably (5.9–21:1)\n   in **both** modes — safe to adopt wholesale.\n2. `--kyla-accent-fg` must be **dark ink (`sky-950`) in light** and **white in\n   dark**; a single fixed value can't serve both because `sky-400` needs dark\n   ink (white fails at 2.18:1) while `sky-700` needs white.\n3. `--kyla-fg-muted` = `gray-600` (light) / `gray-300` (dark) is AA-safe; keep\n   the mode split rather than one value.\n4. Note the deliberate **true-black dark background** — visually aggressive\n   (21:1); fine for AA, but worth a conscious call vs a softer\n   `slate-950 #020618` if Kylä prefers less glare.\n\n---\n\n## 8. Sources\n\n**Primary — live `_ui` (Remix SSR, plain HTTPS GET; class lists verbatim):**\n\n1. `https://www.val.town/_ui/button`, `/callout`, `/card`, `/dropdown`,\n   `/input`, `/select`, `/textarea`, `/forms`, `/privacy-badge` —\n   server-rendered component markup with full Tailwind class lists (cited per\n   component in §5).\n2. `https://static2.esm.town/assets/tailwind-Dy1Hj0e7.css` — compiled Tailwind\n   v4 stylesheet: the `@theme` `--color-*` (oklch) / `--spacing` / `--radius-*`\n   / `--text-*` / `--font-weight-*` tokens, the `html` font-family rule, and\n   VT's semantic aliases in the root layer + `.dark{…}` block (all quoted\n   verbatim in §1a, §3, §4). Hash read from the pages' `<link rel=\"stylesheet\">`\n   tags.\n3. `https://static2.esm.town/assets/_app-*.css` — `@font-face` for iA Writer\n   Quattro (400/700, normal+italic).\n\n**Secondary — distilled token set (via Val Town MCP `read_file`):** 4.\n`dcm31/townie-mobile` → `frontend/style.css` — `--vt-sky #38bdf8`,\n`--vt-sky-deep\n   #0369a1`, `--vt-border #e2e8f0` (Tailwind **v3** hexes), IBM\nPlex Sans body, iA Writer Quattro eyebrow (10px/700/0.14em uppercase).\nReconciled against the live v4 values in the intro; agrees on token names and\nthe dark-ink-on-accent convention, differs on exact hex.\n\n**Value resolution / conversion:** 5. oklch→sRGB hex and all §7 contrast ratios\nare **computed** (D65 sRGB), not read from a source. oklch strings in §1 are the\nsource-of-truth values.\n\n**Informal, non-verbatim signal (not used for any concrete value in this doc):**\n6. `https://www.val.town/secret-styleguide` — Val Town's broader internal\ncomponent library (Tag, Alert, Link, Pagination, Table, Tooltip, Card/\nProjectCard/BigCard, and ~20 more, many product-specific). Unlike the `_ui/*`\npages, this one does not expose Tailwind class attributes to a plain fetch —\nonly rendered layout/component names are recoverable. Cited in the\n`v1-component-set` PRD's VT Parallelism Audit purely as a qualitative signal\n(e.g. confirming Card is really \"ProjectCard,\" or that \"Tag\" is the closer\nanalog to a generic Badge) — never as a source of hex/class values the way §1–§5\nare.\n\nNothing here is invented: every token traces to a CSS property name or a\ncomponent class list; every hex/ratio is a labelled computation from a sourced\noklch value.\n",[],[176,487,480],"reference","fcb4f7e2-3914-43a3-a889-24f9bb460386",["D",1784075151835],[241],[176,487],["D",1784075151835],[],[176,85,88,75],"7851cf8f-5d93-4fb4-89c2-5ad66d417f45","04-button-variant-parity.md","019f632a-69d4-710e-80e2-49085a7764c0",["D",1784075151835],"# 04 · Button variant & state coverage parity with VT\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nA **revision** to the existing `Button` (`src/components/button.tsx`), not a\nrewrite: close the coverage gap between Kylä's 4 shipped variants and VT's 7\n(`docs/reference/val-town-style-guide.md` §5), plus VT's icon-only sizing\nconvention. Kylä's prop _names_ stay its own (ADR-0005) — this ticket ports\n_coverage_, not vocabulary.\n\nEnd-to-end behavior:\n\n- `variant` gains an unbordered filled-neutral member (mirrors VT `default`:\n  `bg-slate-100`/`text-slate-800` light, `bg-slate-800`/`text-slate-200` dark —\n  i.e. `--kyla-recessed`/`--kyla-fg`), named `neutral`.\n- `variant` gains a `success`-backed member (mirrors VT `green`), using the\n  `success`/`success-fg` tokens already landed in v152 — no token work needed.\n- `variant` gains `blend`, reproducing VT's mode-adaptive technique\n  (`mix-blend-color-burn` light / `mix-blend-color-dodge` dark) over\n  `--kyla-recessed`, so the button visually tints to whatever surface it sits\n  on.\n- `subtle` and `ghost` are re-verified (not renamed) for behavioral parity with\n  VT's `secondary` (border + hover-tint) and `clear` (text-only + translucent\n  hover) — note any intentional divergence found.\n- `size` gains icon-only handling: square dimensions per size step (VT's\n  `!px-0 w-8`/`w-10` pattern) instead of padded text sizing.\n- Every new/changed variant keeps the existing token-based focus ring, disabled\n  state, forwarded ref, and `className`-wins contract unchanged.\n\n## Acceptance criteria\n\n- [ ] `Button`'s `variant` union covers `neutral`, a `success`-backed variant,\n      and `blend`, each emitting the correct token utility classes (asserted via\n      rendered markup) and passing AA in both modes using only already-landed\n      tokens (`success`, `success-fg`, `accent-ring`, `accent-text`,\n      `danger-fg`).\n- [ ] Icon-only sizing is available and renders square dimensions matching VT's\n      icon-only pattern per size step.\n- [ ] `subtle`/`ghost` remain behaviorally equivalent to VT's\n      `secondary`/`clear`; any intentional divergence is called out in this\n      ticket's Comments.\n- [ ] All existing guarantees (forwarded ref, `type=\"button\"` default,\n      `className` wins, token focus ring, disabled state) still hold for every\n      variant, old and new.\n- [ ] Render-to-HTML tests (reusing the harness from ticket 01) cover every\n      variant × the icon-only path.\n- [ ] `preview/app.tsx`'s `VARIANTS`/button matrix is updated to include the new\n      variants, so the preview page stops under-representing the component (the\n      trigger for this ticket).\n\n## Out of scope\n\n- Polymorphic rendering (VT's Router Link / external-link button forms) — needs\n  a Slot-style primitive Kylä doesn't have yet; flagged in the parent PRD's Out\n  of Scope, not built here.\n- Renaming any existing variant to match VT's literal names — ADR-0005 keeps\n  Kylä's own vocabulary.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness this ticket's tests reuse.\n\nNot blocked by the scales/palette PRD's remaining tickets — `success`,\n`success-fg`, `danger-fg`, `accent-ring`, `accent-text` already landed in v152\n(see\n[structural-scales-palette issue 01](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)).\n",[],[176,85,88,85,496],"c23988f2-8fb2-44bf-b85b-4bb42cd2d83a","03-form-field-primitives.md","019f632a-69d4-710e-80e2-4501a1629dd9",["D",1784075151835],"# 03 · Form field primitives — Label, Input, Textarea, Select\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nShip the interactive form set with the ADR-0003 bounded-accessibility baseline,\nso consumers get on-system fields with a visible token focus ring and correct\nlabel association without hand-wiring ARIA.\n\nEnd-to-end behavior:\n\n- `Label` associates with a field via `htmlFor` ↔ field `id`.\n- `Input` and `Textarea` share sizes matching `Button`, carry a token visible\n  focus ring (`tw.ring`/`tw.ringOffset`), and wire an `invalid` state to\n  `aria-invalid` and the `danger` token. `Input` forwards `type`.\n- `Select` is a styled-native `<select>` (sizes matching `Input`) that keeps\n  native keyboard behavior with zero added dependencies.\n- Each follows the `Button` authoring contract (`variants()`, semantic element,\n  `forwardRef` + rest props, `className` merged last via `cn()`) and is exported\n  from the `mod.ts` barrel.\n\n## Acceptance criteria\n\n- [ ] `Label`, `Input`, `Textarea`, `Select` render their correct semantic\n      elements, forward refs/rest props, and are exported from `mod.ts`.\n- [ ] `Label htmlFor` matches an `Input id` (association asserted via rendered\n      markup); `Input` forwards `type`.\n- [ ] Focus-ring classes are present on the interactive components; `disabled`\n      and `aria-invalid` render, with `invalid` mapped to the `danger` token.\n- [ ] `className` wins over conflicting classes; render-to-HTML tests cover\n      element + a11y wiring + token classes and pass under `deno test`.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness and the `Button`-pattern reference.\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the `danger` / focus-ring tokens.\n- [Fixed spacing scale + graduated radius scale, with typed accessors](../../structural-scales-palette/issues/02-spacing-and-radius-scales.md)\n  — provides the spacing tokens the field sizes map onto.\n",[],[176,85,88,85,503],"b2912a78-cf90-4204-b8d9-522b165ecff9","02-layout-and-container-primitives.md","019f632a-69d4-710e-80e2-40b9b6389e5d",["D",1784075151835],"# 02 · Layout & container primitives — Stack, Box, Divider, Card, Badge\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nShip the non-interactive visual set — layout primitives and containers — each\nauthored on the `Button` pattern and consuming the spacing-scale tokens so\nlayout stays on-system by construction.\n\nEnd-to-end behavior:\n\n- **Layout:** `Stack` (typed `direction` row/column, `gap` from the spacing\n  scale, alignment), `Box` (minimal styled generic container, no required\n  variants), and `Divider` (orientation, uses the `hairline`/`line` token).\n- **Containers:** `Card` (typed `surface` = `elevated`/`recessed`, `padding`\n  from the spacing scale) and `Badge` (typed `tone` set, `size`). Per the parent\n  PRD's VT Parallelism Audit: VT's card has no elevated/recessed _fill_ — it's\n  flat (`base`) + `border`, elevating only via `hover:border-blue-400` +\n  `hover:shadow-lg`. `Card`'s **default** `surface` must render that\n  flat/bordered look, not a raised fill; `elevated`/`recessed` stay available as\n  explicit, Kylä-only opt-ins.\n- Every component maps typed props → token classes via `variants()`, uses a\n  semantic element, forwards ref + rest props, merges `className` last via\n  `cn()`, and is exported from the `mod.ts` barrel.\n\n## Acceptance criteria\n\n- [ ] `Stack`, `Box`, `Divider`, `Card`, and `Badge` are exported from `mod.ts`,\n      each forwarding refs/rest props.\n- [ ] `Stack` gap and `Card` padding consume spacing-scale tokens; `Divider`\n      uses the hairline token; a bad variant value is a compile error.\n- [ ] `Card surface` and `Badge tone` emit the expected token utility classes\n      (e.g. `Badge tone=\"danger\"` emits the danger color class), asserted via\n      rendered markup.\n- [ ] `Card`'s default `surface` (no prop passed) renders the flat/bordered\n      VT-parity look (`base` surface + border + hover border/shadow), not a\n      raised `elevated` fill.\n- [ ] `className` wins over each component's conflicting class; render-to-HTML\n      tests cover element + token classes and pass under `deno test`.\n\n## Blocked by\n\n- [01 — Render-to-HTML harness + Text / Heading](./01-render-harness-and-typography.md)\n  — provides the render-to-HTML harness and the `Button`-pattern reference for\n  the set.\n- [Fixed spacing scale + graduated radius scale, with typed accessors](../../structural-scales-palette/issues/02-spacing-and-radius-scales.md)\n  — provides the spacing tokens `Stack`/`Card` consume.\n",[],[176,85,88,85,510],"725d184c-42de-47ee-81d8-11f08836436e","01-render-harness-and-typography.md","019f632a-69d4-710e-80e2-3ec3473d219f",["D",1784075151835],"# 01 · Render-to-HTML harness + Text / Heading\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: v1 zero-dependency component set](../spec.md)\n\n## What to build\n\nStand up the render-to-HTML test harness for the component set and ship the\nfirst two components — `Text` and `Heading` — authored exactly like `Button`.\nConsumers get typed typography whose sizes come from the type scale and whose\ntones come from the palette; every later component slice reuses the harness this\nticket establishes.\n\nEnd-to-end behavior:\n\n- `Text` and `Heading` with typed `size` (type-scale steps), `weight`, and\n  `tone` (`fg`/`fg-muted`/`accent`/`danger`) props, a polymorphic `as` for the\n  element, `forwardRef` + rest props, and an escape-hatch `className` merged\n  last via `cn()`. Both are exported from the `mod.ts` barrel.\n- A `renderToStaticMarkup` harness that renders a component to an HTML string\n  for assertions — the uniform seam for the whole set. If this slice lands\n  before the scales PRD's own tests, it establishes the render-to-HTML harness\n  itself.\n\n## Acceptance criteria\n\n- [ ] `Text` and `Heading` render the correct semantic element (`Heading` emits\n      the right heading tag; `Text` a sensible default), forward refs/rest\n      props, and are exported from `mod.ts`.\n- [ ] `size`/`weight`/`tone` map to token utility classes drawn from the type\n      scale and palette; a bad prop value is a compile error via typed unions.\n- [ ] `className` wins over the component's own conflicting class (the `cn()`\n      contract), asserted against the rendered markup.\n- [ ] A reusable render-to-HTML harness exists; `Text`/`Heading` tests assert\n      element + token classes + `className`-wins and pass under `deno test`.\n\n## Blocked by\n\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the palette tones and the `tw.*` color accessor pattern.\n- [Type scale (size + line-height) + overridable font, with loading](../../structural-scales-palette/issues/03-type-scale-and-font.md)\n  — provides the type-scale steps `Text`/`Heading` map onto.\n",[],[176,85,88,85,517],["D",1784075151835],[235,236,237,238],[176,85,88,85],["D",1784075151835],[234,239],[176,85,88],"afa4bccf-19dc-44f7-a0bc-b4a9d8326cc2","019f632a-69d4-710e-80e2-36215a7f3ed8","019f632a-69d4-710e-80e2-38f878f8aaba",["D",1784075151835],"# PRD: Structural scales & real palette\n\nStatus: done Labels: done\n\n> The highest-leverage item on the [roadmap](../../roadmap.md): the spacing /\n> radius / type scale is where visual consistency actually lives. This PRD turns\n> the original provisional token stylesheet into the shipped structural\n> foundation. It is the prerequisite for the\n> [v1 component set](../v1-component-set/spec.md).\n\n## Problem Statement\n\nKylä's whole promise is that apps look coherent by default. Before this effort,\nthe token system shipped only semantic **color** tokens with provisional hex\nvalues plus a single `--kyla-radius`; it had no spacing scale, type scale,\ngraduated radius scale, or automated AA contrast check.\n\nThe consequence was visible in the original preview: it hand-wrote `px-4 py-2`,\n`text-lg`, `gap-6`, `mt-5`, `text-[10px]` — raw Twind numbers chosen ad hoc.\nEvery component built that way re-decided spacing and type independently, which\nis exactly the inconsistency Kylä exists to eliminate. Consumers who trusted the\noriginal default theme also had no guarantee that foreground/background pairings\nwere legible.\n\n## Solution\n\nKylä now ships a real, opinionated set of structural scales — spacing, radius,\nand type (size + line-height, with the font family and any needed weights) —\nplus a real, AA-verified color palette bound to the existing semantic tokens.\nBecause the structural scales are the supported contract consumed by every\ncomponent, spacing and type become consistent by construction. The consumer\noverride surface stays deliberately small (`--kyla-accent`, `--kyla-radius`,\n`--kyla-font`); everything structural is outside the supported theme override\nsurface — that stable contract _is_ the consistency (ADR-0001, CONTEXT.md). The\nvalues are CSS custom properties and therefore technically mutable; redefining\nstructural properties is an unsupported escape hatch, not a theme API.\n\nThe default palette carries AA contrast as a quiet guarantee (ADR-0003),\nverified mechanically rather than by eye.\n\n## User Stories\n\n1. As a consumer, I want a fixed spacing scale exposed as tokens, so that\n   padding and gaps are consistent across every component and every app without\n   me choosing pixel values.\n2. As a consumer, I want a fixed type scale (size + line-height), so that text\n   hierarchy is coherent without me hand-picking `text-*` classes.\n3. As a consumer, I want a font-family token I can override, so that I can\n   express brand while keeping the rest of the system fixed.\n4. As a consumer, I want a graduated radius scale derived from the overridable\n   `--kyla-radius`, so that rounding stays proportional when I change the base\n   radius.\n5. As a consumer, I want the default palette to meet WCAG AA contrast in both\n   light and dark mode, so that my app is legible without me auditing colors.\n6. As a consumer, I want the small override surface (accent, radius, font) to be\n   documented and stable, so that I know exactly what I may safely redefine.\n7. As a consumer, I want structural tokens (spacing, type, surfaces, borders) to\n   stay outside the supported theme override surface, so that documented theme\n   customization preserves visual consistency.\n8. As a component author, I want a sanctioned, typed way to reference scale\n   tokens, so that I compose spacing and type from the scale instead of raw\n   Twind numbers.\n9. As a component author, I want the scale accessors to sit alongside the\n   existing `tw` color helpers, so that authoring one component uses one\n   consistent vocabulary.\n10. As a component author, I want the type scale to bundle line-height with\n    size, so that I cannot set a size without its intended leading.\n11. As a maintainer, I want the palette's AA guarantee enforced by a test, so\n    that a future palette edit that breaks contrast fails CI rather than\n    shipping.\n12. As a maintainer, I want the scale definitions to live in one place\n    (`tokens.ts`), so that the design foundation has a single source of truth.\n13. As a maintainer, I want the scales expressed as CSS custom properties\n    resolved with `light-dark()` where mode-dependent, so that mode still flips\n    with zero JS.\n14. As an end user, I want legible text and comfortable spacing in whatever mode\n    my OS prefers, so that the app is usable by default.\n15. As a consumer upgrading, I want the scale token _names_ to be stable, so\n    that a Release that retunes values doesn't break my component usage.\n\n## Implementation Decisions\n\n- **Source of values (ADR-0005):** the palette and structural scales **conform\n  to the Val Town UI style guide** — they are _ported_, not invented here.\n  Concrete values come from the VT style-guide research/reference doc under\n  `docs/` (see\n  [ADR-0005](../../adr/0005-val-town-visual-language-default-theme.md)). This\n  contract binds those values to the `--kyla-*` tokens and scale accessors and\n  holds the AA line where a VT pairing falls short.\n- **Resolved default values** (from\n  [`val-town-style-guide.md`](../../reference/val-town-style-guide.md) §6; all\n  AA-passing both modes). Values are Tailwind v4 steps, applied via\n  `light-dark(light, dark)`:\n  - `base` = white / **`slate-950` `#020618`** (a deliberate softening of VT's\n    true-black `#000` — see ADR-0005); `elevated` = white+shadow / `slate-900`;\n    `recessed` = `slate-100` / `slate-800`.\n  - `fg` = black / white; `fg-muted` = `gray-600` / `gray-300` (VT's literal\n    `--color-muted`; **not** slate-400, which fails AA).\n  - `line` = `slate-200` / `slate-700`; `hairline` = `slate-100` / `slate-800`.\n  - `accent` = `sky-400` / `sky-700`; `accent-fg` = **`sky-950` ink** / white\n    (never white on `sky-400` — fails at 2.18:1); `accent-ring` = `sky-500`;\n    `accent-text` = `sky-800` / `sky-200`.\n  - `danger` = `rose-300` / `rose-800`; `danger-fg` = `rose-950` / white.\n    `success` = `emerald-400` / `emerald-700`; `success-fg` = `emerald-950` /\n    white.\n  - `radius` (base) = **8px** (`rounded-lg`); spacing base = 4px; font =\n    `\"IBM Plex Sans\", -apple-system, sans-serif`. `KylaProvider` injects the\n    Google Fonts stylesheet for IBM Plex Sans weights 400–800, so the shipped\n    default stack renders as intended.\n- **Added tokens (ADR-0005):** this effort added `accent-ring`, `accent-text`,\n  `danger-fg`, `success`, `success-fg` to the `ColorToken` union and the token\n  stylesheet, alongside the existing set. All are structural (not part of the\n  override surface).\n- **Modules delivered:** `src/theme/tokens.ts` defines the scale custom\n  properties; `src/theme/tw.ts` provides typed scale accessors alongside the\n  color helpers; `src/theme/contrast.ts` provides the pure AA-contrast check.\n- **Delivered scale contract** (defined once in `src/theme/tokens.ts` and\n  reflected here for consumers):\n  - **Spacing:** `--kyla-space-{0,1,2,3,4,5,6,8,10,12,16,20,24}`, a monotonic\n    13-step scale on a 4px base. The spacing accessors cover padding, margin,\n    gaps, and sibling space. Component dimensions such as fixed control heights\n    are not spacing and remain component-level values.\n  - **Type:** `--kyla-text-*` steps, each carrying a size **and** a line-height,\n    plus `--kyla-font` (overridable) and weight tokens if components need them.\n  - **Radius:** `--kyla-radius-sm/md/lg`, derived as 4px / 8px / 12px from the\n    consumer-overridable 8px `--kyla-radius` base.\n- **Override surface (formalized):** consumer-overridable = `--kyla-accent`,\n  `--kyla-radius`, `--kyla-font` (and their direct derivations). Everything else\n  — surfaces, foreground, borders, spacing scale, type scale — is structural and\n  outside the supported theme override surface. CSS custom properties remain\n  technically mutable, so this is a support contract rather than an enforcement\n  boundary. Document the split in `tokens.ts` and CONTEXT.md's Override Surface\n  note.\n- **Accessor shape:** scale accessors follow the `tw.*` pattern. Lengths need no\n  `color:` hint (per the spike finding, only colors do), so spacing/radius/type\n  accessors emit bare arbitrary-value classes (e.g. `p-[var(--kyla-space-4)]`),\n  while a typo in the step is a compile error via a TypeScript union — mirroring\n  how `ColorToken` already guards color tokens.\n- **Palette:** the original provisional hexes were replaced with the resolved VT\n  values above for both modes, keeping the `light-dark()` structure. Every\n  _sanctioned_ foreground/ surface pairing (`fg` on\n  `base`/`elevated`/`recessed`, `accent-fg` on `accent`, `danger-fg` on\n  `danger`, `success-fg` on `success`, `fg-muted` on surfaces used for secondary\n  text) must meet WCAG AA: 4.5:1 for body text, 3:1 for large text and UI/border\n  affordances.\n\n## Testing Decisions\n\n- **What makes a good test here:** it asserts an _external guarantee_ of the\n  foundation, not a specific hex or pixel. Two guarantees are worth testing:\n  contrast and scale integrity.\n- **Seam (highest available):** the token stylesheet string plus a **pure\n  contrast function** over resolved color values. This is the natural seam\n  because the guarantee (\"AA holds\") is a property of the values, computable\n  without a browser.\n  - Enumerate every sanctioned fg/surface pairing and assert its computed\n    contrast ratio meets the AA threshold in **both** modes. This is the load-\n    bearing test — it's what lets a future palette edit fail loudly.\n  - Assert the spacing and type scales exist, are monotonic, and expose the\n    documented step count.\n  - Assert the override tokens (`--kyla-accent`, `--kyla-radius`, `--kyla-font`)\n    are present and that structural tokens are present.\n- **Modules tested:** `tokens.ts` (via the parsed stylesheet) and the contrast\n  helper.\n- **Prior art:** none — this PRD establishes the repo's first test harness. Keep\n  it a plain Deno test so later component PRDs can reuse the pattern.\n\n## Out of Scope\n\n- The Kumo-style **named-theme system** / multiple consumer-defined themes\n  (theming v2 — deferred by the sketch).\n- Per-component **variant → token maps** (which tones `Badge`/`Button` expose,\n  etc.) — that lives with the\n  [v1 component set PRD](../v1-component-set/spec.md).\n- Any new components.\n- Dark-mode raster image handling.\n\n## Further Notes\n\n- This PRD resolved the genuine design decisions around step counts, ratios, and\n  hex values and encoded them as token values. Downstream PRDs consume those\n  delivered names and values rather than re-deciding them.\n- Because scale token _names_ become load-bearing across the component set,\n  treat a rename as a breaking change under ADR-0004 once components depend on\n  them.\n",[],[176,85,536,75],"structural-scales-palette","9e803b48-e18e-4ead-9ad0-62e149607400","04-formalize-override-surface.md","019f632a-69d4-710e-80e2-2f48d46f50d3","019f632a-69d4-710e-80e2-3094482ab7a0",["D",1784075151835],"# Formalize the override surface + structural-token presence test\n\nStatus: done Labels: done Landed: v264\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nSeal the foundation: make the override/structural split explicit and enforced\nnow that every token family (palette, spacing, radius, type/font) exists.\n\nEnd-to-end behavior:\n\n- **Documentation:** record the split in `tokens.ts` and in CONTEXT.md's\n  Override Surface note. Consumer-overridable = `--kyla-accent`,\n  `--kyla-radius`, `--kyla-font` (and their direct derivations); everything else\n  — surfaces, foreground, borders, spacing scale, type scale — is structural and\n  outside the supported theme override surface. CSS custom properties remain\n  technically mutable, so this is a support contract rather than a hard\n  enforcement boundary. That stable contract is the consistency (ADR-0001,\n  CONTEXT.md).\n- **Presence test** (reusing the harness from slice 01): assert the three\n  override tokens are present, and that the structural tokens across all\n  families are present. This encodes the stable-names contract — scale token\n  _names_ are load-bearing across the component set, so a rename becomes a\n  detectable breaking change under ADR-0004.\n\nThis slice adds no new values or accessors; it documents and locks the surface\nthe prior three slices produced.\n\n## Acceptance criteria\n\n- [x] `tokens.ts` and CONTEXT.md's Override Surface note both state the override\n      vs. structural split, listing `--kyla-accent`, `--kyla-radius`,\n      `--kyla-font` as the overridable surface.\n- [x] A test asserts the three override tokens are present and that the\n      structural tokens across surfaces, foreground, borders, spacing, radius,\n      and type are all present.\n- [x] The presence test fails if a documented token name is removed or renamed,\n      giving the stable-names contract teeth — passing under `deno test`.\n\n## Blocked by\n\n- [02 — Fixed spacing scale + graduated radius scale](./02-spacing-and-radius-scales.md)\n- [03 — Type scale + overridable font](./03-type-scale-and-font.md)\n\n(Depends on every token family existing so the presence test can assert the full\nset. Slice 01 is a transitive blocker.)\n\n## Comments\n\n- Implemented the explicit override-surface documentation in `tokens.ts` and\n  `CONTEXT.md`, plus a presence test covering the override and structural token\n  names.\n- `deno task test` passes all 13 tests; merged to `main`, producing Release\n  v264.\n",[],[176,85,536,85,538],"ffcd8168-e6bb-4cce-8e75-5e5ea451ff67","03-type-scale-and-font.md","019f632a-69d4-710e-80e2-2b6af84aab6b",["D",1784075151835],"# Type scale (size + line-height) + overridable font, with loading\n\nStatus: done Labels: done Landed: v261\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nShip the fixed type scale and the overridable font, end-to-end — tokens, typed\naccessor, and the font actually loading in the running app.\n\nEnd-to-end behavior:\n\n- **Type scale:** `--kyla-text-*` steps, each carrying **both** a size and its\n  paired line-height, defined in the token stylesheet. Structural and fixed.\n  Weight tokens are added if components need them.\n- **Font:** `--kyla-font` is the overridable font-family token (default\n  `\"IBM Plex Sans\", -apple-system, sans-serif`), part of the small consumer\n  override surface. The IBM Plex Sans webfont is actually loaded via the\n  shell/Provider so the default renders as intended — this is the delivery\n  concern the PRD flags; without it the token points at a font that never\n  arrives.\n- **Accessor:** a typed type accessor alongside the `tw.*` helpers that bundles\n  line-height with size, so an author cannot set a size without its intended\n  leading. A typo'd step is a compile error via a TypeScript union.\n- **Tests** (reusing the harness from slice 01): assert the type steps exist,\n  are monotonic by size, and that each step carries a line-height; assert\n  `--kyla-font` is present.\n\nExact steps and values come from the PRD Implementation Decisions and\n`docs/reference/val-town-style-guide.md` §4 (size/line-height pairs; weights\n400/500/600/700/800; body `text-base` 16/1.5, controls `text-sm` 14/20).\n\n## Acceptance criteria\n\n- [x] `--kyla-text-*` steps each pair a size with a line-height in the token\n      stylesheet; the scale is fixed/structural and monotonic by size.\n- [x] The typed type accessor bundles size + line-height so a size cannot be set\n      without its leading; a bad step name is a compile error.\n- [x] `--kyla-font` is an overridable token defaulting to the IBM Plex Sans\n      stack, and the webfont is loaded via the shell/Provider so the default\n      actually renders.\n- [x] Weight tokens are exposed if components need them.\n- [x] Tests assert the type steps exist, are monotonic, each carries a\n      line-height, and `--kyla-font` is present — passing under `deno test`.\n\n## Blocked by\n\n- [01 — Real palette + first contrast test harness](./01-real-palette-and-contrast-harness.md)\n  (provides the test harness and the `tw.*` accessor pattern).\n\n## Comments\n\n- Implemented the fixed VT-derived type scale, paired line-height accessors, IBM\n  Plex Sans loading through `KylaProvider`, fixed weight tokens, and Button\n  consumption of the new scale.\n- `deno task test` passes all 12 tests and formatting passes. The repo-wide lint\n  and typecheck commands retain the pre-existing `preview/index.tsx`, React\n  default-import, and `src/utils/variants.ts` baseline failures.\n- Merged to `main`, producing Release v261.\n",[],[176,85,536,85,546],"de37b813-28e6-4193-a3eb-51a8d468de12","02-spacing-and-radius-scales.md","019f632a-69d4-710e-80e2-26d53ed29a44",["D",1784075151835],"# Fixed spacing scale + graduated radius scale, with typed accessors\n\nStatus: done Labels: done Landed: v260\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nShip the two fixed length scales — spacing and radius — as tokens plus\nsanctioned, typed accessors, so component authors compose them from the scale\ninstead of raw Twind numbers.\n\nEnd-to-end behavior:\n\n- **Spacing:** a fixed, monotonic, stepped `--kyla-space-*` scale with a small\n  step count on a consistent 4px base unit, defined in the token stylesheet.\n  These are structural and not supported theme override inputs. They remain CSS\n  custom properties, so consumers can technically redefine them at their own\n  risk.\n- **Radius:** keep `--kyla-radius` as the single consumer-overridable base, and\n  derive a small graduated set (`--kyla-radius-sm/md/lg`) from it so rounding\n  stays proportional when a consumer changes the base radius.\n- **Accessors:** add typed scale accessors alongside the existing `tw.*` color\n  helpers. Lengths need no `color:` hint, so these emit bare arbitrary-value\n  classes (e.g. `p-[var(--kyla-space-4)]`, `rounded-[var(--kyla-radius-md)]`). A\n  typo'd step is a compile error via a TypeScript union, mirroring how\n  `ColorToken` guards color tokens. The existing single `tw.radius` accessor is\n  superseded by the graduated form.\n- **Scope:** the spacing accessor covers spacing semantics (padding, margin,\n  gaps, and sibling space), not component dimensions. A fixed control height\n  such as Button's `h-8` remains a component-level dimension.\n- **Tests** (reusing the harness from slice 01): assert the spacing and radius\n  tokens exist, are monotonic, expose the documented step count, and that the\n  graduated radii derive from the overridable base.\n\nThe delivered spacing steps are `0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24` on\na 4px base. The delivered radius roles are `sm`, `md`, and `lg`, derived as 4px\n/ 8px / 12px from the 8px base. `src/theme/tokens.ts` is the executable source\nof truth; `docs/reference/val-town-style-guide.md` §2–§3 records the upstream VT\nscales from which this supported subset was selected.\n\n## Acceptance criteria\n\n- [x] `--kyla-space-*` is a fixed, monotonic stepped scale on a 4px base with\n      the documented step count, defined in the token stylesheet.\n- [x] `--kyla-radius` remains the single overridable base;\n      `--kyla-radius-sm/md/lg` are derived from it and stay proportional when\n      the base changes.\n- [x] Typed spacing and radius accessors sit alongside the `tw.*` color helpers,\n      emit bare arbitrary-value classes (no `color:` hint), and make a bad step\n      name a compile error.\n- [x] Tests assert both scales exist, are monotonic, expose the documented step\n      count, and that graduated radii derive from the base — passing under\n      `deno test`.\n\n## Blocked by\n\n- [01 — Real palette + first contrast test harness](./01-real-palette-and-contrast-harness.md)\n  (provides the test harness and the expanded `tw.*` accessor pattern).\n\n## Comments\n\n- Implemented the 13-step 4px spacing scale and proportional `sm` / `md` / `lg`\n  radius derivations from the 8px base.\n- Added typed `tw.space(...)` and `tw.radius(...)` accessors with runtime tests\n  and `@ts-expect-error` checks for invalid steps; migrated existing radius\n  consumers to the graduated accessor.\n- Focused theme checks and the full `deno task test` pass (8 tests). The\n  repo-wide lint/typecheck gates still report pre-existing issues in\n  `preview/index.tsx`, React default imports, and `src/utils/variants.ts`.\n- At implementation time, the workspace had Val Town branch state in\n  `.vt/state.json` but no `.git` repository, so the ticket remained claimed\n  pending the branch's normal Release merge.\n- Immutable `main` snapshot metadata shows the structural-scale merge updating\n  this ticket and implementation files across v251–v260: Button at v254, token\n  tests at v255, tokens at v256, accessors at v257, accessor tests at v259, and\n  the final preview file at v260. The next release, v261, begins the type-scale\n  work. The structural-scale Release is therefore v260.\n",[],[176,85,536,85,553],"7a1bd438-7d5b-450b-a83a-b4e8ce60979b","01-real-palette-and-contrast-harness.md","019f632a-69d4-710e-80e2-2337ed84fa5a",["D",1784075151835],"# Real palette + first contrast test harness\n\nStatus: done Labels: done Landed: v152\n\n## Parent\n\n[PRD: Structural scales & real palette](../spec.md)\n\n## What to build\n\nReplace the provisional token palette with the real, AA-verified Val Town\nvalues, and stand up the repo's first test harness by proving that palette meets\nAA contrast. This is the foundational slice every later scale slice builds on.\n\nEnd-to-end behavior:\n\n- The token stylesheet resolves every semantic color token to its real VT value\n  in **both** modes via `light-dark()` (mode still flips with zero JS).\n  Provisional hexes are gone; the values conform to the VT style guide\n  (ADR-0005), with the one sanctioned deviation (dark-mode `base` = `slate-950`\n  `#020618`, not true black).\n- The color-token vocabulary expands to cover VT's accent + status roles: the\n  new structural tokens `accent-ring`, `accent-text`, `danger-fg`, `success`,\n  `success-fg` join the existing set, in both the stylesheet and the typed\n  `ColorToken` union so `tw.*` color helpers can reference them.\n- A pure, browser-free contrast function computes the WCAG contrast ratio\n  between two resolved color values. It is the natural seam for the guarantee\n  (\"AA holds\"), computable without a DOM.\n- The repo's first Deno test parses the token stylesheet, enumerates every\n  _sanctioned_ foreground/surface pairing, and asserts each meets its AA\n  threshold in **both** modes. This is the load-bearing test — a future palette\n  edit that breaks contrast fails CI rather than shipping.\n\nResolved values and the full sanctioned-pairing list come from the PRD's\nImplementation Decisions and `docs/reference/val-town-style-guide.md` §6–§7 —\nbind those values, do not re-decide them. Keep the harness a plain Deno test so\nlater scale slices reuse the pattern.\n\n## Acceptance criteria\n\n- [x] Every semantic color token resolves to its real VT value in both modes via\n      `light-dark()`; no provisional hexes remain, and no `dark:` variants are\n      introduced.\n- [x] Dark-mode `base` uses the sanctioned `slate-950` softening, not true\n      black.\n- [x] `accent-ring`, `accent-text`, `danger-fg`, `success`, `success-fg` are\n      added to both the stylesheet and the `ColorToken` union; existing `tw.*`\n      color helpers reach them.\n- [x] A pure contrast function returns the correct WCAG ratio for known pairs\n      and takes no DOM/browser dependency.\n- [x] A Deno test enumerates every sanctioned fg/surface pairing and asserts AA\n      (4.5:1 body, 3:1 large/UI) in both light and dark; it fails if any pairing\n      regresses.\n- [x] The test suite runs with `deno test` and passes (needs `--allow-import`\n      for the val.town types pulled by `deno.json`).\n\n## Blocked by\n\nNone - can start immediately.\n",[],[176,85,536,85,560],"be038197-6371-461d-85e5-a52d2a72fcb8",["D",1784075151835],[228,229,230,231],[176,85,536,85],"54740bad-6e77-42ec-a79b-6f1948876ebc",["D",1784075151835],[227,232],[176,85,536],"94221671-b04d-4b68-adaf-d9f9d2cf1dd3","019f632a-69d4-710e-80e2-1a9a73178beb","019f632a-69d4-710e-80e2-1ce3f5edb3c8",["D",1784075151835],"# PRD: Starter — remixable todo app\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Ships the **Starter** defined in [CONTEXT.md](../../../CONTEXT.md): a\n> separate, remixable demo val showing idiomatic end-to-end use of Kylä UI. It\n> depends on the [component set](../v1-component-set/spec.md) (and ideally\n> [Dialog](../dialog-radix/spec.md)); the Starter depends on the library, never\n> the reverse.\n\n## Problem Statement\n\nCONTEXT.md's on-ramp for a new app is \"remix the Starter, then edit.\" But the\nStarter doesn't exist. A developer who wants to build with Kylä has only the\nGallery (which shows components in isolation) and the README snippet (a single\nButton). There's no genuine, end-to-end example wiring together a real HTTP\nroute, persistence, the Provider + client hydration, an app shell, and a Mode\ntoggle — i.e. no honest demonstration that Kylä works as a whole for building an\nactual app.\n\n## Solution\n\nShip **`kyla-ui-starter`**: a small but genuine **todo app** that imports Kylä\nUI and is built entirely from its components. It has a real HTTP route,\n`std/sqlite` persistence, `KylaProvider` + client hydration, an app shell, a\nMode toggle, and a view-source link. Remixing it and editing is the intended way\nto start a new Kylä app. Building it also dogfoods the library and surfaces gaps\nin the component set.\n\n## User Stories\n\n1. As a new Kylä developer, I want a remixable Starter val, so that I can begin\n   a real app by copying a working example instead of assembling one.\n2. As a new developer, I want the Starter to be a genuine todo app (add / toggle\n   / delete, persisted), so that it demonstrates real behavior, not a static\n   mock.\n3. As a new developer, I want the Starter to persist todos with `std/sqlite`, so\n   that I see the idiomatic Val Town persistence pattern.\n4. As a new developer, I want the Starter to serve a real HTTP route, so that I\n   see how a Kylä app is served on Val Town.\n5. As a new developer, I want the Starter wrapped in `KylaProvider` with client\n   hydration, so that I see the correct Provider + CSR wiring (Twind before\n   first paint, tokens injected, Mode owned).\n6. As a new developer, I want the whole UI built from Kylä components, so that I\n   learn the components by seeing them composed in a real app.\n7. As a new developer, I want a Mode toggle in the Starter, so that I see how to\n   give an app a first-class light/dark toggle via `useKylaMode()`.\n8. As a new developer, I want a view-source link, so that I can jump from the\n   running app to its code.\n9. As a new developer, I want the Starter pinned to a known-good Kylä Release,\n   so that a fresh remix renders correctly and isn't broken by an in-flight\n   library change.\n10. As a maintainer, I want the Starter to depend on the library (never the\n    reverse), so that the dependency direction stays clean.\n11. As a maintainer, I want the Starter built from real components, so that it\n    doubles as an integration check that the set composes into an app.\n12. As an end user of the demo, I want to add, complete, and remove todos, so\n    that the app is actually usable.\n13. As an end user, I want my todos to persist across reloads, so that the demo\n    behaves like a real app.\n\n## Implementation Decisions\n\n- **Separate val:** `kyla-ui-starter` (per CONTEXT.md), distinct from `kyla-ui`.\n  It **imports** Kylä UI; the library never imports it.\n- **CSR-only** (sketch/ADR-0001): an HTML shell loads Twind before first paint,\n  a client entry hydrates the app, and `KylaProvider` wraps it (owning tokens +\n  Mode). Same shell mechanics the Gallery/preview use (importmap for `npm:`\n  specifiers, `std/catch`, `serveFile`).\n- **Persistence:** `std/sqlite` (project-scoped DB) for the todo list.\n- **HTTP route:** serves the shell and handles todo mutations — list, add,\n  toggle complete, delete — round-tripping through sqlite.\n- **UI built from Kylä components:** app shell, `Card`, `Input`, `Button`,\n  `Text`/`Heading`, `Stack`, etc., plus the Mode toggle via `useKylaMode()`.\n  Using `Dialog` (e.g. a confirm-delete) is encouraged once it ships, to\n  demonstrate the own-import-path pattern.\n- **Version pinning (decided here):** the Starter **pins** its Kylä import to a\n  known-good `?v=NNN` Release, so a remix is a stable starting point rather than\n  tracking `main` mid-change (ADR-0004). Document which Release it targets; bump\n  deliberately.\n- **view-source link** to the Starter val, matching the preview/Gallery pattern.\n\n## Testing Decisions\n\n- **What makes a good test:** it drives the app's _external_ HTTP behavior — the\n  todo operations round-tripping through sqlite — not the internal React tree or\n  the library's internals (those are the component PRDs' concern).\n- **Seam (HTTP, highest available for the app):** exercise the route endpoints\n  and assert the todo lifecycle: adding a todo returns/lists it, toggling flips\n  its completed state, deleting removes it, and the list reflects persisted\n  state on a fresh request. Optionally assert the served shell is a `200` HTML\n  page that boots the client entry.\n- **Modules tested:** the Starter's HTTP handler + its sqlite data access.\n- **Prior art:** Val Town `std/sqlite` HTTP-handler patterns (fetch a template\n  via the platform's skill finder); the `preview/index.tsx` handler is the\n  reference for the serve-shell-and-files structure on Val Town.\n\n## Out of Scope\n\n- Auth / multi-user / per-user todo lists.\n- Isomorphic SSR + hydration for SEO (sketch defers this; CSR-only for v1).\n- Demonstrations beyond the todo app (other example apps).\n- The **Gallery** / component docs — those live in the library\n  ([Gallery PRD](../gallery/spec.md)), not the Starter.\n\n## Further Notes\n\n- The Starter is the honest integration test of the whole v1: if composing it\n  into a real app is awkward, that's a signal to fix the component set, not to\n  work around it in the Starter.\n- Keep it \"tiny but genuine\" — enough to be a real app, small enough to read in\n  one sitting, since developers will copy it as their baseline.\n",[],[176,85,581,75],"starter","a817dd26-a119-4582-849c-8412e6b42453","03-todo-ui-and-mode-toggle.md","019f632a-69d4-710e-80e2-10647bd7466d","019f632a-69d4-710e-80e2-143c45a4f500",["D",1784075151835],"# 03 · Todo UI + Mode toggle\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nWire the todo UI — built entirely from Kylä components — to the CRUD route, and\ngive the app a first-class light/dark toggle via the library's own Mode\nownership. This is where the Starter becomes usable and dogfoods the component\nset as a whole.\n\nEnd-to-end behavior:\n\n- The full add / toggle / delete todo UI composed from Kylä components (`Card`,\n  `Input`, `Button`, `Text`/`Heading`, `Stack`, etc.), wired to the CRUD route.\n- A Mode toggle driven by `useKylaMode()` (not a hand-rolled toggle).\n- Optional: a confirm-delete `Dialog` once it ships, to demonstrate the\n  own-import-path pattern (soft dependency — not required to land this ticket).\n\n## Acceptance criteria\n\n- [ ] An end user can add, complete, and remove todos through a UI built\n      entirely from Kylä components.\n- [ ] A Mode toggle driven by `useKylaMode()` flips the app between light/dark.\n- [ ] The UI reflects persisted state from the CRUD route (reload shows saved\n      todos).\n\n## Blocked by\n\n- [01 — Served, hydrated skeleton app](./01-served-hydrated-skeleton.md)\n- [02 — Todo persistence + CRUD over HTTP](./02-todo-persistence-and-crud.md)\n\nSoft dependency (not blocking):\n[Dialog](../../dialog-radix/issues/01-dialog-radix-component.md) enables the\noptional confirm-delete example.\n",[],[176,85,581,85,583],"9721ea55-5a33-4e8a-9525-61d07b8f7753","02-todo-persistence-and-crud.md","019f632a-69d4-710e-80e2-0f05954a2aea",["D",1784075151835],"# 02 · Todo persistence + CRUD over HTTP\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nGive the Starter a real, persisted todo lifecycle behind its HTTP route, so the\ndemo behaves like an actual app and doubles as the honest integration check the\nPRD calls for.\n\nEnd-to-end behavior:\n\n- `std/sqlite` (project-scoped DB) data access for the todo list.\n- Route handlers that list, add, toggle-complete, and delete todos, each\n  round-tripping through sqlite. The list reflects persisted state on a fresh\n  request.\n- HTTP-seam tests that drive the route's **external** behavior — not the React\n  tree or the library internals.\n\n## Acceptance criteria\n\n- [ ] The route persists todos via `std/sqlite`; adding a todo lists it,\n      toggling flips its completed state, and deleting removes it.\n- [ ] The list reflects persisted state on a fresh request (survives reload).\n- [ ] HTTP-seam tests assert the full add/toggle/delete/list lifecycle and pass\n      under `deno test`.\n\n## Blocked by\n\n- [01 — Served, hydrated skeleton app](./01-served-hydrated-skeleton.md) —\n  provides the served val + HTTP route this builds on.\n",[],[176,85,581,85,591],"d4f6ceef-26af-479d-971b-141794d2dbf6","01-served-hydrated-skeleton.md","019f632a-69d4-710e-80e2-08a275a4f34c",["D",1784075151835],"# 01 · Served, hydrated skeleton app\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Starter — remixable todo app](../spec.md)\n\n## What to build\n\nStand up the `kyla-ui-starter` val as a served, hydrated skeleton that proves\nthe whole render/hydration path end-to-end before any todo logic exists. This is\nthe tracer bullet: a fresh remix boots correctly against a pinned Kylä release.\n\nEnd-to-end behavior:\n\n- A separate val, `kyla-ui-starter`, that **imports** Kylä UI (the library never\n  imports it).\n- CSR-only shell (ADR-0001): an `index.html` static file loads Twind before\n  first paint, a client entry hydrates the app, and `KylaProvider` wraps it\n  (owning tokens + Mode). Same shell mechanics the Gallery/preview use\n  (importmap for `npm:` specifiers, `std/catch`, `serveFile`).\n- A minimal screen built from Kylä components, served at the app's HTTP route,\n  with a view-source link back to the val.\n- The Kylä import is **pinned** to a known-good `?v=NNN` Release (ADR-0004);\n  document which Release it targets.\n\n## Acceptance criteria\n\n- [ ] `kyla-ui-starter` is a separate val that imports Kylä UI and is served at\n      an HTTP route returning a `200` HTML page that boots the client entry.\n- [ ] Twind loads before first paint; `KylaProvider` wraps the hydrated app and\n      owns tokens + Mode; the visible screen is built from Kylä components.\n- [ ] A view-source link points back to the Starter val.\n- [ ] The Kylä import is pinned to a documented known-good `?v=` Release.\n\n## Blocked by\n\n- [v1-component-set 01 — Render-to-HTML harness + Text / Heading](../../v1-component-set/issues/01-render-harness-and-typography.md)\n- [v1-component-set 02 — Layout & container primitives](../../v1-component-set/issues/02-layout-and-container-primitives.md)\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n",[],[176,85,581,85,598],"6f604f94-46ee-46d6-a560-4c4273584d0a",["D",1784075151835],[222,223,224],[176,85,581,85],"60d37959-f161-4182-ab07-e8a2bb8edcac",["D",1784075151835],[221,225],[176,85,581],"c23fa43d-5644-4ce0-9e50-a92ac384d387","019f632a-69d4-710e-80e2-01a06236ce19","019f632a-69d4-710e-80e2-0752833b1f6e",["D",1784075151835],"# PRD: Gallery — self-hosted docs surface\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Promotes the WIP `preview/` into the real **Gallery** — a first-class term in\n> [CONTEXT.md](../../../CONTEXT.md): the library's self-hosted documentation at\n> its own HTTP route, rendering every component in its variants and Modes with\n> the Mode toggle. Grows as the [component set](../v1-component-set/spec.md) and\n> [Dialog](../dialog-radix/spec.md) land.\n\n## Problem Statement\n\nKylä is meant to **document itself**: CONTEXT.md defines the Gallery as an HTTP\nroute on `kyla-ui` that renders every component in its variants and Modes — both\nliving docs and the in-browser proof that the whole stack (Twind + CSS-var\ntokens, Provider mode, Radix hydration) renders correctly on Val Town. Today\nthat surface only exists as `preview/`, which is explicitly labelled\nwork-in-progress and \"not a stable API,\" carries a 🚧 banner, and is framed as\nillustrative rather than canonical. There is no blessed docs surface a consumer\ncan point to.\n\n## Solution\n\nPromote `preview/` into the real **Gallery** served at `kyla-ui`'s HTTP route:\nit renders every shipped component across its variants/sizes/tones, shows the\ndesign token swatches, and carries the Mode toggle driven by the library's own\n`useKylaMode()`. It imports the real library and never modifies it. It is the\ncanonical proof-of-render on Val Town and the seed of a fuller docs site later.\n\n## User Stories\n\n1. As a consumer evaluating Kylä, I want a live Gallery at the library's URL, so\n   that I can see every component before importing it.\n2. As a consumer, I want each component shown in all its variants/sizes/tones,\n   so that I can pick the right props by seeing them.\n3. As a consumer, I want a Mode toggle (light/dark/system) in the Gallery, so\n   that I can verify how components look in each Mode.\n4. As a consumer, I want the token swatches shown, so that I can see the\n   semantic palette the system is built on.\n5. As a consumer, I want a view-source link, so that I can read how the Gallery\n   uses the components.\n6. As a maintainer, I want the Gallery served from `kyla-ui` itself (co-located\n   with source), so that the library documents itself and the docs can never\n   drift from the code they import.\n7. As a maintainer, I want the Gallery to import the real library and never\n   modify it, so that it's an honest proof-of-render, not a mock.\n8. As a maintainer, I want the Gallery to be the in-browser proof that Twind +\n   tokens + Provider + Radix render correctly on Val Town, so that a broken\n   render path is visible immediately.\n9. As a maintainer, I want adding a new component to the Gallery to be a small,\n   obvious edit, so that the docs stay current as the set grows.\n10. As a contributor, I want the Gallery to exercise the interactive components\n    (focus rings, Dialog open/close), so that it doubles as a manual behavior\n    check.\n11. As an end user of the docs, I want the Gallery to load without a build step,\n    so that it works on Val Town's runtime like any consumer app.\n\n## Implementation Decisions\n\n- **Home:** served from `kyla-ui`'s HTTP route (the val documents itself). Reuse\n  the shell _mechanics_ from `preview/`: Twind loaded before first paint\n  (ADR-0001), the importmap that maps `npm:` specifiers to esm.sh for the\n  browser, `std/catch` for client-error surfacing, `serveFile` for transpiled\n  `.ts/.tsx`, and the `/source` redirect. The Gallery **imports** the library\n  from `mod.ts` (and Dialog's own path) and modifies nothing — the preview's\n  core invariant.\n- **Shell conventions (folded-in cleanup — see issue\n  [`01-preview-shell-conventions`](issues/01-preview-shell-conventions.md)):**\n  the Gallery adopts the _corrected_ shell, not today's template-literal one — a\n  real `index.html` static file served via `serveFile`, and no inline `<style>`\n  block (Twind utility classes only, per project convention). This cleanup is\n  small and can land early against `preview/` before the full Gallery is built;\n  the Gallery then inherits it.\n- **Content:** one section per shipped component showing its full variant/size/\n  tone matrix, plus the token swatches and the interactive examples. The Mode\n  toggle is driven by `useKylaMode()` (not a hand-rolled toggle) — dogfooding\n  the Provider's Mode ownership.\n- **Generation approach (open question in the sketch — decided here):**\n  **hand-written** sections per component for v1. A metadata-driven generator\n  (the sketch's alternative) is deferred until the component set stabilizes;\n  hand- written is lower-risk and needs no new metadata layer.\n- **Relationship to `preview/`:** this supersedes `preview/` as the canonical\n  surface. The WIP banner and \"not a stable API\" framing are dropped once it's\n  the blessed Gallery; the corrected shell (above) is kept.\n- **Dialog:** once [Dialog](../dialog-radix/spec.md) ships, the Gallery is where\n  its open/close/focus-trap behavior is manually verifiable in-browser (the\n  behavior backstop that PRD refers to).\n\n## Testing Decisions\n\n- **What makes a good test:** it asserts the Gallery's _external_ HTTP behavior\n  — that the route serves, and that the served markup contains the expected\n  proof — not the internal React tree.\n- **Seam (HTTP, highest available for a served surface):** fetch the Gallery\n  route and assert:\n  - a `200` with an HTML content-type;\n  - each shipped component's section is present;\n  - token utility classes (e.g. `bg-[color:var(--kyla-…)]`) appear in the served\n    markup — a direct check that the render path emits the hinted classes rather\n    than silently dropping them.\n- **Behavior (browser, optional backstop):** the Mode toggle flipping the\n  palette and Dialog interactions are the higher-fidelity checks; run them in a\n  real browser against the live Gallery. Not required for the PRD's automated\n  seam.\n- **Modules tested:** the Gallery's HTTP handler.\n- **Prior art:** the existing `preview/index.tsx` handler (shell + `serveFile` +\n  `/source`) is the working reference for serving on Val Town.\n\n## Out of Scope\n\n- **Metadata-driven Gallery generation** (deferred; hand-written for v1).\n- A fuller prose/MDX docs site (the Gallery is its seed, not its replacement).\n- The **Starter** val — [separate PRD](../starter/spec.md).\n- Building the components themselves —\n  [component set PRD](../v1-component-set/spec.md).\n\n## Further Notes\n\n- The Gallery is load-bearing beyond docs: because the Twind \"missing `color:`\n  hint\" failure is _invisible_, the Gallery is the fastest place a human spots\n  an unstyled element. Keep it exercising real components in real Modes.\n",[],[176,85,619,75],"gallery","644de8f2-bd50-4f37-9322-3f2f364f06eb","03-gallery-dialog-backstop.md","019f632a-69d4-710e-80e1-fa675bf4f618","019f632a-69d4-710e-80e1-fe8ff5d42e18",["D",1784075151835],"# 03 · Wire Dialog into the Gallery as the behavior backstop\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Gallery — self-hosted docs surface](../spec.md)\n\n## What to build\n\nAdd `Dialog` to the Gallery so its interactive behavior is manually verifiable\nin-browser — the behavior backstop the [Dialog PRD](../../dialog-radix/spec.md)\nrefers to (open/close, focus-trap, ESC, in-portal token resolution), which the\nrender-seam test deliberately does not cover.\n\nEnd-to-end behavior:\n\n- A Gallery section that imports `Dialog` from its own path (not the barrel) and\n  renders a real, openable example exercising trigger/content/title/description/\n  close.\n- The example confirms, in a real browser against the live Gallery, that the\n  dialog opens/closes, traps focus, closes on ESC and overlay click, and that\n  token custom properties resolve correctly through the Radix portal in both\n  Modes.\n\n## Acceptance criteria\n\n- [ ] The Gallery renders an openable `Dialog` example imported from Dialog's\n      own path (Dialog stays out of the `mod.ts` barrel).\n- [ ] Open/close, focus-trap, ESC, and overlay-click close are manually\n      verifiable in-browser against the live Gallery.\n- [ ] In-portal token resolution is correct in both light and dark Mode (no\n      wrong-theme flash inside the modal).\n\n## Blocked by\n\n- [02 — Promote preview into the canonical Gallery](./02-gallery-build.md)\n- [dialog-radix 01 — Dialog behind its own import path](../../dialog-radix/issues/01-dialog-radix-component.md)\n",[],[176,85,619,85,621],"128d16f1-5098-4f63-b2c0-4bba5bdb2cd1","02-gallery-build.md","019f632a-69d4-710e-80e1-f4b24c719229",["D",1784075151835],"# 02 · Promote preview into the canonical Gallery\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Gallery — self-hosted docs surface](../spec.md)\n\n## What to build\n\nPromote the WIP `preview/` into the real **Gallery** served at `kyla-ui`'s HTTP\nroute: the blessed, self-hosted docs surface that renders every shipped\ncomponent in its variants and Modes, and the in-browser proof that Twind +\ntokens + Provider render correctly on Val Town.\n\nEnd-to-end behavior:\n\n- Served from `kyla-ui`'s HTTP route, reusing the _corrected_ shell mechanics\n  (Twind before first paint, importmap for `npm:` specifiers, `std/catch`,\n  `serveFile`, `/source` redirect). The Gallery **imports** the library from\n  `mod.ts` (and Dialog's own path) and modifies nothing.\n- One **hand-written** section per shipped component showing its full\n  variant/size/tone matrix, plus the design-token swatches.\n- A Mode toggle driven by the library's own `useKylaMode()` (not a hand-rolled\n  toggle).\n- The `preview/` WIP framing is dropped — the 🚧 banner and \"not a stable API\"\n  language go away once this is the canonical Gallery.\n- An HTTP-seam test asserts the route's external behavior.\n\nDialog's in-browser behavior backstop is a follow-up\n([03](./03-gallery-dialog-backstop.md)).\n\n## Acceptance criteria\n\n- [ ] The Gallery is served from `kyla-ui`'s HTTP route using the corrected\n      shell (real `index.html`, no inline `<style>`), imports the real library,\n      and modifies nothing.\n- [ ] Each shipped component has a hand-written section rendering its full\n      variant/size/tone matrix; token swatches are shown.\n- [ ] A Mode toggle driven by `useKylaMode()` flips the palette across\n      light/dark/system.\n- [ ] The `preview/` WIP banner and \"not a stable API\" framing are removed.\n- [ ] An HTTP-seam test asserts a `200` HTML response, that each shipped\n      component's section is present, and that token utility classes (e.g.\n      `bg-[color:var(--kyla-…)]`) appear in the served markup — passing under\n      `deno test`.\n\n## Blocked by\n\n- [01 — Bring the preview shell in line with platform conventions](./01-preview-shell-conventions.md)\n  — the Gallery inherits the corrected shell.\n- [v1-component-set 02 — Layout & container primitives](../../v1-component-set/issues/02-layout-and-container-primitives.md)\n  — components to render.\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n  — components to render.\n",[],[176,85,619,85,629],"82413678-997a-4cdb-981a-c3791c6d8753","01-preview-shell-conventions.md","019f632a-69d4-710e-80e1-f178ef6bc29e",["D",1784075151835],"# 01 · Bring the preview shell in line with platform conventions\n\nStatus: ready-for-agent Labels: ready-for-agent\n\nImplementation issue under the [Gallery PRD](../spec.md). The Gallery adopts the\ncorrected shell this issue produces, so this can land early against `preview/`\nbefore the full Gallery is built. Target: `nbbaier/kyla-ui`, file\n`preview/index.tsx`.\n\n## Context\n\n`preview/`'s route was reviewed against Val Town's documented React/HTTP\nconventions. Two deviations in the HTML shell built inside `preview/index.tsx`:\n\n1. **HTML shell is a template-literal string, not a real file.** The full\n   `<!doctype html>` document is built as a JS template literal and returned via\n   `new Response(html, ...)`. Val Town's own `templates/react-hono-starter`\n   ships a real `frontend/index.html` static file served via `serveFile()`,\n   satisfying the same \"Twind must load before first paint\" requirement\n   (ADR-0001) with a `<script>` tag in that static file. Template-literal HTML\n   gets no syntax highlighting, linting, or type checking.\n2. **Inline `<style>` block in the shell.** The template literal includes a\n   `<style>` tag (body margin reset + the `#root:empty::before` \"Loading\n   preview…\" placeholder). Project convention is Twind/Tailwind utility classes\n   only — no inline `<style>` tags or hand-written CSS.\n\n## Proposed fix\n\n- Extract the shell markup into a real `preview/index.html` file, keeping the\n  Twind `<script>` tag, the importmap (for the `npm:clsx` / `npm:tailwind-merge`\n  specifiers), and the `std/catch` error-reporting script exactly as they are\n  today.\n- Update `preview/index.tsx` to serve that file via\n  `serveFile(\"/preview/index.html\", import.meta.url)` instead of the inline\n  template string. Keep the existing `/source` redirect and the `.ts/.tsx`\n  passthrough (for `client.tsx`, `app.tsx`, `../mod.ts`, etc.) unchanged.\n- Replace the inline `<style>` block with Twind utility classes. The\n  `#root:empty::before` loading-placeholder trick has no direct Tailwind\n  equivalent for `:empty` — either keep one minimal, clearly-commented `<style>`\n  rule just for that, or (preferred, if simple) render an explicit loading\n  placeholder element inside `#root` in the HTML so Twind classes style it\n  directly and the `<style>` tag can be dropped entirely.\n\n## Acceptance criteria\n\n- `preview/index.tsx` no longer contains a template-literal HTML string.\n- No inline `<style>` tag remains, or the one narrow exception is commented with\n  why Twind can't express it.\n- Twind script, `catch` script, importmap, and `/source` redirect all still\n  present and working.\n- `preview/` route verified via `fetch_val_endpoint` after the change — the page\n  still renders the Button / token / mode-switcher showcase with no console\n  errors (check `get_logs`).\n\n## Out of scope\n\n- Kylä UI's Button variant names (`primary`/`subtle`/`ghost`/`danger`) and size\n  scale (`sm`/`md`/`lg`) intentionally differ from `val.town/_ui`'s own\n  vocabulary — a deliberate design choice (modeled on Cloudflare Kumo per\n  CONTEXT.md), not a bug to fix.\n",[],[176,85,619,85,636],"f05b76df-f5a2-4303-9d11-38782a5a5676",["D",1784075151835],[216,217,218],[176,85,619,85],"6d3f6fba-7981-4d16-931f-9c789f1bf9b8",["D",1784075151835],[215,219],[176,85,619],"cc73391f-0d6b-4874-8971-63a4ba236423","019f632a-69d4-710e-80e1-eb8cc412b3f0","019f632a-69d4-710e-80e1-ee0136480218",["D",1784075151835],"# PRD: Dialog (Radix-backed)\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n> Brings the first Radix-backed component into the library, exercising the\n> hybrid-headless split (ADR-0002) and the version-pinned distribution contract\n> (ADR-0004) in real code — not just the throwaway spike. Depends on the\n> [v1 component set](../v1-component-set/spec.md) for surrounding styled pieces\n> and on the [scales & palette](../structural-scales-palette/spec.md) for\n> tokens.\n\n## Problem Statement\n\nKylä's architecture bets on a **hybrid foundation**: hand-roll simple visual\ncomponents with zero dependencies, and build the hard interactive ones on a\nheadless library (ADR-0002). That bet is currently proven only in a separate\nthrowaway val (`nbbaier/kyla-ui-spike`). No hard interactive component ships in\nthe library, so the load-bearing mechanics — Radix imported behind its own\nimport path, kept out of the barrel so it only loads when used, with the\nReact-18.2.0 `?deps=` pin propagated through Radix's transitive graph — are\nunexercised in the real codebase.\n\n## Solution\n\nBring **`Dialog`** into the library as the first Radix-backed component. It\nlives behind its own import path (a root re-export, e.g. `dialog.tsx`) kept\n**out** of the `mod.ts` barrel, so consumers who never use it never load Radix.\nIt is styled entirely from the token system like every other component; its\nbehavior and accessibility (focus trap, ESC, `aria-*`, portal) are delegated to\nRadix. The public surface stays styling-only — Radix primitives remain internal\nso a later Radix→Base UI swap isn't an API break.\n\n## User Stories\n\n1. As a consumer, I want a `Dialog` component styled on-system, so that modals\n   match the rest of my Kylä app.\n2. As a consumer, I want to import `Dialog` from its own path, so that apps that\n   don't use it never pay Radix's download/parse cost.\n3. As a consumer, I want the `Dialog` to trap focus and close on ESC and overlay\n   click, so that it's accessible without me wiring ARIA by hand.\n4. As a consumer, I want `Dialog` to compose the way I'd expect (trigger,\n   content, title, description, close), so that I can build real modals.\n5. As a consumer, I want the token theme (surfaces, accent, radius) to apply\n   inside the modal, including through the portal, so that light/dark mode is\n   correct everywhere.\n6. As a consumer, I want to override the content's `className`, so that I can\n   size or position a specific dialog without forking.\n7. As a consumer pinning a version, I want `Dialog` to work under the pinned\n   React 18.2.0, so that Radix's transitive deps don't hit the `useState` null\n   mismatch.\n8. As a component author, I want Radix primitives kept internal to the Dialog\n   module, so that swapping to Base UI later doesn't change the public API.\n9. As a maintainer, I want `Dialog` excluded from the `mod.ts` barrel, so that\n   the zero-dep core stays zero-dep.\n10. As a maintainer, I want the React-version pin applied at Radix's import, so\n    that the spike's mismatch finding is encoded in shipping code.\n11. As an end user, I want a modal that manages focus and keyboard correctly, so\n    that I can use it with assistive tech.\n12. As an end user, I want the dialog's colors to match my OS light/dark\n    preference, so that it doesn't flash the wrong theme.\n\n## Implementation Decisions\n\n- **Modules built:** `src/components/dialog.tsx` (styled composition over Radix)\n  plus a root re-export path (e.g. `dialog.tsx` at the repo root) that is the\n  consumer's import URL. **Not** added to `mod.ts` (ADR-0002/0004).\n- **React pin (spike finding, load-bearing):** import Radix with\n  `?deps=react@18.2.0,react-dom@18.2.0` so the pin propagates through Radix's\n  whole transitive graph and defuses the React-mismatch `useState` null error.\n- **Public API is styling-only:** expose a composed, token-styled Dialog surface\n  (root/trigger/content/overlay/title/description/close). Radix's own primitives\n  are an internal implementation detail and are not re-exported, so a later\n  Radix→Base UI variant is not an API break.\n- **Tokens through the portal:** content uses the `elevated` surface, overlay a\n  scrim, focus ring from tokens; verify token custom properties resolve inside\n  the Radix portal (the spike confirmed `light-dark()` resolves in-portal).\n- **Radix first** (proven on VT); a Base-UI-backed variant stays deferred.\n- **Twind hint discipline still applies** inside the portal — all colors go\n  through the `tw` helpers (ADR-0001), no bare `[var(--…)]` color utilities.\n\n## Testing Decisions\n\n- **What makes a good test:** it verifies **our** contribution — that we mounted\n  Radix with the right props and token styling — and does **not** re-test\n  Radix's own guarantees. Testing that Radix traps focus is testing Radix, not\n  Kylä.\n- **Two-level seam:**\n  - **Primary (server-render, uniform with the component set):** render the\n    Dialog's trigger/closed surface (and the content in an open-by-default\n    configuration where feasible) to an HTML string and assert our wiring —\n    token utility classes present on overlay/content, `className` override wins,\n    title/ description associated, close affordance present. This catches the\n    silent Twind hint failure the same way as the rest of the set.\n  - **Behavior backstop (browser):** open/close, focus-trap, ESC, and in-portal\n    token resolution are interaction guarantees best confirmed in a real browser\n    — via the [Gallery](../gallery/spec.md) once Dialog is listed there. Treat\n    this as the higher-fidelity seam for _behavior_, not a unit test of Radix\n    internals.\n- **Modules tested:** `src/components/dialog.tsx` (render seam).\n- **Prior art:** the render-to-HTML harness from the\n  [v1 component set](../v1-component-set/spec.md); the spike val is the\n  reference for the working Radix + React-pin + portal configuration.\n\n## Out of Scope\n\n- Other Radix-backed components (`Popover`, `Menu`, `Tabs`, `Tooltip`,\n  `Combobox`, `Toast`) — v1.1+.\n- The **Base UI** variant (deferred until Radix proves the path).\n- Adding `Dialog` to the barrel (deliberately excluded).\n\n## Further Notes\n\n- This PRD is the real-code payoff of the spike. If anything in the spike's\n  Radix configuration proves brittle in the library, capture it as an ADR update\n  rather than a local workaround.\n- Because `Dialog` defines the _pattern_ for every future Radix-backed\n  component, keep the internal/exposed boundary crisp — it's what protects the\n  Radix→Base UI option.\n",[],[176,85,657,75],"dialog-radix","18ca3cab-79d5-4494-8d89-a5cf3900e63d","01-dialog-radix-component.md","019f632a-69d4-710e-80e1-e3a2e1a6e7b5","019f632a-69d4-710e-80e1-e638b488058e",["D",1784075151835],"# 01 · Dialog behind its own import path (Radix + React pin + token styling)\n\nStatus: ready-for-agent Labels: ready-for-agent\n\n## Parent\n\n[PRD: Dialog (Radix-backed)](../spec.md)\n\n## What to build\n\nBring `Dialog` into the library as the first Radix-backed component, encoding\nthe hybrid-headless split (ADR-0002) and the version-pinned distribution\ncontract (ADR-0004) in shipping code. This ticket defines the pattern every\nfuture Radix-backed component follows, so keep the internal/exposed boundary\ncrisp.\n\nEnd-to-end behavior:\n\n- A token-styled `Dialog` composition over Radix\n  (root/trigger/content/overlay/title/description/close), styled entirely from\n  the token system; behavior and accessibility (focus trap, ESC, `aria-*`,\n  portal) delegated to Radix.\n- Served from its **own root re-export path** (e.g. `dialog.tsx`) and kept\n  **out** of the `mod.ts` barrel, so consumers who never use it never load\n  Radix.\n- Radix imported with `?deps=react@18.2.0,react-dom@18.2.0` so the pin\n  propagates through Radix's transitive graph and defuses the React-mismatch\n  `useState` null error found in the spike.\n- Public surface is styling-only — Radix primitives stay internal (not\n  re-exported) so a later Radix→Base UI swap is not an API break. Content uses\n  the `elevated` surface, overlay a scrim, focus ring from tokens; token custom\n  properties resolve inside the portal. All colors go through the `tw` helpers\n  (ADR-0001).\n- A render-seam test asserts **our** wiring — token utility classes on\n  overlay/content, `className` override wins, title/description associated,\n  close affordance present — and does not re-test Radix's own guarantees.\n\nThe in-browser behavior backstop (open/close, focus-trap, ESC, in-portal token\nresolution) is verified via the [Gallery](../../gallery/spec.md), not here.\n\n## Acceptance criteria\n\n- [ ] `Dialog` renders a token-styled composition over Radix; overlay/content\n      carry token utility classes via the `tw` helpers (no bare `[var(--…)]`\n      color utilities).\n- [ ] `Dialog` is importable from its own root re-export path and is **not**\n      exported from `mod.ts`.\n- [ ] Radix is imported with the `?deps=react@18.2.0,react-dom@18.2.0` pin; the\n      dialog renders under the pinned React without the `useState` null\n      mismatch.\n- [ ] Radix primitives are not re-exported; the public surface is styling-only.\n- [ ] A render-seam test asserts token classes on overlay/content, `className`\n      override wins, title/description association, and close affordance —\n      passing under `deno test`.\n\n## Blocked by\n\n- [v1-component-set 01 — Render-to-HTML harness + Text / Heading](../../v1-component-set/issues/01-render-harness-and-typography.md)\n  — provides the render-seam harness the test reuses.\n- [v1-component-set 03 — Form field primitives](../../v1-component-set/issues/03-form-field-primitives.md)\n  — provides the surrounding styled pieces real modals compose with.\n- [Real palette + first contrast test harness](../../structural-scales-palette/issues/01-real-palette-and-contrast-harness.md)\n  — provides the surface/scrim/focus tokens resolved through the portal.\n",[],[176,85,657,85,659],"7665f285-2750-41b2-8aff-46bc8e02cbfa",["D",1784075151835],[212],[176,85,657,85],"340dc58c-b12e-4ad8-9aa4-5e7aa580d797",["D",1784075151835],[211,213],[176,85,657],"634e77fb-e023-4f03-befd-658742b6159e",["D",1784075151835],[210,214,220,226,233],[176,85],"2decfccb-e1ec-43a7-a74c-b5b5c4d08017","2026-06-18-design-and-foundation.md","019f632a-69d4-710e-80e1-dba5bfd38297","019f632a-69d4-710e-80e1-df3bc60de4d5",["D",1784075151835],"# Handoff — Kylä UI design + foundation (2026-06-18)\n\nPicking up the `nbbaier/kyla-ui` component library for Val Town. This thread did\nthe design grilling, proved the runtime substrate, and built the styling\nfoundation + the first component (`Button`). This doc is a pointer map + \"what's\nnext\", not a re-spec — the real content lives in the artifacts referenced below.\n\n## Read these first (don't duplicate them)\n\n- [`CONTEXT.md`](../../CONTEXT.md) — glossary / shared language.\n- [`docs/v1-design-sketch.md`](../v1-design-sketch.md) — the design hub,\n  **Implementation status** section, open spikes (all ✅), and the \"Deliberately\n  deferred\" list.\n- [`docs/adr/0001..0004`](../adr/) — the load-bearing decisions and _why_.\n- [`README.md`](../../README.md) — consumer-facing quick start.\n\n## State of the world\n\n- **Two vals.** `nbbaier/kyla-ui` (the library; locally synced to this working\n  dir via `vt`). `nbbaier/kyla-ui-spike` (throwaway substrate proof — all 4\n  spikes green in-browser; keep it around as a live sandbox).\n- **Foundation built & verified on the runtime:** `mod.ts` barrel + `src/utils/`\n  (`cn`, `variants`), `src/theme/` (`tokens`, `tw`, `provider`),\n  `src/components/` (`button`). Layout rationale is in the sketch's\n  Implementation status.\n- **`Button`** ships with `variant` × `size`, token focus ring, ref forwarding,\n  escape-hatch `className`. Verified by server-render (`renderToStaticMarkup`).\n- Everything is pushed; `vt status` was clean at handoff time.\n\n## Gotchas that will bite you if forgotten\n\n1. **The `color:` hint is mandatory** for token color utilities —\n   `bg-[color:var(--…)]`, never `bg-[var(--…)]` (the latter silently renders\n   nothing; no error). Always go through the `tw.*` builders in\n   `src/theme/tw.ts`, which bake it in. (ADR-0001.)\n2. **Twind lives in the HTML shell**, not the Provider (must load before first\n   paint). The Provider injects only the token stylesheet. (ADR-0001.)\n3. **Pin React to 18.2.0 everywhere**, including Radix via\n   `?deps=react@18.2.0,react-dom@18.2.0`, or you hit the `useState` null error.\n   (ADR-0002.)\n4. **`cn(componentClasses, className)` call order** is the contract — caller's\n   `className` must come last to win.\n5. **Token values in `src/theme/tokens.ts` are provisional** — not the real\n   palette yet.\n\n## Suggested next steps (roughly in order)\n\n1. **See `Button` live** — add a showcase row to `kyla-ui-spike`'s `App.tsx` to\n   eyeball all variant/size combos + hover/focus in a browser. (Quick\n   loop-closer.)\n2. **Real palette + structural scales** — replace provisional tokens with\n   AA-checked surface/fg/border ramps + spacing/radius/type scales.\n   Highest-leverage deferred item.\n3. **More components** — `Card`, `Text`/`Heading`, `Input`, `Textarea`, `Label`,\n   `Badge`, `Stack`, `Box`, `Divider`, then native-styled `Select`. Reuse the\n   Button pattern.\n4. **`Dialog` (Radix)** — first component behind its own import path:\n   `src/components/dialog.tsx`\n   - a root `dialog.ts` re-export, kept OUT of `mod.ts` (ADR-0002). Exercises\n     the split.\n5. **Gallery** — the library's self-hosted docs HTTP route (CONTEXT.md →\n   \"Gallery\").\n6. **Starter** — `kyla-ui-starter`: a tiny todo app (CONTEXT.md → \"Starter\").\n\n## How to work in this repo\n\n- Edit locally, then `vt push` (and `vt pull` first if needed). `vt status`\n  shows drift.\n- **Smoke-test pattern that works without a browser:** create a throwaway\n  `src/_smoke.ts(x)` in the val, `run_file` it (use `renderToStaticMarkup` from\n  `react-dom@18.2.0/server` to render components to a class string), then\n  `delete_file` it. Used twice this thread; clean and fast.\n- For anything UI/platform-specific on Val Town, pull the official skill via the\n  valtown MCP `find_val_town_skills` tool rather than working from memory.\n\n## Suggested skills for the next session\n\n- **valtown:react-ui** — the canonical conventions (Twind, React pin,\n  view-source) for any component or Gallery work.\n- **grill-with-docs** — if revisiting design decisions (palette, theming v2, new\n  components' APIs); it updates `CONTEXT.md` / ADRs inline.\n- **valtown:sqlite-storage** + **valtown:http-endpoints** — when building the\n  Starter todo app and/or the Gallery route.\n- **rams** (or **impeccable**) — accessibility / visual-design review once there\n  are enough components and the real palette to evaluate.\n",[],[176,686,679],"handoffs","ae4715f3-7a95-4d01-858a-62f2d4a2843e",["D",1784075151835],[208],[176,686],"e05a1714-5c0a-48c3-a441-ae41d8315dba","triage-labels.md","019f632a-69d4-710e-80e1-d018d6910818","019f632a-69d4-710e-80e1-d5f75fb0c220",["D",1784075151835],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those\nroles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning                                  |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |\n| `needs-info`               | `needs-info`         | Waiting on reporter for more information |\n| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |\n| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |\n| `wontfix`                  | `wontfix`            | Will not be actioned                     |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the\ncorresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n\n## Completion\n\nThe five roles above are _triage_ states — none marks work as finished. This\nrepo adds one local completion label beyond that vocabulary:\n\n| Label  | Meaning                                                                  |\n| ------ | ------------------------------------------------------------------------ |\n| `done` | Work merged to `main` and shipped in a Release (see `issue-tracker.md`). |\n",[],[176,699,692],"agents","b3d26b58-670b-4a9c-8312-dad2e1bd0270","issue-tracker.md","019f632a-69d4-710e-80e1-cdf7610243ee",["D",1784075151835],"# Issue tracker: Local Markdown\n\nIssues and specs (you may know a spec as a PRD) for this repo live as markdown\nfiles in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues/<feature-slug>/`\n- The spec is `docs/issues/<feature-slug>/spec.md`\n- Implementation issues are `docs/issues/<feature-slug>/issues/<NN>-<slug>.md`,\n  numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file\n  (see `triage-labels.md` for the role strings)\n- A ticket is **done** when its work merges to `main` (which cuts a Release per\n  ADR-0004): set `Status: done` and add a `Landed: v<NNN>` line recording the\n  Release version\n- Comments and conversation history append to the bottom of the file under a\n  `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues/<feature-slug>/` (creating the directory if\nneeded).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or\nthe issue number directly.\n\n## Wayfinding operations\n\nUsed by `/wayfinder`. The **map** is a file with one **child** file per ticket.\n\n- **Map**: `docs/issues/<effort>/map.md` — the Notes / Decisions-so-far / Fog\n  body.\n- **Child ticket**: `docs/issues/<effort>/issues/NN-<slug>.md`, numbered from\n  `01`, with the question in the body. A `Type:` line records the ticket type\n  (`research`/`prototype`/`grilling`/`task`); a `Status:` line records\n  `claimed`/`resolved`.\n- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked\n  when every file it lists is `resolved`.\n- **Frontier**: scan `docs/issues/<effort>/issues/` for files that are open,\n  unblocked, and unclaimed; first by number wins.\n- **Claim**: set `Status: claimed` and save before any work.\n- **Resolve**: append the answer under an `## Answer` heading, set\n  `Status: resolved`, then append a context pointer (gist + link) to the map's\n  Decisions-so-far in `map.md`.\n",[],[176,699,701],"af5546a5-5afb-498a-89f2-1a2700539096","domain.md","019f632a-69d4-710e-80e1-cb1e3c7e85cf",["D",1784075151835],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when\nexploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one\n  `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In\n  multi-context repos, also check `src/<context>/docs/adr/` for context-scoped\n  decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their\nabsence; don't suggest creating them upfront. The `/domain-modeling` skill\n(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates\nthem lazily when terms or decisions actually get resolved.\n\n## File structure\n\nSingle-context repo (most repos):\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│   ├── 0001-event-sourced-orders.md\n│   └── 0002-postgres-for-write-model.md\n└── src/\n```\n\nMulti-context repo (presence of `CONTEXT-MAP.md` at the root):\n\n```\n/\n├── CONTEXT-MAP.md\n├── docs/adr/                          ← system-wide decisions\n└── src/\n    ├── ordering/\n    │   ├── CONTEXT.md\n    │   └── docs/adr/                  ← context-specific decisions\n    └── billing/\n        ├── CONTEXT.md\n        └── docs/adr/\n```\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal,\na hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift\nto synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either\nyou're inventing language the project doesn't use (reconsider) or there's a real\ngap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than\nsilently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[176,699,708],"3485355f-32a0-4c75-98b7-ead2f3876ba8",["D",1784075151835],[204,205,206],[176,699],"03a6e3b0-60a5-4db5-94dd-b73d3c451c04","0005-val-town-visual-language-default-theme.md","019f632a-69d4-710e-80e1-c356cd787932","019f632a-69d4-710e-80e1-c49b6b164cd1",["D",1784075151835],"# Default theme adopts the Val Town visual language\n\nKylä UI ships **one opinionated default theme** (CONTEXT.md → Theme; ADR-0001).\nUntil now its palette and scales were provisional placeholders, implicitly\nderived from our Cloudflare Kumo lineage. We decide that the default theme's\n**values** — color palette (light + dark), the spacing / radius / type scales,\nand the component-level styling those map to — **conform to the Val Town UI\nstyle guide** (`val.town/_ui`), so that an app built with Kylä looks native to\nVal Town rather than like a foreign design system dropped onto the platform.\n\nThis is a decision about **values, not architecture and not API**. It changes\nwhat the `--kyla-*` tokens resolve to; it does not change how the system is\nbuilt or how consumers call it:\n\n- **Architecture stays Kumo-modeled.** Semantic tokens as CSS custom properties\n  (ADR-0001), the hybrid headless foundation (ADR-0002), primitives + components\n  — all unchanged. The token indirection is precisely what lets us retarget the\n  look without touching components.\n- **API vocabulary stays Kylä's own.** Kylä keeps its Kumo-style variant model —\n  `Button` `variant` = `primary | subtle | ghost | danger`, `size` =\n  `sm | md | lg`, etc. — which deliberately differs from `val.town/_ui`'s own\n  class vocabulary. Adopting VT's _values_ does not rename Kylä's _props_. (This\n  is consistent with the note in the Gallery's preview-shell issue: the\n  divergence recorded there was about **names**, not **palette**.)\n- **Positioning (ADR-0003) is reinforced, not changed.** \"Lead with consistency\"\n  now means consistency _with the surrounding Val Town platform_, not just\n  internal self-consistency.\n\n## Source of truth for the values\n\nThe values are extracted from Val Town's own style guide and captured in\n`docs/reference/val-town-style-guide.md`, so downstream PRDs consume concrete\nnumbers rather than \"conform to VT\" prose. Primary sources (Val Town's site is\nRemix, server-rendered, so the component markup and its compiled token CSS are\nfetchable over plain HTTPS):\n\n- `https://www.val.town/_ui/*` — the live style-guide pages (button, callout,\n  card, dropdown, input, select, textarea, forms, privacy-badge); SSR markup\n  gives each component's verbatim utility classes.\n- `https://static2.esm.town/assets/tailwind-*.css` — the compiled Tailwind v4\n  stylesheet the pages link: the `@theme` token scale (`--color-*` oklch ramp,\n  `--spacing`, `--radius-*`, `--text-*`, fonts, weights) and VT's semantic\n  aliases split across `:root`/`.dark`.\n- `https://www.val.town/x/dcm31/townie-mobile/code/frontend/style.css` — a\n  hand-distilled token artifact billed by its author as Val Town's style guide\n  (\"gave Fable our style guide\"); used as a corroborating cross-check (it is\n  Tailwind v3, so the live `_ui` v4 values are treated as source of truth).\n\n## Considered Options\n\n- **Invent an opinionated palette/scale (Kumo-flavored)** — rejected: arbitrary,\n  and it forfeits the chance to make Kylä apps look like they belong on their\n  host platform. A bespoke look is a liability, not a feature, for this\n  audience.\n- **Adopt VT's values _and_ its class vocabulary** — rejected/deferred:\n  API-breaking, and Kylä's typed variant model is more expressive than raw\n  utility classes. Revisit only if there's a concrete reason to mirror VT's prop\n  names; it is explicitly **not** part of this decision.\n- **Adopt VT's values as the default theme; keep Kylä's architecture and API** —\n  **chosen.**\n\n## Consequences\n\n- The `structural-scales-palette` PRD is reframed: instead of _designing_ a\n  palette + scales, it **ports** the Val Town style guide's palette and scales\n  into the token stylesheet, sourced from the reference doc above. This is why\n  the decision must be recorded before that PRD is implemented.\n- **Coverage parity is the bar, not just palette adoption.** The\n  `v1-component-set` PRD uses `val.town/_ui` as the styling reference for its\n  per-component variant→token maps (button sizing/radius, input styling, badge\n  tones) — but \"conforms to VT\" means matching the _set_ of variants, states,\n  and techniques VT ships per component (color variants, icon-only sizing,\n  hover/active/disabled states, mode-adaptive techniques like `blend`'s\n  `mix-blend-mode`), not only porting palette hex/oklch values onto whatever\n  variant list a component already happens to have. Kylä's prop _names_ stay its\n  own (previous bullet); the _coverage_ those names collectively provide must\n  match VT's per-component surface, checked against\n  `docs/reference/val-town-style-guide.md`. This applies retroactively: a\n  component the roadmap already marks \"Built\" (e.g. `Button`, shipped with 4 of\n  VT's 7 button variants) is still subject to this bar and gets a revision\n  slice, not a pass.\n- **AA contrast (ADR-0003) remains the stricter constraint.** Every sanctioned\n  foreground/surface pairing must meet WCAG AA in both modes. If VT's guide has\n  a pairing that falls short, Kylä's AA guarantee wins and that token value is\n  adjusted; the contrast test enforces this regardless of source.\n- **Kylä keeps its own surface hierarchy.** The extraction\n  (`docs/reference/val-town-style-guide.md`) found VT's _semantic_ layer is\n  thinner than Kylä's — VT names only\n  `background / text / border / muted / shadow` and elevates by shadow over a\n  single surface. Kylä retains its structural `base` → `elevated` → `recessed`\n  hierarchy and `hairline` (CONTEXT.md); where VT has no named token, those\n  values are sourced from VT's slate component fills. So the default theme is\n  **VT's palette under Kylä's structure**, not a strict subset of VT's tokens.\n- **The token vocabulary expands to cover VT's accent + status roles.** VT uses\n  accent in three roles a single `accent`/`accent-fg` can't hold (fill,\n  focus-ring, accent-text-on-surface), and ships a success tone. The canonical\n  `--kyla-*` vocabulary therefore gains `accent-ring`, `accent-text`,\n  `danger-fg`, and a `success`/`success-fg` tone (updating CONTEXT.md's token\n  list and the `ColorToken` union). These are **structural** additions — the\n  consumer override surface stays small.\n- **One deliberate deviation from VT:** the dark-mode `base` uses `slate-950`\n  (`#020618`), a considered softening of VT's literal true-black (`#000`, 21:1)\n  to reduce large-surface glare. Recorded here so it reads as a choice, not an\n  extraction error; every other default tracks VT.\n- The consumer **override surface** (`--kyla-accent`, `--kyla-radius`, font) is\n  unchanged; its _defaults_ become the VT values, and a consumer can still\n  rebrand within that small surface.\n- If Val Town revises its style guide, Kylä tracks it by re-running the\n  extraction and retuning token values — a values change under the existing\n  Release contract (ADR-0004), not an API change.\n",[],[176,726,719],"adr","82f6d459-2a8c-429b-a855-c6f9f94f4537","0004-version-pinned-upgrade-contract.md","019f632a-69d4-710e-80e1-be97e8095cb5",["D",1784075151835],"# Upgrade contract: main-as-release-line, version pinning\n\nKylä UI is consumed by importing its val from esm.town, where an unpinned import\n(`.../kyla-ui/mod.ts`) auto-redirects to the val's latest version and a consumer\ncan freeze onto a specific version with `?v=NNN`. esm.town does **not** offer\nbranch-name import URLs, so the intuitive \"consumers track a long-lived `stable`\nbranch\" model is not available.\n\nWe therefore make **`main` the stable/release line**: all development happens on\nfeature/dev branches, and a **Release is a merge into `main`.** Because raw work\nnever lands on `main`, HEAD-of-`main` is always a Release. Consumers then have\ntwo contracts:\n\n- **Track latest** — import the unpinned URL; always get the newest Release, so\n  fixes auto-propagate (the upside of consumption-by-import).\n- **Freeze** — pin `?v=NNN` from the README's release table; upgrade\n  deliberately by changing the number.\n\n## Considered Options\n\n- **Long-lived `stable` branch consumers import** — rejected: esm.town has no\n  documented branch-import URL, so it isn't realizable.\n- **Live HEAD with raw development on the imported line** — rejected: any\n  work-in-progress push would reach unpinned consumers; keeping development off\n  `main` is what makes the unpinned URL safe.\n\n## Consequences\n\n- Unpinned consumers receive a new Release the instant a branch merges —\n  _including a breaking one_. The release table plus brief per-release notes are\n  how a consumer decides whether to pin. There is no staging window between\n  merge and propagation.\n- Every merge to `main` mints a new `?v=NNN`; the README maps human release\n  names to those version numbers.\n- For v1 (sole consumer is the maintainer) this can be operated loosely, but the\n  convention costs nothing now and makes external consumption safe later.\n",[],[176,726,728],"1fe8daae-59eb-44c9-87be-44dccadd9c61","0003-consistency-first-bounded-accessibility.md","019f632a-69d4-710e-80e1-bb95b48c0779",["D",1784075151835],"# Consistency-first positioning, bounded accessibility\n\nKylä UI is modeled on Cloudflare Kumo, whose headline value is accessibility. We\ndeliberately invert the emphasis: **Kylä leads with visual consistency** — the\nfelt pain for the Val Town audience (people shipping apps fast without a\ndesigner) is that hand-assembled UIs look inconsistent, not that they fail an\naudit. Accessibility remains a real but _quiet_ guarantee underneath, with a\ndeliberately bounded scope for v1.\n\nThe accessibility commitment is exactly: **correct semantic HTML** (native\n`<button>`, real `<label htmlFor>`/`<input id>` association, `<h1–h6>`\nheadings), **token-based visible focus**, **not breaking native keyboard\nbehavior**, and **WCAG-AA contrast on the default theme** (a property of the\nTheme, set once). Anything requiring custom ARIA roles/state is _not_\nhand-rolled — it is built on a Headless Primitive (Radix), which is the dividing\nline of ADR-0002.\n\n## Why record this\n\nA contributor seeing the Kumo lineage will reasonably assume accessibility is\nthe headline and try to chase full WCAG-AA across the hand-rolled zero-dep\ncomponents. That is a deliberate non-goal for v1, not an oversight: the bounded\npromise is one we can actually keep, and \"needs more than semantic HTML\" is\nprecisely the signal a component belongs in the Radix tier. Full WCAG auditing\nis additive and can be revisited later; it should not silently expand v1 scope.\n",[],[176,726,735],"152fddef-3524-4367-9467-8859b08c47de","0002-hybrid-headless-foundation.md","019f632a-69d4-710e-80e1-b72c74ec4946",["D",1784075151835],"# Hybrid headless foundation, Radix-first\n\nKumo builds every component on Base UI headless primitives for accessibility. On\nVal Town a headless library is an unvetted heavy ESM dependency loaded from a\nCDN at runtime, so we take it selectively: **simple visual components (Button,\nCard, Stack, Text, Input, Badge) are hand-rolled with zero dependencies**, and\n**only the genuinely hard interactive components (Dialog, Popover, Menu, Tabs)\nbuild on a third-party headless library.** This keeps the common case\ndependency-free and fast on Val Town while still inheriting accessibility where\nit is expensive to get right.\n\nThe library is **Radix first** — chosen over the maintainer's preferred Base UI\npurely because Radix has a longer track record loading from CDNs — used to prove\nthe pattern works on Val Town. A Base-UI-backed variant is a likely later step\nonce viability is demonstrated.\n\n## Consequences\n\n- Open validation task before committing: confirm a Radix primitive (e.g.\n  Dialog) imports via esm.sh with React pinned to 18.2.0 and hydrates cleanly on\n  Val Town's CSR setup.\n- Swapping the headless library later is contained per-component, not a global\n  rewrite — which is what makes \"Radix now, Base UI later\" affordable.\n",[],[176,726,742],"a9406d42-d336-48b3-9667-e0351115131e","0001-no-build-styling-architecture.md","019f632a-69d4-710e-80e1-b0f6f4c736bf",["D",1784075151835],"# No-build styling architecture\n\nKylä UI targets Val Town, which has no build step or bundler. Cloudflare Kumo —\nour model — achieves visual consistency with Tailwind v4 semantic tokens\ncompiled at build time, which we cannot use. We therefore deliver consistency at\nruntime: **semantic design values are defined as CSS custom properties** (a\ntoken stylesheet served by the `kyla-ui` val, using `light-dark()` for automatic\ndark mode), and **components apply them via runtime Twind arbitrary-value\nutilities** (e.g. `bg-[var(--kyla-base)]`). Styles are delivered with a\ndeliberate split (confirmed by the `kyla-ui-spike`): the **Twind script lives in\nthe HTML shell** (it must load before first paint or utilities FOUC, so it\ncannot be React-injected), while the **token stylesheet is injected by the\nProvider at runtime** (idempotently). The Starter ships the shell tag; the\nProvider guarantees the tokens — so \"styles are present\" is a guarantee, not a\nsetup checklist (a manual two-tag `<head>` setup is the documented escape\nhatch).\n\n## Considered Options\n\n- **Tailwind v4 + build step (the Kumo way)** — rejected: requires a\n  bundler/PostCSS, which Val Town does not provide.\n- **Twind with a named-token theme config** (`bg-kyla-base`) — rejected: every\n  consumer app would have to load an identical Twind runtime config or\n  components render wrong; that coupling is a sharp, silent failure mode.\n- **Pure CSS component classes** (`.kyla-button`) — rejected: self-contained but\n  abandons Tailwind/Twind ergonomics and composable variants, and strays from\n  the Val Town idiom.\n\n## Consequences\n\n- Arbitrary-value Twind syntax is noisier, but it lives inside library source;\n  consumers only write `<Button>`.\n- Components only render correctly where Twind is running and the token\n  stylesheet is loaded — hence the Provider (see ADR-0002's sibling delivery\n  decision) is load-bearing.\n- The `light-dark()` CSS function handles dark mode without `dark:` variants,\n  keeping component source theme-agnostic.\n- **Authoring rule (proven by the spike):** semantic-color utilities must carry\n  the `color:` type hint — `bg-[color:var(--kyla-base)]`,\n  `text-[color:var(--kyla-fg)]`, `border-[color:var(--kyla-line)]`. A bare\n  `bg-[var(--…)]` is type-ambiguous and Twind silently emits nothing (the\n  failure is invisible — no error, just an unstyled element). Lengths are\n  unambiguous, so `rounded-[var(--kyla-radius)]` needs no hint. Because the\n  omission fails silently, component authors must not hand-write these strings;\n  the `cn()`/variant layer should emit token utilities through a tiny helper so\n  the hint can never be forgotten.\n",[],[176,726,749],"812fffee-1297-4a41-9091-bda4b2b6458c",["D",1784075151835],[198,199,200,201,202],[176,726],"24b3ddcd-93b2-47cb-af1a-d243a145b06e",["D",1784075151835],[197,203,207,209,240,242],[176],["D",1781804868537],["D",1789701064442],{"_11":12,"_140":80},{"_11":12,"_136":-5,"_79":80,"_31":78,"_137":138,"_139":30},{"_39":126,"_13":16,"_33":36,"_127":90,"_128":69,"_129":130,"_131":94,"_132":90,"_133":42,"_134":14,"_135":12},"ctx",{"_52":-5,"_160":801,"_802":803,"_804":805,"_806":30,"_807":30,"_808":30,"_809":24,"_810":-5,"_811":-7,"_812":-7,"_813":26,"_814":30,"_815":30,"_816":-5,"_817":30,"_818":30,"_819":30,"_820":-5},"ENV",{"_772":773,"_774":775,"_776":70,"_777":778,"_779":780,"_781":782,"_783":784,"_785":786,"_787":788,"_789":790,"_791":792,"_793":794,"_795":796,"_797":798,"_799":800},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","71c1b20804b3232a7e513be260cfffc1932a9e97","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]
</article></body></html>

History · v1-component-set