design guide: add Case-B extract field notes from first live run

First extract->reconcile run (recap) surfaced generalizable process
learnings: harvest the inventory with grep frequency tables in the main
thread (counts are the reconcile evidence), disambiguate near-duplicates
with frequency plus an external anchor, present conflicts as
recommended-first A/B/C forks with value previews, and treat the code
itself as the inspiration for a document-as-is extract (skip BRIEF and
_imports, write provenance). Also refine the Extract phase to enumerate
every styling surface and read the brand mark before the CSS.
This commit is contained in:
Keysat
2026-06-16 23:14:22 -05:00
parent 8b0799736c
commit 9031281cd4
+27 -1
View File
@@ -113,7 +113,11 @@ canvas. Work it out *with* the user, inspiration-first:
component treatments, depth/elevation — **including the inconsistencies** (the three component treatments, depth/elevation — **including the inconsistencies** (the three
almost-the-same blues, the four heading sizes). A read-only `design-checker` cannot do this almost-the-same blues, the four heading sizes). A read-only `design-checker` cannot do this
(it needs a contract to check against), so inventory here in the main thread, optionally (it needs a contract to check against), so inventory here in the main thread, optionally
delegating a read-only reader to gather the raw values. delegating a read-only reader to gather the raw values. First **enumerate every styling
surface** — there is often more than one (a second stylesheet, a separate auth/landing
page, *CSS embedded in a string literal* that ships a self-contained export); a grep over
one `<style>` block silently misses the others. And **read the brand mark / icon before the
CSS** — it frequently encodes the intended color story the code only partly realized.
2. **Reconcile with the user.** Surface the conflicts and let them make the **canonical calls** 2. **Reconcile with the user.** Surface the conflicts and let them make the **canonical calls**
— which blue is *the* blue, which scale is *the* scale. Organically-arrived-at does not mean — which blue is *the* blue, which scale is *the* scale. Organically-arrived-at does not mean
correct; their taste decides. This is the high-value human step; don't auto-resolve it. correct; their taste decides. This is the high-value human step; don't auto-resolve it.
@@ -276,6 +280,28 @@ us things. Brand facts never go here; only generalizable process/distillation kn
drift risk — name a canonical `brand/palette.css`, point `DESIGN.md` §Agent-guide at it, and log 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 the consolidation as backlog. Before relocating an existing design dir into `_imports/`, grep
that **nothing imports it** (in keysat, nothing did — safe to move). that **nothing imports it** (in keysat, nothing did — safe to move).
- *(first Case-B extract run, 2026-06-16, recap)* **Harvest the inventory with grep frequency
tables in the main thread, not a delegated reader.** For a ~13k-line single file with ~450
inline styles, `grep -oE '<pattern>' | sort | uniq -c | sort -rn` per dimension (hex, rgba,
font-size, weight, radius, shadow, breakpoint) produced a complete *ranked* census that stayed
in context for the reconcile conversation — a sub-agent would have returned excerpts. The
**use-counts themselves are the reconcile evidence**: "which dark is THE background" is answered
by "132 uses + it's the PWA `manifest.json theme_color`," turning a taste call into a confirmation.
- *(first Case-B extract run, 2026-06-16)* **Disambiguate near-duplicates with frequency + an
external anchor**, not the eye. Ranking each value by use-count and cross-referencing a fixed
reference (the PWA `theme_color`, the icon's gradient endpoints) reliably separated "one
canonical + N strays" from "N intentional values," which is exactly the call to hand the user.
- *(first Case-B extract run, 2026-06-16)* **Present the reconcile conflicts as A/B/C forks,
recommended-option-first, with the candidate values in each option's preview.** Surfacing four
conflicts (the background, the accent, the surface ladder, the type scale) as one batch of
multiple-choice questions — each preview a monospace block showing the rival hexes in context —
let the owner make every canonical call in a single turn instead of a long volley. This is the
high-value human step; make it cheap to answer.
- *(first Case-B extract run, 2026-06-16)* **For a document-as-is extract, the "inspiration" is the
code itself.** There is no external reference set and no export bundle, so `BRIEF.md` and
`_imports/` are correctly skipped; instead write `inspiration/README.md` pointing at the
harvested source files + the brand icon as the de-facto reference, and copy the icon into
`brand/`. That preserves the *why/where* record the folder convention exists for.
## Final report ## Final report