diff --git a/configurator/src/data/api-index.generated.json b/configurator/src/data/api-index.generated.json
index f4d1b05a..ef702be2 100644
--- a/configurator/src/data/api-index.generated.json
+++ b/configurator/src/data/api-index.generated.json
@@ -2,7 +2,7 @@
   "_sync": {
     "generatedBy": "configurator/scripts/sync-api.mjs",
     "source": "docs/api-index.json",
-    "tokensHash": "edc94fa13e23",
+    "tokensHash": "46e82162ef0c",
     "bundles": [
       "full",
       "optimal"
@@ -451,7 +451,7 @@
       "category": "Core tokens",
       "group": "Animation presets",
       "description": "Complete animation shorthand values — pair named @keyframes with duration and easing. Use directly as animation property values.",
-      "note": "",
+      "note": "Ready-made animation shorthand: slides the element out downward (sf-slide-out-down) at the normal duration with ease-in.",
       "value": "sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -472,7 +472,7 @@
       "category": "Core tokens",
       "group": "Animation presets",
       "description": "Complete animation shorthand values — pair named @keyframes with duration and easing. Use directly as animation property values.",
-      "note": "",
+      "note": "Ready-made animation shorthand: slides the element out to the left (sf-slide-out-left) at the normal duration with ease-in.",
       "value": "sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -493,7 +493,7 @@
       "category": "Core tokens",
       "group": "Animation presets",
       "description": "Complete animation shorthand values — pair named @keyframes with duration and easing. Use directly as animation property values.",
-      "note": "",
+      "note": "Ready-made animation shorthand: slides the element out to the right (sf-slide-out-right) at the normal duration with ease-in.",
       "value": "sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -514,7 +514,7 @@
       "category": "Core tokens",
       "group": "Animation presets",
       "description": "Complete animation shorthand values — pair named @keyframes with duration and easing. Use directly as animation property values.",
-      "note": "",
+      "note": "Ready-made animation shorthand: slides the element out upward (sf-slide-out-up) at the normal duration with ease-in.",
       "value": "sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -3956,7 +3956,7 @@
       "category": "Core tokens",
       "group": "neutral",
       "description": "Semantic neutral-color scale derived from --sf-color-neutral. Useful for muted UI chrome.",
-      "note": "Light neutral shade.",
+      "note": "Light neutral shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -4124,7 +4124,7 @@
       "category": "Core tokens",
       "group": "neutral",
       "description": "Semantic neutral-color scale derived from --sf-color-neutral. Useful for muted UI chrome.",
-      "note": "Near-black neutral shade.",
+      "note": "Near-black neutral shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -4292,7 +4292,7 @@
       "category": "Core tokens",
       "group": "neutral",
       "description": "Semantic neutral-color scale derived from --sf-color-neutral. Useful for muted UI chrome.",
-      "note": "Light neutral shade.",
+      "note": "Light neutral shade for soft accents — alias of --sf-color-neutral-400.",
       "value": "var(--sf-color-neutral-400)",
       "aliasOf": "--sf-color-neutral-400",
       "registered": false,
@@ -4397,7 +4397,7 @@
       "category": "Core tokens",
       "group": "neutral",
       "description": "Semantic neutral-color scale derived from --sf-color-neutral. Useful for muted UI chrome.",
-      "note": "Near-black neutral shade.",
+      "note": "Near-black neutral shade for maximum contrast on light surfaces — alias of --sf-color-neutral-950.",
       "value": "var(--sf-color-neutral-950)",
       "aliasOf": "--sf-color-neutral-950",
       "registered": false,
@@ -4607,7 +4607,7 @@
       "category": "Core tokens",
       "group": "primary",
       "description": "Semantic primary-color scale derived from --sf-color-primary. Covers fills, hover/active states, and tint variants for the primary palette role.",
-      "note": "Light primary shade.",
+      "note": "Light primary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -4775,7 +4775,7 @@
       "category": "Core tokens",
       "group": "primary",
       "description": "Semantic primary-color scale derived from --sf-color-primary. Covers fills, hover/active states, and tint variants for the primary palette role.",
-      "note": "Near-black primary shade.",
+      "note": "Near-black primary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -4943,7 +4943,7 @@
       "category": "Core tokens",
       "group": "primary",
       "description": "Semantic primary-color scale derived from --sf-color-primary. Covers fills, hover/active states, and tint variants for the primary palette role.",
-      "note": "Light primary shade.",
+      "note": "Light primary shade for soft accents — alias of --sf-color-primary-400.",
       "value": "var(--sf-color-primary-400)",
       "aliasOf": "--sf-color-primary-400",
       "registered": false,
@@ -5048,7 +5048,7 @@
       "category": "Core tokens",
       "group": "primary",
       "description": "Semantic primary-color scale derived from --sf-color-primary. Covers fills, hover/active states, and tint variants for the primary palette role.",
-      "note": "Near-black primary shade.",
+      "note": "Near-black primary shade for maximum contrast on light surfaces — alias of --sf-color-primary-950.",
       "value": "var(--sf-color-primary-950)",
       "aliasOf": "--sf-color-primary-950",
       "registered": false,
@@ -5279,7 +5279,7 @@
       "category": "Core tokens",
       "group": "secondary",
       "description": "Semantic secondary-color scale derived from --sf-color-secondary.",
-      "note": "Light secondary shade.",
+      "note": "Light secondary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -5447,7 +5447,7 @@
       "category": "Core tokens",
       "group": "secondary",
       "description": "Semantic secondary-color scale derived from --sf-color-secondary.",
-      "note": "Near-black secondary shade.",
+      "note": "Near-black secondary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -5615,7 +5615,7 @@
       "category": "Core tokens",
       "group": "secondary",
       "description": "Semantic secondary-color scale derived from --sf-color-secondary.",
-      "note": "Light secondary shade.",
+      "note": "Light secondary shade for soft accents — alias of --sf-color-secondary-400.",
       "value": "var(--sf-color-secondary-400)",
       "aliasOf": "--sf-color-secondary-400",
       "registered": false,
@@ -5720,7 +5720,7 @@
       "category": "Core tokens",
       "group": "secondary",
       "description": "Semantic secondary-color scale derived from --sf-color-secondary.",
-      "note": "Near-black secondary shade.",
+      "note": "Near-black secondary shade for maximum contrast on light surfaces — alias of --sf-color-secondary-950.",
       "value": "var(--sf-color-secondary-950)",
       "aliasOf": "--sf-color-secondary-950",
       "registered": false,
@@ -5846,7 +5846,7 @@
       "category": "Core tokens",
       "group": "Selection",
       "description": "Text-selection background color.",
-      "note": "",
+      "note": "Alt selection background — the inverse-scheme highlight fill for surfaces that deliberately flip colour scheme (e.g. a dark hero in light mode).",
       "value": "light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )",
       "aliasOf": null,
       "registered": false,
@@ -5888,7 +5888,7 @@
       "category": "Core tokens",
       "group": "Selection",
       "description": "Text-selection background color.",
-      "note": "",
+      "note": "Alt selection text colour paired with --sf-color-selection-bg--alt; inherits by default so the underlying text colour shows through.",
       "value": "inherit",
       "aliasOf": null,
       "registered": false,
@@ -6161,7 +6161,7 @@
       "category": "Core tokens",
       "group": "tertiary",
       "description": "Semantic tertiary-color scale derived from --sf-color-tertiary.",
-      "note": "Light tertiary shade.",
+      "note": "Light tertiary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -6329,7 +6329,7 @@
       "category": "Core tokens",
       "group": "tertiary",
       "description": "Semantic tertiary-color scale derived from --sf-color-tertiary.",
-      "note": "Near-black tertiary shade.",
+      "note": "Near-black tertiary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -6497,7 +6497,7 @@
       "category": "Core tokens",
       "group": "tertiary",
       "description": "Semantic tertiary-color scale derived from --sf-color-tertiary.",
-      "note": "Light tertiary shade.",
+      "note": "Light tertiary shade for soft accents — alias of --sf-color-tertiary-400.",
       "value": "var(--sf-color-tertiary-400)",
       "aliasOf": "--sf-color-tertiary-400",
       "registered": false,
@@ -6602,7 +6602,7 @@
       "category": "Core tokens",
       "group": "tertiary",
       "description": "Semantic tertiary-color scale derived from --sf-color-tertiary.",
-      "note": "Near-black tertiary shade.",
+      "note": "Near-black tertiary shade for maximum contrast on light surfaces — alias of --sf-color-tertiary-950.",
       "value": "var(--sf-color-tertiary-950)",
       "aliasOf": "--sf-color-tertiary-950",
       "registered": false,
@@ -7462,8 +7462,8 @@
       "namespace": "corner",
       "category": "Macro tokens",
       "group": "Concave corner",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).",
-      "note": "",
+      "description": "Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0.",
+      "note": "Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0.",
       "value": "100% 0",
       "aliasOf": null,
       "registered": false,
@@ -7483,8 +7483,8 @@
       "namespace": "corner",
       "category": "Macro tokens",
       "group": "Concave corner",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).",
-      "note": "",
+      "description": "Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl).",
+      "note": "Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl).",
       "value": "var(--sf-radius-2xl)",
       "aliasOf": "--sf-radius-2xl",
       "registered": false,
@@ -12185,7 +12185,7 @@
       "category": "Core tokens",
       "group": "Scroll-driven animation range",
       "description": "animation-range start and end positions for scroll-driven entrance effects (animation-timeline: view()). Controls how far into the viewport an element must scroll before its entrance animation starts and ends.",
-      "note": "",
+      "note": "Scroll-timeline range at which a scroll-out exit animation finishes. Default: exit 100%.",
       "value": "exit 100%",
       "aliasOf": null,
       "registered": false,
@@ -12206,7 +12206,7 @@
       "category": "Core tokens",
       "group": "Scroll-driven animation range",
       "description": "animation-range start and end positions for scroll-driven entrance effects (animation-timeline: view()). Controls how far into the viewport an element must scroll before its entrance animation starts and ends.",
-      "note": "",
+      "note": "Scroll-timeline range at which a scroll-out exit animation begins. Default: cover 70%.",
       "value": "cover 70%",
       "aliasOf": null,
       "registered": false,
@@ -13339,8 +13339,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none.",
+      "note": "animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -13360,8 +13360,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll.",
+      "note": "background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll.",
       "value": "scroll",
       "aliasOf": null,
       "registered": false,
@@ -13381,8 +13381,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "Background colour slot for the .sf-surface-bg macro. Default: transparent.",
+      "note": "Background colour slot for the .sf-surface-bg macro. Default: transparent.",
       "value": "transparent",
       "aliasOf": null,
       "registered": false,
@@ -13402,8 +13402,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none.",
+      "note": "Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -13423,8 +13423,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none.",
+      "note": "Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -13444,8 +13444,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "background-position for the .sf-surface-bg image. Default: center.",
+      "note": "background-position for the .sf-surface-bg image. Default: center.",
       "value": "center",
       "aliasOf": null,
       "registered": false,
@@ -13465,8 +13465,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "background-repeat for the .sf-surface-bg image. Default: no-repeat.",
+      "note": "background-repeat for the .sf-surface-bg image. Default: no-repeat.",
       "value": "no-repeat",
       "aliasOf": null,
       "registered": false,
@@ -13486,8 +13486,8 @@
       "namespace": "surface",
       "category": "Macro tokens",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
-      "note": "",
+      "description": "background-size for the .sf-surface-bg image. Default: cover.",
+      "note": "background-size for the .sf-surface-bg image. Default: cover.",
       "value": "cover",
       "aliasOf": null,
       "registered": false,
diff --git a/configurator/src/data/classes.generated.json b/configurator/src/data/classes.generated.json
index 0b2dc372..0229ccb8 100644
--- a/configurator/src/data/classes.generated.json
+++ b/configurator/src/data/classes.generated.json
@@ -740,7 +740,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Concave \"scooped\" corner cut with a radial-gradient mask; defaults to the top-right corner (--sf-corner-scoop-at). Add a placement modifier to move it.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -750,7 +750,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the bottom-left corner.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -760,7 +760,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the bottom-right corner.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -770,7 +770,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the top-left corner.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -780,7 +780,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the top-right corner.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -860,7 +860,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "Divide",
-      "description": "Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap.",
+      "description": "Rules between direct children (a border on each child after the first), reusing .sf-divider's tokens — no per-gap markup needed.",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -870,7 +870,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "Divide",
-      "description": "Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap.",
+      "description": "Vertical rules between direct children (inline-start borders), for row/horizontal layouts.",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -950,7 +950,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-l).",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -960,7 +960,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Medium filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-m).",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -970,7 +970,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-s).",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -980,7 +980,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Extra-large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xl).",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -990,7 +990,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Extra-small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xs).",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -1120,7 +1120,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades the element out in place (sf-fade-out).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1130,7 +1130,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding downward (sf-slide-out-down).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1140,7 +1140,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding to the left (sf-slide-out-left).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1150,7 +1150,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding to the right (sf-slide-out-right).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1160,7 +1160,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding upward (sf-slide-out-up).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1170,7 +1170,7 @@
       "kind": "motion",
       "category": "Motion / animation",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while shrinking (sf-scale-down).",
       "optional": false,
       "layer": "slashed.motion"
     },
