@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -1,7 +1,7 @@
 # UI Spec: Survey Chrome
 
-> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
-> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
+> **Reference:** `SurveyPage.tsx`, `SurveyStickyChrome.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `19-survey-sticky-chrome.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
 
 ## SurveyPage — Phase Router
 
@@ -21,9 +21,8 @@
 ## Active Layout
 
 ```
-Header
+SurveyStickyChrome (sticky top-0 — Header + ProgressBar)
 main (max-w-4xl)
-  ProgressBar(progressPercentage)
   LanguageSelector (hidden if ≤1 language)
   Questions (space-y-12)
   Submit error (if any)
@@ -31,6 +30,25 @@ main (max-w-4xl)
 Footer
 ```
 
+### Sticky chrome (required on content phase)
+
+Long pages push the last question below the fold. Wrap **Header + ProgressBar** in one sticky container so progress stays visible while answering.
+
+```tsx
+<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={state.progressPercentage} />
+  </div>
+</div>
+```
+
+**Spacing:** `pt-4` (16px) between logo block and progress track; `pb-5` (20px) below the track before scrollable content. Do not flush the bar against the logo square.
+
+See [`01-components/19-survey-sticky-chrome.md`](../01-components/19-survey-sticky-chrome.md). Copy [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx).
+
+Use standalone `Header` (no sticky wrapper) on intro, end, paused, loading, and terminal phases.
+
 ## Navigation Labels
 
 German when `survey.language.startsWith('de')`:
@@ -51,10 +69,53 @@ German when `survey.language.startsWith('de')`:
 
 Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`).
 
+Render inside **`SurveyStickyChrome`** (sticky header + progress) on the content phase — not inside scrollable `<main>`. Clamp width to `0–100`.
+
+| Token | Value | Role |
+|-------|-------|------|
+| Gap above track | `pt-4` (16px) | Space between logo block and progress bar |
+| Gap below track | `pb-5` (20px) | Breathing room before question content |
+| Track height | `h-3` (12px) | Full-width rounded pill |
+
 ## LanguageSelector
 
 - Hidden when `languages.length <= 1`
 - Focus ring: `#2563eb`
+- Pass `language` in `useMemo` hook options — SDK remaps survey client-side (no refetch)
+
+## Question numbering
+
+Render ordinals from SDK on content pages:
+
+```tsx
+{question.questionNumber != null && (
+  <span className="mr-1 font-semibold">{question.questionNumber}.</span>
+)}
+```
+
+See [`question-numbering.md`](../00-integration/question-numbering.md).
+
+## Special pages
+
+| Phase | Component | Action |
+|-------|-----------|--------|
+| `intro` | `IntroPage` | `page={state.specialPage}` · `onStart={() => onAction({ type: 'START' })}` |
+| `paused` | `PausedPage` | `page={state.specialPage}` · read-only, no nav |
+| `end` | `EndPage` | `page={state.specialPage}` · terminal thank-you |
+
+## Terminal phases
+
+Render a simple message (no question nav) for:
+
+- `submitted` — already completed
+- `expired` — survey expired
+- `quota_fulfilled` — quota reached
+
+Keep Header/Footer chrome consistent across all phases.
+
+## Submit loading
+
+Disable primary Next/Submit when `submitSurveyResults.isLoading`; label "Submitting…" / "Wird gesendet…".
 
 ## Agent Checklist
 
@@ -62,5 +123,31 @@ Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-inte
 - [ ] `onAction({ type: 'START' })` on intro
 - [ ] `onAction({ type: 'CHANGE' })` wired per question with `allAnswers` / `allQuestions`
 - [ ] Back uses `state.canGoBack`; primary uses `state.primaryButtonType`
-- [ ] ProgressBar receives `state.progressPercentage`
+- [ ] ProgressBar receives `state.progressPercentage` inside sticky chrome (`SurveyStickyChrome`)
+- [ ] Sticky `top-0 z-30` wrapper keeps progress visible on long pages
+- [ ] `pt-4` / `pb-5` spacing between logo, progress track, and question content
 - [ ] Header/Footer on every state branch
