feat(a11y): add .sf-touch-target opt-in class for the WCAG 44px hit area

Scoping the automatic coarse-pointer floor to class-less controls (prev
commit) left classed controls — i.e. almost all real-world controls —
with no first-class way to request the 44px target beyond hand-rolling
min-sizes or the .sf-btn-only --sf-btn-min-height knob. Add the explicit
opt-in counterpart so the floor stays a safety net for bare markup while
the everyday mechanism is a class.

.sf-touch-target enforces min-block-size/min-inline-size:
var(--sf-touch-target) on both axes and centres a short label via
inline-flex (so it also works on inline elements like <a>). It lives in
core/accessibility.css alongside .sr-only / .skip-link / .sf-focus-shadow,
so it ships in every bundle, not just full. It is a single class
(specificity 0,1,0) with no !important, so a component rule can still opt a
specific control back out. Unlike the automatic floor it is not gated to a
coarse pointer — an explicit opt-in is predictable on every device.

- core/accessibility.css: add the .sf-touch-target helper + rationale
- tests/a11y-patterns.spec.js: enforce-on-classed-control and
  overridable-without-!important guards
- docs/migration.md: document .sf-touch-target as the primary remedy

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgL6mqSxe2ihjaUCxx78eR

Author: claude

configurator/src/data/classes.generated.json

@@ -3074,6 +3074,16 @@
       "optional": false,
       "layer": "slashed.themes"
     },
+    {
+      "name": "sf-touch-target",
+      "selector": ".sf-touch-target",
+      "kind": "accessibility",
+      "category": "Accessibility",
+      "group": "",
+      "description": ".sf-touch-target — the explicit opt-IN counterpart to the class-less floor above. Because the automatic floor deliberately never touches a control that carries a class, put this class on any control you own (a button with your own class, a link, a third-party widget you can add…",
+      "optional": false,
+      "layer": "slashed.accessibility"
+    },
     {
       "name": "sf-truncate",
       "selector": ".sf-truncate",

core/accessibility.css

@@ -127,6 +127,29 @@
     }
   }
 
+  /* .sf-touch-target — the explicit opt-IN counterpart to the class-less floor
+     above. Because the automatic floor deliberately never touches a control
+     that carries a class, put this class on any control you own (a button with
+     your own class, a link, a third-party widget you can add a class to) to
+     guarantee the WCAG 2.5.5 44px minimum hit area on both axes. Unlike the
+     automatic floor it is NOT gated to a coarse pointer — an explicit opt-in
+     is predictable everywhere. Size follows --sf-touch-target, so a wrapper (or
+     the element itself) can retune it locally; the flex centring keeps a short
+     label centred inside the enlarged box instead of pinned top-left.
+
+       <button class="my-menu-toggle sf-touch-target" aria-label="Menu">…</button>
+
+     No !important: it's a single class (specificity 0,1,0), so your own
+     component rule can still override it when a specific control needs to opt
+     back out. */
+  .sf-touch-target {
+    display:         inline-flex;
+    align-items:     center;
+    justify-content: center;
+    min-block-size:  var(--sf-touch-target);
+    min-inline-size: var(--sf-touch-target);
+  }
+
   /* Disabled states */
   [disabled],
   [aria-disabled="true"] {

docs/api-index.json

@@ -25,27 +25,27 @@
       "optimal"
     ],
     "counts": {
-      "total": 1053,
+      "total": 1054,
       "by_type": {
-        "class": 312,
+        "class": 313,
         "token": 741
       },
       "by_tier": {
         "INTERNAL": 1,
-        "PUBLIC": 1003,
+        "PUBLIC": 1004,
         "PUBLIC-ADVANCED": 49
       },
       "by_role": {
         "consumption": 488,
         "knob": 253
       },
       "tokens": 741,
-      "classes": 312,
-      "sf_classes": 289,
+      "classes": 313,
+      "sf_classes": 290,
       "is_classes": 15,
       "unprefixed_classes": 8,
       "by_category": {
-        "Accessibility": 8,
+        "Accessibility": 9,
         "Component tokens": 46,
         "Components": 30,
         "Core tokens": 610,
@@ -26314,6 +26314,29 @@
         "optimal"
       ]
     },
