@explorer02/cfm-survey-sdk 0.2.3 → 0.2.4

package/templates/docs/02-reference/routing-table.md

@@ -48,5 +48,6 @@ import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
 | `CustomSliderTrack` | `01-components/09-custom-slider-track.md` |
 | `Header` / `Footer` | `01-components/10-header-footer.md` |
 | `ProgressBar` | `01-components/11-progress-bar.md` |
+| `SurveyStickyChrome` | `01-components/19-survey-sticky-chrome.md` |
 | `LanguageSelector` | `01-components/12-language-selector.md` |
 | `MatrixDropdown` | `01-components/13-matrix-dropdown.md` |

package/templates/docs/02-reference/value-derivation.md

@@ -24,7 +24,7 @@ type ScaleColumn = { id: string; label: string };
 - Filter N/A from scale pickers: `scaleColumns.filter(col => col.id !== 'na')`
 - Slider matrix rows still store numeric slider positions (unchanged)
 
-Monorepo client mirror: `apps/client/src/lib/surveyUi/scaleValues.ts` exports the same helper for matrix UI components.
+Portable template: [`templates/surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts) exports `matrixColumnStoredValue` (same contract). Copy to `src/lib/` — see [`client-lib-folder.md`](../00-integration/client-lib-folder.md).
 
 ## NPS / star rating options
 

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -31,3 +31,13 @@ Never use a `default` fallback that shows `"not yet implemented"`.
 
 - Answers: `state.answers` (not `state.values`)
 - Change action: `{ type: 'CHANGE', payload: { questionId, answerValue } }`
+
+## Wizard customization (Phase 5 — required)
+
+Question shell inherits global theme tokens — no per-shell hex overrides:
+
+- Validation banner: `--cfm-validation-border`, `--cfm-validation-bg`
+- Question title: `--cfm-question-title-color`
+- Required asterisk: `--cfm-required-color`
+
+See [`wizard-preview-build-guide.md`](../00-integration/wizard-preview-build-guide.md) for `data-cfm-*` on wrapper-adjacent chrome only.

package/templates/docs/03-ui-specs/01-rating.md

@@ -44,3 +44,21 @@ See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 - [ ] Two-row grid with `gridTemplateColumns: repeat(options.length, 1fr)`
 - [ ] Only track row is clickable
 - [ ] min/mid/max labels in Question wrapper with midLabelIndex formula
+
+## Wizard customization (Phase 5 — required)
+
+> Reference hex in this spec are defaults. Wire `var(--cfm-*)` per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md). Copy [`selectionStyles.ts`](../templates/selectionStyles.ts) and [`labelStyles.ts`](../templates/labelStyles.ts).
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Track bar / highlight | `--cfm-nps-track-bar`, `--cfm-nps-track-highlight`, `--cfm-nps-selected-fill` | `RatingScale.tsx` track row |
+| Hint labels (min/max) | `--cfm-hint-label-color`, `--cfm-hint-label-bg` | `hintLabelStyle()` on anchor row |
+| Number labels | `--cfm-number-label-mode`, `--cfm-number-mono-color`, `--cfm-number-color-{n}` | Badge row — unselected only |
+| Selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `scaleRadioRingStyle` / `scaleRadioDotStyle` |
+
+### Wizard checklist
+
+- [ ] `selectionStyles.ts` imported in `RatingScale.tsx`
+- [ ] Selected radio: outer border + dot = focus ring; annulus = cell selected
+- [ ] Selected numbered badge: border = focus ring, fill = cell selected, text white
+- [ ] Unselected badges keep traffic-light / per-number `--cfm-number-*` colors

package/templates/docs/03-ui-specs/02-radio.md

@@ -92,9 +92,24 @@ onAction({ type: 'CHANGE', payload: { questionId, answerValue: string[] } })
 
 - [ ] Use `selectionMode`, not `isMultiSelect`
 - [ ] Full-width card options; custom circular radio / checkbox indicators
-- [ ] Selected: magenta border `#e20074` + pink bg `#fdf2f8`
+- [ ] Selected: use `var(--cfm-input-focus-ring)` border + `var(--cfm-mcq-selected-bg)` / `var(--cfm-matrix-selected)` — not hardcoded `#e20074` / `#fdf2f8`
 - [ ] Multi-select: `string[]` answer; block at `maxSelections`
 - [ ] Defaults: bind to `state.answers`; pre-selected visual on load when `defaultOptionIds` set
 - [ ] `getVisibleMcqOptionsForAnswers` with optional `customFieldValues` 4th arg
 - [ ] Store `option.id` — never label text
 - [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../00-integration/question-type-sdk-matrix.md#mcq)
+
+## Wizard customization (Phase 5 — required)
+
+> Wire MCQ tokens per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md). Copy [`selectionStyles.ts`](../templates/selectionStyles.ts).
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Option gap / radius / padding | `--cfm-mcq-option-gap`, `--cfm-mcq-border-radius`, `--cfm-mcq-card-padding` | MCQ option cards |
+| Selection (radio) | `--cfm-input-focus-ring`, `--cfm-matrix-selected`, `--cfm-mcq-selected-bg` | Outer ring border + annulus + inner dot |
+| Selection (checkbox) | `--cfm-input-focus-ring`, `--cfm-mcq-selected-bg` | Checkbox border + fill |
+
+### Wizard checklist
+
+- [ ] Single-select radio uses ring + annulus + dot pattern from `selectionStyles.ts`
+- [ ] `data-cfm-mcq-style` on `:root` when `questionTypes.MCQ.optionStyle` set

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

@@ -1,6 +1,6 @@
 # UI Spec: Text Field (`type: 'TEXTFIELD'`)
 
-> **Reference:** `apps/client/src/components/Question.tsx` (inline)
+> **Reference:** portable `docs/templates/Question.tsx` (inline TEXTFIELD branch)
 > **SDK type:** `TextInputQuestion` — `fetchSurvey/types/text.ts`
 
 ## Config Inventory
@@ -49,3 +49,14 @@ onSelect(string) // onChange from textarea
 - [ ] Character counter bottom-right
 - [ ] Magenta focus ring
 - [ ] Implement `inputVariant: 'short'` as single-line input when present
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Input radius / border / placeholder | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-placeholder` | `textarea` / `input` |
+| Focus outline | `--cfm-input-focus-ring` | `:focus-visible` ring |
+
+### Wizard checklist
+
+- [ ] No hardcoded magenta focus hex — use `var(--cfm-input-focus-ring)`

package/templates/docs/03-ui-specs/04-csat.md

@@ -1,6 +1,7 @@
 # UI Spec: CSAT Matrix Grid (`type: 'CSAT_MATRIX'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
+> **COPY TEMPLATE FIRST:** [`templates/CsatMatrixScale.tsx`](../templates/CsatMatrixScale.tsx) + [`surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts) + [`CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx)
+>
 > **SDK type:** `CsatQuestion` — `fetchSurvey/types/csat.ts`
 > **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
@@ -9,75 +10,89 @@
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
 | `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
-| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `displayStyle` | ✅ | emoji / star / numbered / graphics / standard |
 | `gridLayout` | ✅ | carousel vs standard vs dropdown |
-| `hasNotApplicableOption` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `hasNotApplicableOption` | ✅ | N/A column (56px) or vertical checkbox |
 | `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
-| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns (replaces column headers when set) |
 
-## Config Decision Tree
+## Statement & label visibility (CRITICAL)
 
-```
-CSAT_MATRIX
-├── gridLayout === 'carousel' → CsatMatrixCarousel
-├── displayStyle in (dropdown, selectbox) → CsatMatrixVerticalList
-│   ├── dropdown → MatrixDropdown placeholder "Select..."
-│   ├── selectbox → full-width cards #fdf2f8 selected
-│   └── else → card radio list
-└── else → CsatMatrixGrid
-    ├── displayStyle === 'emoji' → client-side emoji icons (react-icons) + hover scale + ring when selected
-    ├── displayStyle === 'star' → opacity 0.5 unselected; filled/empty icons
-    ├── displayStyle === 'numbered' → 40×40 badge; selected magenta fill
-    └── displayStyle === 'graphics' → CustomSliderTrack per row (carousel)
+Agents often render inputs with **no row labels** and **no column headers**. Every matrix grid MUST include:
+
+### 1. Row labels — `statementRows[].statementText`
+
+Fixed **180px** left column on every data row:
+
+```tsx
+<div style={{ width: '180px', flexShrink: 0, padding: '0 16px' }}>
+  <span
+    style={{ fontSize: '14px', fontWeight: 500, color: '#111827' }}
+    dangerouslySetInnerHTML={{ __html: row.statementText }}
+  />
+</div>
 ```
 
-## Grid Structure
+### 2. Column labels — two modes (mutually exclusive header row)
 
-- Row label: `180px` fixed column
-- N/A column: `56px` when `hasNotApplicableOption`
-- Alternating row backgrounds
-- Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
+| Condition | What to render above cells |
+|-----------|---------------------------|
+| `scaleAnchorLabels.length > 0` | Anchor label row positioned over columns (see formula below) |
+| No anchor labels | Column header row from `scaleColumns[].label` |
 
-## Carousel — Implementation Recipe
+**When `scaleAnchorLabels` is set**, still render anchor row even if column text labels are long (emoji mode Page 9 fixture):
 
-Same rules as CFM carousel (prev/next disabled at bounds, dot click jumps row, no auto-advance). CSAT uses **pink** active dot `#e20074` (not Likert blue).
+```typescript
+const m = scaleColumns.length;
+const n = scaleAnchorLabels.length;
+const percent = n === 1 ? 50 : (0.5 / m + (i / (n - 1)) * ((m - 1) / m)) * 100;
+// position label i at left: `${percent}%`, transform: translateX(-50%)
+```
 
-## N/A mutex
+**When no anchor labels**, render column headers:
 
-| Layout | Behavior |
-|--------|----------|
-| Grid N/A column | Selecting N/A clears row; selecting column clears N/A |
-| Vertical checkbox | `hasNotApplicableOption` checkbox below row sets `null` |
+```tsx
+{scaleColumns.map(col => (
+  <span dangerouslySetInnerHTML={{ __html: col.label }} />
+))}
+```
 
-## Emoji / star / numbered — react-icons mapping
+### 3. N/A column header
 
-Copy [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx) or implement `getEmojiForIndex(index, totalColumns)`.
+When `hasNotApplicableOption`, reserve **56px** right column with "N/A" header text.
 
-**5-point CSAT emoji index → icon key:**
+## Config Decision Tree
 
-| Column index (0-based) | Sentiment | Maps to 11-point scale key |
-|--------------------------|-----------|----------------------------|
-| 0 | Very negative | 3 |
-| 1 | Negative | 4 |
-| 2 | Neutral | 6 |
-| 3 | Positive | 7 |
-| 4 | Very positive | 9 |
+```
+CSAT_MATRIX
+├── gridLayout === 'carousel' → CsatMatrixCarousel
+├── displayStyle in (dropdown, selectbox) → CsatMatrixVerticalList
+└── else → CsatMatrixGrid
+    ├── displayStyle === 'emoji' → getEmojiForIndex(colIdx, m) — NOT radio circles
+    ├── displayStyle === 'star' → CsatStarIcons filled/empty
+    ├── displayStyle === 'numbered' → 40×40 magenta badges (colIdx+1)
+    ├── displayStyle === 'graphics' → CustomSliderTrack per row
+    └── displayStyle === 'standard' → custom radio circles #e20074
+```
 
-**Star mode:** filled `FaStar` `#e20074` when selected; `FaRegStar` `#d1d5db` opacity 0.5 when unselected; hover ring `ring-2 ring-[#e20074] ring-offset-2`.
+## Emoji + anchor labels (Page 9 fixture)
 
-**Numbered mode:** 40×40 badge; selected = magenta fill `#e20074` white text; unselected = gray border.
+- 5 `scaleAnchorLabels` over 6 columns (5 emoji + N/A)
+- Emoji cells: pink ring when selected; tooltip shows `col.label` on hover
+- Do NOT replace emojis with plain radio buttons
 
-**Graphics mode:** `CustomSliderTrack` per row with `ticks={scaleColumns.length}`, `tickLabels={scaleColumns.map(c => c.label)}`, `sliderType="graphics"`.
+## Star mode (Page 14 fixture)
 
-Apply `reverseScaleOrder` by flipping column index before icon lookup.
+- `CsatStarIcons` from `surveyUiIcons.tsx`
+- Unselected opacity 0.5; selected filled star `#e20074`
 
-## Scale column labels on slider (Day 19)
+## Graphics / numbered (RATING_MATRIX reuse)
 
-Pass `tickLabels={visibleScaleColumns.map(col => col.label)}` to `CustomSliderTrack` so tooltips and graphics thumb show mapped labels, not raw numeric indices.
+See [`08-matrix-csat-rating.md`](08-matrix-csat-rating.md) — same `CsatMatrixScale` component.
 
 ## Answer Mutation
 
-Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+Store **`column.id`** via `matrixColumnStoredValue(col)`:
 
 ```typescript
 onSelect(MatrixRowAnswers)
@@ -86,7 +101,26 @@ onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers
 
 ## Agent Checklist
 
-- [ ] All displayStyle × gridLayout branches
-- [ ] reverseScaleOrder on emoji/star/numbered
-- [ ] Carousel pink dot indicators
-- [ ] Vertical selectbox cards match MCQ card styling
+- [ ] Copied `CsatMatrixScale.tsx` + dependencies
+- [ ] **180px statement column visible** on every row
+- [ ] Column headers OR `scaleAnchorLabels` row visible (never both missing)
+- [ ] `displayStyle` branch matches survey (emoji ≠ star ≠ numbered ≠ radio)
+- [ ] N/A column when `hasNotApplicableOption`
+- [ ] `react-icons` in package.json
+
+## Wizard customization (Phase 5 — required)
+
+> Per-format controls in [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md). Copy [`selectionStyles.ts`](../templates/selectionStyles.ts) + [`labelStyles.ts`](../templates/labelStyles.ts).
+
+| Format | Key tokens | Pattern |
+|--------|------------|---------|
+| emoji / star | `--cfm-input-focus-ring`, `cellSelectedVar` | Ring on select; star fill = cell selected |
+| numbered | `--cfm-number-*`, focus ring + cell selected | Selected cell border + fill |
+| radio grid | `--cfm-csat-column-label-*`, matrix radio styles | `csatColumnLabelStyle()` + `matrixRadioRingStyle` |
+| graphics | `--cfm-slider-tick-label-*` | `CustomSliderTrack` thumb ring + annulus + dot |
+| carousel | `--cfm-matrix-selected` | Active dot = cell selected |
+
+### Wizard checklist
+
+- [ ] Column headers use `csatColumnLabelStyle()` — not hint labels
+- [ ] No per-type accent hex overrides — use Question card tokens only

package/templates/docs/03-ui-specs/06-slider.md

@@ -1,6 +1,8 @@
 # UI Spec: Standalone Slider (`type: 'slider'`)
 
-> **DEPRECATED:** Not in the current `SurveyQuestion` union. API SLIDER pages map to `SLIDER_MATRIX` or matrix `displayStyle: 'graphics'`. See `10-slider-matrix.md` and `CustomSliderTrack` specs.
+> **⛔ DEPRECATED — DO NOT IMPLEMENT.** API SLIDER maps to `SLIDER_MATRIX` (`09-slider-matrix.md`) or RATING/CSAT `displayStyle: 'graphics'` (`08-matrix-csat-rating.md`).
+>
+> If you see slider-like UI, copy [`templates/SliderMatrixScale.tsx`](../templates/SliderMatrixScale.tsx) or use `CsatMatrixScale` with `CustomSliderTrack` — not this spec.
 >
 > **Reference:** Standalone slider is not routed in current `Question.tsx`
 > **SDK type:** `SliderQuestion` — `fetchSurvey/types/slider.ts`

package/templates/docs/03-ui-specs/07-matrix-cfm.md

@@ -1,6 +1,7 @@
 # UI Spec: CFM Matrix (`type: 'CFM_MATRIX'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/LikertMatrixScale.tsx`
+> **COPY TEMPLATE FIRST:** [`templates/LikertMatrixScale.tsx`](../templates/LikertMatrixScale.tsx) + [`MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx)
+>
 > **SDK type:** `CfmMatrixQuestion` — `fetchSurvey/types/cfmMatrix.ts`
 > **Component blueprint:** `01-components/06-likert-matrix-scale.md`
 
