@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

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/01-components/19-survey-sticky-chrome.md

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

package/templates/docs/01-components/README.md

@@ -15,8 +15,7 @@ SurveyPage (phase router)
    ├── IntroPage / PausedPage / EndPage (special phases)
    │
    └── SurveyContent (phase.kind === 'content')
-         ├── Header
-         ├── ProgressBar
+         ├── SurveyStickyChrome (sticky Header + ProgressBar)
          ├── LanguageSelector
          ├── Question × N (dispatcher)
          ├── Back / Next|Submit nav
@@ -62,6 +61,7 @@ Shared: `CustomSliderTrack`, `MatrixDropdown`
 | `09-custom-slider-track.md` | `CustomSliderTrack` |
 | `10-header-footer.md` | `Header` & `Footer` |
 | `11-progress-bar.md` | `ProgressBar` |
+| `19-survey-sticky-chrome.md` | `SurveyStickyChrome` (sticky Header + ProgressBar) |
 | `12-language-selector.md` | `LanguageSelector` |
 | `13-matrix-dropdown.md` | `MatrixDropdown` |
 | `14-intro-page.md` | `IntroPage` |

package/templates/docs/02-reference/question-types/10-slider-matrix.md

@@ -2,50 +2,62 @@
 
 > **Type**: `'SLIDER_MATRIX'` | **API Source**: `SLIDER_MATRIX`
 > **Mapper**: `sliderMatrixMapper.ts` | **Component**: `SliderMatrixScale`
+> **Portable template**: [`templates/SliderMatrixScale.tsx`](../../templates/SliderMatrixScale.tsx)
 
 ## TypeScript Type
 
 ```typescript
-type SliderMatrixQuestion = QuestionBase & {
+type SliderMatrixQuestion = {
   type: 'SLIDER_MATRIX';
-  rows: SliderMatrixRow[];       // Each row has independent slider config
-  labels?: string[];             // Anchor labels above track
-  ticks?: number;                // Number of tick marks (default 10)
-  tickValues?: TickValue[];      // Pre-calculated tick values with colors
-  enableInputBox?: boolean;
+  id: string;
+  questionText: string;
+  questionDescription?: string;
+  required: boolean;
+  questionNumber?: number;
+  statementRows: SliderMatrixStatementRow[];
+  scaleAnchorLabels?: string[];
+  ticks: {
+    count: number;
+    marks: { tickPosition: number; tickLabel: string }[];
+  };
+  enableInputBox: boolean;
   displayValues?: boolean;
-  enableNotApplicable?: boolean;
-  sliderType?: 'graphics';       // Emoji thumb slider
+  hasNotApplicableOption: boolean;
+  sliderStyle?: 'standard' | 'graphics';
 };
 
-type SliderMatrixRow = MatrixRow & {
-  min: number; max: number; step: number; defaultValue?: number;
+type SliderMatrixStatementRow = StatementRow & {
+  min: number;
+  max: number;
+  step: number;
+  defaultValue?: number;
 };
-
-type TickValue = { value: number; label: string; color: string; };
 ```
 
 ## Answer Shape: `MatrixRowAnswers`
+
 ```typescript
-{ "row1_id": 75, "row2_id": 30, "row3_id": null }
-// number = slider position, null = N/A
+{ "486d2930-4b96-4ccd-abf7-19fe0fc63f57": 5, "4fba0abf-...": "N/A" }
+// number = slider value; 'N/A' = not applicable (string, not null)
 ```
 
+Skip logic field `SLIDER` uses values like `"rowId_tickValue"` (e.g. `"486d2930-..._5"`).
+
 ## Rendering Guidance
-- Each row: row label + independent range slider
-- If `sliderType === 'graphics'` → use `CustomSliderTrack` (emoji thumb)
-- If `tickValues` available → render tick marks with labels and colors
-- If `enableInputBox` → show numeric input alongside slider
-- If `enableNotApplicable` → add N/A checkbox per row
-- `onSelect` receives the full `MatrixRowAnswers` with all row values
+
+- Copy portable `SliderMatrixScale` — always uses `CustomSliderTrack` per row
+- Shared header: colored badges from `ticks.marks` via `tickColorFromIndex`
+- Optional `scaleAnchorLabels` above tick badges
+- `sliderStyle === 'graphics'` → emoji thumb on `CustomSliderTrack`
+- `enableInputBox` → numeric input + stepper buttons per row
+- `hasNotApplicableOption` → checkbox; value `'N/A'` disables slider
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied templates before customizing
 - [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
-- [ ] Answer stored as: `MatrixRowAnswers` — numeric slider value or `null` for N/A per row
-- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
-- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(question, answers, allQuestions, customFieldValues?)`
-- [ ] Custom fields: 4th arg on statement-row helper when logic references CRM fields
-- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows) variants ✓ numbering ✓
-- [ ] Performance: debounce drag events if partial save enabled; one slider per visible row
+- [ ] Answer stored as: `MatrixRowAnswers` — number or `'N/A'` per row
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
+- [ ] Statement text in 25% row column via `dangerouslySetInnerHTML`
 - [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../../00-integration/question-type-sdk-matrix.md#slider_matrix)

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/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

@@ -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
 
@@ -36,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

@@ -2,44 +2,114 @@
 
 > **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
+- [ ] Use `selectionMode`, not `isMultiSelect`
+- [ ] Full-width card options; custom circular radio / checkbox indicators
+- [ ] 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)
 
-## SDK Integration Checklist (agent)
+## Wizard customization (Phase 5 — required)
 
-- [ ] Visibility helper: `getVisibleMcqOptionsForAnswers`
-- [ ] Store `option.id` — never option label text
-- [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../00-integration/question-type-sdk-matrix.md#mcq)
+> 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)`