From a6e3fe69086bb77b37ad546464ca259581dff993 Mon Sep 17 00:00:00 2001 From: Keysat Date: Tue, 16 Jun 2026 11:30:13 -0500 Subject: [PATCH] Field notes: promote learnings from the keysat /design pilot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/guides/design.md b/guides/design.md index f0c2130..43def93 100644 --- a/guides/design.md +++ b/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