Web UI style reference

English | 中文

This reference defines styling ownership and component rules for browser client packages. The current token values live in packages/client/ui-theme/src/styles/; this document does not duplicate that generated-by-source inventory.

Ownership

ui-theme owns the --dsw-* static scale, semantic aliases, typography, motion, gradients, shadows, scrollbar styles, and light/dark preference. ui-layout applies the resolved theme snapshot to the document. Feature packages consume semantic aliases and do not define another global theme.

Global style sheets belong in ui-theme/src/styles/. Component styles live beside their component as CSS Modules. A component may define a local custom property when its value is part of that component's layout or presentation contract; shared colors, typography, elevation, and motion belong to the theme package.

Component rules

• Use CSS Modules and clsx; do not add a component library or Tailwind.
• Use --dsw-alias-* semantic tokens in feature components. Do not copy static palette values or write literal colors there.
• Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
• Pair font sizes with line heights and use the theme typography variables when an existing role matches.
• Keep source text, terminal output, and diff lines unwrapped when their component contract requires column preservation; use the shared scrollbar styles rather than component-specific scrollbar selectors.
• Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
• Preserve keyboard focus visibility and reduced-motion behavior when adding transitions or hover-only controls.

Changing the system

Add or change a shared token in the owning ui-theme sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the testing policy; the styling-system Agent Note records framework rationale.