design guide: field notes from first live cloud round-trip

Three process learnings from the 2026-06-19 Ten31 mobile round-trip:
- Output read via the DesignSync MCP is a multi-file app on Claude Design's
  own template runtime using CSS custom properties (incl. a dark/light
  switch) — qualifies the seed note about "inline hardcoded CSS" (that's the
  export-bundle path, not the MCP project-read path). Read the shell first,
  then each sub-app's --var block + DCLogic for derived-field formulas.
- DesignSync reads into context only (no bulk download / no screenshots):
  byte-capture the representative source + a manifest README; use
  `jq -r .content` on the harness-persisted result for large files.
- A redesign can return more scope than the brief asked for (a light theme);
  record it but write scope-expanding additions as proposed-not-canonical
  pending an explicit owner decision, surfaced as an A/B reconcile question.

guides/design.md

@@ -320,6 +320,32 @@ us things. Brand facts never go here; only generalizable process/distillation kn
   radius 9) renders identically at any radius ≥ half its height, so snapping *up* to the next scale
   step (9→10) is on-scale **and** pixel-identical. Snap capsules up, not down, to avoid a visible change.
 
+- *(first live cloud round-trip, 2026-06-19, keysat)* Output read **via the DesignSync MCP** (not
+  a downloaded "Handoff" bundle) is richer than the seed note above assumes: a **multi-file
+  interactive app** — a shell that `<dc-import>`s per-surface sub-apps over a shared `store.js`, on
+  Claude Design's **own template runtime** (`<x-dc>`/`<sc-if>`/`<sc-for>` + a `DCLogic` class), using
+  **CSS custom properties** (per-surface `--var` blocks incl. a `[data-theme]` dark/light switch) —
+  *not* the "inline hardcoded CSS" the export path produces. **Qualify, don't delete, the seed note**:
+  the distinction is export-bundle (inline CSS) vs. MCP project-read (custom props + runtime). Read
+  the **shell first** (it enumerates the surfaces), then each sub-app's `--var` block for values and
+  its `DCLogic.renderVals()`/helpers for **derived-field formulas + thresholds** (money formatting,
+  staleness day-cuts, stage order) — those encode product logic worth capturing verbatim, not just
+  visuals.
+- *(2026-06-19)* **DesignSync reads content into context only — no bulk download, no
+  screenshots/binaries.** So `_imports/` from a *project read* (vs. a downloaded bundle) is
+  necessarily partial: byte-capture the representative text source + write a manifest `README.md`
+  (project name/id/URL, full file inventory, distilled data-model/formulas/per-surface interaction
+  notes) and record that screenshots + remaining files stay in-cloud (recoverable via the URL). For
+  a byte-exact copy of a large `get_file`, the harness persists the oversized tool result to a file —
+  `jq -r '.content' <that-file> > dest` extracts it exactly without re-streaming through context.
+- *(2026-06-19)* **A redesign round-trip can hand back *more scope than the brief asked for*** (here:
+  a full light theme + a stage-color axis on a dark-only brief). This is a different reconcile than
+  as-built *inconsistency*: record the additions faithfully in `_imports/`, but write any
+  scope-expanding one (a whole second palette, a new color axis) into the contract as
+  **proposed-not-canonical pending an explicit owner decision** rather than silently adopting it —
+  and surface it as the reconcile call (an A/B "adopt vs. exploration-only" question). Small in-idiom
+  refinements (a 13→15px type bump) just get absorbed.
+
 ## Final report
 
 Short summary: the on-ramp taken (refine/import/extract/fresh) and posture (document/redesign),