@cat-factory/app 0.308.0 → 0.310.0

package/README.md

@@ -300,6 +300,36 @@ Every colour in the SPA is a token that follows the THEME and the colour MODE. T
 - **Never** a raw Tailwind hue (`bg-slate-900`, `text-amber-300`, `text-pink-300`) nor a fixed numbered alias (`text-primary-400`, `bg-warning-950/40`): the first is welded to one palette and one mode, the second follows the palette but not the mode. `scripts/check-frontend-palette.mjs` (CI) bans both. `red` and `rose` both mean `error`.
 - **Never** a fixed `white` / `black` utility (`bg-white`, `text-black`, `border-white/5`, `bg-white/[0.02]`): invisible or wrong in light mode. Use `border-inverted` (a selection ring), `border-default` / `bg-muted` (faint chrome) or `text-inverted` (text over a filled surface). A line that genuinely needs a fixed value says why with a `fixed-colour-ok:` comment, on that line or the one above it.
 
+### Type through named steps, never a pixel literal
+
+Every font size in the SPA is a NAMED step, so it scales with the theme and lines up with the sizes Nuxt UI gives its own components. Two sources of steps:
+
+- **Tailwind's own** from `text-xs` up (`text-xs`, `text-sm`, `text-base`, ...), each paired with a line height.
+- **The app's two steps below them** (`app/assets/css/type.css`), for the dense surfaces Tailwind's scale bottoms out above: `text-2xs` (0.6875rem, 11px at the default root) for the dense body size that panel rows, node metadata and inline detail are written at, and `text-3xs` (0.625rem, 10px) for the caption tier below it: pill and badge text on a board node, a quoted source excerpt, an axis or legend caption. The section eyebrow is `text-2xs`, not `text-3xs`, and is not written by hand at all (see the last bullet). Neither declares a paired LINE HEIGHT: dense text inherits its rhythm from the surrounding block, and a block that wants a specific rhythm says `leading-*`, which wins over a step's paired value anyway.
+- **Never** a literal size (`text-[11px]`, `text-[0.6875rem]`). A theme document's `fontSize` is applied as a root `font-size` (`utils/theme/css.ts`), so every rem step follows it and a pixel literal does not: raising the font size would grow Nuxt UI's components while the app's own text sat still. A literal is also unnameable, so a `UBadge size="sm"` beside one is sized by a system the label cannot refer to. `scripts/check-frontend-type-scale.mjs` (CI) bans the utility forms (`text-[length:11px]`, `[font-size:11px]`, `[font:…]`), a px declaration in CSS (`font-size: 11px`, the `font:` shorthand) and a px JS style property (`fontSize: '11px'`, `style.fontSize = …`); its header lists exactly what it matches. A line that genuinely needs one says why with a `type-literal-ok:` comment, on that line or the one above.
+- **A section eyebrow is [`common/SectionLabel.vue`](./app/components/common/SectionLabel.vue)**, not a hand-written class list. The label that titles a group inside a panel, window, inspector section or dropdown is one recipe, `text-2xs font-semibold uppercase tracking-wide text-muted`, and the component owns all five: they are not overridable, because a caller wanting a different size or colour wants a different thing. The caller picks the ELEMENT with `as` (`div` by default; `h3` / `h4` for a real heading, `label` with an `:id` for a field; a collapsing section is a `UButton` around `as="span"`) and owns SPACING through the ordinary `class` attribute. An ACCENT-coloured uppercase label (`text-primary`, `text-app-info-400`) is not this component: it is signalling state or category rather than titling a section, so it keeps its own classes. Nor is a pill, a chip, a metadata row that merely shares the uppercase styling (`BlockNode.vue`'s composition line), or a caption inside a control (a switcher trigger's label line, a slider's end labels): the test is whether the text TITLES the block after it. The colour is `text-muted` and not the fainter `text-dimmed` for contrast: at 11px `text-dimmed` is 2.63:1 on a light surface, under WCAG AA, where `text-muted` is 4.76:1. (The SPA's wider use of `text-dimmed` outside this component is a separate problem.)
+
+### Radius through the theme scale
+
+Every `rounded-*` utility in the SPA derives from `--ui-radius`, so a theme document's `radius` reaches all of them. Nuxt UI rebuilds seven of Tailwind's steps on it (`rounded-xs` is half it, `rounded-sm` is it, then 1.5x, 2x, 3x, 4x and 6x), and [`main.css`](./app/assets/css/main.css) binds the two spellings that sat outside that: `--radius`, which the bare `rounded` alias and its side and corner forms resolve through, and `--radius-4xl`. Tailwind declares both `@theme default`, so the app's own `@theme inline` block wins, and `inline` is what makes the utility compile to `var(--ui-radius)` rather than to a value frozen at build time. Neither number moves on the default theme.
+
+That is the whole mechanism, and it is why there is no rule here about WHICH step to pick. Two things still name a number instead of the scale:
+
+- **Never an arbitrary value**: `rounded-[10px]`, `rounded-t-[0.6rem]`, or Tailwind v4's CSS-variable shorthand `rounded-(--x)`. Welded to one number the way a pixel font size is, and unnameable besides, so a `UBadge` beside one is shaped by a system the box cannot refer to. The SPA has none.
+- **In CSS, reach the scale through `var(--ui-radius)`**, on its own or inside a `calc()`: `calc(var(--ui-radius) * 2)` is the `rounded-lg` step, and `calc(var(--ui-radius) - 1px)` is an inner box kept concentric with its parent, which follows the theme just as well. **Never a `--radius-*` theme variable**, even though one works today: Tailwind declares that scale in a `@theme default inline` block and emits a variable only where the COMPILED stylesheet graph references it, so `var(--radius-lg)` is correct until the last other reference is deleted and then silently computes to 0. `--ui-radius` is an ordinary custom property on `:root`, so it is there in a scoped SFC `<style>` block too, where the `--radius-*` scale never is. **Never a raw literal** in px, pt, rem or em, the per-corner longhands (`border-top-left-radius`, the logical `border-start-start-radius`) and the JS `borderRadius` / `'border-radius'` spelling a `:style` binding uses included. The pill spellings (`9999px`, `50%`) and `0` are exempt, and a shorthand is read value by value, so `50% 50% 8px 8px` is still caught on the `8px`.
+- `scripts/check-frontend-radius.mjs` (CI) bans both. It needs no notion of where a class list lives, because `rounded-[` and `rounded-(` are not English words. A line that genuinely needs a fixed radius says why with a `radius-literal-ok:` comment, on that line or the one above.
+
+The default `radius` lives on the `Cat Factory` document in `app/utils/theme/builtins.ts`. It equals `THEME_DEFAULTS.radius` and so writes no CSS, which is the point: changing the number there is the whole edit.
+
+### A control is its Nuxt UI component
+
+Every CONTROL in the SPA is the Nuxt UI component for it, never the raw HTML element. A raw `<button>` beside a `UButton` is the same control rendered twice, and only one of the two follows the theme, the focus ring, the disabled state and the size scale; the SPA carried 152 of them, 24 raw `<input>`, five hand-built tables and six hand-rolled `<details>`, each with its own border, background and hover recipe.
+
+- **The mapping**: `<button>` → `UButton`; `<input>` → `UInput` / `UInputNumber` / `UCheckbox` / `URadioGroup` / `USlider` / `UFileUpload`, by what the control IS rather than by its `type=`; `<select>` → `USelect` (`USelectMenu` when it needs searching, `UInputMenu` when the list is open-ended); `<textarea>` → `UTextarea`; `<table>` → `UTable` with column definitions; `<details>` → `UCollapsible`; `<form>` → `UForm`; `<a href>` → `ULink`; `<datalist>` → `UInputMenu` with `mode="autocomplete"`, which is what a datalist was (the DEFAULT combobox mode writes its model only on SELECT, so a typed free-text value is dropped). Which input for which job is the skill's [component-selection matrix](https://github.com/nuxt/ui/blob/v4/skills/nuxt-ui/references/component-selection.md), not restated here.
+- **An icon-only button is [`common/IconButton.vue`](./app/components/common/IconButton.vue)**, which wraps `UButton` in a `UTooltip` and applies `label` as the tooltip text AND `aria-label`. A `title` attribute is not a tooltip: it never fires on touch, is unstyled, waits about a second, and looks nothing like the app's other hints. `IconButton` and `CopyButton` own their tooltip, so passing either a `title` renders a second hint over the first. A `title` on a LABELLED `UButton` is still fine: there it is a hover hint beside the control's own name rather than the name itself. `class` on `IconButton` lands on the wrapper the tooltip needs, which is the box the parent lays out, so it carries layout (`ms-auto`, `shrink-0`, `nodrag`); the button's own look goes through its props and `:ui="{ base: '…' }"`. The guard refuses an icon-only `UButton` whose only name is a `title`.
+- **Prose and layout markup is not in scope.** `<p>`, `<h1>`-`<h6>`, `<ul>`, `<li>`, `<dl>`, `<pre>`, `<code>`, `<img>`, `<nav>`, `<div>` and `<span>` are not controls and have no Nuxt UI component; heading typography is the type scale's rule above.
+- `scripts/check-frontend-primitives.mjs` (CI) holds the count at zero. There is deliberately **no allow-list**: the migration expected two exceptions (a Vue Flow gesture handle, a full-bleed media tile) and both converted cleanly, so the exception table would have had more surface than the thing it governed. A site that genuinely cannot convert says why with a `raw-control-ok:` comment, on that line or the one above; nothing in the tree needs one, and a second one appearing is the signal that the rule needs revisiting rather than the site.
+
 ### Themes and colour mode
 
 A **theme** is a Nuxt UI theme editor document (https://ui.nuxt.com/theme): the sparse `ThemeDoc` the editor edits and shares as a `?doc=` link, decoded by `utils/theme/link.ts` and typed in `utils/theme/doc.ts` (a port of the editor engine's tables). The app speaks THAT format rather than one of its own, so a theme built in the editor imports as-is and a built-in theme is a document a user could have exported. `utils/theme/builtins.ts` ships `Cat Factory` (the default; its `colors` MUST equal `app.config.ts`'s `ui.colors`, which paints the first frame) and the editor's own `Mono` preset, referenced from the preset table rather than copied. The `theme` store persists the pick and the user's imported documents in this browser; `plugins/theme.client.ts` applies the active document at runtime: aliases onto `appConfig.ui.colors` (Nuxt UI's own colours plugin re-emits the ramps), default variants and component overrides onto `appConfig.ui.<component>` merged INTO the layer's own overrides, and tokens / radius / fonts onto one `<style id="app-theme">` whose selectors anchor on the `data-theme` attribute on `<html>` (`utils/theme/css.ts`, which is also the write boundary for untrusted values). The faces the built-in themes name (Geist, Geist Mono) are self-hosted through `@nuxt/fonts` (`fonts.families` in `nuxt.config.ts`, pinned by `builtins.spec.ts`); a font an IMPORTED theme names is applied as a family name only, so it renders when the device or the deployment provides it. A editor link whose document equals one of the editor's presets collapses to `{ preset: 'mono' }`; `utils/theme/presets.ts` is a copy of the editor's preset table so such a link rebuilds (a decode table, not menu entries).
@@ -354,8 +384,8 @@ protects, so the two never contradict silently:
   freely; here a failed backend call is reported with `usePipelineErrorToast().present(error, key)`.
   [Rule](#every-failure-toast-goes-through-one-funnel).
 - **Icon-only buttons carry an accessible name.** Use `common/IconButton.vue`
-  ([source](./app/components/common/IconButton.vue)), which applies `label` as both `title` and
-  `aria-label`, rather than a bare `<UButton icon>`.
+  ([source](./app/components/common/IconButton.vue)), which applies `label` as both the tooltip
+  and `aria-label`, rather than a bare `<UButton icon>`.
 - **Colour goes through theme tokens, never a fixed palette shade.** The skill bans raw Tailwind
   hues; this repo also bans fixed numbered aliases, enforced by
   [`scripts/check-frontend-palette.mjs`](https://github.com/kibertoad/cat-factory/blob/main/scripts/check-frontend-palette.mjs).

package/app/assets/css/main.css

@@ -6,6 +6,28 @@
 /* The app's own mode-adaptive colour tokens (`app-*`), layered on Nuxt UI's. */
 @import './tokens.css';
 
+/* The app's own type steps below `text-xs` (`text-2xs`, `text-3xs`). */
+@import './type.css';
+
+/* Bind the last two radius steps Nuxt UI leaves alone onto `--ui-radius`, so EVERY `rounded-*`
+ * utility follows a theme document's `radius` (issue #2251).
+ *
+ * Nuxt UI rebuilds seven of Tailwind's steps on `--ui-radius` (`--radius-sm` is it, `--radius-lg`
+ * is twice it, and so on), which is why a hand-written box on a named step already lines up with
+ * the Nuxt UI component beside it. Two spellings sat outside that: the bare `rounded` alias, whose
+ * `--radius` Tailwind declares `@theme default inline reference` and so inlines as a literal
+ * 0.25rem, and `rounded-4xl`, whose `--radius-4xl` keeps Tailwind's own 2rem. Both are `default`,
+ * so declaring them here wins, and `inline` is what lets `rounded` compile to `var(--ui-radius)`
+ * rather than to a value frozen at build time.
+ *
+ * Neither number moves on the default theme: `--ui-radius` is 0.25rem, and 8x it is the 2rem
+ * `--radius-4xl` already held. Declaring them here also EMITS both as ordinary custom properties,
+ * where Tailwind's `reference` kept `--radius` out of the stylesheet entirely. */
+@theme inline {
+  --radius: var(--ui-radius);
+  --radius-4xl: calc(var(--ui-radius) * 8);
+}
+
 /* The two toaster rules below are scoped by the `app-toaster` marker class that
  * `app.config.ts` puts on the toaster's viewport slot, NOT by `[data-slot='viewport']`.
  * That attribute is Nuxt UI's name for the scroll region of ELEVEN components

package/app/assets/css/prose.css

@@ -17,7 +17,7 @@
 .reader-prose.review-mode [data-src-start] {
   position: relative;
   cursor: pointer;
-  border-radius: 0.375rem;
+  border-radius: calc(var(--ui-radius) * 1.5);
   transition: background 0.12s ease;
 }
 .reader-prose.review-mode [data-src-start]:hover {
@@ -34,7 +34,7 @@
   width: 1.1rem;
   align-items: center;
   justify-content: center;
-  border-radius: 0.25rem;
+  border-radius: var(--ui-radius);
   background: var(--ui-primary);
   color: var(--ui-text-inverted);
   font-size: 0.8rem;
@@ -81,7 +81,7 @@
   font-style: italic;
 }
 .reader-prose code {
-  border-radius: 0.25rem;
+  border-radius: var(--ui-radius);
   background: var(--ui-bg-elevated);
   padding: 0.1rem 0.3rem;
   font-family: var(--font-mono);
@@ -91,7 +91,7 @@
 .reader-prose pre {
   margin: 0.6rem 0;
   overflow: auto;
-  border-radius: 0.5rem;
+  border-radius: calc(var(--ui-radius) * 2);
   background: var(--app-bg-canvas);
   padding: 0.75rem 0.9rem;
 }

package/app/assets/css/type.css

@@ -0,0 +1,24 @@
+/* The app's own type steps below Tailwind's `text-xs` (issue #2248).
+ *
+ * Both are rem, so both scale with a theme document's `fontSize`, which `utils/theme/css.ts` applies
+ * as the root `font-size`:
+ *
+ *   --text-2xs  0.6875rem  (11px at the 16px default)  the dense body size: panel rows, node
+ *                                                      metadata, inline detail, and the section
+ *                                                      eyebrow (`common/SectionLabel.vue`).
+ *   --text-3xs  0.625rem   (10px)                      the caption tier below the eyebrow: pill and
+ *                                                      badge text on a board node, a quoted source
+ *                                                      excerpt, axis and legend captions.
+ *
+ * Neither step declares a line height. Tailwind pairs `--text-<n>` with an optional
+ * `--text-<n>--line-height`, and when one exists the utility sets both properties. Dense text here
+ * inherits its rhythm from the surrounding block; a block that wants a specific rhythm says so with
+ * `leading-*`.
+ *
+ * `scripts/check-frontend-type-scale.mjs` bans font-size literals, so these two and Tailwind's own
+ * steps are the whole scale. */
+
+@theme {
+  --text-2xs: 0.6875rem;
+  --text-3xs: 0.625rem;
+}

package/app/components/assistant/AssistantModal.vue

@@ -22,6 +22,7 @@
 // the retry belongs.
 import type { AssistantActionId, AssistantOutcome } from '~/types/domain'
 import { answerFor, assistantSurface, revealTarget, submitGate } from './AssistantModal.logic'
+import SectionLabel from '~/components/common/SectionLabel.vue'
 
 const { t } = useI18n()
 const ui = useUiStore()
@@ -254,20 +255,21 @@ function reveal(blockId: string): void {
 
           <!-- What it can do, always visible: the catalog is the affordance. -->
           <div v-if="examples.length" class="space-y-2">
-            <p class="text-xs font-medium uppercase tracking-wide text-dimmed">
+            <SectionLabel as="p">
               {{ t('assistant.examplesTitle') }}
-            </p>
+            </SectionLabel>
             <div class="flex flex-col gap-1">
-              <button
+              <UButton
+                color="neutral"
+                variant="ghost"
                 v-for="entry in examples"
                 :key="entry.actionId"
-                type="button"
-                class="rounded-md px-2 py-1 text-left text-sm text-toned hover:bg-elevated"
+                class="block rounded-md px-2 py-1 text-left text-sm text-toned hover:bg-elevated"
                 @click="useExample(entry.example)"
               >
                 <span class="text-muted">{{ entry.label }}</span>
                 <span class="block text-xs text-dimmed">“{{ entry.example }}”</span>
-              </button>
+              </UButton>
             </div>
           </div>
 

package/app/components/auth/BackendMisconfiguredScreen.vue

@@ -41,16 +41,17 @@ function reload() {
             <span class="font-medium text-toned">{{ t('app.misconfigured.howToFix') }}</span>
             {{ problem.remedy }}
           </p>
-          <a
+          <ULink
+            raw
             v-if="problem.docsUrl"
-            :href="problem.docsUrl"
+            :to="problem.docsUrl"
             target="_blank"
             rel="noopener noreferrer"
             class="mt-2 inline-flex items-center gap-1 text-sm text-app-warning-300 hover:text-app-warning-200"
           >
             <UIcon name="i-lucide-book-open" class="h-4 w-4" />
             {{ t('app.misconfigured.viewDocs') }}
-          </a>
+          </ULink>
         </li>
       </ul>
 

package/app/components/auth/LoginScreen.vue

@@ -286,16 +286,17 @@ const noSignInMethod = computed(
           <!-- Only when nothing can be installed here: the paste form below carries its own
                per-provider link, so showing these too would offer the same thing twice. -->
           <div v-if="installableProviders.length === 0" class="flex flex-wrap gap-3 px-1">
-            <a
+            <ULink
+              raw
               v-for="p in ALL_PROVIDERS"
               :key="p"
-              :href="tokenCreateUrl(p)"
+              :to="tokenCreateUrl(p)"
               target="_blank"
               rel="noopener noreferrer"
               class="text-xs text-primary hover:underline"
             >
               {{ t('auth.localMode.createToken', { provider: PROVIDER_LABELS[p] }) }}
-            </a>
+            </ULink>
           </div>
         </template>
 
@@ -379,10 +380,10 @@ const noSignInMethod = computed(
       </div>
 
       <!-- Email / password -->
-      <form
+      <UForm
         v-if="auth.providers.password && mode !== 'forgot'"
         class="space-y-3"
-        @submit.prevent="submitPassword"
+        @submit="submitPassword"
       >
         <UInput
           v-if="mode === 'signup'"
@@ -426,36 +427,43 @@ const noSignInMethod = computed(
           <template v-if="mode === 'login'">
             <i18n-t keypath="auth.login.needAccount" tag="span" scope="global">
               <template #signUp>
-                <button
-                  type="button"
-                  class="text-primary hover:underline"
+                <UButton
+                  color="primary"
+                  variant="link"
+                  class="p-0 text-xs text-primary hover:underline"
                   @click="setMode('signup')"
                 >
                   {{ t('auth.login.signUp') }}
-                </button>
+                </UButton>
               </template>
             </i18n-t>
           </template>
           <template v-else>
             <i18n-t keypath="auth.login.haveAccount" tag="span" scope="global">
               <template #signIn>
-                <button
-                  type="button"
-                  class="text-primary hover:underline"
+                <UButton
+                  color="primary"
+                  variant="link"
+                  class="p-0 text-xs text-primary hover:underline"
                   @click="setMode('login')"
                 >
                   {{ t('auth.login.signIn') }}
-                </button>
+                </UButton>
               </template>
             </i18n-t>
           </template>
         </p>
         <p v-if="mode === 'login'" class="text-center text-xs text-muted">
-          <button type="button" class="text-primary hover:underline" @click="setMode('forgot')">
+          <UButton
+            color="primary"
+            variant="link"
+            class="p-0 text-xs text-primary hover:underline"
+            @click="setMode('forgot')"
+          >
             {{ t('auth.login.forgotPassword') }}
-          </button>
+          </UButton>
         </p>
-      </form>
+      </UForm>
 
       <!-- Paste-a-token sign-in: your own PAT on a hosted node; on local mode the token this
            deployment will operate with (see `remotePatProviders`). -->
@@ -472,7 +480,7 @@ const noSignInMethod = computed(
           <span class="h-px flex-1 bg-elevated" /> {{ t('auth.login.or') }}
           <span class="h-px flex-1 bg-elevated" />
         </div>
-        <form class="space-y-3" @submit.prevent="submitRemotePat">
+        <UForm class="space-y-3" @submit="submitRemotePat">
           <div v-if="remotePatProviders.length > 1" class="flex gap-2">
             <UButton
               v-for="p in remotePatProviders"
@@ -517,8 +525,9 @@ const noSignInMethod = computed(
             {{ t('auth.localMode.tokenBecomesCredential') }}
           </p>
           <p class="px-1 text-center">
-            <a
-              :href="tokenCreateUrl(remotePatProvider)"
+            <ULink
+              raw
+              :to="tokenCreateUrl(remotePatProvider)"
               target="_blank"
               rel="noopener noreferrer"
               class="text-xs text-primary hover:underline"
@@ -526,9 +535,9 @@ const noSignInMethod = computed(
               {{
                 t('auth.localMode.createToken', { provider: PROVIDER_LABELS[remotePatProvider] })
               }}
-            </a>
+            </ULink>
           </p>
-        </form>
+        </UForm>
       </template>
 
       <!-- No sign-in method configured on a remote deployment: explain, don't show a blank card -->
@@ -542,10 +551,10 @@ const noSignInMethod = computed(
       />
 
       <!-- Forgot password: request a reset link by email -->
-      <form
+      <UForm
         v-if="auth.providers.password && mode === 'forgot'"
         class="space-y-3"
-        @submit.prevent="submitForgot"
+        @submit="submitForgot"
       >
         <template v-if="forgotSent">
           <p class="text-sm text-toned">
@@ -568,11 +577,16 @@ const noSignInMethod = computed(
           </UButton>
         </template>
         <p class="text-center text-xs text-muted">
-          <button type="button" class="text-primary hover:underline" @click="setMode('login')">
+          <UButton
+            color="primary"
+            variant="link"
+            class="p-0 text-xs text-primary hover:underline"
+            @click="setMode('login')"
+          >
             {{ t('auth.login.backToSignIn') }}
-          </button>
+          </UButton>
         </p>
-      </form>
+      </UForm>
     </div>
   </div>
 </template>

package/app/components/auth/ResetPasswordScreen.vue

@@ -76,7 +76,7 @@ function goToLogin() {
         </UButton>
       </template>
 
-      <form v-else class="space-y-3" @submit.prevent="submit">
+      <UForm v-else class="space-y-3" @submit="submit">
         <SecretInput
           v-model="password"
           required
@@ -98,11 +98,16 @@ function goToLogin() {
           {{ t('auth.resetPassword.submit') }}
         </UButton>
         <p class="text-center text-xs text-muted">
-          <button type="button" class="text-primary hover:underline" @click="goToLogin">
+          <UButton
+            color="primary"
+            variant="link"
+            class="p-0 text-xs text-primary hover:underline"
+            @click="goToLogin"
+          >
             {{ t('auth.resetPassword.backToSignIn') }}
-          </button>
+          </UButton>
         </p>
-      </form>
+      </UForm>
     </div>
   </div>
 </template>

package/app/components/auth/UserMenu.vue

@@ -33,8 +33,9 @@ const items = computed<DropdownMenuItem[][]>(() => [
 
 <template>
   <UDropdownMenu v-if="auth.user" :items="items" :content="{ side: 'top', align: 'start' }">
-    <button
-      type="button"
+    <UButton
+      color="neutral"
+      variant="ghost"
       data-testid="user-menu"
       :title="collapsed ? auth.user.name || auth.user.login : undefined"
       class="flex w-full items-center gap-2 rounded-lg border border-default bg-default/60 p-2 text-start transition hover:bg-elevated/60"
@@ -50,9 +51,9 @@ const items = computed<DropdownMenuItem[][]>(() => [
         <div class="truncate text-xs font-medium text-highlighted">
           {{ auth.user.name || auth.user.login }}
         </div>
-        <div class="truncate text-[10px] text-dimmed">@{{ auth.user.login }}</div>
+        <div class="truncate text-3xs text-dimmed">@{{ auth.user.login }}</div>
       </div>
       <UIcon v-if="!collapsed" name="i-lucide-chevron-up" class="h-4 w-4 shrink-0 text-dimmed" />
-    </button>
+    </UButton>
   </UDropdownMenu>
 </template>

package/app/components/binaryCandidates/BinaryCandidatesWindow.vue

@@ -202,7 +202,7 @@ const { requestClose } = useUnsavedGuard({
            declared its candidates and one whose block was unreadable need different fixes. -->
       <p
         v-if="noChoiceKey"
-        class="mb-3 rounded border border-app-warning-500/30 bg-app-warning-500/5 px-3 py-2 text-xs text-app-warning-200"
+        class="mb-3 rounded-sm border border-app-warning-500/30 bg-app-warning-500/5 px-3 py-2 text-xs text-app-warning-200"
         data-testid="binary-candidates-no-choice"
       >
         {{ t(noChoiceKey) }}
@@ -211,7 +211,7 @@ const { requestClose } = useUnsavedGuard({
       <!-- An automatic keep is NOT a review, and must never render as one. -->
       <p
         v-if="view.automatic"
-        class="mb-3 rounded border border-app-600/40 bg-elevated/40 px-3 py-2 text-xs text-toned"
+        class="mb-3 rounded-sm border border-app-600/40 bg-elevated/40 px-3 py-2 text-xs text-toned"
         data-testid="binary-candidates-automatic"
       >
         {{ t('binaryCandidates.automatic') }}
@@ -235,6 +235,16 @@ const { requestClose } = useUnsavedGuard({
         >
       </p>
 
+      <!-- Single-select renders a checkbox per card, not one radio group, so this line is what
+           tells everyone (a screen reader through each box's description) that ticking one clears
+           the other. -->
+      <p
+        v-if="view.awaiting && !view.multiSelect"
+        id="binary-candidates-pick-one"
+        class="mb-3 text-xs text-muted"
+      >
+        {{ t('binaryCandidates.pickOne') }}
+      </p>
       <div v-for="group in view.groups" :key="group.subject ?? '·'" class="mb-6">
         <h3 class="mb-2 text-xs font-medium text-muted">
           {{ group.subject ?? t('binaryCandidates.unlabelledSubject') }}
@@ -243,7 +253,7 @@ const { requestClose } = useUnsavedGuard({
           <div
             v-for="row in group.rows"
             :key="row.id"
-            class="rounded border p-2 transition"
+            class="rounded-sm border p-2 transition"
             :class="[
               selected.includes(row.id) || row.kept
                 ? 'border-app-info-400/60 bg-app-info-500/5'
@@ -255,33 +265,34 @@ const { requestClose } = useUnsavedGuard({
           >
             <!-- The REAL control, not the card's click handler: ticking a candidate is the only
                  way to keep an asset, so without a focusable input the gate could not be completed
-                 by keyboard at all (UX-80). The whole window is ONE radio group in single-select
-                 mode, because `toggle` replaces the selection across every subject rather than per
-                 group.
+                 by keyboard at all (UX-80). In single-select mode `toggle` replaces the selection
+                 across every subject rather than per group.
 
-                 `@click.stop` belongs on the LABEL, which is the element the card's own toggle has
-                 to be shielded from. On the input alone it stopped the wrong click: activating a
-                 label forwards a synthetic click to its input (which `.stop` there does not
-                 prevent, only its propagation), so a click on the label TEXT bubbled to the card
-                 and toggled, then the forwarded click toggled back. On a checkbox that nets to no
-                 change, which means no re-render, which leaves the box ticked over a candidate
-                 that is no longer selected. -->
-            <label
-              v-if="view.awaiting"
-              class="mb-1.5 flex cursor-pointer items-center gap-2 text-[11px] text-muted"
-              @click.stop
-            >
-              <input
-                :type="view.multiSelect ? 'checkbox' : 'radio'"
-                name="binary-candidate"
-                class="accent-app-info-500"
-                :checked="selected.includes(row.id)"
+                 `@click.stop` belongs on the WRAPPER, which is what the card's own toggle has to
+                 be shielded from, and NOT on the control: activating a label forwards a synthetic
+                 click to its control (which `.stop` there does not prevent, only its
+                 propagation), so a click on the label TEXT bubbles to the card and toggles, then
+                 the forwarded click toggles back. On a checkbox that nets to no change, which
+                 means no re-render, which leaves the box ticked over a candidate that is no
+                 longer selected. UCheckbox is not the place for it either: Nuxt UI forwards
+                 `$attrs` onto the inner checkbox button rather than onto its root, so a listener
+                 put there is the same "on the control alone" mistake spelled differently. -->
+            <!-- One control either way. Single-select is a checkbox rather than a radio group,
+                 because the rows render per candidate across several subjects and a radio group
+                 needs the whole set in one place. So the box announces as a checkbox, and the
+                 "pick one" line above is its description: that is the cue that ticking it clears
+                 the previous pick. -->
+            <div v-if="view.awaiting" class="mb-1.5" @click.stop>
+              <UCheckbox
+                size="xs"
+                :model-value="selected.includes(row.id)"
+                :label="candidateLabel(row)"
                 :aria-label="candidateLabel(row)"
+                :aria-describedby="view.multiSelect ? undefined : 'binary-candidates-pick-one'"
                 data-testid="binary-candidate-select"
-                @change="toggle(row.id)"
+                @update:model-value="toggle(row.id)"
               />
-              <span class="truncate">{{ candidateLabel(row) }}</span>
-            </label>
+            </div>
             <!-- Staged through the platform's OWN asset storage: we hold the bytes, so the card
                  renders them (and offers to open or save one) rather than waiting for a public
                  link the shipped storage never issues. Checked first because a candidate can
@@ -297,14 +308,14 @@ const { requestClose } = useUnsavedGuard({
               v-else-if="row.previewUrl"
               :src="row.previewUrl"
               :alt="row.label ?? row.id"
-              class="mb-2 max-h-56 w-full rounded object-contain"
+              class="mb-2 max-h-56 w-full rounded-sm object-contain"
               data-testid="binary-candidate-preview"
             />
             <!-- No preview is ORDINARY (a private asset store issues no link), so it is stated
                  rather than left as an empty frame the reader reads as a failed generation. -->
             <p
               v-else
-              class="mb-2 flex h-24 items-center justify-center rounded bg-elevated/60 px-2 text-center text-[10px] text-muted"
+              class="mb-2 flex h-24 items-center justify-center rounded-sm bg-elevated/60 px-2 text-center text-3xs text-muted"
               data-testid="binary-candidate-no-preview"
             >
               {{ t('binaryCandidates.noPreview') }}
@@ -316,10 +327,10 @@ const { requestClose } = useUnsavedGuard({
                   : t('binaryCandidates.unattributed')
               }}
             </p>
-            <p v-if="row.note" class="mt-1 text-[11px] text-muted">{{ row.note }}</p>
-            <p class="mt-1 break-all text-[10px] text-dimmed">{{ row.location }}</p>
-            <p v-if="row.contentType" class="text-[10px] text-dimmed">{{ row.contentType }}</p>
-            <p v-if="row.kept" class="mt-1 text-[11px] text-app-success-300">
+            <p v-if="row.note" class="mt-1 text-2xs text-muted">{{ row.note }}</p>
+            <p class="mt-1 break-all text-3xs text-dimmed">{{ row.location }}</p>
+            <p v-if="row.contentType" class="text-3xs text-dimmed">{{ row.contentType }}</p>
+            <p v-if="row.kept" class="mt-1 text-2xs text-app-success-300">
               {{
                 row.storeAs
                   ? t('binaryCandidates.keptAs', { id: row.storeAs })
@@ -352,19 +363,19 @@ const { requestClose } = useUnsavedGuard({
         />
         <p
           v-if="missingAliases.length"
-          class="mt-1 text-[11px] text-app-warning-300"
+          class="mt-1 text-2xs text-app-warning-300"
           data-testid="binary-candidates-missing-alias"
         >
           {{ t('binaryCandidates.missingAlias') }}
         </p>
         <p
           v-else-if="duplicateAliases"
-          class="mt-1 text-[11px] text-app-warning-300"
+          class="mt-1 text-2xs text-app-warning-300"
           data-testid="binary-candidates-duplicate-alias"
         >
           {{ t('binaryCandidates.duplicateAlias') }}
         </p>
-        <p v-if="candidates.error" class="mt-1 text-[11px] text-app-error-300">
+        <p v-if="candidates.error" class="mt-1 text-2xs text-app-error-300">
           {{ candidates.error }}
         </p>
         <div class="mt-2 flex justify-end">
@@ -395,7 +406,7 @@ const { requestClose } = useUnsavedGuard({
     >
       <UIcon name="i-lucide-unlink" class="h-8 w-8 opacity-40" />
       <p class="text-sm">{{ t('binaryCandidates.noRun.title') }}</p>
-      <p class="max-w-md text-[11px] text-dimmed">{{ t('binaryCandidates.noRun.hint') }}</p>
+      <p class="max-w-md text-2xs text-dimmed">{{ t('binaryCandidates.noRun.hint') }}</p>
     </div>
     <div
       v-else-if="absence === 'loading'"
@@ -411,7 +422,7 @@ const { requestClose } = useUnsavedGuard({
     >
       <UIcon name="i-lucide-triangle-alert" class="h-8 w-8 text-app-warning-400/70" />
       <p class="text-sm">{{ t('binaryCandidates.loadFailed') }}</p>
-      <p class="max-w-md break-words text-[11px] text-dimmed">{{ candidates.error }}</p>
+      <p class="max-w-md break-words text-2xs text-dimmed">{{ candidates.error }}</p>
       <UButton
         size="xs"
         color="neutral"