@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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

@@ -1,34 +1,34 @@
-# UI Spec: CFM Matrix (`type: 'matrix'`, `subType: 'CFM_MATRIX'`)
+# UI Spec: CFM Matrix (`type: 'CFM_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/LikertMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **SDK type:** `CfmMatrixQuestion` — `fetchSurvey/types/cfmMatrix.ts`
 > **Component blueprint:** `01-components/06-likert-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `rows[]`, `columns[]` | ✅ | Grid / carousel / dropdown data |
-| `matrixFormat` | ✅ | Orchestrator routing |
-| `answerType` | ✅ | `'multiple'` → checkboxes |
-| `matrixType: 'bipolar'` | ✅ | 25% left + 25% right columns |
-| `labels[]` | ✅ | Anchor labels above scale |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `gridLayout` | ✅ | Orchestrator routing |
+| `selectionMode` | ✅ | `'multiple'` → checkboxes |
+| `statementLayout: 'bipolar'` | ✅ | 25% left + 25% right columns |
+| `scaleAnchorLabels[]` | ✅ | Anchor labels above scale |
 | `transposeTable` | ✅ | Swap row/col iteration |
-| `repeatScale` | ✅ | Re-render header per row |
-| `enableScale` | ✅ | Show/hide column header row |
-| `hasNotApplicable` | ✅ | N/A column with mutex |
+| `repeatColumnHeaders` | ✅ | Re-render header per row |
+| `showColumnHeaders` | ✅ | Show/hide column header row |
+| `hasNotApplicableOption` | ✅ | N/A column with mutex |
 
 ## Config Decision Tree
 
 ```
 CFM_MATRIX
-├── matrixFormat === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
-├── matrixFormat === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
+├── gridLayout === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
+├── gridLayout === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
 └── else → LikertMatrixGridLayout
     ├── transposeTable ? columns×rows : rows×columns
-    ├── repeatScale ? header per row : single header
-    ├── enableScale ? column headers : hidden
-    └── matrixType === 'bipolar' ? 25% | scale | 25% layout
+    ├── repeatColumnHeaders ? header per row : single header
+    ├── showColumnHeaders ? column headers : hidden
+    └── statementLayout === 'bipolar' ? 25% | scale | 25% layout
 ```
 
 ## Interactive Behaviors
@@ -37,8 +37,8 @@ CFM_MATRIX
 |----------|-----------|--------|
 | Click selected radio again | single-select grid/carousel | Clear row (`undefined`) |
 | N/A selected | any | Other cols opacity 0.4, disabled |
-| Multi N/A | answerType multiple | Sets `[null]` exclusively |
-| Multi toggle | answerType multiple | Add/remove from array |
+| Multi N/A | selectionMode multiple | Sets `[null]` exclusively |
+| Multi toggle | selectionMode multiple | Add/remove from array |
 
 ## Grid Layout
 
@@ -53,14 +53,17 @@ CFM_MATRIX
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(MatrixAnswerMap) // Record<rowId, value | value[] | null>
+onSelect(MatrixRowAnswers) // Record<statementRows[].id, value | value[] | null>
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] All three matrixFormat branches
-- [ ] transposeTable + repeatScale + enableScale
-- [ ] Bipolar 25/50/25 layout with rightText
+- [ ] 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

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

@@ -1,65 +1,37 @@
-# UI Spec: CSAT / Rating Matrix (`subType: 'CSAT_MATRIX' | 'RATING_MATRIX'`)
+# UI Spec: Rating Matrix Grid (`type: 'RATING_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
-> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **SDK type:** `RatingMatrixQuestion` — `fetchSurvey/types/ratingMatrix.ts`
 > **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `buttonType` | ✅ | Grid vs vertical list routing |