@@ -18,68 +19,90 @@
 | `showColumnHeaders` | ✅ | Show/hide column header row |
 | `hasNotApplicableOption` | ✅ | N/A column with mutex |
 
-## Config Decision Tree
+## Statement & label visibility (CRITICAL)
 
-```
-CFM_MATRIX
-├── gridLayout === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
-├── gridLayout === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
-└── else → LikertMatrixGridLayout
-    ├── transposeTable ? columns×rows : rows×columns
-    ├── repeatColumnHeaders ? header per row : single header
-    ├── showColumnHeaders ? column headers : hidden
-    └── statementLayout === 'bipolar' ? 25% | scale | 25% layout
-```
+### Row labels
+
+| Layout | Left column content | Width |
+|--------|---------------------|-------|
+| `statementLayout: 'likert'` | `statementRows[].statementText` | 180px |
+| `statementLayout: 'bipolar'` | `statementRows[].statementText` | 25% |
+| `transposeTable: true` | `scaleColumns[].label` (rows become scale items) | 180px |
 
-## Interactive Behaviors
+Always use `dangerouslySetInnerHTML` for HTML statement text.
 
-| Behavior | Condition | Action |
-|----------|-----------|--------|
-| Click selected radio again | single-select grid/carousel | Clear row (`undefined`) |
-| N/A selected | any | Other cols opacity 0.4, disabled |
-| Multi N/A | selectionMode multiple | Sets `[null]` exclusively |
-| Multi toggle | selectionMode multiple | Add/remove from array |
+### Bipolar right column
 
