@explorer02/cfm-survey-sdk 0.1.8 → 0.2.0

package/templates/docs/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 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/{03-client-components → 01-components}/README.md

@@ -1,7 +1,7 @@
 # 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).
+> This folder documents props, `onSelect` wiring, and dispatcher architecture.
 
 ## Component Architecture
 
@@ -40,7 +40,7 @@ SurveyPage (Top-level orchestrator)
 
 ## The `Question` Dispatcher
 
-The `Question` component (`apps/client/src/components/Question.tsx`) is the heart of the rendering engine. It receives a `SurveyQuestion` union type and switches on `question.type` (and `question.subType` for matrices) to render the correct specialized scale component.
+The `Question` component is the heart of the rendering engine. It receives a `SurveyQuestion` union type and switches on `question.type` (and `question.subType` for matrices) to render the correct specialized scale component.
 
 See `02-question.md` for details on the dispatcher logic.
 

package/templates/docs/02-question-types/01-rating.md

@@ -21,14 +21,6 @@ type RatingQuestion = QuestionBase & {
 ## Answer Shape: `number`
 Example: `7` (the selected badge value)
 
-## Options Auto-Generation
-If the API provides no explicit options, the SDK generates 0-10:
-```typescript
-Array.from({ length: 11 }, (_, i) => ({
-  id: String(i), label: String(i), value: i, color: getColor(i)
-}));
-```
-
 ## NPS Traffic-Light Colors
 ```
 0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)

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/question-types/01-rating.md

@@ -0,0 +1,52 @@
+# Rating Question (NPS 0-10)
+
+> **Type**: `'rating'` | **API Source**: `SCALE` with `SCALE_TYPE=TEN_POINT` or `NPS_SCALE`
+> **Mapper**: `ratingMapper.ts` | **Component**: `RatingScale`
+
+## TypeScript Type
+
+```typescript
+type RatingQuestion = QuestionBase & {
+  type: 'rating';
+  options: SurveyOption[];       // 0-10 with NPS traffic-light colors
+  minLabel?: string;             // Left label (e.g. "Not Likely")
+  midLabel?: string;             // Middle label (e.g. "Neutral")
+  maxLabel?: string;             // Right label (e.g. "Extremely Likely")
+  midLabelIndex?: number;        // Fractional position for mid-label CSS
+  reverseScaleOrder?: boolean;   // Render high→low
+  buttonVariant?: 'radio' | 'numbered' | 'emoji';
+};
+```
+
+## Answer Shape: `number`
+Example: `7` (the selected badge value)
+
+## Options Auto-Generation
+If the API provides no explicit options, the SDK generates 0-10:
+```typescript
+Array.from({ length: 11 }, (_, i) => ({
+  id: String(i), label: String(i), value: i, color: getColor(i)
+}));
+```
+
+## NPS Traffic-Light Colors
+```
+0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)
+1: #e4251b           4: #f7b200            7: #9fca00 (lime)
+2: #ec610a           5: #fcd900            8: #6bb300 (green)
+                                            9: #339a00
+                                            10: #008000
+```
+
+## Mid-Label Positioning
+```typescript
+// CSS left percentage for mid-label
+const left = (midLabelIndex / (options.length - 1)) * 100;
+// For 11-point scale: midLabelIndex defaults to 7.5
+```
+
+## Rendering Guidance
+- Display as horizontal row of numbered badge buttons
+- Each badge uses `option.color` as background
+- Selected badge: emphasized border/scale, all others dimmed
+- Labels positioned: minLabel (left), midLabel (calculated %), maxLabel (right)

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

@@ -0,0 +1,71 @@
+# Question Types Reference
+
+> Read **on demand** — only for types present in the fetched survey.
+> UI implementation: `01-components/`. Routing table: `02-reference/routing-table.md`.
+
+## Discriminated Union
+
+```typescript
+type SurveyQuestion =
+  | RatingQuestion        // 'rating'
+  | RadioQuestion         // 'radio'
+  | TextQuestion          // 'text'
+  | CsatQuestion          // 'csat'
+  | RatingScaleQuestion   // 'rating_scale'
+  | SliderQuestion        // 'slider'
+  | MatrixQuestion        // 'matrix' (check subType)
+  | RatingMatrixQuestion  // 'rating_matrix'
+  | SliderMatrixQuestion  // 'slider_matrix'
+  | FileUploadQuestion    // 'file_upload'
+  | TextAndMediaQuestion; // 'text_and_media'
+```
+
+## Shared `QuestionBase` Properties
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `id` | `string` | **MUST** be DOM `id` on wrapper |
+| `text` | `string` | HTML — use `dangerouslySetInnerHTML` |
+| `description` | `string?` | HTML |
+| `required` | `boolean?` | |
+| `requiredErrorMessage` | `string?` | Custom validation message |
+| `questionNumber` | `number?` | 1-indexed |
+
+---
+
+## radio {#radio}
+
+- **Type:** `RadioQuestion` — `type: 'radio'`
+- **Answer:** `string | number` (option id or value)
+- **UI:** Inline MCQ radio cards in `Question.tsx` — see `01-components/02-question.md`
+- **No separate reference doc needed**
+
+## text {#text}
+
+- **Type:** `TextQuestion` — `type: 'text'`
+- **Answer:** `string`
+- **UI:** Inline `<textarea>` or `<input>` in `Question.tsx`
+- **No separate reference doc needed**
+
+## text_and_media {#text_and_media}
+
+- **Type:** `TextAndMediaQuestion` — `type: 'text_and_media'`
+- **Answer:** none — display-only, skipped in validation and submission
+- **UI:** Inline `<video>` or `<img>` from `question.mediaUrl` — no scale component
+- **No separate reference doc needed**
+
+---
+
+## Detailed Reference Docs
+
+| File | Type | When to read |
+|------|------|--------------|
+| `01-rating.md` | `rating` | NPS / numeric scales |
+| `04-csat.md` | `csat` | CSAT emoji/star (≤5 options) |
+| `05-rating-scale.md` | `rating_scale` | Star/emoji rating |
+| `06-slider.md` | `slider` | Single range slider |
+| `07-matrix-cfm.md` | `matrix` + `CFM_MATRIX` | Likert text grid |
+| `08-matrix-csat.md` | `matrix` + CSAT/RATING | Satisfaction grid |
+| `09-matrix-rating.md` | `rating_matrix` | NPS-style grid |
+| `10-slider-matrix.md` | `slider_matrix` | Slider grid |
+| `11-file-upload.md` | `file_upload` | File attachments |

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

@@ -0,0 +1,37 @@
+# Question Type → Component Routing
+
+> 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 | 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
+
+| Component | Blueprint |
+|-----------|-----------|
+| `SurveyPage` | `01-components/01-survey-page.md` |
+| `Question` | `01-components/02-question.md` |
+| `RatingScale` | `01-components/03-rating-scale.md` |
+| `CsatScale` | `01-components/04-csat-scale.md` |
+| `CsatMatrixScale` | `01-components/05-csat-matrix-scale.md` |
+| `LikertMatrixScale` | `01-components/06-likert-matrix-scale.md` |
+| `SliderMatrixScale` | `01-components/07-slider-matrix-scale.md` |
+| `FileUploadScale` | `01-components/08-file-upload-scale.md` |
+| `CustomSliderTrack` | `01-components/09-custom-slider-track.md` |
+| `Header` / `Footer` | `01-components/10-header-footer.md` |
+| `ProgressBar` | `01-components/11-progress-bar.md` |
+| `LanguageSelector` | `01-components/12-language-selector.md` |
+| `MatrixDropdown` | `01-components/13-matrix-dropdown.md` |

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -0,0 +1,89 @@
+# UI Spec: Question Shell (`Question.tsx`)
+
+> **Reference:** `apps/client/src/components/Question.tsx`
+> **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
+> **Component blueprint:** `01-components/02-question.md`
+
+## Config Inventory (QuestionBase)
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `id` | ✅ | `section id={question.id}` — required for scroll-to-error |
+| `text` | ✅ | Heading via `dangerouslySetInnerHTML` |
+| `description` | ✅ | Optional HTML block below title |
+| `required` | ✅ | Red `*` after title (`text-red-500`) |
+| `requiredErrorMessage` | ✅ | Shown via SDK validation in error banner |
+| `questionNumber` | ❌ | Not rendered in reference client |
+| `containerMediaUrl` | ❌ | Not rendered on generic questions |
+
+## Layout Anatomy
+
+```
+┌─ section (rounded-xl border border-gray-200 bg-white p-6 shadow-sm) ─────┐
+│  h2: question.text (HTML) + red * if required                           │
+│  [optional description HTML]                                            │
+│  ┌─ type-specific scale (see per-type specs) ─────────────────────┐   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│  [validation error banner if validationError prop]                      │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Dispatcher Routing
+
+| `question.type` | Condition | Component |
+|-----------------|-----------|-----------|
+| `rating` | — | `RatingScale` + label row in Question |
+| `radio` | — | Inline card radios in Question |
+| `text` | — | Inline textarea in Question |
+| `csat` | — | `CsatScale` + min/max labels in Question |
+| `matrix` | `CSAT_MATRIX` \| `RATING_MATRIX` | `CsatMatrixScale` |
+| `matrix` | `CFM_MATRIX` | `LikertMatrixScale` |
+| `slider_matrix` | — | `SliderMatrixScale` |
+| `file_upload` | — | `FileUploadScale` |
+| `text_and_media` | `mediaUrl` present | Inline media in Question |
+| `slider` | — | ❌ Not routed — see `06-slider.md` |
+| `rating_scale` | — | ❌ Not routed — see `05-rating-scale.md` |
+
+## Label Positioning (rating)
+
+Rendered in Question before `RatingScale`:
+
+```tsx
+// midLabel CSS left:
+left: `${(midLabelIndex / (options.length - 1)) * 100}%`
+// with -translate-x-1/2 for centering
+```
+
+minLabel: `absolute left-0`, maxLabel: `absolute right-0`, container `relative h-6 text-xs font-semibold text-gray-500`.
+
+## Label Positioning (csat)
+
+minLabel / maxLabel: `flex justify-between text-xs font-semibold text-gray-500` above `CsatScale`.
+
+## Validation Error Banner
+
+```tsx
+className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4"
+// text: text-[13px] font-bold text-gray-900
+```
+
+## Props Contract
+
+```typescript
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  onSelect: (value: AnswerValue) => void;
+};
+```
+
+Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.
+
+## Agent Checklist
+
+- [ ] `id={question.id}` on outermost `<section>`
+- [ ] HTML rendering for text and description
+- [ ] Exhaustive type switch — all 12 types handled or explicitly noted as gap
+- [ ] Validation error banner below scale
+- [ ] Rating/csat endpoint labels positioned per formulas above

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

