@wpmoo/ui 1.0.0-rc.9 → 1.1.0-dev.1

package/scss/_components.scss

@@ -1,4 +1,4 @@
-// Bootstrap components
+/* Bootstrap Components */
 @import "bootstrap/scss/tables";
 @import "bootstrap/scss/forms/labels";
 @import "bootstrap/scss/forms/form-text";
@@ -25,7 +25,7 @@
 @import "bootstrap/scss/offcanvas";
 @import "bootstrap/scss/helpers/color-bg";
 
-// Moo components
+/* Moo Components */
 @import "components/kbd";
 @import "components/input";
 @import "components/textarea";
@@ -42,6 +42,7 @@
 @import "components/menubar";
 @import "components/avatar";
 @import "components/navigation";
+@import "components/toc";
 @import "components/skeleton";
 @import "components/sidebar";
 @import "components/alert";

package/scss/_config.scss

@@ -1,24 +1,18 @@
-// Moo UI public Sass config
-//
-// Import this before Bootstrap variables so overrides take precedence.
-//
-// Only the variables below are public. Derived $moo-* tokens and component
-// knobs are internal and may change without notice.
 
-$primary: #171717 !default; // Brand color
-$secondary: #f4f4f5 !default; // Secondary surface color
-$success: #047857 !default; // Success color
-$info: #0369a1 !default; // Informational color
-$warning: #b45309 !default; // Warning color
-$danger: #e7000b !default; // Destructive color
-$light: #fafafa !default; // Light surface color
-$dark: #18181b !default; // Dark surface color
+$primary: #171717 !default;
+$secondary: #f4f4f5 !default;
+$success: #047857 !default;
+$info: #0369a1 !default;
+$warning: #b45309 !default;
+$danger: #e7000b !default;
+$light: #fafafa !default;
+$dark: #18181b !default;
 
-$body-color: #18181b !default; // Document text color
-$body-bg: #fff !default; // Document background color
-$font-size-base: 0.875rem !default; // Bootstrap-compatible base font size
+$body-color: #18181b !default;
+$body-bg: #fff !default;
+$font-size-base: 0.875rem !default;
 
-$border-color: #e4e4e7 !default; // Default border color
-$border-radius: 0.5rem !default; // Default radius
-$border-radius-sm: 0.375rem !default; // Small radius
-$border-radius-lg: 0.625rem !default; // Large radius
+$border-color: #e4e4e7 !default;
+$border-radius: 0.5rem !default;
+$border-radius-sm: 0.375rem !default;
+$border-radius-lg: 0.625rem !default;

package/scss/_settings.scss

@@ -1,6 +1,3 @@
-// Ordered Sass settings aggregate. These partials emit variables only; preserve
-// this sequence because later component and catalog knobs depend on earlier
-// palette and form values before Bootstrap's own defaults are loaded.
 @import "config";
 @import "settings/palette";
 @import "settings/forms";

package/scss/components/_accordion.scss

@@ -1,7 +1,4 @@
-// The reference trigger uses a real Lucide chevron-down icon that rotates
-// on expand, not Bootstrap's baked-in ::after background-image glyph.
-// Render the same icon our other components use and drive the rotation
-// off Bootstrap's own :not(.collapsed) state hook instead.
+/* Accordion */
 .accordion-button::after {
   content: none;
 }
@@ -27,8 +24,6 @@
   text-align: start;
 }
 
-// The reference trigger has no active/pressed background — only a hover
-// underline signals interactivity, matching a plain text-link affordance.
 .accordion-button:hover {
   text-decoration: underline;
 }
@@ -43,10 +38,6 @@
   text-decoration: none;
 }
 
-// The reference's flush trigger and body sit edge-to-edge with no
-// horizontal padding, and the trigger reads as medium weight, not
-// Bootstrap's own regular default -- both retune existing Bootstrap
-// accordion tokens/properties, not new selectors.
 .accordion-flush {
   --bs-accordion-btn-padding-x: 0;
   --bs-accordion-btn-padding-y: #{$spacer * 0.625};
@@ -58,8 +49,6 @@
   font-weight: $font-weight-medium;
 }
 
