# 0017. UI skeleton: ui/, ichor-ui as a separate binary, building without it

Status: Accepted · Date: 2026-10-25 · Design section: CLI and UI

Decided: Settled `ui/`'s directory, `cmd/ichor-ui` as a second binary, and how the Go side builds without the UI present

## Context

Phase 5 is the UI skeleton only: scaffolding, not screens. The design
(`docs/design/architecture.md`, "CLI and UI" and "Overview") already settles
several things that would otherwise need deciding here: the frontend is "a
Vite + Preact + TypeScript SPA built with preactcn, embedded in the Go
backend"; the backend is a named deliverable, `ichor-ui`, "a Go backend that
embeds the Preact SPA. It reads and writes CRs, reads logs and state from the
Talos API, and never writes to nodes"; and "the CLI and the UI backend are
added beside [`cmd/main.go`]". What was left open: the frontend directory
name, where `ichor-ui`'s source lives, how `npx shadcn@latest add
@preactcn/...` is actually wired up for a non-React project, which preactcn
components to install for a skeleton, and — the one with teeth — how to keep
`go build ./...`/`go vet ./...`/golangci-lint working for anyone who never
touches the UI, given the Go side embeds its output.

Constraints already fixed by `CLAUDE.md`: preactcn only, no React, no
`preact/compat`; components come from the shadcn CLI against the `@preactcn`
registry, never hand-written; the browser talks only to the backend, never to
a third-party host directly.

## Decision

**Directory and binary.** The frontend lives at `ui/` (plain, matches the
design's "the UI" with no other candidate name in play). The backend is
`cmd/ichor-ui/`, a second `main` package beside the controller's
`cmd/main.go`, per the design's explicit "added beside it" and the `ichor-ui`
name it already assigns. It does not import `pkg/`, `internal/` or `api/`
yet — this phase has no Connect API client and no CR reads/writes to wire up,
so there is nothing shared to pull in. It imports nothing from `cmd/` either,
matching "deliverables don't import each other."

**Scaffolding, done with the CLIs the rules require.**
- `npm create vite@latest ui -- --template preact-ts` (create-vite 9.3.1) —
  Preact 10.29.8, Vite 8.3.4, zero React.
- preactcn (https://github.com/maeshinshin/preactcn) ships no Vite/Preact
  `shadcn init` template — there isn't one upstream for Preact — so its own
  README spells out the equivalent by hand: install `tailwindcss
  @tailwindcss/vite tw-animate-css shadcn`, add the Tailwind Vite plugin and a
  `@/*` path alias in `vite.config.ts`/`tsconfig*.json`, and write
  `components.json` pointing `registries."@preactcn"` at
  `https://maeshinshin.github.io/preactcn/r/{name}.json`. That
  `components.json` is configuration, not a component, so writing it by hand
  from preactcn's own documented recipe doesn't violate "scaffold with the
  tools, never by hand" — there is no tool for it.
- Components: `npx shadcn@latest add @preactcn/button @preactcn/card
  @preactcn/separator` (shadcn CLI 4.22.1). Three, matching "レイアウトやボタン"
  in the task: `Button` and `Separator` build the nav shell, `Card` is the
  page container every placeholder screen uses. The CLI wrote
  `src/components/ui/{button,card,separator}.tsx` plus the Radix-for-Preact
  interop it depends on under `src/lib/radix/` and `src/lib/utils.ts` — all
  generated, all Preact, no `react` or `react-dom` anywhere (verified against
  `package-lock.json`).
- The shadcn `add` step does not also write Tailwind's `:root`/`.dark`
  variable block (there is no Preact `init` to do it, and `add` only touches
  component files) — without it, the components' `bg-primary`/`border-border`
  etc. classes exist in markup but resolve to nothing. The `shadcn` npm
  package exports its shared utility layer as `shadcn/tailwind.css`
  (confirmed in `node_modules/shadcn/package.json`'s `exports` map), and
  ui.shadcn.com/docs/theming publishes the standard oklch `:root`/`.dark`
  variable block for Tailwind v4. `src/index.css` imports the former and
  defines the latter; both are checked in since generating them isn't a
  component-install step either.

**Building without the UI.** `cmd/ichor-ui` has no screens to speak of yet,
but it still has to compile for anyone who only runs `go build`/`go
vet`/golangci-lint, before `ui/` is ever touched. Two separate problems, two
separate fixes:
- `embed.FS` needs *something* to embed at compile time. `webfs_dev.go`
  (`//go:build !uiembed`, the default) embeds a committed
  `cmd/ichor-ui/placeholder/index.html`. `webfs_embed.go` (`//go:build
  uiembed`) embeds `cmd/ichor-ui/dist`, which only exists after `make
  ui-build` — Vite's `build.outDir` points straight at it, no copy step.
  Because the two files carry mutually exclusive build tags, only one
  `//go:embed` directive is ever evaluated, so the missing `dist/` directory
  is never a problem for the default build. `make build-ichor-ui` runs
  `ui-build` then `go build -tags uiembed`.
- Separately: `go build ./...`, `go vet ./...` and `go test ./...` walk the
  whole module by directory, and npm dependencies are not obliged to contain
  only JavaScript — `ui/node_modules/flatted` vendors a Go port of itself,
  and it showed up in `go test ./...` output and in a first, broken
  `golangci-lint run` (`forbid-sort-pkg` tripped inside it). `ui/go.mod`
  gives `ui/` its own module boundary, which is enough for `./...` from the
  repo root to skip it entirely — confirmed by `go list ./...` and
  `golangci-lint run` before and after, with no further `.golangci.yml`
  change needed: golangci-lint resolves packages the same way `go list`
  does, so the module boundary alone was sufficient. An explicit `^ui/`
  path exclusion in `.golangci.yml` was tried first and found to add
  nothing once the module boundary was in place, so it was dropped —
  `.golangci.yml` ships from this phase unchanged.

**Serving.** `cmd/ichor-ui/main.go` is deliberately small: one
`http.FileServerFS` over whichever `fs.FS` the build tag selected, wrapped so
a path that doesn't exist in that FS is rewritten to `/` and re-served —
the standard SPA fallback, so client-side routes 200 instead of 404. A
`-addr` flag and `signal.NotifyContext`/`srv.Shutdown` round it out. No
health endpoint, no metrics, no streaming: none of that exists to serve yet.

**App shell.** `src/router.tsx` is a ~30-line History-API router (`usePath`,
`navigate`, `Link`) rather than a dependency — `preact-router` or similar
would be the obvious reach, but a route table with one page component
doesn't need one, and ponytail's "does this need to exist" answer here is no.
`src/pages/Placeholder.tsx` is the one page component every route renders
("Coming soon" in a `Card`); `src/app.tsx` wires two routes (`/`, `/gitops`)
through it with `Button`/`Separator` for the nav, standing in for the real
nav this skeleton doesn't build.

## Consequences

- Adding a fourth screen later is "add a route table entry and a page
  component," not a framework change.
- `ui/go.mod` means `ui/` packages (there are none, and shouldn't be any)
  would need an explicit `GOWORK`/replace to be imported from the main
  module — moot today since nothing does, or should.
- The base Tailwind theme is the stock shadcn neutral/oklch palette, picked
  for being well-documented and exactly reproducible, not reviewed for
  Ichor's actual visual identity. Expected to be revisited once there's a
  real screen to look at.
- `spaHandler`'s fallback branch is covered by a table test
  (`cmd/ichor-ui/main_test.go`, `TestSpaHandler`) against a synthetic
  `testing/fstest.MapFS` — an existing path is served as-is, an unknown path
  falls back to `index.html` with `200`. It doesn't depend on either
  `embed.FS` variant, so it runs the same under the default build and
  `-tags uiembed`.
- There is currently no path that ships `ichor-ui` anywhere. `-tags uiembed`
  is wired into exactly one place, `make build-ichor-ui`; `.goreleaser.yaml`
  builds only `./cmd/ichor`, and no container image or chart `Deployment`
  references `ichor-ui` at all. That's correct for a skeleton phase — there's
  nothing worth shipping yet — but it means today's repo can produce a
  `bin/manager` and a CLI release without ever touching the UI, and a
  `build-ichor-ui` run that silently used the default tag would ship the
  placeholder page instead of an error. The phase that actually ships the UI
  needs to add `ichor-ui` to goreleaser, a container image, and a
  `Deployment` in the chart (with the two-replica/PDB/anti-affinity shape
  "CLI and UI" describes), and should make building it the wrong way loud
  rather than silent.

## Alternatives considered

**Running `npx shadcn@latest init -t vite`.** Targets React's Vite template;
it would scaffold React-flavored files and fight preactcn's own documented
manual setup rather than complementing it. Not attempted beyond confirming
via its `--help` that `-t`/`-b` offer no Preact option.

**Copying `ui/dist` into `cmd/ichor-ui/dist` as a build step.** Works, but is
one more moving part than pointing Vite's `outDir` at the destination
directly.

**One binary for the controller and the UI backend.** Rejected by the design
itself (`ichor-controller`, `ichor-ui` and `ichor` are three deliverables);
also wrong on trust grounds — "only the controller holds an
`os:admin`-equivalent Talos identity; the UI backend holds a read-only one."

**A `.golangci.yml` path exclusion instead of (or alongside) `ui/go.mod`.**
Tried first; redundant once the module boundary was added, since
golangci-lint's package discovery follows the same module rules `go list`
does. Dropped in favor of touching one file (`ui/go.mod`, new) instead of
two (`ui/go.mod` plus a shared config file other agents are also editing).