Open questions

?For reviewer

val-issue-tracker · Wireframes

Val Issue Tracker — app design

Low-fi structure pass over the tracker's four pages (edit issue mirrors the create form),\n restyled after the GitHub Issues interface per review: a slim top bar (Issues · Labels) on\n every screen, token search + stacked rows on the list, a metadata sidebar with per-section\n gears on detail, and a Write/Preview editor on create. Red dashed marks are the annotation\n layer, not proposed UI.

\n 5 wireframes\n Desktop 1280×800\n Lo-fi · monochrome\n Click any wireframe to zoom\n

\n\n \n

Flow

Screen flow

\n Solid arrows are navigation; labelled arrows note the trigger. Every mutating action\n on the detail page (close, reopen, label, assign, block, comment) POSTs and redirects back to the same page.

flow.svg1280×640

\n $\"Screen$ \n

\n\n \n

Screen 1 · Home

1.Issue list · `/`

\n GitHub-style landing page: slim top bar, a token search bar with the New issue\n button, and a list panel with Open/Closed tabs and stacked issue rows sorted by last activity.

\n issue-list.svg1280×800 · desktop

\n $\"Issue$ \n

Annotations

1 — Slim top bar replaces the sidebar: Issues and Labels tabs (active underlined), avatar and handle on the right. One shared Layout component across all screens; embeds compactly in host vals. Personal views (assigned/created by me) stay deferred.
2 — Token search bar replacing the separate filter fields: parse status: / assignee: tokens plus free text into the existing listIssues filters.
3 — Open/Closed tabs with count pills, replacing both the metric tiles and the status dropdown. Fits the strict two-state model.
4 — Label chips under each title carry the triage signal (ready-for-agent etc.) without a dedicated column.
5 — \"Blocked\" pill sits in the meta line before the issue number, as in GitHub.

\n Why this changes: adopts the GitHub list anatomy from review feedback.\n Stacked rows give titles a full line, make labels visible for triage scanning, and the\n token search collapses three filter controls into one input.

\n \n \n

\n\n \n

Screen 2 · Core

2.Issue detail · `/issue/:id`

\n GitHub-style detail under the shared top bar: title with number and edit pencil, a filled\n Open pill, the issue body as the first comment card, then the thread and composer; management\n lives in a right sidebar of hairline-divided sections, each with a gear.

\n issue-detail.svg1280×800 · desktop

\n $\"Issue$ \n

Annotations

1 — Filled Open pill (with state icon) plus outlined Blocked pill; the pencil beside the title goes to /issue/:id/edit.
2 — The body renders as the first comment card, with an Owner/role badge and \"edited\" provenance drawn from the events log.
3 — Sidebar sections (Assignees, Labels, Relationships, Delete) each with a gear that reveals the add/remove controls, instead of always-visible forms.
4 — \"Close issue\" with a reason chooser sits in the composer footer, GitHub-style: completed (default), not planned, duplicate. Reopen swaps in when closed.
5 — Relationships shows both edge directions with each blocker's open/closed state; adding an edge is rejected if it would create a cycle.

\n Why this changes: matches the GitHub issue view from review feedback.\n Reading and managing separate cleanly, and gear-reveals keep the sidebar quiet until you\n need to change something. Note the gear interaction needs a little client-side JS (or\n <details> disclosure) in an app that is currently zero-JS forms.

\n \n \n

\n\n \n

Screen 3 · Create

3.New issue · `/new`

\n GitHub-style \"Create new issue\": title and a Write/Preview markdown editor in the main\n column, assignees and labels in the right sidebar. The edit page (/issue/:id/edit)\n mirrors this with only title + body.

\n issue-new.svg1280×800 · desktop

\n $\"New$ \n

Annotations

1 — Write/Preview tabs on the description editor. Preview is marked roadmap: it activates once markdown rendering lands, and until then only Write shows.
2 — Assignees and labels move to a sidebar with gear-pickers; labels stay a curated set (picking, never typing). Handles remain unvalidated, noted in the sidebar.
3 — \"Create more\" checkbox for batch entry: on submit, redirect back to /new instead of the new issue.

\n Why this changes: matches the GitHub create screen from review feedback.\n The main column stays focused on writing; metadata moves out of the critical path.

\n \n \n

\n\n \n

Screen 4 · Admin

4.Labels · `/labels`

\n GitHub-style label management, shown with the inline create row expanded: New label\n reveals a form above the list (preview chip, name, color + swatch), and the panel lists one row\n per label with chip, hex color, open-issue count, and an overflow menu. Viewers see the list read-only.

\n labels.svg1280×800 · desktop

\n $\"Labels$ \n

Annotations

1 — Label creation, answered inline: \"New label\" (maintainer-only) expands this create row with a live preview chip, name input, and color input with swatch. It maps directly onto the existing POST /labels (name + color). Descriptions dropped per review.
2 — Open-issue count per label (one join query); clicking it filters the issue list to that label.
3 — Overflow menu holds edit (in-place row) and delete, gated to maintainers.

\n Why this changes: matches the GitHub labels screen from review feedback.\n Creation stays on this page rather than a separate screen, and the count makes delete's\n cascade visible before the click.

\n \n \n

\n\n \n

For reviewer

Open questions

JavaScript budget: The app is currently zero-JS server-rendered forms. Gear-pickers, token search highlighting, and Write/Preview tabs all want some client-side behavior. How much JS is acceptable, or should these degrade to <details> disclosures and plain form posts?
Token search: Parse status:/assignee: tokens server-side into the existing filters, or keep separate query params and just style one input?
Mobile: The tracker is server-rendered and embeddable; do we need dedicated 375px wireframes, or is a single responsive column acceptable?

\n\n

\n Wireframes follow the wireframe skill house style: black on white, 1.5pt strokes, 8px grid, type sizes 12/14/20/28. Red dashed annotations are the call-out layer only and not part of the proposed UI.\n

