diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
new file mode 100644
index 0000000..55a4a63
--- /dev/null
+++ b/.github/workflows/rust.yml
@@ -0,0 +1,56 @@
+name: Rust
+
+# This repo shipped with no CI at all — `.github/` held only banner images —
+# so `rust/src/auth/refresh.rs` could sit for weeks as 174 lines that never
+# compiled (no `mod refresh;`), and the design tokens could drift from the CSS
+# unnoticed. Every check below exists because something got through without it.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: rust
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Format check
+        run: cargo fmt --check
+
+      # `--all-targets` so tests and examples are linted too; `-p`-scoped or
+      # target-less clippy silently skips test code.
+      - name: Clippy (default features — the no_std `ui` build)
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Clippy (all features)
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+      # Run BOTH feature sets: the `ui` tests are the only ones in the default
+      # build, and the `auth` tests only exist behind the feature — running one
+      # configuration would report a green suite that never touched half the crate.
+      - name: Test (default features)
+        run: cargo test
+
+      - name: Test (all features)
+        run: cargo test --all-features
+
+  module-tree:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Catches the `refresh.rs` class: a .rs file on disk that no `mod`
+      # declaration reaches, so it never compiles and no other check sees it.
+      - name: Every .rs file is reachable from the module tree
+        run: python3 scripts/check-module-tree.py
diff --git a/README.md b/README.md
index c988daa..374f6ca 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@
 
 ---
 
