@explorer02/cfm-survey-sdk 0.1.9 → 0.2.1

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -0,0 +1,102 @@
+# UI Spec: Question Shell (`Question.tsx`)
+
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy this dispatcher verbatim
+> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs — implement from this spec)
+> **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
+> **Component blueprint:** `01-components/02-question.md`
+> **Required files:** `00-integration/component-checklist.md`
+
+## Matrix subType Warning (CRITICAL)
+
+Routing on `question.type === 'matrix'` **alone renders nothing**. You MUST branch on `subType`:
+
+- `CFM_MATRIX` → `LikertMatrixScale`
+- `CSAT_MATRIX` | `RATING_MATRIX` → `CsatMatrixScale`
+
+Never use a `default` fallback that shows `"not yet implemented"` — create the scale components listed in the checklist.
+
+## Config Inventory (QuestionBase)
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `id` | ✅ | `section id={question.id}` — required for scroll-to-error |
+| `text` | ✅ | Heading via `dangerouslySetInnerHTML` |
+| `description` | ✅ | Optional HTML block below title |
+| `required` | ✅ | Red `*` after title (`text-red-500`) |
+| `requiredErrorMessage` | ✅ | Shown via SDK validation in error banner |
+| `questionNumber` | ❌ | Not rendered in reference client |
+| `containerMediaUrl` | ❌ | Not rendered on generic questions |
+
+## Layout Anatomy
+
+```
+┌─ section (rounded-xl border border-gray-200 bg-white p-6 shadow-sm) ─────┐
+│  h2: question.text (HTML) + red * if required                           │
+│  [optional description HTML]                                            │
+│  ┌─ type-specific scale (see per-type specs) ─────────────────────┐   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│  [validation error banner if validationError prop]                      │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Dispatcher Routing
+
+| `question.type` | Condition | Component |
+|-----------------|-----------|-----------|
+| `rating` | — | `RatingScale` + label row in Question |
+| `radio` | — | Inline card radios in Question |
+| `text` | — | Inline textarea in Question |
+| `csat` | — | `CsatScale` + min/max labels in Question |
+| `matrix` | `CSAT_MATRIX` \| `RATING_MATRIX` | `CsatMatrixScale` |
+| `matrix` | `CFM_MATRIX` | `LikertMatrixScale` |
+| `slider_matrix` | — | `SliderMatrixScale` |
+| `file_upload` | — | `FileUploadScale` |
+| `text_and_media` | `mediaUrl` present | Inline media in Question |
+| `slider` | — | ❌ Not routed — see `06-slider.md` |
+| `rating_scale` | — | ❌ Not routed — see `05-rating-scale.md` |
+
+## Label Positioning (rating)
+
+Rendered in Question before `RatingScale`:
+
+```tsx
+// midLabel CSS left:
+left: `${(midLabelIndex / (options.length - 1)) * 100}%`
+// with -translate-x-1/2 for centering
+```
+
+minLabel: `absolute left-0`, maxLabel: `absolute right-0`, container `relative h-6 text-xs font-semibold text-gray-500`.
+
+## Label Positioning (csat)
+
+minLabel / maxLabel: `flex justify-between text-xs font-semibold text-gray-500` above `CsatScale`.
+
+## Validation Error Banner
+
+```tsx
+className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4"
+// text: text-[13px] font-bold text-gray-900
+```
+
+## Props Contract
+
+```typescript
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  onSelect: (value: AnswerValue) => void;
+};
+```
+
+Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.
+
+## Agent Checklist
+
+- [ ] `id={question.id}` on outermost `<section>`
+- [ ] HTML rendering for text and description
+- [ ] Copied from `templates/Question.tsx` — no stub/default fallback branches
+- [ ] Matrix routes by `subType`, not type alone
+- [ ] `slider_matrix` → `SliderMatrixScale`; `file_upload` → `FileUploadScale`
+- [ ] Validation error banner below scale
+- [ ] Rating/csat endpoint labels positioned per formulas above

package/templates/docs/03-ui-specs/01-rating.md

@@ -0,0 +1,80 @@
+# UI Spec: NPS Rating (`type: 'rating'`)
+
+> **Reference:** `apps/client/src/components/RatingScale.tsx` + label row in `Question.tsx`
+> **SDK type:** `RatingQuestion` — `fetchSurvey/types/rating.ts`
+> **Component blueprint:** `01-components/03-rating-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `options[]` | ✅ | Badge row + radio row (dual layer) |
+| `options[].color` | ✅ | Badge background; fallback `#e20074` |
+| `options[].label` | ✅ | Displayed in badge |
+| `options[].value` | ✅ | Selection value |
+| `minLabel` | ✅ | Rendered in Question.tsx above scale |
+| `midLabel` | ✅ | Absolute positioned in Question.tsx |
+| `maxLabel` | ✅ | Absolute positioned in Question.tsx |
+| `midLabelIndex` | ✅ | Mid label `left` percentage |
+| `reverseScaleOrder` | ❌ | Document for agents when SDK sends true |
+| `buttonVariant` | ❌ | Client always uses dual-layer radio layout |
+
+## Layout Anatomy
+
+```
+[minLabel]              [midLabel @ %]              [maxLabel]
+┌──┬──┬──┬── ... ──┬──┐  ← Row 1: colored badges (NOT clickable)
+│0 │1 │2 │3 │ ...  │10│     grid repeat(options.length), h-5 w-5 sm:h-6 w-6
+└──┴──┴──┴── ... ──┴──┘     rounded-[3px], white bold text, option.color bg
+┌──────────────────────────────────────────────┐
+│  ○  ○  ●  ○  ...  ○                          │  ← Row 2: gray track bg-[#f2f2f2]
+└──────────────────────────────────────────────┘     h-11 sm:h-12, rounded-md
+         ↑ selected cell: inner bg-[#fbe8f3]
+           radio: border-[4px] border-[#e20074] bg-white
+```
+
+## Config Decision Tree
+
+```
+rating
+└── RatingScale (always dual-layer in reference client)
+    ├── Row 1: display-only colored badges
+    └── Row 2: sr-only radio + custom circle per cell
+```
+
+If `buttonVariant === 'numbered'` (SDK gap): badges become clickable buttons instead — not in reference client.
+
+If `reverseScaleOrder`: reverse `options` array before mapping both rows.
+
+## Interactive States
+
+| State | Badge row | Track cell | Radio circle |
+|-------|-----------|------------|--------------|
+| Default | Full color | Transparent inner | `border-2 border-gray-300` |
+| Hover | — | `hover:bg-gray-200/40` | — |
+| Selected | Unchanged | `bg-[#fbe8f3]` | `border-[4px] border-[#e20074]` |
+
+## Tooltips
+
+Recommended: `title={option.label}` on each track `<label>`. Not in reference client yet.
+
+## Answer Mutation
+
+```typescript
+onSelect(option.value) // number
+// → onAction CHANGE { questionId, value: number }
+```
+
+## Accessibility
+
+- `role="radiogroup"` on wrapper
+- Native `<input type="radio" className="sr-only">` per cell
+- `name={questionId}` groups radios
+
+## Agent Checklist
+
+- [ ] Two-row grid with `gridTemplateColumns: repeat(options.length, 1fr)`
+- [ ] Badges use `option.color`, not hardcoded NPS colors unless option lacks color
+- [ ] Only track row is clickable
+- [ ] min/mid/max labels in Question wrapper with midLabelIndex formula
+- [ ] Selected state: pink inner track + thick magenta radio ring

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

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

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

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

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'`)
+
+> **Implement from this spec** (npm installs). Monorepo 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'`)
+
+> **Implement from this spec** (npm installs). Monorepo 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'`)
+
+> **Implement from this spec** (npm installs). Monorepo 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