+- [ ] `questionNumber` prefix when present on content questions
+- [ ] Intro / Paused / End / terminal phase branches
+- [ ] Submit button disabled while `submitSurveyResults.isLoading`
+
+## Wizard customization (Phase 5 — required)
+
+> Full chrome contract: [`wizard-preview-build-guide.md`](../00-integration/wizard-preview-build-guide.md).
+
+| Element | `data-cfm-*` / CSS vars |
+|---------|-------------------------|
+| Logo | `data-cfm-logo` or `data-cfm-logo-text` |
+| Company | `data-cfm-company` |
+| Survey title | `data-cfm-survey-title` |
+| Thank you | `data-cfm-thank-you` |
+| Next / Back | `data-cfm-btn-next`, `data-cfm-btn-back` |
+| Footer | `data-cfm-copyright`, `data-cfm-footer-links` |
+| Progress | `--cfm-progress-track`, `--cfm-progress-fill` |
+| Header bg | `--cfm-header-bg`, `--cfm-header-text` |
+
+### Wizard checklist
+
+- [ ] All editable chrome strings use `data-cfm-*` attributes
+- [ ] Buttons and progress use `var(--cfm-*)` — not hardcoded Telekom hex
+- [ ] Logo: text/CSS **or** local `public/` image — never external URL (see `constraints.md` §4)

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -1,6 +1,6 @@
 # UI Spec: Heatmap (`type: 'HEATMAP'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/HeatmapScale.tsx`
+> **Implement from this spec.** Portable template: `docs/templates/HeatmapScale.tsx`
 > **SDK type:** `HeatmapQuestion` — `fetchSurvey/types/heatmap.ts`
 > **Component blueprint:** `01-components/17-heatmap-scale.md`
 
@@ -58,11 +58,18 @@ Use singular "spot" when `maxClicksAllowed === 1`.
 ## Answer Mutation
 
 ```typescript
-onSelect(HeatmapAnswer | undefined)
-// HeatmapAnswer = Array<{ id: string; x: number; y: number }>
+onSelect(HeatmapClickPoint[] | undefined)
+// HeatmapClickPoint = { id: string; x: number; y: number }
 // x, y normalized 0–1 relative to rendered image bounds
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: spots } })
 ```
 
+Copy coord helpers from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts): `getNormalizedClickFromImage`, `findSpotNearClick` (14px remove radius), `createNewSpot`.
+
+## Logic fields
+
+`HEATMAP` and `HEATMAP_REGION` — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
 ## Agent Checklist
 
 - [ ] Click handler on `<img>` element (not overlay) for precise coordinates
@@ -71,3 +78,14 @@ onSelect(HeatmapAnswer | undefined)
 - [ ] Wait for `onLoad` before accepting clicks
 - [ ] Percentage-positioned spots (survives resize)
 - [ ] Do NOT render region overlays on respondent UI
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Spot color | `--cfm-heatmap-spot-color` | Click markers |
+| Spot border | `--cfm-heatmap-spot-border` | Marker outline |
+
+### Wizard checklist
+
+- [ ] Spot markers use `--cfm-heatmap-spot-*` vars

package/templates/docs/03-ui-specs/14-rank-order.md

@@ -2,58 +2,138 @@
 
 > **Reference:** `02-reference/question-types/13-rank-order.md`
 > **Blueprint:** `01-components/18-rank-order-scale.md`
-
-## Interaction Modes
+> **Portable template:** copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
+
+## Config gate
+
+| Field | Values | UI branch |
+|-------|--------|-----------|
+| `interactionMode` | `'dropdown'` | Rank `<select>` per row |
+| `interactionMode` | `'dragAndDrop'` | `@dnd-kit` sortable list |
+| `optionDisplay` | `textOnly` / `imageOnly` / `textAndImage` | Option content layout |
+| `requireRankAll` | boolean | Validation (SDK) |
+| `shuffleOptions` | boolean | **SDK shuffles at fetch** — render `question.options` as-is; do not re-shuffle client-side |
+
+## Dependencies
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+Next.js: template includes `'use client'`. Optional in `Question.tsx`:
+
+```tsx
+const RankOrderScale = dynamic(() => import('./RankOrderScale').then(m => ({ default: m.RankOrderScale })), {
+  ssr: false,
+  loading: () => <p>Loading rank order…</p>,
+});
+```
+
+## SDK wiring
+
+```typescript
+import {
+  getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+} from '@explorer02/cfm-survey-sdk';
+
+// Question.tsx — filter options + normalize answer
+const rankOrderQuestion = {
+  ...question,
+  options: getVisibleRankOrderOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues),
+};
+<RankOrderScale
+  question={rankOrderQuestion}
+  selectedValue={normalizeRankOrderAnswers(selectedValue)}
+  onSelect={onSelect}
+/>
+```
+
+Answer shape: `RankOrderAnswers` = `Record<optionId, rank>` (1-based).
+
+## Interaction modes
 
 ### Dropdown (`interactionMode: 'dropdown'`)
 
 | Element | Behavior |
 |---------|----------|
 | Rank select | `-` (unassigned) or `1..N` per option row |
