From 5f21c5fc20ae21cbfdabede4c65f5e00f1d0f70e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 07:34:02 +0000
Subject: [PATCH 1/2] feat(configurator): screenshot QA, mobile ergonomics,
 control UX
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Item 6 — Screenshot QA
- Add tests-e2e/screenshots.spec.js: 9 domains × 3 viewports (1280/768/390px)
- Add 'screenshots' project to playwright.config.js

Item 7 — Mobile ergonomics
- app.css: 44px touch targets for cfg-btn/cfg-input/cfg-select at ≤980px
- StudioFrame: hide description and shrink h3 at ≤820px
- StudioWorkflow + LayoutStudio: horizontal scroll at ≤480px
- ControlSection: default-closed on mobile (window.innerWidth < 768)

Item 8 — "What does this control do"
- FriendlyControl: "drives N" badge via dependentsCount(); ≥10 = master
- ControlPreview: caption label below each preview widget
- SmartSettings: drives count in section summary; token count in reset

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 configurator/playwright.config.js             |  1 +
 .../src/components/ControlPreview.svelte      |  9 ++++++
 .../src/components/ControlSection.svelte      |  3 +-
 .../src/components/FriendlyControl.svelte     | 11 +++++--
 .../src/components/SmartSettings.svelte       | 12 +++++--
 .../components/editors/LayoutStudio.svelte    |  1 +
 .../src/components/editors/StudioFrame.svelte |  8 ++++-
 .../components/editors/StudioWorkflow.svelte  |  1 +
 configurator/src/styles/app.css               |  9 ++++++
 configurator/tests-e2e/screenshots.spec.js    | 32 +++++++++++++++++++
 10 files changed, 81 insertions(+), 6 deletions(-)
 create mode 100644 configurator/tests-e2e/screenshots.spec.js