+    {
+      "name": "sf-touch-target",
+      "type": "class",
+      "tier": "PUBLIC",
+      "selector": ".sf-touch-target",
+      "prefix": "sf",
+      "kind": "accessibility",
+      "category": "Accessibility",
+      "area": "accessibility",
+      "group": "",
+      "description": ".sf-touch-target — the explicit opt-IN counterpart to the class-less floor above. Because the automatic floor deliberately never touches a control that carries a class, put this class on any control you own (a button with your own class, a link, a third-party widget you can add…",
+      "isVariant": false,
+      "baseClass": null,
+      "optional": false,
+      "layer": "slashed.accessibility",
+      "sourceFiles": [
+        "core/accessibility.css"
+      ],
+      "bundles": [
+        "full",
+        "optimal"
+      ]
+    },
     {
       "name": "sf-truncate",
       "type": "class",

docs/api-index.md

@@ -10,11 +10,11 @@ and a short description. The machine-readable companion (with all columns) is
 [registry.json](registry.json); for the tier contract see
 [architecture.md](architecture.md).
 
-**1053 elements** — 741 tokens, 312 classes.
+**1054 elements** — 741 tokens, 313 classes.
 
 | Tier | Count | Meaning |
 |---|---|---|
-| PUBLIC | 1003 | Everyday surface. SemVer-stable. |
+| PUBLIC | 1004 | Everyday surface. SemVer-stable. |
 | PUBLIC-ADVANCED | 49 | Same SemVer guarantee; niche/powerful. |
 | INTERNAL | 1 | Implementation detail; may change without a major bump. |
 
@@ -781,9 +781,9 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-surface-bg-size` | PUBLIC | knob | surface | `cover` | background-size for the .sf-surface-bg image. Default: cover. |
 | `--sf-surface-color` | PUBLIC | consumption | surface | `var(--sf-color-base)` | Input for the generic .sf-surface macro. Set any color (including palette shades); the macro derives background, auto-contrast foreground, and the contextual token set from it. |
 
-## Classes (312)
+## Classes (313)
 
-### Accessibility (8)
+### Accessibility (9)
 
 | Class | Tier | Kind | Group | Description |
 |---|---|---|---|---|
@@ -792,6 +792,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-clickable-parent__overlay` | PUBLIC | accessibility | — | The full-bleed overlay link inside an sf-clickable-parent. Stretches to cover the parent and uses pointer-events to let interactive children keep their own clicks. |
 | `.sf-focus-parent` | PUBLIC | accessibility | — | Forwards focus-visible styling to this container when any descendant is keyboard-focused. Useful for custom controls that wrap a visually-hidden <input>. |
 | `.sf-focus-shadow` | PUBLIC | accessibility | — | Applies the standard focus ring as a box-shadow to any element. Use on custom controls where the native :focus-visible ring doesn't render correctly. |
+| `.sf-touch-target` | PUBLIC | accessibility | — | .sf-touch-target — the explicit opt-IN counterpart to the class-less floor above. Because the automatic floor deliberately never touches a control that carries a class, put this class on any control you own (a button with your own class, a link, a third-party widget you can add… |
 | `.skip-link` | PUBLIC | accessibility | — | Accessible skip-navigation link. Hidden until focused; jumps keyboard users past repeated navigation blocks. Place as the very first element in <body>. |
 | `.sr-only` | PUBLIC | accessibility | — | Visually hides content while keeping it accessible to screen readers. Use for labels, descriptions, and off-screen text that assistive technology needs. |
 | `.sr-only-focusable` | PUBLIC | accessibility | — | Extends sr-only — also reveals the element when it receives keyboard focus. Typical use: skip links and visually-hidden focus targets. |

docs/classes.md

@@ -3,7 +3,7 @@
 > **Generated** from source by `scripts/gen-class-reference.js` —
 > run `npm run docs:classes` to refresh. Do not edit by hand.
 
-**289 .sf-classes, 15 .sf-is-classes.** Every `.sf-*` layout/macro class and `.sf-is-*` state class.
+**290 .sf-classes, 15 .sf-is-classes.** Every `.sf-*` layout/macro class and `.sf-is-*` state class.
 See [architecture.md](architecture.md) for layer order and naming conventions.
 
 ## Layout primitives (`core/layout.css`)
@@ -240,7 +240,7 @@ See [architecture.md](architecture.md) for layer order and naming conventions.
 
 ## Accessibility (`core/accessibility.css`)
 
-6 classes.
+7 classes.
 
 | Class |
 |---|
@@ -250,6 +250,7 @@ See [architecture.md](architecture.md) for layer order and naming conventions.
 | `.sf-focus-shadow` |
 | `.sf-is-loading` |
 | `.sf-text-gradient` |
+| `.sf-touch-target` |
 
 ## Motion / entrances (`core/motion.css`)
 

docs/migration.md

@@ -100,13 +100,27 @@ keeps whatever size its owner gives it. Genuinely bare, un-classed controls
 This generalises the earlier `.sf-btn` carve-out (see 0.7.8 → 0.8.0 below) into
 a single rule: *the framework never re-sizes a control someone else has styled.*
 
+Because most real controls carry a class, the automatic floor is now a
+**safety net for bare markup**, not the everyday mechanism. The everyday
+mechanism is the new opt-in class:
+
+**`.sf-touch-target` (new)** — the explicit counterpart to the class-less
+floor. Put it on any control you own to guarantee the WCAG 2.5.5 44px hit
+area on both axes; it lives in `core/accessibility.css` so it's in every
+bundle. Unlike the automatic floor it is not gated to a coarse pointer, and it
+centres a short label inside the enlarged box:
+
+```html
+<button class="my-menu-toggle sf-touch-target" aria-label="Menu">☰</button>
+```
+
 **What changed for you:**
 - A bare, class-less `<button>` / native control is unaffected — it still gets
   the 44px floor on touch.
-- A control that carries **any** class no longer gets the automatic floor on
-  touch. If you were relying on it for a class-bearing control, restore it
-  explicitly — set `min-block-size`/`min-inline-size` on that control, or on a
-  `.sf-btn` use `:root { --sf-btn-min-height: var(--sf-touch-target); }`.
+- A control that carries **any** class no longer gets the automatic floor. If
+  you want the 44px hit area on a class-bearing control, add `.sf-touch-target`
+  (or set `min-block-size`/`min-inline-size` yourself, or on a `.sf-btn` use
+  `:root { --sf-btn-min-height: var(--sf-touch-target); }`).
 - To opt a control **out** of the floor (e.g. a custom icon button that was
   being stretched), give it any class — no `!important` needed.
 

docs/registry.json

@@ -20,7 +20,7 @@
     ],
     "counts": {
       "tokens": 741,
-      "sf_classes": 289,
+      "sf_classes": 290,
       "is_classes": 15
     }
   },
