@explorer02/cfm-survey-sdk 0.1.9 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer02/cfm-survey-sdk",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/postinstall.js

@@ -53,8 +53,13 @@ Do NOT run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
 RULE 2 — DEEP CONTEXT BEFORE CODE:
 Before writing React code, read EVERY file in `node_modules/@explorer02/cfm-survey-sdk/docs/01-components/`.
+Read `docs/00-integration/component-checklist.md` and `docs/03-ui-specs/` for EVERY question type in the fetched survey (blocking for matrix, slider_matrix, file_upload).
+Copy `docs/templates/Question.tsx` as your Question dispatcher — do NOT use stub/default fallback branches.
 Copy `node_modules/@explorer02/cfm-survey-sdk/docs/templates/implementation_plan.md` to project root and fill it in.
 
+RULE 2b — NO STUB PLACEHOLDERS:
+Never render "not yet implemented" or similar placeholder text. If a type is in the survey, implement its scale component.
+
 RULE 3 — AUTO-PROCEED:
 After the implementation plan is complete, proceed to build without waiting for approval.
 The workflow requires 3 client inputs: Prompt/Mockup, Instance ID (JWT), Deploy Confirmation.

package/templates/AGENT.md

@@ -21,11 +21,13 @@ Import from whatever appears in `package.json`:
 | 1 | Scaffold React app — `00-integration/setup.md` |
 | 2 | Ask client for instanceId JWT |
 | 3 | Read `useSurveySDK.md` — hook contract |
-| 4 | Read all `01-components/`; copy `templates/implementation_plan.md` → project root |
-| 5 | Build UI per blueprints + `constraints.md` |
+| 4 | Read all `01-components/`; inventory survey types; read `03-ui-specs/` per type; copy `templates/Question.tsx` + `implementation_plan.md` |
+| 5 | Build UI — create all scale files from `component-checklist.md`; no stub placeholders |
 | 6 | Verify build checklist |
 | 7 | Deploy on client confirmation |
 
 **Do NOT** run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
 
+**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `docs/templates/Question.tsx` and create all required scale components.
+
 Follow the master index strictly. Do not guess SDK internals. Do not import from `/src/` paths.

package/templates/docs/00-integration/component-checklist.md

