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

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

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

\n ))}\n

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

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

{token}

\n --kyla-{token}\n

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

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

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

\n {/* header */}\n

\n Kylä UI\n

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

\n \n

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

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

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

\n ✅ In place\n

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

\n 🔜 To come\n

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

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

\n \n \n );\n}\n",[],[220,383],["D",1783373301204],[254,255,256],[220],"03c8fddf-4620-4e1b-8421-5ef38b89c67c","v1-design-sketch.md","019f3953-b8df-70da-933b-176d7a976d8d",["D",1783375727400],"# Kylä UI — v1 Design Sketch\n\nA high-level sketch of the v1 design, produced from a design interview. This is\nthe hub: vocabulary lives in [`../CONTEXT.md`](../CONTEXT.md), and each\nconsequential decision has an ADR in [`adr/`](./adr/). This doc summarizes the\nshape and records what is **deliberately deferred**.\n\n> Modeled on [Cloudflare Kumo](https://github.com/cloudflare/kumo) — semantic\n> tokens, headless foundation, primitives + components — ported onto Val Town's\n> **no-build** reality. Where Kumo uses Tailwind v4 + codegen, Kylä uses runtime\n> CSS variables + Twind.\n\n## Positioning\n\n**Lead with consistency, not accessibility.** The felt pain for the Val Town\naudience (shipping apps fast, no designer) is inconsistent, hand-assembled UI.\nAccessibility is a real but _quiet, bounded_ guarantee underneath. See\n[ADR-0003](./adr/0003-consistency-first-bounded-accessibility.md).\n\n## Implementation status\n\n- **Substrate spike** — `nbbaier/kyla-ui-spike`, all four spikes green (see\n below).\n- **Layout** — `src/` is split by concern (root re-export files hide it from\n consumers): `src/utils/` (framework-agnostic class helpers), `src/theme/`\n (tokens, token-class builders, theming runtime), `src/components/` (one file\n per component). `mod.ts` is the public barrel; a Radix component gets a root\n re-export file (e.g. `dialog.ts`) kept _out_ of the barrel (ADR-0002).\n- **Styling foundation** — built in `kyla-ui` and verified on the runtime:\n - `src/utils/cn.ts` — `twMerge(clsx())`, versions pinned (clsx@2.1.1,\n tailwind-merge@3.6.0); empirically confirmed to dedupe `[color:var(--…)]`\n token classes. Contract: `cn(componentClasses, className)` — caller's\n `className` wins.\n - `src/theme/tw.ts` — `tw.bg/text/border/ring/ringOffset(token, state?)`\n builders that bake in the `color:` hint (state-prefixable), plus the\n `ColorToken` union (typo = compile error).\n - `src/utils/variants.ts` — hand-rolled cva-style `variants()` (no external\n dep).\n - `src/theme/tokens.ts` — token stylesheet (provisional values).\n - `src/theme/provider.tsx` — `KylaProvider` + `useKylaMode`.\n - `mod.ts` — public barrel (Radix kept out).\n- **First component** — `src/components/button.tsx` (`Button`, `ButtonProps`):\n variants `primary | subtle | ghost | danger` × `sm | md | lg`, token focus\n ring, default `type=\"button\"`, forwarded ref + rest props, escape-hatch\n `className`. Verified by server-render. Surfaced + fixed a foundation gap:\n state-prefixed token utilities (`tw.bg(\"recessed\", \"hover\")`).\n- **Next** — real palette/scales; more components (`Card`, `Input`, `Text`, …);\n bring `Dialog` over to exercise the Radix-behind-its-own-path split.\n\n## Shape\n\n- **Two vals.**\n - `kyla-ui` — the importable library, which also serves its own\n **Gallery** (docs) at its HTTP route.\n - `kyla-ui-starter` — a remixable, genuine\n **todo app** (real HTTP route + `std/sqlite`) showing idiomatic end-to-end\n use. The Starter depends on the library; never the reverse.\n- **CSR-only for v1.** Target is interactive apps (dashboards, tools, forms)\n where SEO/first-paint don't matter. Components authored pure so isomorphic\n stays possible later, without paying its tax now.\n\n## Styling — [ADR-0001](./adr/0001-no-build-styling-architecture.md)\n\n- Semantic tokens as `--kyla-*` **CSS custom properties** using `light-dark()`;\n applied via runtime **Twind arbitrary-value** utilities\n (`bg-[var(--kyla-base)]`). No build, no bundler.\n- Token vocabulary: surfaces `base → elevated → recessed`; foreground `fg`,\n `fg-muted`; borders `line`, `hairline`; `accent`, `danger`; `radius`.\n- One opinionated theme. Small consumer **override surface** (`--kyla-accent`,\n `--kyla-radius`, font); structural tokens stay fixed — that fixedness _is_ the\n consistency. A Kumo-style named-theme system is a deliberate later step.\n\n## Style delivery & theming\n\n- **`KylaProvider`** guarantees Twind + token stylesheet are present (a manual\n two-tag `` setup is the documented fallback).\n- The Provider **owns Mode**: sets `data-mode=\"light|dark|system\"`, exposes\n `useKylaMode()` (persistence opt-in); `system` falls through to OS via\n `light-dark()`. Apps get a first-class light/dark toggle for free.\n\n## Components — [ADR-0002](./adr/0002-hybrid-headless-foundation.md)\n\n- **Hybrid foundation.** Hand-roll simple visual components with zero deps;\n build on a headless library only for hard interactive ones. **Radix first**\n (proven on VT), Base UI as a likely faithful-to-Kumo later variant.\n- **v1 inventory:**\n - Zero-dep visual: `Button`, `Text`/`Heading`, `Card`, `Input`, `Textarea`,\n `Label`, `Badge`, `Stack`, `Box`, `Divider`\n - Styled native: `Select`\n - Radix-backed (the headless proof): `Dialog`\n - Deferred to v1.1+: `Checkbox`, `Radio`, `Spinner`, `Alert`, then `Popover`,\n `Menu`, `Tabs`, `Tooltip`, `Combobox`, `Toast`, `Table`, …\n- **API:** typed **variant** props (`variant`, `size`, `tone`) mapping to tokens\n internally; escape-hatch `className` merged last via exported `cn()`; refs +\n rest props forwarded. Public surface = finished components + `cn()` +\n Provider. Radix primitives stay **internal** (so Radix→Base UI later isn't an\n API break).\n- **Accessibility (bounded):** correct semantic HTML, real\n ``/`id` association, token-based visible focus, no broken\n native keyboard behavior, AA contrast on the default theme. Anything needing\n custom ARIA → Radix tier.\n\n## Distribution — [ADR-0004](./adr/0004-version-pinned-upgrade-contract.md)\n\n- **Module layout:** barrel `mod.ts` for the zero-dep core; heavy `dialog.tsx`\n behind its own import path so Radix only loads when used.\n- **Upgrade contract:** `main` is the release line; development happens on\n branches; a **Release** is a merge to `main`. Unpinned import = latest Release\n (fixes auto-propagate); `?v=NNN` to freeze; README release table maps names →\n versions. (esm.town has no branch-import URLs, hence version pinning.)\n\n## Open verification spikes\n\nBuilt and **fully verified in-browser** as one throwaway val:\n**`nbbaier/kyla-ui-spike`** (`frontend/{App,KylaProvider,tokens}.tsx`). All four\ngreen:\n\n1. ✅ **Radix `Dialog`** — imports via esm.sh with React 18.2.0 (the\n `?deps=react@18.2.0,react-dom@18.2.0` pin propagates through Radix's whole\n transitive graph, defusing the React-mismatch `useState` null error) and\n renders/opens/closes/focus-traps cleanly under CSR.\n2. ✅ **Twind + CSS-var tokens** — surfaces render stepped, accent applies.\n3. ✅ **`KylaProvider` runtime token injection** — styles exist only because the\n Provider injected the stylesheet. (Twind stays in the _shell_ since it must\n load before first paint; only the token stylesheet is Provider-injected.)\n4. ✅ **`light-dark()` + `data-mode`** — mode toggle flips the palette; resolves\n even inside the Radix portal.\n\n### Load-bearing finding (the spike's main payoff)\n\nOn Val Town's runtime **Twind, semantic-color utilities must carry the `color:`\ntype hint** — `bg-[color:var(--kyla-base)]`, `text-[color:var(--kyla-fg)]`,\n`border-[color:var(--kyla-line)]`. A bare `bg-[var(--…)]` is type-ambiguous and\nTwind **silently emits nothing** — no error, just an unstyled element. Lengths\nare fine bare (`rounded-[var(--kyla-radius)]`). Because the failure is\ninvisible, the `cn()`/variant layer must emit token utilities through a helper\nso authors can't forget the hint. (Baked into ADR-0001.)\n\n## Deliberately deferred (not yet designed)\n\nThese were identified but intentionally not resolved in this sketch. The\n**spacing / radius / type scale** is the highest-leverage — it's where visual\nconsistency actually lives.\n\n- **Structural scales** — the spacing, radius, and typographic scales (the fixed\n tokens carrying most of the consistency). Currently undefined.\n- **Variant → token maps** — concrete `variant`/`size`/`tone` value sets per\n component (e.g. what tones `Button`/`Badge` expose).\n- **`KylaProvider` API** — its precise prop surface beyond \"owns styles + Mode\".\n- **Gallery generation** — hand-written vs generated from component metadata.\n- **Theming v2** — a Kumo-style named-theme system (multiple consumer-defined\n themes) once there's demand.\n- **Base UI variant** — a Base-UI-backed build once Radix proves the path.\n- **Isomorphic rendering** — SSR + hydration for content/landing pages, if\n needed.\n",[],[226,393],"8dab6582-02fc-404c-8075-20be76723447","2026-06-18-design-and-foundation.md","019f3953-b8df-70da-933b-0ead238cd3ee","019f3953-b8df-70da-933b-111bb9523094",["D",1783373215838],"# Handoff — Kylä UI design + foundation (2026-06-18)\n\nPicking up the `nbbaier/kyla-ui` component library for Val Town. This thread did the\ndesign grilling, proved the runtime substrate, and built the styling foundation + the\nfirst component (`Button`). This doc is a pointer map + \"what's next\", not a re-spec —\nthe real content lives in the artifacts referenced below.\n\n## Read these first (don't duplicate them)\n\n- [`CONTEXT.md`](../../CONTEXT.md) — glossary / shared language.\n- [`docs/v1-design-sketch.md`](../v1-design-sketch.md) — the design hub, **Implementation\n status** section, open spikes (all ✅), and the \"Deliberately deferred\" list.\n- [`docs/adr/0001..0004`](../adr/) — the load-bearing decisions and *why*.\n- [`README.md`](../../README.md) — consumer-facing quick start.\n\n## State of the world\n\n- **Two vals.** `nbbaier/kyla-ui` (the library; locally synced to this working dir via\n `vt`). `nbbaier/kyla-ui-spike` (throwaway substrate proof — all 4 spikes green\n in-browser; keep it around as a live sandbox).\n- **Foundation built & verified on the runtime:** `mod.ts` barrel + `src/utils/`\n (`cn`, `variants`), `src/theme/` (`tokens`, `tw`, `provider`), `src/components/`\n (`button`). Layout rationale is in the sketch's Implementation status.\n- **`Button`** ships with `variant` × `size`, token focus ring, ref forwarding,\n escape-hatch `className`. Verified by server-render (`renderToStaticMarkup`).\n- Everything is pushed; `vt status` was clean at handoff time.\n\n## Gotchas that will bite you if forgotten\n\n1. **The `color:` hint is mandatory** for token color utilities — `bg-[color:var(--…)]`,\n never `bg-[var(--…)]` (the latter silently renders nothing; no error). Always go\n through the `tw.*` builders in `src/theme/tw.ts`, which bake it in. (ADR-0001.)\n2. **Twind lives in the HTML shell**, not the Provider (must load before first paint).\n The Provider injects only the token stylesheet. (ADR-0001.)\n3. **Pin React to 18.2.0 everywhere**, including Radix via\n `?deps=react@18.2.0,react-dom@18.2.0`, or you hit the `useState` null error. (ADR-0002.)\n4. **`cn(componentClasses, className)` call order** is the contract — caller's\n `className` must come last to win.\n5. **Token values in `src/theme/tokens.ts` are provisional** — not the real palette yet.\n\n## Suggested next steps (roughly in order)\n\n1. **See `Button` live** — add a showcase row to `kyla-ui-spike`'s `App.tsx` to eyeball\n all variant/size combos + hover/focus in a browser. (Quick loop-closer.)\n2. **Real palette + structural scales** — replace provisional tokens with AA-checked\n surface/fg/border ramps + spacing/radius/type scales. Highest-leverage deferred item.\n3. **More components** — `Card`, `Text`/`Heading`, `Input`, `Textarea`, `Label`, `Badge`,\n `Stack`, `Box`, `Divider`, then native-styled `Select`. Reuse the Button pattern.\n4. **`Dialog` (Radix)** — first component behind its own import path: `src/components/dialog.tsx`\n + a root `dialog.ts` re-export, kept OUT of `mod.ts` (ADR-0002). Exercises the split.\n5. **Gallery** — the library's self-hosted docs HTTP route (CONTEXT.md → \"Gallery\").\n6. **Starter** — `kyla-ui-starter`: a tiny todo app (CONTEXT.md → \"Starter\").\n\n## How to work in this repo\n\n- Edit locally, then `vt push` (and `vt pull` first if needed). `vt status` shows drift.\n- **Smoke-test pattern that works without a browser:** create a throwaway\n `src/_smoke.ts(x)` in the val, `run_file` it (use `renderToStaticMarkup` from\n `react-dom@18.2.0/server` to render components to a class string), then `delete_file`\n it. Used twice this thread; clean and fast.\n- For anything UI/platform-specific on Val Town, pull the official skill via the valtown\n MCP `find_val_town_skills` tool rather than working from memory.\n\n## Suggested skills for the next session\n\n- **valtown:react-ui** — the canonical conventions (Twind, React pin, view-source) for\n any component or Gallery work.\n- **grill-with-docs** — if revisiting design decisions (palette, theming v2, new\n components' APIs); it updates `CONTEXT.md` / ADRs inline.\n- **valtown:sqlite-storage** + **valtown:http-endpoints** — when building the Starter\n todo app and/or the Gallery route.\n- **rams** (or **impeccable**) — accessibility / visual-design review once there are\n enough components and the real palette to evaluate.\n",[],[226,407,400],"handoffs","4fcaf772-350f-455a-be01-06b6aa80fdf6",["D",1783373215838],[251],[226,407],"e694cb85-9e03-4583-80b7-36c6e28536bf","triage-labels.md","019f3953-b8df-70da-933b-07c96565ee56","019f3953-b8df-70da-933b-0ad85de5eb6d",["D",1783375727400],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |\n| `needs-info` | `needs-info` | Waiting on reporter for more information |\n| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |\n| `ready-for-human` | `ready-for-human` | Requires human implementation |\n| `wontfix` | `wontfix` | Will not be actioned |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the corresponding label string from this table.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n",[],[226,420,413],"agents","3932660b-fbc3-4033-b0ba-9b8642870329","issue-tracker.md","019f3953-b8df-70da-933b-033d2b846091",["D",1783375727400],"# Issue tracker: Local Markdown\n\nIssues and PRDs for this repo live as markdown files in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues//`\n- The PRD is `docs/issues//PRD.md`\n- Implementation issues are `docs/issues//issues/-.md`, numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)\n- Comments and conversation history append to the bottom of the file under a `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues//` (creating the directory if needed).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or the issue number directly.\n",[],[226,420,422],"a2003e30-4e1b-4812-8316-eee6f6c2f51f","domain.md","019f3953-b8df-70da-933a-fca9bd7ab51b",["D",1783373215838],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when exploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.\n\n## File structure\n\nSingle-context repo (most repos):\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│ ├── 0001-event-sourced-orders.md\n│ └── 0002-postgres-for-write-model.md\n└── src/\n```\n\nMulti-context repo (presence of `CONTEXT-MAP.md` at the root):\n\n```\n/\n├── CONTEXT-MAP.md\n├── docs/adr/ ← system-wide decisions\n└── src/\n ├── ordering/\n │ ├── CONTEXT.md\n │ └── docs/adr/ ← context-specific decisions\n └── billing/\n ├── CONTEXT.md\n └── docs/adr/\n```\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than silently overriding:\n\n> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_\n",[],[226,420,429],"d137c2ec-f763-4f54-baac-a73ff4c761da",["D",1783373215838],[247,248,249],[226,420],"7e28e964-955b-4e4c-90ab-48a186a7b84f","0004-version-pinned-upgrade-contract.md","019f3953-b8df-70da-933a-f75faa020c6f","019f3953-b8df-70da-933a-fb78b2decae4",["D",1783373215838],"# Upgrade contract: main-as-release-line, version pinning\n\nKylä UI is consumed by importing its val from esm.town, where an unpinned import (`.../kyla-ui/mod.ts`) auto-redirects to the val's latest version and a consumer can freeze onto a specific version with `?v=NNN`. esm.town does **not** offer branch-name import URLs, so the intuitive \"consumers track a long-lived `stable` branch\" model is not available.\n\nWe therefore make **`main` the stable/release line**: all development happens on feature/dev branches, and a **Release is a merge into `main`.** Because raw work never lands on `main`, HEAD-of-`main` is always a Release. Consumers then have two contracts:\n\n- **Track latest** — import the unpinned URL; always get the newest Release, so fixes auto-propagate (the upside of consumption-by-import).\n- **Freeze** — pin `?v=NNN` from the README's release table; upgrade deliberately by changing the number.\n\n## Considered Options\n\n- **Long-lived `stable` branch consumers import** — rejected: esm.town has no documented branch-import URL, so it isn't realizable.\n- **Live HEAD with raw development on the imported line** — rejected: any work-in-progress push would reach unpinned consumers; keeping development off `main` is what makes the unpinned URL safe.\n\n## Consequences\n\n- Unpinned consumers receive a new Release the instant a branch merges — *including a breaking one*. The release table plus brief per-release notes are how a consumer decides whether to pin. There is no staging window between merge and propagation.\n- Every merge to `main` mints a new `?v=NNN`; the README maps human release names to those version numbers.\n- For v1 (sole consumer is the maintainer) this can be operated loosely, but the convention costs nothing now and makes external consumption safe later.\n",[],[226,447,440],"adr","4d38025d-c0a1-4870-8818-45ff8e03f17f","0003-consistency-first-bounded-accessibility.md","019f3953-b8df-70da-933a-f1ab1fb0928e",["D",1783373215838],"# Consistency-first positioning, bounded accessibility\n\nKylä UI is modeled on Cloudflare Kumo, whose headline value is accessibility. We deliberately invert the emphasis: **Kylä leads with visual consistency** — the felt pain for the Val Town audience (people shipping apps fast without a designer) is that hand-assembled UIs look inconsistent, not that they fail an audit. Accessibility remains a real but *quiet* guarantee underneath, with a deliberately bounded scope for v1.\n\nThe accessibility commitment is exactly: **correct semantic HTML** (native `

{title}

Compare

Mergedcm31/mainintonbbaier/main