fix PR 392 review: restore non-obvious WHY comments, revert badge sizes, fix indentation

- Revert badge-essential and badge-optimal sizes to pre-PR values (56.2/64.1 kB);
  changes were made without running npm run build so the computed values were wrong
- Restore truncated .sr-only atomic contract note in accessibility.css
- Add .sf-focus-shadow !important rationale and forced-colors WCAG 2.4.7 note
- Restore a:link WebKit UA specificity trap comment in base.css
- Add .sf-not-prose specificity exception note in macros.css
- Fix 4-space → 2-space indentation for standalone class rules in macros.css and layout.css
- Add .sf-cq, .sf-imposter RTL, and @container var() notes in layout.css
- Add .is-disabled cursor inheritance note in states.css
- Add autofill WebKit dark-mode note and chevron FieldText note in forms.css
- Add LumLocker and section-theming light-dark() notes in themes.css
- Add animation-duration unconditional note in motion.css

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

Author: claude

core/accessibility.css

@@ -15,12 +15,15 @@
     outline-offset: var(--sf-focus-ring-offset) !important;
   }
 
-  /* Focus-shadow opt-in */
+  /* .sf-focus-shadow: replaces outline ring with box-shadow ring; !important required
+     to take over the hardened :focus-visible outline (WCAG 2.4.7 still met). */
   .sf-focus-shadow:focus-visible {
     outline:    none                         !important;
     box-shadow: var(--sf-focus-ring-shadow)  !important;
   }
 
