steid

10.1 KBRaw

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	\| Principle \| Meaning \|
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	## The profile page
33
34	Settled 2026-08-29, after looking at the built page with real data rather than
35	imagining it. Three sections of equal weight — Repositories, Writing, Projects — two of
36	them empty boxes, repositories sorted alphabetically so `dotfiles` outranked `steid`.
37	A third of the page was content and two thirds advertised incompleteness.
38
39	Flat, app-style navigation. No cards, no boxes.
40
41	```
42	James Gill
43	@jamesgill
44	<bio>
45	<links>
46	─────────────────────────────────────────────
47	Overview Repositories 3 Writing
48	─────────────────────────────────────────────
49	CURRENTLY BUILDING
50	steid Rust
51	A self-hostable gitforge where the profile is the product.
52	421 tests · updated 2 hours ago
53
54	REPOSITORIES All 3 →
55	──────────────────────────────────────────
56	topcoat-notes 3d
57	Notes on building with Topcoat 0.5.
58	──────────────────────────────────────────
59	dotfiles 2w
60	```
61
62	- A tab bar, not stacked sections. Empty sections stop being visible failures and
63	become destinations that simply have nothing in them yet. It is also what makes
64	Writing shippable without redesigning the page around it.
65	- Tabs are links. No JavaScript, and each tab is a real URL that can be shared.
66	- One lead item with genuine typographic weight, then a compact list. This is the
67	editorial layer portfolio-first requires: without it the page has no opinion about
68	what matters, and ordering alone cannot carry that.
69	- Hairlines and hover states, never bordered containers. The row is the unit.
70	- Recency, not alphabetical. Alphabetical is a filing rule; a portfolio needs an
71	editorial one.
72	- Sections with nothing in them are hidden from visitors and shown to the owner as
73	an affordance.
74
75	### One vibe. Hierarchy without scale.
76
77	The first version of this design gave the lead item large type and justified it by
78	splitting the product into a "portfolio surface" and a "tool surface" with different
79	rules. That was wrong and is not what ships. Two design languages in one product is
80	how a product stops feeling like one thing, and it contradicted this file's own
81	philosophy — quiet confidence, the UI disappears, small type throughout.
82
83	Nothing exceeds 14px except the page title. The lead item is distinguished by
84	everything except size:
85
86	\| Device \| Lead \| List row \|
87	\|---\|---\|---\|
88	\| Eyebrow label \| yes \| no \|
89	\| Weight \| 600 \| 500 \|
90	\| Description \| full width, roomy \| compact \|
91	\| Space around it \| generous \| tight \|
92	\| Separator \| hairline below \| none \|
93
94	The cost, stated plainly: the distinction is subtle. One weight step is not much,
95	and the eyebrow and whitespace carry most of it. That is the right trade for a developer
96	tool — but it means the copy in the eyebrow is load-bearing, because it is the clearest
97	signal that this item is different.
98
99	The eyebrow reads "Currently building", chosen over a neutral "Featured". It says
100	something rather than labelling something, which is what a portfolio built in public
101	wants. The known cost: it is a claim about the present, so pinning a finished project
102	makes the page lie. The answer if that becomes a problem is a per-pin label, not a
103	blander default.
104
105	The general rule this sets: **hierarchy comes from weight, colour and space. Reach for
106	size last, and outside a page title, probably not at all.**
107
108	### The front door
109
110	Steid is meant to be someone's site, reached at their own domain — `jpgill.dev`, not
111	`git.jpgill.dev`, because a `git.` subdomain announces a Gitea clone and this is
112	portfolio-first. That makes the root a signpost rather than a page: unclaimed it sends
113	you to setup, and otherwise it forwards to a profile — your own when signed in, **the
114	owner's when not**.
115
116	The last case is the one that matters. A stranger arriving at the apex came for the
117	profile and will never sign in, so a sign-in prompt there is the front door answering the
118	wrong question. It only applies when the owner is unambiguous: with more than one user
119	"the owner" has no answer, so the root falls back to a generic landing rather than
120	electing someone by storage order.
121
122	### What it needs that does not exist yet
123
124	- `updated_at` on a repository. The design promises recency and nothing stores it.
125	Asking git costs one fork per repository — a twelve-repo profile would be ~150ms of
126	`execve` before rendering. So it is a column, touched when a push is authorized.
127	Slightly wrong if a push then fails; the alternative is wrong more expensively.
128	- A `/{handle}/repos` index. The Repositories tab needs a destination; only
129	`/{handle}/repos/{name}` exists.
130	- A way to choose the lead. A `pinned` flag on the repository, set from the settings
131	page that now exists. No pin, no lead section — automatic "most recent" would put a
132	dotfiles tweak at the top of a portfolio.
133
134	### Mocking is harder than it looks here
135
136	Tailwind classes the app does not already use are not in the built stylesheet.
137	`build.rs` scans the real sources, so a mockup written against the served CSS silently
138	loses any new utility — `gap-7` and `tracking-widest` collapsed a nav into
139	`OverviewRepositories3WritingProjects` before this was understood. Iterate either in the
140	app itself or, for throwaway exploration, in plain CSS against the theme's custom
141	properties (`--background`, `--foreground`, `--muted-foreground`, `--border`, `--surface`).
142
143	Dark mode is a `.dark` class on an ancestor, not `prefers-color-scheme`; a mockup
144	without it renders light.
145
146	## Stack
147
148	Settled in [0005](decisions/0005-tailwind-and-copied-components.md).
149
150	\| Concern \| Choice \|
151	\|---\|---\|
152	\| Styling \| Tailwind via Topcoat's build script — no Node \|
153	\| Theme \| `styles.css` at the package root: design tokens, dark-first \|
154	\| Components \| `topcoat ui add` for primitives, hand-written for Steid's own \|
155	\| Mono \| IBM Plex Mono, for paths, hashes, branches, handles \|
156
157	### Tokens
158
159	Defined in `styles.css` on `:root` (light) and `.dark` (dark, the default):
160
161	```
162	background surface foreground muted-foreground
163	primary primary-foreground
164	success success-foreground confirmations, git additions
165	warning warning-foreground caution, git modifications
166	destructive destructive-foreground errors, git deletions
167	border ring shadow-xs shadow-sm
168	```
169
170	`surface`, `success` and `warning` are Steid's additions to Topcoat's `neutral` theme;
171	the rest were retuned to the palette below.
172
173	Components reference tokens, never raw colours. A hardcoded colour will not follow
174	a palette change and will not adapt to the colour scheme. This is the convention to
175	enforce in review.
176
177	### Working on it
178
179	```bash
180	topcoat dev # rebuilds CSS and re-bundles on change
181	topcoat asset bundle # manual builds only; a stale bundle serves stale CSS
182	topcoat ui list # what the registry offers
183	topcoat ui add <name> # copies source into src/components/
184	```
185
186	`components.toml` is the record of what is installed; don't duplicate that list here.
187
188	A registry component can need more than a copy. `select` draws its chevron with an
189	Iconify icon, which needs the `icon-iconify` feature on `topcoat` and the icon set
190	staged in `build.rs`:
191
192	```rust
193	topcoat::icon::iconify::BuildConfig::new().icon_set("feather").stage().unwrap();
194	```
195
196	The build fails with a message naming the missing set, so it is discoverable — but the
197	build.rs edit is easy not to expect from a command that only advertises copying a file.
198	Icons are embedded at build time; nothing is fetched at runtime.
199
200	`topcoat ui add` also rewrites the module list in `src/components.rs` by appending, so
201	re-alphabetise it afterwards.
202
203	## Prior art
204
205	Attempt #1 (`steid-backup/AGENTS/UI.md`) has a complete 643-line design system —
206	OKLCH light/dark palettes with concrete token values, a type scale, spacing scale, and
207	component markup for sidebar, file tree, commit bar, breadcrumbs, badges, empty
208	states. It was written for Tailwind + DaisyUI.
209
210	Its palette has been mined already — the dark-first OKLCH values at hue 260 are what
211	`styles.css` was retuned to. Its component markup has not, and comes with two caveats:
212	it specifies DaisyUI, which is a separate choice from Tailwind and not bundled by
213	Topcoat; and it was written for a GitHub-shaped forge rather than a portfolio-first
214	one.
215
216	It is also, on its own, longer than every other doc in this directory combined — for
217	an app that had about nine pages. Take the palette and the principles. Don't
218	re-specify components before there are components.