@@ -0,0 +1,61 @@
+# Required Component Files Checklist
+
+> **Blocking gate before Phase 5 (BUILD).** After fetching the survey with `instanceId`, list every `(type, subType)` pair and ensure all required files exist.
+
+## Step 1: Inventory Question Types
+
+From `survey.pages`, collect unique combinations:
+
+| questionId | type | subType (if matrix) |
+|------------|------|---------------------|
+| | | |
+
+## Step 2: Create Required Files
+
+| If survey contains | Agent MUST create before `npm run build` | UI spec |
+|--------------------|------------------------------------------|---------|
+| `rating` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |
+| `csat` | `CsatScale.tsx` | `03-ui-specs/04-csat.md` |
+| `rating_scale` | Reuse `CsatScale.tsx` or dedicated component | `03-ui-specs/05-rating-scale.md` |
+| `slider` | `CustomSliderTrack.tsx` + wrapper | `03-ui-specs/06-slider.md` |
+| `matrix` + `CFM_MATRIX` | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` | `03-ui-specs/07-matrix-cfm.md` |
+| `matrix` + `CSAT_MATRIX` or `RATING_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `slider_matrix` | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/09-slider-matrix.md` |
+| `file_upload` | `FileUploadScale.tsx` | `03-ui-specs/10-file-upload.md` |
+| `radio`, `text`, `text_and_media` | Inline in `Question.tsx` | `03-ui-specs/02-radio.md`, `03-text.md`, `11-text-and-media.md` |
+
+Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Question.tsx).
+
+## Matrix subType Routing (CRITICAL)
+
+`question.type === 'matrix'` alone renders **nothing**. You MUST branch on `subType`:
+
+```tsx
+{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && (
+  <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+
+{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && (
+  <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
+)}
+```
+
+## Shared Primitives
+
+| File | Used by |
+|------|---------|
+| `CustomSliderTrack.tsx` | `slider_matrix`, CSAT matrix `graphics`, standalone `slider` |
+| `MatrixDropdown.tsx` | `LikertMatrixScale`, `CsatMatrixScale` vertical/dropdown modes |
+
+Specs: `03-ui-specs/shared/custom-slider-track.md`, `03-ui-specs/shared/matrix-dropdown.md`
+
+## Step 3: Verify Before Build
+
+- [ ] Every type in the survey inventory has a matching component file
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` with all branches wired
+- [ ] No `default` fallback rendering stub text (see `constraints.md` §7)
+- [ ] Grep project: `not yet implemented` → **zero matches**
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```

package/templates/docs/00-integration/constraints.md

@@ -40,6 +40,22 @@ Survey UI files importing the SDK must be client components. Next.js: `'use clie
 
 Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infinite re-fetch.
 
+## 7. No Stub Placeholders (CRITICAL)
+
+**FORBIDDEN** in `Question.tsx` or any scale component:
+
+- Text like `"not yet implemented"`, `"coming soon"`, or any placeholder error message
+- `default` / `else` branches in the dispatcher that render stub UI instead of the real component
+- Empty `<div>` where an interactive scale component should be
+
+If a question type appears in the fetched survey, its component **must** be fully implemented before shipping. Read the matching `03-ui-specs/` doc and create the required files listed in `component-checklist.md`.
+
+**Phase 6 verification:** grep the project for stub text — must return zero matches:
+
+```bash
+grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+```
+
 ---
 
 ## Troubleshooting
@@ -52,3 +68,4 @@ Define `SURVEY_PLACEHOLDERS` outside the component — inline objects cause infi
 | Validation errors but no scroll | Add `id={question.id}` to question wrapper |
 | Survey data is null, no error | Invalid/expired `instanceId` — ask client for fresh JWT |
 | CSAT emojis missing | `npm install react-icons` |
+| Grey "not yet implemented" text on questions | Copy `docs/templates/Question.tsx`; create scale components per `component-checklist.md`; route matrix by `subType` |

package/templates/docs/01-components/01-survey-page.md

@@ -1,5 +1,7 @@
 # Survey Page Orchestrator Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Reference implementation:** `apps/client/src/components/SurveyPage.tsx`
 > **Target Component**: `SurveyPage`
 > **Role**: The main entry point that wires the UI to the `useSurveySDK` hook, manages loading/error states, orchestrates pagination, and controls submission.
 

package/templates/docs/01-components/02-question.md

@@ -1,8 +1,19 @@
 # Question Dispatcher Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy verbatim, then create imported components
+> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs)
 > **Target Component**: `Question`
 > **Role**: Wrapper card component that routes to the correct scale component based on `question.type`.
 
+## Start Here (CRITICAL)
+
+1. Copy [`docs/templates/Question.tsx`](../templates/Question.tsx) into your project.
+2. Create every imported scale component — see [`component-checklist.md`](../00-integration/component-checklist.md).
+3. Read `03-ui-specs/` for each type in your fetched survey **before** editing the dispatcher.
+
+**Do NOT** write a partial skeleton with `default` fallbacks or `"not yet implemented"` messages.
+
 ## Core Responsibility
 Render a visually separated container (card) for each question. Handle rich text parsing, required asterisks, description text, and error validation messages. Most importantly, it MUST act as an exhaustive switch statement dispatching to ALL supported question types.
 
@@ -10,17 +21,34 @@ Render a visually separated container (card) for each question. Handle rich text
 
 The agent MUST handle EVERY SINGLE ONE of these `question.type` values. Failure to handle them will result in blank UI or broken surveys.
 
-1. **`rating`**: Renders `RatingScale`. This covers NPS, Stars, Emoji, and generic numeric scales.
+1. **`rating`**: Renders `RatingScale`. This covers NPS scales.
 2. **`csat`**: Renders `CsatScale`. This covers CSAT specific faces/icons.
-3. **`radio`**: Renders inline MCQ radio buttons. (Can be implemented inside this file or separately).
+3. **`radio`**: Renders inline MCQ radio buttons.
 4. **`text`**: Renders an inline `<textarea>` or `<input>`.
-5. **`matrix`**: 
+5. **`matrix`** — **requires `subType`**:
    - If `subType === 'CFM_MATRIX'`, render `LikertMatrixScale`
    - If `subType === 'CSAT_MATRIX'` or `'RATING_MATRIX'`, render `CsatMatrixScale`
+   - Routing on `type === 'matrix'` alone renders **nothing**
 6. **`slider_matrix`**: Renders `SliderMatrixScale`
 7. **`file_upload`**: Renders `FileUploadScale`
-8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. 
-   - *Note: `text_and_media` questions may NOT have user input. Do not render a scale for them.*
+8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. No answer input.
+9. **`rating_scale`**: Star/emoji scale — see `03-ui-specs/05-rating-scale.md`
+10. **`slider`**: Standalone slider — see `03-ui-specs/06-slider.md`
+
+## Forbidden Anti-Patterns
+
+```tsx
+// ❌ FORBIDDEN — never ship this
+default:
+  return <p>Question type "{question.type}" is not yet implemented in this client.</p>;
+
+// ❌ FORBIDDEN — matrix without subType
+{question.type === 'matrix' && <SomeMatrix />}
+
+// ✅ REQUIRED — matrix with subType
+{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
+{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
+```
 
 ## Container UI Structure
 
@@ -45,61 +73,20 @@ Every question MUST be wrapped in a standard HTML `<section>` to visually separa
 
 4. **Validation Error Banner**:
    - If `validationError` prop is passed, render a highly visible banner below the scale.
-   - Example: Red border-left, red background, bold text.
 
 ## Hover Tooltips & Micro-interactions
 - Focus states on text inputs MUST use the brand primary color (e.g., magenta `#e20074` for Telekom).
 - Radio button wrappers should have a subtle background hover effect (e.g., `hover:bg-pink-50`).
 
-## Example Architectural Skeleton
+## Props Contract
 
-```tsx
-<section id={question.id} className="space-y-6 rounded-xl border border-gray-200 bg-white p-6 md:p-8 shadow-sm transition-all hover:shadow-md">
-  
-  {/* HEADING */}
-  <h2 className="text-lg md:text-xl font-semibold leading-relaxed text-gray-900 flex items-start gap-1">
-    <span dangerouslySetInnerHTML={{ __html: question.text }} className="prose prose-sm max-w-none" />
-    {question.required && <span className="text-[#e20074] shrink-0">*</span>}
-  </h2>
-  
-  {/* DESCRIPTION */}
-  {question.description && (
-    <div className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" dangerouslySetInnerHTML={{ __html: question.description }} />
-  )}
-  
-  {/* DISPATCHER */}
-  <div className="pt-4">
-    {question.type === 'rating' && <RatingScale ... />}
-    {question.type === 'csat' && <CsatScale ... />}
-    {question.type === 'slider_matrix' && <SliderMatrixScale ... />}
-    {question.type === 'file_upload' && <FileUploadScale ... />}
-    {question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
-    {question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
-    
-    {question.type === 'radio' && (
-       // Inline Radio implementation
-       // Make sure to match brand hover colors!
-    )}
-    
-    {question.type === 'text' && (
-       // Inline Textarea implementation
-       // Handle character limit `question.maxCharacterCount`
-    )}
-
-    {question.type === 'text_and_media' && (
-       // Display media (image/video) based on question properties
-       // This handles CONTENT blocks.
-    )}
-  </div>
-
-  {/* ERROR BANNER */}
-  {validationError && (
-    <div className="mt-6 rounded-lg border-l-4 border-l-[#e20074] bg-red-50 p-4">
-      <p className="text-sm font-bold text-gray-900 leading-tight flex items-center gap-2">
-        <span className="text-[#e20074]">⚠</span> {validationError}
-      </p>
-    </div>
-  )}
-
-</section>
+```typescript
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  onSelect: (value: AnswerValue) => void;
+};
 ```
+
+Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.

package/templates/docs/01-components/03-rating-scale.md

@@ -1,5 +1,7 @@
 # Rating Scale Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/01-rating.md` (NPS) · `03-ui-specs/05-rating-scale.md` (star/emoji gap)