+  /* forced-colors: box-shadow vanishes — restore outline ring for WCAG 2.4.7
+     in Windows High Contrast. */
   @media (forced-colors: active) {
     .sf-focus-shadow:focus-visible {
       outline:        var(--sf-focus-ring-width) solid !important;
@@ -113,7 +116,8 @@
     opacity: var(--sf-opacity-disabled);
   }
 
-  /* Screen-reader-only. Atomic contract: a partial override */
+  /* Screen-reader-only. Atomic contract: partial override either exposes hidden content
+     or hides intended content — all-or-nothing, whole set hardened. */
   .sr-only,
   .sr-only-focusable:not(:focus, :focus-within) {
     position:    absolute            !important;

core/base.css

@@ -80,6 +80,8 @@
   sup { top:    -0.5em; }
   sub { bottom: -0.25em; }
 
+  /* :link (0,1,1) not bare a: beats WebKit UA rule a:link { color: -webkit-link }
+     that silently overrides --sf-color-link in dark mode. */
   a:link {
     color:                   var(--sf-color-link);
     text-decoration-color:   var(--sf-color-link--underline);

core/layout.css

@@ -27,7 +27,7 @@
     padding-block-start: calc(var(--sf-section-pad) / 2);
   }
 
-    .sf-divider {
+  .sf-divider {
     border:             none;
     border-block-start: var(--sf-divider-width) var(--sf-divider-style) var(--sf-divider-color);
     margin-block:       var(--sf-divider-gap);
@@ -64,7 +64,9 @@
   .sf-container--wide   { max-width: var(--sf-container-wide); }
   .sf-container--full   { max-width: var(--sf-container-full); }
 
-    .sf-cq {
+  /* .sf-cq: CQ scope without .sf-container's max-width/centering.
+     Use when a CQ-dependent primitive needs a container ancestor but no layout chrome. */
+  .sf-cq {
     container-type: inline-size;
   }
 
@@ -85,7 +87,7 @@
   .sf-stack--end     { align-items: flex-end; }
   .sf-stack--stretch { align-items: stretch; }
 
-    .sf-gap { gap: var(--sf-gap); }
+  .sf-gap { gap: var(--sf-gap); }
   .sf-gap--xs  { gap: var(--sf-space-xs); }
   .sf-gap--s   { gap: var(--sf-space-s); }
   .sf-gap--m   { gap: var(--sf-space-m); }
@@ -201,7 +203,7 @@
 
   .sf-grid--dense { grid-auto-flow: dense; }
 
-    .sf-icon {
+  .sf-icon {
     display:        inline-block;
     inline-size:    var(--sf-icon-size, var(--sf-icon-m));
     block-size:     var(--sf-icon-size, var(--sf-icon-m));
@@ -292,6 +294,8 @@
   }
 
 
+  /* Physical left (not inset-inline-start): translate() uses the physical axis,
+     so logical + translate breaks centering in RTL layouts. */
   .sf-imposter {
     position:          absolute;
     inset-block-start: 50%;
@@ -350,6 +354,7 @@
     container: sf-grid / inline-size;
   }
 
+  /* Cannot use var() inside @container per CSS spec — breakpoints hardcoded. */
   @container (min-width: 30em) {
     .sf-grid-cols-4 { grid-template-columns: repeat(2, 1fr); }
     .sf-grid-cols-6 { grid-template-columns: repeat(3, 1fr); }
@@ -376,7 +381,7 @@
     .sf-grid-cols-3-1 { grid-template-columns: 3fr 1fr; }
   }
 
-    .sf-equal {
+  .sf-equal {
     display:               grid;
     grid-template-columns: repeat(auto-fit, minmax(min(var(--sf-equal-min-col), 100%), 1fr));
     gap:                   var(--sf-equal-gap);

core/macros.css

@@ -30,6 +30,8 @@
   .sf-prose :is(th, td)          { padding: var(--sf-prose-table-pad); }
   .sf-prose video                { margin-block: var(--sf-prose-media-margin); border-radius: var(--sf-prose-media-radius); }
 
+  /* Specificity 0-2-1 intentionally beats .sf-prose's 0-2-0 child selectors —
+     documented exception. */
   .sf-prose .sf-not-prose > * + *    { margin-block-start: 0; }
   .sf-prose .sf-not-prose li + li    { margin-block-start: 0; }
 
@@ -49,11 +51,11 @@
   .sf-prose .sf-not-prose :is(th,td) { padding: revert; }
   .sf-prose .sf-not-prose video      { margin-block: 0; border-radius: 0; }
 
-    .sf-flow > * + * {
+  .sf-flow > * + * {
     margin-block-start: var(--sf-flow-space);
   }
 
-    .sf-truncate {
+  .sf-truncate {
     overflow:      hidden;
     text-overflow: ellipsis;
     white-space:   nowrap;
@@ -77,7 +79,7 @@
     -webkit-line-clamp: var(--sf-line-clamp);
   }
 
-    .sf-equal-height {
+  .sf-equal-height {
     display:     flex;
     align-items: stretch;
   }
@@ -86,11 +88,11 @@
     flex:       1 1 auto;
   }
 
-    .sf-aspect {
+  .sf-aspect {
     aspect-ratio: var(--sf-aspect, 16 / 9);
   }
 
-    .sf-scroll-shadow {
+  .sf-scroll-shadow {
     overflow-y:     auto;
     overflow-block: auto;
     /* stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 15.4 */
@@ -108,7 +110,7 @@
         transparent 100%);
   }
 
-    .sf-scroll-snap {
+  .sf-scroll-snap {
     overflow-y:                auto;
     overflow-block:            auto;
     scroll-snap-type:          block mandatory;
@@ -118,7 +120,7 @@
     scroll-snap-align: start;
   }
 
-    .sf-overflow-fade {
+  .sf-overflow-fade {
     overflow: hidden;
     /* stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 15.4 */
     -webkit-mask-image: linear-gradient(
@@ -135,12 +137,12 @@
     );
   }
 
-    .sf-no-tap-highlight {
+  .sf-no-tap-highlight {
     /* stylelint-disable-next-line property-no-vendor-prefix -- no unprefixed equivalent */
     -webkit-tap-highlight-color: transparent;
   }
 
-    .sf-surface { background: var(--sf-surface-color); }
+  .sf-surface { background: var(--sf-surface-color); }
 
   .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); }
@@ -180,7 +182,7 @@
       --sf-shadow-color:            oklch(from var(--sf-surface-color) var(--sf-shadow-lightness) c h);
     }
   }
-    .sf-scrim {
+  .sf-scrim {
     position:  relative;
     isolation: isolate;
   }
@@ -202,33 +204,33 @@
   .sf-scrim--bottom { --sf-scrim-direction: to top; }
   .sf-scrim--full   { --sf-scrim-gradient: var(--sf-scrim-color); }
 
-    .sf-text-protect {
+  .sf-text-protect {
     text-shadow: var(--sf-scrim-text-shadow);
   }
 
-    .sf-text-gradient {
+  .sf-text-gradient {
     background-image: var(--sf-gradient-primary);
     background-clip: text;
     color: transparent;
   }
 
-    .sf-link-external::after {
+  .sf-link-external::after {
     content:         var(--sf-link-external-marker);
     display:         inline-block;
     font-size:       0.85em;
     text-decoration: none;
   }
 
-    .sf-content-auto {
+  .sf-content-auto {
     content-visibility:     auto;
     contain-intrinsic-size: auto var(--sf-content-intrinsic-size, 500px);
   }
 
-    .sf-tabular-nums {
+  .sf-tabular-nums {
     font-variant-numeric: var(--sf-font-numeric, tabular-nums);
   }
 
-    .sf-link--subtle:link,
+  .sf-link--subtle:link,
   .sf-link--subtle:visited {
     text-decoration-line: none;
   }

core/motion.css

@@ -39,6 +39,8 @@
     .sf-scale-down     { animation: var(--sf-animation-scale-down); }
 
 
+    /* animation-duration set unconditionally: without it, engines without
+       animation-timeline snap to end state at 0s. */
     .sf-entrance--fade,
     .sf-entrance--fade-up,
     .sf-entrance--fade-down,

core/states.css

@@ -21,6 +21,8 @@
 
   /* INTERACTIVITY */
 
+  /* cursor: not-allowed inherits to children with pointer-events: auto —
+     intentional, part of the .is-disabled API surface. */
   .is-disabled {
     opacity:        var(--sf-opacity-disabled);
     pointer-events: none;

core/themes.css

@@ -20,7 +20,8 @@
     color:            var(--sf-color-text);
   }
 
-  /* LumLocker */
+  /* LumLocker: locks 4 brand colors to shared OKLCH L. Neutral/base excluded —
+     forcing them to the same L breaks their semantic role. */
   @supports (color: oklch(from red l c h)) {
   :root[data-lumlocker] {
     --sf-color-primary: light-dark(
@@ -56,7 +57,8 @@
   }
 
   /* SECTION-LEVEL THEMING */
-
+  /* light-dark() bakes at :root declaration time; re-declarations on [data-theme]
+     elements are required for section-level theming to work. */
   @supports (color: oklch(from red l c h)) {
 
         :root {

dist/badge-essential.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "label": "essential",
-  "message": "15.6 kB gzip",
+  "message": "56.2 kB gzip",
   "color": "brightgreen",
   "namedLogo": "css3"
 }

dist/badge-optimal.json

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

optional/forms.css

@@ -62,7 +62,8 @@
     opacity: 1;
   }
 
-  /* Autofill */
+  /* Autofill: strips Safari's own dark-mode autofill background; Chromium/Firefox honour
+     the CSS background without this, but WebKit doesn't. */
   /* stylelint-disable selector-pseudo-class-no-unknown */
   input:-webkit-autofill {
     box-shadow: inset 0 0 0 1000px var(--sf-color-surface);
@@ -108,7 +109,8 @@
     }
   }
 
-  /* Select */
+  /* Select: chevron uses FieldText system color — custom properties don't propagate
+     into data-URI SVG backgrounds. */
   select {
     padding-inline-end: calc(var(--sf-space-s) + 1.5em);
   }