@explorer02/cfm-survey-sdk 0.1.9 → 0.2.0

package/templates/docs/03-ui-specs/04-csat.md

@@ -0,0 +1,57 @@
+# UI Spec: CSAT (`type: 'csat'`)
+
+> **Reference:** `apps/client/src/components/CsatScale.tsx`
+> **SDK type:** `CsatQuestion` — `fetchSurvey/types/csat.ts`
+> **Component blueprint:** `01-components/04-csat-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `options[]` | ✅ | Scale buttons or dropdown options |
+| `buttonType` | ✅ partial | Branches below |
+| `labelPosition` | ✅ | `'top'` → flex-col-reverse; `'hidden'` → no label |
+| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
+| `hasNotApplicable` | ❌ | N/A option in options array still renders |
+| `reverseScaleOrder` | ❌ | Document: reverse options before map |
+
+## Config Decision Tree
+
+```
+csat
+├── buttonType === 'dropdown'
+│   └── Native <select>, placeholder "Select an option"
+│       └── Parse value 'null' → null
+└── else (emoji | star | numbered | number | default)
+    └── flex flex-wrap gap-3 buttons
+        ├── emoji → getEmojiForIndex(index, scaleLength)
+        ├── star → CsatStarIcons filled/empty; labels hidden
+        ├── numbered/number → mono font value
+        └── default → bold value or 'N/A' if null
+```
+
+## Interactive States
+
+| State | Border | Background | Transform |
+|-------|--------|------------|-----------|
+| Default | `border-gray-200` | `white` | scale-100 |
+| Hover | `border-gray-300` | `hover:bg-gray-50` | — |
+| Selected | `border-[#e20074]` | `#fdf2f8` | `scale-110` |
+| Star mode | transparent | transparent | no border/bg on button |
+
+## Tooltips
+
+Recommended: `title={option.label}` on each button. Not in reference client.
+
+## Answer Mutation
+
+```typescript
+onSelect(string | number | null)
+```
+
+## Agent Checklist
+
+- [ ] Dropdown branch with magenta focus ring
+- [ ] Emoji/star/numbered branches per decision tree
+- [ ] `labelPosition` controls label above/below/hidden
+- [ ] Implement `reverseScaleOrder` and standalone `hasNotApplicable` (SDK gaps)

package/templates/docs/03-ui-specs/05-rating-scale.md

@@ -0,0 +1,49 @@
+# UI Spec: Rating Scale (`type: 'rating_scale'`)
+
+> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CsatScale.tsx` patterns
+> **SDK type:** `RatingScaleQuestion` — `fetchSurvey/types/ratingScale.ts`
+> **Component blueprint:** `01-components/03-rating-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `options[]` | ❌ gap | Star/emoji buttons (no NPS colors) |
+| `scaleStyle` | ❌ gap | `'star'` or `'emoji'` |
+| `minLabel` / `midLabel` / `maxLabel` | ❌ gap | Same formulas as NPS in Question shell |
+| `midLabelIndex` | ❌ gap | `(midLabelIndex / (options.length - 1)) * 100`% |
+| `reverseScaleOrder` | ❌ gap | Reverse options before render |
+
+## Expected UI (from CsatScale + rating labels)
+
+```
+[minLabel]     [midLabel @ %]     [maxLabel]
+┌────┬────┬────┬────┬────┐
+│ ★  │ ★  │ ★  │ ★  │ ★  │  scaleStyle: 'star'
+└────┴────┴────┴────┴────┘
+  OR emoji row from getEmojiForIndex when scaleStyle: 'emoji'
+```
+
+Reuse CsatScale selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
+
+## Config Decision Tree
+
+```
+rating_scale
+├── scaleStyle === 'star' → CsatStarIcons per option
+├── scaleStyle === 'emoji' → getEmojiForIndex
+└── else → numbered badges (no option.color)
+```
+
+## Answer Mutation
+
+```typescript
+onSelect(number)
+```
+
+## Agent Checklist
+
+- [ ] Add dispatcher branch in Question for `rating_scale`
+- [ ] No traffic-light NPS colors on options
+- [ ] min/mid/max labels with midLabelIndex formula
+- [ ] Match CsatScale interactive states

package/templates/docs/03-ui-specs/06-slider.md

@@ -0,0 +1,42 @@
+# UI Spec: Standalone Slider (`type: 'slider'`)
+
+> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CustomSliderTrack.tsx`
+> **SDK type:** `SliderQuestion` — `fetchSurvey/types/slider.ts`
+> **Component blueprint:** `01-components/09-custom-slider-track.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `min` / `max` / `step` | ❌ gap | Track range |
+| `defaultValue` | ❌ gap | Initial thumb position |
+| `minLabel` / `maxLabel` | ❌ gap | End labels above track |
+| `enableInputBox` | ❌ gap | See SliderMatrixScale input pattern |
+| `displayValues` | ❌ gap | Pass to CustomSliderTrack |
+
+## Layout Anatomy
+
+```
+[minLabel]                              [maxLabel]
+┌──────────────────────────────────────────────────┐
+│  ───●────────────────  (CustomSliderTrack)      │
+└──────────────────────────────────────────────────┘
+[optional number input + steppers if enableInputBox]
+```
+
+## Reference Patterns
+
+Copy from [`09-slider-matrix.md`](09-slider-matrix.md) single-row layout and [`shared/custom-slider-track.md`](shared/custom-slider-track.md).
+
+## Answer Mutation
+
+```typescript
+onSelect(number)
+```
+
+## Agent Checklist
+
+- [ ] Add Question dispatcher for `slider`
+- [ ] CustomSliderTrack with min/max/step
+- [ ] Optional input box with clamp min/max
+- [ ] End labels flex justify-between

package/templates/docs/03-ui-specs/07-matrix-cfm.md

@@ -0,0 +1,66 @@
+# UI Spec: CFM Matrix (`type: 'matrix'`, `subType: 'CFM_MATRIX'`)
+
+> **Reference:** `apps/client/src/components/LikertMatrixScale.tsx`
+> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **Component blueprint:** `01-components/06-likert-matrix-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `rows[]`, `columns[]` | ✅ | Grid / carousel / dropdown data |
+| `matrixFormat` | ✅ | Orchestrator routing |
+| `answerType` | ✅ | `'multiple'` → checkboxes |
+| `matrixType: 'bipolar'` | ✅ | 25% left + 25% right columns |
+| `labels[]` | ✅ | Anchor labels above scale |
+| `transposeTable` | ✅ | Swap row/col iteration |
+| `repeatScale` | ✅ | Re-render header per row |
+| `enableScale` | ✅ | Show/hide column header row |
+| `hasNotApplicable` | ✅ | N/A column with mutex |
+
+## Config Decision Tree
+
+```
+CFM_MATRIX
+├── matrixFormat === 'dropdown' → LikertMatrixDropdownLayout (MatrixDropdown per row)
+├── matrixFormat === 'carousel' → LikertMatrixCarouselLayout (one row, prev/next, blue dots)
+└── else → LikertMatrixGridLayout
+    ├── transposeTable ? columns×rows : rows×columns
+    ├── repeatScale ? header per row : single header
+    ├── enableScale ? column headers : hidden
+    └── matrixType === 'bipolar' ? 25% | scale | 25% layout
+```
+
+## Interactive Behaviors
+
+| Behavior | Condition | Action |
+|----------|-----------|--------|
+| Click selected radio again | single-select grid/carousel | Clear row (`undefined`) |
+| N/A selected | any | Other cols opacity 0.4, disabled |
+| Multi N/A | answerType multiple | Sets `[null]` exclusively |
+| Multi toggle | answerType multiple | Add/remove from array |
+
+## Grid Layout
+
+- Row label column: `180px` (likert) or `25%` (bipolar)
+- Zebra rows: even rows `rgba(249,250,251,0.8)`
+- Native inputs: `accentColor: #e20074`, 18×18px
+
+## Carousel
+
+- Blue active dot: `#2563eb` (Likert only)
+- Card: white, border, shadow, centered row text
+
+## Answer Mutation
+
+```typescript
+onSelect(MatrixAnswerMap) // Record<rowId, value | value[] | null>
+```
+
+## Agent Checklist
+
+- [ ] All three matrixFormat branches
+- [ ] transposeTable + repeatScale + enableScale
+- [ ] Bipolar 25/50/25 layout with rightText
+- [ ] Single-select deselect on re-click
+- [ ] N/A mutex with opacity 0.4

package/templates/docs/03-ui-specs/08-matrix-csat-rating.md

@@ -0,0 +1,65 @@
+# UI Spec: CSAT / Rating Matrix (`subType: 'CSAT_MATRIX' | 'RATING_MATRIX'`)
+
+> **Reference:** `apps/client/src/components/CsatMatrixScale.tsx`
+> **SDK type:** `MatrixQuestion` — `fetchSurvey/types/matrix.ts`
+> **Component blueprint:** `01-components/05-csat-matrix-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `buttonType` | ✅ | Grid vs vertical list routing |
+| `matrixFormat` | ✅ | carousel vs standard |
+| `hasNotApplicable` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
+| `labels[]` | ✅ | Anchor row above columns |
+| `columns[].color` | ✅ | RATING_MATRIX badge colors |
+
+## Config Decision Tree
+
+```
+CSAT_MATRIX | RATING_MATRIX
+├── matrixFormat === 'carousel' → CsatMatrixCarousel
+├── buttonType in (dropdown, selectbox, radio) → CsatMatrixVerticalList
+│   ├── dropdown → MatrixDropdown placeholder "Select..."
+│   ├── selectbox → full-width cards #fdf2f8 selected
+│   └── else → card radio list
+└── else → CsatMatrixGrid
+    ├── emoji → getEmojiForIndex + hover scale + ring when selected
+    ├── star → opacity 0.5 unselected; filled/empty icons
+    ├── numbered → 40×40 badge; selected magenta fill
+    └── graphics → CustomSliderTrack per row (not in grid — carousel only)
+```
+
+## Grid Structure
+
+- Row label: `180px` fixed column
+- N/A column: `56px` when `hasNotApplicable`
+- Alternating row backgrounds
+- Column headers OR `labels[]` anchor row with percentage positioning
+
+## Carousel
+
+- Pink active dot expands: `20px × 8px` vs `8px` inactive
+- Column labels below cells
+- Emoji tooltip via hover state (`hoveredCell`)
+- Graphics mode: slider maps column index
+
+## Tooltips
+
+`title={col.label}` recommended on grid cells (emoji hover uses scale transform).
+
+## Answer Mutation
+
+```typescript
+onSelect(MatrixAnswerMap)
+// hasNotApplicable: null for N/A; undefined clears
+```
+
+## Agent Checklist
+
+- [ ] scaleColumns = columns.filter(c => c.value !== null)
+- [ ] All buttonType × matrixFormat branches
+- [ ] reverseScaleOrder on emoji/star/numbered
+- [ ] Carousel pink dot indicators
+- [ ] Vertical selectbox cards match standalone radio styling

package/templates/docs/03-ui-specs/09-slider-matrix.md

@@ -0,0 +1,61 @@
+# UI Spec: Slider Matrix (`type: 'slider_matrix'`)
+
+> **Reference:** `apps/client/src/components/SliderMatrixScale.tsx`
+> **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`
+> **Component blueprint:** `01-components/07-slider-matrix-scale.md`
+> **Shared:** [`shared/custom-slider-track.md`](shared/custom-slider-track.md)
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `rows[]` (min/max/step) | ✅ | Per-row slider range |
+| `labels[]` | ✅ | Header anchor labels |
+| `tickValues[]` | ✅ | Colored badges above track |
+| `ticks` | ✅ | Discrete marks + htmlStep |
+| `sliderType: 'graphics'` | ✅ | Plain text tick labels; emoji thumb |
+| `enableInputBox` | ✅ | 80px input + stepper buttons |
+| `displayValues` | ✅ | Passed to CustomSliderTrack |
+| `enableNotApplicable` | ✅ | Checkbox; value `'N/A'` string |
+
+## Layout Anatomy
+
+```
+[header: labels[] + tickValues badges OR computed marks]
+┌─ row band (#f3f4f6, rounded-xl) ─────────────────────────────┐
+│ 25% statement │ CustomSliderTrack │ 25% rightText? │ input? │ N/A? │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Header Tick Positioning
+
+```typescript
+percentage = ((tv.value - min) / (max - min)) * 100
+sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100
+// Colored badge: tv.color bg, white text, rounded 4px
+// graphics: plain text label instead of colored badge
+```
+
+## N/A Behavior
+
+- Checked → `rowVal === 'N/A'`; slider disabled, input grayed
+- Unchecked → reset to `defaultValue ?? min`
+
+## Input Box
+
+- Clamp to row.min / row.max on change
+- Steppers use `htmlStep` increment/decrement
+
+## Answer Mutation
+
+```typescript
+onSelect(Record<string, number | null | 'N/A'>)
+```
+
+## Agent Checklist
+
+- [ ] Shared header from first row min/max/step
+- [ ] Gray row bands with 25% statement columns
+- [ ] CustomSliderTrack per row with correct htmlStep
+- [ ] tickValues colored badges (non-graphics)
+- [ ] N/A mutex disables slider + input

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -0,0 +1,54 @@
+# UI Spec: File Upload (`type: 'file_upload'`)
+
+> **Reference:** `apps/client/src/components/FileUploadScale.tsx`
+> **SDK type:** `FileUploadQuestion` — `fetchSurvey/types/fileUpload.ts`
+> **Component blueprint:** `01-components/08-file-upload-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `uploadMessage` | ✅ | HTML in dropzone (bold 16px) |
+| `supportedFileFormats` | ✅ | Validation + accept attribute |
+| `maxFileCount` | ✅ | Total file limit |
+| `fileSizeLimit` | ✅ | MB limit |
+| `fileSizeLimitType` | ✅ | `PER_FILE` or `IN_TOTAL` |
+
+## Layout Anatomy
+
+```
+[uploadMessage HTML in dashed dropzone]
+  File limit: N; File size limit: XMB/file|in total; Supports: ...
+[local error banner — red if validation fails]
+[file list cards: icon, name, size, remove ×]
+```
+
+## Interactive States
+
+| State | Border | Background |
+|-------|--------|------------|
+| Default | `#d1d5db` dashed | `#f9fafb` |
+| Hover | `#e20074` | `#fdf2f8` |
+| Drag active | `#e20074` | `#fdf2f8` |
+
+## Local Validation (before SDK)
+
+1. Max file count exceeded
+2. Unsupported extension
+3. PER_FILE size exceeded
+4. IN_TOTAL cumulative size exceeded
+
+Error banner: `#fee2e2` bg, `#b91c1c` text.
+
+## Answer Mutation
+
+```typescript
+onSelect(File[] | undefined) // undefined when all removed
+```
+
+## Agent Checklist
+
+- [ ] Hidden `<input type="file">` triggered by dropzone click
+- [ ] Drag enter/over/leave/drop handlers
+- [ ] Dynamic constraints line in dropzone
+- [ ] File list with remove button (hover red)

package/templates/docs/03-ui-specs/11-text-and-media.md

@@ -0,0 +1,49 @@
+# UI Spec: Text and Media (`type: 'text_and_media'`)
+
+> **Reference:** `apps/client/src/components/Question.tsx` (inline)
+> **SDK type:** `TextAndMediaQuestion` — `fetchSurvey/types/textAndMedia.ts`
+> **Component blueprint:** `01-components/02-question.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `mediaUrl` | ✅ | Required to render media block |
+| `mediaMimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
+| `mediaTitle` | ✅ | Caption below media, centered gray text |
+| `mediaAlignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
+| `mediaSize` | ✅ | Width `%` on media container; default 100% |
+
+No answer input — display-only question.
+
+## Layout Anatomy
+
+```
+[question title + description — standard shell]
+
+┌─ flex container (justify per mediaAlignment) ──────────────┐
+│  ┌─ media block (width: mediaSize%) ──────────────────┐   │
+│  │  <video controls> or <img>                          │   │
+│  │  [optional mediaTitle caption]                      │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Alignment Mapping
+
+| `mediaAlignment` | CSS |
+|------------------|-----|
+| `TOP_CENTER`, `BOTTOM_CENTER` | `justify-center` |
+| `TOP_RIGHT`, `BOTTOM_RIGHT` | `justify-end` |
+| default | `justify-start` |
+
+## Answer Mutation
+
+None — no `onSelect` payload for this type.
+
+## Agent Checklist
+
+- [ ] Render only when `mediaUrl` is present
+- [ ] Video vs image from mime type
+- [ ] `max-w-full rounded-md shadow-sm` on media element
+- [ ] Optional centered caption for `mediaTitle`

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

@@ -0,0 +1,60 @@
+# UI Spec: Survey Chrome
+
+> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`
+
+## SurveyPage — 5-State Machine
+
+| State | Condition | UI |
+|-------|-----------|-----|
+| Loading | `surveyQueryResults.isLoading` | Centered "Loading..." |
+| Error | `surveyQueryResults.error` | Red error message |
+| Empty | `!survey` | "No survey data" |
+| Submitted | `submitSurveyResults.data` | Thank you message |
+| Active | else | Questions + nav |
+
+## Active Layout
+
+```
+Header
+main (max-w-4xl)
+  ProgressBar(progressPercentage)
+  LanguageSelector (hidden if ≤1 language)
+  Questions (space-y-12)
+  Submit error (if any)
+  Nav: Back (if page > 0) + Next/Submit
+Footer
+```
+
+## Navigation Labels
+
+German when `survey.language.startsWith('de')`:
+
+| Action | EN | DE |
+|--------|----|----|
+| Back | Zurück | Back |
+| Next | Weiter | Next |
+| Submit | Absenden | Submit |
+| Submitting | Wird gesendet... | Submitting... |
+
+## Button Tokens
+
+- Back: `border-[#e20074] text-[#e20074] hover:bg-[#fdf2f8]`
+- Primary: `bg-[#e20074] text-white hover:opacity-90`
+
+## ProgressBar
+
+Pink fill bar, `300ms` width transition on `progressPercentage`.
+
+## LanguageSelector
+
+- Hidden when `languages.length <= 1`
+- Focus ring: `#2563eb`
+
+## Agent Checklist
+
+- [ ] All 5 states implemented
+- [ ] `onAction({ type: 'CHANGE' })` wired per question
+- [ ] PREVIOUS / NEXT actions on nav buttons
+- [ ] ProgressBar receives `state.progressPercentage`
+- [ ] Header/Footer on every state branch

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

@@ -0,0 +1,79 @@
+# UI Specifications — Reference Implementation Guide
+
+> **Authoritative source:** [`apps/client/src/components/`](../../../../../../apps/client/src/components/) in the monorepo.
+> Agents must reproduce this UI when building survey apps. Read the spec for each question type present in the fetched survey.
+
+## How to Read a UI Spec
+
+Each file in this folder follows the same structure:
+
+1. **Config inventory** — every SDK field, whether the reference client implements it
+2. **Layout anatomy** — structured ASCII diagram
+3. **Config decision tree** — matches `if/else` branches in reference code
+4. **Interactive states** — default, hover, selected, disabled, focus
+5. **Tooltips & labels** — positioning formulas
+6. **Color tokens** — exact hex values from reference client
+7. **Answer mutation** — `onSelect` / `onAction CHANGE` shape
+8. **Agent checklist**
+
+## Design Tokens (Reference Client)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#e20074` | Borders, rings, dots, slider fill, selected text |
+| Selected bg | `#fdf2f8` | Card options, CSAT buttons, matrix cells |
+| NPS track highlight | `#fbe8f3` | Selected radio cell in NPS track row |
+| NPS track bar | `#f2f2f2` | Gray bar behind NPS radios |
+| Validation border | `#333333` | Error banner |
+| Validation bg | `#d9d9d9` | Error banner |
+| Row band | `#f3f4f6` | Slider matrix row background |
+| Zebra row | `rgba(249,250,251,0.8)` | Matrix alternating rows |
+| Tooltip bg | `#1f2937` | Hover tooltips on emoji/slider |
+| Likert carousel dot (active) | `#2563eb` | LikertMatrix carousel only |
+| CSAT carousel dot (active) | `#e20074` | CsatMatrix carousel |
+
+## Reference Component Index
+
+| 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` | `rating` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `radio` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `text` |
+| [04-csat.md](04-csat.md) | `CsatScale.tsx` | `csat` |
+| [05-rating-scale.md](05-rating-scale.md) | *(gap — reuse CsatScale patterns)* | `rating_scale` |
+| [06-slider.md](06-slider.md) | *(gap — reuse CustomSliderTrack)* | `slider` |
+| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `matrix` + CFM |
+| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | CSAT/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` |
+| [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 |
+
+## NPS Traffic-Light Colors
+
+Use `option.color` from SDK — never invent colors:
+
+| Value | Hex |
+|-------|-----|
+| 0 | `#e2001a` |
+| 1 | `#e4251b` |
+| 2 | `#ec610a` |
+| 3 | `#f18b00` |
+| 4 | `#f7b200` |
+| 5 | `#fcd900` |
+| 6 | `#fcd900` |
+| 7 | `#9fca00` |
+| 8 | `#6bb300` |
+| 9 | `#339a00` |
+| 10 | `#008000` |
+
+## When to Read
+
+After Phase 3 in [`index.md`](../index.md), for each question in `state.currentQuestions`:
+
+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) `uiSpecs`)
+3. Cross-check [`config-field-index.md`](../02-reference/config-field-index.md)

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

@@ -0,0 +1,52 @@
+# UI Spec: Custom Slider Track (shared primitive)
+
+> **Reference:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
+
+## 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)
+```
+
+## Props
+
+| Prop | Role |
+|------|------|
+| `min`, `max`, `htmlStep` | Range input 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 `getEmojiForIndex` |
+| `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;
+getEmojiForIndex(displayIdx, ticks || 10)
+```
+
+## Agent Checklist
+
+- [ ] 4-layer overlay with invisible range input
+- [ ] Tooltip on hover AND drag
+- [ ] Graphics mode emoji thumb
+- [ ] Transition disabled while dragging

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

@@ -0,0 +1,38 @@
+# UI Spec: Matrix Dropdown (shared primitive)
+
+> **Reference:** `apps/client/src/components/MatrixDropdown.tsx`
+> **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
+
+## Modes
+
+| `multiple` | Trigger | Selection |
+|------------|---------|-----------|
+| `false` | Single line + chevron | One value; checkmark on selected option |
+| `true` | Tag chips with × | Toggle array; N/A mutex |
+
+## Interactive States
+
+| State | Trigger border | Shadow |
+|-------|----------------|--------|
+| Closed | `#d1d5db` | subtle |
+| Open | `#e20074` | `0 0 0 3px rgba(226,0,116,0.1)` |
+| Option hover | bg `#fdf2f8` | — |
+| Option selected | bg `#fdf2f8`, text `#e20074` | — |
+| N/A mutex (multi) | Other options opacity 0.5, disabled | — |
+
+## N/A Mutex (multi-select)
+
+```typescript
+if (val === null) {
+  if (multiValues.includes(null)) onChange([]);
+  else onChange([null]);
+}
+// When null selected, non-null options disabled
+```
+
+## Agent Checklist
+
+- [ ] Click-outside closes panel
+- [ ] HTML labels via dangerouslySetInnerHTML
+- [ ] Single: close on select
+- [ ] Multi: tag chips removable with ×