-// A card owns its own surface, so a nested accordion must let that surface
-// show through instead of painting Bootstrap's body background on top of it.
 .card .accordion {
   --bs-accordion-bg: #{$moo-accordion-contained-bg};
 }

package/scss/components/_alert.scss

@@ -1,6 +1,4 @@
-// Bootstrap's base .alert has a transparent bg/border until a contextual
-// .alert-{state} modifier sets them; the design reference's quiet style
-// keeps a visible neutral border even on the unmodified/default alert.
+/* Alert */
 $moo-alert-dismissible-close-space: $btn-close-width + ($btn-close-padding-x * 2) + 0.5rem !default;
 
 .alert {
@@ -29,21 +27,12 @@ $moo-alert-dismissible-close-space: $btn-close-width + ($btn-close-padding-x * 2
   padding: $btn-close-padding-y $btn-close-padding-x;
 }
 
-// The reference's destructive alert keeps the same neutral surface and
-// border as the default alert and tints only the text/icon color —
-// verified against the live reference page's Destructive example (bg-card,
-// text-destructive). Bootstrap's own alert-danger class instead fills a
-// saturated subtle-danger background, so re-anchor its consumption
-// variables back to the neutral ones and layer only the color shift on top.
 .alert-danger {
   --bs-alert-bg: transparent;
   --bs-alert-border-color: var(--moo-border);
   --bs-alert-color: var(--moo-destructive);
 }
 
-// Warning and success alerts follow the same quiet pattern as destructive:
-// neutral border, tinted alpha surface, hue-colored text. Matches the
-// reference's alert variants (amber for warning, green for success).
 .alert-warning {
   --bs-alert-bg: var(--moo-warning-surface);
   --bs-alert-border-color: var(--moo-border);

package/scss/components/_avatar.scss

@@ -1,5 +1,4 @@
-// Bootstrap has no native avatar component. This public `.avatar` namespace is
-// intentionally small and consumes the shared Bootstrap radius/border primitives.
+/* Avatar */
 .avatar {
   position: relative;
   display: inline-flex;
@@ -8,9 +7,6 @@
   width: $avatar-size;
   height: $avatar-size;
   flex: 0 0 auto;
-  // A badge (such as a presence dot) sits at the avatar's corner and must
-  // stay visible outside the circle; the image/fallback clip to the circle
-  // on their own, so the root itself does not need to clip its children.
   overflow: visible;
   border: 0;
   border-radius: var(--bs-border-radius-pill);
@@ -66,10 +62,6 @@
   padding-inline: 0.2rem;
   border: 0;
   border-radius: var(--bs-border-radius-pill);
-  // Mirrors the reference's ring-2 treatment: the badge keeps its own
-  // 10px/12px/15px box while the page-background ring paints outside it.
-  // box-shadow (not border) keeps the ring out of the layout box, matching
-  // the .avatar-group ring below and Tailwind's own ring-* technique.
   box-shadow: $avatar-badge-ring-shadow;
   background-color: var(--moo-muted-surface);
   color: var(--moo-foreground);
@@ -83,9 +75,6 @@
   height: 0.625rem;
 }
 
-// A plain presence/status dot (no text or icon content) -- the reference's
-// own AvatarBadge with no children, recolored per use via badge_class
-// (such as a Bootstrap bg-success utility) rather than a hardcoded color here.
 .avatar-badge--dot {
   height: $avatar-badge-dot-size;
   min-width: $avatar-badge-dot-size;
@@ -121,10 +110,6 @@
   align-items: center;
 }
 
-// Matches the reference's ring-2 ring-background: each avatar in a group
-// carries a page-background ring (light = white, dark = black) so stacked
-// avatars stay visibly separated. --bs-body-bg is theme-aware in both the
-// standalone and scoped builds, mirroring the badge ring treatment.
 .avatar-group > .avatar {
   box-shadow: $avatar-group-ring-shadow;
   z-index: 0;

package/scss/components/_badge.scss

@@ -1,3 +1,4 @@
+/* Badge */
 .badge {
   display: inline-flex;
   height: $moo-chip-height;

package/scss/components/_breadcrumb.scss

@@ -1,7 +1,4 @@
-// Bootstrap mutes the active/current item and leaves prior items on default
-// link styling (colored, underlined); the design reference inverts this —
-// prior items are muted, the active item reads at full foreground
-// strength — verified against the live reference page.
+/* Breadcrumb */
 .breadcrumb {
   --bs-breadcrumb-item-active-color: var(--moo-foreground);
   --bs-breadcrumb-item-padding-x: #{$spacer * 0.375};
@@ -46,8 +43,6 @@
   line-height: 1;
 }
 
-// Bootstrap emits these RTL changes through RTLCSS. The catalog serves one
-// runtime CSS file, so scoped RTL demos bridge that generated output.
 :dir(rtl) .breadcrumb {
   --bs-breadcrumb-divider: "#{$breadcrumb-divider-flipped}";
 }
@@ -78,8 +73,6 @@
   text-decoration: none;
 }
 
-// A static collapsed-segment marker (no interactive behavior of its own,
-// matching the reference's ellipsis placeholder).
 .breadcrumb-ellipsis {
   display: inline-flex;
   align-items: center;
@@ -91,10 +84,6 @@
   height: 1rem;
 }
 
-// Bootstrap's dropdown wrapper is a plain block box; inside a breadcrumb
-// item that sits beside a floated divider, a block box wraps its content
-// onto its own line instead of flowing beside the float. Making this
-// wrapper an atomic inline-flex box keeps it on the breadcrumb's line.
 .breadcrumb-dropdown-item,
 .breadcrumb-dropdown-item .dropdown {
   display: inline-flex;

package/scss/components/_button.scss

@@ -1,5 +1,4 @@
-// Bootstrap owns button geometry through its --bs-btn-* consumption values.
-// Moo adds only icon composition and the missing xs/icon-only variants.
+/* Buttons */
 .btn {
   display: inline-flex;
   align-items: center;
@@ -23,8 +22,6 @@ label.btn {
   cursor: default;
 }
 
-// Bootstrap provides sm/lg; xs and icon-only variants reuse the same
-// consumption properties instead of introducing a parallel size system.
 .btn-xs,
 .btn-icon-xs {
   --bs-btn-padding-y: #{$spacer * 0.1875};
@@ -66,18 +63,7 @@ label.btn {
   padding-inline-end: $icon-link-gap;
 }
 
-// Icon-only buttons become squares whose side equals the token-driven
-// button height (line-height + 2*padding-y + 2*border), so they always match
-// the height of sibling text buttons. --bs-btn-line-height is a length in
-// Moo, making this calc valid. No hard-coded dimensions.
 .btn-icon {
-  // Icon-only buttons become squares whose side equals the token-driven
-  // button height (line-height + 2*padding-y + 2*border), so they always
-  // match the height of sibling text buttons. The default button exposes no
-  // --bs-btn-line-height / --bs-btn-padding-y custom properties (Bootstrap
-  // compiles those from Sass), so only the default size declares them here;
-  // xs/sm/lg already set their own values in their own blocks above and
-  // must not be overridden back to the default by this shared rule.
   --bs-btn-line-height: #{$btn-line-height};
   --bs-btn-padding-y: #{$btn-padding-y};
 }
@@ -86,8 +72,6 @@ label.btn {
 .btn-icon-xs,
 .btn-icon-sm,
 .btn-icon-lg {
-  // The side is computed once into --moo-btn-icon-size and consumed on both
-  // axes (and by .btn-group-vertical) so the two cannot diverge.
   --moo-btn-icon-size: #{$moo-btn-icon-size};
   padding-inline: 0;
   inline-size: var(--moo-btn-icon-size);
@@ -115,11 +99,6 @@ label.btn {
   height: $font-size-base;
 }
 
-// The loading state swaps icon_start for the same loader-circle icon the
-// standalone Spinner uses; aria-busy doubles as the accessible loading
-// signal and the hook that scopes the spin to only that icon. The
-// rotation uses Bootstrap's own spinner-border keyframe in the standalone
-// build and the namespaced Moo keyframe in the scoped core build.
 .btn[aria-busy="true"] > [data-icon="inline-start"] {
   animation: $moo-spinner-animation-name $spinner-animation-speed linear infinite;
 }
@@ -136,14 +115,10 @@ label.btn {
   opacity: var(--moo-disabled-control-opacity);
 }
 
-// Replaces Bootstrap's native inset active shadow disabled in
-// _bootstrap_overrides.scss; 0.5px keeps the press visible without shifting
-// adjacent inline controls.
 .btn:not(:disabled):not(.disabled):not([aria-disabled="true"]):active {
   transform: translateY($moo-control-active-translate-y);
 }
 
-// Bootstrap consumes these properties; owned variants supply only exceptions.
 :is(.btn-primary, .btn-secondary, .btn-outline-secondary, .btn-outline-primary, .btn-ghost, .btn-danger) {
   --bs-btn-border-color: var(--bs-btn-bg);
   --bs-btn-hover-color: var(--bs-btn-color);
@@ -172,9 +147,6 @@ label.btn {
 
 .btn-secondary {
   --bs-btn-color: var(--moo-foreground);
-  // The reference's secondary button is the surface color (white in light)
-  // with a hairline border (bg-background + border-border), not a tinted
-  // fill; the shared muted surface stays the hover/active step.
   --bs-btn-bg: var(--moo-surface);
   --bs-btn-border-color: var(--moo-border);
   --bs-btn-hover-bg: color-mix(in srgb, var(--moo-muted-surface) 95%, var(--moo-foreground));

package/scss/components/_button_group.scss

@@ -1,7 +1,4 @@
-// Button Group adds no visual tokens of its own: Bootstrap's extend chain
-// (group sizes extend the button sizes) plus the grouped size selectors in
-// the button partial deliver one shared scale. Only RTL geometry lives here:
-// joined borders keep LTR order while labels render bidi-correctly.
+/* Button Group */
 [dir="rtl"] .btn-group,
 [dir="rtl"] .btn-toolbar {
   direction: ltr;
@@ -12,12 +9,6 @@
   unicode-bidi: plaintext;
 }
 
-// Bootstrap raises hovered, focused, and active group buttons above siblings
-// so the current border wins the shared seam. In a mixed-emphasis group (for
-// example primary + outline) pointer interaction paints one pixel into the
-// neighbor and reads like a width jump. Keep keyboard focus, active classes,
-// and checked inputs stacked, but let plain pointer hover/click use DOM order
-// so the joined edge stays visually stable.
 .btn-group > .btn:hover:not(:focus-visible):not(.active),
 .btn-group > .btn:focus:not(:focus-visible):not(.active),
 .btn-group > .btn:active:not(:focus-visible):not(.active),
@@ -34,16 +25,11 @@
   z-index: 1;
 }
 
-// A button group is one compound control surface; pressing one segment should
-// not translate that segment away from its joined border while siblings stay
-// still. The active color change remains as the press affordance.
 .btn-group > .btn:not(:disabled):not(.disabled):not([aria-disabled="true"]):active,
 .btn-group-vertical > .btn:not(:disabled):not(.disabled):not([aria-disabled="true"]):active {
   transform: none;
 }
 
-// Icon buttons in button groups should stay square, not stretch to fill
-// the group width (Bootstrap's flex: 1 1 auto makes them rectangular).
 .btn-group > .btn-icon,
 .btn-group > .btn-icon-xs,
 .btn-group > .btn-icon-sm,
@@ -55,8 +41,6 @@
   flex: 0 0 auto;
 }
 
-// Bootstrap's .btn-group-vertical > .btn { width: 100% } would stretch icon
-// buttons; re-assert the token-derived square so vertical rails stay square.
 .btn-group-vertical > .btn-icon,
 .btn-group-vertical > .btn-icon-xs,
 .btn-group-vertical > .btn-icon-sm,
@@ -64,14 +48,6 @@
   width: var(--moo-btn-icon-size);
 }
 
-// Select inside a button group: compact and content-sized, matching the
-// compact currency selector pattern. Bootstrap's flex defaults would shrink
-// it below its longest option; flex: 0 0 auto keeps the intrinsic (content)
-// width. The min-width floor derives from Bootstrap's form-select caret-space
-// token, not magic numbers. Focus keeps Bootstrap's default visible treatment.
-//
-// The input-group override matches Bootstrap's own `.input-group > .form-select`
-// specificity (0,2,0) which would otherwise stretch the select with flex: 1 1 auto.
 .btn-group-select,
 .input-group > .btn-group-select {
   flex: 0 0 auto;

package/scss/components/_card.scss

@@ -1,15 +1,8 @@
-// Card: bridge Bootstrap's consumption variables to shared primitives
-// (UI-wide shadow and radius) and runtime theme tokens, then add the minimal
-// structure that gives Bootstrap's native card the reference silhouette.
-// The reference card is a rounded surface with a hairline ring and a
-// theme-adaptive muted footer tint; its geometry is the source of the values
-// chosen here (verified against the live reference page).
+/* Card */
 .card {
   --bs-card-bg: color-mix(in srgb, var(--bs-secondary-bg) #{$moo-card-bg-mix}, var(--bs-body-bg));
   --bs-card-color: var(--moo-foreground);
   --bs-card-border-color: var(--moo-border);
-  // The reference uses a 14px corner; Bootstrap's shared radius-xl is the
-  // closest token and wins the delta (12px here) per the token-first rule.
   --bs-card-border-radius: var(--bs-border-radius-xl);
   --bs-card-inner-border-radius: calc(var(--bs-card-border-radius) - var(--bs-card-border-width));
   --bs-card-box-shadow: var(--bs-box-shadow-sm);
@@ -18,32 +11,19 @@
   --bs-card-title-color: var(--moo-foreground);
   --bs-card-subtitle-color: var(--moo-muted-foreground);
   --moo-card-footer-bg: #{$moo-card-footer-bg};
-  // The reference card lets consumers retune section rhythm and inset in one
-  // place; the default matches the 16px step Bootstrap's own spacer scale
-  // already carries. Declared on the selector that consumes it, like
-  // Bootstrap's own component custom properties.
   --moo-card-spacing: #{$moo-card-spacing};
 
-  // One vertical rhythm owned by the card; sections add only inline padding.
   gap: var(--moo-card-spacing);
   padding-block: var(--moo-card-spacing);
 
-  // A footer strip owns its own bottom padding; with one present the card
-  // drops its trailing rhythm so the muted strip touches the card edge
-  // (mirrors the reference's has-data-[slot=card-footer]:pb-0).
   &:has(.card-footer) {
     padding-block-end: 0;
   }
 
-  // A leading image frame owns the top edge; with one present the card drops
-  // its leading rhythm so the image touches the card corner (mirrors the
-  // reference's has-[>img:first-child]:pt-0).
   &:has(> .card-image) {
     padding-block-start: 0;
   }
 
-  // Keep the Bootstrap border box visible with a soft tokenized color, then
-  // let the shared shadow token supply the subtle card depth.
   border: var(--bs-card-border-width) solid var(--bs-card-border-color);
   box-shadow: var(--bs-card-box-shadow);
 
@@ -58,8 +38,6 @@
   --moo-card-spacing: #{$moo-card-spacing-sm};
 }
 
-// The reference header lays title/description in a grid; an optional action
-// occupies the trailing auto column on the same row as the title.
 .card-header {
   display: grid;
   grid-template-columns: 1fr auto;
@@ -92,8 +70,6 @@
   padding-inline: var(--moo-card-spacing);
 }
 
-// Use a separately mixed footer surface so tuning the main card fill does not
-// collapse the footer contrast.
 .card-footer {
   display: flex;
   align-items: center;
@@ -104,14 +80,10 @@
 }
 
 .card-img-top {
-  // The reference clips a leading image to the card's top corners; the shared
-  // radius keeps it aligned with the rounded surface.
   border-top-left-radius: var(--bs-card-border-radius);
   border-top-right-radius: var(--bs-card-border-radius);
 }
 
-// A leading image sits in a 16:9 frame; the frame owns a theme-adaptive
-// surface so a non-cover image never leaves an unstyled gap.
 .card-image {
   aspect-ratio: 16 / 9;
   overflow: hidden;

package/scss/components/_checkbox.scss

@@ -1,15 +1,8 @@
-// Bootstrap's margin-top (0.25rem = 4px) was computed for the old 1em
-// checkbox (14px at the catalog's 0.875rem body font). The override to
-// 1rem (16px) shifted the geometric center by 1px; tightening the top
-// margin to 0.125rem (2px) re-centres the 16px control within the
-// .form-check min-height so it aligns with the label text.
+/* Checkbox */
 .form-check-input {
   margin-top: 0.125rem;
 }
 
-// Bootstrap's checkbox/radio glyphs are SVG data URIs whose stroke/fill color
-// is fixed at compile time. Draw the checkbox mark as an overlay so it follows
-// the runtime primary foreground when Theme color changes.
 .form-check-input[type="checkbox"]:checked:not([role="switch"]) {
   --#{$prefix}form-check-bg-image: none;
 
@@ -42,11 +35,6 @@
   --#{$prefix}form-check-bg-image: radial-gradient(circle at center, var(--moo-primary-foreground) 0 34%, transparent 36%);
 }
 
-// Covers checkbox, switch (also type="checkbox"), and radio alike so
-// mouse-triggered focus never shows a ring on any form-check control,
-// matching Input/Textarea/Select's own :focus:not(:focus-visible) rule
-// in foundations/_focus.scss. Invalid checkboxes are excluded — their
-// persistent validation ring is restored by the rules at the bottom.
 .form-check-input:is([type="checkbox"], [type="radio"]):not(.is-invalid):focus:active,
 .form-check-input:is([type="checkbox"], [type="radio"]):not(.is-invalid):focus:not(:focus-visible) {
   border-color: var(--bs-border-color);
@@ -63,24 +51,10 @@
   border-color: $form-check-input-indeterminate-border-color;
 }
 
-// Invalid ("destructive") checkboxes are an exception to the mouse-click
-// focus-ring suppression above. The validation ring stays visible at all
-// times — not just on :focus — so the error state is never silently
-// dismissed. This matches the reference's aria-invalid ring pattern and
-// mirrors the destructive ring that foundations/_focus.scss already
-// paints on .form-control.is-invalid and .form-select.is-invalid. Border
-// color is left to Bootstrap's own native .is-invalid rule (compiled from
-// vendor/bootstrap/scss/mixins/_forms.scss's form-validation-state(),
-// already themed to --bs-form-invalid-border-color); only the ring is
-// added on top of it here.
 .form-check-input.is-invalid {
   box-shadow: 0 0 0 #{$moo-form-focus-ring-width} var(--moo-form-invalid-ring-color);
 }
 
-// The focus-suppression rules above have specificity (0,4,0) which
-// beats .is-invalid's (0,2,0). These :focus variants sit after the
-// suppression block and carry (0,5,0), so the destructive ring stays
-// visible during mouse click and programmatic focus alike.
 .form-check-input.is-invalid:focus:active,
 .form-check-input.is-invalid:focus:not(:focus-visible) {
   box-shadow: 0 0 0 #{$moo-form-focus-ring-width} var(--moo-form-invalid-ring-color);
@@ -96,17 +70,6 @@
   box-shadow: 0 0 0 #{$moo-form-focus-ring-width} var(--moo-form-invalid-ring-color);
 }
 
-// The reference keeps a checked control's own border and fill at the
-// normal checked color even inside an invalid group -- only unchecked
-// siblings' solid border and the ring (kept above) flag the error, so the
-// user's actual selection never reads as "wrong" by itself. Overrides two
-// separate Bootstrap native rules: the base .is-invalid border-color
-// above (which does not itself distinguish :checked) and .is-invalid:
-// checked's own background-color: var(--bs-form-invalid-color) (also
-// compiled from form-validation-state(), which paints a checked+invalid
-// control's fill destructive-red by default). Repeats the :focus variants
-// verbatim so this wins the same specificity tie by source order, focused
-// or not.
 .form-check-input:is([type="checkbox"], [type="radio"]):not([role="switch"]).is-invalid:checked,
 .form-check-input:is([type="checkbox"], [type="radio"]):not([role="switch"]).is-invalid:checked:focus:active,
 .form-check-input:is([type="checkbox"], [type="radio"]):not([role="switch"]).is-invalid:checked:focus:not(:focus-visible) {

package/scss/components/_close_button.scss

@@ -1,10 +1,9 @@
+/* Close Button */
 .btn-close {
   --bs-btn-close-color: var(--moo-foreground);
   --bs-btn-hover-color: var(--bs-btn-close-color);
   --bs-btn-hover-bg: var(--moo-muted-surface);
   --bs-btn-hover-border-color: #{$moo-close-button-border-color};
-  // Replace Bootstrap's filled-path X with a Lucide-style stroke-based icon
-  // (thinner, more delicate — matches the reference's feel).
   --bs-btn-close-bg: #{escape-svg($moo-close-button-bg-image)};
 
   display: inline-flex;
@@ -14,8 +13,6 @@
   border-width: var(--bs-border-width);
   border-style: var(--bs-border-style);
   border-color: $moo-close-button-border-color;
-  // Keep the square hit area visually circular in every context, including
-  // modal and offcanvas headers.
   border-radius: var(--bs-border-radius-pill);
   color: var(--bs-btn-close-color);
   background-image: none;
@@ -31,11 +28,6 @@
   mask: var(--bs-btn-close-bg) center / contain no-repeat;
 }
 
-// Bootstrap's dark rule filters the whole element to recolor its background
-// image. The glyph above uses currentColor through a mask, so filtering would
-// incorrectly invert the token-driven hover surface as well. Both resolved
-// owner modes override it so an outer dark owner cannot affect an inner light
-// owner through Bootstrap's global descendant selector.
 :scope[data-bs-theme="light"] .btn-close,
 :scope[data-bs-theme="dark"] .btn-close {
   filter: none;

package/scss/components/_collapsible.scss

@@ -1,3 +1,4 @@
+/* Collapsible */
 .collapsible {
   display: flex;
   flex-direction: column;

package/scss/components/_combobox.scss

@@ -1,6 +1,4 @@
-// Bootstrap has no native Combobox component. The Basic pass composes a
-// form-control with a dropdown-menu and keeps only the missing positioning
-// and inline affordance in this component namespace.
+/* Combobox */
 .combobox {
   --moo-combobox-width: #{$moo-combobox-width};
   --moo-combobox-multiple-width: #{$moo-combobox-multiple-width};
@@ -93,9 +91,6 @@
   cursor: text;
 }
 
-// .combobox-chips's focus-visible ring lives in foundations/_focus.scss,
-// next to the other compound-control rings, instead of here -- see that
-// file's comment for why.
 
 .combobox-value {
   display: flex;

package/scss/components/_context-menu.scss

@@ -1,8 +1,4 @@
-// Bootstrap has no native context-menu or "explicit fallback trigger"
-// concept, so there is no Bootstrap token to consume here: the fallback
-// button is a Moo-owned corner affordance layered over arbitrary surface
-// content, verified in the browser to otherwise fall into normal block flow
-// below the surface instead of reading as a menu trigger for it.
+/* Context Menu */
 .context-menu {
   position: relative;
 }
@@ -17,12 +13,6 @@
   inset-inline-end: 0.5rem;
 }
 
-// A pointer-driven open focuses the menu container itself, not an item, so
-// :hover carries the highlight instead of a focus ring competing with it
-// (verified in the browser: focusing the first item unconditionally left a
-// stray ring on it while a different item was hovered). The shared
-// [tabindex]:focus-visible ring in foundations/_focus.scss otherwise applies
-// here too, since a tabindex="-1" container still matches that selector.
 ul.context-menu-menu:focus-visible {
   outline: 0;
 }