refactor(web): dashboard typography & contrast pass

nix/web.nix

@@ -4,7 +4,7 @@ let
   src = ../web;
   npmDeps = pkgs.fetchNpmDeps {
     inherit src;
-    hash = "sha256-FL2E8Vv8gyeClEa5b/pHn/ekWoHWTd4YwzV6zhLEos4=";
+    hash = "sha256-YR+dqRKyuwwpnpDQlHqr0XxgTLIX42mUOK60hp0p5uA=";
   };
 
   npm = hermesNpmLib.mkNpmPassthru { folder = "web"; attr = "web"; pname = "hermes-web"; };

web/README.md

@@ -46,3 +46,43 @@ src/
 ├── main.tsx         # React entry point
 └── index.css        # Tailwind imports and theme variables
 ```
+
+## Typography & contrast rules
+
+Read before adding or editing UI styles. These rules keep the dashboard legible across all built-in themes and stop drift back into the patterns the design system was just refactored out of.
+
+### Text size floor
+
+- **Minimum body size: `text-xs` (12px / 0.75rem).** Do not use arbitrary `text-[0.6rem]`, `text-[0.65rem]`, `text-[9px]`, `text-[10px]`, or `text-[11px]` on copy, hints, labels, counts, or badges. Use the standard scale: `text-xs`, `text-sm`, `text-base`.
+- Smaller sizes are only acceptable on **decorative overlays** (chart stripes, empty-state icons) — never on text the user is meant to read.
+
+### Opacity floor on text
+
+- **Never apply opacity below 0.7 to text.** No `opacity-30`, `opacity-50`, `opacity-60` on `<span>`s, `<p>`s, labels, etc.
+- **Do not stack opacity tokens.** Patterns like `text-muted-foreground/60`, `text-midground/70`, `text-foreground/50` create unpredictable WCAG failures because the parent token already has alpha.
+- Use the **semantic text tokens** from `@nous-research/ui`'s `globals.css`:
+  - `text-text-primary` — default body text.
+  - `text-text-secondary` — subtitles, meta, inactive nav.
+  - `text-text-tertiary` — small chrome labels, counts, footnotes.
+  - `text-text-disabled` — disabled states.
+  - `text-text-on-accent` — text on filled accent surfaces.
+
+### Brand uppercase via `text-display`, not raw `uppercase`
+
+- The dashboard preserves the Nous brand uppercase aesthetic, but it is **opt-in per element, not global**.
+- Apply uppercase via the DS utility `text-display` on **brand chrome only** — page titles, nav section headings, badges, brand wordmark. DS components (`Button`, `Badge`, `Tabs`, `Segmented`, etc.) already self-apply `text-display`.
+- **Do not introduce new `uppercase`** (the literal Tailwind class) in `hermes-agent/web/src`. Prefer `text-display` for new brand chrome. Legacy `uppercase` call sites (e.g. `components/ui/label.tsx`, `card.tsx`) remain until migrated.
+- The app shell no longer forces uppercase globally, so blanket `normal-case` opt-outs are unnecessary. Use `normal-case` only where a DS component applies `text-display` but the label should stay sentence case — e.g. dynamic user content (model slugs, theme names) **or** fixed UI copy that is not brand chrome (EnvPage “not configured” toggle, sidebar “New chat”).
+
+### Fonts
+
+- `font-mondwest` is the brand display font. Apply it explicitly only on brand chrome (paired with `text-display`).
+- Body content inherits the active theme's `--theme-font-sans`. Do not hardcode `font-mondwest` on body text or pages — it locks out per-theme typography.
+- Code/terminal text uses `font-mono` / `font-mono-ui` (both resolve through `--theme-font-mono`).
+
+### Color tokens
+
+- Prefer **semantic tokens** (`text-text-*`, `bg-card`, `border-border`, `text-foreground`, `text-destructive`, `text-success`, `text-warning`) over raw layer references (`text-midground`, `text-foreground`).
+- `text-muted-foreground` is now wired to `--color-text-secondary`, so existing call sites stay correct, but new code should prefer the semantic name.
+- When you genuinely need a non-token color (icon de-emphasis on a chart, terminal foreground via inline style), keep alpha at `≥ 0.7` for any text.
+

web/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@nous-research/ui": "0.14.0",
+    "@nous-research/ui": "0.16.0",
     "@observablehq/plot": "^0.6.17",
     "@react-three/fiber": "^9.6.0",
     "@tailwindcss/vite": "^4.2.1",