Standard controls: the audit and the target shape

"activities display not very pretty. are we using standard controls library? check all user interfaces and all apps if they use standard user interface components" — maintainer, 2026-09-16

The Governance activity page rendered its whole record — state, inputs, a gates table, the signatures, the log — as one markdown string built with a StringBuilder, wrapped the state in a hand-styled <span>-like pill with literal hex colours, and used ✅ ❌ ⏳ as the gate indicator. That is the shape the maintainer called not very pretty, and the audit below found it is the majority shape in this repo, not the exception.

What the audit measured

The four anti-patterns, each measured against the platform's own guidance (Badges, Icons & Status, DataGrid, Layout Areas, the /layout-area skill):

• A — a record rendered as markdown. **Field:** value lines, | a | b | pipe tables and ``` fences assembled from a typed content record and handed to Controls.Markdown. Markdown is for prose; a record has fields and a list has rows.
• B — raw HTML for layout. Controls.Html(handBuiltMarkup) for cards, tables, heroes and trees. Forbidden by AGENTS.md since 2026-09-15 for anything but pre-rendered rich text.
• C — a card, pill or table emulated with inline CSS. border: 1px solid …; border-radius …; padding … on a stack, display:inline-block; padding: 2px 8px on a label, and a StateColors helper returning #e8f5e9 / #c62828. Literal colours ignore the theme — dark mode renders a pastel pill on a dark surface.
• D — emoji as the status indicator. ✅ ❌ ⏳ ⚠️ 🔴 in a cell or a label, and in one place a dialog parsing the emoji prefix of a status string to decide its phase.

The target shape

Every page is composed from the platform's controls and nothing else:

• State → Controls.Badge. Fluent appearances (Accent for active, Neutral for resting) where they fit; otherwise the portal's status tokens — var(--success, #107c10), var(--error, #d13438), var(--warning-fill-rest, …) / var(--warning-foreground, …) — with a Fluent default as the fallback. Never a literal colour by itself, never an emoji.
• A section → a Controls.Stack with Skins.Card. Controls.H4(title) as the heading, an optional badge beside it (the gate tally), the body underneath. No border CSS.
• A list → Controls.DataGrid over a plain row record with PropertyColumnControl<string> columns named by nameof(Row.X).ToCamelCase(). Inputs, gates, signatures, signers, stages, readings, places: rows, not markdown tables.
• A label/value fact → Controls.Subject(label) + Controls.Body(value) in a horizontal stack. Prose (a message, a rationale) stays Controls.Body; a log stays a fenced Controls.Markdown block, which is what a fence is for.
• Actions → Controls.Toolbar with Appearance.Accent on the primary button.
• Texts → a *Texts record per language (ActivityTexts.For(host.ViewerLocale())), so a page never shows a raw localization key. The platform catalog's generic verbs (ui.accept, ui.reject) are reused; everything specific to the page lives beside it.
• The rows and the badge styling are pure functions asserted in Test/, so a page's content is tested without rendering it.

Governance/Activity and Governance/Standard are the first two pages in this shape (#1981). Read them as the reference.

Paid down so far

Three lessons from the first pass, so the next one does not repeat them: a skin and the stack it wraps both bind the control's style — padding goes on an inner stack, never on the skinned one; a count column is PropertyColumnControl<int> — the grid deserializes each cell as the column's type and a string column over numbers throws per row; and a page whose tests read the direct area ids of a card (the Signature desk) needs those ids on the card's direct children, not on a nested content stack.

The remaining debt, per module

Letters are the anti-patterns above. A module is done when its line can be deleted.

Not counted: the canvas and SVG renderers (DoublePendulum, FractalStars, ThreeBody), where Controls.Html carries a drawing rather than a layout; the Tests areas, whose pass/fail table is read by CI; and the package covers' hero blocks, which are pre-rendered rich text by design.

The clean references to align against, from the same audit: DefaultViews/Gallery, Analysis/Gallery (the only KpiStrip), Approvals/Approval, Publish/Deck, Edu/Module, Edu/Lesson, Essentials/Mailbox, Hosting/LogEntry.

How to re-run the audit

for p in 'Skins.Card' 'Controls.Badge' 'Controls.DataGrid' 'Controls.Html(' 'StringBuilder' \
         'border-radius' '#[0-9a-fA-F]\{6\}'; do
  printf '%4s  %s\n' "$(grep -rl --include='*.cs' -e "$p" --exclude-dir=src --exclude-dir=.worktrees \
      --exclude-dir=clients --exclude-dir=app --exclude-dir=e2e . | grep '/Source/' | wc -l)" "$p"
done

The per-file classification was a read of every one of the 116 layout-area files; re-read a module before deleting its line, the counts above only say where to look.