@@ -1720,7 +1720,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the l step (--sf-space-l).",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -1730,7 +1730,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the m step (--sf-space-m).",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -1740,7 +1740,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the s step (--sf-space-s).",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -1750,7 +1750,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the xl step (--sf-space-xl).",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -1760,7 +1760,7 @@
       "kind": "layout",
       "category": "Layout primitives",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the xs step (--sf-space-xs).",
       "optional": false,
       "layer": "slashed.layout"
     },
@@ -2290,7 +2290,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the action colour.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2300,7 +2300,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the primary brand colour.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2310,7 +2310,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the secondary brand colour.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2320,7 +2320,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the tertiary brand colour.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2420,7 +2420,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element upward (negative block-start margin) so it overlaps the previous sibling by --sf-overlap-pull.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -2430,7 +2430,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls following content up (negative block-end margin) so this element overlaps the sibling below it.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -2440,7 +2440,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element toward the inline-end (negative inline-end margin) to overlap horizontally.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -2450,7 +2450,7 @@
       "kind": "macro",
       "category": "Macro classes",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element toward the inline-start (negative inline-start margin) to overlap horizontally.",
       "optional": false,
       "layer": "slashed.macros"
     },
@@ -2890,7 +2890,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "position: sticky pinned at the header-aware --sf-sticky-offset.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2900,7 +2900,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra large gap (--sf-space-l) above the header-aware offset.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2910,7 +2910,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra medium gap (--sf-space-m) above the header-aware offset.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -2920,7 +2920,7 @@
       "kind": "utility",
       "category": "Utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra small gap (--sf-space-s) above the header-aware offset.",
       "optional": true,
       "layer": "slashed.utilities"
     },
@@ -3220,7 +3220,7 @@
       "kind": "theme",
       "category": "Theme utilities",
       "group": "",
-      "description": "",
+      "description": "Forces dark colour scheme on the element and its subtree (class alias of [data-theme=\"dark\"]).",
       "optional": false,
       "layer": "slashed.themes"
     },
@@ -3230,7 +3230,7 @@
       "kind": "theme",
       "category": "Theme utilities",
       "group": "",
-      "description": "",
+      "description": "Forces light colour scheme on the element and its subtree (class alias of [data-theme=\"light\"]).",
       "optional": false,
       "layer": "slashed.themes"
     },
diff --git a/demos/full-api-demo-with-overrides.html b/demos/full-api-demo-with-overrides.html
index 251f76ef..0dd6d58f 100644
--- a/demos/full-api-demo-with-overrides.html
+++ b/demos/full-api-demo-with-overrides.html
@@ -122,7 +122,7 @@
   </nav>
   <main id="main">
     <h1>SLASHED Full API Demo</h1>
-    <p style="color:var(--sf-color-text--muted)">v0.7.8 · full bundle from jsDelivr CDN · 328 classes · 735 tokens (244 configurable)</p>
+    <p style="color:var(--sf-color-text--muted)">v0.7.9 · full bundle from jsDelivr CDN · 328 classes · 735 tokens (244 configurable)</p>
     <div class="notice"><strong>ultimate-override.css is ACTIVE.</strong> Every value below is recomputed from perturbed knob tokens — toggle it off in the toolbar, or compare against <a href="full-api-demo.html">the un-overridden page</a>.</div>
 
     <section id="tokens">
diff --git a/demos/full-api-demo.html b/demos/full-api-demo.html
index ce0cafdc..5a8bda82 100644
--- a/demos/full-api-demo.html
+++ b/demos/full-api-demo.html
@@ -121,7 +121,7 @@
   </nav>
   <main id="main">
     <h1>SLASHED Full API Demo</h1>
-    <p style="color:var(--sf-color-text--muted)">v0.7.8 · full bundle from jsDelivr CDN · 328 classes · 735 tokens (244 configurable)</p>
+    <p style="color:var(--sf-color-text--muted)">v0.7.9 · full bundle from jsDelivr CDN · 328 classes · 735 tokens (244 configurable)</p>
     <div class="notice">Baseline render with default tokens. Use the toolbar to switch theme, toggle the ultimate override live, or replay motion. The always-on override variant is <a href="full-api-demo-with-overrides.html">full-api-demo-with-overrides.html</a>.</div>
 
     <section id="tokens">
