Files
orca/docs/styleguide/native-chat.md
Jinjing 238bdf09f6 Tidy native chat text typography (#42359)
* feat(chat): tidy native chat text typography

Default chat text is 13px in the system UI font on 20px lines, with
paragraphs and list items sharing one line height, bold set by weight in
the body color, and the CI and opened pull request card headers at body
size. Labels, icons and spacing keep their earlier sizes.

* docs(chat): update the chat type scale; trim default-only typography tests
2026-11-14 12:43:04 -08:00

4.3 KiB

Native chat typography and color

Read before changing anything under src/renderer/src/components/native-chat/. Core rules: docs/STYLEGUIDE.md. pnpm lint enforces the type scale, softened-foreground, and focus-ring rules below (config/ast-grep/rules/native-chat-*.yml).

Chat type scale

The native chat uses these steps and no others. Never write an arbitrary size (text-[13px]) inside components/native-chat/.

Step Default Use it for
text-sm 13px Anything the user reads: message prose, tool and agent activity rows, card titles and bodies, the composer
text-xs 12px Labels, timestamps, counters, secondary lines under a row
text-2xs 11px Captions, attribution, uppercase category labels
text-3xs 10px Badges and mono pills
text-chat-code 12px Code blocks, diffs, commands and tool output

The chat root (.native-chat-appearance) redefines these steps from the Text size setting, so every tier scales together; text-chat-code follows the Code text size setting. text-sm is the Text size itself, on one line height for prose and list items (20px at 13px). The smaller steps, the spacing unit, icons, padding and row heights follow the UI size: the Text size, except 14px at the 13px default, so they keep their earlier sizes (spacing 4px).

  • Use spacing-scale utilities (size-3.5, min-h-6.5, pl-3.25), not pixel lengths (min-h-[26px]), or the element stays fixed while the rest scales.
  • Size an element with one of these utilities only: a CSS rule that sets font-size outside a layer silently overrides them.

Text colour, hover and focus

  • Primary text on the chat canvas uses text-chat-foreground, and text-chat-foreground-strong for titles, hover and emphasis; both follow the Contrast setting. Markdown bold and headings keep the surrounding text color and stand out by weight. Don't soften text-foreground by hand (text-foreground/85). text-foreground is for text on a lifted surface inside the chat.
  • Secondary text on the chat canvas (transcript rows, notices, labels between messages) uses text-chat-foreground-faint. text-muted-foreground is for text on a lifted surface inside the chat: cards, menus, popovers and the docks above the composer.
  • Row hover in the transcript is hover:bg-accent/20. Buttons, menu items and card controls use hover:bg-accent.
  • Focus rings: full-width transcript rows use the inset ring (focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring) so it isn't clipped by the scroll container; standalone controls use focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring. Inside the chat --ring is --chat-focus-ring, which clears 3:1 on the canvas; don't lower its opacity.
  • Theme overrides: plugin themes can set --chat-bold-foreground, --chat-muted-foreground, --chat-inline-code, --chat-inline-code-foreground, --chat-code-block, --chat-selection and --chat-selection-foreground. They feed text-chat-foreground-faint, bg-chat-inline-code-surface, bg-chat-code-surface and the chat root's ::selection, so use those rather than reading the theme tokens directly.
  • Selection inside the chat is the link hue mixed into the canvas (close to the system highlight), with selected text in the full foreground so every role stays 4.5:1. Don't add per-component selection: colors in transcript text.
  • State colours: warnings use text-chat-warning; diff lines use text-chat-diff-added / text-chat-diff-removed; what the reader has not seen yet uses text-chat-unread. They are mixed toward the foreground so they pass text contrast in light and dark. Don't use raw palette colours (text-yellow-500) or the git decoration tokens for text on a tinted row.