` (for example `https://username-myval.web.val.run`)\n\n**Auth**: reads are public. Writes require\n`Authorization: Bearer `. Each write may include `actor`,\na Val Town handle; omitted actors default to `agent`. Actor provenance is stored\nonly in the append-only events log.\n\n## Response shapes\n\nEvery response is JSON. Successful responses are either a single object, an\narray, or a small acknowledgement object (`{\"deleted\": id}` /\n`{\"updated\": id}`); error responses always have the shape:\n\n```json\n{ \"error\": \"human-readable message\" }\n```\n\n### Label\n\n```ts\n{\n id: number;\n name: string;\n color: string; // six lowercase hex characters, no leading \"#\"\n created_at: number; // ms since epoch\n updated_at: number;\n}\n```\n\n### IssueReference\n\nThe compact shape used inside `blockers` and `blocks`.\n\n```ts\n{\n id: number;\n title: string;\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n}\n```\n\n### Issue\n\n```ts\n{\n id: number;\n title: string;\n body: string; // markdown, verbatim (not trimmed)\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n created_at: number;\n updated_at: number; // last activity: own edits, comments, or association changes\n creator: string | null; // Val Town handle, derived from the issue's creation event\n labels: Label[];\n assignees: string[]; // Val Town handles, no \"@\" prefix\n blockers: IssueReference[];\n blocks: IssueReference[];\n blocked: boolean; // true iff at least one blocker is still \"open\"\n}\n```\n\n`GET /api/issues/:id` returns an `Issue` plus a `comments` field\n(`comments: Comment[]`); no other endpoint includes `comments`.\n\n### Comment\n\n```ts\n{\n id: number;\n issue_id: number;\n body: string; // markdown, verbatim\n created_at: number;\n updated_at: number;\n author: string | null; // Val Town handle, derived from the comment's creation event\n}\n```\n\n### Event\n\n```ts\n{\n id: number;\n event_type:\n | \"issue.created\" | \"issue.updated\" | \"issue.deleted\"\n | \"comment.created\" | \"comment.updated\" | \"comment.deleted\"\n | \"label.created\" | \"label.updated\" | \"label.deleted\";\n entity_id: number; // the issue/comment/label id the event is about\n actor: string;\n data: unknown; // grammar below\n event_timestamp: number;\n}\n```\n\n`GET /api/issues/:id/events` returns `Event[]` in append order.\n\n## Event data grammar\n\nEvents are the source of truth for provenance and history; live tables hold only\ncurrent state.\n\n- **Boundary events (`*.created`, `*.deleted`) snapshot full state.** The `data`\n field is the entity's complete state at that moment — a hard-deleted row\n leaves a full tombstone:\n - `issue.created` / `issue.deleted` data:\n `{id, title, body, status, state_reason, created_at, updated_at}`\n - `comment.created` / `comment.deleted` data:\n `{id, issue_id, body, created_at, updated_at}` (no `author` — that is always\n derived from the surrounding event, never stored in the payload)\n - `label.created` / `label.deleted` data:\n `{id, name, color, created_at, updated_at}`\n- **`*.updated` events carry a single field delta:**\n `{update_target, from, to}`.\n - For `issue.updated`, `update_target` is one of `title`, `body`, `status`,\n `state_reason`, `label`, `assignee`, `blocks`, `blocked_by`. Associations\n (`label`, `assignee`, `blocks`, `blocked_by`) use **`null ↔ value`**\n (`from: null` = added, `to: null` = removed). A block edge writes exactly\n one event, on the acting issue (the one named in the endpoint path).\n - For `comment.updated`, `update_target` is `\"body\"`.\n - For `label.updated`, `update_target` is `\"name\"` or `\"color\"`.\n - One event per changed field: closing an issue with a new reason emits two\n `issue.updated` events (`status` and `state_reason`), sharing one actor and\n timestamp.\n\n## Status codes\n\n| Status | Meaning |\n| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `200` | Read succeeded, or a mutation applied and the endpoint returns the resulting state. |\n| `201` | An issue, comment, or label was created. |\n| `400` | The request is malformed: invalid `:id`, invalid `status` filter, invalid close `reason`, invalid label `color`, a missing required scalar field (`title`; `name`/`color`; comment `body`), or a collection field (`label_ids`, `add`, `remove`, `assignees`) that isn't shaped as required — see below. |\n| `401` | A write was attempted with a missing or incorrect bearer token. |\n| `403` | A write was attempted but `ISSUE_TRACKER_API_KEY` isn't configured, so writes are disabled entirely. |\n| `404` | The issue, comment, or label named by `:id` — or referenced by an ID inside `label_ids`/`add`/`remove` — does not exist. |\n| `409` | The write conflicts with an existing invariant: a blocking edge would create a cycle (including a self-edge), or a label `name` collides with an existing label. |\n\n## Strict collection validation\n\n`label_ids`, and the `add`/`remove` fields on the labels and blocks/blocked-by\nendpoints, are validated as a whole, not filtered element by element:\n\n- **Absent** — treated as an empty operation (no IDs added or removed).\n- **Present** — must be an array where every element is a positive integer\n (`Number.isInteger(x) && x > 0`). Any other shape (not an array, a\n non-integer, zero, a negative number, a string, etc.) rejects the entire\n request with `400`; nothing is applied.\n- Each ID that passes shape validation must still reference an existing label or\n issue, or the request fails with `404`.\n\n`assignees`, and the `add`/`remove` fields on the assignees endpoint, follow the\nsame absent-is-empty / present-is-all-or-nothing rule, but for handles:\n\n- **Present** — must be an array of non-empty strings after trimming and\n stripping a leading `@`. Any other shape rejects the request with `400`.\n- Handles are not entities (no lookup table), so there is no `404` for an\n unrecognized assignee — any well-shaped handle is accepted.\n\n## Endpoints\n\n| Method and path | Body / query | Success |\n| --------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `GET /api/issues` | `?status=open\\|closed&label=&assignee=&search=` | `200` `Issue[]`. `400` if `status` is present and not `open`/`closed`. |\n| `POST /api/issues` | `{title, body?, label_ids?: number[], assignees?: string[], actor?}` | `201` `Issue`. `400` missing `title` or malformed `label_ids`/`assignees`. `404` if a `label_ids` entry doesn't exist. |\n| `GET /api/issues/:id` | — | `200` `Issue & {comments: Comment[]}`. `400` invalid id. `404` missing issue. |\n| `PATCH /api/issues/:id` | `{title?, body?, actor?}` | `200` updated `Issue`. `400` invalid id. `404` missing issue. |\n| `DELETE /api/issues/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/close` | `{reason?: \"completed\" \\| \"not_planned\" \\| \"duplicate\", comment?, actor?}` | `200` updated `Issue`; reason defaults to `completed`. `400` invalid id/reason. `404` missing issue. |\n| `POST /api/issues/:id/reopen` | `{actor?}` | `200` updated `Issue` with `state_reason: \"reopened\"`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/labels` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or a missing label id. |\n| `POST /api/issues/:id/assignees` | `{add?: string[], remove?: string[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue. |\n| `POST /api/issues/:id/blocks` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or referenced issue id. `409` cycle or self-edge. |\n| `POST /api/issues/:id/blocked-by` | `{add?: number[], remove?: number[], actor?}` | Same as `/blocks`, opposite edge direction. |\n| `POST /api/issues/:id/comments` | `{body, actor?}` | `201` `Comment`. `400` invalid id or missing `body`. `404` missing issue. |\n| `PATCH /api/comments/:id` | `{body, actor?}` | `200` `{updated: id}`. `400` invalid id or missing `body`. `404` missing comment. |\n| `DELETE /api/comments/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing comment. |\n| `GET /api/issues/:id/events` | — | `200` `Event[]` in append order. `400` invalid id. `404` missing issue. |\n| `GET /api/labels` | — | `200` `Label[]`. |\n| `POST /api/labels` | `{name, color, actor?}` | `201` `Label` (`color` is hex, with or without `#`). `400` missing `name`/`color` or invalid `color`. `409` `name` already in use. |\n| `PATCH /api/labels/:id` | `{name?, color?, actor?}` | `200` updated `Label`. `400` invalid id or `color`. `404` missing label. `409` renaming to an in-use `name`. |\n| `DELETE /api/labels/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing label. |\n\nAll write routes additionally return `401` for a missing/incorrect bearer token,\nand `403` if `ISSUE_TRACKER_API_KEY` is unset — checked before any body or id\nvalidation.\n\n## Triage labels\n\nLabels are curated entities, not free-text arrays. Before applying workflow\nlabels such as `needs-triage`, create each one once with `POST /api/labels`,\nretain its ID, then send that ID to the issue-label endpoint. The product's\nfresh-install defaults are `bug`, `enhancement`, `documentation`, `question`,\nand `duplicate`.\n\n## curl examples\n\n```bash\nTRACKER=https://your-handle-your-val.web.val.run\nKEY=...\n\n# Discover label IDs\ncurl -s \"$TRACKER/api/labels\"\n\n# Create with curated labels and multiple assignees\ncurl -s -X POST \"$TRACKER/api/issues\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Fix flaky test\",\"body\":\"Observed in CI\",\"label_ids\":[1],\"assignees\":[\"alice\"],\"actor\":\"alice\"}'\n\n# Close as deliberately not planned\ncurl -s -X POST \"$TRACKER/api/issues/12/close\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"not_planned\",\"comment\":\"Superseded by #15.\",\"actor\":\"alice\"}'\n\n# Reopen\ncurl -s -X POST \"$TRACKER/api/issues/12/reopen\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"actor\":\"alice\"}'\n\n# Declare that #12 blocks #15\ncurl -s -X POST \"$TRACKER/api/issues/12/blocks\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"add\":[15],\"actor\":\"alice\"}'\n```\n",[],[178,543],"44bf1ff5-2ddc-48a7-ba48-5648cd000374","backlog.md","eea1bf8a-7bf2-11f1-975e-1607ee4eb77e",368,["D",1784092022503],"# Backlog — deferred wants\n\nThings wanted eventually, not now. Not commitments; parking lot.\n\n- **Clickable user handles.** Wherever a user handle is displayed (creator,\n comment author, assignee), render it as a link to that user's Val Town\n profile. Purely a rendering concern — the data model just stores the handle.\n (See [[User]] in CONTEXT.md.)\n- **Markdown rendering.** Issue bodies and comment bodies are stored as\n markdown; rendering them to HTML is a later concern.\n- **`DESIGN.md` component conformance.** The follow-on to\n `docs/issues/valtown-native-ui/spec.md`, which specced the foundation\n (palette, fonts, dual-scheme — landed) and defers the component-level Named\n Rules to here: The Machine Facts Rule (mono for issue numbers, handles,\n timestamps), The Hairline Rule and The No-Card Rule (one panel of hairline\n rows), The One Bold Rule and issue-row anatomy, The Badge Containment Rule,\n the status pill as a tinted pair, and hover along the `sky` ramp. Each needs\n visual judgment rather than measurement, which is why it wasn't in the\n foundation spec. Unblocked now that the foundation spec has landed — the\n tokens are in place.\n- **Visible focus ring.** Tracked as\n `docs/issues/valtown-native-ui/issues/07-focus-ring.md` — a real PRD\n requirement (user stories 23–24) that fell out of the foundation spec's ticket\n breakdown. Unlike the conformance items above this is measurable, not a\n judgment call, so it's its own `ready-for-agent` ticket rather than parked\n here.\n",[],[178,551],"3a3e928d-1e27-45cf-832b-40731eacf89d","spec.md","911c9a22-8004-11f1-821c-1607ee4eb77e",331,["D",1784089252790],"# PRD: Val Town-native UI foundation\n\nStatus: ready-for-agent\n\n`DESIGN.md` is the normative target for this work; its YAML frontmatter carries\nthe tokens. `PRODUCT.md` carries the strategy. This spec covers the\n**foundation** of that migration — the layer whose correctness is decidable by\nmeasurement. Purely aesthetic conformance to the component-level Named Rules is\nexplicitly deferred (see Out of Scope).\n\nThis supersedes the \"Migrate the UI to `DESIGN.md`\" entry in `docs/backlog.md`.\nThat entry estimated the work as \"mostly `theme.ts` and `layout.tsx`\". That\nestimate is wrong, and the reason is the core of this spec: flipping the canvas\nbreaks colors that no token controls.\n\n## Problem Statement\n\nThe tracker wears a generic dark-SaaS costume — blue-charcoal surfaces\n(`#0f1115`), a bare system font stack, and a saturated blue accent. `PRODUCT.md`\nnames this exact combination as an anti-reference and as \"the specific thing\nthat makes this UI 'not look good'\". It is also a dark-only surface, so a\ntracker mounted in a light Val Town host renders as a dark island in a light\npage — which contradicts the \"it embeds politely\" principle directly. A guest\nthat ignores its host's color scheme is a rude guest.\n\nUnderneath the cosmetic problem sit measurable defects the maintainer cannot see\nbut does feel:\n\n- Four of the five seeded Labels are **illegible on a light canvas**. The Label\n chip paints the stored color as text on a transparent fill, which works\n against black and fails against white. `enhancement` (`a2eeef`) measures\n 1.31:1 on white; `duplicate` (`cfd3d7`) 1.51:1; `question` (`d876e3`) 2.76:1.\n Separately, `documentation` (`0075ca`) already fails **today** at 4.40:1 on\n the current dark canvas.\n- The open/closed **state icon** — the single most-scanned signal in the list —\n is hardcoded to a color that measures 1.74:1 on white. It disappears.\n- The Banner hardcodes dark-only tints, so on a light canvas it renders as a\n near-black island.\n- Every button and input has **no height mechanism at all**. The code says\n `min-h-10`, intending 40px, but the project's Twind build predates Tailwind's\n numeric `min-h-*` scale and emits no rule for it. Controls are sized by\n line-height alone (~20–24px), far under the 44px touch-target floor. The 40px\n everyone believes is there has never existed.\n\nThe last four are not migration risks. They are live defects, and three of them\nare invisible until the canvas flips.\n\n## Solution\n\nMigrate the tracker's visual foundation to the Val Town-native system already\ndocumented in `DESIGN.md`: an achromatic canvas (true white / true black),\nstructure carried by slate hairlines, the stock `sky` ramp as the only accent,\nIBM Plex Sans for interface text with iA Writer Mono for machine facts, and\n**dual-scheme rendering driven by `prefers-color-scheme`** so the tracker\nfollows whatever its host val is showing.\n\nThe migration is made cheap by one discovery: because every palette token feeds\na color slot and none appear in a `style` attribute, the palette module's\n**values** can change from hex literals to typed CSS variable references while\nevery one of its ~107 call sites stays byte-identical. The scheme switch then\nlives in one generated stylesheet block rather than in a `dark:` variant at\nevery call site.\n\nColors that no token controls — the Banner tints, the state icon, the status\npill, and user-authored Label colors — are brought under the token system or\nmade scheme-aware at render time. Label color is handled without touching stored\ndata: the stored hex remains the source of truth, and legibility is achieved by\nadapting lightness per scheme at render.\n\nEverything stays server-rendered and works with zero client-side JavaScript.\n\n## User Stories\n\n1. As a maintainer triaging in a light Val Town host, I want the tracker to\n render light, so that it does not sit in my page as a dark island.\n2. As a maintainer triaging in a dark Val Town host, I want the tracker to\n render dark, so that it continues to match its surroundings as it does today.\n3. As a maintainer whose host follows the OS scheme, I want the tracker to\n follow it too, so that I never configure the tracker's appearance separately.\n4. As a Val Town developer mounting the tracker, I want it to look like it\n belongs to the platform, so that it reads as native chrome rather than a\n third-party widget competing with my val.\n5. As a Val Town developer, I want the tracker to inherit the platform's own\n typographic identity, so that it does not announce itself as foreign.\n6. As a maintainer scanning the list, I want the interface set in IBM Plex Sans\n rather than a system stack, so that the UI reads as precise rather than\n generic.\n7. As a maintainer, I want the fonts to load without a flash of unstyled or\n invisible text, so that scanning is not interrupted on every navigation.\n8. As a maintainer on a slow or offline connection, I want the interface to stay\n fully legible if the webfonts never arrive, so that the tracker degrades to a\n sane fallback rather than breaking.\n9. As a maintainer scanning the list, I want the open/closed state icon to be\n clearly visible in both schemes, so that I can tell an Issue's Status at a\n glance — the thing the list exists for.\n10. As a maintainer scanning the list, I want every Label chip legible in both\n schemes, so that I can spot triage signal without opening an Issue.\n11. As a user who authored a Label color, I want my color to remain recognizably\n my color in both schemes, so that the chip still reads as the one I chose.\n12. As a user who authored a Label color, I want my stored color left untouched,\n so that switching schemes never silently rewrites my data.\n13. As a maintainer, I want the `documentation` Label to be legible on the dark\n canvas, so that a defect that exists today is fixed rather than carried\n forward.\n14. As a maintainer, I want a Label whose color is near-white to stay visible on\n a white canvas, so that no Label can be rendered invisible by its own color.\n15. As a maintainer, I want a Label whose color is near-black to stay visible on\n a black canvas, so that the same guarantee holds symmetrically.\n16. As a maintainer receiving a success or error Banner, I want it legible and\n correctly tinted in both schemes, so that feedback never renders as a dark\n block on a light page.\n17. As a maintainer, I want the Status pill legible in both schemes, so that\n lifecycle state never rides on an off-brand saturated fill.\n18. As a maintainer, I want state to be conveyed by icon or text as well as\n color, so that Status never rides on color alone.\n19. As a maintainer clicking a primary action, I want its label readable against\n its fill, so that the button is not the least legible element on the page.\n20. As a maintainer hovering a destructive action, I want its label readable\n against the hover fill, so that the most dangerous control is not the least\n legible.\n21. As a maintainer on a touch device, I want buttons and inputs large enough to\n tap reliably, so that I am not fighting 20px targets.\n22. As a maintainer, I want controls to have a real, working height mechanism,\n so that the intended control height is what actually renders.\n23. As a keyboard user, I want a visible focus ring on every interactive element\n in both schemes, so that the zero-JS form-driven flow stays navigable.\n24. As a keyboard user, I want the focus ring to be visible against both the\n white and black canvas, so that focus is never lost against its background.\n25. As a maintainer reading body and meta text, I want it comfortably readable\n in both schemes, so that scanning density does not cost legibility.\n26. As a developer changing a palette value, I want to change it in exactly one\n place, so that the palette stays a single source of truth.\n27. As a developer changing a fill color, I want the obligation to re-check its\n ink contrast to be visible at the point of change, so that I cannot\n introduce an unreadable pairing without noticing.\n28. As a developer, I want a test to fail if a color utility silently compiles\n to the wrong CSS property, so that the class of bug that made `min-h-10`\n dead cannot recur silently.\n29. As a developer, I want a test to fail if any palette pair drops below its\n contrast floor, so that contrast is enforced rather than audited.\n30. As a developer, I want a test to fail if a scheme leaves any variable\n undefined, so that one scheme cannot silently render with missing colors.\n31. As a developer, I want the migration to leave every call site untouched, so\n that the diff is reviewable and the risk is concentrated in one module.\n32. As an agent working the tracker through the JSON API, I want no API or\n schema change, so that this migration is invisible to me.\n33. As a maintainer, I want the existing routes, role model, storage, and API\n untouched, so that a visual migration cannot break behavior.\n34. As a maintainer, I want the tracker to remain fully functional with zero\n client-side JavaScript, so that the PRD-level zero-JS contract survives.\n\n## Implementation Decisions\n\n### The palette module becomes typed CSS variable references\n\nThe palette module keeps its current key names and gains a second export. Its\n`T` values change from hex literals to **typed** CSS variable references; a new\nexport carries the per-scheme hex tables that the layout shell renders into a\nstylesheet block and that the contrast test asserts over.\n\nBecause every call site interpolates `T.x` inside a Twind arbitrary-value\nbracket (`text-[${T.text}]`), and no token appears in a `style` attribute, all\ncall sites remain byte-identical. Verified against the real class strings: the\nsix prefixes tokens feed are `bg`, `border`, `focus:border`, `hover:bg`,\n`hover:text`, and `text` — all color slots.\n\n### The `color:` type hint is mandatory and non-obvious\n\nThis came out of a prototype and encodes the decision more precisely than prose\ncan. Twind infers the CSS property from the _shape_ of an arbitrary value. A\nbare `var()` is untyped, so it guesses wrong — **silently**, with no error:\n\n```\ntext-[var(--ink)] -> font-size: var(--ink) WRONG\nbg-[var(--canvas)] -> background-image: var(--canvas) WRONG\nborder-[var(--rule)] -> border-width: var(--rule) WRONG\n\ntext-[color:var(--ink)] -> color: var(--ink) correct\nbg-[color:var(--canvas)] -> background-color: var(--canvas) correct\nborder-[color:var(--rule)] -> border-color: var(--rule) correct\n```\n\nSo token values must embed the hint (`text: \"color:var(--ink)\"`), not just the\n`var()`. Confirmed to hold through `hover:` and `focus:` variants and the ring\ncolor. Anyone attempting this without the hint will conclude CSS variables are\nincompatible with Twind and fall back to doubling every call site with `dark:`\nvariants — which is the expensive, wrong path.\n\n### Dual-scheme lives in one generated stylesheet block\n\nThe layout shell renders a `

Flow

Screens

Open questions

Screen flow

1.Issue list · /

Annotations

2.Issue detail · /issue/:id

Annotations

3.New issue · /new

Annotations

4.Labels · /labels

Annotations

Open questions

1.Issue list · `/`

2.Issue detail · `/issue/:id`

3.New issue · `/new`

4.Labels · `/labels`

History · issues