@@ -0,0 +1,80 @@
+# UI Spec: NPS Rating (`type: 'rating'`)
+
+> **Reference:** `apps/client/src/components/RatingScale.tsx` + label row in `Question.tsx`
+> **SDK type:** `RatingQuestion` — `fetchSurvey/types/rating.ts`
+> **Component blueprint:** `01-components/03-rating-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `options[]` | ✅ | Badge row + radio row (dual layer) |
+| `options[].color` | ✅ | Badge background; fallback `#e20074` |
+| `options[].label` | ✅ | Displayed in badge |
+| `options[].value` | ✅ | Selection value |
+| `minLabel` | ✅ | Rendered in Question.tsx above scale |
+| `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 |
+
+## Layout Anatomy
+
+```
+[minLabel]              [midLabel @ %]              [maxLabel]
+┌──┬──┬──┬── ... ──┬──┐  ← Row 1: colored badges (NOT clickable)
+│0 │1 │2 │3 │ ...  │10│     grid repeat(options.length), h-5 w-5 sm:h-6 w-6
+└──┴──┴──┴── ... ──┴──┘     rounded-[3px], white bold text, option.color bg
+┌──────────────────────────────────────────────┐
+│  ○  ○  ●  ○  ...  ○                          │  ← Row 2: gray track bg-[#f2f2f2]
+└──────────────────────────────────────────────┘     h-11 sm:h-12, rounded-md
+         ↑ selected cell: inner bg-[#fbe8f3]
+           radio: border-[4px] border-[#e20074] bg-white
+```
+
+## Config Decision Tree
+
+```
+rating
+└── RatingScale (always dual-layer in reference client)
+    ├── Row 1: display-only colored badges
+    └── Row 2: sr-only radio + custom circle per cell
+```
+
+If `buttonVariant === 'numbered'` (SDK gap): badges become clickable buttons instead — not in reference client.
+
+If `reverseScaleOrder`: reverse `options` array before mapping both rows.
+
+## Interactive States
+
+| State | Badge row | Track cell | Radio circle |
+|-------|-----------|------------|--------------|
+| Default | Full color | Transparent inner | `border-2 border-gray-300` |
+| Hover | — | `hover:bg-gray-200/40` | — |
+| Selected | Unchanged | `bg-[#fbe8f3]` | `border-[4px] border-[#e20074]` |
+
+## Tooltips
+
+Recommended: `title={option.label}` on each track `<label>`. Not in reference client yet.
+
+## Answer Mutation
+
+```typescript
+onSelect(option.value) // number
+// → onAction CHANGE { questionId, value: number }
+```
+
+## Accessibility
+
+- `role="radiogroup"` on wrapper
+- Native `<input type="radio" className="sr-only">` per cell
+- `name={questionId}` groups radios
+
+## Agent Checklist
+
+- [ ] Two-row grid with `gridTemplateColumns: repeat(options.length, 1fr)`
+- [ ] Badges use `option.color`, not hardcoded NPS colors unless option lacks color
+- [ ] Only track row is clickable
+- [ ] min/mid/max labels in Question wrapper with midLabelIndex formula
+- [ ] Selected state: pink inner track + thick magenta radio ring