-| `matrixFormat` | ✅ | carousel vs standard |
-| `hasNotApplicable` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `gridLayout` | ✅ | carousel vs standard vs dropdown |
+| `hasNotApplicableOption` | ✅ | N/A column or checkbox |
 | `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
-| `labels[]` | ✅ | Anchor row above columns |
-| `columns[].color` | ✅ | RATING_MATRIX badge colors |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
+| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
+| `scaleColumns[].accentColor` | ✅ | NPS-style badge colors when numbered |
 
 ## Config Decision Tree
 
-```
-CSAT_MATRIX | RATING_MATRIX
-├── matrixFormat === 'carousel' → CsatMatrixCarousel
-├── buttonType in (dropdown, selectbox, radio) → CsatMatrixVerticalList
-│   ├── dropdown → MatrixDropdown placeholder "Select..."
-│   ├── selectbox → full-width cards #fdf2f8 selected
-│   └── else → card radio list
-└── else → CsatMatrixGrid
-    ├── emoji → getEmojiForIndex + hover scale + ring when selected
-    ├── star → opacity 0.5 unselected; filled/empty icons
-    ├── numbered → 40×40 badge; selected magenta fill
-    └── graphics → CustomSliderTrack per row (not in grid — carousel only)
-```
-
-## Grid Structure
-
-- Row label: `180px` fixed column
-- N/A column: `56px` when `hasNotApplicable`
-- Alternating row backgrounds
-- Column headers OR `labels[]` anchor row with percentage positioning
-
-## Carousel
-
-- Pink active dot expands: `20px × 8px` vs `8px` inactive
-- Column labels below cells
-- Emoji tooltip via hover state (`hoveredCell`)
-- Graphics mode: slider maps column index
-
-## Tooltips
-
-`title={col.label}` recommended on grid cells (emoji hover uses scale transform).
+Same as `CSAT_MATRIX` grid — reuse `CsatMatrixScale` component. See [04-csat.md](04-csat.md) decision tree with `type: 'RATING_MATRIX'`.
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(MatrixAnswerMap)
-// hasNotApplicable: null for N/A; undefined clears
+onSelect(MatrixRowAnswers)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] scaleColumns = columns.filter(c => c.value !== null)
-- [ ] All buttonType × matrixFormat branches
-- [ ] reverseScaleOrder on emoji/star/numbered
-- [ ] Carousel pink dot indicators
-- [ ] Vertical selectbox cards match standalone radio styling
+- [ ] Reuse CsatMatrixScale with `RATING_MATRIX` type
+- [ ] Apply accentColor on numbered badges when present
+- [ ] minLabel / maxLabel above grid when set

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

@@ -1,4 +1,4 @@
-# UI Spec: Slider Matrix (`type: 'slider_matrix'`)
+# UI Spec: Slider Matrix (`type: 'SLIDER_MATRIX'`)
 
 > **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/SliderMatrixScale.tsx`
 > **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`

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

@@ -1,4 +1,4 @@
-# UI Spec: File Upload (`type: 'file_upload'`)
+# 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`

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

@@ -1,4 +1,4 @@
-# UI Spec: Text and Media (`type: 'text_and_media'`)
+# UI Spec: Text and Media (`type: 'TEXT_AND_MEDIA'`)
 
 > **Reference:** `apps/client/src/components/Question.tsx` (inline)
 > **SDK type:** `TextAndMediaQuestion` — `fetchSurvey/types/textAndMedia.ts`
@@ -8,42 +8,42 @@
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `mediaUrl` | ✅ | Required to render media block |
-| `mediaMimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
-| `mediaTitle` | ✅ | Caption below media, centered gray text |
-| `mediaAlignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
-| `mediaSize` | ✅ | Width `%` on media container; default 100% |
+| `media?.url` | ✅ | Required to render media block |
+| `media?.mimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
+| `media?.title` | ✅ | Caption below media, centered gray text |
+| `media?.alignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
+| `media?.size` | ✅ | Width `%` on media container; default 100% |
 
 No answer input — display-only question.
 
-## Layout Anatomy
+## Media alignment anatomy
 
 ```
-[question title + description — standard shell]
-
-┌─ flex container (justify per mediaAlignment) ──────────────┐
-│  ┌─ media block (width: mediaSize%) ──────────────────┐   │
-│  │  <video controls> or <img>                          │   │
-│  │  [optional mediaTitle caption]                      │   │
-│  └─────────────────────────────────────────────────────┘   │
-└────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────┐
+│  questionText (HTML)                    │
+│  questionDescription (optional)         │
+├─────────────────────────────────────────┤
+│  [ media block — flex container ]       │
+│    alignment LEFT:   justify-start      │
+│    alignment CENTER: justify-center     │
+│    alignment RIGHT:  justify-end        │
+│    width: media.size % (default 100)    │
+│    <img> or <video> max-w-full          │
+│    caption: media.title (centered gray) │
+└─────────────────────────────────────────┘
 ```
 