-## Grid Layout
+When `statementLayout === 'bipolar'`, render **`oppositeStatementText`** in 25% right column (unless transposed):
 
-- Row label column: `180px` (likert) or `25%` (bipolar)
-- Zebra rows: even rows `rgba(249,250,251,0.8)`
-- Native inputs: `accentColor: #e20074`, 18×18px
+```tsx
+<span dangerouslySetInnerHTML={{ __html: row.oppositeStatementText ?? '' }} />
+```
 
-## Carousel — Implementation Recipe
+### Column / anchor labels
 
-| Rule | Behavior |
-|------|----------|
-| Prev button | Disabled when `currentRowIndex === 0` |
-| Next button | Disabled when on last visible row |
-| Dot indicators | Click dot → jump to that row index |
-| On answer | **Do not** auto-advance to next row |
-| Keyboard | Optional Left/Right for prev/next |
-| Active dot (Likert) | `#2563eb`, expanded pill `20×8px` vs `8×8px` inactive |
+Header renders when `scaleAnchorLabels` OR `showColumnHeaders`:
 
-One statement row visible at a time; column headers below cells when `showColumnHeaders`.
+**Bipolar + anchor labels (Page 7 fixture)** — `showColumnHeaders: false`:
 
-## N/A mutex (all layouts)
+```
+[25% spacer] [Label1 at col2] [Label2 at col6] [Label3 at col10] [25% spacer]
+[25% Left Stmt 1] [10 radios] [25% Right Stmt 1]
+```
 