+> **Reference implementation:** `apps/client/src/components/RatingScale.tsx`
 > **Target Component**: `RatingScale`
 > **Handles**: `type: 'rating'`, `type: 'rating_scale'`
 

package/templates/docs/01-components/04-csat-scale.md

@@ -1,6 +1,8 @@
 # CSAT & Rating Architectural Blueprints
 
-> **Target Components**: `CsatScale`, `RatingScale`, `CsatMatrixScale`
+> **UI spec (authoritative):** `03-ui-specs/04-csat.md`
+> **Reference implementation:** `apps/client/src/components/CsatScale.tsx`
+> **Target Components**: `CsatScale`
 > **Handles**: `type: 'csat'`, `'rating'`, `'rating_scale'`, CSAT matrices.
 
 ## Core Responsibility

package/templates/docs/01-components/05-csat-matrix-scale.md

@@ -1,5 +1,7 @@
 # CSAT Matrix Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/08-matrix-csat-rating.md`
+> **Reference implementation:** `apps/client/src/components/CsatMatrixScale.tsx`
 > **Target Component**: `CsatMatrixScale`
 > **Handles**: `type: 'matrix'` (CSAT_MATRIX and RATING_MATRIX subTypes)
 

package/templates/docs/01-components/06-likert-matrix-scale.md