-| Duplicate ranks | Selecting rank R on option A clears R from any other option |
-| Layout | Rank select on left, option content on right |
+| Duplicate ranks | `assignRankWithoutDuplicates` clears rank R from other options |
+| Layout | Rank select left, option content right |
 
-### Drag and Drop (`interactionMode: 'dragAndDrop'`)
+### Drag and drop (`interactionMode: 'dragAndDrop'`)
 
 | Element | Behavior |
 |---------|----------|
-| Drag handle | Six-dot grip on left; pointer + keyboard sensors |
+| Drag handle | Six-dot grip; `PointerSensor` + `KeyboardSensor` |
 | Rank badge | Circular badge showing 1-based position |
-| Reorder | List order determines rank; smooth transform during drag |
-| Up/Down buttons | Keyboard fallback on right side of each row |
+| Reorder | List order → `buildRankOrderFromOrderedOptionIds(orderedIds)` |
+| Up/Down | Keyboard fallback; disabled on first/last |
+
+## Implementation Recipe — dnd-kit
+
+```typescript
+const sensors = useSensors(
+  useSensor(PointerSensor),
+  useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+);
+
+const handleDragEnd = (event: DragEndEvent) => {
+  const { active, over } = event;
+  if (!over || active.id === over.id) return;
+  const oldIndex = orderedOptionIds.indexOf(String(active.id));
+  const newIndex = orderedOptionIds.indexOf(String(over.id));
+  if (oldIndex === -1 || newIndex === -1) return;
+  onSelect(buildRankOrderFromOrderedOptionIds(arrayMove(orderedOptionIds, oldIndex, newIndex)));
+};
+```
+
+Wrap list in `<DndContext collisionDetection={closestCenter}>` + `<SortableContext strategy={verticalListSortingStrategy}>`.
 
-## Option Display Variants
+Copy full implementation from [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx).
+
+## Option display
 
 | `optionDisplay` | Render |
 |-----------------|--------|
-| `textOnly` | Full-width text label only |
-| `imageOnly` | Large square thumbnail only (no label) |
-| `textAndImage` | Thumbnail + text label side by side |
-
-Use `dangerouslySetInnerHTML` for option labels (HTML from builder).
+| `textOnly` | Label via `dangerouslySetInnerHTML` |
+| `imageOnly` | Square thumbnail; prefer `option.imageUrl` over `previewImageUrl` |
+| `textAndImage` | Thumbnail + label side by side |
 
 ## Validation UX
 
-- Required + `requireRankAll`: every visible option must have a unique rank from 1..N
+- Required + `requireRankAll`: every visible option unique rank 1..N
 - Required + not `requireRankAll`: at least one visible option ranked
-- SDK surfaces `validationError` on the question shell — show the standard error banner
+- Show `validationError` from question shell
 
 ## Styling
 
-Match MCQ card styling:
+- Border `#e5e5e5`, optional `#e20074` when ranked
+- Rank badge: `#fdf2f8` bg, `#e20074` text
+
+## Logic
+
+RANK_ORDER operators (ranked as/above/below) — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
+## Agent checklist
 
-- Border: `#e5e5e5` default, `#e20074` when actively ranked (optional highlight)
-- Background hover: `hover:bg-gray-50/50`
-- Rank badge: `#fdf2f8` background, `#e20074` text
+- [ ] Copied `templates/RankOrderScale.tsx` (or equivalent dnd-kit + dropdown)
+- [ ] `@dnd-kit/*` in package.json when survey has RANK_ORDER
+- [ ] `getVisibleRankOrderOptionsForAnswers` + `normalizeRankOrderAnswers`
+- [ ] `option.imageUrl` before `previewImageUrl`
+- [ ] No client-side re-shuffle when `shuffleOptions` is true
+- [ ] No stub placeholder text
 
