Skip to content

docs(design): correct DESIGN.md against the current tokens and components - #85

Merged
mrsibe merged 1 commit into
mainfrom
docs/design-md-accuracy
Sep 24, 2026
Merged

mrsibe merged 1 commit into
mainfrom
docs/design-md-accuracy

Conversation

@mrsibe

@mrsibe mrsibe commented Sep 24, 2026

Copy link
Copy Markdown
Owner

What does this PR do?

Corrects DESIGN.md where it describes something the code does not do, or leaves out a value the code already uses. Documentation only — no rendered pixel changes.

Follow-up to the merged #84: that PR added the Window chrome section and the Raised card recipe, and this pass is the rest of the same check.

Why?

impeccable doctor reports one finding (design-md-coverage), but that finding is about heading names, not content. Reading DESIGN.md against the current tokens and components turns up several places where the document is simply wrong about the code, and a few values the code uses that the document never states.

Because DESIGN.md is the source of truth for UI decisions, a wrong recipe is worse than a missing one: the next agent copies it.

What changed?

Wrong about existing code

  • The Form field recipe contradicted both the components and the density table.
    It said the label is text-xs and the control h-8:

    • Label is text-sm font-medium leading-none; FieldLabel and the
      hand-written labels in ModelConnectionForm are text-sm font-medium.
    • Input is h-9 and the Select trigger is h-9, and the density table
      already said Input / Select trigger | h-9. The recipe's h-8 is the sm
      button height and the compact row height, not an input height.
    • Error text was documented as text-xs; FieldError is
      text-destructive text-sm font-normal with role="alert".
  • components/ui/field.tsx was never documented, yet it is what the settings
    surfaces use (GeneralSettings renders FieldLabel). The recipe described a
    hand-rolled label/input/error stack. The primitives are now named, and the
    recipe points at FieldError instead of restating its classes.

Missing values the code already uses

  • The title-bar density tier. TopNavigationBar runs 28px tabs and 28px icon
    buttons inside the 44px bar. Without a row in the density table, that reads as a
    violation of Toolbar icon button | size-8 rather than a deliberate tier, so
    the tier is now documented as stopping at the title bar.
  • Tabs was documented as having exactly one form — the segmented control,
    where "selection is expressed as a surface step". The open-notebook strip in the
    title bar is a second, legitimate form: no track, and selection expressed with
    the ordinary translucent bg-surface-selected fill. Both are now written down.
  • The border-none opt-out that fix(ui): remove the dashed border from the knowledge base empty state #58 added to the panel-level empty states was
    never recorded, so the next reader would reasonably reintroduce the dashed
    outline in the knowledge-base panel.

Smaller corrections

  • The legacy-alias list was incomplete, and it implied --secondary was one of
    those aliases. It is not: it holds its own literals in both themes, nothing
    renders it (Button and Badge variant="secondary" both use bg-muted), and
    its light value is the only blue-tinted neutral in the palette. DESIGN.md now
    says so and marks it for deletion rather than adoption.

Open decisions this PR does not make

Found by the same pass; both need a call rather than a doc edit, so neither is in
this diff:

  1. The surface table claims the title bar is surface-sunken; it renders
    surface-base.
    TopNavigationBar carries no background class, so it
    inherits the page root and is the same tone as the canvas rather than a
    distinct chrome band. Either the table row is wrong, or the bar should get
    bg-surface-sunken. The second option is a visible change.
    (Everything else that row names — the settings Sidebar, the settings dialog
    shell — does use bg-surface-sunken.)
  2. --secondary / --secondary-foreground are dead tokens. Now documented as
    such; deleting them from theme.css is a separate mechanical change.

How was this tested?

  • npx prettier --check DESIGN.md — clean.
  • Every claim above was read out of the source it names before it was written:
    ui/label.tsx, ui/input.tsx, ui/select.tsx, ui/field.tsx,
    ui/tabs.tsx, common/TopNavigationBar.tsx, settings/ModelConnectionForm.tsx,
    notebook/source/DocumentList.tsx, assets/theme.css.
  • npm run check:design — no violations.

No code changed, so npm test / npm run build were not re-run.

Screenshots / recordings

Not applicable — documentation only.

Checklist

  • I have reviewed my own changes.
  • npm run typecheck passes. (unchanged; no code touched)
  • npm run build passes. (unchanged; no code touched)
  • I have tested the affected user workflow. (n/a)
  • I have not included unrelated changes.
  • I have updated documentation when necessary.

Desktop / build changes

  • Not applicable

…ents

`impeccable doctor` reports one finding (`design-md-coverage`), but reading
DESIGN.md against the code turns up several places where the document describes
something the code does not do. Those are corrected here; none of them changes a
rendered pixel.

Wrong about existing code:

- The Form field recipe said the label is `text-xs` and the control `h-8`.
  `Label` / `FieldLabel` are `text-sm font-medium`, `Input` and the `Select`
  trigger are `h-9`, and the density table already said `h-9` — the recipe was
  contradicting both the components and the table. Error text was documented as
  `text-xs`; `FieldError` is `text-sm`.
- The recipe described a hand-rolled label/input/error stack and never mentioned
  `components/ui/field.tsx`, which is what the settings surfaces actually use.
  The primitives are now named, including the `role="alert"` wiring `FieldError`
  already provides.

Missing values the code already uses:

- The title-bar density tier (28px tabs and icon buttons in a 44px bar) was
  undocumented, which made `TopNavigationBar` look like it was violating the
  `size-8` toolbar-icon-button rule instead of being a deliberate tier.
- `Tabs` was documented as having exactly one form, the segmented control. The
  open-notebook strip in the title bar is a second form, and it expresses
  selection with the translucent fill rather than a surface step.
- The `border-none` opt-out that #58 added to the panel-level empty states was
  not recorded, so the next reader would reintroduce the dashed outline there.

Also: the legacy-alias list was incomplete, and it implied `--secondary` was one
of those aliases. It is not — it holds its own literals, nothing renders it
(`Button` and `Badge` `variant="secondary"` use `bg-muted`), and its light value
is the only blue-tinted neutral in the palette. DESIGN.md now says so and marks
it for deletion rather than adoption.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 24, 2026
@mrsibe
mrsibe merged commit 31d03b5 into main Sep 24, 2026
4 checks passed
@mrsibe
mrsibe deleted the docs/design-md-accuracy branch September 24, 2026 17:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant