@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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

@@ -1,22 +1,27 @@
 # CSAT Matrix Architectural Blueprint
 
-> **UI spec (authoritative):** `03-ui-specs/08-matrix-csat-rating.md`
+> **UI spec (authoritative):** `03-ui-specs/04-csat.md` (for `CSAT_MATRIX`) and `03-ui-specs/08-matrix-csat-rating.md` (for `RATING_MATRIX`)
 > **Reference implementation:** `apps/client/src/components/CsatMatrixScale.tsx`
 > **Target Component**: `CsatMatrixScale`
-> **Handles**: `type: 'matrix'` (CSAT_MATRIX and RATING_MATRIX subTypes)
+> **Handles**: `type: 'CSAT_MATRIX'` and `type: 'RATING_MATRIX'`
 
 ## Core Responsibility
+
 Render a grid where columns represent satisfaction scales (Emojis, Stars, or Rating Badges).
 
 ## Data Mapping & State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape.
-- Iterate over `question.rows`. Within each row, iterate over `question.columns`.
-- Render the correct icon/badge in the `<td>` based on `question.buttonType`.
+
+- `selectedValue`: `MatrixRowAnswers` — keys are `statementRows[].id`, values are column **`id`** (via `matrixColumnStoredValue`)
+- Iterate over `question.statementRows`. Within each row, iterate over `question.scaleColumns`.
+- Render the correct icon/badge in the `<td>` based on `question.displayStyle`.
 
 ## Configuration Matrix
+
 You MUST handle:
-- **`hasNotApplicable`**: If true, the last column might be `null`. Render a distinct UI (e.g., standard radio or gray badge) for the N/A column.
-- **`reverseScaleOrder`**: Ensure your column mapping respects this logic if implemented in the UI.
+
+- **`hasNotApplicableOption`**: If true, the last column might be `null`. Render a distinct UI for the N/A column.
+- **`reverseScaleOrder`**: Reverse column order before render when true.
+- **`gridLayout`**: `'standard'`, `'carousel'`, or `'dropdown'` — see ui-spec decision tree.
 
 ## UI/UX Bounding Box Rules (CRITICAL)
 
@@ -28,8 +33,12 @@ Matrices are difficult to read and click accurately. You MUST implement these st
 2. **The "Active Bounding Box"**:
    - For Emojis and Stars inside the matrix, do NOT just change the SVG fill.
    - The interactive wrapper inside the `<td>` MUST toggle a pink bounding box.
-   - **Selected Cell**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100 cursor-pointer`.
-   - **Unselected Cell**: `border-2 border-transparent p-2 opacity-40 hover:opacity-100 hover:scale-110 cursor-pointer`.
 
-3. **Tooltips**:
-   - Every single interactive cell MUST have `title={col.label}` so the user sees exactly what column they are in without scrolling up to the table header.
+## SDK Integration Checklist (agent)
+
+- [ ] Type literals: `QUESTION_TYPE.CSAT_MATRIX` and `QUESTION_TYPE.RATING_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` via `matrixColumnStoredValue`
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Emoji/star UI: client-side `react-icons` — not SDK exports
+- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

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

@@ -3,14 +3,14 @@
 > **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)
+> **Handles**: `type: 'CFM_MATRIX'`
 
 ## Core Responsibility
 Render a grid with text-label columns. However, this component must be highly dynamic to support complex layouts, transpositions, and long-form matrix readability.
 
 ## Data Mapping & State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape (`Record<string, string | number | null>`).
-- **Mutation**: When radio button is clicked for `row.id` and `col.value`, dispatch `onSelect({ ...selectedValue, [row.id]: col.value })`.
+- `selectedValue`: `MatrixRowAnswers` — store column **`id`** via `matrixColumnStoredValue(col)`
+- **Mutation**: When a cell is selected for `row.id`, dispatch `onSelect({ ...selectedValue, [row.id]: columnId })`
 
 ## Configuration Matrix (CRITICAL FOR PLANNING)
 
@@ -44,3 +44,12 @@ To match enterprise standards, implement the following UI strictly:
    - Every input MUST have `title={col.label}` so the user sees the semantic meaning when hovering the radio button.
 4. **Header Typography**:
    - `th` tags should be `text-xs font-semibold text-gray-500 uppercase tracking-wider p-4 border-b`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.CFM_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` via `matrixColumnStoredValue`
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Handle `gridLayout`: standard / carousel / dropdown
+- [ ] Matrix row: [`question-type-sdk-matrix.md#cfm_matrix`](../00-integration/question-type-sdk-matrix.md#cfm_matrix)

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

@@ -3,13 +3,13 @@
 > **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'`
+> **Handles**: `type: 'SLIDER_MATRIX'`
 
 ## Core Responsibility
 Render an independent range slider for every row in the matrix. Sliders must be highly visible, utilizing a "thick track" UI, dynamic fill based on the current value, and exact value badges.
 
 ## State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape.
+- `selectedValue`: Expects `MatrixRowAnswers` shape.
 - `row.min`, `row.max`, and `row.step` must dictate the boundaries of the slider logic.
 - **Mutation**: `onChange` of the input must parse the value as a Number before dispatching `onSelect`.
 
@@ -45,3 +45,12 @@ Your component must account for:
 - If `true`, render a checkbox at the end of the row.
 - Checking it sets the value in the map to `null`.
 - When `value === null`, gray out the slider track and disable the input.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — number or `null` per row
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
+- [ ] Use `CustomSliderTrack` when `sliderType === 'graphics'`
+- [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../00-integration/question-type-sdk-matrix.md#slider_matrix)

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

@@ -3,7 +3,7 @@
 > **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'`
+> **Handles**: `type: 'FILE_UPLOAD'`
 
 ## Core Responsibility
 Render a robust drag-and-drop zone and enforce complex file size, type limits, and maximum file count constraints BEFORE updating the state.
@@ -56,3 +56,12 @@ Before calling `onSelect`, your component MUST validate against these properties
 
 ## Hidden Input
 - Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
+- [ ] Answer stored as: `UploadedFile[]`
+- [ ] onAction CHANGE: `{ questionId, answerValue: UploadedFile[] }` after upload
+- [ ] Visibility helper: N/A
+- [ ] Enforce `maxFileCount` and `fileSizeLimit` client-side
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)

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

@@ -3,7 +3,7 @@
 > **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`
+> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, standalone `slider`
 
 ## Core Responsibility
 Native browser `<input type="range">` elements are impossible to style consistently across browsers, especially when trying to render dynamic emoji handles. This component MUST implement an invisible overlay architecture to provide total CSS control over the slider's appearance.
@@ -24,7 +24,7 @@ A dynamic `<div>` representing the portion of the slider up to the current value
 ### Layer 3: The Custom Thumb
 A visual element that floats along the track.
 - **For Standard Sliders**: A pink circle. `w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none`.
-- **For Graphics Sliders (`sliderType === 'graphics'`)**: A larger white circle containing an emoji mapped to the current value using `getEmojiForIndex`. `w-10 h-10 bg-white shadow-md border flex items-center justify-center text-2xl`.
+- **For Graphics Sliders (`sliderType === 'graphics'`)**: A larger white circle containing an emoji mapped to the current value using client-side react-icons. `w-10 h-10 bg-white shadow-md border flex items-center justify-center text-2xl`.
 - Inline Style: `style={{ left: \`\${percentage}%\` }}`.
 
 ### Layer 4: The Native Input (The Engine)

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

@@ -1,14 +1,15 @@
 # Progress Bar
 
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Progress calculation:** `00-integration/progress.md`
 > **Reference implementation:** `apps/client/src/components/ProgressBar.tsx`
 > **Component**: `ProgressBar`
-> **Role**: Displays completion status at the top of the survey.
 
 ## Props Interface
+
 ```typescript
 type ProgressBarProps = {
-  progressPercentage: number; // 0 to 100
+  progressPercentage: number; // 0 to 100, path-scoped
 };
 ```
 
@@ -16,7 +17,6 @@ type ProgressBarProps = {
 
 ```tsx
 export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
-  // Ensure it's bounded between 0 and 100
   const width = Math.min(100, Math.max(0, progressPercentage));
 
   return (
@@ -30,4 +30,10 @@ export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
 }
 ```
 
-The `progressPercentage` value is provided directly by `state.progressPercentage` from the `useSurveySDK` hook.
+## Wiring
+
+```tsx
+<ProgressBar progressPercentage={state.progressPercentage} />
+```
+
+The SDK computes percentage from **questions on the active skip path**, not total survey pages. Skip logic and answer changes update the bar automatically.

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

@@ -6,7 +6,9 @@
 > **Used by**: `CsatMatrixScale`, `LikertMatrixScale`
 
 ## Role
-Renders a dropdown selector for a single row in a matrix question. Used when `matrixFormat === 'dropdown'` or `buttonType === 'dropdown'`.
+Renders a dropdown selector for a single row in a matrix question. Used when `gridLayout === 'dropdown'` or `displayStyle === 'dropdown'`.
+
+Accepts `ScaleColumn[]`; emits stored column ids via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
 
 ## Props Interface
 ```typescript

package/templates/docs/01-components/14-intro-page.md

@@ -0,0 +1,34 @@
+# Intro Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/IntroPage.tsx`
+
+## When to render
+
+`state.phase.kind === 'intro'` and `state.specialPage` is set.
+
+## Props
+
+```typescript
+type IntroPageProps = {
+  page: SpecialPage;
+  language?: string;
+  onStart: () => void;
+};
+```
+
+## Wiring
+
+```tsx
+<IntroPage
+  page={state.specialPage}
+  language={survey.language}
+  onStart={() => onAction({ type: 'START' })}
+/>
+```
+
+## Content
+
+- Render `page.header` and optional `page.description` as HTML
+- CTA label: `page.ctaLabel` or default "Start Survey"
+- Header + Footer chrome on full-page layout

package/templates/docs/01-components/15-end-page.md

@@ -0,0 +1,31 @@
+# End Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/EndPage.tsx`
+> **Logic:** `00-integration/end-page-logic.md`
+
+## When to render
+
+`state.phase.kind === 'end'` after successful submit, with `state.specialPage` from `survey.endPages`.
+
+When the survey has **multiple end pages**, the SDK picks the page at submit using display logic (see [`end-page-logic.md`](../00-integration/end-page-logic.md)). The client only renders the resolved `state.specialPage`.
+
+## Props
+
+```typescript
+type EndPageProps = {
+  page: SpecialPage;
+};
+```
+
+## Wiring
+
+```tsx
+<EndPage page={state.specialPage} />
+```
+
+## Content
+
+- Render `page.header` and optional `page.description` as HTML
+- No navigation buttons — terminal thank-you screen
+- Header + Footer chrome

package/templates/docs/01-components/16-paused-page.md

@@ -0,0 +1,27 @@
+# Paused Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/PausedPage.tsx`
+
+## When to render
+
+`state.phase.kind === 'paused'` when survey `phaseFlags.paused` is true.
+
+## Props
+
+```typescript
+type PausedPageProps = {
+  page: SpecialPage;
+};
+```
+
+## Wiring
+
+```tsx
+<PausedPage page={state.specialPage} />
+```
+
+## Content
+
+- Read-only message from `page.header` / `page.description`
+- No start or navigation actions

package/templates/docs/01-components/17-heatmap-scale.md

@@ -0,0 +1,75 @@
+# Heatmap Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/13-heatmap.md`
+> **Reference implementation:** `apps/client/src/components/HeatmapScale.tsx`
+> **Coordinate helpers:** `apps/client/src/lib/surveyUi/heatmapCoords.ts`
+> **Target Component**: `HeatmapScale`
+> **Handles**: `type: 'HEATMAP'`
+
+## Core Responsibility
+
+Render the heatmap image, capture click spots in normalized 0–1 coordinates, toggle spots on repeat click, enforce `maxClicksAllowed` client-side, and bubble answers via `onSelect`.
+
+## Props Contract
+
+```typescript
+type HeatmapScaleProps = {
+  question: HeatmapQuestion;
+  selectedValue?: HeatmapAnswer;
+  onSelect: (answer: HeatmapAnswer | undefined) => void;
+};
+```
+
+## State Management
+
+- `selectedValue` from SDK is source of truth — do not duplicate answer state
+- Local UI state: `isImageReady` only
+
+## Click Interaction
+
+1. User clicks image → compute normalized `{ x, y }` from `getBoundingClientRect()`
+2. If click within 14px of existing spot → remove that spot
+3. Else if under `maxClicksAllowed` → append `{ id: crypto.randomUUID(), x, y }`
+4. Else → no-op
+
+## Coordinate Helpers
+
+Use `apps/client/src/lib/surveyUi/heatmapCoords.ts`:
+
+- `getNormalizedClickFromImage(event, imageElement)`
+- `findSpotNearClick(clickX, clickY, spots, imageRect)`
+- `createNewSpot(x, y)`
+
+## DOM Structure
+
+```tsx
+<div className="relative inline-block max-w-full">
+  <img onClick={handleImageClick} ... />
+  <div className="absolute inset-0 pointer-events-none">
+    {spots.map(spot => <Spot />)}
+  </div>
+</div>
+```
+
+## Wiring in Question.tsx
+
+```typescript
+{question.type === QUESTION_TYPE.HEATMAP && (
+  <HeatmapScale
+    question={question as HeatmapQuestion}
+    selectedValue={Array.isArray(selectedValue) ? selectedValue : undefined}
+    onSelect={onSelect}
+  />
+)}
+```
+
+Question shell (title, description, validation) stays in `Question.tsx`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.HEATMAP`
+- [ ] Answer stored as: `HeatmapClickPoint[]`
+- [ ] onAction CHANGE: `{ questionId, answerValue: HeatmapClickPoint[] }`
+- [ ] Copy coord helper from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
+- [ ] Respect `maxClicksAllowed`; normalize coords 0–1
+- [ ] Matrix row: [`question-type-sdk-matrix.md#heatmap`](../00-integration/question-type-sdk-matrix.md#heatmap)

package/templates/docs/01-components/18-rank-order-scale.md

@@ -0,0 +1,100 @@
+# Rank Order Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/14-rank-order.md`
+> **Reference implementation:** `apps/client/src/components/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`.
+
+## Props Contract
+
+```typescript
+type RankOrderScaleProps = {
+  question: RankOrderQuestion;
+  selectedValue?: RankOrderAnswers;
+  onSelect: (value: RankOrderAnswers) => void;
+};
+```
+
+## 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
+
+## Layout Orchestrator
+
+```tsx
+export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderScaleProps) {
+  if (question.interactionMode === 'dragAndDrop') {
+    return <DragDropRankLayout ... />;
+  }
+  return <DropdownRankLayout ... />;
+}
+```
+
+## Dropdown Mode
+
+- 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
+
+## Wiring in Question.tsx
+
+```typescript
+import {
+  QUESTION_TYPE,
+  getVisibleRankOrderOptionsForAnswers,
+} from '@explorer02/cfm-survey-sdk';
+
+const rankOrderQuestion = useMemo(() => {
+  if (question.type !== QUESTION_TYPE.RANK_ORDER) return null;
+  return {
+    ...question,
+    options: getVisibleRankOrderOptionsForAnswers(
+      question,
+      allAnswers,
+      allQuestions,
+      customFieldValues
+    ),
+  };
+}, [question, allAnswers, allQuestions, customFieldValues]);
+
+{question.type === QUESTION_TYPE.RANK_ORDER && rankOrderQuestion && (
+  <RankOrderScale
+    question={rankOrderQuestion}
+    selectedValue={...}
+    onSelect={onSelect}
+  />
+)}
+```
+
+## Dependencies
+
+Add to client `package.json`:
+
+- `@dnd-kit/core`
+- `@dnd-kit/sortable`
+- `@dnd-kit/utilities`
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.RANK_ORDER`
+- [ ] Answer stored as: `RankOrderAnswers`
+- [ ] onAction CHANGE: `{ questionId, answerValue: RankOrderAnswers }`
+- [ ] Visibility helper: `getVisibleRankOrderOptionsForAnswers(..., customFieldValues?)`
+- [ ] Rank 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/README.md

@@ -1,50 +1,51 @@
 # Client Components Overview
 
-> Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md) (reference-client driven).
+> Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md).
 > **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.
+> Read blueprints **per type** from `MANIFEST.json` after survey inventory — not all files are needed for every survey.
 
 ## Component Architecture
 
-The UI is driven by a single top-level `SurveyPage` component which iterates over the `currentQuestions` array and passes each `SurveyQuestion` object to the `Question` dispatcher component.
+The UI is driven by `SurveyPage`, which routes by `state.phase` and renders `Question` for each item in `currentQuestions`.
 
 ```
-SurveyPage (Top-level orchestrator)
+SurveyPage (phase router)
    │
-   ├── Header (Branding/Logo)
-   ├── ProgressBar
-   ├── LanguageSelector
-   ├── Footer
+   ├── IntroPage / PausedPage / EndPage (special phases)
    │
-   └── Question (Dispatcher, mapped over `currentQuestions`)
-         │
-         ├── RatingScale (handles 'rating' and 'rating_scale')
-         ├── CsatScale (handles 'csat')
-         ├── LikertMatrixScale (handles 'matrix' CFM_MATRIX)
-         ├── CsatMatrixScale (handles 'matrix' CSAT_MATRIX / 'rating_matrix')
-         ├── SliderMatrixScale (handles 'slider_matrix')
-         ├── FileUploadScale (handles 'file_upload')
-         │
-         ├── (Inline UI for 'radio', 'text', 'text_and_media')
-         │
-         └── Shared Sub-Components:
-               ├── CustomSliderTrack (used by csat/matrix sliders)
-               └── MatrixDropdown (used by matrix dropdowns)
+   └── SurveyContent (phase.kind === 'content')
+         ├── Header
+         ├── ProgressBar
+         ├── LanguageSelector
+         ├── Question × N (dispatcher)
+         ├── Back / Next|Submit nav
+         └── Footer
 ```
 
-## Styling Approach
+## Question dispatcher (11 types)
 
-- Built entirely with **Tailwind CSS**.
-- **No external UI libraries** (no Material UI, Chakra, etc.).
-- The default brand colour is Telekom Magenta: `#e20074`.
-- The UI follows a strict, clean, modern corporate aesthetic (card-based layout, subtle borders, pink accents on selection).
+`Question` switches on `question.type` / `QUESTION_TYPE` (no `subType`):
+
+| Type | Component |
+|------|-----------|
+| `NPS_SCALE` | `RatingScale` |
+| `MCQ`, `TEXTFIELD`, `TEXT_AND_MEDIA` | Inline in `Question` |
+| `CFM_MATRIX` | `LikertMatrixScale` |
+| `CSAT_MATRIX`, `RATING_MATRIX` | `CsatMatrixScale` |
+| `SLIDER_MATRIX` | `SliderMatrixScale` |
+| `FILE_UPLOAD` | `FileUploadScale` |
+| `HEATMAP` | `HeatmapScale` |
+| `RANK_ORDER` | `RankOrderScale` |
 
-## The `Question` Dispatcher
+Shared: `CustomSliderTrack`, `MatrixDropdown`
 
-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.
+## Styling Approach
 
-See `02-question.md` for details on the dispatcher logic.
+- Built entirely with **Tailwind CSS**.
+- **No external UI libraries** (no Material UI, Chakra, etc.).
+- Default brand colour: Telekom Magenta `#e20074`.
+- Card-based layout, subtle borders, pink accents on selection.
 
 ## Files in This Folder
 
@@ -52,14 +53,19 @@ See `02-question.md` for details on the dispatcher logic.
 |------|-----------|
 | `01-survey-page.md` | `SurveyPage` orchestrator |
 | `02-question.md` | `Question` dispatcher & inline types |
-| `03-rating-scale.md` | `RatingScale` (NPS/Stars) |
-| `04-csat-scale.md` | `CsatScale` (Emoji/Star CSAT) |
-| `05-csat-matrix-scale.md` | `CsatMatrixScale` (Satisfaction Grid) |
-| `06-likert-matrix-scale.md` | `LikertMatrixScale` (Text Grid) |
-| `07-slider-matrix-scale.md` | `SliderMatrixScale` (Sliders Grid) |
+| `03-rating-scale.md` | `RatingScale` (NPS) |
+| `04-star-rating-scale.md` | Legacy star patterns (deprecated) |
+| `05-csat-matrix-scale.md` | `CsatMatrixScale` |
+| `06-likert-matrix-scale.md` | `LikertMatrixScale` |
+| `07-slider-matrix-scale.md` | `SliderMatrixScale` |
 | `08-file-upload-scale.md` | `FileUploadScale` |
-| `09-custom-slider-track.md` | `CustomSliderTrack` (Emoji thumbs) |
+| `09-custom-slider-track.md` | `CustomSliderTrack` |
 | `10-header-footer.md` | `Header` & `Footer` |
 | `11-progress-bar.md` | `ProgressBar` |
 | `12-language-selector.md` | `LanguageSelector` |
 | `13-matrix-dropdown.md` | `MatrixDropdown` |
+| `14-intro-page.md` | `IntroPage` |
+| `15-end-page.md` | `EndPage` |
+| `16-paused-page.md` | `PausedPage` |
+| `17-heatmap-scale.md` | `HeatmapScale` |
+| `18-rank-order-scale.md` | `RankOrderScale` |