@explorer02/cfm-survey-sdk 0.3.0 → 0.3.2

package/package.json

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

package/templates/docs/00-integration/client-lib-folder.md

@@ -81,6 +81,7 @@ Exports used by portable scale templates:
 | `tickColorFromIndex(index, total)` | SLIDER_MATRIX header tick badge colors |
 | `matrixColumnStoredValue(col)` | Matrix answer storage — column `id` or `null` for N/A |
 | `npsValueFromOption` / `starValueFromOption` | NPS badge numeric values |
+| `isScaleAnswerSelected` | NPS/star `checked` state — loose number compare |
 | `nonNaScaleColumns` | Filter N/A column from scale columns |
 
 Prefer SDK `matrixColumnStoredValue` when importing from package; template re-exports the same contract for co-located components.

package/templates/docs/00-integration/wizard-chrome-contract.md

@@ -22,7 +22,8 @@ Pipeline: [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) · [`
 | Scale selection colors not updating | Import `selectionStyles.ts`; use `var(--cfm-matrix-selected)` / `var(--cfm-input-focus-ring)` |
 | Company name not showing after logo | Copy `Header.tsx` template — brand row is `[logo][data-cfm-company]` in one flex container |
 | Company shows when empty | Bridge clears `[data-cfm-company]` when `companyName` is `""` — do not hardcode "Company Name" as visible default |
-| NPS colors / rings not updating | Copy `RatingScale.tsx` + `selectionStyles.ts` — no hardcoded `#e20074` |
+| NPS clicks do nothing / no visible selection before wizard | Copy latest `RatingScale.tsx` + `selectionStyles.ts` + `surveyUiScaleUtils.ts`; use `isScaleAnswerSelected()`; radio track row must use `label` + `onChange` → `onSelect(number)` — see `03-ui-specs/01-rating.md` |
+| NPS colors / rings not updating | Copy `RatingScale.tsx` + `selectionStyles.ts` — hex fallbacks in `selectionStyles.ts` for pre-theme builds |
 | Text placeholder color not updating | `data-cfm-textfield` + `--cfm-input-placeholder` in CSS / `::placeholder` rule |
 | Matrix 2nd row toggle | Harness adds row via `previewMultiStatement` — `LikertMatrixScale` must render all `statementRows` from props |
 | Blank page after deploy | **Never** reference `UI_CONFIG` without import — use `src/lib/uiConfig.ts` |

package/templates/docs/00-integration/wizard-preview-build-guide.md

@@ -50,6 +50,23 @@ If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` h
 
 **Default for production wizard:** agent components. Use templates-only for SDK smoke tests, not client delivery.
 
+### Wizard static preview vs production survey
+
+During `npx cfm-sdk customize`, the right panel loads **SDK static HTML** from `preview-harness/previewPages.js` — not your React tree. Layout matches the original survey-page mock; **customization** is driven by `--cfm-*` CSS vars + `preview-bridge.inline.js`.
+
+| Wizard control | Static preview (iframe) | Production survey (after Phase 6c) |
+|----------------|-------------------------|-------------------------------------|
+| NPS hints + number labels | Hint text + badge colors via bridge | Copy `RatingScale.tsx` + `Question.tsx` hint row |
+| Matrix multi-row toggle | Shows/hides `[data-cfm-matrix-row-extra]` | `LikertMatrixScale` maps all `statementRows` |
+| Matrix row width + label items | `--cfm-matrix-row-width`, column label vars | `LikertMatrixScale` + `labelStyles.ts` |
+| CSAT/Rating star/numbered/radio | Theme focus ring + cell selected on mock cells | `CsatMatrixScale.tsx` + `selectionStyles.ts` |
+| Slider track + tick labels | `--cfm-slider-*` on static slider mock | `SliderMatrixScale` + `CustomSliderTrack` |
+| File upload dropzone | `--cfm-upload-*` on `.cfm-dropzone` | `FileUploadScale.tsx` |
+| Rank / heatmap | `--cfm-rank-*` / `--cfm-heatmap-pin-*` | `RankOrderScale.tsx` / `HeatmapScale.tsx` |
+| Logo size slider | `--cfm-header-logo-width/height` + `max-height` in header | `Header.tsx` via `uiConfig.ts` |
+
+**Rule:** If a wizard control updates the static preview but not localhost dev, the agent has not copied the matching template from `docs/templates/` — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
 ---
 
 ## Required project artifacts (Phase 5)

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

@@ -21,9 +21,14 @@ Render a horizontal sequence of numbered badges with traffic-light colors (NPS 0
 ## UI/UX Rules (CRITICAL)
 
 1. **Shape**: Square badges with rounded corners — not full circles
-2. **Unselected State**: Dim unselected when any item selected (`opacity-30`)
-3. **Selected State**: `border-2 border-[#e20074] shadow-md scale-105`
-4. **Tooltips**: `title={option.label}` on every badge
+2. **Interactive row**: Only the **radio track row** accepts clicks (`label` + hidden `input type="radio"`)
+3. **Selection compare**: Use `isScaleAnswerSelected(selectedValue, optionValue)` — store/compare **numbers**, not option ids
+4. **Unselected State**: Gray ring (`#d1d5db`) + white fill on track row
+5. **Selected State**: Focus ring `#e20074` (or `--cfm-input-focus-ring`) + annulus `#fbe8f3` (or `--cfm-matrix-selected`) + filled dot
+6. **Tooltips**: `title={option.label}` on every clickable cell
+7. **`buttonStyle: 'standard'`**: Radio track only — omit numbered badge row
+
+Reference implementation: [`apps/client/src/components/RatingScale.tsx`](../../../../apps/client/src/components/RatingScale.tsx)
 
 ## SDK Integration Checklist (agent)
 

package/templates/docs/02-reference/value-derivation.md

@@ -39,6 +39,8 @@ function npsValueFromOption(option: NpsScalePoint, index: number): number {
 
 NPS questions use `question.type === 'NPS_SCALE'`. Store a **number** in `SurveyAnswers`. Badge colors: traffic-light table keyed by numeric value (0–10).
 
+Compare selection with `isScaleAnswerSelected(selectedValue, npsValueFromOption(option, index))` — do not compare to `option.id`.
+
 ## MCQ
 
 - Selected answer: **`option.id`** (string), not a separate `optionValue` field

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

@@ -31,11 +31,22 @@ When `reverseScaleOrder === true`, map visual index `i` to stored index `options
 ## Answer Mutation
 
 ```typescript
+import { isScaleAnswerSelected, npsValueFromOption } from '@/lib/surveyUiScaleUtils';
+
 const value = npsValueFromOption(option, index);
-onSelect(value) // number
+onSelect(value); // number — never option.id
 // → onAction CHANGE { questionId, answerValue: number }
+
+// Compare stored answer to option value (handles string/number drift):
+const isSelected = isScaleAnswerSelected(selectedValue, value);
 ```
 
+**Selection row (required):** Only the **radio track row** is interactive — use `<label>` + hidden `<input type="radio">` + `onChange={() => onSelect(option.value)}`. Mirror [`apps/client/src/components/RatingScale.tsx`](../../../../apps/client/src/components/RatingScale.tsx) (reference monorepo).
+
+**Pre-customization defaults:** Copy `selectionStyles.ts` with `#e20074` / `#fbe8f3` hex fallbacks so selected rings are visible before `survey-theme.css` loads. Import `survey-theme.css` in `globals.css` for full wizard tokens.
+
+**`buttonStyle`:** `standard` = radio track only (no numbered badge row). `numbered` = badge row + track. `emoji` = emoji cells.
+
 See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 
 ## Agent Checklist
@@ -59,6 +70,9 @@ See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 ### Wizard checklist
 
 - [ ] `selectionStyles.ts` imported in `RatingScale.tsx`
+- [ ] `isScaleAnswerSelected()` used for `checked` state — not raw `===` on `selectedValue`
+- [ ] Radio track: `label` + `sr-only` radio + `onChange` → `onSelect(number)` (see client `RatingScale.tsx`)
 - [ ] Selected radio: outer border + dot = focus ring; annulus = cell selected
 - [ ] Selected numbered badge: border = focus ring, fill = cell selected, text white
 - [ ] Unselected badges keep traffic-light / per-number `--cfm-number-*` colors
+- [ ] `buttonStyle: 'standard'` hides badge row; track row remains clickable

package/templates/docs/templates/CsatMatrixScale.tsx

@@ -12,6 +12,8 @@ import {
   emojiSizeStyle,
   cellSelectedVar,
   focusRingVar,
+  mcqSelectedAccentVar,
+  mcqSelectedBgVar,
 } from '@/lib/surveyUi/selectionStyles';
 import { csatColumnLabelStyle } from '@/lib/surveyUi/labelStyles';
 
@@ -106,10 +108,10 @@ function CsatMatrixVerticalList({
                     onClick={() => onCellSelect(row.id, submitValue)}
                     style={{
                       width: '100%', display: 'flex', alignItems: 'center', justifyContent: 'flex-start',
-                      borderRadius: '8px', border: `1px solid ${isSelected ? '#e20074' : '#d1d5db'}`,
+                      borderRadius: '8px', border: `1px solid ${isSelected ? mcqSelectedAccentVar : '#d1d5db'}`,
                       padding: '14px 18px', cursor: 'pointer', transition: 'all 0.15s',
-                      backgroundColor: isSelected ? '#fdf2f8' : '#fff',
-                      color: isSelected ? '#e20074' : '#374151',
+                      backgroundColor: isSelected ? mcqSelectedBgVar : '#fff',
+                      color: isSelected ? mcqSelectedAccentVar : '#374151',
                       fontWeight: isSelected ? 600 : 400, fontSize: '15px', textAlign: 'left',
                     }}
                   >
@@ -128,9 +130,9 @@ function CsatMatrixVerticalList({
                     key={col.id}
                     style={{
                       display: 'flex', alignItems: 'center', gap: '16px',
-                      borderRadius: '8px', border: `1px solid ${isSelected ? '#e20074' : '#e5e5e5'}`,
+                      borderRadius: '8px', border: `1px solid ${isSelected ? mcqSelectedAccentVar : '#e5e5e5'}`,
                       padding: '16px 20px', cursor: 'pointer', transition: 'all 0.15s',
-                      backgroundColor: isSelected ? '#fdf2f8' : '#fff',
+                      backgroundColor: isSelected ? mcqSelectedBgVar : '#fff',
                     }}
                   >
                     <input type="radio" name={`${question.id}-${row.id}`}
@@ -138,13 +140,8 @@ function CsatMatrixVerticalList({
                       onChange={() => onCellSelect(row.id, submitValue)}
                       style={{ position: 'absolute', width: 0, height: 0, opacity: 0 }}
                     />
-                    <div style={{
-                      display: 'flex', width: '20px', height: '20px', flexShrink: 0,
-                      alignItems: 'center', justifyContent: 'center', borderRadius: '50%',
-                      border: isSelected ? '2px solid #e20074' : '1.5px solid #9ca3af',
-                      backgroundColor: '#fff',
-                    }}>
-                      {isSelected && <div style={{ width: '10px', height: '10px', borderRadius: '50%', backgroundColor: '#e20074' }} />}
+                    <div style={matrixRadioRingStyle(isSelected, '20px')}>
+                      <div style={matrixRadioDotStyle(isSelected, '10px')} />
                     </div>
                     <span style={{ fontSize: '15px', fontWeight: 500, color: '#111827' }}
                       dangerouslySetInnerHTML={{ __html: col.label }} />
@@ -158,7 +155,7 @@ function CsatMatrixVerticalList({
             <label style={{ display: 'flex', alignItems: 'center', gap: '12px', cursor: 'pointer', userSelect: 'none' }}>
               <input type="checkbox" checked={selectedValue[row.id] === null}
                 onChange={() => onCellSelect(row.id, selectedValue[row.id] === null ? undefined : null)}
-                style={{ width: '16px', height: '16px', accentColor: '#e20074', cursor: 'pointer' }} />
+                style={{ width: '16px', height: '16px', accentColor: focusRingVar, cursor: 'pointer' }} />
               <span style={{ fontSize: '14px', fontWeight: 500, color: '#4b5563' }}>Not Applicable</span>
             </label>
           )}
@@ -387,7 +384,7 @@ function CsatMatrixGrid({
                 <label style={{ cursor: 'pointer' }}>
                   <input type="checkbox" checked={selectedValue[row.id] === null}
                     onChange={() => onCellSelect(row.id, selectedValue[row.id] === null ? undefined : null)}
-                    style={{ width: '16px', height: '16px', accentColor: '#e20074', cursor: 'pointer' }} />
+                    style={{ width: '16px', height: '16px', accentColor: focusRingVar, cursor: 'pointer' }} />
                 </label>
               </div>
             )}
@@ -490,13 +487,8 @@ function CsatMatrixCarousel({
             const EmojiNode = isEmoji ? getEmojiForIndex(displayIdx, scaleColumns.length) : null;
             const StarNode = isStar ? (isSelected ? (CsatStarIcons.filled as any) : (CsatStarIcons.empty as any)) : null;
             const RadioNode = (
-              <div style={{
-                display: 'flex', width: '18px', height: '18px',
-                alignItems: 'center', justifyContent: 'center', borderRadius: '50%',
-                margin: '0 auto', border: isSelected ? '2px solid #e20074' : '2px solid #d1d5db',
-                backgroundColor: '#fff',
-              }}>
-                {isSelected && <div style={{ width: '8px', height: '8px', borderRadius: '50%', backgroundColor: '#e20074' }} />}
+              <div style={matrixRadioRingStyle(isSelected, '18px')}>
+                <div style={matrixRadioDotStyle(isSelected, '8px')} />
               </div>
             );
 
@@ -518,7 +510,9 @@ function CsatMatrixCarousel({
                       padding: '4px', transform: isHovered ? 'scale(1.1)' : 'scale(1)', opacity: isSelected ? 1 : isHovered ? 1 : 0.5,
                     } : isNumbered ? {
                       width: '40px', height: '40px', borderRadius: '8px', fontSize: '14px', fontWeight: 500,
-                      border: `1px solid ${isSelected ? '#e20074' : '#d1d5db'}`, backgroundColor: isSelected ? '#e20074' : '#fff', color: isSelected ? '#fff' : '#111827',
+                      ...(isSelected
+                        ? scaleCellSelectedStyle(true)
+                        : { border: '1px solid #d1d5db', backgroundColor: '#fff', color: '#111827' }),
                     } : { padding: '8px' }),
                   }}
                 >
@@ -537,7 +531,7 @@ function CsatMatrixCarousel({
           <label style={{ display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
             <input type="checkbox" checked={selectedValue[row.id] === null}
                    onChange={() => onCellSelect(row.id, selectedValue[row.id] === null ? undefined : null)}
-                   style={{ width: '16px', height: '16px', accentColor: '#e20074', cursor: 'pointer' }} />
+                   style={{ width: '16px', height: '16px', accentColor: focusRingVar, cursor: 'pointer' }} />
             <span style={{ fontSize: '14px', fontWeight: 500, color: '#4b5563' }}>N/A</span>
           </label>
         </div>
@@ -559,7 +553,7 @@ function CsatMatrixCarousel({
             <button key={i} type="button" onClick={() => setActiveCarouselIndex(i)}
                     style={{
                       width: i === activeCarouselIndex ? '20px' : '8px', height: '8px', borderRadius: '4px',
-                      backgroundColor: i === activeCarouselIndex ? '#e20074' : '#d1d5db', border: 'none', padding: 0,
+                      backgroundColor: i === activeCarouselIndex ? mcqSelectedAccentVar : '#d1d5db', border: 'none', padding: 0,
                       cursor: 'pointer', transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)'
                     }} />
           ))}

package/templates/docs/templates/CustomSliderTrack.tsx

@@ -50,7 +50,9 @@ export function CustomSliderTrack({
     ? tooltipLabel.replace(/<[^>]*>/g, '')
     : String(Math.round(value));
 
-  const themeColor = disabled ? '#9ca3af' : 'var(--cfm-input-focus-ring, var(--cfm-primary))';
+  const themeColor = disabled
+    ? '#9ca3af'
+    : 'var(--cfm-slider-thumb, var(--cfm-input-focus-ring, var(--cfm-primary)))';
 
   return (
     <div
@@ -127,7 +129,7 @@ export function CustomSliderTrack({
       {(isHovered || isDragging) && !disabled && (
         <div style={{
           position: 'absolute', bottom: '100%', left: `${percentage}%`, transform: 'translate(-50%, -10px)',
-          backgroundColor: '#1f2937', color: '#fff', fontSize: '13px', fontWeight: 600,
+          backgroundColor: 'var(--cfm-tooltip-bg, #1f2937)', color: '#fff', fontSize: '13px', fontWeight: 600,
           padding: '4px 10px', borderRadius: '6px', pointerEvents: 'none',
           boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1)', zIndex: 20,
         }}>
@@ -135,7 +137,7 @@ export function CustomSliderTrack({
           <div style={{
             position: 'absolute', top: '100%', left: '50%', transform: 'translateX(-50%)',
             borderWidth: '5px', borderStyle: 'solid',
-            borderColor: '#1f2937 transparent transparent transparent',
+            borderColor: 'var(--cfm-tooltip-bg, #1f2937) transparent transparent transparent',
           }} />
         </div>
       )}

package/templates/docs/templates/FileUploadScale.tsx

@@ -8,6 +8,7 @@
 
 import React, { useState, useRef } from 'react';
 import type { FileUploadQuestion } from '@explorer02/cfm-survey-sdk';
+import { focusRingVar, mcqSelectedBgVar } from '@/lib/surveyUi/selectionStyles';
 
 type UploadedFileAnswer = {
   id: string;
@@ -86,8 +87,20 @@ function FileUploadDropzone({
   onDrag: (e: React.DragEvent) => void;
   onDrop: (e: React.DragEvent) => void;
 }) {
+  const baseBorder = 'var(--cfm-upload-border-color, #d1d5db)';
+  const activeBorder = focusRingVar;
+  const baseBg = 'var(--cfm-upload-fill, #f9fafb)';
+  const activeBg = mcqSelectedBgVar;
+  const borderStyle =
+    typeof document !== 'undefined'
+      ? getComputedStyle(document.documentElement).getPropertyValue('--cfm-upload-border-style').trim() ||
+        'dashed'
+      : 'dashed';
+
   return (
     <div
+      data-cfm-dropzone
+      className="cfm-dropzone"
       onDragEnter={onDrag}
       onDragOver={onDrag}
       onDragLeave={onDrag}
@@ -98,17 +111,45 @@ function FileUploadDropzone({
         flexDirection: 'column',
         alignItems: 'center',
         justifyContent: 'center',
-        border: `2px ${isDragActive ? 'solid' : 'var(--cfm-upload-border-style, dashed)'} var(--cfm-upload-border-color, #d1d5db)`,
+        border: `2px ${borderStyle} ${isDragActive ? activeBorder : baseBorder}`,
         borderRadius: 'var(--cfm-border-radius, 12px)',
-        backgroundColor: isDragActive ? 'var(--cfm-mcq-selected-bg, #fdf2f8)' : 'var(--cfm-upload-fill, #f9fafb)',
+        backgroundColor: isDragActive ? activeBg : baseBg,
         padding: 'var(--cfm-upload-padding, 40px 24px)',
         cursor: disabled ? 'not-allowed' : 'pointer',
         opacity: disabled ? 0.6 : 1,
         textAlign: 'center',
         boxSizing: 'border-box',
+        transition: 'all 0.2s ease-in-out',
+      }}
+      onMouseEnter={e => {
+        if (disabled) return;
+        e.currentTarget.style.borderColor = activeBorder;
+        e.currentTarget.style.backgroundColor = activeBg;
+      }}
+      onMouseLeave={e => {
+        if (disabled || isDragActive) return;
+        e.currentTarget.style.borderColor = baseBorder;
+        e.currentTarget.style.backgroundColor = baseBg;
       }}
     >
-      <div style={{ fontSize: '16px', fontWeight: 600, color: '#374151', marginBottom: '8px' }}
+      <div style={{ marginBottom: '16px', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+        <svg
+          width="40"
+          height="40"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="var(--cfm-upload-icon-color, #9ca3af)"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+          <polyline points="17 8 12 3 7 8" />
+          <line x1="12" y1="3" x2="12" y2="15" />
+        </svg>
+      </div>
+      <div
+        style={{ fontSize: '16px', fontWeight: 600, color: '#374151', marginBottom: '8px' }}
         dangerouslySetInnerHTML={{ __html: uploadMessage }}
       />
       <div style={{ fontSize: '13px', color: '#6b7280', lineHeight: 1.5 }}>
@@ -120,6 +161,104 @@ function FileUploadDropzone({
   );
 }
 
+function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+function UploadedFileList({
+  files,
+  onRemoveFile,
+}: {
+  files: UploadedFileAnswer[];
+  onRemoveFile: (index: number) => void;
+}) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+      {files.map((file, idx) => (
+        <div
+          key={file.id}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            padding: '12px 16px',
+            backgroundColor: 'var(--cfm-card-bg, #fff)',
+            border: '1px solid var(--cfm-card-border-color, #e5e7eb)',
+            borderRadius: 'var(--cfm-border-radius, 8px)',
+            boxSizing: 'border-box',
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: '12px', overflow: 'hidden' }}>
+            <svg
+              width="20"
+              height="20"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="#6b7280"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            >
+              <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+              <polyline points="14 2 14 8 20 8" />
+            </svg>
+            <div style={{ display: 'flex', flexDirection: 'column', overflow: 'hidden' }}>
+              <span
+                style={{
+                  fontSize: '14px',
+                  fontWeight: 500,
+                  color: '#374151',
+                  textOverflow: 'ellipsis',
+                  overflow: 'hidden',
+                  whiteSpace: 'nowrap',
+                }}
+              >
+                {file.name ?? file.mediaUrl}
+              </span>
+              {file.size != null && (
+                <span style={{ fontSize: '12px', color: '#9ca3af' }}>{formatFileSize(file.size)}</span>
+              )}
+            </div>
+          </div>
+          <button
+            type="button"
+            onClick={() => onRemoveFile(idx)}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: '24px',
+              height: '24px',
+              borderRadius: '50%',
+              backgroundColor: '#f3f4f6',
+              border: 'none',
+              color: '#6b7280',
+              cursor: 'pointer',
+              fontSize: '14px',
+              fontWeight: 'bold',
+              transition: 'background-color 0.2s',
+            }}
+            onMouseEnter={e => {
+              e.currentTarget.style.backgroundColor = '#fee2e2';
+              e.currentTarget.style.color = '#ef4444';
+            }}
+            onMouseLeave={e => {
+              e.currentTarget.style.backgroundColor = '#f3f4f6';
+              e.currentTarget.style.color = '#6b7280';
+            }}
+          >
+            &times;
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+
 export function FileUploadScale({ question, selectedValue, onSelect }: FileUploadScaleProps) {
   const {
     uploadMessage = 'Drag attachments here or browse',
@@ -241,21 +380,7 @@ export function FileUploadScale({ question, selectedValue, onSelect }: FileUploa
       )}
 
       {currentFiles.length > 0 && (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
-          {currentFiles.map((file, idx) => (
-            <div key={file.id} style={{
-              display: 'flex', alignItems: 'center', justifyContent: 'space-between',
-              padding: '12px 16px', backgroundColor: '#fff', border: '1px solid #e5e7eb', borderRadius: '8px',
-            }}>
-              <span style={{ fontSize: '14px', fontWeight: 500, color: '#374151' }}>{file.name ?? file.mediaUrl}</span>
-              <button type="button" onClick={() => removeFile(idx)} style={{
-                border: 'none', background: '#f3f4f6', borderRadius: '50%', width: 24, height: 24, cursor: 'pointer',
-              }}>
-                ×
-              </button>
-            </div>
-          ))}
-        </div>
+        <UploadedFileList files={currentFiles} onRemoveFile={removeFile} />
       )}
     </div>
   );

package/templates/docs/templates/Header.tsx

@@ -56,6 +56,7 @@ export default function Header({ embedded = false }: HeaderProps) {
               style={{
                 width: 'var(--cfm-header-logo-width, 120px)',
                 height: 'var(--cfm-header-logo-height, 120px)',
+                maxHeight: 'calc(var(--cfm-header-height, 120px) - 8px)',
                 padding: 'var(--cfm-header-logo-padding, 10px)',
                 background: 'transparent',
               }}

package/templates/docs/templates/HeatmapScale.tsx

@@ -2,7 +2,7 @@
 
 /**
  * Portable HeatmapScale — copy to src/components/HeatmapScale.tsx
- * Also copy templates/heatmapCoords.ts to src/lib/heatmapCoords.ts
+ * Also copy templates/heatmapCoords.ts to src/lib/surveyUi/heatmapCoords.ts
  */
 
 import React, { useState } from 'react';
@@ -11,7 +11,7 @@ import {
   createNewSpot,
   findSpotNearClick,
   getNormalizedClickFromImage,
-} from './heatmapCoords';
+} from '@/lib/surveyUi/heatmapCoords';
 
 type HeatmapScaleProps = {
   question: HeatmapQuestion;
@@ -91,6 +91,15 @@ export function HeatmapScale({ question, selectedValue = [], onSelect }: Heatmap
           className="block max-w-full h-auto select-none rounded-md"
           style={{ cursor: isImageReady ? 'crosshair' : 'default' }}
         />
+        {isImageReady && (
+          <div
+            className="pointer-events-none absolute inset-0 rounded-md"
+            style={{
+              backgroundColor: '#000000',
+              opacity: 'var(--cfm-heatmap-overlay-opacity, 0)',
+            }}
+          />
+        )}
         {isImageReady && (
           <div className="pointer-events-none absolute inset-0">
             {spots.map(spot => (

package/templates/docs/templates/LanguageSelector.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import type { SurveyLanguage } from '@explorer02/cfm-survey-sdk';
+import { focusRingVar } from '@/lib/surveyUi/selectionStyles';
 
 type LanguageSelectorProps = {
   languages: SurveyLanguage[];
@@ -14,27 +15,49 @@ export default function LanguageSelector({
   selectedLanguage,
   onChange,
 }: LanguageSelectorProps) {
-  if (languages.length <= 1) return null;
+  if (!languages || languages.length <= 1) return null;
 
   return (
-    <div data-cfm-language className="mb-6 flex justify-end">
-      <select
-        value={selectedLanguage}
-        onChange={(e) => onChange(e.target.value)}
-        className="rounded border px-3 py-1.5 text-sm outline-none"
-        style={{
-          background: 'var(--cfm-language-bg, #fff)',
-          color: 'var(--cfm-language-text, #2563eb)',
-          borderColor: 'var(--cfm-language-border, #2563eb)',
-          borderRadius: 'var(--cfm-border-radius, 8px)',
-        }}
-      >
-        {languages.map((lang) => (
-          <option key={lang.code} value={lang.code}>
-            {lang.label}
-          </option>
-        ))}
-      </select>
+    <div data-cfm-language className="mb-6 mt-4 flex justify-end">
+      <div className="relative">
+        <select
+          value={selectedLanguage}
+          onChange={(e) => onChange(e.target.value)}
+          className="cursor-pointer appearance-none py-2 pl-4 pr-10 text-sm font-semibold outline-none focus:ring-2"
+          style={{
+            background: 'var(--cfm-language-bg, #fff)',
+            color: 'var(--cfm-language-text, #2563eb)',
+            borderColor: 'var(--cfm-language-border, #2563eb)',
+            borderWidth: 1,
+            borderStyle: 'solid',
+            borderRadius: 'var(--cfm-border-radius, 8px)',
+            boxShadow: `0 0 0 0px ${focusRingVar}`,
+          }}
+          onFocus={e => {
+            e.currentTarget.style.boxShadow = `0 0 0 2px ${focusRingVar}`;
+          }}
+          onBlur={e => {
+            e.currentTarget.style.boxShadow = 'none';
+          }}
+        >
+          {languages.map((lang) => (
+            <option key={lang.code} value={lang.code} className="text-gray-900">
+              {lang.name}
+            </option>
+          ))}
+        </select>
+        <div className="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-3">
+          <svg
+            className="h-4 w-4"
+            style={{ color: 'var(--cfm-language-text, #2563eb)' }}
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M19 9l-7 7-7-7" />
+          </svg>
+        </div>
+      </div>
     </div>
   );
 }