@@ -1,5 +1,7 @@
 # Likert Matrix Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/07-matrix-cfm.md`
+> **Reference implementation:** `apps/client/src/components/LikertMatrixScale.tsx`
 > **Target Component**: `LikertMatrixScale`
 > **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
 

package/templates/docs/01-components/07-slider-matrix-scale.md

@@ -1,5 +1,7 @@
 # Slider Matrix Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/09-slider-matrix.md`
+> **Reference implementation:** `apps/client/src/components/SliderMatrixScale.tsx`
 > **Target Component**: `SliderMatrixScale`
 > **Handles**: `type: 'slider_matrix'`
 

package/templates/docs/01-components/08-file-upload-scale.md

@@ -1,5 +1,7 @@
 # File Upload Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/10-file-upload.md`
+> **Reference implementation:** `apps/client/src/components/FileUploadScale.tsx`
 > **Target Component**: `FileUploadScale`
 > **Handles**: `type: 'file_upload'`
 

package/templates/docs/01-components/09-custom-slider-track.md

@@ -1,5 +1,7 @@
 # Custom Slider Track Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/shared/custom-slider-track.md`
+> **Reference implementation:** `apps/client/src/components/CustomSliderTrack.tsx`
 > **Target Component**: `CustomSliderTrack`
 > **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
 

package/templates/docs/01-components/10-header-footer.md

@@ -1,6 +1,8 @@
 # Theme & Logo Engineering Blueprint
 
-> **Target Components**: `Header`, Global Styles
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Reference implementation:** `apps/client/src/components/Header.tsx`, `Footer.tsx`
+> **Target Components**: `Header`, `Footer`
 > **Handles**: Branding, Mockup Replication
 
 ## Core Responsibility

package/templates/docs/01-components/11-progress-bar.md

@@ -1,5 +1,7 @@
 # Progress Bar
 
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Reference implementation:** `apps/client/src/components/ProgressBar.tsx`
 > **Component**: `ProgressBar`
 > **Role**: Displays completion status at the top of the survey.
 

package/templates/docs/01-components/12-language-selector.md

@@ -1,5 +1,7 @@
 # Language Selector
 
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Reference implementation:** `apps/client/src/components/LanguageSelector.tsx`
 > **Component**: `LanguageSelector`
 > **Role**: Allows the user to switch the survey language.
 

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

