[design] The atomic layer under #187: 273 buttons in 14 shapes, 3 card geometries, 17 font sizes

[serge-ivo]

The console has design-system vocabulary but no design system

Tokens exist and are mostly used — bg-panel, border-line, text-muted, text-accent are
everywhere, and that is the part that works. What does not exist is any layer between those tokens
and the JSX. Every control is assembled by hand, every time.

Measured across store/console/src:

	count
Hand-authored control class strings (padding + radius)	291
Distinct padding/radius combinations for those controls	14+
Hand-written "card" divs	~59
Distinct card geometries	3
Arbitrary font sizes (text-[…rem])	168 uses, 17 distinct values
Shared Button / Card / Badge / Input primitives	0

What that produces

Buttons. px-3 py-1.5 rounded-lg appears 62 times; px-2.5 py-1.5 rounded-lg appears 23 times.
Those differ by 2px of horizontal padding and are otherwise the same control. Nobody chose that
difference 23 times — it was copied from whichever neighbour was nearest. Add px-3 py-2, px-4 py-2, px-2 py-1, px-2.5 py-1, px-5 py-2.5, each in rounded-lg / rounded-xl / rounded-md
/ rounded-full variants, and there are 14+ shapes expressing what is really three sizes.

Cards. The same panel is written as rounded-xl p-3 sm:p-4 (26×), rounded-xl p-4 (15×), and
rounded-lg p-3 (10×). So a card's corner radius and whether its padding responds to viewport
depend on which file you are in.

Type. The design system says, verbatim: "Use Tailwind defaults… No custom font-size
values." There are 168, across 17 values. Nine of them — 0.65 · 0.66 · 0.68 · 0.70 · 0.72 · 0.74 · 0.75 · 0.76 · 0.78 — sit inside a 2px band. text-[0.68rem] vs text-[0.7rem] is a 0.32px
difference at a 16px root: not a design decision, an artefact of copying.

It also produces text that is too small to read. text-[0.7rem] is 11.2px and is used 95 times,
including for descriptive body copy under form controls.

The fix is a component layer, not a lint rule

A lint that bans text-[…] would relocate the problem into 168 mechanical edits. The reason the
values proliferate is that there is nowhere to put a decision once.

1. Button — variants (primary · secondary · ghost · danger) × sizes (sm · md),
   which covers essentially all 291 sites. The chip local const already invented in
   TeamworkSection.tsx:228 and again in TriggersSection is this component, discovered twice and
   shared zero times.
2. Card — one geometry, with the responsive padding as the default rather than one of three.
3. Badge/Chip — for the status pills currently written inline with rounded-full and
   text-[0.62rem].
4. A real type ramp. Three or four named steps mapped onto Tailwind defaults, and the 17
   arbitrary values collapsed into them. Nothing below text-xs (12px) for anything a user reads
   as prose.

Migration is mechanical and safe to do incrementally — a new Card can wrap existing children with
no behaviour change, and each converted call site deletes a string rather than adding one.

Why now

SettingsTab.tsx (1,154 lines) and InstanceDetail.tsx (1,275) are both on #305's split list, and
#365 restructures the chat composer. Both will be far cheaper against primitives than against 291
bespoke strings — and doing them first bakes the strings in.

Related: #305 (large-file split), #365 (composer restructure), #367 (design-system conformance).

[serge-ivo]

Sequencing conflict with #365 and #305 — needs deciding before anyone starts

Three open issues now want to rewrite InstanceDetail.tsx (1,275 lines) and none of them agrees with the others about order:

• Move the composer below the thread and show it only in text mode — the live dictation becomes the one surface above it #365 moves the composer below the thread and gates it to text mode.
• [standards][tracking] Split worst large files into testable modules #305 splits the file into testable modules.
• this replaces its hand-authored controls with primitives.

I asserted "do this first or #365 bakes the strings in", and #365 asserts "#364 → #365". Both cannot lead. My recommendation, stated as a proposal rather than a decision:

1. [bug] Hands-free says "Listening…" and shows no words — the composer still binds voice.interim, which stopped carrying speech in #281 #364 — a deletion, tiny, and the actual reported bug.
2. Move the composer below the thread and show it only in text mode — the live dictation becomes the one surface above it #365 — the layout inversion, while the file is still one piece and the change is legible as a diff.
3. this — primitives, applied to the settled structure.
4. [standards][tracking] Split worst large files into testable modules #305 — split last, once the call sites are short.

Rationale: primitives-first sounds right but means doing the refactor twice on the composer specifically, since #365 changes which controls exist there at all. The strings #365 would "bake in" are ~15 sites; converting them afterwards is cheaper than blocking a UX fix on a 291-site refactor.