-| Action | Result |
-|--------|--------|
-| Select N/A | Clear other column values for row; other inputs opacity 0.4 + disabled |
-| Select column after N/A | Clear N/A first |
-| Multi-select + N/A | N/A sets `[null]` exclusively |
+Anchor positioning:
 
-## Implementation Recipe
+```typescript
+const numCols = gridCols.length;
+if (idx === 0) left = `${100 / (2 * numCols)}%`;
+else if (idx === labels.length - 1) left = `${100 - 100 / (2 * numCols)}%`;
+else if (labels.length === 3 && idx === 1) left = '50%';
+```
 
-Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+**Transposed + column headers (Page 10 fixture)** — `transposeTable: true`, `showColumnHeaders: true`:
 
 ```typescript
-onSelect(MatrixRowAnswers) // Record<statementRows[].id, value | value[] | null>
-onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
+gridRows = scaleColumns;   // row labels = Scale Item 1, 2, 3
+gridCols = statementRows;  // column headers = Statement Item 1, 2, 3
+// Header cell HTML: col.statementText
+// Row label HTML: row.label
+input type = selectionMode === 'multiple' ? 'checkbox' : 'radio';
+```
+
+Answer keys **always** use `statementRows[].id` as row id (`actualRowId` logic in template).
+
+## Config Decision Tree
+
+```
+CFM_MATRIX
+├── gridLayout === 'dropdown' → MatrixDropdown per statement row
+├── gridLayout === 'carousel' → one row visible + blue dot nav
+└── else → LikertMatrixGridLayout
+    ├── transposeTable swaps gridRows/gridCols
+    ├── showColumnHeaders controls column label row
+    └── statementLayout bipolar adds oppositeStatementText column
 ```
 
 ## Agent Checklist
 
