Theme Builder: accordion panels across the full config surface, vertical-tab nav, reflective gallery

docs/architecture/10-interaction-and-feedback.md

@@ -660,6 +660,31 @@ without clipping, wrapping, or crowding.
 
 ---
 
+## 9. Organizing a large control surface (two levels)
+
+A control surface too big for one scroll (the Theme Builder spans most of the
+Vega-Lite config) is organized in two levels, each with a settled widget so the
+choice isn't re-litigated per surface:
+
+- **Level 1 — switch by domain with tabs.** Mutually-exclusive top-level
+  categories (Color, Marks, Type, …) are an APG **tab set**, one panel visible at
+  a time. Past a handful of tabs a horizontal strip wraps raggedly and the active
+  tab shifts rows; a **vertical tab list** (`aria-orientation="vertical"`, Up/Down
+  - Home/End) scales without wrapping and keeps the active panel anchored. Never
+    **nest** tab sets — two roving tablists collide.
+- **Level 2 — group within a panel by how it's read.** Sub-groups a user reads in
+  full get **flat headings** (`role="group"` labelled by the heading). Sub-groups
+  where a user tunes one or two and skips the rest get a **single-expand
+  accordion** (APG accordion — heading-button toggles a `role="region"`; Up/Down
+  between headers) — Carbon's rule: accordion is for content "not crucial to read
+  in full." A per-section **modified badge** (count of set properties) keeps an
+  override scannable while collapsed (NN/g #6, recognition).
+
+_(Consulted via /council → WAI-ARIA APG tabs/accordion/disclosure, IBM Carbon
+accordion usage, NN/g #6/#8.)_
+
+---
+
 ## Do / Don't
 
 **Do**