diff --git a/demos/ultimate-override.css b/demos/ultimate-override.css
index 57c07a49..20cef66e 100644
--- a/demos/ultimate-override.css
+++ b/demos/ultimate-override.css
@@ -1,6 +1,6 @@
 /* ============================================================================
    ULTIMATE OVERRIDE — generated by demos/generate.mjs (do not edit by hand)
-   SLASHED v0.7.8
+   SLASHED v0.7.9
 
    Perturbs every CONFIGURABLE (role: "knob") token to a valid, visibly-distinct
    value so full-api-demo.html can prove each one is wired end to end.
diff --git a/dist/css-custom-data.json b/dist/css-custom-data.json
index 64bfbc6c..fd1ef017 100644
--- a/dist/css-custom-data.json
+++ b/dist/css-custom-data.json
@@ -103,22 +103,22 @@
     },
     {
       "name": "--sf-animation-slide-out-down",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);\n\nDefault: `sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both`",
+      "description": "Ready-made animation shorthand: slides the element out downward (sf-slide-out-down) at the normal duration with ease-in.\n\nDefault: `sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both`",
       "syntax": "*"
     },
     {
       "name": "--sf-animation-slide-out-left",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);\n\nDefault: `sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both`",
+      "description": "Ready-made animation shorthand: slides the element out to the left (sf-slide-out-left) at the normal duration with ease-in.\n\nDefault: `sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both`",
       "syntax": "*"
     },
     {
       "name": "--sf-animation-slide-out-right",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);\n\nDefault: `sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both`",
+      "description": "Ready-made animation shorthand: slides the element out to the right (sf-slide-out-right) at the normal duration with ease-in.\n\nDefault: `sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both`",
       "syntax": "*"
     },
     {
       "name": "--sf-animation-slide-out-up",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);\n\nDefault: `sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both`",
+      "description": "Ready-made animation shorthand: slides the element out upward (sf-slide-out-up) at the normal duration with ease-in.\n\nDefault: `sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both`",
       "syntax": "*"
     },
     {
@@ -943,7 +943,7 @@
     },
     {
       "name": "--sf-color-neutral-200",
-      "description": "Light neutral shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))`",
+      "description": "Light neutral shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.\n\nDefault: `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))`",
       "syntax": "*"
     },
     {
@@ -983,7 +983,7 @@
     },
     {
       "name": "--sf-color-neutral-900",
-      "description": "Near-black neutral shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))`",
+      "description": "Near-black neutral shade at step 900 on the numeric scale. Extreme contrast on light surfaces.\n\nDefault: `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))`",
       "syntax": "*"
     },
     {
@@ -1023,7 +1023,7 @@
     },
     {
       "name": "--sf-color-neutral-lighter",
-      "description": "Light neutral shade.\n\nDefault: `var(--sf-color-neutral-400)`",
+      "description": "Light neutral shade for soft accents — alias of --sf-color-neutral-400.\n\nDefault: `var(--sf-color-neutral-400)`",
       "syntax": "*"
     },
     {
@@ -1048,7 +1048,7 @@
     },
     {
       "name": "--sf-color-neutral-superdark",
-      "description": "Near-black neutral shade.\n\nDefault: `var(--sf-color-neutral-950)`",
+      "description": "Near-black neutral shade for maximum contrast on light surfaces — alias of --sf-color-neutral-950.\n\nDefault: `var(--sf-color-neutral-950)`",
       "syntax": "*"
     },
     {
@@ -1098,7 +1098,7 @@
     },
     {
       "name": "--sf-color-primary-200",
-      "description": "Light primary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
+      "description": "Light primary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.\n\nDefault: `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
       "syntax": "*"
     },
     {
@@ -1138,7 +1138,7 @@
     },
     {
       "name": "--sf-color-primary-900",
-      "description": "Near-black primary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))`",
+      "description": "Near-black primary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.\n\nDefault: `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))`",
       "syntax": "*"
     },
     {
@@ -1178,7 +1178,7 @@
     },
     {
       "name": "--sf-color-primary-lighter",
-      "description": "Light primary shade.\n\nDefault: `var(--sf-color-primary-400)`",
+      "description": "Light primary shade for soft accents — alias of --sf-color-primary-400.\n\nDefault: `var(--sf-color-primary-400)`",
       "syntax": "*"
     },
     {
@@ -1203,7 +1203,7 @@
     },
     {
       "name": "--sf-color-primary-superdark",
-      "description": "Near-black primary shade.\n\nDefault: `var(--sf-color-primary-950)`",
+      "description": "Near-black primary shade for maximum contrast on light surfaces — alias of --sf-color-primary-950.\n\nDefault: `var(--sf-color-primary-950)`",
       "syntax": "*"
     },
     {
@@ -1258,7 +1258,7 @@
     },
     {
       "name": "--sf-color-secondary-200",
-      "description": "Light secondary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
+      "description": "Light secondary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.\n\nDefault: `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
       "syntax": "*"
     },
     {
@@ -1298,7 +1298,7 @@
     },
     {
       "name": "--sf-color-secondary-900",
-      "description": "Near-black secondary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))`",
+      "description": "Near-black secondary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.\n\nDefault: `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))`",
       "syntax": "*"
     },
     {
@@ -1338,7 +1338,7 @@
     },
     {
       "name": "--sf-color-secondary-lighter",
-      "description": "Light secondary shade.\n\nDefault: `var(--sf-color-secondary-400)`",
+      "description": "Light secondary shade for soft accents — alias of --sf-color-secondary-400.\n\nDefault: `var(--sf-color-secondary-400)`",
       "syntax": "*"
     },
     {
@@ -1363,7 +1363,7 @@
     },
     {
       "name": "--sf-color-secondary-superdark",
-      "description": "Near-black secondary shade.\n\nDefault: `var(--sf-color-secondary-950)`",
+      "description": "Near-black secondary shade for maximum contrast on light surfaces — alias of --sf-color-secondary-950.\n\nDefault: `var(--sf-color-secondary-950)`",
       "syntax": "*"
     },
     {
@@ -1393,7 +1393,7 @@
     },
     {
       "name": "--sf-color-selection-bg--alt",
-      "description": "Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css).\n\nDefault: `light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )`",
+      "description": "Alt selection background — the inverse-scheme highlight fill for surfaces that deliberately flip colour scheme (e.g. a dark hero in light mode).\n\nDefault: `light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )`",
       "syntax": "*"
     },
     {
@@ -1403,7 +1403,7 @@
     },
     {
       "name": "--sf-color-selection-text--alt",
-      "description": "Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css).\n\nDefault: `inherit`",
+      "description": "Alt selection text colour paired with --sf-color-selection-bg--alt; inherits by default so the underlying text colour shows through.\n\nDefault: `inherit`",
       "syntax": "*"
     },
     {
@@ -1468,7 +1468,7 @@
     },
     {
       "name": "--sf-color-tertiary-200",
-      "description": "Light tertiary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
+      "description": "Light tertiary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.\n\nDefault: `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))`",
       "syntax": "*"
     },
     {
@@ -1508,7 +1508,7 @@
     },
     {
       "name": "--sf-color-tertiary-900",
-      "description": "Near-black tertiary shade.\n\nDefault: `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))`",
+      "description": "Near-black tertiary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.\n\nDefault: `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))`",
       "syntax": "*"
     },
     {
@@ -1548,7 +1548,7 @@
     },
     {
       "name": "--sf-color-tertiary-lighter",
-      "description": "Light tertiary shade.\n\nDefault: `var(--sf-color-tertiary-400)`",
+      "description": "Light tertiary shade for soft accents — alias of --sf-color-tertiary-400.\n\nDefault: `var(--sf-color-tertiary-400)`",
       "syntax": "*"
     },
     {
@@ -1573,7 +1573,7 @@
     },
     {
       "name": "--sf-color-tertiary-superdark",
-      "description": "Near-black tertiary shade.\n\nDefault: `var(--sf-color-tertiary-950)`",
+      "description": "Near-black tertiary shade for maximum contrast on light surfaces — alias of --sf-color-tertiary-950.\n\nDefault: `var(--sf-color-tertiary-950)`",
       "syntax": "*"
     },
     {
@@ -1778,12 +1778,12 @@
     },
     {
       "name": "--sf-corner-scoop-at",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).\n\nDefault: `100% 0`",
+      "description": "Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0.\n\nDefault: `100% 0`",
       "syntax": "*"
     },
     {
       "name": "--sf-corner-scoop-size",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).\n\nDefault: `var(--sf-radius-2xl)`",
+      "description": "Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl).\n\nDefault: `var(--sf-radius-2xl)`",
       "syntax": "*"
     },
     {
@@ -2898,12 +2898,12 @@
     },
     {
       "name": "--sf-scroll-timeline-range-exit-end",
-      "description": "Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out.\n\nDefault: `exit 100%`",
+      "description": "Scroll-timeline range at which a scroll-out exit animation finishes. Default: exit 100%.\n\nDefault: `exit 100%`",
       "syntax": "*"
     },
     {
       "name": "--sf-scroll-timeline-range-exit-start",
-      "description": "Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out.\n\nDefault: `cover 70%`",
+      "description": "Scroll-timeline range at which a scroll-out exit animation begins. Default: cover 70%.\n\nDefault: `cover 70%`",
       "syntax": "*"
     },
     {
@@ -3173,42 +3173,42 @@
     },
     {
       "name": "--sf-surface-bg-animation",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `none`",
+      "description": "animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none.\n\nDefault: `none`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-attachment",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `scroll`",
+      "description": "background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll.\n\nDefault: `scroll`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-color",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `transparent`",
+      "description": "Background colour slot for the .sf-surface-bg macro. Default: transparent.\n\nDefault: `transparent`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-image",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `none`",
+      "description": "Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none.\n\nDefault: `none`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-overlay",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `none`",
+      "description": "Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none.\n\nDefault: `none`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-position",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `center`",
+      "description": "background-position for the .sf-surface-bg image. Default: center.\n\nDefault: `center`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-repeat",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `no-repeat`",
+      "description": "background-repeat for the .sf-surface-bg image. Default: no-repeat.\n\nDefault: `no-repeat`",
       "syntax": "*"
     },
     {
       "name": "--sf-surface-bg-size",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…\n\nDefault: `cover`",
+      "description": "background-size for the .sf-surface-bg image. Default: cover.\n\nDefault: `cover`",
       "syntax": "*"
     },
     {
diff --git a/docs/api-index.json b/docs/api-index.json
index 55f1deb0..b9189ca4 100644
--- a/docs/api-index.json
+++ b/docs/api-index.json
@@ -619,7 +619,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Animation presets",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);",
+      "description": "Ready-made animation shorthand: slides the element out downward (sf-slide-out-down) at the normal duration with ease-in.",
       "value": "sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -645,7 +645,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Animation presets",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);",
+      "description": "Ready-made animation shorthand: slides the element out to the left (sf-slide-out-left) at the normal duration with ease-in.",
       "value": "sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -671,7 +671,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Animation presets",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);",
+      "description": "Ready-made animation shorthand: slides the element out to the right (sf-slide-out-right) at the normal duration with ease-in.",
       "value": "sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -697,7 +697,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Animation presets",
-      "description": "pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in);",
+      "description": "Ready-made animation shorthand: slides the element out upward (sf-slide-out-up) at the normal duration with ease-in.",
       "value": "sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both",
       "aliasOf": null,
       "registered": false,
@@ -4964,7 +4964,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "neutral",
-      "description": "Light neutral shade.",
+      "description": "Light neutral shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -5172,7 +5172,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "neutral",
-      "description": "Near-black neutral shade.",
+      "description": "Near-black neutral shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -5380,7 +5380,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "neutral",
-      "description": "Light neutral shade.",
+      "description": "Light neutral shade for soft accents — alias of --sf-color-neutral-400.",
       "value": "var(--sf-color-neutral-400)",
       "aliasOf": "--sf-color-neutral-400",
       "registered": false,
@@ -5510,7 +5510,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "neutral",
-      "description": "Near-black neutral shade.",
+      "description": "Near-black neutral shade for maximum contrast on light surfaces — alias of --sf-color-neutral-950.",
       "value": "var(--sf-color-neutral-950)",
       "aliasOf": "--sf-color-neutral-950",
       "registered": false,
@@ -5770,7 +5770,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "primary",
-      "description": "Light primary shade.",
+      "description": "Light primary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -5978,7 +5978,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "primary",
-      "description": "Near-black primary shade.",
+      "description": "Near-black primary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -6186,7 +6186,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "primary",
-      "description": "Light primary shade.",
+      "description": "Light primary shade for soft accents — alias of --sf-color-primary-400.",
       "value": "var(--sf-color-primary-400)",
       "aliasOf": "--sf-color-primary-400",
       "registered": false,
@@ -6316,7 +6316,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "primary",
-      "description": "Near-black primary shade.",
+      "description": "Near-black primary shade for maximum contrast on light surfaces — alias of --sf-color-primary-950.",
       "value": "var(--sf-color-primary-950)",
       "aliasOf": "--sf-color-primary-950",
       "registered": false,
@@ -6602,7 +6602,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "secondary",
-      "description": "Light secondary shade.",
+      "description": "Light secondary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -6810,7 +6810,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "secondary",
-      "description": "Near-black secondary shade.",
+      "description": "Near-black secondary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -7018,7 +7018,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "secondary",
-      "description": "Light secondary shade.",
+      "description": "Light secondary shade for soft accents — alias of --sf-color-secondary-400.",
       "value": "var(--sf-color-secondary-400)",
       "aliasOf": "--sf-color-secondary-400",
       "registered": false,
@@ -7148,7 +7148,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "secondary",
-      "description": "Near-black secondary shade.",
+      "description": "Near-black secondary shade for maximum contrast on light surfaces — alias of --sf-color-secondary-950.",
       "value": "var(--sf-color-secondary-950)",
       "aliasOf": "--sf-color-secondary-950",
       "registered": false,
@@ -7304,7 +7304,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Selection",
-      "description": "Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css).",
+      "description": "Alt selection background — the inverse-scheme highlight fill for surfaces that deliberately flip colour scheme (e.g. a dark hero in light mode).",
       "value": "light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )",
       "aliasOf": null,
       "registered": false,
@@ -7356,7 +7356,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Selection",
-      "description": "Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css).",
+      "description": "Alt selection text colour paired with --sf-color-selection-bg--alt; inherits by default so the underlying text colour shows through.",
       "value": "inherit",
       "aliasOf": null,
       "registered": false,
@@ -7694,7 +7694,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "tertiary",
-      "description": "Light tertiary shade.",
+      "description": "Light tertiary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
       "value": "color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))",
       "aliasOf": null,
       "registered": false,
@@ -7902,7 +7902,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "tertiary",
-      "description": "Near-black tertiary shade.",
+      "description": "Near-black tertiary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
       "value": "color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))",
       "aliasOf": null,
       "registered": false,
@@ -8110,7 +8110,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "tertiary",
-      "description": "Light tertiary shade.",
+      "description": "Light tertiary shade for soft accents — alias of --sf-color-tertiary-400.",
       "value": "var(--sf-color-tertiary-400)",
       "aliasOf": "--sf-color-tertiary-400",
       "registered": false,
@@ -8240,7 +8240,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "tertiary",
-      "description": "Near-black tertiary shade.",
+      "description": "Near-black tertiary shade for maximum contrast on light surfaces — alias of --sf-color-tertiary-950.",
       "value": "var(--sf-color-tertiary-950)",
       "aliasOf": "--sf-color-tertiary-950",
       "registered": false,
@@ -9306,7 +9306,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Concave corner",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).",
+      "description": "Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0.",
       "value": "100% 0",
       "aliasOf": null,
       "registered": false,
@@ -9332,7 +9332,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Concave corner",
-      "description": "radius and corner position for .sf-corner-scoop. Override per element: style=\"--sf-corner-scoop-size: var(--sf-radius-3xl)\" (cut radius) or style=\"--sf-corner-scoop-at: 0 0\" (which corner).",
+      "description": "Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl).",
       "value": "var(--sf-radius-2xl)",
       "aliasOf": "--sf-radius-2xl",
       "registered": false,
@@ -15153,7 +15153,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Scroll-driven animation range",
-      "description": "Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out.",
+      "description": "Scroll-timeline range at which a scroll-out exit animation finishes. Default: exit 100%.",
       "value": "exit 100%",
       "aliasOf": null,
       "registered": false,
@@ -15179,7 +15179,7 @@
       "category": "Core tokens",
       "area": "core",
       "group": "Scroll-driven animation range",
-      "description": "Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out.",
+      "description": "Scroll-timeline range at which a scroll-out exit animation begins. Default: cover 70%.",
       "value": "cover 70%",
       "aliasOf": null,
       "registered": false,
@@ -16583,7 +16583,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -16609,7 +16609,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll.",
       "value": "scroll",
       "aliasOf": null,
       "registered": false,
@@ -16635,7 +16635,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "Background colour slot for the .sf-surface-bg macro. Default: transparent.",
       "value": "transparent",
       "aliasOf": null,
       "registered": false,
@@ -16661,7 +16661,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -16687,7 +16687,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none.",
       "value": "none",
       "aliasOf": null,
       "registered": false,
@@ -16713,7 +16713,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "background-position for the .sf-surface-bg image. Default: center.",
       "value": "center",
       "aliasOf": null,
       "registered": false,
@@ -16739,7 +16739,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "background-repeat for the .sf-surface-bg image. Default: no-repeat.",
       "value": "no-repeat",
       "aliasOf": null,
       "registered": false,
@@ -16765,7 +16765,7 @@
       "category": "Macro tokens",
       "area": "macros",
       "group": "Named background surface preset",
-      "description": "input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose…",
+      "description": "background-size for the .sf-surface-bg image. Default: cover.",
       "value": "cover",
       "aliasOf": null,
       "registered": false,
@@ -20833,7 +20833,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Concave \"scooped\" corner cut with a radial-gradient mask; defaults to the top-right corner (--sf-corner-scoop-at). Add a placement modifier to move it.",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -20856,7 +20856,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the bottom-left corner.",
       "isVariant": true,
       "baseClass": "sf-corner-scoop",
       "optional": false,
@@ -20879,7 +20879,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the bottom-right corner.",
       "isVariant": true,
       "baseClass": "sf-corner-scoop",
       "optional": false,
@@ -20902,7 +20902,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the top-left corner.",
       "isVariant": true,
       "baseClass": "sf-corner-scoop",
       "optional": false,
@@ -20925,7 +20925,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that…",
+      "description": "Places the concave corner scoop at the top-right corner.",
       "isVariant": true,
       "baseClass": "sf-corner-scoop",
       "optional": false,
@@ -21109,7 +21109,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "Divide",
-      "description": "Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap.",
+      "description": "Rules between direct children (a border on each child after the first), reusing .sf-divider's tokens — no per-gap markup needed.",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21132,7 +21132,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "Divide",
-      "description": "Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap.",
+      "description": "Vertical rules between direct children (inline-start borders), for row/horizontal layouts.",
       "isVariant": true,
       "baseClass": "sf-divide",
       "optional": false,
@@ -21316,7 +21316,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-l).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21339,7 +21339,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Medium filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-m).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21362,7 +21362,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-s).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21385,7 +21385,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Extra-large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xl).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21408,7 +21408,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos).",
+      "description": "Extra-small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xs).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -21707,7 +21707,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades the element out in place (sf-fade-out).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -21730,7 +21730,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding downward (sf-slide-out-down).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -21753,7 +21753,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding to the left (sf-slide-out-left).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -21776,7 +21776,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding to the right (sf-slide-out-right).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -21799,7 +21799,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while sliding upward (sf-slide-out-up).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -21822,7 +21822,7 @@
       "category": "Motion / animation",
       "area": "motion",
       "group": "",
-      "description": "Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines…",
+      "description": "Scroll-out exit animation: fades out while shrinking (sf-scale-down).",
       "isVariant": true,
       "baseClass": "sf-exit",
       "optional": false,
@@ -23081,7 +23081,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the l step (--sf-space-l).",
       "isVariant": true,
       "baseClass": "sf-header",
       "optional": false,
@@ -23104,7 +23104,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the m step (--sf-space-m).",
       "isVariant": true,
       "baseClass": "sf-header",
       "optional": false,
@@ -23127,7 +23127,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the s step (--sf-space-s).",
       "isVariant": true,
       "baseClass": "sf-header",
       "optional": false,
@@ -23150,7 +23150,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the xl step (--sf-space-xl).",
       "isVariant": true,
       "baseClass": "sf-header",
       "optional": false,
@@ -23173,7 +23173,7 @@
       "category": "Layout primitives",
       "area": "layout",
       "group": "",
-      "description": "Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left…",
+      "description": "Header block padding at the xs step (--sf-space-xs).",
       "isVariant": true,
       "baseClass": "sf-header",
       "optional": false,
@@ -24389,7 +24389,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the action colour.",
       "isVariant": true,
       "baseClass": "sf-marker",
       "optional": true,
@@ -24411,7 +24411,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the primary brand colour.",
       "isVariant": true,
       "baseClass": "sf-marker",
       "optional": true,
@@ -24433,7 +24433,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the secondary brand colour.",
       "isVariant": true,
       "baseClass": "sf-marker",
       "optional": true,
@@ -24455,7 +24455,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "LIST MARKER COLOUR (.sf-marker--*)",
-      "description": "Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities…",
+      "description": "Colours list ::markers with the tertiary brand colour.",
       "isVariant": true,
       "baseClass": "sf-marker",
       "optional": true,
@@ -24684,7 +24684,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element upward (negative block-start margin) so it overlaps the previous sibling by --sf-overlap-pull.",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -24707,7 +24707,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls following content up (negative block-end margin) so this element overlaps the sibling below it.",
       "isVariant": true,
       "baseClass": "sf-overlap",
       "optional": false,
@@ -24730,7 +24730,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element toward the inline-end (negative inline-end margin) to overlap horizontally.",
       "isVariant": true,
       "baseClass": "sf-overlap",
       "optional": false,
@@ -24753,7 +24753,7 @@
       "category": "Macro classes",
       "area": "macros",
       "group": "",
-      "description": "Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob).",
+      "description": "Overlap recipe — pulls the element toward the inline-start (negative inline-start margin) to overlap horizontally.",
       "isVariant": true,
       "baseClass": "sf-overlap",
       "optional": false,
@@ -25765,7 +25765,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "position: sticky pinned at the header-aware --sf-sticky-offset.",
       "isVariant": false,
       "baseClass": null,
       "optional": true,
@@ -25787,7 +25787,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra large gap (--sf-space-l) above the header-aware offset.",
       "isVariant": true,
       "baseClass": "sf-sticky",
       "optional": true,
@@ -25809,7 +25809,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra medium gap (--sf-space-m) above the header-aware offset.",
       "isVariant": true,
       "baseClass": "sf-sticky",
       "optional": true,
@@ -25831,7 +25831,7 @@
       "category": "Utilities",
       "area": "utilities",
       "group": "STICKY POSITIONING (.sf-sticky)",
-      "description": "The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.)",
+      "description": "Sticky positioning with an extra small gap (--sf-space-s) above the header-aware offset.",
       "isVariant": true,
       "baseClass": "sf-sticky",
       "optional": true,
@@ -26512,7 +26512,7 @@
       "category": "Theme utilities",
       "area": "theme",
       "group": "",
-      "description": "",
+      "description": "Forces dark colour scheme on the element and its subtree (class alias of [data-theme=\"dark\"]).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
@@ -26535,7 +26535,7 @@
       "category": "Theme utilities",
       "area": "theme",
       "group": "",
-      "description": "",
+      "description": "Forces light colour scheme on the element and its subtree (class alias of [data-theme=\"light\"]).",
       "isVariant": false,
       "baseClass": null,
       "optional": false,
diff --git a/docs/api-index.md b/docs/api-index.md
index dbac8f67..bffb9487 100644
--- a/docs/api-index.md
+++ b/docs/api-index.md
@@ -73,10 +73,10 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-animation-slide-in-left` | PUBLIC | consumption | animation | `sf-slide-in-left var(--sf-duration-normal) var(--sf-ease-out) both` | Slide-in from the left. Use for left-side drawers and navigation panels. |
 | `--sf-animation-slide-in-right` | PUBLIC | consumption | animation | `sf-slide-in-right var(--sf-duration-normal) var(--sf-ease-out) both` | Slide-in from the right. Use for right-side drawers and detail panels. |
 | `--sf-animation-slide-in-up` | PUBLIC | consumption | animation | `sf-slide-in-up var(--sf-duration-normal) var(--sf-ease-out) both` | Slide-in from below. Use for bottom sheets, toasts, and floating action buttons. |
-| `--sf-animation-slide-out-down` | PUBLIC | consumption | animation | `sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both` | pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in); |
-| `--sf-animation-slide-out-left` | PUBLIC | consumption | animation | `sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both` | pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in); |
-| `--sf-animation-slide-out-right` | PUBLIC | consumption | animation | `sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both` | pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in); |
-| `--sf-animation-slide-out-up` | PUBLIC | consumption | animation | `sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both` | pair keyframes (core/motion.css) with duration + easing. Use directly: animation: var(--sf-animation-fade-in); |
+| `--sf-animation-slide-out-down` | PUBLIC | consumption | animation | `sf-slide-out-down var(--sf-duration-normal) var(--sf-ease-in) both` | Ready-made animation shorthand: slides the element out downward (sf-slide-out-down) at the normal duration with ease-in. |
+| `--sf-animation-slide-out-left` | PUBLIC | consumption | animation | `sf-slide-out-left var(--sf-duration-normal) var(--sf-ease-in) both` | Ready-made animation shorthand: slides the element out to the left (sf-slide-out-left) at the normal duration with ease-in. |
+| `--sf-animation-slide-out-right` | PUBLIC | consumption | animation | `sf-slide-out-right var(--sf-duration-normal) var(--sf-ease-in) both` | Ready-made animation shorthand: slides the element out to the right (sf-slide-out-right) at the normal duration with ease-in. |
+| `--sf-animation-slide-out-up` | PUBLIC | consumption | animation | `sf-slide-out-up var(--sf-duration-normal) var(--sf-ease-in) both` | Ready-made animation shorthand: slides the element out upward (sf-slide-out-up) at the normal duration with ease-in. |
 | `--sf-animation-spin` | PUBLIC | consumption | animation | `sf-spin var(--sf-duration-slower) linear infinite` | Continuous rotation loop. Use for loading spinners and progress indicators. |
 | `--sf-blur` | PUBLIC | knob | blur | `12px` | Backdrop-filter blur amount for frosted-glass surfaces (navbars, overlays, dialogs). Default 12px. Pair with a semi-transparent background. |
 | `--sf-body-color` | PUBLIC | consumption | body | `var(--sf-color-text)` | Text color for body copy. Alias of --sf-color-text. Override here to deviate body text from the global text color. |
@@ -198,7 +198,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-neutral--active` | PUBLIC | consumption | color | `var(--sf-color-neutral-xdark)` | Neutral color at pressed/active brightness. |
 | `--sf-color-neutral--hover` | PUBLIC | consumption | color | `var(--sf-color-neutral-darker)` | Neutral color at hover brightness. |
 | `--sf-color-neutral-100` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-100), var(--sf-color-surface))` | Very light neutral shade. |
-| `--sf-color-neutral-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light neutral shade. |
+| `--sf-color-neutral-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light neutral shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds. |
 | `--sf-color-neutral-300` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-300), var(--sf-color-surface))` | Light-mid neutral shade. |
 | `--sf-color-neutral-400` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-400), var(--sf-color-surface))` | Mid-light neutral shade. |
 | `--sf-color-neutral-50` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-50), var(--sf-color-surface))` | Lightest neutral tint. |
@@ -206,7 +206,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-neutral-600` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-600), var(--sf-color-text))` | Mid-dark neutral shade. |
 | `--sf-color-neutral-700` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-700), var(--sf-color-text))` | Dark neutral shade. |
 | `--sf-color-neutral-800` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-800), var(--sf-color-text))` | Very dark neutral shade. |
-| `--sf-color-neutral-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black neutral shade. |
+| `--sf-color-neutral-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black neutral shade at step 900 on the numeric scale. Extreme contrast on light surfaces. |
 | `--sf-color-neutral-950` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-neutral) var(--sf-palette-mix-950), var(--sf-color-text))` | Darkest neutral tint. |
 | `--sf-color-neutral-a10` | PUBLIC | consumption | color | `oklch(from var(--sf-color-neutral) l c h / 0.10)` | 10% opacity neutral tint. |
 | `--sf-color-neutral-a30` | PUBLIC | consumption | color | `oklch(from var(--sf-color-neutral) l c h / 0.30)` | 30% opacity neutral tint. |
@@ -214,12 +214,12 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-neutral-a50` | PUBLIC | consumption | color | `oklch(from var(--sf-color-neutral) l c h / 0.50)` | 50% opacity neutral tint. |
 | `--sf-color-neutral-a80` | PUBLIC | consumption | color | `oklch(from var(--sf-color-neutral) l c h / 0.80)` | 80% opacity neutral tint. |
 | `--sf-color-neutral-darker` | PUBLIC | consumption | color | `var(--sf-color-neutral-600)` | Deep neutral shade for high-contrast contexts. |
-| `--sf-color-neutral-lighter` | PUBLIC | consumption | color | `var(--sf-color-neutral-400)` | Light neutral shade. |
+| `--sf-color-neutral-lighter` | PUBLIC | consumption | color | `var(--sf-color-neutral-400)` | Light neutral shade for soft accents — alias of --sf-color-neutral-400. |
 | `--sf-color-neutral-muted` | PUBLIC | consumption | color | `var(--sf-color-neutral-a30)` | Muted neutral fill for low-emphasis contexts. |
 | `--sf-color-neutral-source-dark` | PUBLIC | knob | color | `oklch(0.69 0.0225 260)` | Registered <color> dark counterpart of --sf-color-neutral. |
 | `--sf-color-neutral-source-light` | PUBLIC | knob | color | `oklch(0.52 0.025 260)` | OKLCH lightness source for the neutral color. |
 | `--sf-color-neutral-subtle` | PUBLIC | consumption | color | `var(--sf-color-neutral-a10)` | Lightest neutral semantic tint. |
-| `--sf-color-neutral-superdark` | PUBLIC | consumption | color | `var(--sf-color-neutral-950)` | Near-black neutral shade. |
+| `--sf-color-neutral-superdark` | PUBLIC | consumption | color | `var(--sf-color-neutral-950)` | Near-black neutral shade for maximum contrast on light surfaces — alias of --sf-color-neutral-950. |
 | `--sf-color-neutral-superlight` | PUBLIC | consumption | color | `var(--sf-color-neutral-50)` | Near-white neutral shade. |
 | `--sf-color-neutral-tint` | PUBLIC | consumption | color | `var(--sf-color-neutral-a5)` | Near-transparent neutral tint (5% alpha) for hover-state washes and the most subtle backgrounds. |
 | `--sf-color-neutral-xdark` | PUBLIC | consumption | color | `var(--sf-color-neutral-800)` | Extra-dark neutral shade. |
@@ -229,7 +229,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-primary--active` | PUBLIC | consumption | color | `var(--sf-color-primary-xdark)` | Primary color at pressed/active brightness. |
 | `--sf-color-primary--hover` | PUBLIC | consumption | color | `var(--sf-color-primary-darker)` | Primary color at hover brightness. |
 | `--sf-color-primary-100` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-100), var(--sf-color-surface))` | Very light primary shade. |
-| `--sf-color-primary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light primary shade. |
+| `--sf-color-primary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light primary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds. |
 | `--sf-color-primary-300` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-300), var(--sf-color-surface))` | Light-mid primary shade. |
 | `--sf-color-primary-400` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-400), var(--sf-color-surface))` | Mid-light primary shade. |
 | `--sf-color-primary-50` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-50), var(--sf-color-surface))` | Lightest primary tint. |
@@ -237,7 +237,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-primary-600` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-600), var(--sf-color-text))` | Mid-dark primary shade. |
 | `--sf-color-primary-700` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-700), var(--sf-color-text))` | Dark primary shade. |
 | `--sf-color-primary-800` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-800), var(--sf-color-text))` | Very dark primary shade. |
-| `--sf-color-primary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black primary shade. |
+| `--sf-color-primary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black primary shade at step 900 on the numeric scale. Extreme contrast on light surfaces. |
 | `--sf-color-primary-950` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-primary) var(--sf-palette-mix-950), var(--sf-color-text))` | Darkest primary tint. |
 | `--sf-color-primary-a10` | PUBLIC | consumption | color | `oklch(from var(--sf-color-primary) l c h / 0.10)` | 10% opacity primary tint. |
 | `--sf-color-primary-a30` | PUBLIC | consumption | color | `oklch(from var(--sf-color-primary) l c h / 0.30)` | 30% opacity primary tint. |
@@ -245,12 +245,12 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-primary-a50` | PUBLIC | consumption | color | `oklch(from var(--sf-color-primary) l c h / 0.50)` | 50% opacity primary tint. |
 | `--sf-color-primary-a80` | PUBLIC | consumption | color | `oklch(from var(--sf-color-primary) l c h / 0.80)` | 80% opacity primary tint. |
 | `--sf-color-primary-darker` | PUBLIC | consumption | color | `var(--sf-color-primary-600)` | Deep primary shade. |
-| `--sf-color-primary-lighter` | PUBLIC | consumption | color | `var(--sf-color-primary-400)` | Light primary shade. |
+| `--sf-color-primary-lighter` | PUBLIC | consumption | color | `var(--sf-color-primary-400)` | Light primary shade for soft accents — alias of --sf-color-primary-400. |
 | `--sf-color-primary-muted` | PUBLIC | consumption | color | `var(--sf-color-primary-a30)` | Muted primary fill. |
 | `--sf-color-primary-source-dark` | PUBLIC | knob | color | `oklch(0.715 0.243 264)` | Registered <color> dark counterpart of --sf-color-primary. |
 | `--sf-color-primary-source-light` | PUBLIC | knob | color | `oklch(0.47 0.27 264)` | OKLCH lightness source for the primary color. |
 | `--sf-color-primary-subtle` | PUBLIC | consumption | color | `var(--sf-color-primary-a10)` | Lightest primary semantic tint. |
-| `--sf-color-primary-superdark` | PUBLIC | consumption | color | `var(--sf-color-primary-950)` | Near-black primary shade. |
+| `--sf-color-primary-superdark` | PUBLIC | consumption | color | `var(--sf-color-primary-950)` | Near-black primary shade for maximum contrast on light surfaces — alias of --sf-color-primary-950. |
 | `--sf-color-primary-superlight` | PUBLIC | consumption | color | `var(--sf-color-primary-50)` | Near-white primary shade. |
 | `--sf-color-primary-tint` | PUBLIC | consumption | color | `var(--sf-color-primary-a5)` | Near-transparent primary tint (5% alpha) for hover-state washes and the most subtle backgrounds. |
 | `--sf-color-primary-xdark` | PUBLIC | consumption | color | `var(--sf-color-primary-800)` | Extra-dark primary shade. |
@@ -261,7 +261,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-secondary--active` | PUBLIC | consumption | color | `var(--sf-color-secondary-xdark)` | Secondary color at pressed/active brightness. |
 | `--sf-color-secondary--hover` | PUBLIC | consumption | color | `var(--sf-color-secondary-darker)` | Secondary color at hover brightness. |
 | `--sf-color-secondary-100` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-100), var(--sf-color-surface))` | Very light secondary shade. |
-| `--sf-color-secondary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light secondary shade. |
+| `--sf-color-secondary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light secondary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds. |
 | `--sf-color-secondary-300` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-300), var(--sf-color-surface))` | Light-mid secondary shade. |
 | `--sf-color-secondary-400` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-400), var(--sf-color-surface))` | Mid-light secondary shade. |
 | `--sf-color-secondary-50` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-50), var(--sf-color-surface))` | Lightest secondary tint. |
@@ -269,7 +269,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-secondary-600` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-600), var(--sf-color-text))` | Mid-dark secondary shade. |
 | `--sf-color-secondary-700` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-700), var(--sf-color-text))` | Dark secondary shade. |
 | `--sf-color-secondary-800` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-800), var(--sf-color-text))` | Very dark secondary shade. |
-| `--sf-color-secondary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black secondary shade. |
+| `--sf-color-secondary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black secondary shade at step 900 on the numeric scale. Extreme contrast on light surfaces. |
 | `--sf-color-secondary-950` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-secondary) var(--sf-palette-mix-950), var(--sf-color-text))` | Darkest secondary tint. |
 | `--sf-color-secondary-a10` | PUBLIC | consumption | color | `oklch(from var(--sf-color-secondary) l c h / 0.10)` | 10% opacity secondary tint. |
 | `--sf-color-secondary-a30` | PUBLIC | consumption | color | `oklch(from var(--sf-color-secondary) l c h / 0.30)` | 30% opacity secondary tint. |
@@ -277,20 +277,20 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-secondary-a50` | PUBLIC | consumption | color | `oklch(from var(--sf-color-secondary) l c h / 0.50)` | 50% opacity secondary tint. |
 | `--sf-color-secondary-a80` | PUBLIC | consumption | color | `oklch(from var(--sf-color-secondary) l c h / 0.80)` | 80% opacity secondary tint. |
 | `--sf-color-secondary-darker` | PUBLIC | consumption | color | `var(--sf-color-secondary-600)` | Deep secondary shade. |
-| `--sf-color-secondary-lighter` | PUBLIC | consumption | color | `var(--sf-color-secondary-400)` | Light secondary shade. |
+| `--sf-color-secondary-lighter` | PUBLIC | consumption | color | `var(--sf-color-secondary-400)` | Light secondary shade for soft accents — alias of --sf-color-secondary-400. |
 | `--sf-color-secondary-muted` | PUBLIC | consumption | color | `var(--sf-color-secondary-a30)` | Muted secondary fill. |
 | `--sf-color-secondary-source-dark` | PUBLIC | knob | color | `oklch(0.84 0.036 264)` | Registered <color> dark counterpart of --sf-color-secondary. |
 | `--sf-color-secondary-source-light` | PUBLIC | knob | color | `oklch(0.22 0.04 264)` | OKLCH lightness source for the secondary color. |
 | `--sf-color-secondary-subtle` | PUBLIC | consumption | color | `var(--sf-color-secondary-a10)` | Lightest secondary semantic tint. |
-| `--sf-color-secondary-superdark` | PUBLIC | consumption | color | `var(--sf-color-secondary-950)` | Near-black secondary shade. |
+| `--sf-color-secondary-superdark` | PUBLIC | consumption | color | `var(--sf-color-secondary-950)` | Near-black secondary shade for maximum contrast on light surfaces — alias of --sf-color-secondary-950. |
 | `--sf-color-secondary-superlight` | PUBLIC | consumption | color | `var(--sf-color-secondary-50)` | Near-white secondary shade. |
 | `--sf-color-secondary-tint` | PUBLIC | consumption | color | `var(--sf-color-secondary-a5)` | Near-transparent secondary tint (5% alpha) for hover-state washes and the most subtle backgrounds. |
 | `--sf-color-secondary-xdark` | PUBLIC | consumption | color | `var(--sf-color-secondary-800)` | Extra-dark secondary shade. |
 | `--sf-color-secondary-xlight` | PUBLIC | consumption | color | `var(--sf-color-secondary-200)` | Extra-light secondary shade. |
 | `--sf-color-selection-bg` | PUBLIC | consumption | color | `light-dark( oklch(from var(--sf-color-action-source-light) l c h / 0.28), oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55) )` | Background color applied to browser text selections. |
-| `--sf-color-selection-bg--alt` | PUBLIC | consumption | color | `light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )` | Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css). |
+| `--sf-color-selection-bg--alt` | PUBLIC | consumption | color | `light-dark( oklch(from var(--sf-color-action-source-dark) clamp(0.62, calc(0.93 - l * 0.4), 0.78) c h / 0.55), oklch(from var(--sf-color-action-source-light) l c h / 0.28) )` | Alt selection background — the inverse-scheme highlight fill for surfaces that deliberately flip colour scheme (e.g. a dark hero in light mode). |
 | `--sf-color-selection-text` | PUBLIC | knob | color | `inherit` | Text color inside browser text selections. |
-| `--sf-color-selection-text--alt` | PUBLIC | knob | color | `inherit` | Alt selection — the opposite scheme's treatment, for a surface that deliberately inverts colours relative to the page (e.g. a dark card on a light page) where the default pairing above would land with poor contrast. Consumed by .sf-selection--alt (optional/utilities.css). |
+| `--sf-color-selection-text--alt` | PUBLIC | knob | color | `inherit` | Alt selection text colour paired with --sf-color-selection-bg--alt; inherits by default so the underlying text colour shows through. |
 | `--sf-color-success` | PUBLIC | consumption | color | `light-dark(var(--sf-color-success-source-light), var(--sf-color-success-source-dark, oklch(from var(--sf-color-success-source-light) clamp(0.65, calc(0.95 - l * 0.5), 0.88) calc(c * 0.9) h)))` | Positive / success color for confirmation messages and completed-state indicators. |
 | `--sf-color-success-muted` | PUBLIC | consumption | color | `oklch(from var(--sf-color-success) l c h / 0.3)` | Medium success fill for success icons and status chips. |
 | `--sf-color-success-source-dark` | PUBLIC | knob | color | `oklch(0.70 0.144 145)` | Registered <color> dark counterpart of --sf-color-success. |
@@ -303,7 +303,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-tertiary--active` | PUBLIC | consumption | color | `var(--sf-color-tertiary-xdark)` | Tertiary color at pressed/active brightness. |
 | `--sf-color-tertiary--hover` | PUBLIC | consumption | color | `var(--sf-color-tertiary-darker)` | Tertiary color at hover brightness. |
 | `--sf-color-tertiary-100` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-100), var(--sf-color-surface))` | Very light tertiary shade. |
-| `--sf-color-tertiary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light tertiary shade. |
+| `--sf-color-tertiary-200` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-200), var(--sf-color-surface))` | Light tertiary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds. |
 | `--sf-color-tertiary-300` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-300), var(--sf-color-surface))` | Light-mid tertiary shade. |
 | `--sf-color-tertiary-400` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-400), var(--sf-color-surface))` | Mid-light tertiary shade. |
 | `--sf-color-tertiary-50` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-50), var(--sf-color-surface))` | Lightest tertiary tint. |
@@ -311,7 +311,7 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-tertiary-600` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-600), var(--sf-color-text))` | Mid-dark tertiary shade. |
 | `--sf-color-tertiary-700` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-700), var(--sf-color-text))` | Dark tertiary shade. |
 | `--sf-color-tertiary-800` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-800), var(--sf-color-text))` | Very dark tertiary shade. |
-| `--sf-color-tertiary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black tertiary shade. |
+| `--sf-color-tertiary-900` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-900), var(--sf-color-text))` | Near-black tertiary shade at step 900 on the numeric scale. Extreme contrast on light surfaces. |
 | `--sf-color-tertiary-950` | PUBLIC | consumption | color | `color-mix(in oklab, var(--sf-color-tertiary) var(--sf-palette-mix-950), var(--sf-color-text))` | Darkest tertiary tint. |
 | `--sf-color-tertiary-a10` | PUBLIC | consumption | color | `oklch(from var(--sf-color-tertiary) l c h / 0.10)` | 10% opacity tertiary tint. |
 | `--sf-color-tertiary-a30` | PUBLIC | consumption | color | `oklch(from var(--sf-color-tertiary) l c h / 0.30)` | 30% opacity tertiary tint. |
@@ -319,12 +319,12 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-color-tertiary-a50` | PUBLIC | consumption | color | `oklch(from var(--sf-color-tertiary) l c h / 0.50)` | 50% opacity tertiary tint. |
 | `--sf-color-tertiary-a80` | PUBLIC | consumption | color | `oklch(from var(--sf-color-tertiary) l c h / 0.80)` | 80% opacity tertiary tint. |
 | `--sf-color-tertiary-darker` | PUBLIC | consumption | color | `var(--sf-color-tertiary-600)` | Deep tertiary shade. |
-| `--sf-color-tertiary-lighter` | PUBLIC | consumption | color | `var(--sf-color-tertiary-400)` | Light tertiary shade. |
+| `--sf-color-tertiary-lighter` | PUBLIC | consumption | color | `var(--sf-color-tertiary-400)` | Light tertiary shade for soft accents — alias of --sf-color-tertiary-400. |
 | `--sf-color-tertiary-muted` | PUBLIC | consumption | color | `var(--sf-color-tertiary-a30)` | Muted tertiary fill. |
 | `--sf-color-tertiary-source-dark` | PUBLIC | knob | color | `oklch(0.74 0.198 295)` | Registered <color> dark counterpart of --sf-color-tertiary. |
 | `--sf-color-tertiary-source-light` | PUBLIC | knob | color | `oklch(0.42 0.22 295)` | OKLCH lightness source for the tertiary color. |
 | `--sf-color-tertiary-subtle` | PUBLIC | consumption | color | `var(--sf-color-tertiary-a10)` | Lightest tertiary semantic tint. |
-| `--sf-color-tertiary-superdark` | PUBLIC | consumption | color | `var(--sf-color-tertiary-950)` | Near-black tertiary shade. |
+| `--sf-color-tertiary-superdark` | PUBLIC | consumption | color | `var(--sf-color-tertiary-950)` | Near-black tertiary shade for maximum contrast on light surfaces — alias of --sf-color-tertiary-950. |
 | `--sf-color-tertiary-superlight` | PUBLIC | consumption | color | `var(--sf-color-tertiary-50)` | Near-white tertiary shade. |
 | `--sf-color-tertiary-tint` | PUBLIC | consumption | color | `var(--sf-color-tertiary-a5)` | Near-transparent tertiary tint (5% alpha) for hover-state washes and the most subtle backgrounds. |
 | `--sf-color-tertiary-xdark` | PUBLIC | consumption | color | `var(--sf-color-tertiary-800)` | Extra-dark tertiary shade. |
@@ -537,8 +537,8 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-safe-right` | PUBLIC-ADVANCED | knob | safe | `env(safe-area-inset-right, 0px)` | Device safe-area inset at the right edge (rounded corners, home indicator). Resolves to env(safe-area-inset-right, 0px). |
 | `--sf-safe-top` | PUBLIC-ADVANCED | knob | safe | `env(safe-area-inset-top, 0px)` | Device safe-area inset at the top edge (notch, Dynamic Island). Resolves to env(safe-area-inset-top, 0px). Use for fixed headers on notched devices. |
 | `--sf-scroll-timeline-range-end` | PUBLIC-ADVANCED | knob | scroll | `cover 30%` | animation-range end value for scroll-driven entrance effects. Default 'cover 30%'. Override on an element to control when its entrance animation finishes. |
-| `--sf-scroll-timeline-range-exit-end` | PUBLIC | knob | scroll | `exit 100%` | Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out. |
-| `--sf-scroll-timeline-range-exit-start` | PUBLIC | knob | scroll | `cover 70%` | Exit counterpart — element is well into view before starting to leave, finishing exactly as it scrolls fully out. |
+| `--sf-scroll-timeline-range-exit-end` | PUBLIC | knob | scroll | `exit 100%` | Scroll-timeline range at which a scroll-out exit animation finishes. Default: exit 100%. |
+| `--sf-scroll-timeline-range-exit-start` | PUBLIC | knob | scroll | `cover 70%` | Scroll-timeline range at which a scroll-out exit animation begins. Default: cover 70%. |
 | `--sf-scroll-timeline-range-start` | PUBLIC-ADVANCED | knob | scroll | `entry 0%` | animation-range start value for scroll-driven entrance effects. Default 'entry 0%'. Override on an element to control when its entrance animation begins. |
 | `--sf-scrollbar-thumb` | PUBLIC | consumption | scrollbar | `var(--sf-color-neutral)` | Color of the custom scrollbar thumb. |
 | `--sf-scrollbar-track` | PUBLIC | knob | scrollbar | `transparent` | Color of the custom scrollbar track. |
@@ -742,8 +742,8 @@ and a short description. The machine-readable companion (with all columns) is
 |---|---|---|---|---|---|
 | `--sf-aspect` | PUBLIC | knob | aspect | `16 / 9` | Aspect ratio value for the .aspect-ratio macro. |
 | `--sf-content-intrinsic-size` | PUBLIC | knob | content | `500px` | Intrinsic-size hint for content-visibility: auto (prevents layout shift on first reveal). |
-| `--sf-corner-scoop-at` | PUBLIC | knob | corner | `100% 0` | radius and corner position for .sf-corner-scoop. Override per element: style="--sf-corner-scoop-size: var(--sf-radius-3xl)" (cut radius) or style="--sf-corner-scoop-at: 0 0" (which corner). |
-| `--sf-corner-scoop-size` | PUBLIC | consumption | corner | `var(--sf-radius-2xl)` | radius and corner position for .sf-corner-scoop. Override per element: style="--sf-corner-scoop-size: var(--sf-radius-3xl)" (cut radius) or style="--sf-corner-scoop-at: 0 0" (which corner). |
+| `--sf-corner-scoop-at` | PUBLIC | knob | corner | `100% 0` | Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0. |
+| `--sf-corner-scoop-size` | PUBLIC | consumption | corner | `var(--sf-radius-2xl)` | Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl). |
 | `--sf-flow-space` | PUBLIC | consumption | flow | `var(--sf-content-gap)` | Margin-block-start applied to all flow children except the first. |
 | `--sf-line-clamp` | PUBLIC | knob | line | `3` | Number of visible lines before text is clipped with an ellipsis. |
 | `--sf-overlap-pull` | PUBLIC | consumption | overlap | `var(--sf-space-xl)` | how far .sf-overlap pulls into the adjacent element. .sf-overlap-host's padding compensation defaults to this same value via a var() fallback in the rule itself (not aliased here — see core/macros.css), so one override on the host tunes both unless --sf-overlap-host-pad is set… |
@@ -765,14 +765,14 @@ and a short description. The machine-readable companion (with all columns) is
 | `--sf-scrim-gradient` | PUBLIC | consumption | scrim | `linear-gradient(var(--sf-scrim-direction), var(--sf-scrim-color), transparent)` | Full gradient shorthand for the scrim. Override to customise the fade. |
 | `--sf-scrim-text-shadow` | PUBLIC | knob | scrim | `0 1px 3px oklch(0 0 0 / 0.6)` | Text-shadow layered over the scrim gradient to ensure legibility for text placed directly on image backgrounds. |
 | `--sf-scroll-shadow-size` | PUBLIC | knob | scroll | `2rem` | Size of the scroll-shadow fade effect on overflowing containers. |
-| `--sf-surface-bg-animation` | PUBLIC | knob | surface | `none` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-attachment` | PUBLIC | knob | surface | `scroll` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-color` | PUBLIC | knob | surface | `transparent` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-image` | PUBLIC | knob | surface | `none` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-overlay` | PUBLIC | knob | surface | `none` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-position` | PUBLIC | knob | surface | `center` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-repeat` | PUBLIC | knob | surface | `no-repeat` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
-| `--sf-surface-bg-size` | PUBLIC | knob | surface | `cover` | input set for the .sf-surface-bg macro (issue #523). One reusable, named background bundling a base colour fallback + image/gradient/pattern + sizing + an optional overlay + an optional animation. Define a preset by setting these on a scope, then apply .sf-surface-bg to compose… |
+| `--sf-surface-bg-animation` | PUBLIC | knob | surface | `none` | animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none. |
+| `--sf-surface-bg-attachment` | PUBLIC | knob | surface | `scroll` | background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll. |
+| `--sf-surface-bg-color` | PUBLIC | knob | surface | `transparent` | Background colour slot for the .sf-surface-bg macro. Default: transparent. |
+| `--sf-surface-bg-image` | PUBLIC | knob | surface | `none` | Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none. |
+| `--sf-surface-bg-overlay` | PUBLIC | knob | surface | `none` | Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none. |
+| `--sf-surface-bg-position` | PUBLIC | knob | surface | `center` | background-position for the .sf-surface-bg image. Default: center. |
+| `--sf-surface-bg-repeat` | PUBLIC | knob | surface | `no-repeat` | background-repeat for the .sf-surface-bg image. Default: no-repeat. |
+| `--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 (329)
@@ -869,8 +869,8 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-cover--padding-l` | PUBLIC | layout | Cover | Cover variant with large vertical padding above and below the centered content. |
 | `.sf-cover--padding-s` | PUBLIC | layout | Cover | Cover variant with small vertical padding above and below the centered content. |
 | `.sf-cq` | PUBLIC | layout | Container query context | Assigns an inline-size container context to any element. Children can then use @container rules or container-query-aware tokens. |
-| `.sf-divide` | PUBLIC | layout | Divide | Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap. |
-| `.sf-divide--vertical` | PUBLIC | layout | Divide | Divide — rules between direct children, reusing .sf-divider's tokens. Unlike .sf-divider (a standalone separator element), .sf-divide is applied to the container and needs no extra markup per gap. |
+| `.sf-divide` | PUBLIC | layout | Divide | Rules between direct children (a border on each child after the first), reusing .sf-divider's tokens — no per-gap markup needed. |
+| `.sf-divide--vertical` | PUBLIC | layout | Divide | Vertical rules between direct children (inline-start borders), for row/horizontal layouts. |
 | `.sf-divider` | PUBLIC | layout | Divider | Horizontal rule (divider line). Uses --sf-divider-* tokens for color, width, and style. Modifiers change dash style or orientation. |
 | `.sf-divider--dashed` | PUBLIC | layout | Divider | Divider variant with a dashed stroke. |
 | `.sf-divider--dotted` | PUBLIC | layout | Divider | Divider variant with a dotted stroke. |
@@ -926,11 +926,11 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-grid-flex--s` | PUBLIC | layout | Grid (flex) | Grid-flex variant with a small (s) minimum item width. |
 | `.sf-grid-flex--xl` | PUBLIC | layout | Grid (flex) | Grid-flex variant with an xl minimum item width. |
 | `.sf-grid-flex--xs` | PUBLIC | layout | Grid (flex) | Grid-flex variant with an xs minimum item width. |
-| `.sf-header--l` | PUBLIC | layout | — | Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left… |
-| `.sf-header--m` | PUBLIC | layout | — | Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left… |
-| `.sf-header--s` | PUBLIC | layout | — | Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left… |
-| `.sf-header--xl` | PUBLIC | layout | — | Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left… |
-| `.sf-header--xs` | PUBLIC | layout | — | Header — block padding on the standard spacing scale. Headers usually want lighter vertical rhythm than .sf-section, so these map to --sf-space-* directly. Only block padding is set; any inline gutter (from .sf-section--guttered, a container, or the element itself) is left… |
+| `.sf-header--l` | PUBLIC | layout | — | Header block padding at the l step (--sf-space-l). |
+| `.sf-header--m` | PUBLIC | layout | — | Header block padding at the m step (--sf-space-m). |
+| `.sf-header--s` | PUBLIC | layout | — | Header block padding at the s step (--sf-space-s). |
+| `.sf-header--xl` | PUBLIC | layout | — | Header block padding at the xl step (--sf-space-xl). |
+| `.sf-header--xs` | PUBLIC | layout | — | Header block padding at the xs step (--sf-space-xs). |
 | `.sf-icon` | PUBLIC | layout | Icon | Inline icon sizing primitive. Sets width and height to --sf-icon-m via em-based tokens so the icon scales with the surrounding text. |
 | `.sf-icon--2xl` | PUBLIC | layout | Icon | Icon variant sized to --sf-icon-2xl (extra-extra-large). |
 | `.sf-icon--boxed` | PUBLIC | layout | Icon | Icon variant with a square bordered box background. Useful for standalone icon buttons and feature icons. |
@@ -981,16 +981,16 @@ and a short description. The machine-readable companion (with all columns) is
 |---|---|---|---|---|
 | `.sf-aspect` | PUBLIC | macro | Aspect | Sets aspect-ratio from a --sf-aspect-ratio scoped token. Override the token inline to get any ratio without a new class. |
 | `.sf-content-auto` | PUBLIC | macro | Content visibility | Sets content-visibility: auto on the element. The browser skips rendering off-screen content, improving LCP for long pages. |
-| `.sf-corner-scoop` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
-| `.sf-corner-scoop--bottom-left` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
-| `.sf-corner-scoop--bottom-right` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
-| `.sf-corner-scoop--top-left` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
-| `.sf-corner-scoop--top-right` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
-| `.sf-drop-shadow-l` | PUBLIC | macro | — | filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos). |
-| `.sf-drop-shadow-m` | PUBLIC | macro | — | filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos). |
-| `.sf-drop-shadow-s` | PUBLIC | macro | — | filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos). |
-| `.sf-drop-shadow-xl` | PUBLIC | macro | — | filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos). |
-| `.sf-drop-shadow-xs` | PUBLIC | macro | — | filter: drop-shadow() utilities — unlike box-shadow, follows the element's actual alpha shape (SVG icons, PNG cutouts, transparent logos). |
+| `.sf-corner-scoop` | PUBLIC | macro | — | Concave "scooped" corner cut with a radial-gradient mask; defaults to the top-right corner (--sf-corner-scoop-at). Add a placement modifier to move it. |
+| `.sf-corner-scoop--bottom-left` | PUBLIC | macro | — | Places the concave corner scoop at the bottom-left corner. |
+| `.sf-corner-scoop--bottom-right` | PUBLIC | macro | — | Places the concave corner scoop at the bottom-right corner. |
+| `.sf-corner-scoop--top-left` | PUBLIC | macro | — | Places the concave corner scoop at the top-left corner. |
+| `.sf-corner-scoop--top-right` | PUBLIC | macro | — | Places the concave corner scoop at the top-right corner. |
+| `.sf-drop-shadow-l` | PUBLIC | macro | — | Large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-l). |
+| `.sf-drop-shadow-m` | PUBLIC | macro | — | Medium filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-m). |
+| `.sf-drop-shadow-s` | PUBLIC | macro | — | Small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-s). |
+| `.sf-drop-shadow-xl` | PUBLIC | macro | — | Extra-large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xl). |
+| `.sf-drop-shadow-xs` | PUBLIC | macro | — | Extra-small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xs). |
 | `.sf-equal-height` | PUBLIC | macro | Equal height | Forces all flex children to equal height (align-items: stretch). Use on a flex row to make cards in a grid share the tallest card's height. |
 | `.sf-flow` | PUBLIC | macro | Flow | Applies --sf-flow-space as margin-block-start to all direct children except the first. Establishes consistent vertical rhythm in prose-like containers. |
 | `.sf-line-clamp-2` | PUBLIC | macro | Truncate / line-clamp | Clamps text to 2 lines with an ellipsis. Applies -webkit-line-clamp: 2. |
@@ -1008,10 +1008,10 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-overflow-fade--left` | PUBLIC | macro | — | Overflow fade variant: fades the left (inline-start) edge. |
 | `.sf-overflow-fade--right` | PUBLIC | macro | — | Overflow fade variant: fades the right (inline-end) edge. Explicit alias for the default sf-overflow-fade behaviour. |
 | `.sf-overflow-fade--top` | PUBLIC | macro | — | Overflow fade variant: fades the top (block-start) edge. |
-| `.sf-overlap` | PUBLIC | macro | — | Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob). |
-| `.sf-overlap--down` | PUBLIC | macro | — | Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob). |
-| `.sf-overlap--end` | PUBLIC | macro | — | Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob). |
-| `.sf-overlap--start` | PUBLIC | macro | — | Overlap recipe — one element intentionally overlapping the previous one (e.g. an image pulled up over the card below it), via a negative logical margin + a raised stacking context. Directional variants are standalone (margins are distinct properties, not a re-pointable knob). |
+| `.sf-overlap` | PUBLIC | macro | — | Overlap recipe — pulls the element upward (negative block-start margin) so it overlaps the previous sibling by --sf-overlap-pull. |
+| `.sf-overlap--down` | PUBLIC | macro | — | Overlap recipe — pulls following content up (negative block-end margin) so this element overlaps the sibling below it. |
+| `.sf-overlap--end` | PUBLIC | macro | — | Overlap recipe — pulls the element toward the inline-end (negative inline-end margin) to overlap horizontally. |
+| `.sf-overlap--start` | PUBLIC | macro | — | Overlap recipe — pulls the element toward the inline-start (negative inline-start margin) to overlap horizontally. |
 | `.sf-overlap-host` | PUBLIC | macro | — | Card-container recipe — the receiving side of an overlap: an isolated stacking context with block-start padding compensation so in-flow content clears an element intruding from above. The padding knob defaults to the pull knob so one override tunes both. |
 | `.sf-prose` | PUBLIC | macro | LIST MARKER COLOUR (.sf-marker--*) | Opinionated typographic defaults for long-form content: heading hierarchy, paragraph spacing, blockquote, code, and list styling. Override with sf-not-prose. |
 | `.sf-scrim` | PUBLIC | macro | Scrim | Overlay container with a gradient darkening scrim behind text placed on an image or colored background. |
@@ -1049,12 +1049,12 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-entrance--fade-right` | PUBLIC | motion | Scroll-driven entrances | Scroll-driven entrance: element fades in while moving from the left toward the right. |
 | `.sf-entrance--fade-up` | PUBLIC | motion | Scroll-driven entrances | Scroll-driven entrance: element fades in while moving upward into position. |
 | `.sf-entrance--scale-up` | PUBLIC | motion | Scroll-driven entrances | Scroll-driven entrance: element fades in while scaling up from a slightly smaller size. |
-| `.sf-exit--fade` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
-| `.sf-exit--fade-down` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
-| `.sf-exit--fade-left` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
-| `.sf-exit--fade-right` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
-| `.sf-exit--fade-up` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
-| `.sf-exit--scale-down` | PUBLIC | motion | — | Exit counterpart of .sf-entrance--*: fires as the element scrolls out of view. Every declaration below lives inside @supports — unlike entrance (where a non-scroll fallback still ends visible), an unconditional exit animation would leave content permanently hidden on engines… |
+| `.sf-exit--fade` | PUBLIC | motion | — | Scroll-out exit animation: fades the element out in place (sf-fade-out). |
+| `.sf-exit--fade-down` | PUBLIC | motion | — | Scroll-out exit animation: fades out while sliding downward (sf-slide-out-down). |
+| `.sf-exit--fade-left` | PUBLIC | motion | — | Scroll-out exit animation: fades out while sliding to the left (sf-slide-out-left). |
+| `.sf-exit--fade-right` | PUBLIC | motion | — | Scroll-out exit animation: fades out while sliding to the right (sf-slide-out-right). |
+| `.sf-exit--fade-up` | PUBLIC | motion | — | Scroll-out exit animation: fades out while sliding upward (sf-slide-out-up). |
+| `.sf-exit--scale-down` | PUBLIC | motion | — | Scroll-out exit animation: fades out while shrinking (sf-scale-down). |
 | `.sf-fade-in` | PUBLIC | motion | Animation presets | One-shot fade-in animation (opacity 0 → 1). Scoped to no-preference so it stops automatically for reduced-motion users. |
 | `.sf-fade-out` | PUBLIC | motion | Animation presets | One-shot fade-out animation (opacity 1 → 0). Scoped to no-preference. |
 | `.sf-scale-down` | PUBLIC | motion | Animation presets | One-shot scale-down animation (element shrinks from full size). Scoped to no-preference. |
@@ -1116,8 +1116,8 @@ and a short description. The machine-readable companion (with all columns) is
 
 | Class | Tier | Kind | Group | Description |
 |---|---|---|---|---|
-| `.sf-theme-dark` | PUBLIC | theme | — |  |
-| `.sf-theme-light` | PUBLIC | theme | — |  |
+| `.sf-theme-dark` | PUBLIC | theme | — | Forces dark colour scheme on the element and its subtree (class alias of [data-theme="dark"]). |
+| `.sf-theme-light` | PUBLIC | theme | — | Forces light colour scheme on the element and its subtree (class alias of [data-theme="light"]). |
 | `.sf-theme-transition` | PUBLIC | theme | OPT-IN THEME CROSS-FADE | Opt-in animated light/dark theme crossfade. Apply to <html> (or a subtree) so color tokens transition smoothly when [data-theme] changes. Duration controlled by --sf-theme-transition-duration. |
 
 ### Utilities (31)
@@ -1137,15 +1137,15 @@ and a short description. The machine-readable companion (with all columns) is
 | `.sf-hover-slide-end` | PUBLIC | utility | HOVER-TRANSFORM UTILITIES (.sf-hover-*) | Hover-triggered transform: translates the element toward the inline-end on hover. |
 | `.sf-hover-slide-start` | PUBLIC | utility | HOVER-TRANSFORM UTILITIES (.sf-hover-*) | Hover-triggered transform: translates the element toward the inline-start on hover. |
 | `.sf-list-none` | PUBLIC | utility | LIST RESET (.sf-list-none) | Drops marker + inline start-padding in one class, on any <ul>/<ol> (or element with list-style applied). |
-| `.sf-marker--action` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities… |
-| `.sf-marker--primary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities… |
-| `.sf-marker--secondary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities… |
-| `.sf-marker--tertiary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colour the ::marker of an arbitrary list. Brand/action families only — for any other colour set `::marker { color }` yourself. The :not(.sf-prose *) guard keeps this utility from reaching into a .sf-prose subtree, which owns its markers via --sf-prose-marker-color (utilities… |
+| `.sf-marker--action` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colours list ::markers with the action colour. |
+| `.sf-marker--primary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colours list ::markers with the primary brand colour. |
+| `.sf-marker--secondary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colours list ::markers with the secondary brand colour. |
+| `.sf-marker--tertiary` | PUBLIC | utility | LIST MARKER COLOUR (.sf-marker--*) | Colours list ::markers with the tertiary brand colour. |
 | `.sf-selection--alt` | PUBLIC | utility | ALTERNATE SELECTION COLOUR (.sf-selection--alt) | Overrides the ::selection custom properties (core/base.css) on the element and its descendants, for surfaces where the default selection colours land with poor contrast (e.g. a dark card on a light page). Backed by --sf-color-selection-*--alt (core/tokens.css). |
-| `.sf-sticky` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.) |
-| `.sf-sticky--l` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.) |
-| `.sf-sticky--m` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.) |
-| `.sf-sticky--s` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | The sticky mechanism — position: sticky at the header-aware --sf-sticky-offset. Offset modifiers (--s/-m/-l) add extra gap on top of that fluid offset. (position: sticky is already conditional by nature, so there is no separate runtime-toggled state class.) |
+| `.sf-sticky` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | position: sticky pinned at the header-aware --sf-sticky-offset. |
+| `.sf-sticky--l` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | Sticky positioning with an extra large gap (--sf-space-l) above the header-aware offset. |
+| `.sf-sticky--m` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | Sticky positioning with an extra medium gap (--sf-space-m) above the header-aware offset. |
+| `.sf-sticky--s` | PUBLIC | utility | STICKY POSITIONING (.sf-sticky) | Sticky positioning with an extra small gap (--sf-space-s) above the header-aware offset. |
 | `.sf-text-2xl` | PUBLIC | utility | TEXT-SIZE UTILITIES (.sf-text-2xs | Applies the 2xl text-size role: font-size, line-height, font-weight, letter-spacing, and measure (max-inline-size) in one class. |
 | `.sf-text-2xs` | PUBLIC | utility | TEXT-SIZE UTILITIES (.sf-text-2xs | Applies the 2xs text-size role: font-size, line-height, font-weight, letter-spacing, and measure (max-inline-size) in one class. |
 | `.sf-text-3xl` | PUBLIC | utility | TEXT-SIZE UTILITIES (.sf-text-2xs | Applies the 3xl text-size role: font-size, line-height, font-weight, letter-spacing, and measure (max-inline-size) in one class. |
diff --git a/docs/token-annotations.json b/docs/token-annotations.json
index 35f44901..cc1619e3 100644
--- a/docs/token-annotations.json
+++ b/docs/token-annotations.json
@@ -504,14 +504,14 @@
     "--sf-color-base-a80": "80% opacity base-surface tint.",
     "--sf-color-neutral-50": "Lightest neutral tint.",
     "--sf-color-neutral-100": "Very light neutral shade.",
-    "--sf-color-neutral-200": "Light neutral shade.",
+    "--sf-color-neutral-200": "Light neutral shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
     "--sf-color-neutral-300": "Light-mid neutral shade.",
     "--sf-color-neutral-400": "Mid-light neutral shade.",
     "--sf-color-neutral-500": "Mid neutral shade — the 'pure' hue.",
     "--sf-color-neutral-600": "Mid-dark neutral shade.",
     "--sf-color-neutral-700": "Dark neutral shade.",
     "--sf-color-neutral-800": "Very dark neutral shade.",
-    "--sf-color-neutral-900": "Near-black neutral shade.",
+    "--sf-color-neutral-900": "Near-black neutral shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
     "--sf-color-neutral-950": "Darkest neutral tint.",
     "--sf-color-neutral-a5": "5% opacity neutral tint.",
     "--sf-color-neutral-a10": "10% opacity neutral tint.",
@@ -523,22 +523,22 @@
     "--sf-color-neutral--hover": "Neutral color at hover brightness.",
     "--sf-color-neutral--active": "Neutral color at pressed/active brightness.",
     "--sf-color-neutral-darker": "Deep neutral shade for high-contrast contexts.",
-    "--sf-color-neutral-lighter": "Light neutral shade.",
+    "--sf-color-neutral-lighter": "Light neutral shade for soft accents — alias of --sf-color-neutral-400.",
     "--sf-color-neutral-tint": "Near-transparent neutral tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-color-neutral-xdark": "Extra-dark neutral shade.",
     "--sf-color-neutral-xlight": "Extra-light neutral shade.",
-    "--sf-color-neutral-superdark": "Near-black neutral shade.",
+    "--sf-color-neutral-superdark": "Near-black neutral shade for maximum contrast on light surfaces — alias of --sf-color-neutral-950.",
     "--sf-color-neutral-superlight": "Near-white neutral shade.",
     "--sf-color-primary-50": "Lightest primary tint.",
     "--sf-color-primary-100": "Very light primary shade.",
-    "--sf-color-primary-200": "Light primary shade.",
+    "--sf-color-primary-200": "Light primary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
     "--sf-color-primary-300": "Light-mid primary shade.",
     "--sf-color-primary-400": "Mid-light primary shade.",
     "--sf-color-primary-500": "Mid primary shade — the 'pure' hue.",
     "--sf-color-primary-600": "Mid-dark primary shade.",
     "--sf-color-primary-700": "Dark primary shade.",
     "--sf-color-primary-800": "Very dark primary shade.",
-    "--sf-color-primary-900": "Near-black primary shade.",
+    "--sf-color-primary-900": "Near-black primary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
     "--sf-color-primary-950": "Darkest primary tint.",
     "--sf-color-primary-a5": "5% opacity primary tint.",
     "--sf-color-primary-a10": "10% opacity primary tint.",
@@ -550,22 +550,22 @@
     "--sf-color-primary--hover": "Primary color at hover brightness.",
     "--sf-color-primary--active": "Primary color at pressed/active brightness.",
     "--sf-color-primary-darker": "Deep primary shade.",
-    "--sf-color-primary-lighter": "Light primary shade.",
+    "--sf-color-primary-lighter": "Light primary shade for soft accents — alias of --sf-color-primary-400.",
     "--sf-color-primary-tint": "Near-transparent primary tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-color-primary-xdark": "Extra-dark primary shade.",
     "--sf-color-primary-xlight": "Extra-light primary shade.",
-    "--sf-color-primary-superdark": "Near-black primary shade.",
+    "--sf-color-primary-superdark": "Near-black primary shade for maximum contrast on light surfaces — alias of --sf-color-primary-950.",
     "--sf-color-primary-superlight": "Near-white primary shade.",
     "--sf-color-secondary-50": "Lightest secondary tint.",
     "--sf-color-secondary-100": "Very light secondary shade.",
-    "--sf-color-secondary-200": "Light secondary shade.",
+    "--sf-color-secondary-200": "Light secondary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
     "--sf-color-secondary-300": "Light-mid secondary shade.",
     "--sf-color-secondary-400": "Mid-light secondary shade.",
     "--sf-color-secondary-500": "Mid secondary shade — the 'pure' hue.",
     "--sf-color-secondary-600": "Mid-dark secondary shade.",
     "--sf-color-secondary-700": "Dark secondary shade.",
     "--sf-color-secondary-800": "Very dark secondary shade.",
-    "--sf-color-secondary-900": "Near-black secondary shade.",
+    "--sf-color-secondary-900": "Near-black secondary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
     "--sf-color-secondary-950": "Darkest secondary tint.",
     "--sf-color-secondary-a5": "5% opacity secondary tint.",
     "--sf-color-secondary-a10": "10% opacity secondary tint.",
@@ -577,22 +577,22 @@
     "--sf-color-secondary--hover": "Secondary color at hover brightness.",
     "--sf-color-secondary--active": "Secondary color at pressed/active brightness.",
     "--sf-color-secondary-darker": "Deep secondary shade.",
-    "--sf-color-secondary-lighter": "Light secondary shade.",
+    "--sf-color-secondary-lighter": "Light secondary shade for soft accents — alias of --sf-color-secondary-400.",
     "--sf-color-secondary-tint": "Near-transparent secondary tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-color-secondary-xdark": "Extra-dark secondary shade.",
     "--sf-color-secondary-xlight": "Extra-light secondary shade.",
-    "--sf-color-secondary-superdark": "Near-black secondary shade.",
+    "--sf-color-secondary-superdark": "Near-black secondary shade for maximum contrast on light surfaces — alias of --sf-color-secondary-950.",
     "--sf-color-secondary-superlight": "Near-white secondary shade.",
     "--sf-color-tertiary-50": "Lightest tertiary tint.",
     "--sf-color-tertiary-100": "Very light tertiary shade.",
-    "--sf-color-tertiary-200": "Light tertiary shade.",
+    "--sf-color-tertiary-200": "Light tertiary shade at step 200 on the numeric scale. Subtle fills and outlined badge backgrounds.",
     "--sf-color-tertiary-300": "Light-mid tertiary shade.",
     "--sf-color-tertiary-400": "Mid-light tertiary shade.",
     "--sf-color-tertiary-500": "Mid tertiary shade — the 'pure' hue.",
     "--sf-color-tertiary-600": "Mid-dark tertiary shade.",
     "--sf-color-tertiary-700": "Dark tertiary shade.",
     "--sf-color-tertiary-800": "Very dark tertiary shade.",
-    "--sf-color-tertiary-900": "Near-black tertiary shade.",
+    "--sf-color-tertiary-900": "Near-black tertiary shade at step 900 on the numeric scale. Extreme contrast on light surfaces.",
     "--sf-color-tertiary-950": "Darkest tertiary tint.",
     "--sf-color-tertiary-a5": "5% opacity tertiary tint.",
     "--sf-color-tertiary-a10": "10% opacity tertiary tint.",
@@ -604,11 +604,11 @@
     "--sf-color-tertiary--hover": "Tertiary color at hover brightness.",
     "--sf-color-tertiary--active": "Tertiary color at pressed/active brightness.",
     "--sf-color-tertiary-darker": "Deep tertiary shade.",
-    "--sf-color-tertiary-lighter": "Light tertiary shade.",
+    "--sf-color-tertiary-lighter": "Light tertiary shade for soft accents — alias of --sf-color-tertiary-400.",
     "--sf-color-tertiary-tint": "Near-transparent tertiary tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-color-tertiary-xdark": "Extra-dark tertiary shade.",
     "--sf-color-tertiary-xlight": "Extra-light tertiary shade.",
-    "--sf-color-tertiary-superdark": "Near-black tertiary shade.",
+    "--sf-color-tertiary-superdark": "Near-black tertiary shade for maximum contrast on light surfaces — alias of --sf-color-tertiary-950.",
     "--sf-color-tertiary-superlight": "Near-white tertiary shade.",
     "--sf-color-code-bg": "Background for inline <code> elements. Usually a subtle tint of the inset surface.",
     "--sf-color-link--underline": "Color of the link underline decoration. Defaults to a semi-transparent variant of the link color.",
@@ -827,7 +827,25 @@
     "--sf-color-info-tint": "Near-transparent info tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-color-danger-tint": "Near-transparent danger tint (5% alpha) for hover-state washes and the most subtle backgrounds.",
     "--sf-gradient-action": "Gradient using action palette colors (light to saturated). Core-4 parity with the primary/secondary/tertiary gradients; drives the default .sf-btn--gradient fill.",
-    "--sf-card-avatar-size": "Diameter of .sf-card__avatar. Defaults to 2.5rem."
+    "--sf-card-avatar-size": "Diameter of .sf-card__avatar. Defaults to 2.5rem.",
+    "--sf-surface-bg-color": "Background colour slot for the .sf-surface-bg macro. Default: transparent.",
+    "--sf-surface-bg-image": "Background image slot for the .sf-surface-bg macro (e.g. url(…)). Default: none.",
+    "--sf-surface-bg-overlay": "Overlay layer composited above the image in .sf-surface-bg — e.g. a scrim gradient. Default: none.",
+    "--sf-surface-bg-size": "background-size for the .sf-surface-bg image. Default: cover.",
+    "--sf-surface-bg-position": "background-position for the .sf-surface-bg image. Default: center.",
+    "--sf-surface-bg-repeat": "background-repeat for the .sf-surface-bg image. Default: no-repeat.",
+    "--sf-surface-bg-attachment": "background-attachment for the .sf-surface-bg image (scroll vs fixed). Default: scroll.",
+    "--sf-surface-bg-animation": "animation shorthand applied to the .sf-surface-bg layer, e.g. a slow pan. Default: none.",
+    "--sf-animation-slide-out-up": "Ready-made animation shorthand: slides the element out upward (sf-slide-out-up) at the normal duration with ease-in.",
+    "--sf-animation-slide-out-down": "Ready-made animation shorthand: slides the element out downward (sf-slide-out-down) at the normal duration with ease-in.",
+    "--sf-animation-slide-out-left": "Ready-made animation shorthand: slides the element out to the left (sf-slide-out-left) at the normal duration with ease-in.",
+    "--sf-animation-slide-out-right": "Ready-made animation shorthand: slides the element out to the right (sf-slide-out-right) at the normal duration with ease-in.",
+    "--sf-corner-scoop-size": "Cut radius of the .sf-corner-scoop mask. Default: var(--sf-radius-2xl).",
+    "--sf-corner-scoop-at": "Corner the .sf-corner-scoop mask cuts, as a radial-gradient origin (e.g. '100% 0' = top-right). Default: 100% 0.",
+    "--sf-scroll-timeline-range-exit-start": "Scroll-timeline range at which a scroll-out exit animation begins. Default: cover 70%.",
+    "--sf-scroll-timeline-range-exit-end": "Scroll-timeline range at which a scroll-out exit animation finishes. Default: exit 100%.",
+    "--sf-color-selection-bg--alt": "Alt selection background — the inverse-scheme highlight fill for surfaces that deliberately flip colour scheme (e.g. a dark hero in light mode).",
+    "--sf-color-selection-text--alt": "Alt selection text colour paired with --sf-color-selection-bg--alt; inherits by default so the underlying text colour shows through."
   },
   "classes": {
     "sf-btn": "Interactive call-to-action button. Apply to <button> or <a>. Intrinsic width by default; owns its own styling (excluded from the classless <button> look). Three orthogonal axes — colour family, style treatment (fill/--soft/--outline), gradient — plus a size modifier.",
@@ -1116,6 +1134,43 @@
     "sf-is-valid": "Valid state — applies success color tokens to form fields that have passed validation. Visual styling is identical to sf-is-success; the name signals form-field context.",
     "print-only": "Hides the element on screen (display: none) but shows it in @media print. Use for print-only headers, footers, and supplementary content not needed on screen.",
     "theme-transition": "Internal helper class used by the sf-theme-transition macro. Applies per-property transitions to registered color tokens during light/dark mode switches.",
-    "sf-bg-layer": "Background layer — absolutely-positioned cover media that sits behind a parent's content. The parent is auto-promoted to a positioned, isolated stacking context via :has(), so .sf-bg-layer composes natively under .sf-scrim (background → scrim gradient → content). Works as a bare <img class=\"sf-bg-layer\"> or as a wrapper with a nested > img / > video / > picture."
+    "sf-bg-layer": "Background layer — absolutely-positioned cover media that sits behind a parent's content. The parent is auto-promoted to a positioned, isolated stacking context via :has(), so .sf-bg-layer composes natively under .sf-scrim (background → scrim gradient → content). Works as a bare <img class=\"sf-bg-layer\"> or as a wrapper with a nested > img / > video / > picture.",
+    "sf-exit--fade": "Scroll-out exit animation: fades the element out in place (sf-fade-out).",
+    "sf-exit--fade-up": "Scroll-out exit animation: fades out while sliding upward (sf-slide-out-up).",
+    "sf-exit--fade-down": "Scroll-out exit animation: fades out while sliding downward (sf-slide-out-down).",
+    "sf-exit--fade-left": "Scroll-out exit animation: fades out while sliding to the left (sf-slide-out-left).",
+    "sf-exit--fade-right": "Scroll-out exit animation: fades out while sliding to the right (sf-slide-out-right).",
+    "sf-exit--scale-down": "Scroll-out exit animation: fades out while shrinking (sf-scale-down).",
+    "sf-corner-scoop": "Concave \"scooped\" corner cut with a radial-gradient mask; defaults to the top-right corner (--sf-corner-scoop-at). Add a placement modifier to move it.",
+    "sf-corner-scoop--top-left": "Places the concave corner scoop at the top-left corner.",
+    "sf-corner-scoop--top-right": "Places the concave corner scoop at the top-right corner.",
+    "sf-corner-scoop--bottom-left": "Places the concave corner scoop at the bottom-left corner.",
+    "sf-corner-scoop--bottom-right": "Places the concave corner scoop at the bottom-right corner.",
+    "sf-drop-shadow-xs": "Extra-small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xs).",
+    "sf-drop-shadow-s": "Small filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-s).",
+    "sf-drop-shadow-m": "Medium filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-m).",
+    "sf-drop-shadow-l": "Large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-l).",
+    "sf-drop-shadow-xl": "Extra-large filter drop-shadow — follows the element's alpha shape (--sf-drop-shadow-xl).",
+    "sf-header--xs": "Header block padding at the xs step (--sf-space-xs).",
+    "sf-header--s": "Header block padding at the s step (--sf-space-s).",
+    "sf-header--m": "Header block padding at the m step (--sf-space-m).",
+    "sf-header--l": "Header block padding at the l step (--sf-space-l).",
+    "sf-header--xl": "Header block padding at the xl step (--sf-space-xl).",
+    "sf-marker--primary": "Colours list ::markers with the primary brand colour.",
+    "sf-marker--secondary": "Colours list ::markers with the secondary brand colour.",
+    "sf-marker--tertiary": "Colours list ::markers with the tertiary brand colour.",
+    "sf-marker--action": "Colours list ::markers with the action colour.",
+    "sf-overlap": "Overlap recipe — pulls the element upward (negative block-start margin) so it overlaps the previous sibling by --sf-overlap-pull.",
+    "sf-overlap--down": "Overlap recipe — pulls following content up (negative block-end margin) so this element overlaps the sibling below it.",
+    "sf-overlap--start": "Overlap recipe — pulls the element toward the inline-start (negative inline-start margin) to overlap horizontally.",
+    "sf-overlap--end": "Overlap recipe — pulls the element toward the inline-end (negative inline-end margin) to overlap horizontally.",
+    "sf-sticky": "position: sticky pinned at the header-aware --sf-sticky-offset.",
+    "sf-sticky--s": "Sticky positioning with an extra small gap (--sf-space-s) above the header-aware offset.",
+    "sf-sticky--m": "Sticky positioning with an extra medium gap (--sf-space-m) above the header-aware offset.",
+    "sf-sticky--l": "Sticky positioning with an extra large gap (--sf-space-l) above the header-aware offset.",
+    "sf-divide": "Rules between direct children (a border on each child after the first), reusing .sf-divider's tokens — no per-gap markup needed.",
+    "sf-divide--vertical": "Vertical rules between direct children (inline-start borders), for row/horizontal layouts.",
+    "sf-theme-light": "Forces light colour scheme on the element and its subtree (class alias of [data-theme=\"light\"]).",
+    "sf-theme-dark": "Forces dark colour scheme on the element and its subtree (class alias of [data-theme=\"dark\"])."
   }
 }