@explorer02/cfm-survey-sdk 0.2.5 → 0.2.7

package/templates/docs/00-integration/wizard-post-customize-build.md

@@ -0,0 +1,405 @@
+# Wizard Post-Customize Build — All Types, All Formats
+
+> **Phase 6c runbook.** Read after the client clicks **Review & Build** and the CLI prints `✅ UI configuration saved`.  
+> Companion docs: [`wizard-config-handoff.md`](wizard-config-handoff.md) · [`wizard-customization-catalog.md`](wizard-customization-catalog.md) · [`apply-ui-config.md`](apply-ui-config.md) · [`wizard-question-type-styling.md`](wizard-question-type-styling.md) · [`wizard-chrome-contract.md`](wizard-chrome-contract.md)
+
+This doc answers two agent questions:
+
+1. **What does the wizard expose** for every question type and format — and which component must honor it?
+2. **What is the exact build sequence** after the client confirms customization — without re-running the wizard or skipping tokens?
+
+---
+
+## End-to-end flow (confirmation → deploy)
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Wizard as Wizard SPA
+  participant CLI as cfm-sdk customize
+  participant Agent
+  participant Build as npm run build
+  participant Deploy as Phase 7
+
+  Client->>Wizard: Review and Build
+  Wizard->>CLI: POST /api/save-config
+  CLI->>CLI: Write survey-ui-config.json
+  CLI->>CLI: Delete out/previews/ (GC)
+  CLI->>Agent: Exit 0 — UI configuration saved
+  Agent->>Agent: Phase 6c apply (this doc)
+  Agent->>Build: verify-agent-build.sh
+  Build->>Agent: out/ + logo in out/
+  Agent->>Deploy: After INPUT 4 confirm
+```
+
+**Agent must not** start Phase 6c until CLI exit 0. **Agent must not** proceed to Phase 7 until verify + build pass after apply.
+
+---
+
+## Phase 6c — ordered runbook (copy-paste checklist)
+
+Run from project root after `✅ UI configuration saved`.
+
+### A. Capture
+
+```bash
+# Local wizard (default)
+test -f survey-ui-config.json && echo "OK: config captured"
+
+# EC2 review mode only — also read diff before editing code
+test -f survey-ui-config.final.json && cat survey-ui-config.diff.md
+```
+
+### B. Validate
+
+- [ ] JSON parses; validate against `templates/survey-ui-config.schema.json`
+- [ ] `surveyTypes[]` still matches fetched survey inventory (types in survey, not wizard tabs)
+- [ ] EC2: every path in `survey-ui-config.diff.json` (`changed` + `added` + `removed`) has a planned apply target
+
+### C. Regenerate theme (full — never partial)
+
+- [ ] Regenerate **entire** `src/styles/survey-theme.css` from final config (all `global.*` + all `questionTypes.*`)
+- [ ] Confirm `@import` in `globals.css` (or equivalent)
+- [ ] Theme → Question card tokens present: `--cfm-matrix-selected`, `--cfm-input-focus-ring`
+
+### D. Chrome + content hooks
+
+Copy/sync if missing — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
+| Area | Config paths | Wire in |
+|------|--------------|---------|
+| Logo | `global.logo.fileName` | `Header.tsx` via `uiConfig.getLogoSrc()` → `src="./{fileName}"` |
+| Company | `global.companyName`, `global.header.showCompanyName` | `data-cfm-company` in brand row after logo |
+| Title / thank you | `global.surveyTitle`, `global.thankYouMessage` | `data-cfm-survey-title`, `data-cfm-thank-you` |
+| Buttons | `global.buttons.*` | `data-cfm-btn-next`, `data-cfm-btn-back` |
+| Footer | `global.footer.*` | `cfm-footer`, `data-cfm-copyright`, `data-cfm-footer-links` |
+| Layout | `global.layout.*` | `SurveyPage` / `SurveyStickyChrome` conditionals |
+| Progress | `global.theme.progress*` | `data-cfm-progress` + `.cfm-progress` (separate from header) |
+
+**Logo rule:** never hand-edit `fileName` to a seed SVG. Use wizard value; file must exist in `public/{fileName}`.
+
+```bash
+LOGO=$(python3 -c "import json; print(json.load(open('survey-ui-config.json')).get('global',{}).get('logo',{}).get('fileName') or '')")
+test -z "$LOGO" || test -f "public/$LOGO" || echo "FAIL: logo file missing in public/"
+```
+
+### E. Per-type tokens (all wizard types — not only survey inventory)
+
+The wizard **Question Types** step exposes **10 type families** (TEXT_AND_MEDIA uses theme vars only). Apply `questionTypes.{TYPE}` for **every** type block in saved JSON — even if the client's survey does not include that type. This keeps `survey-theme.css` complete and future-proof.
+
+Use the format matrix below. Detailed token tables: [`wizard-customization-catalog.md`](wizard-customization-catalog.md) and [`wizard-question-type-styling.md`](wizard-question-type-styling.md) and [`apply-ui-config.md`](apply-ui-config.md).
+
+### F. Hook options
+
+- [ ] `placeholders.*` → `useSurveySDK({ options: { placeholders } })` (stable ref)
+- [ ] `customFields` → `customFieldValues.ts` + SurveyPage + Question prop
+- [ ] `debug.enabled` → hook `debug: true`
+
+### G. EC2 promote (review mode only)
+
+```bash
+npx cfm-sdk confirm-ui-config   # downloads logo → public/
+```
+
+### H. Verify + build (blocking)
+
+```bash
+bash templates/verify-agent-build.sh
+```
+
+Script runs `npm run build`. Additionally confirm logo in static output:
+
+```bash
+test -z "$LOGO" || test -f "out/$LOGO" || echo "FAIL: logo not in out/"
+```
+
+### I. Phase 7 gate
+
+Only after H passes → ask deploy (INPUT 4). See [`aws-deploy.md`](aws-deploy.md) § Logos.
+
+**Do not re-run** `npx cfm-sdk customize` unless the client explicitly requests another session.
+
+**Do not re-run** `npx cfm-sdk export-previews` after wizard save — previews were deleted on purpose (GC). Export-previews is for **component structure changes** during Phase 5, not for applying saved config.
+
+---
+
+## Wizard steps → live preview keys
+
+| Wizard step | Default preview | What updates live |
+|-------------|-----------------|-------------------|
+| **Branding & Header** | `header` | Logo upload, company name, header dimensions/colors |
+| **Footer** | `footer` | Copyright, links, footer logo, colors |
+| **Theme & Colors** | `survey_page` | Palette, header/footer/progress/language colors, **Question card** (cell selected + focus ring) |
+| **Layout & Chrome** | `survey_page` | showHeader/Footer/Progress, nav buttons, question numbers, asterisk, width, font |
+| **Question Types** | per format tab | Per-type panels (see matrix below) |
+| **Testing & Tokens** | `survey_page` | Placeholders, custom fields, debug |
+| **Deploy & Build** | `survey_page` | Deploy target metadata (informational) |
+
+Chrome previews also exist: `intro`, `end`, `chrome` — used by harness; agent wires same hooks on Intro/End/SurveyPage.
+
+---
+
+## Question type format matrix (wizard → config → component)
+
+### How to read this table
+
+| Column | Meaning |
+|--------|---------|
+| **Preview key** | Iframe loaded in wizard right panel |
+| **Survey `question.type`** | Flat literal in `Question.tsx` dispatch |
+| **Wizard controls** | Fields in Question Types step for that tab |
+| **Config block** | `survey-ui-config.json` path (shared across formats of same type) |
+| **Scale / branch** | Component that must use `var(--cfm-*)` + `selectionStyles` / `labelStyles` |
+| **DOM attrs** | `data-cfm-*` set on `:root` or elements |
+
+**Shared across almost all scale types:** Theme → Question card → `cellSelectedColor` → `--cfm-matrix-selected`; `focusRingColor` → `--cfm-input-focus-ring`. Use [`selectionStyles.ts`](../templates/selectionStyles.ts).
+
+**Matrix multi-row:** Toggle **Preview multiple statements** on CFM, CSAT, Rating, Slider types. `LikertMatrixScale` / `CsatMatrixScale` must map **all** `statementRows` — not a single hardcoded row.
+
+---
+
+### MCQ — `questionTypes.MCQ`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `MCQ_single` | Single select | Option style, gap, radius, padding | `Question.tsx` MCQ branch + radio ring/dot |
+| `MCQ_multiple` | Multi select | Same | Checkbox: ring border + fill from theme |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `optionStyle` | `data-cfm-mcq-style` on `:root` |
+| `optionGap` | `--cfm-mcq-option-gap` |
+| `borderRadius` | `--cfm-mcq-border-radius` |
+| `optionPadding` | `--cfm-mcq-card-padding` |
+| Selection | `--cfm-input-focus-ring`, `--cfm-matrix-selected`, `--cfm-mcq-selected-bg` |
+
+---
+
+### TEXTFIELD — `questionTypes.TEXTFIELD`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `TEXTFIELD_short` | Short | Placeholder text, radius, border, placeholder color | `Question.tsx` + `data-cfm-textfield` |
+| `TEXTFIELD_long` | Long | Same | `textarea` with same hooks |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `inputRadius` | `--cfm-input-radius` |
+| `borderColor` | `--cfm-input-border` |
+| `placeholderColor` | `--cfm-input-placeholder` + `::placeholder` rule in theme CSS |
+| `defaultPlaceholder` | Default placeholder string (cosmetic) |
+| Focus | `--cfm-input-focus-ring` |
+
+---
+
+### NPS_SCALE — `questionTypes.NPS_SCALE`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `NPS_SCALE` | Radio / numbered / pill | Button style, track colors, hint labels, number labels | `RatingScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `buttonStyle` | `data-cfm-nps-button-style` |
+| `selectedFill`, `trackBarColor`, `trackHighlightColor` | `--cfm-nps-*` |
+| `hintMinText`, `hintMaxText`, hint colors | `hintLabelStyle()` |
+| `numberLabelMode`, per-index colors | `--cfm-number-*`, `resolveNumberLabelColor()` for **unselected** badges |
+| Selection | `scaleRadioRingStyle`, `scaleRadioDotStyle` |
+
+---
+
+### CFM_MATRIX — `questionTypes.CFM_MATRIX`
+
+Wizard tabs: **Likert**, **Bipolar**. Harness also ships `CFM_transpose`, `CFM_carousel`, `CFM_dropdown` — same config block.
+
+| Preview key | Matrix variant | Wizard controls | Scale / branch |
+|-------------|----------------|-----------------|----------------|
+| `CFM_likert` | Likert grid | Row width, bipolar %, label items | `LikertMatrixScale.tsx` |
+| `CFM_bipolar` | Bipolar anchors | Same + bipolar column width | Same |
+| `CFM_transpose` | Transposed | *(no extra wizard fields)* | `LikertMatrixScale` / matrix utils |
+| `CFM_carousel` | Carousel | Label items + theme selection | Matrix carousel branch |
+| `CFM_dropdown` | Dropdown | Label items | `MatrixDropdown.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `bipolarColumnWidthPercent` | `--cfm-matrix-bipolar-width` |
+| `columnLabelColor`, `columnLabelBgColor` | `matrixColumnLabelStyle()` |
+| Selection | `matrixRadioRingStyle`, `matrixRadioDotStyle` |
+
+**No** per-format accent overrides in wizard — Question card tokens only.
+
+---
+
+### CSAT_MATRIX — `questionTypes.CSAT_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `CSAT_emoji` | Emoji | Emoji size, unselected opacity, label items | `CsatMatrixScale.tsx` emoji cells |
+| `CSAT_star` | Star | Unselected opacity, label items | Star row; selected = `cellSelectedVar` |
+| `CSAT_numbered` | Numbered | Opacity, label items, number labels | Number badges + selection pattern |
+| `CSAT_graphics` | Graphics slider | Label items | `CustomSliderTrack.tsx` thumb pattern |
+| `CSAT_carousel` | Carousel | Label items | Dot indicators = cell selected when active |
+| `CSAT_dropdown` | Dropdown | Label items | `MatrixDropdown` + list radio |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `emojiSize` | `--cfm-csat-emoji-size` |
+| `unselectedOpacity` | `--cfm-csat-unselected-opacity` |
+| `columnLabelColor`, `columnLabelBgColor` | `csatColumnLabelStyle()` |
+| Number labels (numbered tab) | `--cfm-number-*` |
+| Selection | theme Question card vars |
+
+---
+
+### RATING_MATRIX — `questionTypes.RATING_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `RATING_star` | Star | Unselected star opacity, label items | `CsatMatrixScale.tsx` (shared path) |
+| `RATING_numbered` | Numbered | Opacity, label items, number labels | Numbered badges |
+| `RATING_radio` | Radio grid | Opacity, label items | Horizontal radio grid — `matrixRadioRingStyle` |
+| `RATING_emoji` | Emoji | Emoji size, opacity, label items | Emoji cells |
+| `RATING_graphics` | Graphics | Opacity, label items | `CustomSliderTrack` |
+| `RATING_slider` | Slider | Label items | Slider thumb pattern |
+
+Config block mirrors CSAT where formats overlap; uses `unselectedStarOpacity` instead of `unselectedOpacity` in JSON.
+
+---
+
+### SLIDER_MATRIX — `questionTypes.SLIDER_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `SLIDER_matrix` | Slider matrix | Track, thumb, tick colors, row width, tick label items, tick number labels | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `trackColor`, `thumbColor`, `tickColor` | `--cfm-slider-track`, `--cfm-slider-thumb`, `--cfm-slider-tick` |
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| Tick label items | `sliderTickLabelStyle()` |
+| Tick number labels | `--cfm-number-*` |
+| Row band | `--cfm-slider-row-band` / `--cfm-row-band` from theme |
+| Thumb selection | focus ring + cell selected on knob |
+
+---
+
+### FILE_UPLOAD — `questionTypes.FILE_UPLOAD`
+
+| Preview key | Wizard controls | Scale / branch |
+|-------------|-----------------|----------------|
+| `FILE_UPLOAD` | Dropzone border style, border color, fill, padding | `FileUploadScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `dropzoneStyle` | `data-cfm-dropzone-style` |
+| `borderColor` | `--cfm-upload-border-color` (not hardcoded gray) |
+| `dropzoneFillColor`, `dropzonePadding` | `--cfm-upload-fill`, `--cfm-upload-padding` |
+| Focus / drag | `--cfm-input-focus-ring`, `--cfm-mcq-selected-bg` |
+
+Presigned upload flow unchanged — styling only.
+
+---
+
+### HEATMAP — `questionTypes.HEATMAP`
+
+| Preview key | Wizard controls | Scale / branch |
+|-------------|-----------------|----------------|
+| `HEATMAP` | Pin color, border, size | `HeatmapScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `pinColor` | `--cfm-heatmap-pin` |
+| `pinBorderColor` | `--cfm-heatmap-pin-border` |
+| `pinSize` | `--cfm-heatmap-pin-size` |
+
+---
+
+### RANK_ORDER — `questionTypes.RANK_ORDER`
+
+| Preview key | Variant | Wizard controls | Scale / branch |
+|-------------|---------|-----------------|----------------|
+| `RANK_drag` | Drag & drop | Item bg, handle, badge | `RankOrderScale.tsx` + `@dnd-kit` |
+| `RANK_dropdown` | Dropdown | Item bg, select border, badge | Dropdown rank UI in same scale |
+
+| Config path | CSS var |
+|-------------|---------|
+| `drag.itemBg` / `dropdown.itemBg` | `--cfm-rank-item-bg` |
+| `drag.dragHandleColor` | `--cfm-rank-handle` |
+| `*.rankBadgeColor` | `--cfm-rank-badge` |
+| `drag.itemGap`, `itemPadding` | `--cfm-rank-item-gap`, `--cfm-rank-item-padding` |
+| `dropdown.selectBorderColor` | `--cfm-rank-select-border` |
+
+Do not change `interactionMode` or answer payload shapes.
+
+---
+
+### TEXT_AND_MEDIA — theme only
+
+| Preview key | Wizard step | Tokens |
+|-------------|-------------|--------|
+| `TEXT_AND_MEDIA` | Theme (media) | `--cfm-media-max-width`, `--cfm-media-radius` |
+
+No dedicated Question Types panel — wire in `Question.tsx` TEXT_AND_MEDIA branch.
+
+---
+
+## Phase 5 prerequisite — why post-customize apply works smoothly
+
+If Phase 5 copied all wizard-ready artifacts **before** the wizard ran, Phase 6c is mostly **config sync** — not rewriting components:
+
+| Artifact | Required before wizard |
+|----------|------------------------|
+| `survey-theme.css` | Full `--cfm-*` scaffold |
+| `selectionStyles.ts`, `labelStyles.ts` | Selection + label helpers |
+| `Header.tsx`, `Footer.tsx`, chrome templates | All `data-cfm-*` hooks |
+| `uiConfig.ts` | No bare `UI_CONFIG` |
+| Scale components per inventory | `var(--cfm-*)` not hardcoded hex |
+| `previewBridge.ts` | `layoutFlags` handler (dev preview) |
+
+If a wizard control does not live-update during Phase 6b, fix the **missing hook** in Phase 5 templates first — then re-run wizard. See symptom table in [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
+---
+
+## Post-apply smoke checks (by type in survey)
+
+For each `question.type` in the **fetched survey** (not all 11), spot-check in `npm run dev` after apply:
+
+| Type | Check |
+|------|-------|
+| MCQ | Option gap/radius; selected ring uses theme focus + cell colors |
+| TEXTFIELD | Placeholder color on focus/blur |
+| NPS_SCALE | Number badge traffic colors when unselected; selected uses theme |
+| CFM_MATRIX | Column label item colors; multi-row if multiple statements |
+| CSAT / RATING | Format-specific opacity/size; carousel dots if used |
+| SLIDER_MATRIX | Thumb ring+dot; tick label item colors |
+| FILE_UPLOAD | Dropzone border color from config |
+| HEATMAP | Pin size/color |
+| RANK_ORDER | Drag handle + badge colors |
+| TEXT_AND_MEDIA | Media max-width |
+
+---
+
+## Common mistakes after confirmation
+
+| Mistake | Fix |
+|---------|-----|
+| Partial CSS update (only changed colors) | Full regen `survey-theme.css` from entire JSON |
+| Changed `logo.fileName` manually | Use wizard `fileName`; keep `public/` file in sync |
+| Re-ran `export-previews` after save | Unnecessary — previews GC'd; apply config to client app instead |
+| Skipped types not in survey inventory | Still apply `questionTypes.*` blocks from saved JSON to CSS |
+| Edited `Question.tsx` dispatch | Forbidden — cosmetic tokens only |
+| Deploy before `out/{logo}` exists | Run build + logo preflight in Phase 6c H |
+
+---
+
+## Related
+
+| Doc | When |
+|-----|------|
+| [`wizard-config-handoff.md`](wizard-config-handoff.md) | Wait protocol, GC, EC2 link |
+| [`apply-ui-config.md`](apply-ui-config.md) | Full config path → CSS tables |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Selection patterns, code snippets |
+| [`wizard-chrome-contract.md`](wizard-chrome-contract.md) | Copy commands, symptom → fix |
+| [`agent-execution-flow.md`](agent-execution-flow.md) | Full pipeline phases |
+| [`verify-agent-build.sh`](../templates/verify-agent-build.sh) | Automated gate before deploy |

package/templates/docs/00-integration/wizard-preview-build-guide.md

@@ -1,10 +1,15 @@
 # Wizard Live Preview — Client Build Guide
 
 > **Read during Phase 5 (BUILD) — mandatory.** Wizard **run** (Phase 6b) is optional; this contract is required for every agent build.  
+> **Authoritative hook list + copy commands:** [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — fixes logo, layout toggles, question card, and per-type preview issues.  
+> **Complete control catalog (all steps, types, formats):** [`wizard-customization-catalog.md`](wizard-customization-catalog.md).  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 Related docs:
 
+- [`wizard-customization-catalog.md`](wizard-customization-catalog.md) — **every wizard control** → config → CSS var → component
+- [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — **copy-first templates** + symptom → fix table
+
 - [`ui-customization-wizard.md`](ui-customization-wizard.md) — wizard flow and CLI
 - [`apply-ui-config.md`](apply-ui-config.md) — applying final `survey-ui-config.json` after wizard
 - [`wizard-api.md`](wizard-api.md) — EC2 `/wizard/*` API
@@ -51,14 +56,25 @@ If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` h
 
 ## Required project artifacts (Phase 5)
 
-Create these **before** the client opens the wizard:
+**Copy wizard-ready templates first** (do not hand-write chrome from `apps/client`):
+
+| Template (SDK) | Copy to |
+|----------------|---------|
+| `templates/docs/templates/Header.tsx` | `src/components/Header.tsx` |
+| `templates/docs/templates/Footer.tsx` | `src/components/Footer.tsx` |
+| `templates/docs/templates/ProgressBar.tsx` | `src/components/ProgressBar.tsx` |
+| `templates/docs/templates/SurveyStickyChrome.tsx` | `src/components/SurveyStickyChrome.tsx` |
+| `templates/docs/templates/LanguageSelector.tsx` | `src/components/LanguageSelector.tsx` |
+| `templates/docs/templates/PreviewBridgeInit.tsx` | `src/components/PreviewBridgeInit.tsx` |
+| `templates/previewBridge.ts` | `src/lib/previewBridge.ts` |
+| `templates/survey-theme.css` | `src/styles/survey-theme.css` |
+| `templates/docs/templates/Question.tsx` | `src/components/Question.tsx` (dispatcher base) |
+
+Full symptom → fix table: [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
 
 | File | Purpose |
 |------|---------|
-| `src/styles/survey-theme.css` | All `--cfm-*` CSS custom properties (defaults from mockup) |
 | `survey-ui-config.json` (draft) | Seeds wizard form fields from agent branding |
-| `src/lib/previewBridge.ts` | Live bridge in **local dev** (`npx cfm-sdk customize`) — copy from `templates/previewBridge.ts` |
-| `src/components/PreviewBridgeInit.tsx` | Mount bridge once in `layout.tsx` (local dev only) |
 
 Import theme in `globals.css`:
 

package/templates/docs/00-integration/wizard-question-type-styling.md

@@ -1,6 +1,7 @@
 # Wizard Question-Type Styling
 
-> **Read during Phase 5 (BUILD) — mandatory.** Alongside [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> **Read during Phase 5 (BUILD) — mandatory.** Alongside [`wizard-customization-catalog.md`](wizard-customization-catalog.md) (complete control index), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> **After client saves wizard:** [`wizard-post-customize-build.md`](wizard-post-customize-build.md) — full format matrix + Phase 6c runbook.  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 **Do not change** `Question.tsx` dispatch logic, answer shapes, SDK visibility helpers, or matrix routing algorithms — styling only.
@@ -75,10 +76,26 @@ Single-select radio: outer border = focus ring, annulus = cell selected, inner d
 
 ### TEXTFIELD (`TEXTFIELD_short`, `TEXTFIELD_long`)
 
-| Wizard section | CSS vars |
-|----------------|----------|
-| Input radius, border, placeholder | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-placeholder` |
-| Focus | `--cfm-input-focus-ring` on focus outline |
+| Wizard section | CSS vars | Apply in |
+|----------------|----------|----------|
+| Input radius, border, padding | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-padding` | `Question.tsx` textarea |
+| **Placeholder color** | `--cfm-input-placeholder` | `data-cfm-textfield` + CSS `::placeholder { color: var(--cfm-input-placeholder) }` |
+| Focus | `--cfm-input-focus-ring` | focus outline |
+
+```tsx
+<textarea
+  data-cfm-textfield
+  style={{ borderColor: 'var(--cfm-input-border)', ... }}
+  className="placeholder:cfm-input-ph"
+/>
+```
+
+```css
+[data-cfm-textfield]::placeholder {
+  color: var(--cfm-input-placeholder);
+  opacity: 1;
+}
+```
 
 ### NPS_SCALE (`NPS_SCALE`)
 
@@ -101,6 +118,8 @@ Single-select radio: outer border = focus ring, annulus = cell selected, inner d
 
 **No** per-type accent/ring overrides in CFM — use Question card tokens only.
 
+**Matrix multi-row preview:** Wizard **Question Types → CFM** has a **multi-statement** toggle. Preview harness injects a second `statementRow` when enabled. `LikertMatrixScale.tsx` **must** map over `question.statementRows` — never hardcode a single row.
+
 ### CSAT_MATRIX (`CSAT_carousel`, `CSAT_dropdown`, `CSAT_emoji`, `CSAT_graphics`, `CSAT_numbered`, `CSAT_star`)
 
 | Format | Wizard sections | Key styling |
@@ -174,7 +193,9 @@ For production builds after wizard: syncing `survey-theme.css` is sufficient —
 
 **Wizard customization** exposes all **11** question types regardless of fetched survey inventory. Wire styling for every scale template you copy — not only types in the client's mockup image.
 
-For each type in **wizard export** (all 11):
+**Format-level matrix** (every preview tab → component): [`wizard-customization-catalog.md`](wizard-customization-catalog.md) § Question Types step.
+
+For each type in **wizard export** (all types in `surveyTypes[]`):
 
 - [ ] Scale component uses `var(--cfm-*)` for every wizard-exposed token (no hardcoded brand hex)
 - [ ] Radio/scale selections use `selectionStyles.ts` pattern (focus ring + cell selected)

package/templates/docs/01-components/19-survey-sticky-chrome.md

@@ -1,30 +1,28 @@
 # Survey Sticky Chrome
 
-> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/SurveyStickyChrome.tsx`
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`  
+> **Wizard contract:** [`wizard-chrome-contract.md`](../00-integration/wizard-chrome-contract.md) — header and progress are **separate** toggle targets  
 > **Template:** [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx)
-> **Component**: `SurveyStickyChrome`
 
 ## Purpose
 
-Wrap **Header + ProgressBar** in a single `sticky top-0` container so the progress bar stays visible when the respondent scrolls to answer questions lower on the page (especially the last question on a multi-question page).
+Wrap **Header + ProgressBar** in a sticky container. The wizard toggles them **independently**:
 
-## Props
+| Toggle | Target |
+|--------|--------|
+| `showHeader` | `.cfm-header` on `<header>` only |
+| `showProgressBar` | `[data-cfm-progress]` / `.cfm-progress` only |
 
-```typescript
-type SurveyStickyChromeProps = {
-  progressPercentage: number; // from state.progressPercentage
-};
-```
+Do **not** put class `cfm-header` on the sticky wrapper.
 
-## Implementation
+## Implementation (wizard-ready)
 
 ```tsx
 export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyChromeProps) {
   return (
-    <div className="sticky top-0 z-30 bg-white shadow-[0_2px_8px_rgba(0,0,0,0.06)]">
+    <div className="cfm-sticky-chrome sticky top-0 z-30" style={{ background: 'var(--cfm-header-bg)' }}>
       <Header embedded />
-      <div className="mx-auto w-full max-w-4xl px-4 pb-5 pt-4 sm:px-6 lg:px-8">
+      <div className="mx-auto w-full px-4" style={{ maxWidth: 'var(--cfm-max-width)' }}>
         <ProgressBar progressPercentage={progressPercentage} />
       </div>
     </div>
@@ -32,48 +30,11 @@ export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyC
 }
 ```
 
-## Spacing (logo → progress bar)
-
-Keep a visible gap between the logo block and the progress track — do **not** flush them together.
-
-| Token | Tailwind | Purpose |
-|-------|----------|---------|
-| Top inset | `pt-4` | 16px gap below logo / header row |
-| Bottom inset | `pb-5` | 20px gap above scrollable question content |
-| Horizontal | `px-4 sm:px-6 lg:px-8` | Align track with `main` content column (`max-w-4xl`) |
-
-## Header `embedded` prop
-
-When `Header` is inside sticky chrome, pass `embedded` to avoid a double shadow:
-
-```tsx
-<header className={`relative h-[120px] w-full bg-white ${embedded ? '' : 'z-10 shadow-[0_2px_8px_rgba(0,0,0,0.06)]'}`}>
-```
-
-Use the standalone `Header` (no `embedded`) on intro, end, loading, and terminal pages.
-
-## SurveyPage wiring (content phase only)
-
-```tsx
-<div className="flex min-h-screen flex-col bg-white">
-  <SurveyStickyChrome progressPercentage={state.progressPercentage} />
-
-  <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10 sm:px-6 lg:px-8">
-    <LanguageSelector ... />
-    {/* questions + nav */}
-  </main>
-
-  <Footer />
-</div>
-```
-
-Do **not** render a separate `ProgressBar` inside `<main>` — it belongs in sticky chrome only.
+Copy full file from [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx).
 
 ## Agent checklist
 
-- [ ] `SurveyStickyChrome` (or equivalent sticky wrapper) on `phase.kind === 'content'`
-- [ ] `ProgressBar` bound to `state.progressPercentage`
-- [ ] `sticky top-0 z-30 bg-white` on wrapper; single shadow on wrapper, not Header
-- [ ] `pt-4` gap between logo and progress track; `pb-5` below track
-- [ ] Progress track aligned to same `max-w-4xl` as question content
-- [ ] Standalone `Header` on intro / end / loading / terminal branches
+- [ ] `Header.tsx` has class `cfm-header` + `data-cfm-logo` + `data-cfm-company`
+- [ ] `ProgressBar.tsx` has `data-cfm-progress` + class `cfm-progress`
+- [ ] Sticky wrapper uses `cfm-sticky-chrome` — not `cfm-header`
+- [ ] `pt`/`pb` spacing via `--cfm-sticky-pt` / `--cfm-sticky-pb`

package/templates/docs/03-ui-specs/README.md

@@ -4,7 +4,7 @@
 > **Shared lib utilities** (NPS colors, custom fields, heatmap coords) live in [`templates/`](../templates/) — see [`client-lib-folder.md`](../00-integration/client-lib-folder.md), not in this ui-specs folder.
 > Read the spec for **each question type present** in the fetched survey before writing React code.
 
-> **Wizard customization:** When the client may use the web wizard, hardcoded hex in § Design Tokens below are **defaults only**. Wire `var(--cfm-*)` per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md) — especially `--cfm-matrix-selected` (cell annulus) and `--cfm-input-focus-ring` (outer border + inner dot). Portable scale templates in `docs/templates/` are layout/logic baselines; extend with `selectionStyles.ts` + `labelStyles.ts` for live preview.
+> **Wizard customization:** When the client may use the web wizard, hardcoded hex in § Design Tokens below are **defaults only**. Wire `var(--cfm-*)` per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md) — especially `--cfm-matrix-selected` (cell annulus) and `--cfm-input-focus-ring` (outer border + inner dot). **Full control catalog (all formats):** [`wizard-customization-catalog.md`](../00-integration/wizard-customization-catalog.md).
 
 ## How to Read a UI Spec
 

package/templates/docs/MANIFEST.json

@@ -156,6 +156,10 @@
       "path": "00-integration/client-lib-folder.md",
       "purpose": "src/lib layout — customFieldValues + surveyUi portable templates"
     },
+    {
+      "path": "00-integration/wizard-chrome-contract.md",
+      "purpose": "Wizard DOM/CSS hook contract — copy-first Header/Footer/ProgressBar templates (Phase 5)"
+    },
     {
       "path": "00-integration/wizard-preview-build-guide.md",
       "purpose": "Build client components for wizard live preview — --cfm-* vars and data-cfm-* hooks (Phase 5)"
@@ -364,8 +368,10 @@
         "00-integration/agent-execution-flow.md",
         "00-integration/constraints.md",
         "00-integration/component-checklist.md",
+        "00-integration/wizard-customization-catalog.md",
         "00-integration/wizard-preview-build-guide.md",
         "00-integration/wizard-question-type-styling.md",
+        "00-integration/wizard-chrome-contract.md",
         "02-reference/routing-table.md"
       ],
       "onDemand": "02-reference/question-types"
@@ -422,6 +428,7 @@
       "read": [
         "00-integration/wizard-config-handoff.md",
         "00-integration/ui-customization-wizard.md",
+        "00-integration/wizard-customization-catalog.md",
         "00-integration/wizard-preview-build-guide.md",
         "00-integration/wizard-question-type-styling.md",
         "00-integration/wizard-api.md",
@@ -453,9 +460,11 @@
       "when": "wizardUsedOrSurveyUiConfigExists",
       "read": [
         "00-integration/wizard-config-handoff.md",
+        "00-integration/wizard-post-customize-build.md",
         "00-integration/apply-ui-config.md",
         "00-integration/wizard-preview-build-guide.md",
-        "00-integration/wizard-question-type-styling.md"
+        "00-integration/wizard-question-type-styling.md",
+        "00-integration/wizard-chrome-contract.md"
       ],
       "inputFile": "survey-ui-config.final.json",
       "inputFileLocal": "survey-ui-config.json",