-- [ ] All three gridLayout branches
-- [ ] transposeTable + repeatColumnHeaders + showColumnHeaders
-- [ ] Bipolar 25/50/25 layout with oppositeStatementText
-- [ ] Single-select deselect on re-click
-- [ ] N/A mutex with opacity 0.4
+- [ ] Copied `LikertMatrixScale.tsx` + `MatrixDropdown.tsx`
+- [ ] Row labels visible (statementText or transposed scale label)
+- [ ] Bipolar: oppositeStatementText on right when not transposed
+- [ ] Anchor labels OR column headers — never both missing when configured
+- [ ] `selectionMode: multiple` uses checkboxes, not radios
+- [ ] `transposeTable` swaps rows/cols correctly
+
+## Wizard customization (Phase 5 — required)
+
+> CFM column headers are **label items** only. See [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md).
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Row / bipolar width | `--cfm-matrix-row-width`, `--cfm-matrix-bipolar-width` | Statement columns |
+| Label items | `--cfm-matrix-column-label-color`, `--cfm-matrix-column-label-bg` | Column header row — `matrixColumnLabelStyle()` |
+| Selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `matrixRadioRingStyle` / dropdown option ring |
+
+### Wizard checklist
+
+- [ ] `labelStyles.ts` imported; column headers never use hint-label vars
+- [ ] No CFM-specific accent overrides — Question card tokens only