@@ -1,5 +1,7 @@
 # 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`
 

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

@@ -1,7 +1,9 @@
 # Client Components Overview
 
-> This folder documents the React client components that render the survey UI.
-> It explains the architecture, the dispatcher (`Question.tsx`), and all 11 individual question scale components.
+> Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md) (reference-client driven).
+> **Required files gate:** [`component-checklist.md`](../00-integration/component-checklist.md)
+> **Dispatcher template:** [`templates/Question.tsx`](../templates/Question.tsx)
+> This folder documents props, `onSelect` wiring, and dispatcher architecture.
 
 ## Component Architecture
 

package/templates/docs/02-reference/config-field-index.md

@@ -0,0 +1,158 @@
+# Config Field Index
+
+> Master map: every SDK config field → reference client file → implemented? → UI spec doc.
+> Cross-check this when building any question with non-default config.
+
+## QuestionBase (all types)
+
+| Field | Types | Client file | Implemented? | Spec doc |
+|-------|-------|-------------|--------------|----------|
+| `id` | all | Question.tsx | ✅ | 00-question-shell |
+| `text` | all | Question.tsx | ✅ | 00-question-shell |
+| `description` | all | Question.tsx | ✅ | 00-question-shell |
+| `required` | all | Question.tsx | ✅ | 00-question-shell |
+| `requiredErrorMessage` | all | Question.tsx | ✅ | 00-question-shell |
+| `questionNumber` | all | — | ❌ | 00-question-shell |
+| `containerMediaUrl` | all | — | ❌ | 00-question-shell |
+| `containerMediaMimeType` | all | — | ❌ | 00-question-shell |
+| `containerMediaAlignment` | all | — | ❌ | 00-question-shell |
+| `containerMediaSize` | all | — | ❌ | 00-question-shell |
+
+## rating
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `options[]` | SurveyOption[] | RatingScale.tsx | ✅ | 01-rating |
+| `options[].color` | hex | RatingScale.tsx | ✅ | 01-rating |
+| `minLabel` | string | Question.tsx | ✅ | 01-rating |
+| `midLabel` | string | Question.tsx | ✅ | 01-rating |
+| `maxLabel` | string | Question.tsx | ✅ | 01-rating |
+| `midLabelIndex` | number | Question.tsx | ✅ | 01-rating |
+| `reverseScaleOrder` | boolean | — | ❌ | 01-rating |
+| `buttonVariant` | radio/numbered/emoji | — | ❌ | 01-rating |
+
+## radio
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `options[]` | SurveyOption[] | Question.tsx | ✅ | 02-radio |
+| `isMultiSelect` | boolean | — | ❌ | 02-radio |
+
+## text
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `placeholder` | string | Question.tsx | ✅ | 03-text |
+| `maxCharacterCount` | number | Question.tsx | ✅ | 03-text |
+| `inputVariant` | long/short | Question.tsx | partial | 03-text |
+
+## csat
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `options[]` | SurveyOption[] | CsatScale.tsx | ✅ | 04-csat |
+| `buttonType` | emoji/star/numbered/... | CsatScale.tsx | ✅ | 04-csat |
+| `labelPosition` | top/bottom/hidden | CsatScale.tsx | ✅ | 04-csat |
+| `minLabel` / `maxLabel` | string | Question.tsx | ✅ | 04-csat |
+| `hasNotApplicable` | boolean | — | ❌ | 04-csat |
+| `reverseScaleOrder` | boolean | — | ❌ | 04-csat |
+
+## rating_scale
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `options[]` | SurveyOption[] | — | ❌ | 05-rating-scale |
+| `scaleStyle` | star/emoji | — | ❌ | 05-rating-scale |
+| `minLabel` / `midLabel` / `maxLabel` | string | — | ❌ | 05-rating-scale |
+| `midLabelIndex` | number | — | ❌ | 05-rating-scale |
+| `reverseScaleOrder` | boolean | — | ❌ | 05-rating-scale |
+
+## slider
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `min` / `max` / `step` | number | — | ❌ | 06-slider |
+| `defaultValue` | number | — | ❌ | 06-slider |
+| `minLabel` / `maxLabel` | string | — | ❌ | 06-slider |
+| `enableInputBox` | boolean | SliderMatrixScale.tsx | partial | 06-slider |
+| `displayValues` | boolean | CustomSliderTrack.tsx | partial | 06-slider, shared/custom-slider-track |
+
+## matrix (shared)
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `subType` | CFM/CSAT/RATING | Question.tsx | ✅ | 07, 08 |
+| `rows[]` | MatrixRow[] | Likert/CsatMatrix | ✅ | 07, 08 |
+| `columns[]` | MatrixColumn[] | Likert/CsatMatrix | ✅ | 07, 08 |
+| `matrixFormat` | standard/carousel/dropdown | Likert/CsatMatrix | ✅ | 07, 08 |
+| `hasNotApplicable` | boolean | Likert/CsatMatrix | ✅ | 07, 08 |
+| `reverseScaleOrder` | boolean | CsatMatrixScale | ✅ | 08 |
+| `labels[]` | string[] | Likert/CsatMatrix | ✅ | 07, 08 |
+| `buttonType` | SurveyButtonType | CsatMatrixScale | ✅ | 08 |
+
+## matrix — CFM only
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `matrixType` | likert/bipolar | LikertMatrixScale | ✅ | 07-matrix-cfm |
+| `answerType` | single/multiple | LikertMatrixScale | ✅ | 07-matrix-cfm |
+| `transposeTable` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
+| `repeatScale` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
+| `enableScale` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
+
+## slider_matrix
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `rows[].min/max/step` | number | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `labels[]` | string[] | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `ticks` | number | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `tickValues[]` | TickValue[] | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `enableInputBox` | boolean | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `displayValues` | boolean | CustomSliderTrack | ✅ | 09-slider-matrix |
+| `enableNotApplicable` | boolean | SliderMatrixScale | ✅ | 09-slider-matrix |
+| `sliderType` | graphics | SliderMatrixScale | ✅ | 09-slider-matrix |
+
+## file_upload
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `uploadMessage` | HTML string | FileUploadScale | ✅ | 10-file-upload |
+| `supportedFileFormats` | string[] | FileUploadScale | ✅ | 10-file-upload |
+| `maxFileCount` | number | FileUploadScale | ✅ | 10-file-upload |
+| `fileSizeLimit` | number (MB) | FileUploadScale | ✅ | 10-file-upload |
+| `fileSizeLimitType` | PER_FILE/IN_TOTAL | FileUploadScale | ✅ | 10-file-upload |
+
+## text_and_media
+
+| Field | Values | Client file | Implemented? | Spec doc |
+|-------|--------|-------------|--------------|----------|
+| `mediaUrl` | string | Question.tsx | ✅ | 11-text-and-media |
+| `mediaMimeType` | string | Question.tsx | ✅ | 11-text-and-media |
+| `mediaTitle` | string | Question.tsx | ✅ | 11-text-and-media |
+| `mediaAlignment` | string | Question.tsx | ✅ | 11-text-and-media |
+| `mediaSize` | number (%) | Question.tsx | ✅ | 11-text-and-media |
+
+## Implementation Gaps (no client branch yet)
+
+| Gap | SDK type/field | Extend from |
+|-----|----------------|-------------|
+| `rating_scale` dispatcher | `type: 'rating_scale'` | CsatScale star/emoji patterns |
+| `slider` dispatcher | `type: 'slider'` | CustomSliderTrack + SliderMatrixScale row |
+| `radio.isMultiSelect` | checkbox cards | 02-radio card styling |
+| `text.inputVariant: 'short'` | single-line input | 03-text focus tokens |
+| `rating.reverseScaleOrder` | reverse options array | 01-rating |
+| `rating.buttonVariant` | numbered clickable badges | 01-rating |
+| `csat.hasNotApplicable` / `reverseScaleOrder` | standalone CSAT | 04-csat, 08-matrix N/A |
+| `containerMedia*` on any type | container asset | 11-text-and-media media block |
+
+## buttonType × matrixFormat Quick Reference
+
+| buttonType | matrixFormat | Layout component | Spec |
+|------------|--------------|------------------|------|
+| (CFM default) | standard | LikertMatrixGrid | 07 |
+| (CFM default) | carousel | LikertMatrixCarousel | 07 |
+| (CFM default) | dropdown | LikertMatrixDropdown | 07 |
+| emoji/star/numbered | standard | CsatMatrixGrid | 08 |
+| emoji/star/numbered/graphics | carousel | CsatMatrixCarousel | 08 |
+| dropdown/selectbox/radio | any | CsatMatrixVerticalList | 08 |

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

