@explorer02/cfm-survey-sdk 0.1.9 → 0.2.0

package/package.json

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

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,5 +1,7 @@
 # Question Dispatcher Architectural Blueprint
 
+> **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
+> **Reference implementation:** `apps/client/src/components/Question.tsx`
 > **Target Component**: `Question`
 > **Role**: Wrapper card component that routes to the correct scale component based on `question.type`.
 

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

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
 

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

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

@@ -0,0 +1,57 @@
+# UI Spec: Radio MCQ (`type: 'radio'`)
+
+> **Reference:** `apps/client/src/components/Question.tsx` (inline)
+> **SDK type:** `RadioQuestion` — `fetchSurvey/types/radio.ts`
+> **Component blueprint:** `01-components/02-question.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `options[]` | ✅ | One card per option |
+| `options[].label` | ✅ | HTML via `dangerouslySetInnerHTML` |
+| `options[].value` | ✅ | Selection value; `null` → empty string on input |
+| `isMultiSelect` | ❌ | SDK supports; client is single-select only |
+
+## Layout Anatomy
+
+```
+┌─ label (full-width card) ─────────────────────────────────────┐
+│  (●)  Option label HTML                                      │  selected
+└───────────────────────────────────────────────────────────────┘
+┌─ label ───────────────────────────────────────────────────────┐
+│  (○)  Option label HTML                                      │  unselected
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Interactive States
+
+| State | Border | Background | Radio |
+|-------|--------|------------|-------|
+| Unselected | `#e5e5e5` | `white` | `border-gray-400`, empty |
+| Unselected hover | `#e5e5e5` | `hover:bg-gray-50/50` | — |
+| Selected | `#e20074` | `#fdf2f8` | `border-2 border-[#e20074]` + inner dot `h-2.5 w-2.5 bg-[#e20074]` |
+
+## Structure
+
+```tsx
+<label className="flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer">
+  <input type="radio" name={question.id} className="sr-only" />
+  <div className="h-5 w-5 rounded-full border ..."> {/* custom radio */} </div>
+  <span dangerouslySetInnerHTML={{ __html: option.label }} />
+</label>
+```
+
+## Answer Mutation
+
+```typescript
+onSelect(option.value) // string | number
+```
+
+## 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 (SDK gap in reference)

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

@@ -0,0 +1,51 @@
+# UI Spec: Text Field (`type: 'text'`)
+
+> **Reference:** `apps/client/src/components/Question.tsx` (inline)
+> **SDK type:** `TextQuestion` — `fetchSurvey/types/text.ts`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `placeholder` | ✅ | Textarea placeholder; default `'Type your response here...'` |
+| `maxCharacterCount` | ✅ | Counter uses this; default 1000 |
+| `inputVariant: 'long'` | ✅ | Always textarea (4 rows) in reference |
+| `inputVariant: 'short'` | ❌ | Should render single-line `<input>` when SDK sends `'short'` |
+
+## Layout Anatomy
+
+```
+┌─ textarea (w-full rounded-[4px] border border-gray-300 p-4) ──┐
+│  placeholder text                                               │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+                                    N Zeichen verbleiben.  ← counter
+```
+
+## Interactive States
+
+| State | Style |
+|-------|-------|
+| Default | `border-gray-300` |
+| Focus | `focus:border-[#e20074] focus:ring-1 focus:ring-[#e20074]` |
+
+## Character Counter
+
+```typescript
+remaining = maxCharacterCount ?? 1000 - selectedValue.length
+// Display: "{remaining} Zeichen verbleiben." (German in reference client)
+// Agents: use survey language for i18n
+```
+
+## Answer Mutation
+
+```typescript
+onSelect(string) // onChange from textarea
+```
+
+## Agent Checklist
+
+- [ ] Textarea with 4 rows for long variant
+- [ ] Character counter bottom-right
+- [ ] Magenta focus ring
+- [ ] Implement `inputVariant: 'short'` as single-line input when present