@@ -1055,6 +1055,7 @@
     "sf-theme-dark",
     "sf-theme-light",
     "sf-theme-transition",
+    "sf-touch-target",
     "sf-truncate",
     "sf-visible"
   ],

tests/a11y-patterns.spec.js

@@ -199,6 +199,34 @@ test.describe('a11y: touch target token', () => {
     expect(px).toBeGreaterThanOrEqual(44);
   });
 
+  // .sf-touch-target — explicit opt-in for a classed control the automatic
+  // class-less floor no longer reaches. Not gated to a coarse pointer, so it
+  // enforces the 44px hit area here on a normal (fine) pointer too.
+  test('.sf-touch-target enforces a ≥44px hit area on both axes on a classed control', async ({ page }) => {
+    await setup(page, `<button id="t" class="my-toggle sf-touch-target"
+                               style="inline-size:20px;block-size:20px;padding:0">x</button>`);
+    const box = await page.locator('#t').evaluate(el => {
+      const r = el.getBoundingClientRect();
+      return { w: r.width, h: r.height };
+    });
+    expect(box.w).toBeGreaterThanOrEqual(44);
+    expect(box.h).toBeGreaterThanOrEqual(44);
+  });
+
+  // A single class (0,1,0) — a component rule can still override it without
+  // !important, so a specific control can opt back out.
+  test('.sf-touch-target is overridable by a plain class rule (no !important)', async ({ page }) => {
+    await setup(page, `<style>.small{min-block-size:20px;min-inline-size:20px}</style>
+                       <button id="t" class="sf-touch-target small"
+                               style="inline-size:20px;block-size:20px;padding:0">x</button>`);
+    const box = await page.locator('#t').evaluate(el => {
+      const r = el.getBoundingClientRect();
+      return { w: r.width, h: r.height };
+    });
+    expect(box.w).toBeLessThan(44);
+    expect(box.h).toBeLessThan(44);
+  });
+
   // #582: the WCAG floor must NOT track the configurable --sf-size-* scale.
   // Shrinking a size rung must not drag the touch target below spec.
   test('--sf-touch-target is independent of the --sf-size-* scale', async ({ page }) => {