@explorer02/cfm-survey-sdk 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer02/cfm-survey-sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/templates/docs/01-sdk-core/08-icons-and-emojis.md

@@ -1,88 +1,56 @@
-# Icons & Emojis — CSAT Visual System
+# Icons & Emojis Architecture
 
-> **Source**: `packages/sdk/src/ui/icons.tsx`
-> **Exports**: `CsatEmojiSet`, `CsatEmojiMapping`, `CsatStarIcons`, `getEmojiForIndex`
+> **Source**: `apps/client/src/components/icons.tsx` (to be created by the agent)
 
-## What It Provides
+## The CSAT Emoji System
 
-Pre-built React elements for CSAT satisfaction faces and star rating icons. These are used by `CsatScale`, `CsatMatrixScale`, and `CustomSliderTrack` components.
+The SDK relies on a specific sequence of sentiment faces for CSAT scales. You MUST implement this mapping in your client application using a library like `react-icons/fa` or raw SVGs.
 
-## Emoji Face System (11-Level)
+### Default 5-Point Mapping
 
-The SDK ships an 11-level sentiment face scale using `react-icons/fa6`:
-
-| Index | Face | Color | Icon |
-|-------|------|-------|------|
-| 1 | Very Angry | `#dc2626` | FaFaceAngry |
-| 2 | Sad | `#e04832` | FaFaceSadTear |
-| 3 | Frown | `#ea580c` | FaFaceFrown |
-| 4 | Open Frown | `#f59e0b` | FaFaceFrownOpen |
-| 5 | Meh | `#eab308` | FaFaceMeh |
-| 6 | Neutral | `#a3a323` | FaFaceMeh |
-| 7 | Smile | `#84cc16` | FaFaceSmile |
-| 8 | Beam | `#65a30d` | FaFaceSmileBeam |
-| 9 | Grin | `#22c55e` | FaFaceGrin |
-| 10 | Wide Grin | `#16a34a` | FaFaceGrinWide |
-| 11 | Star-Struck | `#059669` | FaFaceGrinStars |
-
-## `getEmojiForIndex(index, total)` — Adaptive Mapping
-
-Maps a 0-based column index within a scale of `total` items to the correct face from the 11-level set.
-
-**Curated subsets for common scale lengths:**
-- 3 options → indices [3, 6, 8] from the 11-set
-- 4 options → indices [3, 4, 7, 9]
-- 5 options → indices [3, 4, 6, 7, 9]
-- 6 options → indices [3, 4, 6, 7, 9, 11]
-
-**For other lengths:** Interpolates linearly across the 11-set:
-```typescript
-const percent = index / (total - 1);
-const key = Math.min(11, Math.max(1, Math.round(percent * 10) + 1));
+```tsx
+import { FaRegSmile, FaRegMeh, FaRegFrown, FaRegSmileBeam, FaRegTired } from 'react-icons/fa';
+
+export const CsatEmojiMapping: Record<number | string, JSX.Element> = {
+  1: <FaRegTired className="text-red-500 w-full h-full" />,
+  2: <FaRegFrown className="text-orange-500 w-full h-full" />,
+  3: <FaRegMeh className="text-yellow-500 w-full h-full" />,
+  4: <FaRegSmile className="text-green-500 w-full h-full" />,
+  5: <FaRegSmileBeam className="text-green-600 w-full h-full" />,
+};
 ```
 
-## `CsatEmojiMapping` — Legacy 1–5 Mapping
-
-For standalone 5-point CSAT scales:
-```typescript
-{ 1: Face[1], 2: Face[4], 3: Face[6], 4: Face[8], 5: Face[11] }
-```
+### The `getEmojiForIndex` Helper
 
-## `CsatStarIcons` — Star Rating
+Because some surveys use 3-point, 7-point, or 10-point scales instead of 5, you MUST use a helper function to proportionally map any scale length to the 5 core sentiment faces.
 
-```typescript
-{
-  filled: <FaStar style={{ color: '#e20074', fontSize: '28px' }} />,
-  empty: <FaRegStar style={{ color: '#d1d5db', fontSize: '28px' }} />,
+```tsx
+export function getEmojiForIndex(index: number, totalOptions: number): JSX.Element {
+  const percentage = index / (totalOptions - 1);
+  
+  if (percentage < 0.2) return CsatEmojiMapping[1];
+  if (percentage < 0.4) return CsatEmojiMapping[2];
+  if (percentage < 0.6) return CsatEmojiMapping[3];
+  if (percentage < 0.8) return CsatEmojiMapping[4];
+  return CsatEmojiMapping[5];
 }
 ```
 
-## Usage in Components
-
-```tsx
-import { getEmojiForIndex, CsatStarIcons, CsatEmojiMapping } from '@explorer02/cfm-survey-sdk';
+## The Star Icon System
 
-// CSAT Matrix — dynamic emoji per column
-{columns.map((col, i) => getEmojiForIndex(i, columns.length))}
+For star ratings, you need filled and empty variants:
 
-// CSAT Scale — star rendering
-{options.map((opt, i) => (
-  i < selectedIndex ? CsatStarIcons.filled : CsatStarIcons.empty
-))}
+```tsx
+import { FaStar, FaRegStar } from 'react-icons/fa';
 
-// Standalone CSAT — legacy 1-5 emoji
-{CsatEmojiMapping[optionValue]}
+export const CsatStarIcons = {
+  filled: <FaStar className="text-yellow-400 w-full h-full" />,
+  empty: <FaRegStar className="text-gray-300 w-full h-full" />
+};
 ```
 
-## Important: `buttonType` Determines Rendering
-
-The `CsatQuestion.buttonType` and `MatrixQuestion.buttonType` fields control which icon system to use:
-
-| `buttonType` | Render Style |
-|-------------|-------------|
-| `'emoji'` | Sentiment face icons from `getEmojiForIndex` |
-| `'star'` | Star icons from `CsatStarIcons` |
-| `'numbered'` | Numeric badge buttons (no icons) |
-| `'radio'` | Standard radio circles |
-| `'graphics'` | Continuous slider with emoji thumb |
-| `'dropdown'` | Collapsed select dropdown |
+## Color Mapping System
+For rating matrices and numbered NPS grids, colors are usually provided by the SDK in `option.color`. If not, use standard NPS coloring:
+- **0-6 (Detractors)**: Red/Orange
+- **7-8 (Passives)**: Yellow
+- **9-10 (Promoters)**: Green

package/templates/docs/03-client-components/02-question.md

@@ -14,44 +14,61 @@ type QuestionProps = {
 };
 ```
 
-## Structure
+## Structure & Styling Rules (CRITICAL)
 
-Every question is wrapped in a standard HTML section:
+Every question is wrapped in a standard HTML section. It **MUST** have a border around the entire question block to separate them visually, and it **MUST** handle rich text (HTML) provided by the SDK safely.
 
 ```tsx
-<section id={question.id} className="space-y-4 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
-  {/* 1. Question Text (with required asterisk) */}
-  <h2 className="text-lg font-medium leading-relaxed text-gray-900">
-    <span dangerouslySetInnerHTML={{ __html: question.text }} />
-    {question.required && <span className="text-red-500 ml-1">*</span>}
+<section 
+  id={question.id} 
+  className="space-y-6 rounded-xl border border-gray-200 bg-white p-6 md:p-8 shadow-sm transition-all hover:shadow-md"
+>
+  {/* 1. Question Text (Rich Text with required asterisk) */}
+  <h2 className="text-lg md:text-xl font-semibold leading-relaxed text-gray-900 flex items-start gap-1">
+    {/* dangerouslySetInnerHTML handles strong, em, and link tags from the SDK */}
+    <span dangerouslySetInnerHTML={{ __html: question.text }} className="prose prose-sm max-w-none" />
+    {question.required && <span className="text-[#e20074] shrink-0">*</span>}
   </h2>
   
-  {/* 2. Question Description */}
+  {/* 2. Question Description (Rich Text) */}
   {question.description && (
-    <div className="text-sm text-gray-600 mt-2 leading-relaxed" dangerouslySetInnerHTML={{ __html: question.description }} />
+    <div 
+      className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" 
+      dangerouslySetInnerHTML={{ __html: question.description }} 
+    />
   )}
   
   {/* 3. The Scale Component (Dispatcher switch statement) */}
-  {question.type === 'rating' && <RatingScale ... />}
-  {/* ... other types ... */}
+  <div className="pt-4">
+    {question.type === 'rating' && <RatingScale ... />}
+    {/* ... other types ... */}
+  </div>
   
   {/* 4. Validation Error Banner */}
   {validationError && (
-    <div className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4 text-left">
-      <p className="text-[13px] sm:text-sm font-bold text-gray-900 leading-tight">{validationError}</p>
+    <div className="mt-6 rounded-lg border-l-4 border-l-[#e20074] bg-red-50 p-4">
+      <p className="text-sm font-bold text-gray-900 leading-tight flex items-center gap-2">
+        <span className="text-[#e20074]">⚠</span> {validationError}
+      </p>
     </div>
   )}
 </section>
 ```
 
-**⚠️ CRITICAL**: The wrapper element **MUST** have `id={question.id}` for the scroll-to-error validation to work!
+**⚠️ CRITICAL RULES**:
+1. **DOM ID**: The wrapper element **MUST** have `id={question.id}` for the scroll-to-error validation to work!
+2. **Borders**: The wrapper **MUST** have `border border-gray-200 rounded-xl`.
+3. **Rich Text**: `question.text` and `question.description` MUST be rendered using `dangerouslySetInnerHTML` because the SDK sends formatted HTML. Do not render them as raw strings.
+4. **Spacing**: Use `space-y-6` and `p-6 md:p-8` for generous internal padding.
 
 ## Inline vs Dedicated Components
 
 While complex scales (like Matrix, Slider, FileUpload) get their own dedicated files (e.g. `CsatMatrixScale.tsx`), some simpler types are handled directly inline within `Question.tsx` to reduce boilerplate:
 
-1. **`radio` (MCQ)**: Inline mapping of `<label>` and `<input type="radio">`
-2. **`text`**: Inline `<textarea>`
-3. **`text_and_media`**: Inline `<video>` or `<img>` tag
-
-(See the respective question type docs for the exact rendering guidance for these inline types).
+1. **`radio` (MCQ)**: 
+   - Each option is a card: `border rounded-lg p-4 flex items-center gap-3 cursor-pointer transition-colors`.
+   - Hover state: `hover:border-[#e20074] hover:bg-pink-50`.
+   - Selected state: `border-[#e20074] bg-pink-50`.
+   - Custom radio dot: `<div className={`h-5 w-5 rounded-full border-2 ${isSelected ? 'border-[#e20074]' : 'border-gray-300'} flex items-center justify-center`}><div className={`h-2.5 w-2.5 rounded-full bg-[#e20074] ${isSelected ? 'block' : 'hidden'}`} /></div>`
+2. **`text`**: Inline `<textarea>` or `<input type="text">` with `border-gray-300 focus:border-[#e20074] focus:ring-[#e20074] rounded-lg w-full`.
+3. **`text_and_media`**: Inline `<video>` or `<img>` tag with `rounded-lg`.

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

@@ -3,9 +3,6 @@
 > **Component**: `RatingScale`
 > **Handles**: `type: 'rating'` | `type: 'rating_scale'`
 
-## Role
-Renders numbered badge arrays (for NPS 0-10) or icon arrays (stars/emojis) for satisfaction scales.
-
 ## Props Interface
 ```typescript
 type RatingScaleProps = {
@@ -13,26 +10,82 @@ type RatingScaleProps = {
   options: SurveyOption[];
   selectedValue?: string | number | null | any;
   onSelect: (value: number) => void;
+  // Extracted from question object:
+  minLabel?: string;
+  midLabel?: string;
+  maxLabel?: string;
+  midLabelIndex?: number;
 };
 ```
 
-## Sub-Variants
+## UI Styling & Interaction Rules (CRITICAL)
+
+The UI must exactly match these specifications:
+
+### 1. Square Rounded Buttons
+- Do **NOT** use circles for `rating` badges. Use squares with rounded corners.
+- Base classes: `flex h-10 w-10 sm:h-12 sm:w-12 items-center justify-center rounded-lg text-sm sm:text-base font-medium transition-all duration-200 cursor-pointer`.
 
-### 1. Numbered Badges (NPS / 10-point)
-If `option.color` is present, it's an NPS scale.
-- Map over `options`
-- Render rounded `<button>` for each
-- Use `option.color` as the background color
-- If an option is selected (`selectedValue !== undefined`), apply full opacity to the selected button and dim the unselected ones (`opacity-30`).
+### 2. Colors & Hover States
+- `options` may contain a `color` property (NPS scale). Use it for the background.
+- If no color is provided, use a default gray background.
+- **Unselected State**: `opacity-30` (if any option is selected, dim the others), or just standard opacity with a subtle border.
+- **Hover State**: `hover:scale-105 hover:shadow-md hover:border-[#e20074] hover:border-2`.
+- **Selected State**: 
+  - Apply `opacity-100`.
+  - Apply a strong prominent border: `border-2 border-[#e20074] shadow-md`.
 
-### 2. Star Scale (`question.scaleStyle === 'star'`)
-- Render generic star icons using `CsatStarIcons.filled` and `CsatStarIcons.empty`
-- Use logic: `i < selectedIndex ? filled : empty` (fill all stars up to the selected one).
+### 3. Tooltips
+- Every button **MUST** have `title={option.label}` so users can see the exact semantic meaning (e.g., "Extremely Likely") when hovering over the number '10'.
 
-### 3. Emoji Scale (`question.scaleStyle === 'emoji'`)
-- Render emoji face icons
-- Since options length is variable, use `getEmojiForIndex(i, options.length)` to map the position to the correct sentiment face.
+### 4. Label Positioning
+- Place `minLabel`, `midLabel`, and `maxLabel` underneath the button track.
+- Container for labels: `relative mt-3 h-8 w-full text-xs text-gray-500`.
+- Left label (`minLabel`): `absolute left-0`.
+- Right label (`maxLabel`): `absolute right-0`.
+- Middle label (`midLabel`): `absolute transform -translate-x-1/2` with `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.
 
-## Layout
-- Usually rendered as a `flex` row, `justify-between` or `gap-2` depending on container width.
-- Needs to wrap cleanly on mobile viewports.
+## Implementation Snippet
+
+```tsx
+<div className="w-full">
+  <div className="flex w-full justify-between gap-1 sm:gap-2">
+    {options.map((option, i) => {
+      const isSelected = selectedValue === option.value;
+      const isAnySelected = selectedValue !== undefined && selectedValue !== null;
+      
+      return (
+        <button
+          key={option.id}
+          type="button"
+          onClick={() => onSelect(option.value as number)}
+          title={option.label} // Tooltip required
+          className={`
+            flex h-10 w-10 sm:h-12 sm:w-12 items-center justify-center rounded-lg font-semibold transition-all
+            ${isSelected ? 'border-2 border-[#e20074] scale-105 shadow-md opacity-100 z-10' : 'border border-transparent'}
+            ${!isSelected && isAnySelected ? 'opacity-40' : 'opacity-100'}
+            hover:border-[#e20074] hover:scale-105 hover:opacity-100
+          `}
+          style={{ backgroundColor: option.color || '#f3f4f6', color: '#000000' }}
+        >
+          {option.value}
+        </button>
+      );
+    })}
+  </div>
+  
+  {/* Label Positioning */}
+  <div className="relative mt-3 h-6 w-full text-xs font-medium text-gray-500">
+    {minLabel && <span className="absolute left-0">{minLabel}</span>}
+    {midLabel && (
+      <span 
+        className="absolute transform -translate-x-1/2 text-center"
+        style={{ left: `${(midLabelIndex! / (options.length - 1)) * 100}%` }}
+      >
+        {midLabel}
+      </span>
+    )}
+    {maxLabel && <span className="absolute right-0 text-right">{maxLabel}</span>}
+  </div>
+</div>
+```

package/templates/docs/03-client-components/04-csat-scale.md

@@ -3,9 +3,6 @@
 > **Component**: `CsatScale`
 > **Handles**: `type: 'csat'`
 
-## Role
-Renders satisfaction scales (typically 1-5). Relies heavily on the `buttonType` property to determine the visual rendering style.
-
 ## Props Interface
 ```typescript
 type CsatScaleProps = {
@@ -15,26 +12,68 @@ type CsatScaleProps = {
 };
 ```
 
-## Rendering by `buttonType`
+## UI Styling & Interaction Rules (CRITICAL)
+
+The visual rendering heavily depends on `buttonType`. All variants MUST implement strict hover states, tooltips, and distinct active state bounding boxes.
 
-1. **`buttonType === 'emoji'`**
-   - Map over options. Use `CsatEmojiMapping[option.value]` for standard 1-5 scales.
-   - Or use `getEmojiForIndex` if scale is variable length.
-   
-2. **`buttonType === 'star'`**
-   - Map options. Fill stars up to the selected index using `CsatStarIcons`.
+### 1. `buttonType === 'emoji'`
+- **Icons**: Use `getEmojiForIndex(index, total)` or map `CsatEmojiMapping`.
+- **Hover State**: `hover:scale-110 transition-transform cursor-pointer`.
+- **Active State Bounding Box**: 
+  - DO NOT just change the emoji color.
+  - The selected emoji MUST be wrapped in a prominent pink square box with rounded corners.
+  - Wrapper CSS: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110`.
+  - Unselected CSS: `border-2 border-transparent p-2 opacity-50 hover:opacity-100`.
+- **Tooltips**: `title={option.label}` on every button.
 
-3. **`buttonType === 'numbered'`**
-   - Simple rounded `<button>` with the numeric value. No traffic-light colors.
+### 2. `buttonType === 'star'`
+- **Icons**: Use `CsatStarIcons.filled` and `CsatStarIcons.empty`.
+- **Active State Bounding Box**:
+  - The *last* selected star (the one matching the `selectedValue`) receives the pink bounding box: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 scale-110`.
+  - Previous filled stars get `border-transparent p-2 text-[#e20074]`.
+  - Empty stars get `opacity-30`.
 
-4. **`buttonType === 'radio'`**
-   - Standard radio list.
+### 3. `buttonType === 'numbered'`
+- Fallback to `RatingScale` style (Square badges).
 
-5. **`buttonType === 'graphics'`**
-   - Renders a single continuous slider. Uses `<CustomSliderTrack>`.
+### 4. `buttonType === 'graphics'`
+- Render a single `<CustomSliderTrack>`.
 
 ## N/A Option Handling
 If `question.hasNotApplicable` is true:
-- The options array contains an option with `value: null`.
-- Render a distinct button for N/A.
+- Render a distinct button or checkbox for N/A.
 - Selecting it passes `null` to `onSelect`.
+- Style it distinctly from the main scale (e.g., standard text button or checkbox).
+
+## Label Positioning
+- Place `minLabel` and `maxLabel` underneath the emoji/star track, just like RatingScale.
+- `relative mt-4 flex w-full justify-between text-xs text-gray-500 font-medium`.
+
+## Implementation Snippet (Emoji Variant)
+
+```tsx
+<div className="flex w-full justify-between items-center gap-2">
+  {options.map((option, i) => {
+    const isSelected = selectedValue === option.value;
+    
+    return (
+      <button
+        key={option.id}
+        onClick={() => onSelect(option.value as number)}
+        title={option.label} // Required Tooltip
+        className={`
+          flex items-center justify-center transition-all duration-200
+          ${isSelected 
+            ? 'border-2 border-[#e20074] rounded-lg p-1 sm:p-2 bg-pink-50 scale-110 shadow-sm z-10' 
+            : 'border-2 border-transparent p-1 sm:p-2 opacity-50 hover:opacity-100 hover:scale-105'
+          }
+        `}
+      >
+        <div className="w-8 h-8 sm:w-10 sm:h-10">
+          {getEmojiForIndex(i, options.length)}
+        </div>
+      </button>
+    );
+  })}
+</div>
+```

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

@@ -3,9 +3,6 @@
 > **Component**: `CsatMatrixScale`
 > **Handles**: `type: 'matrix'` (CSAT_MATRIX subType) | `type: 'rating_matrix'`
 
-## Role
-Renders a grid where rows are statements and columns are rating/satisfaction levels.
-
 ## Props Interface
 ```typescript
 type CsatMatrixScaleProps = {
@@ -15,29 +12,66 @@ type CsatMatrixScaleProps = {
 };
 ```
 
-## Structure
-- Renders an HTML `<table>`.
-- **`<thead>`**:
-  - Empty top-left cell.
-  - Column headers mapped from `question.columns`. Use `col.label`.
-- **`<tbody>`**:
-  - Map over `question.rows`.
-  - First cell is the row text.
-  - Subsequent cells are the input controls mapped from `question.columns`.
+## UI Structure & Hover Rules (CRITICAL)
+
+The matrix must be rendered as an HTML `<table>` with strict hover tracking and active selection bounding boxes.
+
+### 1. Table Layout
+- `w-full text-left border-collapse`.
+- **Headers (`<thead>`)**:
+  - `th` elements must be `p-4 text-sm font-semibold text-gray-600 text-center`.
+  - Leftmost header is empty.
+
+### 2. Row Hover Tracking
+- Matrix grids are hard to read. You **MUST** add `hover:bg-gray-50 transition-colors` to every `<tr>` in the `<tbody>`.
+- Cells: `td` elements must be `p-4 border-b border-gray-100 text-center`.
+- Leftmost cell (row text): `text-sm font-medium text-gray-800 text-left w-1/3`.
+
+### 3. Active State Bounding Boxes (Emojis & Stars)
+Just like `CsatScale`, when `buttonType === 'emoji'` or `'star'`, you cannot just swap the icon. The selected cell must highlight the selection prominently.
 
-## Input Control Selection
-Within each table cell, the control rendered depends on `question.buttonType` (similar to CsatScale):
+- **Unselected Icon Wrapper**: `inline-flex p-1 border-2 border-transparent opacity-40 hover:opacity-100 hover:scale-110 transition-all cursor-pointer`.
+- **Selected Icon Wrapper**: `inline-flex p-1 border-2 border-[#e20074] rounded-md bg-pink-50 scale-110 shadow-sm opacity-100 cursor-pointer`.
 
-- `'emoji'`: Use `getEmojiForIndex(colIndex, cols.length)`
-- `'star'`: Use `CsatStarIcons`
-- `'radio'`: `<input type="radio">` + custom CSS dot
-- `'numbered'`: Badge button (if `rating_matrix`, apply `col.color`)
+### 4. Tooltips
+- Every icon in every cell MUST have `title={col.label}` so the user knows what column they are clicking.
 
-If `buttonType === 'dropdown'`, the table structure is **abandoned**. Instead, it renders a list of rows, each containing a `<MatrixDropdown>` component.
+## Implementation Snippet (Row Rendering)
 
-## `MatrixAnswerMap` Updates
-When a cell is clicked:
 ```tsx
-const newValue = { ...selectedValue, [row.id]: col.value };
-onSelect(newValue);
+<tbody>
+  {question.rows.map((row) => (
+    <tr key={row.id} className="hover:bg-gray-50 transition-colors group">
+      <td className="p-4 border-b border-gray-100 text-sm font-medium text-gray-800 text-left w-1/3">
+        {row.text}
+      </td>
+      {question.columns.map((col, colIdx) => {
+        const isSelected = selectedValue[row.id] === col.value;
+        
+        return (
+          <td key={col.id} className="p-4 border-b border-gray-100 text-center">
+            <button
+              type="button"
+              onClick={() => onSelect({ ...selectedValue, [row.id]: col.value })}
+              title={col.label} // Tooltip required
+              className={`
+                inline-flex items-center justify-center transition-all duration-200
+                ${isSelected 
+                  ? 'border-2 border-[#e20074] rounded-md p-1.5 bg-pink-50 scale-110 shadow-sm' 
+                  : 'border-2 border-transparent p-1.5 opacity-40 group-hover:opacity-70 hover:opacity-100 hover:scale-110'
+                }
+              `}
+            >
+              <div className="w-6 h-6 sm:w-8 sm:h-8">
+                 {/* Render icon based on buttonType */}
+                 {question.buttonType === 'emoji' && getEmojiForIndex(colIdx, question.columns.length)}
+                 {question.buttonType === 'star' && (isSelected ? CsatStarIcons.filled : CsatStarIcons.empty)}
+              </div>
+            </button>
+          </td>
+        );
+      })}
+    </tr>
+  ))}
+</tbody>
 ```

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

@@ -3,9 +3,6 @@
 > **Component**: `LikertMatrixScale`
 > **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
 
-## Role
-Renders a grid with text-label columns (Likert scale).
-
 ## Props Interface
 ```typescript
 type LikertMatrixScaleProps = {
@@ -15,24 +12,32 @@ type LikertMatrixScaleProps = {
 };
 ```
 
-## Structure & Formats
+## Matrix Configurations (CRITICAL)
+
+The SDK provides several boolean flags that alter the grid layout. You MUST implement logic for these:
+
+### 1. `question.transposeTable`
+If `true`, swap the axes:
+- The `columns` (labels like "Strongly Agree") become the left-hand row headers.
+- The `rows` (statements) become the top column headers.
+- Rendering logic must map over columns first, then rows.
 
-The visual representation changes drastically based on `question.matrixFormat`:
+### 2. `question.repeatScale`
+If `true`, the `<thead>` (the column labels) should be injected periodically in the `<tbody>`.
+- Example: `if (rowIndex > 0 && rowIndex % 5 === 0) return <RepeatedHeaderRow />`
+- This helps users maintain context on very long grids.
 
-### 1. `matrixFormat === 'standard'` (Default)
-- Table grid.
-- Columns are simple radio buttons (`<input type="radio">`).
-- **No emojis or stars** — standard Likert matrices are purely structural text.
-- If `matrixType === 'bipolar'`, the first cell has `row.text` and the last cell has `row.rightText` added.
+### 3. `question.matrixType === 'bipolar'`
+- The first cell contains `row.text`.
+- The last cell contains `row.rightText`.
+- The radio buttons span the cells in between.
 
-### 2. `matrixFormat === 'carousel'`
-- Shows one row at a time.
-- Renders `row.text` prominently.
-- Renders a standard MCQ-style list of options (`columns`) below it.
-- Has internal state for `currentRowIndex`.
-- Next/Prev buttons step through the rows.
+## UI Styling Rules
 
-### 3. `matrixFormat === 'dropdown'`
-- Renders a list of rows.
-- Each row contains a `<select>` dropdown populated with `question.columns`.
-- Or uses a custom `<MatrixDropdown>` component for better styling.
+- **Row Hovers**: Every `<tr>` must have `hover:bg-gray-50 transition-colors`.
+- **Radio Buttons**: 
+  - Do NOT use plain browser radios if possible. Use accent-colored styling:
+    `accent-[#e20074] w-5 h-5 cursor-pointer`.
+  - Alternatively, build custom CSS circles that fill with pink when selected.
+- **Labels**: Header labels (`th`) should be `text-xs font-semibold text-gray-500 uppercase tracking-wider text-center`.
+- **Tooltips**: Native `title` on every radio button mapping to the column label.

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

@@ -3,9 +3,6 @@
 > **Component**: `SliderMatrixScale`
 > **Handles**: `type: 'slider_matrix'`
 
-## Role
-Renders a list of rows, where each row contains an independent range slider.
-
 ## Props Interface
 ```typescript
 type SliderMatrixScaleProps = {
@@ -15,30 +12,82 @@ type SliderMatrixScaleProps = {
 };
 ```
 
-## Structure
-- Not a `<table>`. Rendered as a flex/grid list.
-- Map over `question.rows`.
-- Each row uses the row's specific `min`, `max`, and `step` values.
-- The slider is bound to `selectedValue[row.id]`.
+## UI Styling Rules (CRITICAL)
 
-## Rendering the Slider
+Sliders must look substantial and modern. Native thin browser sliders are unacceptable.
 
-```tsx
-<input 
-  type="range"
-  min={row.min}
-  max={row.max}
-  step={row.step}
-  value={selectedValue[row.id] ?? row.min}
-  onChange={e => onSelect({ ...selectedValue, [row.id]: Number(e.target.value) })}
-/>
-```
+### 1. Thick Track Styling
+The slider track must be visually prominent:
+- Height: `h-2` or `h-3`.
+- Rounded corners: `rounded-full`.
+- **Dynamic Fill**: The track up to the thumb MUST be pink (`bg-[#e20074]`). The track after the thumb MUST be light gray (`bg-gray-200`).
+- You can achieve this using CSS linear-gradients tied to the value percentage, or by using a custom overlay div.
+
+### 2. Thumb Styling
+- Solid pink circle: `w-5 h-5 rounded-full bg-[#e20074] shadow-md border-2 border-white`.
+- Hover state: `hover:scale-125 transition-transform`.
 
-If `question.sliderType === 'graphics'`, delegate to `<CustomSliderTrack>` instead of native `<input>`.
+### 3. Value Display
+- The exact selected value (e.g., `7`) **MUST** be displayed visibly.
+- Typical layout: Place it at the far right of the slider track in a small bold badge.
+
+### 4. Ticks and Labels
+- `row.ticks`: If provided (e.g., `10`), render tiny tick marks beneath the track at intervals.
+- `row.minLabel` & `row.maxLabel`: Render underneath the far left and far right of the track.
+
+## Implementation Snippet (Custom Slider Row)
 
-If `question.enableNotApplicable` is true, render a checkbox next to each slider:
 ```tsx
-<input type="checkbox" onChange={e => {
-  onSelect({ ...selectedValue, [row.id]: e.target.checked ? null : row.min })
-}} />
+{question.rows.map(row => {
+  const val = selectedValue[row.id] ?? row.min;
+  const percentage = ((val - row.min) / (row.max - row.min)) * 100;
+
+  return (
+    <div key={row.id} className="flex flex-col gap-4 py-6 border-b border-gray-100">
+      <p className="text-sm font-medium text-gray-800">{row.text}</p>
+      
+      <div className="flex items-center gap-4">
+        <div className="relative w-full flex items-center h-6">
+          {/* Track Background */}
+          <div className="absolute w-full h-2 bg-gray-200 rounded-full" />
+          
+          {/* Track Fill (Pink) */}
+          <div 
+            className="absolute h-2 bg-[#e20074] rounded-l-full" 
+            style={{ width: `${percentage}%` }}
+          />
+          
+          {/* Native Input (Invisible overlay for mechanics) */}
+          <input 
+            type="range"
+            min={row.min}
+            max={row.max}
+            step={row.step}
+            value={val}
+            onChange={e => onSelect({ ...selectedValue, [row.id]: Number(e.target.value) })}
+            className="absolute w-full h-full opacity-0 cursor-pointer z-10"
+            title={`Value: ${val}`}
+          />
+          
+          {/* Visual Thumb */}
+          <div 
+            className="absolute w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none transition-transform"
+            style={{ left: `calc(${percentage}% - 10px)` }}
+          />
+        </div>
+        
+        {/* Value Display Badge */}
+        <div className="shrink-0 w-8 text-center font-bold text-[#e20074]">
+          {val}
+        </div>
+      </div>
+      
+      {/* Min/Max Labels */}
+      <div className="flex justify-between text-xs text-gray-500 font-medium px-1">
+        <span>{row.minLabel}</span>
+        <span>{row.maxLabel}</span>
+      </div>
+    </div>
+  );
+})}
 ```

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

@@ -3,9 +3,6 @@
 > **Component**: `FileUploadScale`
 > **Handles**: `type: 'file_upload'`
 
-## Role
-Provides a UI for selecting files, enforcing limits, and displaying the selected list.
-
 ## Props Interface
 ```typescript
 type FileUploadScaleProps = {
@@ -15,19 +12,76 @@ type FileUploadScaleProps = {
 };
 ```
 
-## Structure
-1. **Dropzone / Browse Button**
-   - `<input type="file" multiple={maxFileCount > 1} className="hidden">`
-   - Visible button triggers `.click()` on hidden input.
-2. **File List**
-   - Map over `selectedValue || []`.
-   - Show file name and remove button.
-3. **Error Text**
-   - Local state for size limit or format errors.
-
-## Limit Enforcement
-- `question.maxFileCount`
-- `question.supportedFileFormats` (e.g. `['PDF', 'PNG']`)
-- `question.fileSizeLimit` (MB)
-
-When files are selected, validate before adding to `selectedValue`.
+## UI Styling Rules (CRITICAL)
+
+The file upload component must be highly polished, featuring a drag-and-drop zone and a discrete list of uploaded files.
+
+### 1. Dropzone Area
+- **Border**: Thick dashed border. `border-2 border-dashed border-gray-300 rounded-xl`.
+- **Background & Spacing**: `bg-gray-50 p-8 text-center cursor-pointer transition-colors`.
+- **Hover State**: `hover:border-[#e20074] hover:bg-pink-50 hover:shadow-sm`.
+- **Content**: 
+  - Render a large prominent cloud upload icon (e.g., from `react-icons`).
+  - Render the instruction text (`question.uploadMessage` or "Click or drag files here to upload").
+  - Render limits text below it in smaller font: `Max files: ${maxFileCount} | Limit: ${fileSizeLimit}MB | Formats: ${supportedFileFormats.join(', ')}`.
+
+### 2. Uploaded Files List
+When files are selected (`selectedValue.length > 0`), render them as a list of distinct cards below the dropzone:
+- **Card**: `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
+- **File Info**: Display a small file icon, the file name (`truncate` class if long), and the file size.
+- **Remove Button**: A discrete trash can icon button. `text-red-500 hover:bg-red-50 rounded-md p-2 transition-colors`.
+
+## Implementation Snippet
+
+```tsx
+<div className="space-y-4">
+  {/* Hidden Input */}
+  <input 
+    type="file" 
+    ref={fileInputRef} 
+    className="hidden" 
+    multiple={question.maxFileCount > 1}
+    accept={question.supportedFileFormats?.map(f => `.${f.toLowerCase()}`).join(',')}
+    onChange={handleFileChange}
+  />
+
+  {/* Dropzone */}
+  <div 
+    onClick={() => fileInputRef.current?.click()}
+    className="border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 hover:bg-pink-50 hover:border-[#e20074] transition-colors p-8 text-center cursor-pointer flex flex-col items-center justify-center gap-2 group"
+  >
+    <div className="w-12 h-12 rounded-full bg-white flex items-center justify-center text-gray-400 group-hover:text-[#e20074] shadow-sm mb-2">
+      {/* Insert SVG Cloud Icon Here */}
+      <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12" /></svg>
+    </div>
+    <p className="text-sm font-semibold text-gray-700 group-hover:text-[#e20074]">
+      {question.uploadMessage || "Click or drag files here to upload"}
+    </p>
+    <p className="text-xs text-gray-500">
+      Supported formats: {question.supportedFileFormats?.join(', ')} (Max {question.fileSizeLimit}MB)
+    </p>
+  </div>
+
+  {/* Uploaded Files List */}
+  {selectedValue && selectedValue.length > 0 && (
+    <ul className="space-y-2 mt-4">
+      {selectedValue.map((file, i) => (
+        <li key={i} className="flex items-center justify-between p-3 border border-gray-200 rounded-lg bg-white shadow-sm">
+          <div className="flex items-center gap-3 overflow-hidden">
+            <span className="text-gray-400">📄</span>
+            <span className="text-sm font-medium text-gray-700 truncate">{file.name}</span>
+            {file.size && <span className="text-xs text-gray-400">({(file.size / 1024 / 1024).toFixed(2)} MB)</span>}
+          </div>
+          <button 
+            onClick={() => onSelect(selectedValue.filter((_, index) => index !== i))}
+            className="text-red-500 hover:bg-red-50 p-2 rounded-md transition-colors"
+            title="Remove file"
+          >
+            🗑️
+          </button>
+        </li>
+      ))}
+    </ul>
+  )}
+</div>
+```

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

@@ -4,24 +4,69 @@
 > **Used by**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
 
 ## Role
-A shared presentation component that overrides native browser range slider styling to provide an emoji-thumb or branded track.
-
-## Why it exists
-Native `<input type="range">` cannot reliably render an emoji inside the draggable thumb handle cross-browser. This component uses CSS tricks (often a transparent native range input layered over a custom styled `div` track) to achieve the design.
-
-## Props Interface
-```typescript
-type CustomSliderTrackProps = {
-  min: number;
-  max: number;
-  step: number;
-  value: number;
-  onChange: (val: number) => void;
-  sliderType?: 'graphics' | 'standard';
-  // Additional props for tick marks, colors
-};
-```
+A shared presentation component that overrides native browser range slider styling to provide an emoji-thumb or a standard branded thick track. 
+
+## Custom Graphics Variant (`sliderType === 'graphics'`)
+If the API specifies `graphics`, the slider thumb **MUST** dynamically display an emoji corresponding to the current value.
+- The thumb must be large enough to hold an emoji (`w-8 h-8` or `w-10 h-10`).
+- Use `getEmojiForIndex` from the SDK to map the current percentage/value to the correct sentiment face.
+- The thumb must have a shadow and white background to pop out from the track: `bg-white rounded-full shadow-md border border-gray-200 flex items-center justify-center text-xl`.
+
+## Track CSS Construction
+Native `<input type="range">` cannot reliably render an emoji inside the draggable thumb handle cross-browser. 
+
+You MUST use the "invisible overlay" trick:
+1. Render a visual background track `div` (the gray bar).
+2. Render a visual fill track `div` (the pink bar, width bound to `percentage`).
+3. Render a visual thumb `div` (the pink circle or the emoji, left bound to `percentage`).
+4. **Overlay** a completely invisible native `<input type="range" className="absolute opacity-0 w-full h-full cursor-pointer z-10" />`.
 
-## Emoji Thumb Logic
-If `sliderType === 'graphics'`, the thumb handle should dynamically display an emoji corresponding to the current value.
-It uses `getEmojiForIndex` from `icons.tsx`.
+## Implementation Snippet
+
+```tsx
+export default function CustomSliderTrack({ min, max, step, value, onChange, sliderType }) {
+  const percentage = ((value - min) / (max - min)) * 100;
+
+  // Determine emoji if graphics variant
+  const emoji = sliderType === 'graphics' 
+    ? getEmojiForIndex(value - min, (max - min) / step + 1)
+    : null;
+
+  return (
+    <div className="relative w-full flex items-center h-8">
+      {/* Background Track */}
+      <div className="absolute w-full h-2 bg-gray-200 rounded-full" />
+      
+      {/* Filled Track */}
+      <div 
+        className="absolute h-2 bg-[#e20074] rounded-l-full" 
+        style={{ width: `${percentage}%` }}
+      />
+      
+      {/* Invisible Native Input */}
+      <input 
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={e => onChange(Number(e.target.value))}
+        className="absolute w-full h-full opacity-0 cursor-pointer z-10"
+        title={`Value: ${value}`}
+      />
+      
+      {/* Custom Thumb */}
+      <div 
+        className={`absolute pointer-events-none transition-transform flex items-center justify-center ${
+          sliderType === 'graphics' 
+            ? 'w-10 h-10 bg-white rounded-full shadow-md border border-gray-200 text-2xl -ml-5' 
+            : 'w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md -ml-2.5 hover:scale-125'
+        }`}
+        style={{ left: `${percentage}%` }}
+      >
+        {sliderType === 'graphics' && emoji}
+      </div>
+    </div>
+  );
+}
+```