Field notes: promote learnings from the keysat /design pilot

First real /design run (keysat import, document-as-is). Generalizable
process learnings, per the Phase-D loop:
- implemented CSS/tokens are authoritative over prose when they disagree
- real type scales/shadows resist strict DTCG — keep as documented strings
- encode stated intent even where code violates it; the gap is the backlog
- "each surface inlines its own tokens" is a recurring drift risk; grep
  before relocating a design dir into _imports

guides/design.md

@@ -257,6 +257,22 @@ us things. Brand facts never go here; only generalizable process/distillation kn
 - *(seed, from research 2026-06-16)* On input, **point Claude Design at a front-end
   subdirectory, not the whole monorepo** — large trees choke the codebase scan. It accepts text
   prompts, image/doc uploads, live-URL web capture, and Figma files.
+- *(import run, 2026-06-16, keysat)* When a prior Claude Design artifact has a **README that
+  disagrees with its own shipped CSS/tokens** (keysat's README named "Archivo" but every surface
+  ships Manrope), the **implemented stylesheet is authoritative** for as-built values — encode
+  that, and record the prose/code disagreement as a reconciliation note, not a guess.
+- *(import run, 2026-06-16)* **Real type scales and shadows resist strict DTCG.** As-built
+  values use `clamp()` for the display scale, multi-layer composite shadows, and `em`
+  letter-spacing — none map cleanly to a DTCG primitive. Keep them as documented strings and say
+  so in the file's `$description`; don't force-fit or claim strict-spec compliance.
+- *(import run, 2026-06-16)* In **document-as-is**, encode the design system's stated *intent* in
+  the contract even where the current code violates it (keysat's README forbids gold-as-fill, but
+  the admin SPA ships two). `design-checker` then flags the code as the cleanup backlog — do
+  **not** water the contract down to match non-compliant code.
+- *(import run, 2026-06-16)* "**Each surface inlines its own copy of the tokens**" is a recurring
+  drift risk — name a canonical `brand/palette.css`, point `DESIGN.md` §Agent-guide at it, and log
+  the consolidation as backlog. Before relocating an existing design dir into `_imports/`, grep
+  that **nothing imports it** (in keysat, nothing did — safe to move).
 
 ## Final report