@@ -1,22 +1,22 @@
 # Question Type → Component Routing
 
-> Canonical mapping. For UI implementation details, read `01-components/`. For data shapes, read `02-reference/question-types/`.
+> Canonical mapping. For **UI implementation** (config branches, tokens, states), read `03-ui-specs/`. For wiring, read `01-components/`. For data shapes, read `02-reference/question-types/`. For field audit, read `config-field-index.md`.
 
-| `question.type` | `question.subType` | Component | Answer Shape | Reference Doc |
-|-----------------|-------------------|-----------|--------------|---------------|
-| `'rating'` | — | `RatingScale` | `number` | `question-types/01-rating.md` |
-| `'radio'` | — | Inline in `Question` | `string \| number` | `question-types/README.md#radio` |
-| `'text'` | — | Inline in `Question` | `string` | `question-types/README.md#text` |
-| `'csat'` | — | `CsatScale` | `number \| null` | `question-types/04-csat.md` |
-| `'rating_scale'` | — | `RatingScale` | `number` | `question-types/05-rating-scale.md` |
-| `'slider'` | — | `CustomSliderTrack` | `number` | `question-types/06-slider.md` |
-| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` | `question-types/07-matrix-cfm.md` |
-| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` |
-| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` |
-| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/09-matrix-rating.md` |
-| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` | `question-types/10-slider-matrix.md` |
-| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` | `question-types/11-file-upload.md` |
-| `'text_and_media'` | — | Inline in `Question` | (no answer) | `question-types/README.md#text_and_media` |
+| `question.type` | `question.subType` | Component | Answer Shape | Reference Doc | UI Spec |
+|-----------------|-------------------|-----------|--------------|---------------|---------|
+| `'rating'` | — | `RatingScale` | `number` | `question-types/01-rating.md` | `03-ui-specs/01-rating.md` |
+| `'radio'` | — | Inline in `Question` | `string \| number` | `question-types/README.md#radio` | `03-ui-specs/02-radio.md` |
+| `'text'` | — | Inline in `Question` | `string` | `question-types/README.md#text` | `03-ui-specs/03-text.md` |
+| `'csat'` | — | `CsatScale` | `number \| null` | `question-types/04-csat.md` | `03-ui-specs/04-csat.md` |
+| `'rating_scale'` | — | `RatingScale` | `number` | `question-types/05-rating-scale.md` | `03-ui-specs/05-rating-scale.md` |
+| `'slider'` | — | `CustomSliderTrack` | `number` | `question-types/06-slider.md` | `03-ui-specs/06-slider.md` |
+| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` | `question-types/07-matrix-cfm.md` | `03-ui-specs/07-matrix-cfm.md` |
+| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/09-matrix-rating.md` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` | `question-types/10-slider-matrix.md` | `03-ui-specs/09-slider-matrix.md` |
+| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` | `question-types/11-file-upload.md` | `03-ui-specs/10-file-upload.md` |
+| `'text_and_media'` | — | Inline in `Question` | (no answer) | `question-types/README.md#text_and_media` | `03-ui-specs/11-text-and-media.md` |
 
 ## Component Blueprint Docs