-## Alignment Mapping
-
-| `mediaAlignment` | CSS |
-|------------------|-----|
-| `TOP_CENTER`, `BOTTOM_CENTER` | `justify-center` |
-| `TOP_RIGHT`, `BOTTOM_RIGHT` | `justify-end` |
-| default | `justify-start` |
-
-## Answer Mutation
-
-None — no `onSelect` payload for this type.
+Container-level media (survey chrome) is separate — see `03-ui-specs/12-survey-chrome.md`.
 
 ## Agent Checklist
 
-- [ ] Render only when `mediaUrl` is present
-- [ ] Video vs image from mime type
+- [ ] Render only when `question.media?.url` is present
+- [ ] Video vs image from `media.mimeType`
 - [ ] `max-w-full rounded-md shadow-sm` on media element
-- [ ] Optional centered caption for `mediaTitle`
+- [ ] Optional centered caption for `media.title`
+- [ ] Respect `media.alignment` (LEFT / CENTER / RIGHT) and `media.size` width %
+
+## SDK Integration Checklist (agent)
+
+- [ ] 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)

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -1,17 +1,22 @@
 # UI Spec: Survey Chrome
 
-> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`
-> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`
+> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
 
-## SurveyPage — 5-State Machine
+## SurveyPage — Phase Router
 
 | State | Condition | UI |
 |-------|-----------|-----|
 | Loading | `surveyQueryResults.isLoading` | Centered "Loading..." |
 | Error | `surveyQueryResults.error` | Red error message |
 | Empty | `!survey` | "No survey data" |
-| Submitted | `submitSurveyResults.data` | Thank you message |
-| Active | else | Questions + nav |
+| Intro | `state.phase.kind === 'intro'` | `IntroPage` + Start CTA |
+| Paused | `state.phase.kind === 'paused'` | `PausedPage` |
+| End | `state.phase.kind === 'end'` | `EndPage` |
+| Submitted | `state.phase.kind === 'submitted'` | Terminal message |
+| Expired | `state.phase.kind === 'expired'` | Terminal message |
+| Quota | `state.phase.kind === 'quota_fulfilled'` | Terminal message |
+| Active | `state.phase.kind === 'content'` | Questions + nav |
 
 ## Active Layout
 
@@ -22,7 +27,7 @@ main (max-w-4xl)
   LanguageSelector (hidden if ≤1 language)
   Questions (space-y-12)
   Submit error (if any)
-  Nav: Back (if page > 0) + Next/Submit
+  Nav: Back (if canGoBack) + Next/Submit (primaryButtonType)
 Footer
 ```
 
@@ -32,10 +37,10 @@ German when `survey.language.startsWith('de')`:
 
 | Action | EN | DE |
 |--------|----|----|
-| Back | Zurück | Back |
-| Next | Weiter | Next |
-| Submit | Absenden | Submit |
-| Submitting | Wird gesendet... | Submitting... |
+| Back | Back | Zurück |
+| Next | Next | Weiter |
+| Submit | Submit | Absenden |
+| Submitting | Submitting... | Wird gesendet... |
 
 ## Button Tokens
 
@@ -44,7 +49,7 @@ German when `survey.language.startsWith('de')`:
 
 ## ProgressBar
 
-Pink fill bar, `300ms` width transition on `progressPercentage`.
+Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`).
 
 ## LanguageSelector
 
@@ -53,8 +58,9 @@ Pink fill bar, `300ms` width transition on `progressPercentage`.
 
 ## Agent Checklist
 