Whoever picks any of these up should confirm the order on all four before starting.

[serge-ivo]

Correction — I filed this without reading #187, and three of its claims are wrong

I measured the console with greps and did not read the components, the stylesheet past its tokens,
or the existing plan. Doing that now changes what this issue should say.

1. "No component layer" is false, and there is already an epic for the missing half

#187 (open) + docs/agent-ui-blocks.md (status: decision + plan) already contain a console
audit that goes deeper than this one. Verified still true today:

• The chat thread exists three times — InstanceDetail.tsx, AgentDetail.tsx, and
  agents/coder/web/src/CopilotView.tsx. All three files are present and all three render a thread.
• Hand-rolled relative-time formatters, none using the SDK's formatTime: agoShort
  (SettingsTab.tsx:30), ago (Terminals.tsx:15), timeAgo (coder/web/src/BuildsPanel.tsx:46).
  I find three, not the five the epic claims — either two were consolidated since or they are
  named something my search missed. Worth re-counting when [Epic] Agent UI as composable blocks — a first-party component library #187 is picked up; the point stands
  either way.

Duplicated logic — the same tool-call regex, the same scroll threshold, a colorizer that lived in
one agent's package while the console rendered a plain <pre> — is a worse problem than the
duplicated class strings this issue counted, and it was already written up.

2. Primitives DO exist — the pattern is understood and applied, just not to controls

• components/Page.tsx is explicitly "single source of truth for the w-full max-w-[N] mx-auto
  pattern so no page can drop w-full again" — the exact reasoning this issue argues for, already
  practised for layout.
• Form inputs are centralised in CSS. index.css:71-88 gives every input/textarea/select
  a shared width, background, border, radius, padding and font-size: 0.88rem, with a matching
  :focus ring. So "no Input primitive exists" was wrong — it exists as a base-layer style rather
  than a component.

That leaves the real gap much narrower than stated: buttons, cards and badges, not "no component
layer".

3. The destination was wrong

packages/sdk/src/ui.ts states the plan in its header: "shared 'lovable shell' components (as
they're extracted from the console), exposed on the ./ui subpath… React lands as an optional peer
dependency when the first component moves in." ui-react.ts already exists and already holds the
React half, split deliberately so the React-free barrel stays React-free.

So extracted components have a designated home, and it is not console-local files. agent-ui-blocks.md
goes further and decides the mechanism — an imperative DOM factory on ctx.sdk, so third-party
surfaces get first-party components without React.

4. One number was measured loosely

"291 hand-authored controls" counted class strings containing padding + radius, which includes divs,
spans and badges. The honest figure is 273 <button> elements. The substance is unchanged; the
label was wrong.

What survives, and what this issue should now be

Unaffected, because they are counts of the source as it stands:

• 168 arbitrary font sizes across 17 values, nine inside a 2px band, against a design system that
  says "No custom font-size values." text-[0.7rem] (11.2px) used 95 times.
• ~59 hand-written cards in 3 geometries (rounded-xl p-3 sm:p-4 ×26, rounded-xl p-4 ×15,
  rounded-lg p-3 ×10).
• 14+ padding/radius combinations across 273 buttons, including px-3 py-1.5 (62×) and
  px-2.5 py-1.5 (23×) differing by 2px.
• The chip constant invented locally in both TeamworkSection.tsx:228 and TriggersSection.

Re-scoped: this is the atomic layer — a Button/Card/Badge vocabulary and a real type ramp —
sitting beneath #187's composite blocks (Terminal, ChatThread, Board, RunList). They are
complementary and this one is a prerequisite: extracting ChatThread into the SDK while its buttons
are still 14 bespoke shapes just moves the inconsistency into the library where more consumers
inherit it.

Retitled accordingly. It should be treated as a sub-issue of #187, not a competing proposal.

[serge-ivo]

Context: PAGS now owns its design system (decided 2026-08-07, #367 / workspace 358b029). It is out of scope of ~/dev/stores/DESIGN-SYSTEM.md, which mandated light+dark and a cross-store theme key the dark-only console never had.

That is directly relevant here. 273 buttons in 14 shapes is not drift from an external spec — it is the absence of an internal one. There was no document this could have violated, which is why nothing caught it.

Sequencing that follows: #367 documents what the system IS, this ticket makes the atomic layer conform to it, and #187 builds the composable blocks on top. Doing #366 first would standardise 273 buttons against 14 shapes and no stated rule — picking a winner by majority vote rather than by decision.

One thing worth carrying: with no external spec, a guard is the only thing that keeps this from re-drifting. 14 shapes accumulated because nothing failed a build when a fifteenth appeared.