From ca94eb7302e4e14fab7286867eb12a26ebe23ef5 Mon Sep 17 00:00:00 2001
From: Phil Scott <phil.scott@gmail.com>
Date: Sun, 12 Jul 2026 09:09:51 -0400
Subject: [PATCH] refactor(docs): fold brand CSS into MonorailCSS utility
 compositions

Split BrandStyling's declarative CSS into two forms by what each is good
at. The repetitive box-model + colour + .dark/:hover twin rules move into
a new `Applies` map (CssFrameworkSettings.Applies: selector -> utility
string, expanded into @layer components), folding each variant pair into
one dark:/hover: value. Program.cs wires it via CustomCssFrameworkSettings.
ExtraStyles keeps only the genuine residue: at-rules, pseudo-elements,
--beck-* token tables, and gnarly literals a utility wouldn't clarify.

The playground toolbar (PlaygroundIsland.razor) and the lightbox chrome
(site.js) move to utility classes directly on their elements; the
`.beck-lightbox` hook stays only for the ::backdrop / @starting-style /
cloned-svg sizing that utilities can't reach.

Pin MonorailCss 0.1.3 explicitly (Directory.Packages.props +
Beck.Docs.csproj) for the Applies bug fixes not yet flowed through
Pennington.
---
 Directory.Packages.props                     |   1 +
 docs/Beck.Docs.Client/PlaygroundIsland.razor |  95 ++++--
 docs/Beck.Docs/Beck.Docs.csproj              |   2 +
 docs/Beck.Docs/BrandStyling.cs               | 315 ++++++-------------
 docs/Beck.Docs/Program.cs                    |   6 +
 docs/Beck.Docs/wwwroot/js/site.js            |  10 +-
 6 files changed, 171 insertions(+), 258 deletions(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 5a4f5c9..420f18a 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -3,6 +3,7 @@
     <!-- Tag-driven versioning + source link for the shipping package. -->
     <PackageVersion Include="MinVer" Version="7.0.0" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <PackageVersion Include="MonorailCss" Version="0.1.3" />
   </ItemGroup>
   <ItemGroup>
     <!-- Pennington content engine, consumed from NuGet so the docs site builds on CI
diff --git a/docs/Beck.Docs.Client/PlaygroundIsland.razor b/docs/Beck.Docs.Client/PlaygroundIsland.razor
index afe6224..7aa3c02 100644
--- a/docs/Beck.Docs.Client/PlaygroundIsland.razor
+++ b/docs/Beck.Docs.Client/PlaygroundIsland.razor
@@ -13,26 +13,26 @@
     <div class="flex items-center gap-3 px-5 py-[9px] border-b border-base-200 dark:border-base-800 bg-base-50 dark:bg-base-900">
         @* Examples: a rich grouped dropdown. Open/close/select are component state; each
            item fetches its sample's YAML from the site's /examples over HttpClient. *@
-        <div id="pg-examples" class="pg-dd @(_open == Dd.Examples ? "is-open" : "")">
-            <button type="button" class="pg-dd-trigger" @onclick="ToggleExamples" @onkeydown="e => OnTriggerKey(e, Dd.Examples)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Examples)">
-                <span class="pg-dd-value">@_exampleLabel</span>
-                <svg class="pg-dd-caret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
+        <div id="pg-examples" class="group relative @(_open == Dd.Examples ? "is-open" : "")">
+            <button type="button" class="@DdTrigger" @onclick="ToggleExamples" @onkeydown="e => OnTriggerKey(e, Dd.Examples)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Examples)">
+                <span class="whitespace-nowrap">@_exampleLabel</span>
+                <svg class="@DdCaret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
             </button>
             @if (_open == Dd.Examples)
             {
-                <div class="pg-dd-panel" role="listbox" aria-label="Example diagrams">
+                <div class="@DdPanel left-0 min-w-[384px]" role="listbox" aria-label="Example diagrams">
                     @foreach (var group in ExampleGroups)
                     {
                         <div class="pg-dd-group">
-                            <div class="pg-dd-group-label">@group.Label</div>
+                            <div class="font-mono text-[10px] font-semibold tracking-[0.09em] uppercase text-base-400 pt-1 px-[11px] pb-2 dark:text-base-500">@group.Label</div>
                             @foreach (var ex in group.Items)
                             {
-                                <button type="button" class="pg-dd-item" role="option" @onclick="() => LoadExample(ex)" @onkeydown="e => OnOptionKey(e, Dd.Examples)">
-                                    <span class="pg-dd-item-main">
-                                        <span class="pg-dd-item-title">@ex.Label</span>
-                                        <span class="pg-dd-item-desc">@ex.Desc</span>
+                                <button type="button" class="@DdItem gap-[14px] py-[9px]" role="option" @onclick="() => LoadExample(ex)" @onkeydown="e => OnOptionKey(e, Dd.Examples)">
+                                    <span class="@DdItemMain">
+                                        <span class="@DdItemTitle">@ex.Label</span>
+                                        <span class="@DdItemDesc">@ex.Desc</span>
                                     </span>
-                                    <span class="pg-pill" data-type="@group.Type">@group.Glyph @group.Short</span>
+                                    <span class="pg-pill flex-none font-mono text-[10px] font-semibold px-2 py-[3px] rounded-full whitespace-nowrap border border-transparent" data-type="@group.Type">@group.Glyph @group.Short</span>
                                 </button>
                             }
                         </div>
@@ -45,22 +45,22 @@
            meta.style still wins — the documented precedence — so this is a default, not an
            override; the panel hints as much. Classic is first and is the default. Changing it
            rebuilds the options and re-renders. *@
-        <div id="pg-style" class="pg-dd ml-auto @(_open == Dd.Style ? "is-open" : "")">
-            <button type="button" class="pg-dd-trigger" @onclick="ToggleStyle" @onkeydown="e => OnTriggerKey(e, Dd.Style)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Style)" title="Default style — a diagram's meta.style overrides">
-                <span class="pg-dd-trigger-label">Style</span>
-                <span class="pg-dd-value">@_styleLabel</span>
-                <svg class="pg-dd-caret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
+        <div id="pg-style" class="group relative ml-auto @(_open == Dd.Style ? "is-open" : "")">
+            <button type="button" class="@DdTrigger" @onclick="ToggleStyle" @onkeydown="e => OnTriggerKey(e, Dd.Style)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Style)" title="Default style — a diagram's meta.style overrides">
+                <span class="font-medium text-base-400 dark:text-base-500">Style</span>
+                <span class="whitespace-nowrap">@_styleLabel</span>
+                <svg class="@DdCaret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
             </button>
             @if (_open == Dd.Style)
             {
-                <div class="pg-dd-panel pg-dd-panel--right" role="listbox" aria-label="Diagram style">
-                    <div class="pg-dd-note">Default style — a diagram's <code>meta.style</code> overrides.</div>
+                <div class="@DdPanel right-0 min-w-[216px]" role="listbox" aria-label="Diagram style">
+                    <div class="text-[11.5px] leading-[1.45] text-base-500 pt-[6px] px-3 pb-2 mb-1 border-b border-base-100 dark:text-base-400 dark:border-base-800">Default style — a diagram's <code class="font-mono text-[11px]">meta.style</code> overrides.</div>
                     @foreach (var st in Styles)
                     {
-                        <button type="button" class="pg-dd-item pg-dd-item--scheme" role="option" aria-selected="@(_styleName == st.Name)" @onclick="() => SelectStyle(st)" @onkeydown="e => OnOptionKey(e, Dd.Style)">
-                            <span class="pg-dd-item-main">
-                                <span class="pg-dd-item-title">@st.Label</span>
-                                <span class="pg-dd-item-desc">@st.Desc</span>
+                        <button type="button" class="@DdSchemeItem" role="option" aria-selected="@(_styleName == st.Name ? "true" : "false")" @onclick="() => SelectStyle(st)" @onkeydown="e => OnOptionKey(e, Dd.Style)">
+                            <span class="@DdItemMain">
+                                <span class="@DdItemTitle">@st.Label</span>
+                                <span class="@DdItemDesc">@st.Desc</span>
                             </span>
                         </button>
                     }
@@ -71,20 +71,20 @@
         @* Colour scheme: recolours the live diagram by overriding its --beck-* tokens
            on #pg-host[data-scheme] (see BrandStyling). Pure CSS — setting the attribute is
            enough, no re-render. "Default" keeps the site palette and the light/dark toggle. *@
-        <div id="pg-scheme" class="pg-dd @(_open == Dd.Scheme ? "is-open" : "")">
-            <button type="button" class="pg-dd-trigger" @onclick="ToggleScheme" @onkeydown="e => OnTriggerKey(e, Dd.Scheme)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Scheme)">
-                <span class="pg-swatch" data-scheme="@_scheme"></span>
-                <span class="pg-dd-value">@_schemeLabel</span>
-                <svg class="pg-dd-caret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
+        <div id="pg-scheme" class="group relative @(_open == Dd.Scheme ? "is-open" : "")">
+            <button type="button" class="@DdTrigger" @onclick="ToggleScheme" @onkeydown="e => OnTriggerKey(e, Dd.Scheme)" aria-haspopup="listbox" aria-expanded="@(_open == Dd.Scheme)">
+                <span class="@DdSwatch" data-scheme="@_scheme"></span>
+                <span class="whitespace-nowrap">@_schemeLabel</span>
+                <svg class="@DdCaret" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"></polyline></svg>
             </button>
             @if (_open == Dd.Scheme)
             {
-                <div class="pg-dd-panel pg-dd-panel--right" role="listbox" aria-label="Colour scheme">
+                <div class="@DdPanel right-0 min-w-[216px]" role="listbox" aria-label="Colour scheme">
                     @foreach (var s in Schemes)
                     {
-                        <button type="button" class="pg-dd-item pg-dd-item--scheme" role="option" aria-selected="@(_scheme == s.Value)" @onclick="() => SelectScheme(s)" @onkeydown="e => OnOptionKey(e, Dd.Scheme)">
-                            <span class="pg-swatch" data-scheme="@s.Value"></span>
-                            <span class="pg-dd-item-title">@s.Label</span>
+                        <button type="button" class="@DdSchemeItem" role="option" aria-selected="@(_scheme == s.Value ? "true" : "false")" @onclick="() => SelectScheme(s)" @onkeydown="e => OnOptionKey(e, Dd.Scheme)">
+                            <span class="@DdSwatch" data-scheme="@s.Value"></span>
+                            <span class="@DdItemTitle">@s.Label</span>
                         </button>
                     }
                 </div>
@@ -96,7 +96,7 @@
        it. Sits below the panel (z-index) so panel items stay clickable. *@
     @if (_open != Dd.None)
     {
-        <div class="pg-dd-backdrop" @onclick="CloseDropdowns"></div>
+        <div class="fixed inset-0 z-30" @onclick="CloseDropdowns"></div>
     }
 
     <div id="pg-panes" class="flex-1 grid grid-cols-2 min-h-0 max-md:grid-cols-1 max-md:grid-rows-2">
@@ -174,6 +174,37 @@
     private string _styleName = BeckStyle.Classic.Name;
     private string _styleLabel = "Classic";
 
+    // ---- toolbar dropdown utility classes -----------------------------------
+    // The dropdowns are Tailwind utilities directly on the elements (MonorailCSS scans this
+    // component's compiled IL). Only strings that repeat verbatim across the three identical
+    // dropdowns are named here; one-offs stay inline in the markup above. `pg-dd-trigger` /
+    // `pg-dd-item` survive only as hooks for beck-editor.js's querySelectors; `pg-pill` /
+    // `pg-swatch` as hooks for the per-type/scheme colour tables in BrandStyling. State rides
+    // attributes Blazor already sets: aria-expanded: (open-trigger ring), group-[.is-open]:
+    // (caret flip), aria-selected: (chosen style/scheme).
+    private const string DdTrigger =
+        "pg-dd-trigger inline-flex items-center gap-2 leading-none text-[13px] font-medium cursor-pointer " +
+        "text-base-700 bg-white border border-base-300 rounded-lg px-[11px] py-[7px] " +
+        "transition-[border-color,background-color,box-shadow] duration-150 hover:border-base-400 " +
+        "dark:text-base-300 dark:bg-base-900 dark:border-base-700 dark:hover:border-base-600 " +
+        // Open-state ring rides the wrapper's .is-open (Blazor renders aria-expanded as a
+        // minimized boolean attribute — ="" not ="true" — so an aria-expanded: variant can't match).
+        "group-[.is-open]:border-primary-500 group-[.is-open]:shadow-[0_0_0_3px_color-mix(in_srgb,var(--color-primary-500)_20%,transparent)]";
+    private const string DdCaret = "w-[13px] h-[13px] opacity-50 [transition:transform_0.18s_ease] group-[.is-open]:rotate-180";
+    private const string DdPanel =
+        "absolute top-[calc(100%+7px)] z-40 max-h-[min(66vh,560px)] overflow-y-auto bg-white border border-base-200 " +
+        "rounded-[13px] p-2 shadow-[0_12px_34px_-10px_rgb(0_0_0_/_0.28),0_3px_10px_-3px_rgb(0_0_0_/_0.12)] " +
+        "dark:bg-base-900 dark:border-base-700 dark:shadow-[0_14px_40px_-10px_rgb(0_0_0_/_0.7)]";
+    private const string DdItem =
+        "pg-dd-item flex items-center w-full text-left cursor-pointer bg-transparent border-0 rounded-[9px] px-3 " +
+        "text-base-800 hover:bg-base-100 dark:text-base-100 dark:hover:bg-base-800";
+    private const string DdSchemeItem = DdItem +
+        " gap-[10px] py-2 aria-selected:bg-primary-50 dark:aria-selected:bg-[color-mix(in_srgb,var(--color-primary-950)_45%,transparent)]";
+    private const string DdItemMain = "flex flex-col gap-[3px] min-w-0 flex-auto";
+    private const string DdItemTitle = "text-[13px] font-medium truncate";
+    private const string DdItemDesc = "text-[11.5px] leading-[1.4] text-base-500 truncate dark:text-base-400";
+    private const string DdSwatch = "pg-swatch flex-none w-[15px] h-[15px] rounded border border-[rgb(0_0_0_/_0.18)] dark:border-[rgb(255_255_255_/_0.22)]";
+
     // Ask for the site's IBM Plex families (rewrites --beck-font); glyphs are measured in the
     // browser via canvas measureText (CanvasTextMeasurer), so card sizing matches exactly what
     // the browser draws. Measurer is wired up on the first client render (below).
diff --git a/docs/Beck.Docs/Beck.Docs.csproj b/docs/Beck.Docs/Beck.Docs.csproj
index d301863..00a9f1d 100644
--- a/docs/Beck.Docs/Beck.Docs.csproj
+++ b/docs/Beck.Docs/Beck.Docs.csproj
@@ -36,6 +36,8 @@
   </ItemGroup>
 
   <ItemGroup>
+    <!-- Explicitly use the latest version here, it has some bug fixes that we want that aren't in Pennington yet -->
+    <PackageReference Include="MonorailCss" />
     <!-- Pennington content engine, from NuGet so the site builds on CI without a local
          b:\penn checkout. Versions are pinned centrally in Directory.Packages.props.
          - Pennington            : bare content host (markdown pipeline, RunOrBuildAsync).
diff --git a/docs/Beck.Docs/BrandStyling.cs b/docs/Beck.Docs/BrandStyling.cs
index 739fe39..b52bbf8 100644
--- a/docs/Beck.Docs/BrandStyling.cs
+++ b/docs/Beck.Docs/BrandStyling.cs
@@ -1,30 +1,80 @@
 namespace Beck.Docs;
 
 /// <summary>
-/// Raw CSS appended to the generated <c>/styles.css</c> via
-/// <c>MonorailCssOptions.ExtraStyles</c>. Everything here is something MonorailCSS's
-/// utility/discovery pipeline can't (or shouldn't) produce:
+/// Brand CSS fed to MonorailCSS in two forms, split by what each form is actually good at.
 /// <list type="bullet">
-///   <item>the IBM Plex font wiring (<c>--font-sans</c> / <c>--font-mono</c>);</item>
-///   <item>the signature dot-grid surface (<c>.dot-grid</c>) reused by every diagram frame;</item>
-///   <item>syntax tokens for the <b>hand-authored</b> code snippets in the hero/API pages
-///         (Markdig fences are colored by <c>SyntaxTheme</c> instead);</item>
-///   <item>framing for the <c>.beck-embed</c> wrapper the build-time fence renderer and
-///         <c>&lt;BeckDiagram&gt;</c> emit around each SVG — it lives in rendered markdown, so
-///         it stays declarative CSS rather than utility classes;</item>
-///   <item>playground elements created or class-toggled by <c>site.js</c>: the runtime
-///         IL scan that discovers utility classes never sees a class that only exists in a
-///         JavaScript string, so those stay declarative CSS.</item>
+///   <item><see cref="Applies"/> — component classes expressed as <b>utility compositions</b>
+///     (MonorailCSS's <c>CssFrameworkSettings.Applies</c>: selector → space-separated utilities,
+///     expanded into <c>@layer components</c> at build). This is where the repetitive box-model +
+///     colour + <c>.dark</c>/<c>:hover</c> twin CSS lived; folding the variants into one
+///     <c>dark:</c>/<c>hover:</c> value each is the whole point. <c>Applies</c> emits by explicit
+///     selector, so a class being referenced only from a JS string (or from server Razor) is
+///     irrelevant — no IL/utility discovery is involved.</item>
+///   <item><see cref="ExtraStyles"/> — the residue that genuinely isn't utility-shaped: at-rules
+///     (<c>@keyframes</c>, <c>@starting-style</c>, <c>@media</c>), pseudo-elements
+///     (<c>::backdrop</c>, <c>::-webkit-scrollbar</c>), custom-property token assignments (the
+///     <c>--beck-*</c> accent remap and the named colour schemes), and gnarly literals a utility
+///     wouldn't clarify (the dot-grid radial-gradient, the <c>[data-type]</c>/<c>[data-scheme]</c>
+///     colour tables, <c>color-mix</c> scrims).</item>
 /// </list>
-/// All colors resolve from the palette variables MonorailCSS emits for the mapped
-/// primary/accent/base slots (and flip under <c>.dark</c>), so this CSS themes itself.
+/// Both resolve from the palette variables MonorailCSS emits for the mapped primary/accent/base
+/// slots (and flip under <c>.dark</c>), so this CSS themes itself.
+///
+/// <para><b>Cascade note.</b> <see cref="ExtraStyles"/> is appended <i>unlayered</i> (it wins over
+/// every <c>@layer</c>), whereas <see cref="Applies"/> lands in <c>@layer components</c> (which
+/// utilities beat). That only matters if an element carried both a class below and a utility
+/// touching the same property — none do: every consumer (playground dropdowns, syntax chips, API
+/// nav, icon cards) uses these classes in isolation, at most with a state class like
+/// <c>is-active</c>.</para>
 /// </summary>
 internal static class BrandStyling
 {
+    /// <summary>
+    /// Component classes as utility compositions, merged into <c>CssFrameworkSettings.Applies</c>.
+    /// Keys are full CSS selectors (compound/descendant/sibling/attribute selectors all emit as
+    /// written); values are MonorailCSS utility strings with <c>dark:</c>/<c>hover:</c> variants
+    /// folded in. <c>font: inherit</c> is dropped throughout — preflight already resets it on
+    /// <c>button</c>/<c>input</c>/<c>select</c>.
+    /// </summary>
+    public static readonly IReadOnlyDictionary<string, string> Applies = new Dictionary<string, string>
+    {
+        // ---- hand-authored code-sample syntax tokens (hero + API pages) ----
+        [".tok-key"]    = "text-primary-700 dark:text-primary-400",
+        [".tok-accent"] = "text-primary-700 dark:text-primary-400",
+        [".tok-punct"]  = "text-base-400 dark:text-base-500",
+        [".tok-str"]    = "text-[#b45309] dark:text-[#e0b341]",
+
+        // ---- lazy style-gallery slots ----
+        [".beck-lazy"]           = "grid place-items-center min-h-[680px] border border-dashed border-base-200 rounded-xl mb-6 dark:border-base-800",
+        [".beck-lazy > a"]       = "text-[0.85rem] text-base-500",
+        [".beck-lazy.is-loaded"] = "block min-h-0 border-0 m-0",
+
+        // NB: the playground toolbar (the .pg-dd* dropdowns, .pg-pill, .pg-swatch) is styled with
+        // utilities directly on the elements in Beck.Docs.Client/PlaygroundIsland.razor — not here.
+        // Only the adjacent-sibling separators and the per-type/scheme colour tables remain as
+        // declarative rules in ExtraStyles (keyed off the .pg-dd-group/.pg-pill/.pg-swatch hooks).
+
+        // ---- syntax cheatsheet: filter chips ----
+        [".syntax-chip"]           = "font-medium text-[13px] px-[14px] py-[6px] rounded-full cursor-pointer bg-white text-base-600 border border-base-300 transition-[background-color,color,border-color] duration-150 hover:border-base-400 hover:text-base-900 dark:bg-base-900 dark:text-base-400 dark:border-base-700 dark:hover:border-base-600 dark:hover:text-base-50",
+        [".syntax-chip.is-active"] = "bg-primary-600 border-primary-600 text-white dark:bg-primary-500 dark:border-primary-500",
+
+        // ---- API reference sidebar links (scroll-spy state toggled by site.js) ----
+        [".api-nav-link"]           = "block w-full text-left font-mono text-[13px] px-[10px] py-[6px] rounded-md no-underline text-base-600 transition-colors duration-150 hover:bg-base-50 hover:text-base-900 dark:text-base-400 dark:hover:bg-base-900 dark:hover:text-base-50",
+        [".api-nav-link.is-active"] = "bg-primary-50 text-primary-700 dark:bg-[color-mix(in_srgb,var(--color-primary-950)_40%,transparent)] dark:text-primary-400",
+
+        // ---- icon reference gallery (server-rendered by <IconGallery />) ----
+        ["[data-beck-icon-gallery]"]  = "grid grid-cols-[repeat(auto-fill,minmax(128px,1fr))] gap-3",
+        [".beck-icon-card"]           = "flex flex-col items-center gap-2 px-[10px] py-4 text-center border border-base-200 rounded-xl bg-white dark:border-base-800 dark:bg-base-900",
+        // Distinct from the SVG-internal `.beck-icon-chip` <rect> the engine emits.
+        [".beck-icon-card-chip"]      = "flex items-center justify-center w-10 h-10 rounded-[10px] bg-[color-mix(in_srgb,var(--color-primary-600)_12%,var(--color-base-100))] text-primary-700 dark:bg-[color-mix(in_srgb,var(--color-primary-500)_18%,var(--color-base-800))] dark:text-primary-400",
+        [".beck-icon-card-chip svg"]  = "w-[22px] h-[22px]",
+        [".beck-icon-key"]            = "font-mono text-[12.5px] text-base-900 dark:text-base-50",
+        [".beck-icon-aliases"]        = "font-mono text-[10.5px] leading-[1.4] text-base-400 break-words dark:text-base-500",
+    };
+
+    // lang=css
     public const string ExtraStyles = """
-        /* ---- reset safety net (harmless if MonorailCSS preflight already does it) ---- */
-        *, *::before, *::after { box-sizing: border-box; }
-        body { margin: 0; }
+        /* ---- scroll offset for the sticky nav (box-sizing + margin reset come from preflight) ---- */
         html { scroll-padding-top: 5rem; }
 
         /* ---- fonts: IBM Plex is part of the brand identity ---- */
@@ -45,16 +95,6 @@ .dark .dot-grid {
           background-image: radial-gradient(var(--color-base-800) 1px, transparent 1px);
         }
 
-        /* ---- hand-authored code-sample syntax tokens (hero + API pages) ---- */
-        .tok-key    { color: var(--color-primary-700); }
-        .tok-accent { color: var(--color-primary-700); }
-        .tok-punct  { color: var(--color-base-400); }
-        .tok-str    { color: #b45309; }
-        .dark .tok-key    { color: var(--color-primary-400); }
-        .dark .tok-accent { color: var(--color-primary-400); }
-        .dark .tok-punct  { color: var(--color-base-500); }
-        .dark .tok-str    { color: #e0b341; }
-
         /* ---- Beck embeds ---- */
         /* A rendered ```beck fence becomes <div class="beck-embed"><svg …>; frame it on the
            dot-grid surface so every live diagram reads as a framed preview. */
@@ -96,29 +136,10 @@ would repaint a solid panel over the host's dots in dark mode. */
           border: 0; background: none; padding: 0; margin: 0; min-height: 0;
         }
 
-        /* ---- lazy style-gallery slots ---- */
-        /* The styles guide holds one .beck-lazy placeholder per style; site.js fetches the
-           build-baked fragment (three .beck-embed diagrams) as it scrolls near and injects
-           it. Until then the slot reserves roughly one gallery's height (three ~200px
-           embeds + gaps) so late loads don't yank the scroll position, showing the no-JS
-           fallback link centred on the embed dot-grid frame. Once loaded, the slot
-           collapses to its injected content. */
-        .beck-lazy {
-          display: grid; place-items: center;
-          min-height: 680px;
-          border: 1px dashed var(--color-base-200); border-radius: 12px;
-          margin: 0 0 24px;
-        }
-        .dark .beck-lazy { border-color: var(--color-base-800); }
-        .beck-lazy > a { font-size: 0.85rem; color: var(--color-base-500); }
-        .beck-lazy.is-loaded {
-          display: block; min-height: 0; border: 0; margin: 0;
-        }
-
         /* ---- diagram fullscreen zoom ---- */
         /* BeckSvgPreprocessor emits the .beck-zoom button into each embed; site.js opens the
-           .beck-lightbox <dialog>. Both exist only in C#/JS strings, so they stay declarative.
-           The button fades in on embed hover (always visible on touch, where there is no hover). */
+           .beck-lightbox <dialog>. The button fades in on embed hover (always visible on touch,
+           where there is no hover). Kept declarative for the color-mix scrim + hover chain. */
         .beck-zoom {
           position: absolute; right: 10px; bottom: 10px;
           display: flex; align-items: center; justify-content: center;
@@ -138,17 +159,12 @@ .dark .beck-zoom {
         .dark .beck-zoom:hover { color: var(--color-base-50); border-color: var(--color-base-600); }
         @media (hover: none) { .beck-zoom { opacity: 1; } }
 
-        /* The lightbox: a transparent full-viewport dialog whose ::backdrop dims and blurs the
-           page. The cloned SVG renders at its natural size (its width/height attributes), only
-           scaling DOWN when it exceeds the viewport — never up, which made small diagrams look
-           comically large. In-page embeds constrain diagrams to the article column, so natural
-           size is still a real zoom for anything sizable. */
-        .beck-lightbox {
-          border: 0; padding: 0; margin: auto; background: transparent;
-          width: 100vw; height: 100vh; max-width: 100vw; max-height: 100vh;
-          overflow: hidden; cursor: zoom-out;
-        }
-        .beck-lightbox[open] { display: flex; align-items: center; justify-content: center; }
+        /* The lightbox: a transparent full-viewport <dialog> whose ::backdrop dims and blurs
+           the page. site.js builds the dialog (its box is utility classes there) and keys it
+           `.beck-lightbox` purely as the hook for what utilities can't reach — the ::backdrop,
+           its @starting-style entrance, and the cloned SVG's sizing below. The cloned SVG
+           renders at its natural size (its width/height attributes), only scaling DOWN when it
+           exceeds the viewport — never up, which made small diagrams look comically large. */
         /* The page behind goes blurred, washed out, and sunk into the app surface, so the
            diagram is the only saturated thing on screen. The scrim can't say
            `var(--beck-surface)`: that token is declared on the per-diagram `.b-{hash}` scope
@@ -181,15 +197,7 @@ the scrim read as the page receding rather than a black wash.
           .beck-lightbox::backdrop { transition: none; }
         }
         .beck-lightbox .beck-svg { width: auto; height: auto; max-width: 94vw; max-height: 90vh; }
-        .beck-lightbox-close {
-          position: fixed; top: 18px; right: 18px;
-          display: flex; align-items: center; justify-content: center;
-          width: 38px; height: 38px; padding: 0; cursor: pointer;
-          border: 1px solid rgb(255 255 255 / 0.25); border-radius: 9999px;
-          background: rgb(0 0 0 / 0.35); color: #fff;
-          transition: background-color .15s;
-        }
-        .beck-lightbox-close:hover { background: rgb(0 0 0 / 0.55); }
+        /* (The lightbox close button is fully utility-styled in site.js — no rule here.) */
 
         /* ---- Beck accent remap: differentiate from the emerald brand ---- */
         /* The engine maps `success`->emerald and `info`->violet. On this emerald-branded
@@ -206,8 +214,6 @@ body .beck-root {
         }
 
         /* ---- playground: elements created / class-toggled by site.js ---- */
-        /* IL discovery can't see classes that exist only inside a JS string, so these
-           stay declarative CSS rather than utilities. */
         /* Auto margins center the rendered diagram in the preview pane but collapse
            to the top when it's taller than the pane, so the title stays scrollable
            (align-items:center would center-clip it above an unreachable scroll origin). */
@@ -219,86 +225,20 @@ stay declarative CSS rather than utilities. */
         #pg-status.ok  { color: var(--color-primary-600); }
         #pg-status.err { color: #e6685b; }
 
-        /* ---- playground toolbar: custom dropdowns (examples + colour scheme) ---- */
-        /* The controls are SSR markup wired by site.js (wireDropdown). Structure +
-           colour live here because the classes are shared across the trigger/panel/
-           items and several are toggled from JS (is-open / is-active). */
-        .pg-dd { position: relative; }
-        .pg-dd-trigger {
-          display: inline-flex; align-items: center; gap: 8px; line-height: 1;
-          font: inherit; font-size: 13px; font-weight: 500; cursor: pointer;
-          color: var(--color-base-700); background: #fff;
-          border: 1px solid var(--color-base-300); border-radius: 8px; padding: 7px 11px;
-          transition: border-color .15s, background-color .15s, box-shadow .15s;
-        }
-        .dark .pg-dd-trigger { color: var(--color-base-300); background: var(--color-base-900); border-color: var(--color-base-700); }
-        .pg-dd-trigger:hover { border-color: var(--color-base-400); }
-        .dark .pg-dd-trigger:hover { border-color: var(--color-base-600); }
-        .pg-dd.is-open .pg-dd-trigger { border-color: var(--color-primary-500); box-shadow: 0 0 0 3px color-mix(in srgb, var(--color-primary-500) 20%, transparent); }
-        .pg-dd-value { white-space: nowrap; }
-        /* Dimmed lead-in label inside a trigger (e.g. "Style  Classic") so the value reads
-           as the selection while the control still says what it controls. */
-        .pg-dd-trigger-label { font-weight: 500; color: var(--color-base-400); }
-        .dark .pg-dd-trigger-label { color: var(--color-base-500); }
-        /* Hint line at the top of a panel (the style dropdown's precedence note). */
-        .pg-dd-note {
-          font-size: 11.5px; line-height: 1.45; color: var(--color-base-500);
-          padding: 6px 12px 8px; margin-bottom: 4px;
-          border-bottom: 1px solid var(--color-base-100);
-        }
-        .dark .pg-dd-note { color: var(--color-base-400); border-bottom-color: var(--color-base-800); }
-        .pg-dd-note code { font-family: var(--font-mono); font-size: 11px; }
-        .pg-dd-caret { width: 13px; height: 13px; opacity: .5; transition: transform .18s ease; }
-        .pg-dd.is-open .pg-dd-caret { transform: rotate(180deg); }
-
-        .pg-dd-panel {
-          position: absolute; top: calc(100% + 7px); left: 0; z-index: 40;
-          min-width: 384px; max-height: min(66vh, 560px); overflow-y: auto;
-          background: #fff; border: 1px solid var(--color-base-200);
-          border-radius: 13px; padding: 8px;
-          box-shadow: 0 12px 34px -10px rgb(0 0 0 / .28), 0 3px 10px -3px rgb(0 0 0 / .12);
-        }
-        .dark .pg-dd-panel { background: var(--color-base-900); border-color: var(--color-base-700); box-shadow: 0 14px 40px -10px rgb(0 0 0 / .7); }
-        .pg-dd-panel--right { left: auto; right: 0; min-width: 216px; }
-        /* Click-catcher behind an open panel (z-index 30 < panel's 40) so an outside
-           click closes the dropdown while its items stay clickable. */
-        .pg-dd-backdrop { position: fixed; inset: 0; z-index: 30; }
-
+        /* ---- playground dropdown: adjacent-sibling separators ---- */
+        /* The dropdown boxes are utilities on the elements (PlaygroundIsland.razor); these are
+           the sibling-combinator bits utilities can't express — the divider between example
+           groups and the 2px gap between options. `.pg-dd-group`/`.pg-dd-item` survive as the
+           hooks (also used by beck-editor.js). */
         .pg-dd-group { padding: 2px 0; }
         .pg-dd-group + .pg-dd-group { margin-top: 6px; border-top: 1px solid var(--color-base-100); padding-top: 8px; }
         .dark .pg-dd-group + .pg-dd-group { border-top-color: var(--color-base-800); }
-        .pg-dd-group-label {
-          font-family: var(--font-mono); font-size: 10px; font-weight: 600;
-          letter-spacing: .09em; text-transform: uppercase; color: var(--color-base-400);
-          padding: 4px 11px 8px;
-        }
-        .dark .pg-dd-group-label { color: var(--color-base-500); }
-
-        .pg-dd-item {
-          display: flex; align-items: center; gap: 14px; width: 100%;
-          text-align: left; font: inherit; cursor: pointer;
-          background: none; border: 0; border-radius: 9px; padding: 9px 12px;
-          color: var(--color-base-800);
-        }
         .pg-dd-item + .pg-dd-item { margin-top: 2px; }
-        .dark .pg-dd-item { color: var(--color-base-100); }
-        .pg-dd-item.is-active, .pg-dd-item:hover { background: var(--color-base-100); }
-        .dark .pg-dd-item.is-active, .dark .pg-dd-item:hover { background: var(--color-base-800); }
-        .pg-dd-item[aria-selected="true"] { background: var(--color-primary-50); }
-        .dark .pg-dd-item[aria-selected="true"] { background: color-mix(in srgb, var(--color-primary-950) 45%, transparent); }
-        .pg-dd-item--scheme { gap: 10px; padding: 8px 12px; }
-        .pg-dd-item-main { display: flex; flex-direction: column; gap: 3px; min-width: 0; flex: 1 1 auto; }
-        .pg-dd-item-title { font-size: 13px; font-weight: 500; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-        .pg-dd-item-desc { font-size: 11.5px; line-height: 1.4; color: var(--color-base-500); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-        .dark .pg-dd-item-desc { color: var(--color-base-400); }
 
-        /* Type pill: colour-coded per diagram type, literal fallbacks so it renders
-           even for ramps MonorailCSS doesn't emit (violet/amber aren't always used). */
-        .pg-pill {
-          flex: none; font-family: var(--font-mono); font-size: 10px; font-weight: 600;
-          padding: 3px 8px; border-radius: 999px; white-space: nowrap;
-          border: 1px solid transparent;
-        }
+        /* ---- playground type pill: colour-coded per diagram type ---- */
+        /* The `.pg-pill` base box is utilities in PlaygroundIsland.razor; these are the per-type
+           colour tables — literal fallbacks so a pill renders even for ramps MonorailCSS doesn't
+           emit (violet/amber aren't always used). */
         .pg-pill[data-type="architecture"] { color: var(--color-emerald-700, #047857); background: color-mix(in srgb, var(--color-emerald-500, #10b981) 14%, transparent); border-color: color-mix(in srgb, var(--color-emerald-500, #10b981) 30%, transparent); }
         .pg-pill[data-type="sequence"]     { color: var(--color-sky-700, #0369a1);     background: color-mix(in srgb, var(--color-sky-500, #0ea5e9) 14%, transparent);     border-color: color-mix(in srgb, var(--color-sky-500, #0ea5e9) 30%, transparent); }
         .pg-pill[data-type="state"]        { color: #b45309;                            background: color-mix(in srgb, #f59e0b 16%, transparent);                            border-color: color-mix(in srgb, #f59e0b 32%, transparent); }
@@ -314,9 +254,9 @@ items and several are toggled from JS (is-open / is-active). */
         .dark .pg-pill[data-type="mindmap"]      { color: #fda4af; }
         .dark .pg-pill[data-type="chart"]        { color: #67e8f9; }
 
-        /* Colour-scheme swatch: a two-tone chip previewing each palette's signature. */
-        .pg-swatch { flex: none; width: 15px; height: 15px; border-radius: 4px; border: 1px solid rgb(0 0 0 / .18); }
-        .dark .pg-swatch { border-color: rgb(255 255 255 / .22); }
+        /* ---- playground colour-scheme swatch: per-scheme two-tone chips ---- */
+        /* The `.pg-swatch` base box is utilities in PlaygroundIsland.razor; these paint each
+           palette's signature. */
         .pg-swatch[data-scheme="default"]  { background: linear-gradient(135deg, var(--color-primary-400, #34d399), var(--color-primary-700, #047857)); }
         .pg-swatch[data-scheme="monokai"]  { background: linear-gradient(135deg, #f92672 0 50%, #a6e22e 50% 100%); }
         .pg-swatch[data-scheme="one-dark"] { background: linear-gradient(135deg, #61afef 0 50%, #c678dd 50% 100%); }
@@ -377,29 +317,6 @@ land on the light preview pane. */
         @keyframes beck-caret-blink { 50% { opacity: 0; } }
         #hero-host .beck-root { max-width: 100%; }
 
-        /* ---- syntax cheatsheet: filter chips (class-toggled by site.js) ---- */
-        /* site.js swaps `.is-active` between chips; declarative so the toggle never
-           depends on IL-discovered utility classes that live only in a JS string. */
-        .syntax-chip {
-          font: inherit; font-weight: 500; font-size: 13px;
-          padding: 6px 14px; border-radius: 9999px; cursor: pointer;
-          background: #fff; color: var(--color-base-600);
-          border: 1px solid var(--color-base-300);
-          transition: background-color .15s, color .15s, border-color .15s;
-        }
-        .dark .syntax-chip {
-          background: var(--color-base-900); color: var(--color-base-400);
-          border-color: var(--color-base-700);
-        }
-        .syntax-chip:hover { border-color: var(--color-base-400); color: var(--color-base-900); }
-        .dark .syntax-chip:hover { border-color: var(--color-base-600); color: var(--color-base-50); }
-        .syntax-chip.is-active {
-          background: var(--color-primary-600); border-color: var(--color-primary-600); color: #fff;
-        }
-        .dark .syntax-chip.is-active {
-          background: var(--color-primary-500); border-color: var(--color-primary-500); color: #fff;
-        }
-
         /* ---- syntax cheatsheet: live-diagram canvas ---- */
         /* Each card renders its diagram server-side via <BeckDiagram> into a .beck-embed.
            Strip the fence's framed-preview chrome so the diagram sits directly on the
@@ -408,59 +325,9 @@ Strip the fence's framed-preview chrome so the diagram sits directly on the
           border: 0; background: none; padding: 0; margin: 0; min-height: 0; width: 100%;
         }
 
-        /* ---- icon reference gallery ---- */
-        /* The <IconGallery /> component renders these cards server-side from the C# engine's
-           icon registry (BeckSvg.IconRegistry). The chip echoes a node's accent-tinted icon
-           chip, in brand primary. */
-        [data-beck-icon-gallery] {
-          display: grid;
-          grid-template-columns: repeat(auto-fill, minmax(128px, 1fr));
-          gap: 12px;
-        }
-        .beck-icon-card {
-          display: flex; flex-direction: column; align-items: center; gap: 8px;
-          padding: 16px 10px; text-align: center;
-          border: 1px solid var(--color-base-200); border-radius: 12px; background: #fff;
-        }
-        .dark .beck-icon-card { border-color: var(--color-base-800); background: var(--color-base-900); }
-        /* NB: distinct from the SVG-internal `.beck-icon-chip` <rect> the engine emits — reusing
-           that exact name here would leak width/height onto every rendered node's chip. */
-        .beck-icon-card-chip {
-          display: flex; align-items: center; justify-content: center;
-          width: 40px; height: 40px; border-radius: 10px;
-          background: color-mix(in srgb, var(--color-primary-600) 12%, var(--color-base-100));
-          color: var(--color-primary-700);
-        }
-        .dark .beck-icon-card-chip {
-          background: color-mix(in srgb, var(--color-primary-500) 18%, var(--color-base-800));
-          color: var(--color-primary-400);
-        }
-        .beck-icon-card-chip svg { width: 22px; height: 22px; }
-        .beck-icon-key { font-family: var(--font-mono); font-size: 12.5px; color: var(--color-base-900); }
-        .dark .beck-icon-key { color: var(--color-base-50); }
-        .beck-icon-aliases { font-family: var(--font-mono); font-size: 10.5px; line-height: 1.4; color: var(--color-base-400); word-break: break-word; }
-        .dark .beck-icon-aliases { color: var(--color-base-500); }
-
-        /* ---- API reference sidebar links (scroll-spy class-toggled by site.js) ---- */
-        .api-nav-link {
-          display: block; width: 100%; text-align: left;
-          font-family: var(--font-mono); font-size: 13px;
-          padding: 6px 10px; border-radius: 6px; text-decoration: none;
-          color: var(--color-base-600);
-          transition: background-color .15s, color .15s;
-        }
-        .dark .api-nav-link { color: var(--color-base-400); }
-        .api-nav-link:hover { background: var(--color-base-50); color: var(--color-base-900); }
-        .dark .api-nav-link:hover { background: var(--color-base-900); color: var(--color-base-50); }
-        .api-nav-link.is-active { background: var(--color-primary-50); color: var(--color-primary-700); }
-        .dark .api-nav-link.is-active {
-          background: color-mix(in srgb, var(--color-primary-950) 40%, transparent);
-          color: var(--color-primary-400);
-        }
-
         /* ---- docs sidebar: mobile disclosure chevron ---- */
         /* site.js toggles the nav's `hidden` and the button's aria-expanded; the chevron
-           flips off that attribute (a JS-only class wouldn't be IL-discovered). */
+           flips off that attribute. */
         .docs-nav-chevron { transition: transform .2s ease; }
         .docs-nav-toggle[aria-expanded="true"] .docs-nav-chevron { transform: rotate(180deg); }
 
@@ -470,4 +337,4 @@ flips off that attribute (a JS-only class wouldn't be IL-discovered). */
         .dark ::-webkit-scrollbar-thumb { background: var(--color-base-700); }
         ::-webkit-scrollbar-track { background: transparent; }
         """;
-}
\ No newline at end of file
+}
diff --git a/docs/Beck.Docs/Program.cs b/docs/Beck.Docs/Program.cs
index 146508c..d3b60c3 100644
--- a/docs/Beck.Docs/Program.cs
+++ b/docs/Beck.Docs/Program.cs
@@ -78,6 +78,12 @@
         BaseColorName = ColorName.Slate,      // neutral grays
     },
     ExtraStyles = BrandStyling.ExtraStyles,
+    // Component classes as utility compositions, expanded into @layer components. See
+    // BrandStyling.Applies for the split between this and the declarative ExtraStyles residue.
+    CustomCssFrameworkSettings = settings => settings with
+    {
+        Applies = settings.Applies.SetItems(BrandStyling.Applies),
+    },
 });
 
 // `:symbol` source embeds — pull real source out of files by path. ContentRoot is
diff --git a/docs/Beck.Docs/wwwroot/js/site.js b/docs/Beck.Docs/wwwroot/js/site.js
index 3649bd5..ca283eb 100644
--- a/docs/Beck.Docs/wwwroot/js/site.js
+++ b/docs/Beck.Docs/wwwroot/js/site.js
@@ -212,7 +212,11 @@
     if (!svg || document.querySelector('.beck-lightbox')) return;
 
     var dialog = document.createElement('dialog');
-    dialog.className = 'beck-lightbox';
+    // Utility classes here are discovered by MonorailCSS's scan of this JS file, so the
+    // box lives with the element that creates it. `beck-lightbox` stays only as the hook
+    // BrandStyling keys the ::backdrop / @starting-style / cloned-svg sizing off — those
+    // can't be expressed as utilities.
+    dialog.className = 'beck-lightbox border-0 p-0 m-auto bg-transparent w-screen h-screen max-w-[100vw] max-h-[100vh] overflow-hidden cursor-zoom-out open:flex open:items-center open:justify-center';
     dialog.setAttribute('aria-label', 'Diagram, full screen');
 
     var clone = svg.cloneNode(true);
@@ -224,7 +228,9 @@
 
     var close = document.createElement('button');
     close.type = 'button';
-    close.className = 'beck-lightbox-close';
+    // Fully utility-styled (no BrandStyling rule) — MonorailCSS scans this file, so these
+    // classes are emitted just like markup ones.
+    close.className = 'fixed top-[18px] right-[18px] flex items-center justify-center w-[38px] h-[38px] p-0 cursor-pointer rounded-full border border-[rgb(255_255_255_/_0.25)] bg-[rgb(0_0_0_/_0.35)] text-white [transition:background-color_0.15s] hover:bg-[rgb(0_0_0_/_0.55)]';
     close.setAttribute('aria-label', 'Close full screen view');
     close.innerHTML = '<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg>';
     dialog.appendChild(close);