-## Accessibility
+## Wizard customization (Phase 5 — required)
 
-- Each rank select: `aria-label="Rank for {option label}"`
-- Drag handle: `aria-label="Drag to reorder {option label}"`
-- Up/Down: disabled on first/last item
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Rank badge | `--cfm-rank-badge-bg`, `--cfm-rank-badge-color` | Drag handle / rank number |
+| Option border | `--cfm-rank-option-border` | List item cards |
 
-## Do Not
+### Wizard checklist
 
-- Store ranks in local component state without syncing to `onSelect`
-- Submit option labels — submit rank numbers via SDK formatter only
-- Hardcode logic operators in the client — all conditions are SDK-evaluated
+- [ ] Rank badges and option borders use `--cfm-rank-*` vars

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

@@ -1,9 +1,11 @@
 # UI Specifications — Reference Implementation Guide
 
 > **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx).
-> **For monorepo devs:** Reference client at `apps/client/src/components/` aligns with SDK types — trust `03-ui-specs/`, `templates/Question.tsx`, and exported types.
+> **Shared lib utilities** (NPS colors, custom fields, heatmap coords) live in [`templates/`](../templates/) — see [`client-lib-folder.md`](../00-integration/client-lib-folder.md), not in this ui-specs folder.
 > Read the spec for **each question type present** in the fetched survey before writing React code.
 
+> **Wizard customization:** When the client may use the web wizard, hardcoded hex in § Design Tokens below are **defaults only**. Wire `var(--cfm-*)` per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md) — especially `--cfm-matrix-selected` (cell annulus) and `--cfm-input-focus-ring` (outer border + inner dot). Portable scale templates in `docs/templates/` are layout/logic baselines; extend with `selectionStyles.ts` + `labelStyles.ts` for live preview.
+
 ## How to Read a UI Spec
 
 Each file in this folder follows the same structure:
@@ -38,17 +40,19 @@ Each file in this folder follows the same structure:
 | Spec file | Reference component | `question.type` |
 |-----------|---------------------|-----------------|
 | [00-question-shell.md](00-question-shell.md) | `Question.tsx` | All (wrapper) |
-| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `nps` |
-| [02-radio.md](02-radio.md) | `Question.tsx` inline | `mcq` |
-| [03-text.md](03-text.md) | `Question.tsx` inline | `text_input` |
-| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `csat` |
+| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `NPS_SCALE` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `MCQ` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `TEXTFIELD` |
+| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `CSAT_MATRIX` |
 | [05-rating-scale.md](05-rating-scale.md) | `RatingScale.tsx` | `star_rating` |
 | [06-slider.md](06-slider.md) | `CustomSliderTrack.tsx` | `slider` |
 | [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `cfm_matrix` |
 | [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | `rating_matrix` |
 | [09-slider-matrix.md](09-slider-matrix.md) | `SliderMatrixScale.tsx` | `slider_matrix` |
 | [10-file-upload.md](10-file-upload.md) | `FileUploadScale.tsx` | `file_upload` |
-| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `text_and_media` |
+| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `TEXT_AND_MEDIA` |
+| [13-heatmap.md](13-heatmap.md) | `HeatmapScale.tsx` | `HEATMAP` |
+| [14-rank-order.md](14-rank-order.md) | `RankOrderScale.tsx` | `RANK_ORDER` |
 | [12-survey-chrome.md](12-survey-chrome.md) | `SurveyPage.tsx` + chrome | Shell |
 | [shared/custom-slider-track.md](shared/custom-slider-track.md) | `CustomSliderTrack.tsx` | Primitive |
 | [shared/matrix-dropdown.md](shared/matrix-dropdown.md) | `MatrixDropdown.tsx` | Primitive |
@@ -73,7 +77,7 @@ Use accent colors from SDK options — never invent colors for NPS:
 
 ## When to Read
 
-After Phase 3 in [`index.md`](../index.md), for each question in the fetched survey:
+After Phase 3 in [`index.md`](../index.md) and [`agent-execution-flow.md`](../00-integration/agent-execution-flow.md), for each question in the fetched survey:
 
 1. Read [`02-reference/question-types/`](../02-reference/question-types/) for data shape
 2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `questionTypes.{type}.uiSpec`)

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -1,52 +1,45 @@
 # UI Spec: Custom Slider Track (shared primitive)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CustomSliderTrack.tsx`
-> **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
+> **Portable template:** copy [`templates/CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
+> **Used by:** `SliderMatrixScale`, `CsatMatrixScale` (graphics), matrix `displayStyle: graphics`
+
+## Scale column labels (Day 19 — CRITICAL)
+
+Matrix rows must pass **`tickLabels` from `scaleColumns[].label`** (filtered to visible columns):
+
+```typescript
+const tickLabels = visibleScaleColumns.map(col => col.label);
+<CustomSliderTrack tickLabels={tickLabels} ticks={tickLabels.length} ... />
+```
+
+Tooltip shows stripped HTML from `tickLabels[tickIndex]`; without labels, tooltips fall back to numeric value only.
 
 ## Layer Architecture
 
 ```
-1. Gray inactive track (#e5e7eb, 4px height)
-2. Magenta fill bar (width = percentage%, #e20074 or #9ca3af if disabled)
-3. Tick marks (1px × 8px at ticks positions)
-4. Invisible <input type="range"> overlay (opacity 0, full hit area)
-5. Visual thumb: circle OR emoji (sliderType === 'graphics')
-6. Tooltip bubble on hover/drag (#1f2937 bg, rounded value)
+1. Gray inactive track (#e5e7eb, 4px)
+2. Magenta fill bar (percentage%, #e20074 or #9ca3af if disabled)
+3. Tick marks at column positions
+4. Invisible <input type="range"> overlay
+5. Thumb: circle OR emoji (sliderType === 'graphics')
+6. Tooltip on hover/drag (#1f2937)
 ```
 
 ## Props
 
 | Prop | Role |
 |------|------|
-| `min`, `max`, `htmlStep` | Range input bounds |
+| `min`, `max`, `htmlStep` | Range bounds |
 | `value` | Current position |
-| `disabled` | Gray theme, opacity 0.5, no interaction |
-| `displayValues` | Reserved — tooltip always shows on hover/drag in client |
-| `hasSelectedValue` | Reserved |
-| `sliderType: 'graphics'` | Emoji thumb via client-side react-icons |
-| `ticks` | Discrete tick count + emoji index scale |
-| `reverseScaleOrder` | Flip emoji index calculation |
-
-## Interactive States
-
-| State | Thumb | Tooltip |
-|-------|-------|---------|
-| Default | White circle, 2.5px magenta border | Hidden |
-| Hover/drag | Pink glow ring `rgba(226,0,116,0.2)` | Dark bubble with `Math.round(value)` |
-| Disabled | Gray border, opacity 0.5 | Hidden |
-| Graphics | Emoji at percentage position | Same tooltip |
-
-## Emoji Index Formula
-
-```typescript
-const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
-const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
-// Map displayIdx to react-icons emoji — proportional mapping is client-implemented (not an SDK export)
-```
+| `disabled` | Gray theme, opacity 0.5 |
+| `sliderType: 'graphics'` | Emoji thumb via `surveyUiIcons.getEmojiForIndex` |
+| `ticks` | Discrete tick count |
+| **`tickLabels`** | **Column labels for tooltip + graphics index** |
+| `reverseScaleOrder` | Flip emoji index |
 
 ## Agent Checklist
 
-- [ ] 4-layer overlay with invisible range input
+- [ ] Copy portable template or match layer stack
+- [ ] Always pass `tickLabels` from matrix `scaleColumns` when available
 - [ ] Tooltip on hover AND drag
-- [ ] Graphics mode emoji thumb
-- [ ] Transition disabled while dragging
+- [ ] Graphics emoji thumb with `reverseScaleOrder` support

package/templates/docs/03-ui-specs/shared/matrix-dropdown.md

@@ -1,6 +1,6 @@
 # UI Spec: Matrix Dropdown (shared primitive)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/MatrixDropdown.tsx`
+> **Implement from this spec.** Portable template: `docs/templates/MatrixDropdown.tsx`
 > **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
 
 ## Modes