fix: restore named-surface colour fallbacks and harden catalog/test checks

Address three issues flagged in the PR #386 automated review:

- core/macros.css: add `color: var(--sf-color-text--on-*)` back to each named
  surface variant. Chrome 125–137 / Firefox 128–130 support oklch(from) but not
  sign(), so the @supports cascade block is skipped; without an explicit color
  declaration those browsers inherit page-body text onto coloured backgrounds.
  Restores accessible foreground for the intermediate browser tier while the
  auto-contrast cascade still takes over in fully modern engines.

- scripts/check-macro-catalog.js: track wildcard patterns that expand to zero
  CSS classes and report them as errors. Previously a stale wildcard (e.g.
  .sf-entrance--* after a rename) would pass the drift-check silently.

- tests/auto-color.spec.js: add .sf-link--reverse to the dark-theme underline
  test anchor and assert textDecorationLine === 'underline' before checking the
  decoration colour. Prevents the assertion from passing vacuously when no
  underline is rendered.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TJ5PentbTtNx4serLVMZcb

Author: claude

core/macros.css

@@ -252,20 +252,23 @@
 
   /* Named variants are thin aliases — they set --sf-surface-color (for the
      auto-contrast formula) and background directly (so they work standalone
-     without also adding .sf-surface). Old engines (Chrome <119 / Safari <16.4)
-     get the background only, with inherited text colour. The --sf-color-text--on-*
-     tokens remain as standalone public tokens for custom components. */
-  .sf-surface--primary   { --sf-surface-color: var(--sf-color-primary);   background: var(--sf-color-primary); }
-  .sf-surface--secondary { --sf-surface-color: var(--sf-color-secondary); background: var(--sf-color-secondary); }
-  .sf-surface--tertiary  { --sf-surface-color: var(--sf-color-tertiary);  background: var(--sf-color-tertiary); }
-  .sf-surface--action    { --sf-surface-color: var(--sf-color-action);    background: var(--sf-color-action); }
-  .sf-surface--neutral   { --sf-surface-color: var(--sf-color-neutral);   background: var(--sf-color-neutral); }
-  .sf-surface--inverse   { --sf-surface-color: var(--sf-color-inverse);   background: var(--sf-color-inverse); }
-  .sf-surface--success   { --sf-surface-color: var(--sf-color-success);   background: var(--sf-color-success); }
-  .sf-surface--warning   { --sf-surface-color: var(--sf-color-warning);   background: var(--sf-color-warning); }
-  .sf-surface--error     { --sf-surface-color: var(--sf-color-error);     background: var(--sf-color-error); }
-  .sf-surface--info      { --sf-surface-color: var(--sf-color-info);      background: var(--sf-color-info); }
-  .sf-surface--danger    { --sf-surface-color: var(--sf-color-danger);    background: var(--sf-color-danger); }
+     without also adding .sf-surface). color: var(--sf-color-text--on-*) is the
+     fallback for Chrome 125–137 / Firefox 128–130, which have oklch(from) but
+     not sign(): in those browsers the @supports block below is skipped, so
+     without an explicit color declaration the element would inherit the page
+     body text on a coloured background. Old engines (Chrome <119, Safari <16.4)
+     get background + colour only; no contextual cascade. */
+  .sf-surface--primary   { --sf-surface-color: var(--sf-color-primary);   background: var(--sf-color-primary);   color: var(--sf-color-text--on-primary); }
+  .sf-surface--secondary { --sf-surface-color: var(--sf-color-secondary); background: var(--sf-color-secondary); color: var(--sf-color-text--on-secondary); }
+  .sf-surface--tertiary  { --sf-surface-color: var(--sf-color-tertiary);  background: var(--sf-color-tertiary);  color: var(--sf-color-text--on-tertiary); }
+  .sf-surface--action    { --sf-surface-color: var(--sf-color-action);    background: var(--sf-color-action);    color: var(--sf-color-text--on-action); }
+  .sf-surface--neutral   { --sf-surface-color: var(--sf-color-neutral);   background: var(--sf-color-neutral);   color: var(--sf-color-text--on-neutral); }
+  .sf-surface--inverse   { --sf-surface-color: var(--sf-color-inverse);   background: var(--sf-color-inverse);   color: var(--sf-color-text--on-inverse); }
+  .sf-surface--success   { --sf-surface-color: var(--sf-color-success);   background: var(--sf-color-success);   color: var(--sf-color-text--on-success); }
+  .sf-surface--warning   { --sf-surface-color: var(--sf-color-warning);   background: var(--sf-color-warning);   color: var(--sf-color-text--on-warning); }
+  .sf-surface--error     { --sf-surface-color: var(--sf-color-error);     background: var(--sf-color-error);     color: var(--sf-color-text--on-error); }
+  .sf-surface--info      { --sf-surface-color: var(--sf-color-info);      background: var(--sf-color-info);      color: var(--sf-color-text--on-info); }
+  .sf-surface--danger    { --sf-surface-color: var(--sf-color-danger);    background: var(--sf-color-danger);    color: var(--sf-color-text--on-danger); }
 
   /* sign() gate: the auto-contrast formula requires both oklch(from) AND sign().
      Named variants set --sf-surface-color so the generic .sf-surface formula

dist/badge-optimal.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "label": "optimal",
-  "message": "17.9 kB gzip",
+  "message": "18.0 kB gzip",
   "color": "brightgreen",
   "namedLogo": "css3"
 }

scripts/check-macro-catalog.js

@@ -74,16 +74,19 @@ if (!fs.existsSync(docsPath)) {
 const docsText = fs.readFileSync(docsPath, 'utf8');
 
 const docsClasses = new Set();
+const unmatchedWildcards = [];
 
 // Single pass: match every `.sf-...` token and check if a `*` follows it.
 const SF_CLASS_RE = /\.(sf-[\w-]+)(\*)?/g;
 for (const [, name, glob] of docsText.matchAll(SF_CLASS_RE)) {
   if (glob) {
     // Wildcard: `.sf-entrance--*` — expand against CSS classes
     const prefix = `.${name}`;
+    let matched = false;
     for (const cls of cssClasses) {
-      if (cls.startsWith(prefix)) docsClasses.add(cls);
+      if (cls.startsWith(prefix)) { docsClasses.add(cls); matched = true; }
     }
+    if (!matched) unmatchedWildcards.push(`${prefix}*`);
   } else {
     docsClasses.add(`.${name}`);
   }
@@ -98,6 +101,12 @@ const inDocsOnly = [...docsClasses].filter(c => !cssClasses.has(c)).sort();
 
 let ok = true;
 
+if (unmatchedWildcards.length > 0) {
+  ok = false;
+  console.error('[check:macros] Wildcards in docs/macros.md with no matching source classes:');
+  for (const w of unmatchedWildcards) console.error(`  ${w}`);
+}
+
 if (inCssOnly.length > 0) {
   ok = false;
   console.error('[check:macros] In CSS but NOT documented in docs/macros.md:');

tests/auto-color.spec.js

@@ -290,20 +290,23 @@ test.describe('Auto-colour — links and underlines', () => {
   });
 
   // Dark theme — link underline token is defined and resolves to a non-transparent colour.
+  // Uses .sf-link--reverse which renders an underline at rest, so the colour assertion
+  // only fires when an underline is actually present.
   test('dark theme: link underline token is non-transparent', async ({ page }) => {
     await page.evaluate(() => document.documentElement.setAttribute('data-theme', 'dark'));
     const info = await page.evaluate(() => {
       const a = document.createElement('a');
-      a.href = '#'; a.textContent = 'link';
+      a.href = '#'; a.className = 'sf-link--reverse'; a.textContent = 'link';
       document.body.appendChild(a);
       const cs = getComputedStyle(a);
       const tokenRaw = getComputedStyle(document.documentElement)
         .getPropertyValue('--sf-color-link--underline').trim();
-      const out = { decoColor: cs.textDecorationColor, hasToken: tokenRaw.length > 0 };
+      const out = { line: cs.textDecorationLine, decoColor: cs.textDecorationColor, hasToken: tokenRaw.length > 0 };
       a.remove();
       return out;
     });
     expect(info.hasToken).toBe(true);
+    expect(info.line).toBe('underline');
     expect(info.decoColor).not.toBe('rgba(0, 0, 0, 0)');
   });