@explorer02/cfm-survey-sdk 0.1.6 → 0.1.8

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

@@ -1,43 +1,44 @@
-# Likert Matrix Scale Component
+# Likert Matrix Architectural Blueprint
 
-> **Component**: `LikertMatrixScale`
+> **Target Component**: `LikertMatrixScale`
 > **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
 
-## Props Interface
-```typescript
-type LikertMatrixScaleProps = {
-  question: SurveyQuestion & { type: 'matrix' };
-  selectedValue: MatrixAnswerMap;
-  onSelect: (value: MatrixAnswerMap) => void;
-};
-```
-
-## 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.
-
-### 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.
-
-### 3. `question.matrixType === 'bipolar'`
-- The first cell contains `row.text`.
-- The last cell contains `row.rightText`.
-- The radio buttons span the cells in between.
-
-## UI Styling Rules
-
-- **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.
+## Core Responsibility
+Render a grid with text-label columns. However, this component must be highly dynamic to support complex layouts, transpositions, and long-form matrix readability.
+
+## Data Mapping & State Management
+- `selectedValue`: Expects `MatrixAnswerMap` shape (`Record<string, string | number | null>`).
+- **Mutation**: When radio button is clicked for `row.id` and `col.value`, dispatch `onSelect({ ...selectedValue, [row.id]: col.value })`.
+
+## Configuration Matrix (CRITICAL FOR PLANNING)
+
+Your component architecture MUST account for the following boolean flags from `question`:
+
+### 1. `transposeTable`
+If `true`, the standard Row-by-Column matrix is inverted:
+- `question.columns` become the row labels on the left.
+- `question.rows` become the top column headers.
+- **Architectural Requirement**: Your `<tbody>` map must iterate over `question.columns` first, and render `<td>` cells mapped from `question.rows`.
+- Ensure `onSelect` still correctly pairs the original `row.id` with the original `col.value`.
+
+### 2. `repeatScale`
+If `true`, the `<thead>` containing column labels must be re-injected periodically to prevent users from losing track of columns on long matrices.
+- **Implementation Strategy**: In your row `map()`, if `index > 0 && index % 5 === 0`, return a React Fragment containing a cloned `<tr>` header row followed by the actual data `<tr>`.
+
+### 3. `matrixType === 'bipolar'`
+Standard matrices (`'likert'`) only show statement text on the left. Bipolar scales show text on BOTH sides of the radio buttons.
+- **Implementation Strategy**: Render an extra `<td>` at the end of the row containing `row.rightText`.
+
+## UI/UX & Styling Constraints
+
+To match enterprise standards, implement the following UI strictly:
+
+1. **Row Tracking (Hover Effects)**:
+   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150 group`. This is mandatory for UX on wide matrices.
+2. **Radio Buttons**:
+   - Use `accent-[#e20074] w-5 h-5 cursor-pointer` or build custom CSS circles that fill with the brand color.
+   - Do NOT use standard unstyled blue browser radios.
+3. **Tooltips (Accessibility)**:
+   - Every input MUST have `title={col.label}` so the user sees the semantic meaning when hovering the radio button.
+4. **Header Typography**:
+   - `th` tags should be `text-xs font-semibold text-gray-500 uppercase tracking-wider p-4 border-b`.

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

@@ -1,93 +1,45 @@
-# Slider Matrix Scale Component
+# Slider Matrix Architectural Blueprint
 
-> **Component**: `SliderMatrixScale`
+> **Target Component**: `SliderMatrixScale`
 > **Handles**: `type: 'slider_matrix'`
 
-## Props Interface
-```typescript
-type SliderMatrixScaleProps = {
-  question: SurveyQuestion & { type: 'slider_matrix' };
-  selectedValue: MatrixAnswerMap;
-  onSelect: (value: MatrixAnswerMap) => void;
-};
-```
+## Core Responsibility
+Render an independent range slider for every row in the matrix. Sliders must be highly visible, utilizing a "thick track" UI, dynamic fill based on the current value, and exact value badges.
 
-## UI Styling Rules (CRITICAL)
+## State Management
+- `selectedValue`: Expects `MatrixAnswerMap` shape.
+- `row.min`, `row.max`, and `row.step` must dictate the boundaries of the slider logic.
+- **Mutation**: `onChange` of the input must parse the value as a Number before dispatching `onSelect`.
 
-Sliders must look substantial and modern. Native thin browser sliders are unacceptable.
+## The "Thick Slider" UX Implementation (CRITICAL)
 
-### 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.
+Native `<input type="range">` elements are notoriously difficult to style consistently across browsers. You MUST implement the "Invisible Overlay" pattern to achieve the expected thick-track UI.
 
-### 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`.
+### The Invisible Overlay Pattern
+For every slider row, build a relative container:
+1. **Base Track**: `absolute w-full h-2 bg-gray-200 rounded-full`.
+2. **Dynamic Fill Track**: `absolute h-2 bg-[#e20074] rounded-l-full`.
+   - Calculate width dynamically: `((value - min) / (max - min)) * 100 + '%'`.
+3. **The Thumb**: `absolute w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none transition-transform group-hover:scale-125`.
+   - Position it dynamically: `left: calc(${percentage}% - 10px)`.
+4. **The Input Control**: Layer a native input on top, completely invisible but clickable:
+   - `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`
 
-### 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.
+## Configuration Matrix (CRITICAL FOR PLANNING)
 
-### 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.
+Your component must account for:
 
-## Implementation Snippet (Custom Slider Row)
+### 1. Exact Value Display
+- Users must see the exact number they are selecting.
+- Render a badge at the far right of the slider track: `shrink-0 w-8 text-center font-bold text-[#e20074]`.
 
-```tsx
-{question.rows.map(row => {
-  const val = selectedValue[row.id] ?? row.min;
-  const percentage = ((val - row.min) / (row.max - row.min)) * 100;
+### 2. `row.ticks` & `tickValues`
+- If `question.ticks` or `row.tickValues` exists, you must render tiny vertical tick marks below the track at appropriate percentage intervals to guide the user.
 
-  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>
-  );
-})}
-```
+### 3. Label Positioning
+- `row.minLabel` and `row.maxLabel` must be displayed directly underneath the far-left and far-right of the slider track using flexbox `justify-between text-xs text-gray-500`.
+
+### 4. `enableNotApplicable`
+- If `true`, render a checkbox at the end of the row.
+- Checking it sets the value in the map to `null`.
+- When `value === null`, gray out the slider track and disable the input.

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

@@ -1,87 +1,56 @@
-# File Upload Scale Component
+# File Upload Architectural Blueprint
 
-> **Component**: `FileUploadScale`
+> **Target Component**: `FileUploadScale`
 > **Handles**: `type: 'file_upload'`
 
-## Props Interface
-```typescript
-type FileUploadScaleProps = {
-  question: SurveyQuestion & { type: 'file_upload' };
-  selectedValue?: any[]; // Expected to be UploadedFile[]
-  onSelect: (value: any[]) => void;
-};
-```
-
-## 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>
-```
+## Core Responsibility
+Render a robust drag-and-drop zone and enforce complex file size, type limits, and maximum file count constraints BEFORE updating the state.
+
+## State Management
+- `selectedValue`: Expects an array of native `File` objects (or serialized equivalents).
+- **Mutation Pattern**: 
+  1. The user selects files.
+  2. The component intercepts the files.
+  3. The component validates them against ALL limits.
+  4. If valid, append the new files to `selectedValue` (handling it as an array).
+  5. Call `onSelect(updatedFilesArray)`.
+
+## Configuration Matrix (CRITICAL FOR PLANNING)
+
+Before calling `onSelect`, your component MUST validate against these properties:
+
+### 1. `supportedFileFormats`
+- Extracted from `question.supportedFileFormats` (e.g. `['PDF', 'PNG', 'JPG']`).
+- Use this to build the `accept` attribute string for the hidden input: `question.supportedFileFormats?.map(f => \`.\${f.toLowerCase()}\`).join(',')`.
+- You MUST reject files with extensions that are not in this list.
+
+### 2. `maxFileCount`
+- Prevent uploads if `currentFiles.length + newFiles.length > maxFileCount`.
+- Provide a clear local error message indicating the max limit.
+
+### 3. `fileSizeLimit` & `fileSizeLimitType`
+- `fileSizeLimit` is a number representing megabytes (MB).
+- If `fileSizeLimitType === 'PER_FILE'`, validate that EVERY incoming file's `size` (in bytes) is `<= fileSizeLimit * 1024 * 1024`.
+- If `fileSizeLimitType === 'IN_TOTAL'`, validate that the combined sum of all existing `selectedValue` sizes plus the incoming files' sizes is `<= fileSizeLimit * 1024 * 1024`.
+
+## UI/UX Specifications
+
+1. **Dropzone**:
+   - Wrap the main area with `onDragEnter`, `onDragOver`, `onDragLeave`, `onDrop`.
+   - **Inactive State**: `border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 p-8 text-center cursor-pointer transition-all`.
+   - **Drag/Hover State**: `border-[#e20074] bg-[#fdf2f8]` (Using the brand primary color).
+   - Display a Cloud SVG icon (use gray, switch to magenta on hover).
+   - Render `question.uploadMessage` (which can contain HTML, so use `dangerouslySetInnerHTML`).
+   - Dynamically render the limits text (e.g., "Max 3 files, 10MB per file").
+
+2. **File List**:
+   - Render existing files as distinct cards underneath the dropzone.
+   - Styling: `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
+   - Display the filename (truncated if long) and the formatted file size (e.g., "1.2 MB").
+   - Include a distinct, circular Trash/Remove button that removes the file from the state and calls `onSelect` with the updated array.
+
+3. **Validation Errors**:
+   - Local validation errors (e.g. "File too large") must be displayed in a highly visible red banner (`bg-red-50 text-red-700 p-3 rounded-md`) right below the dropzone.
+
+## Hidden Input
+- Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.

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

@@ -1,72 +1,36 @@
-# Custom Slider Track
+# Custom Slider Track Architectural Blueprint
 
-> **Component**: `CustomSliderTrack`
-> **Used by**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
+> **Target Component**: `CustomSliderTrack`
+> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
 
-## Role
-A shared presentation component that overrides native browser range slider styling to provide an emoji-thumb or a standard branded thick track. 
+## Core Responsibility
+Native browser `<input type="range">` elements are impossible to style consistently across browsers, especially when trying to render dynamic emoji handles. This component MUST implement an invisible overlay architecture to provide total CSS control over the slider's appearance.
 
-## 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`.
+## The Invisible Overlay Architecture (CRITICAL)
 
-## Track CSS Construction
-Native `<input type="range">` cannot reliably render an emoji inside the draggable thumb handle cross-browser. 
+Instead of trying to style the `::-webkit-slider-thumb` pseudo-elements, you MUST build the slider using layered DOM elements.
 
-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" />`.
+### Layer 1: The Background Track
+A static `<div>` representing the entire length of the slider.
+- CSS: `absolute w-full h-2 bg-gray-200 rounded-full`.
 
-## Implementation Snippet
+### Layer 2: The Active Fill
+A dynamic `<div>` representing the portion of the slider up to the current value.
+- CSS: `absolute h-2 bg-[#e20074] rounded-l-full`.
+- Inline Style: `style={{ width: \`\${percentage}%\` }}`.
 
-```tsx
-export default function CustomSliderTrack({ min, max, step, value, onChange, sliderType }) {
-  const percentage = ((value - min) / (max - min)) * 100;
+### Layer 3: The Custom Thumb
+A visual element that floats along the track.
+- **For Standard Sliders**: A pink circle. `w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none`.
+- **For Graphics Sliders (`sliderType === 'graphics'`)**: A larger white circle containing an emoji mapped to the current value using `getEmojiForIndex`. `w-10 h-10 bg-white shadow-md border flex items-center justify-center text-2xl`.
+- Inline Style: `style={{ left: \`\${percentage}%\` }}`.
 
-  // Determine emoji if graphics variant
-  const emoji = sliderType === 'graphics' 
-    ? getEmojiForIndex(value - min, (max - min) / step + 1)
-    : null;
+### Layer 4: The Native Input (The Engine)
+An invisible native input overlaid exactly on top to capture all mouse/touch events automatically without needing manual math for drag interactions.
+- CSS: `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`.
+- This ensures perfect accessibility, keyboard navigation, and mobile touch support.
 
-  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>
-  );
-}
-```
+## Configuration Logic
+- Calculate percentage carefully: `((value - min) / (max - min)) * 100`.
+- Ensure the custom thumb is negatively margined (e.g. `-ml-2.5` or `-ml-5`) so that its *center* aligns with the percentage point, not its left edge.
+- If `question.ticks` is provided, map out small `w-0.5 h-3 bg-gray-300` vertical lines below the track at the correct percentage intervals.

package/templates/docs/03-client-components/10-header-footer.md

@@ -1,46 +1,23 @@
-# Header, Footer & Branding
+# Theme & Logo Engineering Blueprint
 
-> **Components**: `Header`, `Footer`
-> **Role**: Branding shells around the survey content.
+> **Target Components**: `Header`, Global Styles
+> **Handles**: Branding, Mockup Replication
 
-## Strict Logo Requirement
+## Core Responsibility
+When building the survey layout, the client will provide a text prompt or an image mockup. You MUST dynamically build the Theme and Logo using purely CSS and Tailwind to match the requested brand.
 
-**⚠️ CRITICAL RULE**: You must NOT use `<img>` tags pointing to external Telekom or Sprinklr URLs. You must NOT download static images into the `public/` folder.
+## Logo Engineering Rules (CRITICAL)
+- **NO EXTERNAL IMAGES**: You are strictly forbidden from writing `<img src="url" />` for logos, because you do not have a CDN to host them.
+- **CSS-Only Logos**: You MUST construct the company logo using HTML and CSS primitives. 
+- Example: If the prompt shows the Telekom logo (a white 'T' inside a pink square, or distinct abstract shapes), you must build it using Flexbox, CSS shapes (`rounded-full`, `rounded-tr-3xl`, absolute positioning), and the exact brand colors (`bg-[#e20074] text-white`).
 
-All logos must be constructed **purely using Tailwind CSS** geometric shapes.
+## Theme Engineering
+- Map the primary brand color to the accent and border colors across the entire survey.
+- If the mockup shows a distinct font, update the Next.js `layout.tsx` to pull that font from `next/font/google` (e.g. `Inter`, `Outfit`, `Roboto`).
+- Ensure the header, footer, and progress bar strictly align with the color palette extracted from the mockup.
 
-## The Header (Abstract Brand)
-
-```tsx
-export default function Header() {
-  return (
-    <header className="flex h-16 items-center justify-between border-b px-6">
-      {/* CSS-only Abstract Logo */}
-      <div className="flex items-center gap-2">
-        <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-[#e20074]">
-          <div className="h-4 w-4 rounded-full bg-white" />
-        </div>
-        <span className="text-xl font-bold tracking-tight text-gray-900">
-          YourBrand
-        </span>
-      </div>
-    </header>
-  );
-}
-```
-
-## The Footer
-
-```tsx
-export default function Footer() {
-  return (
-    <footer className="border-t py-6 text-center text-sm text-gray-500">
-      <p>Powered by Sprinklr CFM SDK</p>
-    </footer>
-  );
-}
-```
-
-## Customization
-
-The client may provide a prompt asking for specific colors ("make it dark mode", "use blue"). Update the CSS classes in `SurveyPage`, `Header`, and `Footer` to match their request. Do not try to reverse-engineer their brand logo exactly — stick to clean abstract CSS geometry unless you have an explicit SVG path.
+## Planning Requirement
+In your `implementation_plan.md`, explicitly document:
+1. What CSS techniques you will use to build the abstract/geometric logo.
+2. What primary HEX color you will use for the theme.
+3. What Google font you will import.

package/templates/docs/index.md

@@ -76,15 +76,37 @@ Then understand what question types exist:
 
 *You do NOT need to read every question type doc upfront. Read them ON DEMAND when you encounter each type during component building.*
 
-### PHASE 4: BUILD THE SURVEY UI
-Read these component docs IN ORDER:
-
-1. `03-client-components/README.md`        — File structure overview
-2. `03-client-components/01-survey-page.md` — MAIN orchestrator (REQUIRED)
-3. `03-client-components/02-question.md`    — Question dispatcher (REQUIRED)
-4. `03-client-components/10-header-footer.md` — CSS-built logo/branding
-5. `03-client-components/11-progress-bar.md`  — Progress indicator
-6. `03-client-components/12-language-selector.md` — Language dropdown
+### PHASE 4: UI ARCHITECTURE & WORKFLOW PLANNING (CRITICAL)
+Before writing ANY React code, you MUST enter Planning Mode and generate a deeply comprehensive \`implementation_plan.md\`.
+
+**DEEP CONTEXT INGESTION REQUIRED**:
+Before you even start writing the plan, you MUST read EVERY SINGLE markdown file inside \`03-client-components/\`. You cannot plan accurately without knowing the exact architectures required for CSAT bounds, file validations, and matrix transpositions.
+
+Read ALL the component architectural blueprints IN ORDER:
+1. \`03-client-components/README.md\`
+2. \`03-client-components/01-survey-page.md\`
+3. \`03-client-components/02-question.md\`
+4. \`03-client-components/03-rating-scale.md\`
+5. \`03-client-components/04-csat-scale.md\`
+6. \`03-client-components/05-csat-matrix-scale.md\`
+7. \`03-client-components/06-likert-matrix-scale.md\`
+8. \`03-client-components/07-slider-matrix-scale.md\`
+9. \`03-client-components/08-file-upload-scale.md\`
+10. \`03-client-components/09-custom-slider-track.md\`
+11. \`03-client-components/10-header-footer.md\`
+12. \`03-client-components/11-progress-bar.md\`
+13. \`03-client-components/12-language-selector.md\`
+14. \`03-client-components/13-matrix-dropdown.md\`
+
+Your \`implementation_plan.md\` MUST be structured professionally and precisely cover:
+1. **Data Fetching & State**: Precisely how \`useSurveySDK(instanceId)\` will be integrated. How to handle \`isLoading\`, \`error\`, \`empty\`, and \`submitted\` states properly.
+2. **Pagination, Actions, & Flow**: How you will iterate through pages, manage \`onAction({ type: 'NEXT' / 'PREVIOUS' })\`, and precisely wire up the \`ProgressBar\`.
+3. **Question Dispatching**: How \`Question.tsx\` will comprehensively route all 12 \`question.type\` variants (including \`text_and_media\` for \`CONTENT\` questions). How it will safely handle rich HTML parsing and validation error display.
+4. **Question Architectures & Component Checklist**: You must create a checklist inside your plan for EACH complex component. You must verify mappings, step sizes, ticks, hover effects, scale items positioning, and matrix transposition logic EXACTLY as detailed in the blueprints.
+5. **Theme, Brand & Logos**: How you will engineer CSS-only logos based on the client's mockup prompt and map specific brand colors to hover states.
+6. **Submit Survey**: How you will trigger the final \`submitSurvey\` dispatch and elegantly transition the UI to the Thank You screen.
+
+**ACTION**: Generate the \`implementation_plan.md\`. Once the plan is written, **DO NOT WAIT FOR APPROVAL**. Automatically proceed to trigger Phase 5 and start implementing the code!
 
 Then for EACH question type present in the fetched survey, read the matching question-type doc AND component doc: