# UI

## Philosophy

A developer tool people use daily to browse code and manage repos. Optimise for:

1. **Speed-first** — minimise clicks, maximise information density
2. **Scannable** — find what you need in under a second
3. **Quiet confidence** — premium without flashy; the UI should disappear
4. **Code-centric** — code is the hero, everything else supports it

| Principle | Meaning |
|---|---|
| Readable density | Compact without cramped. Maximise info per viewport. |
| Clear hierarchy | Strong contrast between labels, content, and muted elements |
| Functional spacing | 8px on items, 12–16px on sections. No wasted space. |
| Keyboard-first | Every action reachable without a mouse |
| Dark-mode primary | Developers live in dark mode. Light mode is supported, secondary. |

**Do:** small type (`text-xs` / `text-sm` for most UI), small buttons, monospace for
paths, SHAs, and branch names, opacity modifiers for text hierarchy, tight spacing.

**Don't:** large type outside page titles, shadows in dark mode (use borders), bright
backgrounds, hover animations that move or resize things.

## Where the portfolio framing bites

Steid is portfolio-first, not a Gitea clone. The profile page is the product — repos
are one kind of thing on it, alongside writing and projects. Any layout inherited from
a GitHub-shaped forge needs checking against that before it's copied.

## Stack

Topcoat bundles assets and ships Tailwind **without Node**, plus htmx and Alpine
integrations, Fontsource, and Iconify.

That's worth noting: the previous attempt dropped Tailwind purely to avoid an npm
build step and hand-rolled CSS instead. Topcoat removes that objection, so Tailwind is
back on the table at no tooling cost.

Suggested, none of it settled until Milestone 5 needs real pages:

| Concern | Candidate |
|---|---|
| Styling | Tailwind via Topcoat's bundler |
| UI font | Inter (Fontsource) |
| Mono font | IBM Plex Mono |
| Icons | Iconify |
| Interactivity | Topcoat signals; htmx where signals fall short |

Topcoat's own client reactivity is early and acknowledged as limited, which is why the
htmx integration exists. Reach for signals first, fall back without ceremony.

## Prior art

Attempt #1 (`steid-backup/AGENTS/UI.md`) has a complete 643-line design system —
OKLCH light/dark palettes with concrete token values, a type scale, spacing scale, and
component markup for sidebar, file tree, commit bar, breadcrumbs, badges, empty
states. It was written for Tailwind + DaisyUI.

It is worth mining when Milestone 5 arrives, with two caveats: it specifies DaisyUI,
which is a separate choice from Tailwind and not bundled by Topcoat; and it was
written for a GitHub-shaped forge rather than a portfolio-first one.

It is also, on its own, longer than every other doc in this directory combined — for
an app that had about nine pages. Take the palette and the principles. Don't
re-specify components before there are components.