| 1 | # UI |
| 2 | |
| 3 | ## Philosophy |
| 4 | |
| 5 | A developer tool people use daily to browse code and manage repos. Optimise for: |
| 6 | |
| 7 | 1. **Speed-first** — minimise clicks, maximise information density |
| 8 | 2. **Scannable** — find what you need in under a second |
| 9 | 3. **Quiet confidence** — premium without flashy; the UI should disappear |
| 10 | 4. **Code-centric** — code is the hero, everything else supports it |
| 11 | |
| 12 | |
| 13 | |
| 14 | | Readable density | Compact without cramped. Maximise info per viewport. | |
| 15 | | Clear hierarchy | Strong contrast between labels, content, and muted elements | |
| 16 | | Functional spacing | 8px on items, 12–16px on sections. No wasted space. | |
| 17 | | Keyboard-first | Every action reachable without a mouse | |
| 18 | | Dark-mode primary | Developers live in dark mode. Light mode is supported, secondary. | |
| 19 | |
| 20 | **Do:** small type (`text-xs` / `text-sm` for most UI), small buttons, monospace for |
| 21 | paths, SHAs, and branch names, opacity modifiers for text hierarchy, tight spacing. |
| 22 | |
| 23 | **Don't:** large type outside page titles, shadows in dark mode (use borders), bright |
| 24 | backgrounds, hover animations that move or resize things. |
| 25 | |
| 26 | ## Where the portfolio framing bites |
| 27 | |
| 28 | Steid is portfolio-first, not a Gitea clone. The profile page is the product — repos |
| 29 | are one kind of thing on it, alongside writing and projects. Any layout inherited from |
| 30 | a GitHub-shaped forge needs checking against that before it's copied. |
| 31 | |
| 32 | ## Stack |
| 33 | |
| 34 | Settled in [0005](decisions/0005-tailwind-and-copied-components.md). |
| 35 | |
| 36 | |
| 37 | |
| 38 | | Styling | Tailwind via Topcoat's build script — no Node | |
| 39 | | Theme | `styles.css` at the package root: design tokens, dark-first | |
| 40 | | Components | `topcoat ui add` for primitives, hand-written for Steid's own | |
| 41 | | Mono | IBM Plex Mono, for paths, hashes, branches, handles | |
| 42 | |
| 43 | ### Tokens |
| 44 | |
| 45 | Defined in `styles.css` on `:root` (light) and `.dark` (dark, the default): |
| 46 | |
| 47 | ``` |
| 48 | background surface foreground muted-foreground |
| 49 | primary primary-foreground |
| 50 | success success-foreground confirmations, git additions |
| 51 | warning warning-foreground caution, git modifications |
| 52 | destructive destructive-foreground errors, git deletions |
| 53 | border ring shadow-xs shadow-sm |
| 54 | ``` |
| 55 | |
| 56 | `surface`, `success` and `warning` are Steid's additions to Topcoat's `neutral` theme; |
| 57 | the rest were retuned to the palette below. |
| 58 | |
| 59 | **Components reference tokens, never raw colours.** A hardcoded colour will not follow |
| 60 | a palette change and will not adapt to the colour scheme. This is the convention to |
| 61 | enforce in review. |
| 62 | |
| 63 | ### Working on it |
| 64 | |
| 65 | ```bash |
| 66 | topcoat dev |
| 67 | topcoat asset bundle |
| 68 | topcoat ui list |
| 69 | topcoat ui add <name> |
| 70 | ``` |
| 71 | |
| 72 | ## Prior art |
| 73 | |
| 74 | Attempt #1 (`steid-backup/AGENTS/UI.md`) has a complete 643-line design system — |
| 75 | OKLCH light/dark palettes with concrete token values, a type scale, spacing scale, and |
| 76 | component markup for sidebar, file tree, commit bar, breadcrumbs, badges, empty |
| 77 | states. It was written for Tailwind + DaisyUI. |
| 78 | |
| 79 | Its palette has been mined already — the dark-first OKLCH values at hue 260 are what |
| 80 | `styles.css` was retuned to. Its component markup has not, and comes with two caveats: |
| 81 | it specifies DaisyUI, which is a separate choice from Tailwind and not bundled by |
| 82 | Topcoat; and it was written for a GitHub-shaped forge rather than a portfolio-first |
| 83 | one. |
| 84 | |
| 85 | It is also, on its own, longer than every other doc in this directory combined — for |
| 86 | an app that had about nine pages. Take the palette and the principles. Don't |
| 87 | re-specify components before there are components. |