@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

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

@@ -1,7 +1,8 @@
 # Survey Page Orchestrator Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/SurveyPage.tsx`
+> **Portable template:** implement from `docs/templates/` + [`agent-execution-flow.md`](../00-integration/agent-execution-flow.md) Phase 5
+> **Monorepo snapshot (do not copy):** `apps/client/src/components/SurveyPage.tsx`
 > **Target Component**: `SurveyPage`
 > **Role**: Wires `useSurveySDK` to the UI — loading/error states, phase routing, pagination, submission.
 
@@ -13,9 +14,9 @@ Act as the **phase state machine** for the survey. Never render questions direct
 
 ```tsx
 import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
 
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
-const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {}; // Populate when survey uses custom-field logic
 
 export default function SurveyPage() {
   const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
@@ -46,6 +47,14 @@ export default function SurveyPage() {
 
 See [`client-integration-guide.md`](../00-integration/client-integration-guide.md) for lifecycle effects (`SCROLL`, `RECORD_QUESTION_VIEW`).
 
+When fetched survey contains any `_c_…` custom field id in logic rules:
+
+- [ ] Copy [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) → `src/lib/customFieldValues.ts`
+- [ ] Populate map from CRM/transaction payload
+- [ ] Import `CUSTOM_FIELD_VALUES` in `SurveyPage` (do not define inline empty `{}`)
+
+See [`client-lib-folder.md`](../00-integration/client-lib-folder.md) and [`custom-field-logic-and-navigation.md`](../00-integration/custom-field-logic-and-navigation.md).
+
 ## Render Order (MANDATORY)
 
 Handle in this order:
@@ -73,12 +82,13 @@ See `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`.
 
 ### 3. Active content (`phase.kind === 'content'`)
 
-1. `Header`
-2. `ProgressBar` (`state.progressPercentage`) — see `00-integration/progress.md`
-3. `LanguageSelector`
-4. Question map (below)
-5. Navigation buttons (below)
-6. `Footer`
+1. `SurveyStickyChrome` — sticky `Header` + `ProgressBar` (`state.progressPercentage`); see `19-survey-sticky-chrome.md` and `00-integration/progress.md`
+2. `main`: `LanguageSelector`
+3. Question map (below)
+4. Navigation buttons (below)
+5. `Footer`
+
+Use standalone `Header` (no sticky chrome) on intro, end, paused, loading, and terminal phases.
 
 ## The Question Map
 

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

@@ -2,7 +2,7 @@
 
 > **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`
+> **Monorepo snapshot (illustrative only):** `apps/client/src/components/Question.tsx`
 > **Target Component**: `Question`
 
 ## Start Here (CRITICAL)
@@ -77,7 +77,7 @@ Store matrix cell values as column **`id`** via `matrixColumnStoredValue(col)`
 ### MCQ (`QUESTION_TYPE.MCQ`)
 
 - [ ] Filter options with `getVisibleMcqOptionsForAnswers` before render
-- [ ] Store `option.id`; support `isMultiSelect` array shape when configured
+- [ ] Store `option.id`; use `selectionMode` (`single` | `multiple`) — not `isMultiSelect`
 - [ ] onAction CHANGE: `{ questionId, answerValue: optionId | optionId[] }`
 
 ### TEXTFIELD (`QUESTION_TYPE.TEXTFIELD`)

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

@@ -1,40 +1,34 @@
 # 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`
+> **Portable template:** copy [`templates/RatingScale.tsx`](../templates/RatingScale.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts) + [`surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
 > **Target Component**: `RatingScale`
 > **Handles**: `type: 'NPS_SCALE'` (via `QUESTION_TYPE.NPS_SCALE`)
 
 ## Core Responsibility
-Render a horizontal sequence of numbered badges. 
+
+Render a horizontal sequence of numbered badges with traffic-light colors (NPS 0–10).
 
 ## Configuration Matrix
-You MUST handle the following configurations dynamically:
 
 ### 1. Color Grading (NPS)
-- Check if `option.color` exists. If so, apply it to the badge background. This is crucial for NPS scales (Red 0-6, Yellow 7-8, Green 9-10).
+- Use `getAccentColor(value)` from `surveyUiScaleUtils.ts` for badge backgrounds
 
 ### 2. Label Positioning (`minLabel`, `midLabel`, `maxLabel`)
-- **Architectural Requirement**: Wrap the badge sequence and the labels in a relative container.
-- Place labels underneath the badges using absolute positioning.
-- **Mid Label Calculation**: You must calculate the exact center position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.
+- Render in `Question.tsx` above `RatingScale` with absolute positioning
+- Mid label: `left: (midLabelIndex / (options.length - 1)) * 100%`
 
 ## UI/UX Rules (CRITICAL)
 
-The UI must exactly match enterprise standards:
-
-1. **Shape**: Badges MUST be square with rounded corners (`rounded-lg w-10 h-10 sm:w-12 sm:h-12`). Do NOT use full circles (`rounded-full`).
-2. **Unselected State**: If any item is selected, unselected items must dim (`opacity-30`).
-3. **Selected State**: The selected badge MUST pop out prominently: `border-2 border-[#e20074] shadow-md scale-105 opacity-100 font-bold`.
-4. **Hover State**: `hover:scale-105 hover:border-[#e20074] transition-all cursor-pointer`.
-5. **Tooltips**: Every badge MUST have `title={option.label}` applied for accessibility and semantic context (e.g. hovering '10' shows 'Extremely Likely').
+1. **Shape**: Square badges with rounded corners — not full circles
+2. **Unselected State**: Dim unselected when any item selected (`opacity-30`)
+3. **Selected State**: `border-2 border-[#e20074] shadow-md scale-105`
+4. **Tooltips**: `title={option.label}` on every badge
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable `RatingScale.tsx`
 - [ ] Type literal: `QUESTION_TYPE.NPS_SCALE`
 - [ ] Answer stored as: `number`
 - [ ] onAction CHANGE: `{ questionId, answerValue: number }`
-- [ ] Visibility helper: `getVisibleScaleColumnsForAnswers` when scale points have answer logic
-- [ ] Custom fields: 4th arg on scale visibility helper when needed
-- [ ] Logic features: skip ✓ display ✓ answer ✓ variants ✓ numbering ✓
-- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md#nps_scale)
+- [ ] minLabel/maxLabel rendered in Question.tsx when present

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

@@ -1,44 +1,36 @@
 # CSAT Matrix Architectural Blueprint
 
-> **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`
+> **UI spec (authoritative):** `03-ui-specs/04-csat.md` (CSAT) · `03-ui-specs/08-matrix-csat-rating.md` (RATING)
+> **Portable template:** copy [`templates/CsatMatrixScale.tsx`](../templates/CsatMatrixScale.tsx) + shared deps (see ui-spec)
 > **Target Component**: `CsatMatrixScale`
 > **Handles**: `type: 'CSAT_MATRIX'` and `type: 'RATING_MATRIX'`
 
 ## Core Responsibility
 
-Render a grid where columns represent satisfaction scales (Emojis, Stars, or Rating Badges).
+Render a matrix grid where rows are `statementRows` and columns are `scaleColumns`. Route on `displayStyle` and `gridLayout`.
 
-## Data Mapping & State Management
+## Statement & labels (CRITICAL)
 
-- `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`.
+Every grid row MUST show `statementRows[].statementText` in a **180px** left column.
 
-## Configuration Matrix
-
-You MUST handle:
-
-- **`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.
+Every grid MUST show either:
+- A **column header row** from `scaleColumns[].label`, OR
+- An **anchor label row** from `scaleAnchorLabels[]`
 
-## UI/UX Bounding Box Rules (CRITICAL)
+Never render a bare grid of inputs with no row/column labels.
 
-Matrices are difficult to read and click accurately. You MUST implement these strict UI rules:
-
-1. **Row Tracking**:
-   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150`.
+## Configuration Matrix
 
-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.
+- **`displayStyle`**: emoji | star | numbered | graphics | standard — each has distinct UI (see ui-spec)
+- **`hasNotApplicableOption`**: 56px N/A column
+- **`reverseScaleOrder`**: flip column index before icon/badge lookup
+- **`gridLayout`**: standard | carousel | dropdown
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable template + `surveyUiIcons.tsx` + `surveyUiScaleUtils.ts`
 - [ ] 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
+- [ ] Answer: `MatrixRowAnswers` via `matrixColumnStoredValue(col)`
+- [ ] Visibility: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Row labels + column/anchor labels visible
 - [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

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

@@ -1,56 +1,36 @@
 # Likert Matrix Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/07-matrix-cfm.md`
-> **Reference implementation:** `apps/client/src/components/LikertMatrixScale.tsx`
+> **Portable template:** copy [`templates/LikertMatrixScale.tsx`](../templates/LikertMatrixScale.tsx) + [`MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx)
 > **Target Component**: `LikertMatrixScale`
 > **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`: `MatrixRowAnswers` — store column **`id`** via `matrixColumnStoredValue(col)`
-- **Mutation**: When a cell is selected for `row.id`, dispatch `onSelect({ ...selectedValue, [row.id]: columnId })`
+Render CFM matrix grids with support for bipolar layout, transposed tables, multi-select checkboxes, and anchor labels.
 
-## Configuration Matrix (CRITICAL FOR PLANNING)
+## Statement & labels (CRITICAL)
 
-Your component architecture MUST account for the following boolean flags from `question`:
+| Mode | Left label | Right label | Column headers |
+|------|------------|-------------|----------------|
+| Likert | `statementText` (180px) | — | `scaleColumns[].label` when `showColumnHeaders` |
+| Bipolar | `statementText` (25%) | `oppositeStatementText` (25%) | anchor labels OR column headers |
+| Transposed | `scaleColumns[].label` as row | — | `statementRows[].statementText` as columns |
 
-### 1. `transposeTable`
-If `true`, the standard Row-by-Column matrix is inverted:
-- `question.columns` become the row labels on the left.
-- `question.rows` become the top column headers.
-- **Architectural Requirement**: Your `<tbody>` map must iterate over `question.columns` first, and render `<td>` cells mapped from `question.rows`.
-- Ensure `onSelect` still correctly pairs the original `row.id` with the original `col.value`.
+Use `dangerouslySetInnerHTML` for all statement/label HTML.
 
-### 2. `repeatColumnHeaders`
-If `true`, the `<thead>` containing column labels must be re-injected periodically to prevent users from losing track of columns on long matrices.
-- **Implementation Strategy**: In your row `map()`, if `index > 0 && index % 5 === 0`, return a React Fragment containing a cloned `<tr>` header row followed by the actual data `<tr>`.
-- **Note:** API/config field is `repeatColumnHeaders` (not `repeatScale`).
+## Configuration Matrix
 
-### 3. `matrixType === 'bipolar'`
-Standard matrices (`'likert'`) only show statement text on the left. Bipolar scales show text on BOTH sides of the radio buttons.
-- **Implementation Strategy**: Render an extra `<td>` at the end of the row containing `row.rightText`.
-
-## UI/UX & Styling Constraints
-
-To match enterprise standards, implement the following UI strictly:
-
-1. **Row Tracking (Hover Effects)**:
-   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150 group`. This is mandatory for UX on wide matrices.
-2. **Radio Buttons**:
-   - Use `accent-[#e20074] w-5 h-5 cursor-pointer` or build custom CSS circles that fill with the brand color.
-   - Do NOT use standard unstyled blue browser radios.
-3. **Tooltips (Accessibility)**:
-   - 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`.
+- **`transposeTable`**: swaps which array becomes grid rows vs columns
+- **`selectionMode: 'multiple'`**: checkboxes; answers are `string[]` per row
+- **`statementLayout: 'bipolar'`**: 25% | scale | 25% layout
+- **`scaleAnchorLabels`**: positioned above scale when bipolar or likert
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable template
 - [ ] 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)
+- [ ] Answer: `MatrixRowAnswers` via `matrixColumnStoredValue(col)`
+- [ ] Visibility: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] All row labels and header labels visible per ui-spec
+- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

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

@@ -1,56 +1,71 @@
 # Slider Matrix Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/09-slider-matrix.md`
-> **Reference implementation:** `apps/client/src/components/SliderMatrixScale.tsx`
+> **Portable template:** copy [`templates/SliderMatrixScale.tsx`](../templates/SliderMatrixScale.tsx) + [`CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts)
 > **Target Component**: `SliderMatrixScale`
 > **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 `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`.
+Render one `CustomSliderTrack` per `statementRows[]` entry, with a shared header row of colored tick badges and optional anchor labels.
 
-## The "Thick Slider" UX Implementation (CRITICAL)
+## CRITICAL — Do NOT improvise
 
-Native `<input type="range">` elements are notoriously difficult to style consistently across browsers. You MUST implement the "Invisible Overlay" pattern to achieve the expected thick-track UI.
+- **Do NOT** build custom “thick slider” / invisible overlay range inputs
+- **Do NOT** use legacy field names (`rows`, `labels`, `tickValues`, `enableNotApplicable`, `sliderType`)
+- **Copy the portable template first**, then customize branding colors only
 
-### The Invisible Overlay Pattern
-For every slider row, build a relative container:
-1. **Base Track**: `absolute w-full h-2 bg-gray-200 rounded-full`.
-2. **Dynamic Fill Track**: `absolute h-2 bg-[#e20074] rounded-l-full`.
-   - Calculate width dynamically: `((value - min) / (max - min)) * 100 + '%'`.
-3. **The Thumb**: `absolute w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none transition-transform group-hover:scale-125`.
-   - Position it dynamically: `left: calc(${percentage}% - 10px)`.
-4. **The Input Control**: Layer a native input on top, completely invisible but clickable:
-   - `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`
+## SDK Fields (authoritative)
 
-## Configuration Matrix (CRITICAL FOR PLANNING)
+From `fetchSurvey/types/sliderMatrix.ts`:
 
-Your component must account for:
+| Field | UI role |
+|-------|---------|
+| `statementRows[]` | Row labels + per-row min/max/step |
+| `ticks.count` + `ticks.marks[]` | Header colored badges (`tickPosition`, `tickLabel`) |
+| `scaleAnchorLabels?` | Optional text labels above tick row |
+| `enableInputBox` | 80px numeric input + steppers |
+| `displayValues` | Pass to `CustomSliderTrack` |
+| `hasNotApplicableOption` | N/A checkbox column; answer value **`'N/A'`** string |
+| `sliderStyle?: 'graphics'` | Plain text ticks + emoji thumb via `CustomSliderTrack` |
 
-### 1. Exact Value Display
-- Users must see the exact number they are selecting.
-- Render a badge at the far right of the slider track: `shrink-0 w-8 text-center font-bold text-[#e20074]`.
+## Layout (matches reference)
 
-### 2. `row.ticks` & `tickValues`
-- If `question.ticks` or `row.tickValues` exists, you must render tiny vertical tick marks below the track at appropriate percentage intervals to guide the user.
+```
+[25% spacer] [scaleAnchorLabels?] [colored tick badges 0–10] [input spacer?] [N/A header?]
+┌─ gray row band #f3f4f6 ─────────────────────────────────────────────────────────────┐
+│ 25% statementText │ CustomSliderTrack │ 80px input? │ N/A checkbox? │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
 
-### 3. Label Positioning
-- `row.minLabel` and `row.maxLabel` must be displayed directly underneath the far-left and far-right of the slider track using flexbox `justify-between text-xs text-gray-500`.
+## Statement text visibility
 
-### 4. `enableNotApplicable`
-- 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.
+- Render `row.statementText` with `dangerouslySetInnerHTML` in the **25% left column**
+- Skip rendering when text is empty or literal `"Question"` (placeholder from API)
+- **Never** omit the statement column — agents that put statement text in the question title only will fail multi-row surveys
+
+## Header tick badges
+
+```typescript
+const tickValues = ticks.marks.map((mark, index) => ({
+  value: mark.tickPosition,
+  label: mark.tickLabel,
+  color: tickColorFromIndex(index, ticks.count),
+}));
+const htmlStep = ticks.count > 1 ? (max - min) / (ticks.count - 1) : row.step;
+```
+
+## N/A behavior
+
+- Checked → store `'N/A'` string (not `null`)
+- Unchecked → reset to `row.defaultValue ?? row.min`
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx`, `surveyUiScaleUtils.ts`
 - [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
-- [ ] Answer stored as: `MatrixRowAnswers` — number or `null` per row
+- [ ] Answer: `MatrixRowAnswers` — `{ [rowId]: number | 'N/A' }`
 - [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
-- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
-- [ ] Use `CustomSliderTrack` when `sliderType === 'graphics'`
+- [ ] Visibility: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
+- [ ] Header row renders even for single-row questions
 - [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../00-integration/question-type-sdk-matrix.md#slider_matrix)

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

@@ -1,38 +1,28 @@
 # Custom Slider Track Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/shared/custom-slider-track.md`
-> **Reference implementation:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Portable template:** copy [`templates/CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
 > **Target Component**: `CustomSliderTrack`
-> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, standalone `slider`
+> **Used By**: `SliderMatrixScale`, `CsatMatrixScale` (`displayStyle: graphics`)
 
 ## 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.
 
-## The Invisible Overlay Architecture (CRITICAL)
+Provide a styled range slider with optional emoji thumb (`sliderType: 'graphics'`). Used **inside** `SliderMatrixScale` and matrix graphics rows — not as a standalone question type.
 
-Instead of trying to style the `::-webkit-slider-thumb` pseudo-elements, you MUST build the slider using layered DOM elements.
+## CRITICAL — Copy template
 
-### Layer 1: The Background Track
-A static `<div>` representing the entire length of the slider.
-- CSS: `absolute w-full h-2 bg-gray-200 rounded-full`.
+Do not reimplement from this blueprint alone. Copy `templates/CustomSliderTrack.tsx` which implements the layered track + invisible range input pattern.
 
-### Layer 2: The Active Fill
-A dynamic `<div>` representing the portion of the slider up to the current value.
-- CSS: `absolute h-2 bg-[#e20074] rounded-l-full`.
-- Inline Style: `style={{ width: \`\${percentage}%\` }}`.
+## Pass tickLabels for matrix graphics
 
-### 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 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}%\` }}`.
+```typescript
+tickLabels={scaleColumns.map(col => col.label)}
+```
 
-### Layer 4: The Native Input (The Engine)
-An invisible native input overlaid exactly on top to capture all mouse/touch events automatically without needing manual math for drag interactions.
-- CSS: `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`.
-- This ensures perfect accessibility, keyboard navigation, and mobile touch support.
+Required for correct tooltip text on graphics sliders (RATING_MATRIX Page 11 fixture).
 
-## Configuration Logic
-- Calculate percentage carefully: `((value - min) / (max - min)) * 100`.
-- Ensure the custom thumb is negatively margined (e.g. `-ml-2.5` or `-ml-5`) so that its *center* aligns with the percentage point, not its left edge.
-- If `question.ticks` is provided, map out small `w-0.5 h-3 bg-gray-300` vertical lines below the track at the correct percentage intervals.
+## SDK Integration Checklist
+
+- [ ] Copied portable `CustomSliderTrack.tsx`
+- [ ] Used by `SliderMatrixScale` or `CsatMatrixScale` — not wired directly in `Question.tsx` for SLIDER_MATRIX
+- [ ] `hasSelectedValue`, `disabled`, `htmlStep` props wired correctly

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

@@ -1,17 +1,36 @@
 # Theme & Logo Engineering Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/Header.tsx`, `Footer.tsx`
+> **Wizard contract:** [`wizard-preview-build-guide.md`](../00-integration/wizard-preview-build-guide.md) — `data-cfm-*` + `var(--cfm-*)`
+> **Monorepo snapshot (do not copy):** `apps/client/src/components/Header.tsx`, `Footer.tsx`
 > **Target Components**: `Header`, `Footer`
 > **Handles**: Branding, Mockup Replication
 
 ## Core Responsibility
 When building the survey layout, the client will provide a text prompt or an image mockup. You MUST dynamically build the Theme and Logo using purely CSS and Tailwind to match the requested brand.
 
+## Sticky content chrome
+
+On the **content** phase, render `Header` inside `SurveyStickyChrome` with `embedded` so the wrapper owns the shadow:
+
+```tsx
+<Header embedded />
+```
+
+Use standalone `Header` (default, with shadow) on intro, end, paused, loading, and terminal pages. See `19-survey-sticky-chrome.md`.
+
 ## Logo Engineering Rules (CRITICAL)
-- **NO EXTERNAL IMAGES**: You are strictly forbidden from writing `<img src="url" />` for logos, because you do not have a CDN to host them.
-- **CSS-Only Logos**: You MUST construct the company logo using HTML and CSS primitives. 
-- Example: If the prompt shows the Telekom logo (a white 'T' inside a pink square, or distinct abstract shapes), you must build it using Flexbox, CSS shapes (`rounded-full`, `rounded-tr-3xl`, absolute positioning), and the exact brand colors (`bg-[#e20074] text-white`).
+
+Agents must implement **one** of these wizard-compatible patterns in `Header.tsx`:
+
+| Mode | When | Required markup |
+|------|------|-----------------|
+| **Image** | Brand asset in `public/` | `<img data-cfm-logo src="./exact-file.svg" />` for AWS deploy (`assetPrefix: './'`). Use `/exact-file.svg` only for local dev. Include hidden `<span data-cfm-logo-text>` fallback. |
+| **Text** | CSS-only logo from prompt (no image file) | `<span data-cfm-logo-text>Company</span>` in logo slot — no `data-cfm-logo` img |
+
+- **NO EXTERNAL URLS** for logos (`https://…`, wizard `/assets/` URLs, or `data:image/…`).
+- **CSS-only logos** use `data-cfm-logo-text` (and optional CSS shapes) — wizard shows text until client uploads an image.
+- After wizard upload, set `src="./{global.logo.fileName}"` from saved config — see [`aws-deploy.md`](../00-integration/aws-deploy.md) § Logos & local assets.
 
 ## Theme Engineering
 - Map the primary brand color to the accent and border colors across the entire survey.

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

@@ -20,20 +20,28 @@ export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
   const width = Math.min(100, Math.max(0, progressPercentage));
 
   return (
-    <div className="mb-8 h-2 w-full overflow-hidden rounded-full bg-gray-100">
-      <div
-        className="h-full bg-[#e20074] transition-all duration-500 ease-out"
-        style={{ width: `${width}%` }}
-      />
+    <div className="w-full">
+      <div className="h-3 w-full rounded-full bg-gray-100">
+        <div
+          className="h-3 rounded-full bg-[#e20074] transition-all duration-300 ease-out"
+          style={{ width: `${width}%` }}
+        />
+      </div>
     </div>
   );
 }
 ```
 
+Vertical spacing (`pt-4` above, `pb-5` below) lives on the **`SurveyStickyChrome`** wrapper — not on `ProgressBar` itself.
+
 ## Wiring
 
+Place inside **`SurveyStickyChrome`** on the content phase (see `19-survey-sticky-chrome.md`):
+
 ```tsx
-<ProgressBar progressPercentage={state.progressPercentage} />
+<SurveyStickyChrome progressPercentage={state.progressPercentage} />
 ```
 
+Do not duplicate `ProgressBar` inside scrollable `<main>`.
+
 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/19-survey-sticky-chrome.md

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

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

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