-> **Every Smoo AI Rust client needs the same three things — so they live in one crate.** Design tokens + the smoo monogram (`ui`), the full Supabase auth story — browser OAuth with PKCE, email+password, session refresh, M2M `client_credentials` — with a shared 0600 on-disk credential store (`auth`), and an LLM session exchange (`llm`, **stub today**). One Rust crate, feature-gated so the bare `ui` build stays `no_std` with zero dependencies. Consumed in production by the [`th` CLI](https://github.com/SmooAI/smooth). **Rust-only today; not yet on crates.io** — npm / NuGet / PyPI siblings are planned, not built.
+> **Every Smoo AI Rust client needs the same three things — so they live in one crate.** Design tokens + the smoo monogram (`ui`), the full Supabase auth story — browser OAuth with PKCE, email+password, session refresh, M2M `client_credentials` — with a shared 0600 on-disk credential store (`auth`), One Rust crate, feature-gated so the bare `ui` build stays `no_std` with zero dependencies. Consumed in production by the [`th` CLI](https://github.com/SmooAI/smooth). **Rust-only today; not yet on crates.io** — npm / NuGet / PyPI siblings are planned, not built.
 
 ## What is this?
 
@@ -29,9 +29,9 @@ A Smoo AI Rust client (smooblue, observability-studio, `th`, `smoo admin`, …)
 
 1. **Design tokens + monogram** — so the UI looks like Smoo AI.
 2. **Auth** — Supabase user OAuth (browser login), email+password, session refresh, AND M2M `client_credentials` grant (service accounts), with one shared on-disk `CredentialsStore`.
-3. **LLM access** — exchanging a user session JWT for an org-scoped `llm.smoo.ai` bearer. *(Not implemented yet — see [Honest status](#honest-status).)*
+3. **LLM access** — exchanging a user session JWT for an org-scoped `llm.smoo.ai` bearer. *(Not built — there is deliberately no feature flag for it yet; see [Honest status](#honest-status).)*
 
-Each of these has been re-implemented in every consumer at least once. This crate makes them one dependency. It absorbs the standalone [`SmooAI/ui`](https://github.com/SmooAI/ui) crate: `ui` is one module among siblings (`auth`, `llm`) — same constants, same paths, byte-identical `shared/` sources.
+Each of these has been re-implemented in every consumer at least once. This crate makes them one dependency. It absorbs the standalone [`SmooAI/ui`](https://github.com/SmooAI/ui) crate: `ui` is one module alongside `auth` — same constants, same paths. This repo's `shared/` is the **source of truth** for the design system; SmooAI/ui carries a copy, and a CI gate there fails if the two ever diverge.
 
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{
@@ -42,7 +42,6 @@ flowchart LR
   subgraph CRATE["smooai-client-shared"]
     UI["ui (default)<br/>STYLES · MONOGRAM_SVG · tokens::*<br/>zero deps · no_std"]
     AUTH["auth (feature)<br/>oauth · password · refresh · m2m<br/>CredentialsStore (0600)"]
-    LLM["llm (feature)<br/>STUB — pending"]
   end
   AUTH -->|"PKCE localhost callback"| SB[("Supabase<br/>/auth/v1")]
   AUTH -->|"client_credentials"| TOK[("auth.smoo.ai/token")]
@@ -162,15 +161,16 @@ smooai-client-shared = { git = "https://github.com/SmooAI/client-shared.git", fe
 | --- | --- | --- | --- |
 | `ui` (default) | `STYLES`, `MONOGRAM_SVG`, `tokens::*` | nothing — `no_std` | ✅ working |
 | `auth` | Supabase OAuth + password + refresh, M2M, `CredentialsStore` | `tokio`, `reqwest`, `axum`, `serde`, … | ✅ working, 28 unit tests |
-| `llm` | JWT → `llm.smoo.ai` org-session exchange | (implies `auth`) | 🚧 **stub — compiles, no usable surface** (pearl th-f7b20f) |
 
-Run the tests yourself — 32 unit tests across `ui` + `auth` (OAuth callback/PKCE, token rotation, store round-trips, permission bits):
+An `llm` feature (JWT → `llm.smoo.ai` org-session exchange, pearl th-f7b20f) is **planned and deliberately absent**. It previously existed as a flag over a six-line doc-comment module: `--features llm` compiled and produced nothing, which is worse than an honest gap. It returns when there is code behind it.
+
+Run the tests yourself — 34 unit tests across `ui` + `auth` (OAuth callback/PKCE, token rotation, store round-trips, permission bits, token/CSS drift):
 
 ```bash
-cd rust && cargo test --features auth,llm
+cd rust && cargo test --all-features
 ```
 
-There is no CI in this repo yet — run the tests locally before merging.
+CI (`.github/workflows/rust.yml`) runs `cargo fmt --check`, `clippy --all-targets -D warnings` and the test suite in **both** feature configurations — the default `no_std` `ui` build and `--all-features` — plus a module-tree check that fails if any `.rs` file is unreachable from a `mod` declaration.
 
 ---
 
@@ -178,9 +178,9 @@ There is no CI in this repo yet — run the tests locally before merging.
 
 | Surface | Status |
 | --- | --- |
-| **Rust `ui`** | ✅ Working — byte-identical to the `smooai-ui` crate's surface; drift-tested against `shared/styles.css` |
+| **Rust `ui`** | ✅ Working — the `tokens` constants are **generated** from `shared/tokens.json` at build time, and cross-checked against `shared/styles.css` in both directions (every token matches its custom property; every colour the CSS declares has a token) |
 | **Rust `auth`** | ✅ Working — OAuth PKCE localhost-callback (387 LOC), password grant, refresh with rotation, M2M, 0600 `CredentialsStore`; 28 unit tests; consumed by the `th` CLI in production |
-| **Rust `llm`** | 🚧 **Stub** — the feature flag exists and compiles, but the module is a doc-comment placeholder. Building with `--features llm` gives you no usable API today |
+| **Rust `llm`** | ❌ Not built — no module, no feature flag. Pearl th-f7b20f tracks it |
 | **crates.io** | ❌ Not published — git dependency is the only install path |
 | **npm / NuGet / PyPI** | 📦 Planned, no code — the `src/`, `dotnet/`, `python/` directories in the layout below don't exist yet |
 
@@ -191,14 +191,15 @@ client-shared/
 ├── shared/                # cross-language source of truth
 │   ├── styles.css         # OKLCH tokens + base component CSS
 │   ├── monogram.svg       # smoo monogram
-│   └── tokens.json        # tokens as plain JSON (no consumer yet)
+│   ├── tokens.json        # THE token source — the Rust `tokens` module is generated from it
+│   ├── tokens_codegen.rs  # generator, run from rust/build.rs
+│   └── tokens_css_check.rs # asserts tokens.json <-> styles.css agree, both ways
 └── rust/                  # smooai-client-shared (git dependency; crates.io planned)
     ├── Cargo.toml
     └── src/
         ├── lib.rs
         ├── ui/            # lifted verbatim from smooai-ui
-        ├── auth/          # oauth · password · refresh · m2m · storage  (feature = "auth")
-        └── llm/           # STUB — pending pearl th-f7b20f             (feature = "llm")
+        └── auth/          # oauth · password · refresh · m2m · storage  (feature = "auth")
 ```
 
 npm (`src/`), NuGet (`dotnet/`), and PyPI (`python/`) packages are roadmap, not directories.
@@ -240,7 +241,7 @@ The `ui` module is API-compatible with `smooai-ui`: same constants, same paths,
 
 ## 🤝 Contributing
 
-PRs welcome. `cd rust && cargo test --features auth,llm` must pass; keep the bare `ui` build zero-dep and `no_std`, and gate anything heavier behind a feature flag.
+PRs welcome. `cd rust && cargo test --all-features` must pass; keep the bare `ui` build zero-dep and `no_std`, and gate anything heavier behind a feature flag.
 
 ## 📄 License
 
diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index 94ae2a0..7de4482 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -3,10 +3,10 @@ name = "smooai-client-shared"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
-description = "SmooAI's cross-runtime client shared library — design tokens, monogram, auth, and llm session primitives shared across every SmooAI Rust app (smooblue, observability-studio, th, th admin, …)."
+description = "SmooAI's cross-runtime client shared library — design tokens, monogram, and auth primitives shared across every SmooAI Rust app (smooblue, observability-studio, th, th admin, …)."
 repository = "https://github.com/SmooAI/client-shared"
 homepage = "https://github.com/SmooAI/client-shared"
-keywords = ["smooai", "design-system", "auth", "llm", "client"]
+keywords = ["smooai", "design-system", "auth", "client"]
 categories = ["gui", "authentication", "config"]
 readme = "README.md"
 authors = ["SmooAI <brent@smoo.ai>"]
@@ -16,10 +16,13 @@ authors = ["SmooAI <brent@smoo.ai>"]
 include = [
     "Cargo.toml",
     "README.md",
+    "build.rs",
     "src/**/*.rs",
     "../shared/styles.css",
     "../shared/monogram.svg",
     "../shared/tokens.json",
+    "../shared/tokens_codegen.rs",
+    "../shared/tokens_css_check.rs",
     "../LICENSE",
 ]
 
@@ -27,14 +30,19 @@ include = [
 # Default to the lightweight `ui` module so existing smooai-ui
 # consumers (smooblue, observability-studio) get the same dependency
 # tree they had before — no tokio, no reqwest, still no_std-friendly.
-# Opt into `auth` / `llm` only when needed.
+# Opt into `auth` only when needed.
 default = ["ui"]
 ui = []
 auth = ["dep:tokio", "dep:reqwest", "dep:serde", "dep:serde_json", "dep:url", "dep:axum", "dep:anyhow", "dep:chrono", "dep:dirs-next", "dep:webbrowser", "dep:rand", "dep:base64", "dep:sha2"]
-llm = ["auth"]
+
+[build-dependencies]
+# Build-script only: parses shared/tokens.json to generate the `tokens`
+# module. Build dependencies are host-side and never reach consumers, so the
+# bare `ui` build stays zero-dependency and `no_std`.
+serde_json = "1"
 
 [dependencies]
-# Heavy deps gated behind `auth` / `llm` features so the bare `ui`
+# Heavy deps gated behind the `auth` feature so the bare `ui`
 # build stays no_std-compatible and zero-dep.
 tokio = { version = "1", features = ["macros", "rt-multi-thread", "fs", "net", "sync", "time"], optional = true }
 reqwest = { version = "0.12", features = ["json"], optional = true }
diff --git a/rust/build.rs b/rust/build.rs
new file mode 100644
index 0000000..a44518c
--- /dev/null
+++ b/rust/build.rs
@@ -0,0 +1,17 @@
+//! Generate the `tokens` module from `shared/tokens.json`.
+//!
+//! The generator itself lives in `shared/tokens_codegen.rs` so SmooAI/ui and
+//! SmooAI/client-shared generate identically from the identical input — the
+//! `shared/**` drift gate keeps those files byte-for-byte equal. This build
+//! script is only the shim that feeds it.
+
+include!("../shared/tokens_codegen.rs");
+
+fn main() {
+    println!("cargo:rerun-if-changed=../shared/tokens.json");
+    println!("cargo:rerun-if-changed=../shared/tokens_codegen.rs");
+
+    let json = std::fs::read_to_string("../shared/tokens.json").expect("read shared/tokens.json");
+    let out = std::path::Path::new(&std::env::var("OUT_DIR").expect("OUT_DIR")).join("tokens.rs");
+    std::fs::write(out, generate_tokens_rs(&json)).expect("write tokens.rs");
+}
diff --git a/rust/src/lib.rs b/rust/src/lib.rs
index 67e7d8c..473713f 100644
--- a/rust/src/lib.rs
+++ b/rust/src/lib.rs
@@ -7,8 +7,7 @@
 //! `smoo admin` (the Smooth CLI), and any future Rust client.
 //!
 //! Replaces the standalone `smooai-ui` crate (which only carried the
-//! `ui` slice) by adding `auth` and `llm` modules behind feature
-//! flags. The bare `default-features = ["ui"]` build stays
+//! `ui` slice) by adding an `auth` module behind a feature flag. The bare `default-features = ["ui"]` build stays
 //! `no_std`-compatible with zero runtime dependencies — same shape as
 //! the old `smooai-ui` so existing consumers don't inherit any new
 //! tree.
@@ -18,10 +17,14 @@
 //! - `ui` (default) — design tokens, base CSS, monogram. Zero deps,
 //!   `no_std`.
 //! - `auth` — Supabase user OAuth (localhost-callback flow), M2M
-//!   `client_credentials` grant, on-disk `CredentialsStore`. Pulls
-//!   in `tokio`, `reqwest`, `serde`, `axum`.
-//! - `llm` — JWT → `llm.smoo.ai` org-scoped LLM session exchange.
-//!   Implies `auth`.
+//!   `client_credentials` grant, refresh-token rotation, on-disk
+//!   `CredentialsStore`. Pulls in `tokio`, `reqwest`, `serde`, `axum`.
+//!
+//! An `llm` feature (JWT → `llm.smoo.ai` org-scoped session exchange)
+//! is planned under pearl th-f7b20f. It is deliberately **absent**
+//! rather than stubbed: a feature flag that compiles to an empty
+//! module advertises a capability that does not exist. It comes back
+//! when there is something behind it.
 //!
 //! ## Migrating from `smooai-ui`
 //!
@@ -42,7 +45,7 @@
 //! path it lived at under `smooai_ui::` (e.g. `STYLES`,
 //! `MONOGRAM_SVG`, `tokens::*`).
 
-#![cfg_attr(not(any(feature = "auth", feature = "llm")), no_std)]
+#![cfg_attr(not(feature = "auth"), no_std)]
 #![doc(html_root_url = "https://docs.rs/smooai-client-shared/0.1.0")]
 #![warn(missing_docs)]
 
@@ -51,6 +54,3 @@ pub mod ui;
 
 #[cfg(feature = "auth")]
 pub mod auth;
-
-#[cfg(feature = "llm")]
-pub mod llm;
diff --git a/rust/src/llm/mod.rs b/rust/src/llm/mod.rs
deleted file mode 100644
index 0d463c5..0000000
--- a/rust/src/llm/mod.rs
+++ /dev/null
@@ -1,6 +0,0 @@
-//! # llm — JWT → llm.smoo.ai org-scoped LLM session exchange.
-//!
-//! **PENDING (pearl th-f7b20f)**. This module is stubbed so the
-//! `#[cfg(feature = "llm")] pub mod llm;` declaration in `lib.rs`
-//! resolves cleanly — building with `--features llm` today produces
-//! no usable surface; landing pearl th-f7b20f fills it in.
diff --git a/rust/src/ui/mod.rs b/rust/src/ui/mod.rs
index f5ad7e5..a86cfde 100644
--- a/rust/src/ui/mod.rs
+++ b/rust/src/ui/mod.rs
@@ -15,52 +15,23 @@ pub const STYLES: &str = include_str!("../../../shared/styles.css");
 /// backdrop.
 pub const MONOGRAM_SVG: &str = include_str!("../../../shared/monogram.svg");
 
-/// Brand + semantic token *values* as `&'static str`, for code paths
-/// that need a colour outside of CSS (custom-painted egui widgets,
-/// native menu chrome, chart libraries, etc.). The single source of
-/// truth is the CSS in [`STYLES`]; these constants are mirrored from
-/// it and validated by the `tokens_match_css` test below.
+/// Brand + semantic token *values*, for code paths that need a colour,
+/// radius, spacing step, or font stack outside of CSS (custom-painted egui
+/// widgets, native menu chrome, chart libraries, etc.).
+///
+/// **Generated** at build time from
+/// [`shared/tokens.json`](https://github.com/SmooAI/client-shared/blob/main/shared/tokens.json)
+/// by `shared/tokens_codegen.rs` — nobody hand-writes these, so a token cannot
+/// exist in the design system and be missing here. `shared/tokens_css_check.rs`
+/// then asserts each one equals the resolved value of its custom property in
+/// [`STYLES`], and that every colour the CSS declares has a token.
 pub mod tokens {
-    /// Brand orange — primary CTA stop, accent.
-    pub const SMOOAI_ORANGE: &str = "oklch(0.769 0.164 71)";
-    /// Brand red — destructive, "like" affordance.
-    pub const SMOOAI_RED: &str = "oklch(0.712 0.181 22.4)";
-    /// Brand green — confirm / "repost" affordance / focus ring.
-    pub const SMOOAI_GREEN: &str = "oklch(0.657 0.112 194.8)";
-    /// Lightest brand blue — reply hover.
-    pub const SMOOAI_BLUE_300: &str = "oklch(0.803 0.074 230.9)";
-    /// Mid brand blue.
-    pub const SMOOAI_BLUE_400: &str = "oklch(0.725 0.102 233.4)";
-    /// Active nav-rail item background.
-    pub const SMOOAI_BLUE_500: &str = "oklch(0.55 0.13 233)";
-    /// Brand dark blue — base background.
-    pub const SMOOAI_DARK_BLUE: &str = "oklch(0.13 0.043 265.1)";
-    /// Sidebar tint.
-    pub const SMOOAI_DARK_BLUE_850: &str = "oklch(0.177 0.074 266)";
-    /// Hover on rail items.
-    pub const SMOOAI_DARK_BLUE_700: &str = "oklch(0.303 0.154 265.8)";
-    /// Brand white.
-    pub const SMOOAI_WHITE: &str = "oklch(0.984 0.003 247.9)";
-    /// Muted text.
-    pub const SMOOAI_GRAY_400: &str = "oklch(0.715 0 89.9)";
+    include!(concat!(env!("OUT_DIR"), "/tokens.rs"));
 
-    /// Default page background.
-    pub const BACKGROUND: &str = "oklch(0.145 0.014 265)";
-    /// Default text color.
-    pub const FOREGROUND: &str = SMOOAI_WHITE;
-    /// Card surface background.
-    pub const CARD: &str = "oklch(0.205 0.015 265)";
-    /// Border / divider.
-    pub const BORDER: &str = "oklch(0.3 0.008 260)";
-
-    /// Signature brand gradient — gradient-as-string for `background: …;`.
-    /// Note that CSS doesn't accept gradients in inline `color:` — this is
-    /// for `background` and SVG paint only.
-    pub const GRADIENT_BRAND: &str =
-        "linear-gradient(135deg, oklch(0.769 0.164 71) 0%, oklch(0.712 0.181 22.4) 100%)";
-
-    /// Default radius for cards + buttons (matches `--radius` in CSS).
-    pub const RADIUS_PX: u16 = 10;
+    /// The default corner radius, as used by cards and buttons. Retained as an
+    /// alias of [`RADIUS_MD_PX`] so consumers pinned to the pre-codegen name
+    /// keep compiling.
+    pub const RADIUS_PX: u16 = RADIUS_MD_PX;
 }
 
 #[cfg(test)]
@@ -81,35 +52,9 @@ mod tests {
         assert!(MONOGRAM_SVG.contains("fill=\"currentColor\""));
     }
 
-    /// Validate that every token value in the `tokens` module is also
-    /// present in the CSS, so the two sources of truth can't silently
-    /// drift.
-    #[test]
-    fn tokens_match_css() {
-        let css = STYLES;
-        for (name, value) in [
-            ("SMOOAI_ORANGE", tokens::SMOOAI_ORANGE),
-            ("SMOOAI_RED", tokens::SMOOAI_RED),
-            ("SMOOAI_GREEN", tokens::SMOOAI_GREEN),
-            ("SMOOAI_BLUE_300", tokens::SMOOAI_BLUE_300),
-            ("SMOOAI_BLUE_400", tokens::SMOOAI_BLUE_400),
-            ("SMOOAI_BLUE_500", tokens::SMOOAI_BLUE_500),
-            ("SMOOAI_DARK_BLUE", tokens::SMOOAI_DARK_BLUE),
-            ("SMOOAI_DARK_BLUE_850", tokens::SMOOAI_DARK_BLUE_850),
-            ("SMOOAI_DARK_BLUE_700", tokens::SMOOAI_DARK_BLUE_700),
-            ("SMOOAI_WHITE", tokens::SMOOAI_WHITE),
-            ("SMOOAI_GRAY_400", tokens::SMOOAI_GRAY_400),
-            ("BACKGROUND", tokens::BACKGROUND),
-            ("CARD", tokens::CARD),
-            ("BORDER", tokens::BORDER),
-        ] {
-            assert!(
-                css.contains(value),
-                "token {name} = {value:?} not found in shared/styles.css — Rust \
-                 constants and CSS have drifted",
-            );
-        }
-    }
+    // The token <-> CSS cross-check (both directions) lives in `shared/`, so
+    // SmooAI/client-shared and SmooAI/ui run the identical assertions.
+    include!("../../../shared/tokens_css_check.rs");
 
     #[test]
     fn semantic_classes_exist() {
@@ -123,6 +68,10 @@ mod tests {
             ".rail",
             ".rail__btn",
             ".brand-badge",
+            ".input",
+            ".input--lg",
+            ".input-error",
+            ".input-hint",
         ] {
             assert!(STYLES.contains(cls), "missing class {cls}");
         }
diff --git a/scripts/check-module-tree.py b/scripts/check-module-tree.py
new file mode 100644
index 0000000..8cb8024
--- /dev/null
+++ b/scripts/check-module-tree.py
@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Fail if any .rs file under rust/src/ is unreachable from the module tree.
+
+An orphaned file compiles to nothing and is invisible to every other check:
+`cargo build`, `clippy`, `cargo test` and code coverage all skip it, because as
+far as rustc is concerned it does not exist. Reviewers see a diff full of real
+code and assume it ships.
+
+SmooAI/client-shared shipped exactly that: 174 lines of auth token-refresh code
+in `rust/src/auth/refresh.rs` that `auth/mod.rs` never declared, so it never
+compiled once (fixed upstream in a21c06b). This is the check that would have
+caught it the same day.
+
+Deliberately textual rather than a real parse: a `mod foo;` behind a `#[cfg(...)]`
+still counts as declared, which is what we want — the question is whether the
+file is wired in at all, not whether it is wired in for every feature set.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+SRC = Path(__file__).resolve().parent.parent / "rust" / "src"
+
+
+def declares(parent: Path, name: str) -> bool:
+    """Whether `parent` contains a `mod <name>;` / `mod <name> { … }` declaration."""
+    if not parent.is_file():
+        return False
+    return re.search(rf"\bmod\s+{re.escape(name)}\s*[;{{]", parent.read_text()) is not None
+
+
+ROOTS = [SRC / "lib.rs", SRC / "main.rs"]
+
+
+def module_of(rs: Path) -> tuple[str, list[Path]]:
+    """The module name `rs` defines, and the file(s) that could declare it."""
+    if rs.name == "mod.rs":
+        # `src/a/mod.rs` defines module `a`, declared one level up.
+        name, parent_dir = rs.parent.name, rs.parent.parent
+    else:
+        # `src/a/b.rs` defines module `b`, declared in `src/a`.
+        name, parent_dir = rs.stem, rs.parent
+
+    if parent_dir == SRC:
+        return name, ROOTS
+    # Either module style: `src/a/mod.rs` or the 2018-edition `src/a.rs`.
+    return name, [parent_dir / "mod.rs", parent_dir.with_suffix(".rs")]
+
+
+def main() -> int:
+    if not SRC.is_dir():
+        print(f"no {SRC} — nothing to check")
+        return 0
+
+    repo = SRC.parent.parent
+    orphans = []
+
+    for rs in sorted(SRC.rglob("*.rs")):
+        if rs in ROOTS:
+            continue
+        name, candidates = module_of(rs)
+        if not any(declares(c, name) for c in candidates):
+            where = " or ".join(str(c.relative_to(repo)) for c in candidates)
+            orphans.append(f"  {rs.relative_to(repo)} — no `mod {name};` in {where}")
+
+    if orphans:
+        print("Orphaned module files (present on disk, never compiled):", file=sys.stderr)
+        print("\n".join(orphans), file=sys.stderr)
+        print(
+            "\nDeclare each with `mod <name>;` / `pub mod <name>;` in its parent, "
+            "or delete the file.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"✓ every .rs file under {SRC.relative_to(repo)} is in the module tree")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/shared/monogram.svg b/shared/monogram.svg
index 18965ef..7fd88a4 100644
--- a/shared/monogram.svg
+++ b/shared/monogram.svg
@@ -1,3 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 135 135" fill="currentColor" fill-rule="evenodd">
-    <path d="M45.63,15.38c-12.39,5.21-22.54,14.64-28.65,26.61-6.12,11.97-7.8,25.72-4.77,38.81,3.04,13.09,10.6,24.69,21.36,32.75,10.76,8.06,24.02,12.05,37.44,11.28,13.42-.77,26.13-6.26,35.9-15.5,9.76-9.24,15.95-21.63,17.46-34.99,1.51-13.36-1.74-26.82-9.19-38.01-1.07-1.61-.64-3.78.97-4.85,1.61-1.07,3.78-.64,4.85.97,8.36,12.56,12.02,27.68,10.32,42.67-1.7,15-8.64,28.91-19.61,39.28-10.96,10.37-25.24,16.54-40.31,17.4-15.07.87-29.96-3.62-42.04-12.66-12.08-9.05-20.58-22.07-23.99-36.77-3.41-14.7-1.51-30.14,5.35-43.58,6.87-13.44,18.26-24.02,32.17-29.87,13.91-5.85,29.44-6.6,43.85-2.11,1.85.57,2.88,2.54,2.3,4.38-.57,1.85-2.54,2.88-4.38,2.3-12.83-4-26.67-3.33-39.06,1.88Z"/>
+    <path d="M45.63,15.38c-12.39,5.21-22.54,14.64-28.65,26.61-6.12,11.97-7.8,25.72-4.77,38.81,3.04,13.09,10.6,24.69,21.36,32.75,10.76,8.06,24.02,12.05,37.44,11.28,13.42-.77,26.13-6.26,35.9-15.5,9.76-9.24,15.95-21.63,17.46-34.99,1.51-13.36-1.74-26.82-9.19-38.01-1.07-1.61-.64-3.78.97-4.85,1.61-1.07,3.78-.64,4.85.97,8.36,12.56,12.02,27.68,10.32,42.67-1.7,15-8.64,28.91-19.61,39.28-10.96,10.37-25.24,16.54-40.31,17.4-15.07.87-29.96-3.62-42.04-12.66-12.08-9.05-20.58-22.07-23.99-36.77-3.41-14.7-1.51-30.14,5.35-43.58,6.87-13.44,18.26-24.02,32.17-29.87,13.91-5.85,29.44-6.6,43.85-2.11,1.85.57,2.88,2.54,2.3,4.38-.57,1.85-2.54,2.88-4.38,2.3-12.83-4-26.67-3.33-39.06,1.88ZM108.73,20.17c0,2.07-1.68,3.75-3.75,3.75s-3.75-1.68-3.75-3.75,1.68-3.75,3.75-3.75,3.75,1.68,3.75,3.75ZM61.98,60.34c0,1.91,2.39,2.56,7.69,3.88,3.89.97,6.6,2.18,8.15,3.63,1.53,1.45,2.29,3.53,2.29,6.25,0,3.57-1.03,6.26-3.11,8.08-2.07,1.82-5.09,2.73-9.09,2.73h-9.6c-1.97,0-3.57-1.6-3.59-3.57-.01-1.99,1.6-3.61,3.59-3.61h9.41c3.15-.12,4.79-.95,4.91-2.47,0-1.3-1.03-2.21-3.07-2.73-6.91-1.72-11.11-3.44-12.6-5.15-1.48-1.71-2.23-3.77-2.23-6.19,0-6.59,3.2-9.85,9.59-9.8h10.77c1.99,0,3.6,1.61,3.6,3.59s-1.61,3.59-3.6,3.59h-9.69c-1.83,0-3.43.06-3.43,1.77Z"/>
 </svg>
diff --git a/shared/styles.css b/shared/styles.css
index 18cd013..65384c2 100644
--- a/shared/styles.css
+++ b/shared/styles.css
@@ -328,6 +328,66 @@ input {
     color: var(--color-smooai-white);
 }
 
+/* ===========================================================
+ *  Text inputs + textareas
+ *
+ *  Single canonical form-field style so every consumer's auth screen,
+ *  search bar, settings field, and compose box look like they came from
+ *  the same product. Apply `.input` to <input>, <textarea>, or
+ *  <select>. Modifier `.input--lg` for hero / login-card inputs.
+ * =========================================================== */
+
+.input {
+    width: 100%;
+    padding: 8px 12px;
+    background: var(--input);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--foreground);
+    font: inherit;
+    font-size: 14px;
+    line-height: 1.45;
+    outline: none;
+    transition:
+        border-color 120ms ease,
+        background-color 120ms ease;
+}
+
+.input::placeholder {
+    color: var(--muted-foreground);
+}
+
+.input:focus {
+    border-color: var(--ring);
+}
+
+.input:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+}
+
+.input--lg {
+    padding: 10px 14px;
+    font-size: 15px;
+}
+
+textarea.input {
+    min-height: 96px;
+    resize: vertical;
+}
+
+.input-error {
+    color: var(--color-smooai-red);
+    font-size: 13px;
+    margin-top: 6px;
+}
+
+.input-hint {
+    color: var(--muted-foreground);
+    font-size: 12px;
+    margin-top: 6px;
+}
+
 /* ===========================================================
  *  Brand monogram badge
  * =========================================================== */
diff --git a/shared/tokens.json b/shared/tokens.json
index be5fa2f..8bcc72b 100644
--- a/shared/tokens.json
+++ b/shared/tokens.json
@@ -1,55 +1,140 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "name": "@smooai/ui design tokens",
-    "version": "0.1.0",
-    "description": "Language-agnostic source of truth for SmooAI brand + semantic tokens. Per-language bindings (smooai-ui Rust crate, @smooai/ui npm package, etc.) mirror these values and assert at test time that they match shared/styles.css.",
+    "name": "SmooAI design tokens",
+    "description": "Language-agnostic source of truth for SmooAI brand + semantic tokens. This file is not documentation — it is CODE INPUT: the Rust crate's `tokens` module is generated from it at build time (rust/build.rs + shared/tokens_codegen.rs), and shared/tokens_css_check.rs asserts every value here matches the corresponding custom property in shared/styles.css, in both directions. Add a token here and the bindings follow; add one only to the CSS and the check fails.",
+    "conventions": {
+        "cssVar": "color.brand.<key> -> --color-smooai-<key>; color.semantic.<key> -> --<key>; gradient.<key> -> --gradient-<key>; radius.<key> -> --radius-<key>, except radius.md -> --radius; space.<n> -> --space-<n>; font.<key> -> --font-<key>. Underscores become hyphens.",
+        "rustConst": "color.brand.<key> -> SMOOAI_<KEY>; color.semantic.<key> -> <KEY>; gradient.<key> -> GRADIENT_<KEY>; radius.<key> -> RADIUS_<KEY>_PX (u16); space.<n> -> SPACE_<N>_PX (u16); font.<key> -> FONT_<KEY>.",
+        "ref": "A token whose value is another token's, by dotted path. Generates a Rust alias and is expected to be `var(--other)` in the CSS.",
+        "doc": "Required on every token — it becomes the Rust doc comment, and the crate denies missing docs."
+    },
     "color": {
         "brand": {
-            "orange": { "oklch": "oklch(0.769 0.164 71)", "hex": "#f49f0a" },
-            "red": { "oklch": "oklch(0.712 0.181 22.4)", "hex": "#ff6b6c" },
-            "green": { "oklch": "oklch(0.657 0.112 194.8)", "hex": "#00a6a6" },
-            "blue_300": { "oklch": "oklch(0.803 0.074 230.9)" },
-            "blue_400": { "oklch": "oklch(0.725 0.102 233.4)" },
-            "blue_500": { "oklch": "oklch(0.55 0.13 233)" },
-            "dark_blue": { "oklch": "oklch(0.13 0.043 265.1)", "hex": "#020618" },
-            "dark_blue_700": { "oklch": "oklch(0.303 0.154 265.8)" },
-            "dark_blue_850": { "oklch": "oklch(0.177 0.074 266)" },
-            "white": { "oklch": "oklch(0.984 0.003 247.9)" },
-            "gray_400": { "oklch": "oklch(0.715 0 89.9)" }
+            "orange": {
+                "oklch": "oklch(0.769 0.164 71)",
+                "hex": "#f49f0a",
+                "doc": "Brand orange — primary CTA stop, accent."
+            },
+            "red": {
+                "oklch": "oklch(0.712 0.181 22.4)",
+                "hex": "#ff6b6c",
+                "doc": "Brand red — destructive, \"like\" affordance."
+            },
+            "green": {
+                "oklch": "oklch(0.657 0.112 194.8)",
+                "hex": "#00a6a6",
+                "doc": "Brand green — confirm / \"repost\" affordance / focus ring."
+            },
+            "blue_300": {
+                "oklch": "oklch(0.803 0.074 230.9)",
+                "doc": "Lightest brand blue — reply hover."
+            },
+            "blue_400": {
+                "oklch": "oklch(0.725 0.102 233.4)",
+                "doc": "Mid brand blue."
+            },
+            "blue_500": {
+                "oklch": "oklch(0.55 0.13 233)",
+                "doc": "Active nav-rail item background."
+            },
+            "dark_blue": {
+                "oklch": "oklch(0.13 0.043 265.1)",
+                "hex": "#020618",
+                "doc": "Brand dark blue — base background."
+            },
+            "dark_blue_700": {
+                "oklch": "oklch(0.303 0.154 265.8)",
+                "doc": "Hover on rail items."
+            },
+            "dark_blue_850": {
+                "oklch": "oklch(0.177 0.074 266)",
+                "doc": "Sidebar tint."
+            },
+            "white": {
+                "oklch": "oklch(0.984 0.003 247.9)",
+                "doc": "Brand white."
+            },
+            "gray_400": {
+                "oklch": "oklch(0.715 0 89.9)",
+                "doc": "Muted text."
+            }
         },
         "semantic": {
-            "background": { "oklch": "oklch(0.145 0.014 265)" },
-            "foreground": { "ref": "color.brand.white" },
-            "card": { "oklch": "oklch(0.205 0.015 265)" },
-            "muted": { "oklch": "oklch(0.27 0.01 260)" },
-            "muted_foreground": { "ref": "color.brand.gray_400" },
-            "accent": { "ref": "color.brand.orange" },
-            "border": { "oklch": "oklch(0.3 0.008 260)" },
-            "input": { "oklch": "oklch(0.38 0.006 260)" },
-            "ring": { "ref": "color.brand.green" },
-            "sidebar": { "ref": "color.brand.dark_blue_850" }
+            "background": {
+                "oklch": "oklch(0.145 0.014 265)",
+                "doc": "Default page background."
+            },
+            "foreground": {
+                "ref": "color.brand.white",
+                "doc": "Default text color."
+            },
+            "card": {
+                "oklch": "oklch(0.205 0.015 265)",
+                "doc": "Card surface background."
+            },
+            "muted": {
+                "oklch": "oklch(0.27 0.01 260)",
+                "doc": "Muted surface — inactive chips, disabled fills."
+            },
+            "muted_foreground": {
+                "ref": "color.brand.gray_400",
+                "doc": "Muted text on any surface."
+            },
+            "accent": {
+                "ref": "color.brand.orange",
+                "doc": "Accent — highlights, active affordances."
+            },
+            "border": {
+                "oklch": "oklch(0.3 0.008 260)",
+                "doc": "Border / divider."
+            },
+            "input": {
+                "oklch": "oklch(0.38 0.006 260)",
+                "doc": "Text-input / textarea fill."
+            },
+            "ring": {
+                "oklch": "oklch(0.657 0.112 194.8)",
+                "doc": "Focus ring."
+            },
+            "sidebar": {
+                "ref": "color.brand.dark_blue_850",
+                "doc": "Sidebar / nav-rail surface."
+            },
+            "sidebar_border": {
+                "ref": "color.semantic.border",
+                "doc": "Sidebar edge — split from `border` so a rail can be retinted alone."
+            }
         }
     },
     "gradient": {
-        "brand": "linear-gradient(135deg, oklch(0.769 0.164 71) 0%, oklch(0.712 0.181 22.4) 100%)"
+        "brand": {
+            "value": "linear-gradient(135deg, oklch(0.769 0.164 71) 0%, oklch(0.712 0.181 22.4) 100%)",
+            "doc": "Signature brand gradient — gradient-as-string for `background: …;`. CSS does not accept gradients in inline `color:`; this is for `background` and SVG paint only."
+        }
     },
     "radius": {
-        "sm": "6px",
-        "md": "10px",
-        "lg": "14px",
-        "xl": "18px"
+        "sm": { "px": 6, "doc": "Tight radius — chips, inline controls." },
+        "md": { "px": 10, "doc": "Default radius for cards + buttons (the bare `--radius`)." },
+        "lg": { "px": 14, "doc": "Large radius — panels, sheets." },
+        "xl": { "px": 18, "doc": "Extra-large radius — modals, hero surfaces." }
     },
     "space": {
-        "1": "4px",
-        "2": "8px",
-        "3": "12px",
-        "4": "16px",
-        "5": "20px",
-        "6": "24px",
-        "8": "32px"
+        "1": { "px": 4, "doc": "Spacing step 1 — 4px." },
+        "2": { "px": 8, "doc": "Spacing step 2 — 8px." },
+        "3": { "px": 12, "doc": "Spacing step 3 — 12px." },
+        "4": { "px": 16, "doc": "Spacing step 4 — 16px." },
+        "5": { "px": 20, "doc": "Spacing step 5 — 20px." },
+        "6": { "px": 24, "doc": "Spacing step 6 — 24px." },
+        "8": { "px": 32, "doc": "Spacing step 8 — 32px." }
     },
     "font": {
-        "sans": "-apple-system, BlinkMacSystemFont, \"Inter\", \"Segoe UI\", system-ui, sans-serif",
-        "mono": "\"SF Mono\", \"JetBrains Mono\", \"Menlo\", \"Consolas\", ui-monospace, monospace"
+        "sans": {
+            "value": "-apple-system, BlinkMacSystemFont, \"Inter\", \"Segoe UI\", system-ui, sans-serif",
+            "doc": "UI font stack."
+        },
+        "mono": {
+            "value": "\"SF Mono\", \"JetBrains Mono\", \"Menlo\", \"Consolas\", ui-monospace, monospace",
+            "doc": "Monospace font stack — code, logs, IDs."
+        }
     }
 }
diff --git a/shared/tokens_codegen.rs b/shared/tokens_codegen.rs
new file mode 100644
index 0000000..7f34cbf
--- /dev/null
+++ b/shared/tokens_codegen.rs
@@ -0,0 +1,234 @@
+// Generator for the Rust `tokens` module, from `shared/tokens.json`.
+//
+// This file lives in `shared/` — not in either crate's `src/` — because both
+// SmooAI/ui and SmooAI/client-shared carry the same design system, and the
+// `shared/**` drift gate keeps them byte-identical. Generating the constants
+// rather than hand-mirroring them is the whole point: a token can no longer
+// exist in `tokens.json` and be missing from Rust, because nobody types the
+// constants at all.
+//
+// `include!`d by each crate's `rust/build.rs`. Host-side only (build script),
+// so `std` and `serde_json` are available here even though the crate itself
+// is `no_std` with no runtime dependencies.
+
+use serde_json::Value;
+use std::fmt::Write as _;
+
+/// A token as it lands in generated Rust: the constant name, the CSS custom
+/// property it must agree with, and the rendered Rust literal.
+struct Token {
+    rust: String,
+    css_var: String,
+    /// The Rust expression — a quoted string, an integer, or an alias to
+    /// another constant.
+    expr: String,
+    /// The Rust type. `&str` for strings, `u16` for pixel values.
+    ty: &'static str,
+    /// The value as it should appear in the CSS, once `var(--x)` references
+    /// are resolved. `None` for aliases, which the CSS states as `var(--x)`
+    /// and whose resolved value is the target's — checked via the target.
+    css_value: String,
+    doc: String,
+}
+
+fn screaming(key: &str) -> String {
+    key.to_uppercase().replace('-', "_")
+}
+
+fn kebab(key: &str) -> String {
+    key.replace('_', "-")
+}
+
+fn obj<'a>(root: &'a Value, path: &str) -> &'a serde_json::Map<String, Value> {
+    let mut node = root;
+    for part in path.split('.') {
+        node = node
+            .get(part)
+            .unwrap_or_else(|| panic!("tokens.json: missing section {path:?}"));
+    }
+    node.as_object()
+        .unwrap_or_else(|| panic!("tokens.json: section {path:?} is not an object"))
+}
+
+fn require_str<'a>(entry: &'a Value, field: &str, path: &str) -> &'a str {
+    entry
+        .get(field)
+        .and_then(Value::as_str)
+        .unwrap_or_else(|| panic!("tokens.json: {path} is missing a string {field:?}"))
+}
+
+/// Resolve a dotted `ref` path (e.g. `color.brand.white`) to the constant name
+/// it maps to under the naming conventions.
+fn ref_to_const(path: &str) -> String {
+    let (section, key) = path
+        .rsplit_once('.')
+        .unwrap_or_else(|| panic!("tokens.json: malformed ref {path:?}"));
+    match section {
+        "color.brand" => format!("SMOOAI_{}", screaming(key)),
+        "color.semantic" => screaming(key),
+        other => panic!("tokens.json: ref into unsupported section {other:?}"),
+    }
+}
+
+fn collect(root: &Value) -> Vec<Token> {
+    let mut tokens = Vec::new();
+
+    // Colours. Brand tokens are literal OKLCH; semantic tokens are either
+    // literal or a `ref` to another token (rendered as a Rust alias and
+    // expected to be `var(--other)` in the CSS).
+    for (section, prefix) in [("color.brand", "SMOOAI_"), ("color.semantic", "")] {
+        for (key, entry) in obj(root, section) {
+            let path = format!("{section}.{key}");
+            let doc = require_str(entry, "doc", &path).to_string();
+            let rust = format!("{prefix}{}", screaming(key));
+            let css_var = if section == "color.brand" {
+                format!("--color-smooai-{}", kebab(key))
+            } else {
+                format!("--{}", kebab(key))
+            };
+            let (expr, css_value) = match entry.get("ref").and_then(Value::as_str) {
+                Some(target) => {
+                    let alias = ref_to_const(target);
+                    // A ref's CSS value is its target's, so record the target's
+                    // literal for the cross-check by resolving it here.
+                    let (t_section, t_key) = target.rsplit_once('.').unwrap();
+                    let literal = obj(root, t_section)
+                        .get(t_key)
+                        .and_then(|t| t.get("oklch"))
+                        .and_then(Value::as_str)
+                        .map(str::to_string)
+                        .unwrap_or_else(|| {
+                            // A ref to a ref — resolve one more hop.
+                            let next = obj(root, t_section)
+                                .get(t_key)
+                                .and_then(|t| t.get("ref"))
+                                .and_then(Value::as_str)
+                                .unwrap_or_else(|| {
+                                    panic!("tokens.json: {target:?} is neither oklch nor ref")
+                                });
+                            let (n_section, n_key) = next.rsplit_once('.').unwrap();
+                            require_str(&obj(root, n_section)[n_key], "oklch", next).to_string()
+                        });
+                    (alias, literal)
+                }
+                None => {
+                    let literal = require_str(entry, "oklch", &path).to_string();
+                    (format!("{literal:?}"), literal)
+                }
+            };
+            tokens.push(Token {
+                rust,
+                css_var,
+                expr,
+                ty: "&str",
+                css_value,
+                doc,
+            });
+        }
+    }
+
+    for (key, entry) in obj(root, "gradient") {
+        let path = format!("gradient.{key}");
+        let value = require_str(entry, "value", &path).to_string();
+        tokens.push(Token {
+            rust: format!("GRADIENT_{}", screaming(key)),
+            css_var: format!("--gradient-{}", kebab(key)),
+            expr: format!("{value:?}"),
+            ty: "&str",
+            css_value: value,
+            doc: require_str(entry, "doc", &path).to_string(),
+        });
+    }
+
+    for (key, entry) in obj(root, "radius") {
+        let path = format!("radius.{key}");
+        let px = entry
+            .get("px")
+            .and_then(Value::as_u64)
+            .unwrap_or_else(|| panic!("tokens.json: {path} is missing an integer \"px\""));
+        tokens.push(Token {
+            rust: format!("RADIUS_{}_PX", screaming(key)),
+            // The default radius is the bare `--radius`, not `--radius-md`.
+            css_var: if key == "md" {
+                "--radius".to_string()
+            } else {
+                format!("--radius-{}", kebab(key))
+            },
+            expr: px.to_string(),
+            ty: "u16",
+            css_value: format!("{px}px"),
+            doc: require_str(entry, "doc", &path).to_string(),
+        });
+    }
+
+    for (key, entry) in obj(root, "space") {
+        let path = format!("space.{key}");
+        let px = entry
+            .get("px")
+            .and_then(Value::as_u64)
+            .unwrap_or_else(|| panic!("tokens.json: {path} is missing an integer \"px\""));
+        tokens.push(Token {
+            rust: format!("SPACE_{}_PX", screaming(key)),
+            css_var: format!("--space-{}", kebab(key)),
+            expr: px.to_string(),
+            ty: "u16",
+            css_value: format!("{px}px"),
+            doc: require_str(entry, "doc", &path).to_string(),
+        });
+    }
+
+    for (key, entry) in obj(root, "font") {
+        let path = format!("font.{key}");
+        let value = require_str(entry, "value", &path).to_string();
+        tokens.push(Token {
+            rust: format!("FONT_{}", screaming(key)),
+            css_var: format!("--font-{}", kebab(key)),
+            expr: format!("{value:?}"),
+            ty: "&str",
+            css_value: value,
+            doc: require_str(entry, "doc", &path).to_string(),
+        });
+    }
+
+    tokens
+}
+
+/// Render `shared/tokens.json` as the body of the crate's `tokens` module.
+///
+/// Emits one `pub const` per token plus `ALL`, the complete
+/// `(rust_name, css_var, css_value)` table that `shared/tokens_css_check.rs`
+/// walks. `ALL` is generated alongside the constants, so it cannot fall behind
+/// them — that is what makes the "CSS has a token Rust omitted" case
+/// detectable, which the old hand-written list could not do.
+pub fn generate_tokens_rs(json: &str) -> String {
+    let root: Value = serde_json::from_str(json).expect("shared/tokens.json is not valid JSON");
+    let tokens = collect(&root);
+
+    let mut out = String::from(
+        "// @generated by shared/tokens_codegen.rs from shared/tokens.json — do not edit.\n\
+         // Add or change a token in shared/tokens.json; this file follows.\n\n",
+    );
+
+    for t in &tokens {
+        let _ = writeln!(out, "/// {}", t.doc);
+        let _ = writeln!(out, "pub const {}: {} = {};", t.rust, t.ty, t.expr);
+    }
+
+    let _ = writeln!(
+        out,
+        "\n/// Every generated token as `(rust_name, css_var, css_value)`, for the\n\
+         /// `shared/tokens_css_check.rs` cross-check against `shared/styles.css`.\n\
+         /// Generated with the constants above, so it is complete by construction.\n\
+         pub const ALL: &[(&str, &str, &str)] = &["
+    );
+    for t in &tokens {
+        let _ = writeln!(
+            out,
+            "    ({:?}, {:?}, {:?}),",
+            t.rust, t.css_var, t.css_value
+        );
+    }
+    let _ = writeln!(out, "];");
+
+    out
+}
diff --git a/shared/tokens_css_check.rs b/shared/tokens_css_check.rs
new file mode 100644
index 0000000..0c78cf3
--- /dev/null
+++ b/shared/tokens_css_check.rs
@@ -0,0 +1,140 @@
+// Cross-check the generated `tokens` constants against `shared/styles.css`.
+//
+// `include!`d from each crate's `#[cfg(test)] mod tests`. Lives in `shared/`
+// so SmooAI/ui and SmooAI/client-shared run the identical check — the
+// `shared/**` drift gate keeps the copies byte-identical.
+//
+// What this replaces: the old `tokens_match_css` asserted only that each
+// hand-written Rust constant appeared *somewhere* in the CSS as a substring.
+// That passes even when the constant is attached to the wrong custom property,
+// and it is structurally blind to a token the CSS declares and Rust omits —
+// nothing walks the CSS. This parses `:root`, resolves `var(--x)` references,
+// and checks BOTH directions.
+//
+// Scope of the completeness half: every **colour-valued** custom property (one
+// that resolves to `oklch(...)`) must be a generated token. Non-colour geometry
+// vars that `tokens.json` does not claim to cover (`--rail-width`,
+// `--status-bar-height`) are deliberately out of scope.
+
+// The `ui` slice compiles `no_std`, so `String`/`Vec`/`format!` are not in the
+// prelude here. The enclosing test module has already done `extern crate std`.
+use std::{
+    string::{String, ToString},
+    vec::Vec,
+};
+
+/// Strip `/* … */` comments so a trailing hex annotation can't be read as value text.
+fn strip_css_comments(css: &str) -> String {
+    let mut out = String::with_capacity(css.len());
+    let mut rest = css;
+    while let Some(start) = rest.find("/*") {
+        out.push_str(&rest[..start]);
+        match rest[start..].find("*/") {
+            Some(end) => rest = &rest[start + end + 2..],
+            None => return out,
+        }
+    }
+    out.push_str(rest);
+    out
+}
+
+/// Collapse every run of whitespace to a single space and trim, so a
+/// multi-line CSS value compares equal to its single-line JSON twin.
+fn normalize(value: &str) -> String {
+    value.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+/// Parse the `:root { … }` block into `(--custom-property, raw value)` pairs.
+fn parse_root_vars(css: &str) -> Vec<(String, String)> {
+    let css = strip_css_comments(css);
+    let start = css.find(":root").expect("shared/styles.css has no :root block");
+    let body_start = start + css[start..].find('{').expect(":root has no opening brace") + 1;
+    let body_len = css[body_start..]
+        .find('}')
+        .expect(":root has no closing brace");
+    let body = &css[body_start..body_start + body_len];
+
+    body.split(';')
+        .filter_map(|decl| {
+            let (name, value) = decl.split_once(':')?;
+            let name = name.trim();
+            name.starts_with("--")
+                .then(|| (name.to_string(), normalize(value)))
+        })
+        .collect()
+}
+
+/// Resolve `var(--x)` references against the parsed table, to a fixed point.
+/// Bounded by the number of variables, so a reference cycle errors rather than
+/// hanging.
+fn resolve(name: &str, vars: &[(String, String)], depth: usize) -> String {
+    assert!(
+        depth <= vars.len(),
+        "shared/styles.css: var() reference cycle reaching {name}"
+    );
+    let raw = vars
+        .iter()
+        .find(|(n, _)| n == name)
+        .map(|(_, v)| v.clone())
+        .unwrap_or_else(|| panic!("shared/styles.css: :root does not define {name}"));
+
+    let mut out = String::with_capacity(raw.len());
+    let mut rest = raw.as_str();
+    while let Some(at) = rest.find("var(") {
+        out.push_str(&rest[..at]);
+        let after = &rest[at + 4..];
+        let close = after
+            .find(')')
+            .unwrap_or_else(|| panic!("shared/styles.css: unclosed var() in {name}"));
+        out.push_str(&resolve(after[..close].trim(), vars, depth + 1));
+        rest = &after[close + 1..];
+    }
+    out.push_str(rest);
+    normalize(&out)
+}
+
+/// Every generated token's value must equal the resolved value of the CSS
+/// custom property it claims to mirror — not merely appear somewhere in the file.
+#[test]
+fn tokens_match_css() {
+    let vars = parse_root_vars(STYLES);
+    for (rust_name, css_var, expected) in tokens::ALL {
+        let actual = resolve(css_var, &vars, 0);
+        assert_eq!(
+            &actual,
+            &normalize(expected),
+            "token {rust_name} ({css_var}) disagrees with shared/styles.css — \
+             tokens.json says {expected:?}, the CSS resolves to {actual:?}",
+        );
+    }
+}
+
+/// The direction the old substring check could not see: a colour the CSS
+/// declares that `tokens.json` never mentions, so no binding in any language
+/// ever gets it.
+#[test]
+fn css_colors_are_all_tokens() {
+    let vars = parse_root_vars(STYLES);
+    for (name, _) in &vars {
+        if !resolve(name, &vars, 0).starts_with("oklch(") {
+            continue;
+        }
+        assert!(
+            tokens::ALL.iter().any(|(_, css_var, _)| *css_var == name.as_str()),
+            "shared/styles.css declares the colour {name} but shared/tokens.json \
+             has no token for it — add it to tokens.json so every language binding \
+             gets it (the Rust constants are generated from that file)",
+        );
+    }
+}
+
+/// `ALL` is generated alongside the constants; if that ever stops being true
+/// the two checks above go quietly vacuous, so assert it is populated.
+#[test]
+fn token_table_is_populated() {
+    assert!(
+        tokens::ALL.len() >= 20,
+        "tokens::ALL has only {} entries — codegen produced an near-empty table",
+        tokens::ALL.len()
+    );
+}