-- [ ] All 5 states implemented
-- [ ] `onAction({ type: 'CHANGE' })` wired per question
-- [ ] PREVIOUS / NEXT actions on nav buttons
+- [ ] All phase branches implemented
+- [ ] `onAction({ type: 'START' })` on intro
+- [ ] `onAction({ type: 'CHANGE' })` wired per question with `allAnswers` / `allQuestions`
+- [ ] Back uses `state.canGoBack`; primary uses `state.primaryButtonType`
 - [ ] ProgressBar receives `state.progressPercentage`
 - [ ] Header/Footer on every state branch

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -0,0 +1,73 @@
+# UI Spec: Heatmap (`type: 'HEATMAP'`)
+
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/HeatmapScale.tsx`
+> **SDK type:** `HeatmapQuestion` — `fetchSurvey/types/heatmap.ts`
+> **Component blueprint:** `01-components/17-heatmap-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `questionText` | ✅ (shell) | Bold title + required asterisk |
+| `questionDescription` | ✅ (shell) | Instruction text below title |
+| `required` | ✅ (shell + SDK) | Asterisk + validation on NEXT |
+| `imageUrl` | ✅ | Center-aligned interactive image |
+| `maxClicksAllowed` | ✅ | Footer hint count; blocks new clicks at limit |
+| `regions` | ❌ (respondent UI) | Logic only — not rendered on survey |
+
+## Layout Anatomy
+
+```
+[Question shell: title *, description]
+[Heatmap container — relative, inline-block, max-width 100%]
+  [<img> — object-contain, display block, crosshair cursor]
+  [Spot overlay — absolute inset-0, pointer-events-none]
+    [Orange circle markers at normalized x/y positions]
+[Footer hint — info icon + max spots text]
+[Validation error — from Question shell]
+```
+
+## Spot Marker Visual Spec
+
+| Property | Value |
+|----------|-------|
+| Shape | Circle |
+| Diameter | 16px |
+| Fill | `#F97316` |
+| Border | 2px solid `#FFFFFF` |
+| Shadow | `0 1px 3px rgba(0,0,0,0.25)` |
+| Position | `left: x * 100%`, `top: y * 100%`, `transform: translate(-50%, -50%)` |
+
+## Interactive States
+
+| State | Behavior |
+|-------|----------|
+| Image loading | Spinner overlay; clicks disabled |
+| Ready | `cursor: crosshair` on image |
+| At max clicks | Block new adds; allow remove |
+| Removing last spot | `onSelect(undefined)` |
+
+## Footer Hint Text
+
+```
+ⓘ You can select up to {maxClicksAllowed} spot(s). To change your selection, simply click on the same spot again to remove it.
+```
+
+Use singular "spot" when `maxClicksAllowed === 1`.
+
+## Answer Mutation
+
+```typescript
+onSelect(HeatmapAnswer | undefined)
+// HeatmapAnswer = Array<{ id: string; x: number; y: number }>
+// x, y normalized 0–1 relative to rendered image bounds
+```
+
+## Agent Checklist
+
+- [ ] Click handler on `<img>` element (not overlay) for precise coordinates
+- [ ] `inline-block` wrapper so spots align with image bounds
+- [ ] Toggle-remove within 14px hit radius
+- [ ] Wait for `onLoad` before accepting clicks
+- [ ] Percentage-positioned spots (survives resize)
+- [ ] Do NOT render region overlays on respondent UI

package/templates/docs/03-ui-specs/14-rank-order.md

@@ -0,0 +1,59 @@
+# Rank Order UI Spec (`RANK_ORDER`)
+
+> **Reference:** `02-reference/question-types/13-rank-order.md`
+> **Blueprint:** `01-components/18-rank-order-scale.md`
+
+## Interaction Modes
+
+### Dropdown (`interactionMode: 'dropdown'`)
+
+| Element | Behavior |
+|---------|----------|
+| Rank select | `-` (unassigned) or `1..N` per option row |
+| Duplicate ranks | Selecting rank R on option A clears R from any other option |
+| Layout | Rank select on left, option content on right |
+
+### Drag and Drop (`interactionMode: 'dragAndDrop'`)
+
+| Element | Behavior |
+|---------|----------|
+| Drag handle | Six-dot grip on left; pointer + keyboard sensors |
+| Rank badge | Circular badge showing 1-based position |
+| Reorder | List order determines rank; smooth transform during drag |
+| Up/Down buttons | Keyboard fallback on right side of each row |
+
+## Option Display Variants
+
+| `optionDisplay` | Render |
+|-----------------|--------|
+| `textOnly` | Full-width text label only |
+| `imageOnly` | Large square thumbnail only (no label) |
+| `textAndImage` | Thumbnail + text label side by side |
+
+Use `dangerouslySetInnerHTML` for option labels (HTML from builder).
+
+## Validation UX
+
+- Required + `requireRankAll`: every visible option must have a unique rank from 1..N
+- Required + not `requireRankAll`: at least one visible option ranked
+- SDK surfaces `validationError` on the question shell — show the standard error banner
+
+## Styling
+
+Match MCQ card styling:
+
+- Border: `#e5e5e5` default, `#e20074` when actively ranked (optional highlight)
+- Background hover: `hover:bg-gray-50/50`
+- Rank badge: `#fdf2f8` background, `#e20074` text
+
+## Accessibility
+
+- Each rank select: `aria-label="Rank for {option label}"`
+- Drag handle: `aria-label="Drag to reorder {option label}"`
+- Up/Down: disabled on first/last item
+
+## Do Not
+
+- Store ranks in local component state without syncing to `onSelect`
+- Submit option labels — submit rank numbers via SDK formatter only
+- Hardcode logic operators in the client — all conditions are SDK-evaluated

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

