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

= {\n open: \"Open\",\n closed: \"Closed\",\n};\nexport const STATE_REASON_LABELS: Record, string> = {\n completed: \"Completed\",\n not_planned: \"Not planned\",\n duplicate: \"Duplicate\",\n reopened: \"Reopened\",\n};\n\nexport const Card: FC> = ({\n children,\n class: cls,\n}) => (\n \n {children}\n \n);\n\nexport const Button: FC<\n PropsWithChildren<{\n variant?: keyof typeof VARIANTS;\n href?: string;\n type?: \"button\" | \"submit\";\n class?: string;\n name?: string;\n value?: string;\n form?: string;\n }>\n> = ({\n variant = \"solid\",\n href,\n type = \"button\",\n class: cls,\n name,\n value,\n form,\n children,\n}) => {\n const classes = `${BUTTON} ${VARIANTS[variant]} ${cls ?? \"\"}`;\n return href\n ? (\n \n {children}\n \n )\n : (\n \n {children}\n \n );\n};\n\nexport const Select: FC<\n PropsWithChildren<{ name: string; id?: string; class?: string }>\n> = ({ name, id, class: cls, children }) => (\n \n);\n\nexport const Banner: FC<{ kind: \"ok\" | \"err\"; msg: string }> = ({\n kind,\n msg,\n}) => (\n \n {msg}\n \n);\n\nexport const StatusBadge: FC<{ status: IssueStatus; reason?: StateReason }> = ({\n status,\n reason,\n}) => (\n \n {STATUS_LABELS[status]}\n {reason ? ` · ${STATE_REASON_LABELS[reason]}` : \"\"}\n \n);\n\nexport const LabelTag: FC<{ label: Label }> = ({ label }) => (\n \n {label.name}\n \n);\n","children",[],[238],"47ddee41-3a79-4b55-846e-57c64446692d","theme_test.ts","a65d7e0a-800a-11f1-bec8-1607ee4eb77e",357,["D",1784091865144],"import { assert, assertEquals, assertMatch } from \"jsr:@std/assert@1.0.19\";\nimport {\n adaptLabelColor,\n INK_FILL_PAIRS,\n renderSchemeStylesheet,\n SCHEMES,\n T,\n} from \"./theme.ts\";\n\nfunction hexToRgb(hex: string): [number, number, number] {\n const n = Number.parseInt(hex.replace(/^#/, \"\"), 16);\n return [(n >> 16) & 255, (n >> 8) & 255, n & 255];\n}\n\nfunction srgbToLinear(c: number): number {\n const v = c / 255;\n return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;\n}\n\nfunction relativeLuminance(hex: string): number {\n const [r, g, b] = hexToRgb(hex).map(srgbToLinear);\n return 0.2126 * r + 0.7152 * g + 0.0722 * b;\n}\n\nfunction contrastRatio(hexA: string, hexB: string): number {\n const a = relativeLuminance(hexA);\n const b = relativeLuminance(hexB);\n const [hi, lo] = a > b ? [a, b] : [b, a];\n return (hi + 0.05) / (lo + 0.05);\n}\n\nfunction hueOf(hex: string): number | null {\n const [r, g, b] = hexToRgb(hex).map((v) => v / 255);\n const max = Math.max(r, g, b), min = Math.min(r, g, b);\n if (max - min < 1e-3) return null; // achromatic — hue undefined\n let h: number;\n if (max === r) h = ((g - b) / (max - min)) % 6;\n else if (max === g) h = (b - r) / (max - min) + 2;\n else h = (r - g) / (max - min) + 4;\n h *= 60;\n return h < 0 ? h + 360 : h;\n}\n\nDeno.test(\"every ink/fill pair clears 4.5:1 in both schemes\", () => {\n for (const [ink, fill] of INK_FILL_PAIRS) {\n for (const scheme of [\"light\", \"dark\"] as const) {\n const ratio = contrastRatio(SCHEMES[ink][scheme], SCHEMES[fill][scheme]);\n assert(\n ratio >= 4.5,\n `${ink} on ${fill} (${scheme}) is ${ratio.toFixed(2)}:1, below 4.5:1`,\n );\n }\n }\n});\n\nDeno.test(\"both schemes define every variable — neither omits one\", () => {\n for (const key of Object.keys(SCHEMES) as Array) {\n const value = SCHEMES[key];\n assert(typeof value.light === \"string\" && value.light.length > 0);\n assert(typeof value.dark === \"string\" && value.dark.length > 0);\n }\n});\n\nDeno.test(\"T's values are typed CSS variable references, not hex literals\", () => {\n for (const key of Object.keys(SCHEMES) as Array) {\n assertMatch(T[key], /^color:var\$--[a-z-]+\$$/);\n }\n});\n\nDeno.test(\"renderSchemeStylesheet emits a :root block and a dark media block\", () => {\n const css = renderSchemeStylesheet();\n assertMatch(css, /^:root\\{/);\n assertMatch(css, /@media \$prefers-color-scheme:dark\$\\{:root\\{/);\n for (const key of Object.keys(SCHEMES) as Array) {\n const varName = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);\n assertMatch(css, new RegExp(`--${varName}:${SCHEMES[key].light}`));\n assertMatch(css, new RegExp(`--${varName}:${SCHEMES[key].dark}`));\n }\n});\n\nconst ADVERSARIAL_LABEL_COLORS = [\n \"d73a4a\", // bug (seeded)\n \"a2eeef\", // enhancement (seeded) — the 1.31:1-on-white defect\n \"0075ca\", // documentation (seeded) — the 4.40:1-on-dark defect\n \"d876e3\", // question (seeded)\n \"cfd3d7\", // duplicate (seeded)\n \"fefefe\", // near-white\n \"010101\", // near-black\n \"ff0000\", // fully saturated\n \"808080\", // achromatic\n];\n\nDeno.test(\"adaptLabelColor clears 4.5:1 against both canvases\", () => {\n for (const hex of ADVERSARIAL_LABEL_COLORS) {\n const { light, dark } = adaptLabelColor(hex);\n const onWhite = contrastRatio(light, \"#ffffff\");\n const onBlack = contrastRatio(dark, \"#000000\");\n assert(\n onWhite >= 4.5,\n `#${hex} adapted for light (${light}) is ${\n onWhite.toFixed(2)\n }:1 on white`,\n );\n assert(\n onBlack >= 4.5,\n `#${hex} adapted for dark (${dark}) is ${onBlack.toFixed(2)}:1 on black`,\n );\n }\n});\n\nDeno.test(\"adaptLabelColor preserves hue\", () => {\n for (const hex of ADVERSARIAL_LABEL_COLORS) {\n const sourceHue = hueOf(`#${hex}`);\n const { light, dark } = adaptLabelColor(hex);\n if (sourceHue === null) continue; // achromatic input has no hue to preserve\n for (const adapted of [light, dark]) {\n const adaptedHue = hueOf(adapted);\n if (adaptedHue === null) continue; // gamut clamp pushed chroma to ~0\n const delta = Math.min(\n Math.abs(adaptedHue - sourceHue),\n 360 - Math.abs(adaptedHue - sourceHue),\n );\n assert(\n delta < 5,\n `#${hex} hue ${sourceHue.toFixed(1)} drifted to ${\n adaptedHue.toFixed(1)\n } (${adapted})`,\n );\n }\n }\n});\n\nDeno.test(\"adaptLabelColor is idempotent and deterministic\", () => {\n for (const hex of ADVERSARIAL_LABEL_COLORS) {\n const first = adaptLabelColor(hex);\n const second = adaptLabelColor(hex);\n assertEquals(first, second);\n\n const reapplied = {\n light: adaptLabelColor(first.light.replace(\"#\", \"\")).light,\n dark: adaptLabelColor(first.dark.replace(\"#\", \"\")).dark,\n };\n assertEquals(reapplied, first);\n }\n});\n\nDeno.test(\"adaptLabelColor accepts hex with or without a leading #\", () => {\n assertEquals(adaptLabelColor(\"d73a4a\"), adaptLabelColor(\"#d73a4a\"));\n});\n",[],[250],"76ace744-e98a-42fa-99b1-de1b591cfac8","theme.ts","743531d4-7fba-11f1-b433-1607ee4eb77e",359,["D",1784091865898],2,"/**\n * Single source of truth for the recurring palette values used across\n * layout.tsx, ui.tsx, and components.tsx. Presentation-only — no local\n * imports, so importing this file can never create a cycle.\n *\n * `T`'s values are typed CSS variable references, not hex literals. The\n * `color:` type hint is mandatory: Twind infers the CSS property from the\n * *shape* of an arbitrary value, and a bare `var()` is misparsed as the\n * wrong property with no error (`text-[var(--ink)]` compiles to\n * `font-size: var(--ink)`). `text-[color:var(--ink)]` compiles correctly.\n *\n * `SCHEMES` carries the light/dark hex each variable resolves to. The\n * layout shell renders these into 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 · index.html