package/templates/docs/03-ui-specs/08-matrix-csat-rating.md

@@ -1,6 +1,7 @@
 # UI Spec: Rating Matrix Grid (`type: 'RATING_MATRIX'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
+> **COPY TEMPLATE FIRST:** [`templates/CsatMatrixScale.tsx`](../templates/CsatMatrixScale.tsx) — **same component as CSAT_MATRIX**
+>
 > **SDK type:** `RatingMatrixQuestion` — `fetchSurvey/types/ratingMatrix.ts`
 > **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
@@ -8,34 +9,63 @@
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
-| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid data |
+| `displayStyle` | ✅ | **numbered / graphics / standard** — NOT generic radio grid |
 | `gridLayout` | ✅ | carousel vs standard vs dropdown |
-| `hasNotApplicableOption` | ✅ | N/A column or checkbox |
-| `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
 | `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
-| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
-| `scaleColumns[].accentColor` | ✅ | NPS-style badge colors when numbered |
+| `minLabel` / `maxLabel` | ✅ | Rendered in `Question.tsx` above scale |
+| `hasNotApplicableOption` | ✅ | N/A column |
+| `reverseScaleOrder` | ✅ | Flip column index |
 
-## Config Decision Tree
+## Statement & label visibility (CRITICAL)
 
-Same as `CSAT_MATRIX` — reuse `CsatMatrixScale`. See [04-csat.md](04-csat.md) for emoji/star/carousel/N/A/graphics recipes.
+Same rules as [`04-csat.md`](04-csat.md):
 
-## Carousel / N/A / scale labels
+1. **180px row column** — `statementRows[].statementText` via `dangerouslySetInnerHTML`
+2. **Header row** — `scaleAnchorLabels` OR `scaleColumns[].label` (never both missing)
+3. **Page 14 numbered fixture** — 10 column headers "1"–"10" above radio/badge row
 
-Follow CSAT Implementation Recipes in [04-csat.md](04-csat.md): pink carousel dots, N/A mutex, `tickLabels` from `scaleColumns[].label` on graphics sliders.
+## displayStyle branches (do NOT collapse to generic radios)
 
-## Answer Mutation
+| displayStyle | UI | Page fixture |
+|--------------|-----|--------------|
+| `numbered` | 40×40 magenta badges showing `colIdx+1`; tooltip = `col.label` | Page 14 Q8 |
+| `graphics` | One `CustomSliderTrack` per row; `min=0`, `max=cols-1`, `tickLabels=scaleColumns.map(c=>c.label)` | Page 11 |
+| `standard` | Custom 18px radio circles, `#e20074` accent | — |
+| `emoji` / `star` | Same as CSAT — see [`04-csat.md`](04-csat.md) | — |
+
+**graphics mode is NOT `SliderMatrixScale`** — it uses `CsatMatrixScale` with `CustomSliderTrack` per statement row.
+
+## minLabel / maxLabel (Page 11)
 
-Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+`Question.tsx` template renders these above `CsatMatrixScale` when set on the question.
+
+## Answer Mutation
 
 ```typescript
-onSelect(MatrixRowAnswers)
-onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
+onSelect(MatrixRowAnswers) // keys = statementRows[].id, values = scaleColumns[].id
+matrixColumnStoredValue(col) // returns col.id or null for N/A
 ```
 
 ## Agent Checklist
 
-- [ ] Reuse CsatMatrixScale with `RATING_MATRIX` type
-- [ ] Apply accentColor on numbered badges when present
-- [ ] minLabel / maxLabel above grid when set
+- [ ] Reuse copied `CsatMatrixScale` — do not create separate RatingMatrixScale
+- [ ] Statement text visible in 180px column
+- [ ] Column headers or anchor labels visible
+- [ ] `displayStyle: numbered` uses badges, not native radios
+- [ ] `displayStyle: graphics` uses CustomSliderTrack per row
+
+## Wizard customization (Phase 5 — required)
+
+> Reuses `CsatMatrixScale` patterns — see [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md) § RATING_MATRIX.
+
+| Format | Key tokens |
+|--------|------------|
+| radio | Horizontal grid + `matrixRadioRingStyle` |
+| star / emoji / numbered | Same as CSAT formats |
+| graphics / slider | `CustomSliderTrack` thumb ring + annulus + dot |
+
+### Wizard checklist
+
+- [ ] Radio format is horizontal grid (not vertical list)
+- [ ] `csatColumnLabelStyle()` on column headers