@@ -1,7 +1,7 @@
 # UI Specifications — Reference Implementation Guide
 
-> **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx). The monorepo path `apps/client/src/components/` is **not** available in client projects.
-> **For monorepo devs:** cross-check against [`apps/client/src/components/`](../../../../../../apps/client/src/components/).
+> **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx).
+> **For monorepo devs:** Reference client at `apps/client/src/components/` aligns with SDK types — trust `03-ui-specs/`, `templates/Question.tsx`, and exported types.
 > Read the spec for **each question type present** in the fetched survey before writing React code.
 
 ## How to Read a UI Spec
@@ -38,14 +38,14 @@ Each file in this folder follows the same structure:
 | Spec file | Reference component | `question.type` |
 |-----------|---------------------|-----------------|
 | [00-question-shell.md](00-question-shell.md) | `Question.tsx` | All (wrapper) |
-| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `rating` |
-| [02-radio.md](02-radio.md) | `Question.tsx` inline | `radio` |
-| [03-text.md](03-text.md) | `Question.tsx` inline | `text` |
-| [04-csat.md](04-csat.md) | `CsatScale.tsx` | `csat` |
-| [05-rating-scale.md](05-rating-scale.md) | *(gap — reuse CsatScale patterns)* | `rating_scale` |
-| [06-slider.md](06-slider.md) | *(gap — reuse CustomSliderTrack)* | `slider` |
-| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `matrix` + CFM |
-| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | CSAT/RATING matrix |
+| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `nps` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `mcq` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `text_input` |
+| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `csat` |
+| [05-rating-scale.md](05-rating-scale.md) | `RatingScale.tsx` | `star_rating` |
+| [06-slider.md](06-slider.md) | `CustomSliderTrack.tsx` | `slider` |
+| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `cfm_matrix` |
+| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | `rating_matrix` |
 | [09-slider-matrix.md](09-slider-matrix.md) | `SliderMatrixScale.tsx` | `slider_matrix` |
 | [10-file-upload.md](10-file-upload.md) | `FileUploadScale.tsx` | `file_upload` |
 | [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `text_and_media` |
@@ -55,7 +55,7 @@ Each file in this folder follows the same structure:
 
 ## NPS Traffic-Light Colors
 
-Use `option.color` from SDK — never invent colors:
+Use accent colors from SDK options — never invent colors for NPS:
 
 | Value | Hex |
 |-------|-----|
@@ -73,8 +73,8 @@ Use `option.color` from SDK — never invent colors:
 
 ## When to Read
 
-After Phase 3 in [`index.md`](../index.md), for each question in `state.currentQuestions`:
+After Phase 3 in [`index.md`](../index.md), for each question in the fetched survey:
 
 1. Read [`02-reference/question-types/`](../02-reference/question-types/) for data shape
-2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `uiSpecs`)
+2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `questionTypes.{type}.uiSpec`)
 3. Cross-check [`config-field-index.md`](../02-reference/config-field-index.md)

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -23,7 +23,7 @@
 | `disabled` | Gray theme, opacity 0.5, no interaction |
 | `displayValues` | Reserved — tooltip always shows on hover/drag in client |
 | `hasSelectedValue` | Reserved |
-| `sliderType: 'graphics'` | Emoji thumb via `getEmojiForIndex` |
+| `sliderType: 'graphics'` | Emoji thumb via client-side react-icons |
 | `ticks` | Discrete tick count + emoji index scale |
 | `reverseScaleOrder` | Flip emoji index calculation |
 
@@ -41,7 +41,7 @@
 ```typescript
 const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
 const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
-getEmojiForIndex(displayIdx, ticks || 10)
+// Map displayIdx to react-icons emoji — proportional mapping is client-implemented (not an SDK export)
 ```
 
 ## Agent Checklist

package/templates/docs/03-ui-specs/shared/matrix-dropdown.md

@@ -30,6 +30,11 @@ if (val === null) {
 // When null selected, non-null options disabled
 ```
 
+## Props
+
+- `options: ScaleColumn[]` — matrix scale columns (`id`, `label`)
+- `value` / `onChange` — stored values use `matrixColumnStoredValue(col)` → column **`id`**
+
 ## Agent Checklist
 
 - [ ] Click-outside closes panel