@explorer02/cfm-survey-sdk 0.2.2 → 0.2.3

package/templates/docs/01-components/13-matrix-dropdown.md

@@ -1,46 +1,41 @@
 # Matrix Dropdown
 
-> **UI spec (authoritative):** `03-ui-specs/shared/matrix-dropdown.md`
-> **Reference implementation:** `apps/client/src/components/MatrixDropdown.tsx`
-> **Component**: `MatrixDropdown`
-> **Used by**: `CsatMatrixScale`, `LikertMatrixScale`
+> **UI spec (authoritative):** [`03-ui-specs/shared/matrix-dropdown.md`](../03-ui-specs/shared/matrix-dropdown.md) — implement the **custom panel** (not a native `<select>`).
+> **Portable template:** copy [`templates/MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx) when available.
+> **Component:** `MatrixDropdown`
+> **Used by:** `CsatMatrixScale`, `LikertMatrixScale`
 
 ## Role
-Renders a dropdown selector for a single row in a matrix question. Used when `gridLayout === 'dropdown'` or `displayStyle === 'dropdown'`.
 
-Accepts `ScaleColumn[]`; emits stored column ids via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+Renders a custom dropdown selector for a single matrix row. Used when `gridLayout === 'dropdown'` or `displayStyle` is `'dropdown'` / `'selectbox'`.
+
+Emits stored column **`id`** values via `matrixColumnStoredValue(col)` — see [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
+
+## Props (wiring only)
 
-## Props Interface
 ```typescript
 type MatrixDropdownProps = {
-  columns: MatrixColumn[];
-  selectedValue: string | number | null | undefined;
+  options: ScaleColumn[];           // visible columns for this row
+  value: string | number | null | undefined;
   onChange: (value: string | number | null) => void;
+  multiple?: boolean;
   placeholder?: string;
 };
 ```
 
-## Structure
-Renders a native HTML `<select>` element.
-
-```tsx
-<select
-  value={selectedValue === null ? '' : String(selectedValue ?? '')}
-  onChange={e => {
-    const val = e.target.value;
-    if (val === '') onChange(null); // Map empty string back to null for N/A
-    else {
-      // Find original option to keep type (number vs string) intact
-      const opt = columns.find(c => String(c.value) === val);
-      onChange(opt ? opt.value : val);
-    }
-  }}
->
-  <option value="" disabled>Select an option...</option>
-  {columns.map(col => (
-    <option key={String(col.value)} value={String(col.value)}>
-      {col.label}
-    </option>
-  ))}
-</select>
-```
+## Implementation
+
+Do **not** use a native `<select>`. Follow the shared ui-spec for:
+
+- Click-to-open panel with click-outside dismiss
+- Single-select: one choice; multi-select: tag chips + toggle
+- N/A mutual exclusion when `hasNotApplicableOption` applies
+- Placeholder text: `"Select..."` (dropdown) or full-width cards (selectbox)
+
+See [`03-ui-specs/shared/matrix-dropdown.md`](../03-ui-specs/shared/matrix-dropdown.md) for layout, states, and agent checklist.
+
+## SDK Integration Checklist
+
+- [ ] Copy `templates/MatrixDropdown.tsx` or implement per shared ui-spec
+- [ ] `onChange` stores column **`id`** via `matrixColumnStoredValue(col)`
+- [ ] Filter columns with `getVisibleMatrixItemsForAnswers` before passing to dropdown

package/templates/docs/01-components/17-heatmap-scale.md

@@ -2,7 +2,7 @@
 
 > **UI spec (authoritative):** `03-ui-specs/13-heatmap.md`
 > **Reference implementation:** `apps/client/src/components/HeatmapScale.tsx`
-> **Coordinate helpers:** `apps/client/src/lib/surveyUi/heatmapCoords.ts`
+> **Portable coord helper:** copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
 > **Target Component**: `HeatmapScale`
 > **Handles**: `type: 'HEATMAP'`
 
@@ -15,8 +15,8 @@ Render the heatmap image, capture click spots in normalized 0–1 coordinates, t
 ```typescript
 type HeatmapScaleProps = {
   question: HeatmapQuestion;
-  selectedValue?: HeatmapAnswer;
-  onSelect: (answer: HeatmapAnswer | undefined) => void;
+  selectedValue?: HeatmapClickPoint[];
+  onSelect: (answer: HeatmapClickPoint[] | undefined) => void;
 };
 ```
 
@@ -34,7 +34,7 @@ type HeatmapScaleProps = {
 
 ## Coordinate Helpers
 
-Use `apps/client/src/lib/surveyUi/heatmapCoords.ts`:
+Copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts):
 
 - `getNormalizedClickFromImage(event, imageElement)`
 - `findSpotNearClick(clickX, clickY, spots, imageRect)`

package/templates/docs/01-components/18-rank-order-scale.md

@@ -1,13 +1,13 @@
 # Rank Order Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/14-rank-order.md`
-> **Reference implementation:** `apps/client/src/components/RankOrderScale.tsx`
+> **Portable template:** copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
 > **Target Component:** `RankOrderScale`
 > **Handles:** `type: 'RANK_ORDER'`
 
 ## Core Responsibility
 
-Render rankable options in either **dropdown** or **drag-and-drop** mode, support three option display variants (text only, image only, text and image), and bubble rank assignments via `onSelect`.
+Render rankable options in **dropdown** or **drag-and-drop** mode, three option display variants, bubble ranks via `onSelect`.
 
 ## Props Contract
 
@@ -21,9 +21,9 @@ type RankOrderScaleProps = {
 
 ## State Management
 
-- `selectedValue` from SDK is source of truth — do not duplicate answer state locally
-- Dropdown mode: use `assignRankWithoutDuplicates` from SDK when a rank changes
-- Drag-and-drop mode: use `buildRankOrderFromOrderedOptionIds` after reorder
+- `selectedValue` from SDK is source of truth — no duplicate local answer state
+- Dropdown: `assignRankWithoutDuplicates` on rank change
+- Drag-and-drop: `buildRankOrderFromOrderedOptionIds` after reorder; `getOrderedOptionIdsFromRanks` for display order
 
 ## Layout Orchestrator
 
@@ -36,20 +36,9 @@ export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderS
 }
 ```
 
-## Dropdown Mode
+## shuffleOptions
 
-- One row per visible option
-- Left: rank `<select>` with `-` (unassigned) and `1..N`
-- Selecting rank `R` clears `R` from any other option (SDK helper)
-- Option content depends on `question.optionDisplay`
-- **Image URLs:** prefer `option.imageUrl` over `option.previewImageUrl` — preview `*_p.*` URLs often return 403 on CloudFront
-
-## Drag-and-Drop Mode
-
-- Use `@dnd-kit/core` + `@dnd-kit/sortable` for smooth reorder
-- List order maps to ranks: position 0 → rank 1
-- Show rank badge on each row
-- Provide Up/Down buttons for keyboard accessibility
+When API `SHUFFLE_ORDER` is true, SDK shuffles options at map time. **Do not re-shuffle in the client** — logic and option ids must stay aligned with fetched order.
 
 ## Wiring in Question.tsx
 
@@ -57,6 +46,7 @@ export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderS
 import {
   QUESTION_TYPE,
   getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
 } from '@explorer02/cfm-survey-sdk';
 
 const rankOrderQuestion = useMemo(() => {
@@ -64,10 +54,7 @@ const rankOrderQuestion = useMemo(() => {
   return {
     ...question,
     options: getVisibleRankOrderOptionsForAnswers(
-      question,
-      allAnswers,
-      allQuestions,
-      customFieldValues
+      question, allAnswers, allQuestions, customFieldValues
     ),
   };
 }, [question, allAnswers, allQuestions, customFieldValues]);
@@ -75,7 +62,11 @@ const rankOrderQuestion = useMemo(() => {
 {question.type === QUESTION_TYPE.RANK_ORDER && rankOrderQuestion && (
   <RankOrderScale
     question={rankOrderQuestion}
-    selectedValue={...}
+    selectedValue={normalizeRankOrderAnswers(
+      typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue)
+        ? selectedValue
+        : undefined
+    )}
     onSelect={onSelect}
   />
 )}
@@ -83,18 +74,20 @@ const rankOrderQuestion = useMemo(() => {
 
 ## Dependencies
 
-Add to client `package.json`:
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+## Next.js SSR
 
-- `@dnd-kit/core`
-- `@dnd-kit/sortable`
-- `@dnd-kit/utilities`
+Template uses `'use client'`. For drag-and-drop, optional `dynamic(..., { ssr: false })` in Question.tsx if hydration warnings occur.
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
 - [ ] Type literal: `QUESTION_TYPE.RANK_ORDER`
-- [ ] Answer stored as: `RankOrderAnswers`
-- [ ] onAction CHANGE: `{ questionId, answerValue: RankOrderAnswers }`
-- [ ] Visibility helper: `getVisibleRankOrderOptionsForAnswers(..., customFieldValues?)`
-- [ ] Rank utils: `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `normalizeRankOrderAnswers`
+- [ ] Answer: `RankOrderAnswers`
+- [ ] Visibility: `getVisibleRankOrderOptionsForAnswers(..., customFieldValues?)`
+- [ ] Utils: `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `normalizeRankOrderAnswers`
 - [ ] Prefer `option.imageUrl` over `previewImageUrl`
 - [ ] Matrix row: [`question-type-sdk-matrix.md#rank_order`](../00-integration/question-type-sdk-matrix.md#rank_order)

package/templates/docs/02-reference/question-types/11-file-upload.md

@@ -2,44 +2,59 @@
 
 > **Type**: `'FILE_UPLOAD'` | **API Source**: `FILE_UPLOAD`
 > **Mapper**: `fileUploadMapper.ts` | **Component**: `FileUploadScale`
+> **Upload flow**: [`00-integration/file-upload-aws.md`](../../00-integration/file-upload-aws.md)
 
 ## TypeScript Type
 
 ```typescript
 type FileUploadQuestion = QuestionBase & {
   type: 'FILE_UPLOAD';
-  uploadMessage?: string;              // Instruction text (HTML)
-  supportedFileFormats?: string[];     // ['PDF', 'PNG', 'DOCX'] (uppercase, no dots)
-  maxFileCount?: number;               // Max files allowed
-  fileSizeLimit?: number;              // Max size in MB
+  uploadMessage?: string;
+  supportedFileFormats?: string[];
+  maxFileCount?: number;
+  fileSizeLimit?: number;
   fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
 };
 
-type UploadedFile = {
-  id: string; name: string; mediaUrl: string;
-  mimeType?: string; size?: number;
+/** Stored in state.answers — required for submit */
+type UploadedFileAnswer = {
+  id: string;
+  mediaUrl: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
 };
 ```
 
-## Answer Shape: `UploadedFile[]`
-Array of uploaded file descriptors. Submitted via `quesIdVsAttachmentDetails` (NOT `questionToAnswers`).
+## Answer Shape: `UploadedFileAnswer[]`
+
+Submitted via `quesIdVsAttachmentDetails` (NOT `questionToAnswers`). SDK submit formatter only accepts objects with `id` and `mediaUrl` — **raw browser `File[]` is dropped at submit**.
+
+## Two-phase client flow
+
+1. **Pick + validate locally** — extension, count, size (`PER_FILE` / `IN_TOTAL`)
+2. **Upload each file** — `POST /get-upload-url` → presigned PUT → collect `{ id, mediaUrl, name, mimeType, size }`
+3. **`onAction(CHANGE)`** — pass `UploadedFileAnswer[]` to SDK
+
+See [`file-upload-aws.md`](../../00-integration/file-upload-aws.md) for API contract.
 
 ## Rendering Guidance
-- Drag-and-drop zone + click-to-upload button
+
+- Drag-and-drop zone + click-to-upload
 - Show accepted formats from `supportedFileFormats`
-- Set `<input type="file" accept=".pdf,.png,.docx">`
-- Enforce `maxFileCount` in UI
-- Show file list with name, size, and remove button
-- Enforce `fileSizeLimit` with appropriate error messages
-- `onSelect` receives the full `UploadedFile[]` array
+- Set `<input type="file" accept=".pdf,.png,...">` from formats
+- Enforce `maxFileCount` and `fileSizeLimit` before upload
+- Show file list with name, size, remove button, uploading spinner per file
+- `onSelect(undefined)` when all files removed
+
+## Skip logic
+
+Presence-only (`EXISTS` / `MISSING`) — evaluated on page entry; no discrete value-change events required.
 
 ## SDK Integration Checklist (agent)
 
 - [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
-- [ ] Answer stored as: `UploadedFile[]`
-- [ ] onAction CHANGE payload: `{ questionId, answerValue: UploadedFile[] }` after upload completes
-- [ ] Visibility helper: N/A
-- [ ] Custom fields: skip/display rules only — no visibility helper
-- [ ] Logic features: skip ✓ display ✓ answer ✗ variants ✓ numbering ✓
-- [ ] Performance: upload to presigned URL before CHANGE; show progress UI
+- [ ] Answer stored as: `UploadedFileAnswer[]` after upload completes
+- [ ] onAction CHANGE: `{ questionId, answerValue: UploadedFileAnswer[] }`
+- [ ] Do **not** store raw `File[]` as final answer
 - [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../../00-integration/question-type-sdk-matrix.md#file_upload)

package/templates/docs/02-reference/question-types/README.md

@@ -49,10 +49,20 @@ Each type is **standalone** — open its file in exported SDK types for the comp
 - **Answer:** `string` or `string[]` (`option.id` values)
 - **Options:** `McqOption[]` with `id`, `optionLabel`
 
+| Field | Type | API source |
+|-------|------|------------|
+| `selectionMode` | `'single' \| 'multiple'` | multi-select config |
+| `defaultOptionIds?` | `string[]` | `DEFAULT_ANSWER` when enabled |
+| `minSelections?` | `number` | `ANSWER_CONDITION` / `MIN_ANSWER` |
+| `maxSelections?` | `number` | `ANSWER_CONDITION` / `MAX_ANSWER` |
+| `answerConditionErrorMessage?` | `string` | `ANSWER_CONDITION` error message |
+
+**Default answers:** On survey load, SDK `buildInitialAnswers` / `applyMcqDefaults` pre-populates `state.answers[questionId]` from `defaultOptionIds` (single: first id; multi: full array). Client binds UI checked state to `state.answers` — do not maintain separate default state. SDK re-applies defaults on validation/submit if answer is still empty.
+
 ### SDK Integration Checklist (agent)
 
 - [ ] Type literal: `QUESTION_TYPE.MCQ`
-- [ ] Answer stored as: `option.id` (string/number) or array when multi-select
+- [ ] Answer stored as: `option.id` (string/number) or array when `selectionMode === 'multiple'`
 - [ ] onAction CHANGE payload: `{ questionId, answerValue: optionId | optionId[] }`
 - [ ] Visibility helper: `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`
 - [ ] Custom fields: 4th arg when logic references CRM fields

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

@@ -17,8 +17,16 @@
 | `midLabel` | ✅ | Absolute positioned in Question.tsx |
 | `maxLabel` | ✅ | Absolute positioned in Question.tsx |
 | `midLabelIndex` | ✅ | Mid label `left` percentage |
-| `reverseScaleOrder` | ❌ | Document for agents when SDK sends true |
-| `buttonVariant` | ❌ | Client always uses dual-layer radio layout |
+| `reverseScaleOrder` | ✅ | Reverse option index before selection/color lookup |
+| `buttonVariant` | ❌ | Client uses dual-layer radio layout |
+
+## Answer logic on scale points
+
+When scale points have answer logic, filter with `getVisibleScaleColumnsForAnswers(question, answers, allQuestions, customFieldValues?)` before render.
+
+## Implementation Recipe — reverseScaleOrder
+
+When `reverseScaleOrder === true`, map visual index `i` to stored index `options.length - 1 - i` before deriving submit value and badge color.
 
 ## Answer Mutation
 

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

@@ -2,44 +2,99 @@
 
 > **SDK type:** `McqQuestion` — `fetchSurvey/types/mcq.ts`
 > **Component blueprint:** `01-components/02-question.md`
+> **Dispatcher:** inline in `Question.tsx` (see [`templates/Question.tsx`](../templates/Question.tsx))
 
 ## Config Inventory
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `options[]` | ✅ | One card per option |
-| `options[].optionLabel` | ✅ | HTML via `dangerouslySetInnerHTML` |
-| `options[].id` | ✅ | **Submit value** — selected answer is `option.id` |
-| `isMultiSelect` | ⚠️ | SDK supports multi-select; implement checkbox cards when `true` |
+| Field | UI impact |
+|-------|-----------|
+| `options[]` | One card per visible option |
+| `options[].optionLabel` | HTML via `dangerouslySetInnerHTML` |
+| `options[].id` | **Submit value** — answer is `option.id` |
+| `selectionMode` | `'single'` → radio cards; `'multiple'` → checkbox cards + `string[]` answer |
+| `defaultOptionIds?` | Pre-selected on load (SDK seeds `state.answers`) |
+| `minSelections?` / `maxSelections?` | Answer-condition count (SDK validates on NEXT) |
+| `answerConditionErrorMessage?` | Custom validation banner text |
+| `requiredErrorMessage?` | Required-field error text |
 
-## Multi-select note
+## Selection mode (not `isMultiSelect`)
 
-When `question.isMultiSelect === true`:
+Use `question.selectionMode` from the SDK — **never** `isMultiSelect`.
 
-- Answer shape is `string[]` (or `number[]`) of selected `option.id` values
-- Toggle options on click; do not replace the entire array with a single id
-- onAction CHANGE: `{ questionId, answerValue: selectedIds[] }`
-- Still filter via `getVisibleMcqOptionsForAnswers` before render
+| `selectionMode` | UI | Answer shape |
+|-----------------|-----|--------------|
+| `'single'` (default) | Radio cards; one selected | `string` (option `id`) |
+| `'multiple'` | Checkbox cards; toggle on click | `string[]` of option ids |
 
-When `false` (default), single-select radio behavior applies.
+Multi-select toggle pattern:
+
+```typescript
+const handleToggle = (optionId: string) => {
+  const next = selectedIds.includes(optionId)
+    ? selectedIds.filter(id => id !== optionId)
+    : question.maxSelections && selectedIds.length >= question.maxSelections
+      ? selectedIds  // block add at max
+      : [...selectedIds, optionId];
+  onSelect(next);
+};
+```
+
+Filter options before render: `getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues?)`.
+
+---
+
+## Implementation Recipe — Default answers
+
+| Concern | SDK behavior | Client UI contract |
+|---------|--------------|-------------------|
+| **Config** | API `DEFAULT_ANSWER` → `question.defaultOptionIds?: string[]` | Inventory in implementation plan §4b |
+| **Initial load** | `buildInitialAnswers` / `applyMcqDefaults` writes into `state.answers` | Bind checked state to `selectedValue` (`state.answers[question.id]`) |
+| **Single-select** | Default = `defaultOptionIds[0]` | Pre-selected radio when present in `state.answers` |
+| **Multi-select** | Default = full `defaultOptionIds` array | Pre-checked boxes for each id |
+| **User override** | `applyMcqDefaults` never overwrites user selection | Toggle via `onAction(CHANGE)` |
+| **Validation / submit** | SDK re-applies defaults in `validateCurrentPage` and submit if empty | Client does **not** re-apply defaults at NEXT/SUBMIT |
+| **Answer logic** | Hidden defaults may exist in `state.answers` until SDK sanitizes | Show checked state only for **visible** options |
+| **Template fallback** | `Question.tsx` uses `selectedValue ?? defaultOptionIds` defensively | Prefer `state.answers`; fallback is display-only |
+
+---
+
+## Implementation Recipe — Answer conditions
+
+When API `ANSWER_CONDITION` is enabled, SDK maps:
+
+- `minSelections` — minimum selected count (multi-select)
+- `maxSelections` — maximum selected count (multi-select)
+- `answerConditionErrorMessage` — shown in `state.validationErrors[questionId]`
+
+**Client must:**
+
+1. Render `validationError` banner when SDK sets an error (do not duplicate count validation).
+2. Block adding options when `selectedIds.length >= maxSelections` in multi-select UI.
+3. Pass through `onAction(CHANGE)` with updated array — SDK validates on NEXT.
+
+Skip logic may use `NUM_OF_SELECTED_OPTIONS` — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
+---
 
 ## Answer Mutation
 
 ```typescript
-onSelect(option.id) // string
-// → onAction CHANGE { questionId, answerValue: string }
+// Single-select
+onSelect(option.id)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: string } })
+
+// Multi-select
+onSelect(selectedIds)  // string[]
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: string[] } })
 ```
 
 ## Agent Checklist
 
-- [ ] Full-width card options with gap-3 vertical stack
-- [ ] Custom circular radio indicator (not browser default)
-- [ ] Selected: magenta border + pink background
-- [ ] HTML labels
-- [ ] If `isMultiSelect`: implement checkbox cards with array answer shape
-
-## SDK Integration Checklist (agent)
-
-- [ ] Visibility helper: `getVisibleMcqOptionsForAnswers`
-- [ ] Store `option.id` — never option label text
+- [ ] Use `selectionMode`, not `isMultiSelect`
+- [ ] Full-width card options; custom circular radio / checkbox indicators
+- [ ] Selected: magenta border `#e20074` + pink bg `#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)

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

@@ -38,12 +38,42 @@ CSAT_MATRIX
 - Alternating row backgrounds
 - Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
 
-## Carousel
+## Carousel — Implementation Recipe
 
-- Pink active dot expands: `20px × 8px` vs `8px` inactive
-- Column labels below cells
-- Emoji tooltip via hover state
-- Graphics mode: slider maps column index
+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).
+
+## N/A mutex
+
+| Layout | Behavior |
+|--------|----------|
+| Grid N/A column | Selecting N/A clears row; selecting column clears N/A |
+| Vertical checkbox | `hasNotApplicableOption` checkbox below row sets `null` |
+
+## Emoji / star / numbered — react-icons mapping
+
+Copy [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx) or implement `getEmojiForIndex(index, totalColumns)`.
+
+**5-point CSAT emoji index → icon key:**
+
+| 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 |
+
+**Star mode:** filled `FaStar` `#e20074` when selected; `FaRegStar` `#d1d5db` opacity 0.5 when unselected; hover ring `ring-2 ring-[#e20074] ring-offset-2`.
+
+**Numbered mode:** 40×40 badge; selected = magenta fill `#e20074` white text; unselected = gray border.
+
+**Graphics mode:** `CustomSliderTrack` per row with `ticks={scaleColumns.length}`, `tickLabels={scaleColumns.map(c => c.label)}`, `sliderType="graphics"`.
+
+Apply `reverseScaleOrder` by flipping column index before icon lookup.
+
+## Scale column labels on slider (Day 19)
+
+Pass `tickLabels={visibleScaleColumns.map(col => col.label)}` to `CustomSliderTrack` so tooltips and graphics thumb show mapped labels, not raw numeric indices.
 
 ## Answer Mutation
 

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

@@ -46,12 +46,28 @@ CFM_MATRIX
 - Zebra rows: even rows `rgba(249,250,251,0.8)`
 - Native inputs: `accentColor: #e20074`, 18×18px
 
-## Carousel
+## Carousel — Implementation Recipe
 
-- Blue active dot: `#2563eb` (Likert only)
-- Card: white, border, shadow, centered row text
+| 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 |
 
-## Answer Mutation
+One statement row visible at a time; column headers below cells when `showColumnHeaders`.
+
+## N/A mutex (all layouts)
+
+| 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 |
+
+## Implementation Recipe
 
 Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
 

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

@@ -19,7 +19,11 @@
 
 ## Config Decision Tree
 
-Same as `CSAT_MATRIX` grid — reuse `CsatMatrixScale` component. See [04-csat.md](04-csat.md) decision tree with `type: 'RATING_MATRIX'`.
+Same as `CSAT_MATRIX` — reuse `CsatMatrixScale`. See [04-csat.md](04-csat.md) for emoji/star/carousel/N/A/graphics recipes.
+
+## Carousel / N/A / scale labels
+
+Follow CSAT Implementation Recipes in [04-csat.md](04-csat.md): pink carousel dots, N/A mutex, `tickLabels` from `scaleColumns[].label` on graphics sliders.
 
 ## Answer Mutation
 

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

@@ -36,6 +36,23 @@ sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100
 // graphics: plain text label instead of colored badge
 ```
 
+## CustomSliderTrack per row — scale labels
+
+```typescript
+<CustomSliderTrack
+  min={row.min}
+  max={row.max}
+  htmlStep={row.htmlStep}
+  value={rowVal as number}
+  tickLabels={row.tickLabels ?? scaleColumns.map(c => c.label)}
+  ticks={row.ticks}
+  sliderType={question.sliderStyle === 'graphics' ? 'graphics' : undefined}
+  onChange={v => updateRow(row.id, v)}
+/>
+```
+
+Pass **`scaleColumns[].label`** (or row tick labels) as `tickLabels` — required for correct tooltip text (Day 19 fix).
+
 ## N/A Behavior
 
 - Checked → `rowVal === 'N/A'`; slider disabled, input grayed