diff --git a/configurator/playwright.config.js b/configurator/playwright.config.js
index f5303d4c..1d5e8f54 100644
--- a/configurator/playwright.config.js
+++ b/configurator/playwright.config.js
@@ -34,6 +34,7 @@ export default defineConfig({
     { name: 'chromium', use: { browserName: 'chromium' } },
     { name: 'firefox', use: { browserName: 'firefox' }, testMatch: CROSS_ENGINE },
     { name: 'webkit', use: { browserName: 'webkit' }, testMatch: CROSS_ENGINE },
+    { name: 'screenshots', use: { browserName: 'chromium' }, testMatch: '**/screenshots.spec.js' },
   ],
   webServer: {
     command: 'npm run preview -- --port 4173 --strictPort',
diff --git a/configurator/src/components/ControlPreview.svelte b/configurator/src/components/ControlPreview.svelte
index fdcdf56a..70cafc91 100644
--- a/configurator/src/components/ControlPreview.svelte
+++ b/configurator/src/components/ControlPreview.svelte
@@ -4,6 +4,13 @@
   let { token, value = '', type = 'text', label = '' } = $props();
   const active = $derived(value || overrides[token?.name] || token?.value || '');
   const stageStyle = $derived(buildPreviewDeclarations(overrides, ui.previewTheme));
+  const LABELS = {
+    color: 'colour', font: 'typeface', radius: 'corner', shadow: 'elevation',
+    motion: 'timing', 'line-height': 'leading', wrap: 'text wrap',
+    opacity: 'opacity', gradient: 'gradient', border: 'border style',
+    media: 'object fit', scale: 'scale', spacing: 'size',
+  };
+  const caption = $derived(LABELS[type] ?? type);
 </script>
 
 <div class="ctrl-preview" style={stageStyle} title={token?.name || label}>
@@ -37,6 +44,7 @@
     <div class="ctrl-preview__spacing"><span style:inline-size={active || '40%'}></span></div>
   {/if}
 </div>
+<p class="ctrl-preview__cap">{caption}</p>
 
 <style>
   .ctrl-preview { min-height: 54px; border: 1px solid var(--cfg-border); border-radius: var(--cfg-radius-s); background: var(--cfg-bg-2); padding: 10px; overflow: hidden; color: var(--sf-color-text, var(--cfg-text)); }
@@ -59,5 +67,6 @@
   .ctrl-preview__scale span { inline-size:30px; block-size:30px; border-radius:8px; background:var(--cfg-accent-strong); }
   .ctrl-preview__spacing { min-height: 34px; display:flex; align-items:center; }
   .ctrl-preview__spacing span { display:block; block-size: 14px; max-inline-size:100%; min-inline-size:12px; border-radius:999px; background: var(--cfg-accent-strong); }
+  .ctrl-preview__cap { margin: 2px 0 0; font-size: 10px; text-transform: uppercase; letter-spacing: .06em; color: var(--cfg-text-faint); text-align: center; }
   @keyframes cp-move { to { transform: translateX(min(120px, 35vw)); } }
 </style>
diff --git a/configurator/src/components/ControlSection.svelte b/configurator/src/components/ControlSection.svelte
index c3f18a19..7f778996 100644
--- a/configurator/src/components/ControlSection.svelte
+++ b/configurator/src/components/ControlSection.svelte
@@ -1,8 +1,9 @@
 <script>
   let { title, hint = '', modifiedCount = 0, defaultOpen = true, children } = $props();
+  let open = $state(window.innerWidth >= 768 ? defaultOpen : false);
 </script>
 
-<details class="control-section" open={defaultOpen}>
+<details class="control-section" open={open} ontoggle={(e) => (open = e.currentTarget.open)}>
   <summary>
     <span class="control-section__chev">›</span>
     <strong>{title}</strong>
diff --git a/configurator/src/components/FriendlyControl.svelte b/configurator/src/components/FriendlyControl.svelte
index 7d585877..20d90c93 100644
--- a/configurator/src/components/FriendlyControl.svelte
+++ b/configurator/src/components/FriendlyControl.svelte
@@ -1,6 +1,7 @@
 <script>
   import { overrides, clearOverride, setOverride } from '../lib/store.svelte.js';
   import { controlForToken } from '../lib/controlSchema.js';
+  import { dependentsCount } from '../lib/model.js';
   import TokenEditor from './TokenEditor.svelte';
   import ControlPreview from './ControlPreview.svelte';
   let { token, label = '', help = '', schema = {}, showToken = false } = $props();
@@ -9,6 +10,7 @@
   const desc = $derived(help || meta.description);
   const modified = $derived(overrides[token.name] != null);
   const activeValue = $derived(overrides[token.name] ?? token.value ?? '');
+  const drives = $derived(dependentsCount(token?.name ?? ''));
   let rawOpen = $state(false);
 
   function onSelect(e) {
@@ -20,7 +22,10 @@
   <div class="friendly__copy">
     <div class="friendly__top">
       <strong>{title}</strong>
-      {#if modified}<span>modified</span>{/if}
+      {#if modified}<span class="friendly__mod">modified</span>{/if}
+      {#if drives > 0}
+        <span class="friendly__drives" class:friendly__drives--master={drives >= 10} title="{drives} token{drives === 1 ? '' : 's'} reference this via var()">drives {drives}</span>
+      {/if}
     </div>
     {#if desc}<p>{desc}</p>{/if}
     {#if showToken || rawOpen}<code class="friendly__token">{token.name}</code>{/if}
@@ -53,7 +58,9 @@
   .friendly__copy { min-width: 0; display:grid; gap:4px; }
   .friendly__top { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
   .friendly__top strong { font-size: 13px; }
-  .friendly__top span { font-size: 10px; text-transform: uppercase; color: var(--cfg-accent); border: 1px solid color-mix(in oklab, var(--cfg-accent) 40%, transparent); border-radius: 999px; padding: 1px 6px; }
+  .friendly__mod { font-size: 10px; text-transform: uppercase; color: var(--cfg-accent); border: 1px solid color-mix(in oklab, var(--cfg-accent) 40%, transparent); border-radius: 999px; padding: 1px 6px; }
+  .friendly__drives { font-size: 10px; text-transform: uppercase; letter-spacing: .06em; color: var(--cfg-text-faint); border: 1px solid var(--cfg-border); border-radius: 999px; padding: 1px 6px; }
+  .friendly__drives--master { color: var(--cfg-accent); border-color: color-mix(in oklab, var(--cfg-accent) 40%, transparent); }
   .friendly__copy p { margin: 0; color: var(--cfg-text-muted); font-size: 12px; }
   .friendly__token { color: var(--cfg-text-faint); font-size: 11px; word-break: break-all; }
   .friendly__editor { min-width: 0; }
diff --git a/configurator/src/components/SmartSettings.svelte b/configurator/src/components/SmartSettings.svelte
index 36e9a235..6abe9787 100644
--- a/configurator/src/components/SmartSettings.svelte
+++ b/configurator/src/components/SmartSettings.svelte
@@ -1,6 +1,6 @@
 <script>
   import { overrides, ui, patchOverrides, setOverride, dragSetOverride, endDrag } from '../lib/store.svelte.js';
-  import { tokenByName } from '../lib/model.js';
+  import { tokenByName, dependentsCount } from '../lib/model.js';
   import { sectionTokenNames, smartSettingsFor } from '../lib/domainSettings.js';
   import { buildPreviewDeclarations } from '../lib/preview.js';
   import { getFold, setFold } from '../lib/foldState.js';
@@ -15,6 +15,10 @@
   const exists = (name) => tokenByName.has(name);
   const token = (name) => tokenByName.get(name);
 
+  function sectionDrives(section) {
+    return sectionTokenNames(section).filter(exists).reduce((acc, name) => acc + dependentsCount(name), 0);
+  }
+
   function cleanPatch(section, patch) {
     const names = new Set(sectionTokenNames(section).filter(exists));
     if (patch == null) return Object.fromEntries([...names].map((name) => [name, null]));
@@ -67,6 +71,8 @@
 {#if sections.length}
   <div class="smart">
     {#each sections as section (section.id)}
+      {@const totalDrives = sectionDrives(section)}
+      {@const tokenCount = sectionTokenNames(section).filter(exists).length}
       <details
         class="cfg-card smart__section"
         open={getFold(`${domainId}:${section.id}`, true)}
@@ -76,6 +82,7 @@
           <span class="smart__chev" aria-hidden="true">›</span>
           <span class="smart__title">{section.title}</span>
           {#if section.hint}<span class="smart__hint">{section.hint}</span>{/if}
+          {#if totalDrives > 0}<span class="smart__drives">drives {totalDrives}</span>{/if}
         </summary>
 
         <div class="smart__actions" aria-label="{section.title} actions">
@@ -86,7 +93,7 @@
               {/each}
             </div>
           {/if}
-          <button type="button" class="cfg-btn cfg-btn--ghost cfg-btn--sm smart__reset" onclick={() => resetSection(section)}>Reset section</button>
+          <button type="button" class="cfg-btn cfg-btn--ghost cfg-btn--sm smart__reset" onclick={() => resetSection(section)}>Reset section ({tokenCount})</button>
         </div>
 
         {#if section.kind === 'sliders'}
@@ -173,6 +180,7 @@
   .smart__chev { color: var(--cfg-text-faint); transition: transform .14s; }
   .smart__title { font-size: 12.5px; font-weight: 800; text-transform: uppercase; letter-spacing: .06em; }
   .smart__hint { color: var(--cfg-text-faint); font-size: 12px; flex: 1 1 260px; }
+  .smart__drives { font-size: 10px; text-transform: uppercase; letter-spacing: .06em; color: var(--cfg-accent); border: 1px solid color-mix(in oklab, var(--cfg-accent) 35%, transparent); border-radius: 999px; padding: 2px 7px; }
   .smart__actions { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 16px; border-bottom: 1px solid var(--cfg-border); flex-wrap: wrap; }
   .smart__reset { margin-left: auto; }
   .smart__presets { display: flex; gap: 8px; flex-wrap: wrap; }
diff --git a/configurator/src/components/editors/LayoutStudio.svelte b/configurator/src/components/editors/LayoutStudio.svelte
index 106b185f..08764cdb 100644
--- a/configurator/src/components/editors/LayoutStudio.svelte
+++ b/configurator/src/components/editors/LayoutStudio.svelte
@@ -88,4 +88,5 @@
   .legend b { font-size: 11px; color: var(--cfg-text-muted); text-transform: uppercase; }
   @media (max-width: 840px) { .composition, .measure-lab { grid-template-columns: 1fr; } }
   @media (max-width: 640px) { .workflow, .device-strip { grid-template-columns: 1fr 1fr; } }
+  @media (max-width: 480px) { .workflow { grid-template-columns: repeat(4, minmax(110px, 1fr)); overflow-x: auto; padding-bottom: 4px; } }
 </style>
diff --git a/configurator/src/components/editors/StudioFrame.svelte b/configurator/src/components/editors/StudioFrame.svelte
index 75def248..8f4d986e 100644
--- a/configurator/src/components/editors/StudioFrame.svelte
+++ b/configurator/src/components/editors/StudioFrame.svelte
@@ -26,5 +26,11 @@
   .studio__steps { display: grid; gap: 6px; margin-top: 6px; list-style: none; padding: 0; }
   .studio__steps li { padding: 7px 9px; border: 1px solid var(--cfg-border); border-radius: 999px; background: var(--cfg-bg-2); color: var(--cfg-text-muted); font-size: 10px; font-weight: 800; text-transform: uppercase; letter-spacing: .08em; }
   .studio__surface { min-width: 0; }
-  @media (max-width: 820px) { .studio { grid-template-columns: 1fr; padding: 12px; } .studio__copy { position: static; } .studio__steps { grid-template-columns: repeat(3, 1fr); } }
+  @media (max-width: 820px) {
+    .studio { grid-template-columns: 1fr; padding: 12px; }
+    .studio__copy { position: static; }
+    .studio__copy h3 { font-size: clamp(18px, 4vw, 26px); }
+    .studio__copy span { display: none; }
+    .studio__steps { grid-template-columns: repeat(3, 1fr); }
+  }
 </style>
diff --git a/configurator/src/components/editors/StudioWorkflow.svelte b/configurator/src/components/editors/StudioWorkflow.svelte
index 103f99fc..cea3e2a7 100644
--- a/configurator/src/components/editors/StudioWorkflow.svelte
+++ b/configurator/src/components/editors/StudioWorkflow.svelte
@@ -15,4 +15,5 @@
   .studio-workflow li { display: flex; align-items: center; gap: 8px; padding: 9px 10px; border: 1px solid var(--cfg-border); border-radius: var(--cfg-radius-s); background: var(--cfg-bg-2); color: var(--cfg-text-muted); font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .06em; }
   .studio-workflow b { display: grid; place-items: center; inline-size: 20px; block-size: 20px; border-radius: 999px; background: var(--cfg-accent-strong); color: white; font-size: 10px; }
   @media (max-width: 640px) { .studio-workflow { grid-template-columns: 1fr 1fr; } }
+  @media (max-width: 480px) { .studio-workflow { grid-template-columns: repeat(var(--workflow-cols, 4), minmax(110px, 1fr)); overflow-x: auto; padding-bottom: 4px; } }
 </style>
diff --git a/configurator/src/styles/app.css b/configurator/src/styles/app.css
index 66e2b5db..4a841830 100644
--- a/configurator/src/styles/app.css
+++ b/configurator/src/styles/app.css
@@ -270,5 +270,14 @@ code, kbd { font-family: var(--cfg-mono); }
   line-height: 1.4;
 }
 
+/* ─── Touch targets (WCAG 2.5.5 — 44×44px minimum) ────────────────────── */
+@media (max-width: 980px) {
+  .cfg-btn           { min-height: 44px; padding-block: 10px; }
+  .cfg-btn--sm       { min-height: 36px; padding-block: 6px; }
+  .cfg-input,
+  .cfg-select        { min-height: 44px; padding-block: 10px; }
+  input[type='range'] { min-height: 36px; }
+}
+
 /* No per-theme overrides needed: every chrome colour derives from --sf-* tokens
    that already adapt to the framework's [data-theme] light/dark switch. */
diff --git a/configurator/tests-e2e/screenshots.spec.js b/configurator/tests-e2e/screenshots.spec.js
new file mode 100644
index 00000000..51dc97c4
--- /dev/null
+++ b/configurator/tests-e2e/screenshots.spec.js
@@ -0,0 +1,32 @@
+/**
+ * Screenshot QA — captures every Studio domain at three viewport widths.
+ *
+ * Not part of the main regression suite (separate "screenshots" project in
+ * playwright.config.js). Run with:
+ *
+ *   npx playwright test --project=screenshots --reporter=html
+ *
+ * Output: test-results/screenshots/<domain>-<width>.png  (27 files)
+ */
+import { test } from '@playwright/test';
+import { gotoClean, sideItem } from './helpers.js';
+
+const DOMAINS = ['Colors', 'Typography', 'Spacing', 'Layout', 'Borders', 'Shadows', 'Motion', 'Effects', 'Misc'];
+const WIDTHS = [1280, 768, 390];
+
+test.describe('Studio screenshot QA', () => {
+  for (const domain of DOMAINS) {
+    for (const width of WIDTHS) {
+      test(`${domain} @ ${width}px`, async ({ page }) => {
+        await page.setViewportSize({ width, height: 900 });
+        await gotoClean(page);
+        await sideItem(page, domain).click();
+        await page.waitForLoadState('networkidle');
+        await page.screenshot({
+          path: `test-results/screenshots/${domain.toLowerCase()}-${width}.png`,
+          fullPage: true,
+        });
+      });
+    }
+  }
+});

From 5454930a65e4e3054d057089d43d01ebaf862796 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 08:05:07 +0000
Subject: [PATCH 2/2] fix(configurator): address CodeRabbit review comments

- playwright.config.js: exclude screenshots.spec.js from the default
  chromium project so it only runs under the dedicated screenshots
  project (prevents duplicate runs in CI)
- app.css: bump .cfg-btn--sm and input[type='range'] to 44px min-height
  in the touch-target media query so all interactive controls meet
  WCAG 2.5.5 consistently

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 configurator/playwright.config.js | 2 +-
 configurator/src/styles/app.css   | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/configurator/playwright.config.js b/configurator/playwright.config.js
index 1d5e8f54..82cebe12 100644
--- a/configurator/playwright.config.js
+++ b/configurator/playwright.config.js
@@ -31,7 +31,7 @@ export default defineConfig({
     viewport: { width: 1600, height: 1000 },
   },
   projects: [
-    { name: 'chromium', use: { browserName: 'chromium' } },
+    { name: 'chromium', use: { browserName: 'chromium' }, testIgnore: '**/screenshots.spec.js' },
     { name: 'firefox', use: { browserName: 'firefox' }, testMatch: CROSS_ENGINE },
     { name: 'webkit', use: { browserName: 'webkit' }, testMatch: CROSS_ENGINE },
     { name: 'screenshots', use: { browserName: 'chromium' }, testMatch: '**/screenshots.spec.js' },
diff --git a/configurator/src/styles/app.css b/configurator/src/styles/app.css
index 4a841830..7a83438a 100644
--- a/configurator/src/styles/app.css
+++ b/configurator/src/styles/app.css
@@ -273,10 +273,10 @@ code, kbd { font-family: var(--cfg-mono); }
 /* ─── Touch targets (WCAG 2.5.5 — 44×44px minimum) ────────────────────── */
 @media (max-width: 980px) {
   .cfg-btn           { min-height: 44px; padding-block: 10px; }
-  .cfg-btn--sm       { min-height: 36px; padding-block: 6px; }
+  .cfg-btn--sm       { min-height: 44px; padding-block: 10px; }
   .cfg-input,
   .cfg-select        { min-height: 44px; padding-block: 10px; }
-  input[type='range'] { min-height: 36px; }
+  input[type='range'] { min-height: 44px; }
 }
 
 /* No per-theme overrides needed: every chrome colour derives from --sf-* tokens