@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

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,11 +10,56 @@
 | 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) |
+
+## Statement & label visibility (CRITICAL)
+
+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>
+```
+
+### 2. Column labels — two modes (mutually exclusive header row)
+
+| 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` |
+
+**When `scaleAnchorLabels` is set**, still render anchor row even if column text labels are long (emoji mode Page 9 fixture):
+
+```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%)
+```
+
+**When no anchor labels**, render column headers:
+
+```tsx
+{scaleColumns.map(col => (
+  <span dangerouslySetInnerHTML={{ __html: col.label }} />
+))}
+```
+
+### 3. N/A column header
+
+When `hasNotApplicableOption`, reserve **56px** right column with "N/A" header text.
 
 ## Config Decision Tree
 
@@ -21,33 +67,32 @@
 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)
+    ├── 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
 ```
 
-## Grid Structure
+## Emoji + anchor labels (Page 9 fixture)
+
+- 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
 
-- Row label: `180px` fixed column
-- N/A column: `56px` when `hasNotApplicableOption`
-- Alternating row backgrounds
-- Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
+## Star mode (Page 14 fixture)
 
-## Carousel
+- `CsatStarIcons` from `surveyUiIcons.tsx`
+- Unselected opacity 0.5; selected filled star `#e20074`
 
-- Pink active dot expands: `20px × 8px` vs `8px` inactive
-- Column labels below cells
-- Emoji tooltip via hover state
-- Graphics mode: slider maps column index
+## Graphics / numbered (RATING_MATRIX reuse)
+
+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)
@@ -56,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,52 +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 |
+
+Always use `dangerouslySetInnerHTML` for HTML statement text.
 
-## Interactive Behaviors
+### Bipolar right column
 
-| 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 |
+When `statementLayout === 'bipolar'`, render **`oppositeStatementText`** in 25% right column (unless transposed):
 
-## Grid Layout
+```tsx
+<span dangerouslySetInnerHTML={{ __html: row.oppositeStatementText ?? '' }} />
+```
+
+### Column / anchor labels
 
-- Row label column: `180px` (likert) or `25%` (bipolar)
-- Zebra rows: even rows `rgba(249,250,251,0.8)`
-- Native inputs: `accentColor: #e20074`, 18×18px
+Header renders when `scaleAnchorLabels` OR `showColumnHeaders`:
 
-## Carousel
+**Bipolar + anchor labels (Page 7 fixture)** — `showColumnHeaders: false`:
 
-- Blue active dot: `#2563eb` (Likert only)
-- Card: white, border, shadow, centered row text
+```
+[25% spacer] [Label1 at col2] [Label2 at col6] [Label3 at col10] [25% spacer]
+[25% Left Stmt 1] [10 radios] [25% Right Stmt 1]
+```
 
-## Answer Mutation
+Anchor positioning:
+
+```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,30 +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` grid — reuse `CsatMatrixScale` component. See [04-csat.md](04-csat.md) decision tree with `type: 'RATING_MATRIX'`.
+Same rules as [`04-csat.md`](04-csat.md):
 
-## Answer Mutation
+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
+
+## displayStyle branches (do NOT collapse to generic radios)
+
+| 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)
+
+`Question.tsx` template renders these above `CsatMatrixScale` when set on the question.
 
-Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+## 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

package/templates/docs/03-ui-specs/09-slider-matrix.md

@@ -1,61 +1,105 @@
 # UI Spec: Slider Matrix (`type: 'SLIDER_MATRIX'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/SliderMatrixScale.tsx`
+> **COPY TEMPLATE FIRST:** [`templates/SliderMatrixScale.tsx`](../templates/SliderMatrixScale.tsx) + [`CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts)
+>
+> **Anti-pattern:** Do NOT build custom range overlay sliders. Lone pink circle with no track = broken implementation.
+>
 > **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`
 > **Component blueprint:** `01-components/07-slider-matrix-scale.md`
-> **Shared:** [`shared/custom-slider-track.md`](shared/custom-slider-track.md)
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `rows[]` (min/max/step) | ✅ | Per-row slider range |
-| `labels[]` | ✅ | Header anchor labels |
-| `tickValues[]` | ✅ | Colored badges above track |
-| `ticks` | ✅ | Discrete marks + htmlStep |
-| `sliderType: 'graphics'` | ✅ | Plain text tick labels; emoji thumb |
+| `statementRows[]` (min/max/step) | ✅ | Per-row slider + **25% statement column** |
+| `scaleAnchorLabels?` | ✅ | Text labels above tick badge row |
+| `ticks.count` + `ticks.marks[]` | ✅ | Colored header badges (`tickPosition`, `tickLabel`) |
+| `sliderStyle: 'graphics'` | ✅ | Plain text tick labels; emoji thumb |
 | `enableInputBox` | ✅ | 80px input + stepper buttons |
 | `displayValues` | ✅ | Passed to CustomSliderTrack |
-| `enableNotApplicable` | ✅ | Checkbox; value `'N/A'` string |
+| `hasNotApplicableOption` | ✅ | Checkbox; answer value **`'N/A'`** string |
 
 ## Layout Anatomy
 
 ```
-[header: labels[] + tickValues badges OR computed marks]
+[header: scaleAnchorLabels? + colored tick badges from ticks.marks]
 ┌─ row band (#f3f4f6, rounded-xl) ─────────────────────────────┐
-│ 25% statement │ CustomSliderTrack │ 25% rightText? │ input? │ N/A? │
+│ 25% statementText │ CustomSliderTrack │ 80px input? │ N/A? │
 └───────────────────────────────────────────────────────────────┘
 ```
 
-## Header Tick Positioning
+## Statement text (CRITICAL)
+
+Every row MUST show `statementRows[].statementText` in the left 25% column:
+
+```tsx
+<div style={{ flex: '0 0 25%', paddingRight: '16px' }}>
+  {row.statementText && row.statementText !== 'Question' && (
+    <span dangerouslySetInnerHTML={{ __html: row.statementText }} />
+  )}
+</div>
+```
+
+Agents that hide statement text or merge it into the question title break multi-row sliders.
+
+## Header tick badges
 
 ```typescript
-percentage = ((tv.value - min) / (max - min)) * 100
-sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100
-// Colored badge: tv.color bg, white text, rounded 4px
-// graphics: plain text label instead of colored badge
+tickValues = ticks.marks.map((mark, i) => ({
+  value: mark.tickPosition,
+  label: mark.tickLabel,
+  color: tickColorFromIndex(i, ticks.count),
+}));
+percentage = ((tv.value - min) / (max - min)) * 100;
+htmlStep = ticks.count > 1 ? (max - min) / (ticks.count - 1) : row.step;
 ```
 
-## N/A Behavior
+## CustomSliderTrack per row
 
-- Checked → `rowVal === 'N/A'`; slider disabled, input grayed
-- Unchecked → reset to `defaultValue ?? min`
+```typescript
+<CustomSliderTrack
+  min={row.min}
+  max={row.max}
+  htmlStep={htmlStep}
+  value={rowVal as number}
+  disabled={rowVal === 'N/A'}
+  hasSelectedValue={typeof rowVal === 'number'}
+  displayValues={displayValues}
+  sliderType={question.sliderStyle === 'graphics' ? 'graphics' : undefined}
+  ticks={ticks.count}
+  onChange={v => updateRow(row.id, v)}
+/>
+```
 
-## Input Box
+## N/A Behavior
 
-- Clamp to row.min / row.max on change
-- Steppers use `htmlStep` increment/decrement
+- Checked → `rowVal === 'N/A'`; slider disabled
+- Unchecked → reset to `defaultValue ?? min`
 
 ## Answer Mutation
 
 ```typescript
-onSelect(Record<string, number | null | 'N/A'>)
+onSelect(Record<string, number | 'N/A'>)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] Shared header from first row min/max/step
-- [ ] Gray row bands with 25% statement columns
+- [ ] Copied portable templates — did not build slider from scratch
+- [ ] Shared header with colored 0–10 badges (even single-row questions)
+- [ ] Gray row bands with **visible** statement text in 25% column
 - [ ] CustomSliderTrack per row with correct htmlStep
-- [ ] tickValues colored badges (non-graphics)
-- [ ] N/A mutex disables slider + input
+- [ ] N/A uses `'N/A'` string, not null
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Tick label items | `--cfm-slider-tick-label-color`, `--cfm-slider-tick-label-bg` | Header badge row — `sliderTickLabelStyle()` |
+| Row band | `--cfm-slider-row-bg` | Gray statement band |
+| Thumb selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `CustomSliderTrack` thumb ring + annulus + dot |
+
+### Wizard checklist
+
+- [ ] Colored tick badges use `--cfm-number-*` when traffic-light mode applies
+- [ ] `labelStyles.ts` imported for tick label row

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -1,18 +1,18 @@
 # UI Spec: File Upload (`type: 'FILE_UPLOAD'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/FileUploadScale.tsx`
 > **SDK type:** `FileUploadQuestion` — `fetchSurvey/types/fileUpload.ts`
 > **Component blueprint:** `01-components/08-file-upload-scale.md`
+> **Upload API:** [`00-integration/file-upload-aws.md`](../00-integration/file-upload-aws.md)
 
 ## Config Inventory
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `uploadMessage` | ✅ | HTML in dropzone (bold 16px) |
-| `supportedFileFormats` | ✅ | Validation + accept attribute |
-| `maxFileCount` | ✅ | Total file limit |
-| `fileSizeLimit` | ✅ | MB limit |
-| `fileSizeLimitType` | ✅ | `PER_FILE` or `IN_TOTAL` |
+| Field | UI impact |
+|-------|-----------|
+| `uploadMessage` | HTML in dropzone (bold 16px) |
+| `supportedFileFormats` | Validation + accept attribute |
+| `maxFileCount` | Total file limit |
+| `fileSizeLimit` | MB limit |
+| `fileSizeLimitType` | `PER_FILE` or `IN_TOTAL` |
 
 ## Layout Anatomy
 
@@ -20,7 +20,7 @@
 [uploadMessage HTML in dashed dropzone]
   File limit: N; File size limit: XMB/file|in total; Supports: ...
 [local error banner — red if validation fails]
-[file list cards: icon, name, size, remove ×]
+[file list cards: icon, name, size, uploading…, remove ×]
 ```
 
 ## Interactive States
@@ -31,24 +31,56 @@
 | Hover | `#e20074` | `#fdf2f8` |
 | Drag active | `#e20074` | `#fdf2f8` |
 
-## Local Validation (before SDK)
+## Implementation Recipe
 
-1. Max file count exceeded
-2. Unsupported extension
-3. PER_FILE size exceeded
-4. IN_TOTAL cumulative size exceeded
+### Phase 1 — Local pick + validate
 
-Error banner: `#fee2e2` bg, `#b91c1c` text.
+1. Hidden `<input type="file" multiple={maxFileCount > 1}>`
+2. Drag enter/over/leave/drop on dropzone
+3. Reject: wrong extension, count exceeded, size exceeded
+
+### Phase 2 — Upload (required for submit)
+
+```
+User picks File
+  → POST {uploadApi}/get-upload-url { fileName, contentType, questionId }
+  ← { uploadUrl, fileId, mediaUrl }
+  → PUT uploadUrl (binary body, file Content-Type)
+  → onSelect([...existing, { id: fileId, mediaUrl, name, mimeType, size }])
+  → onAction(CHANGE)
+```
+
+See [`file-upload-aws.md`](../00-integration/file-upload-aws.md).
+
+### Phase 3 — Remove
+
+Remove from list → `onSelect(undefined)` when empty, else updated `UploadedFileAnswer[]`.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(File[] | undefined) // undefined when all removed
+// After upload completes — NOT raw File[]
+onSelect: (value: UploadedFileAnswer[] | undefined) => void
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } })
 ```
 
+**Non-submittable:** storing `File[]` only — SDK submit drops attachments.
+
 ## Agent Checklist
 
-- [ ] Hidden `<input type="file">` triggered by dropzone click
-- [ ] Drag enter/over/leave/drop handlers
-- [ ] Dynamic constraints line in dropzone
-- [ ] File list with remove button (hover red)
+- [ ] Local validation before upload
+- [ ] Presigned upload wired; progress/spinner per file
+- [ ] Final answer shape: `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Remove clears answer or passes updated array
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Dropzone border | `--cfm-upload-border-color` | Dashed border on upload area |
+| Focus / drag-over | `--cfm-input-focus-ring` | Active dropzone outline |
+
+### Wizard checklist
+
+- [ ] Dropzone border uses `var(--cfm-upload-border-color)` not hardcoded hex

package/templates/docs/03-ui-specs/11-text-and-media.md

@@ -47,3 +47,7 @@ Container-level media (survey chrome) is separate — see `03-ui-specs/12-survey
 
 - [ ] No CHANGE action — display-only
 - [ ] Matrix row: [`question-type-sdk-matrix.md#text_and_media`](../00-integration/question-type-sdk-matrix.md#text_and_media)
+
+## Wizard customization (Phase 5 — required)
+
+Display-only — no selection tokens. Media caption may use `--cfm-question-title-color` for consistency.