maverick-wave 4.28.0 → 5.0.0

package/src/scss/abstracts/_variables.scss

@@ -4,286 +4,147 @@ $mw-theme-mode: 'switchable' !default; // 'dark', 'light', or 'switchable'
 
 $mw-hero-image: url('https://images.unsplash.com/photo-1591638462868-19cfad9c49d1?q=80&w=1300&auto=format&fit=crop') !default;
 
-// Ink on the hero image. The photo behind it is the same picture in both themes,
-// so the text on top cannot follow the theme: --mw-text-color would go dark the
-// moment the light theme is on, over a photo that stayed exactly as dark as it
-// was. Fixed to the light end of the palette instead, because a hero image is
-// usually the dark one. Set it to var(--mw-light-text-color) for a bright photo,
-// or to any color of your own.
+// Fixed to the light end rather than theme-bound: the photo does not change with
+// the theme, so its ink must not either. Use --mw-light-text-color on a bright one.
 $mw-hero-text-color: var(--mw-dark-text-color) !default;
 
-// How the hero image is treated per theme. A filter on the image, not a tinted
-// overlay: a translucent layer can only ever darken *toward its own colour*, so
-// on an already dark photo the two themes end up looking the same until the
-// alpha is high enough that the tint colour itself takes over - dark blue in
-// both, just more of it. brightness() moves the picture instead of covering it,
-// which reads as a difference even on a dark image.
-//
-// Kept below 1 in the dark theme and just above it in the light one, so the
-// photo stays dark enough for the fixed light ink either way. Any filter list
-// works - add contrast(), sepia(), grayscale() to taste.
+// A filter on the image, not a tinted overlay: an overlay can only darken toward
+// its own colour, so both themes end up alike on an already dark photo. Kept
+// below 1 dark and just above it light, so the fixed light ink stays readable.
 $hero-filter-dark: brightness(0.7) !default;
 $hero-filter-light: brightness(1.1) !default;
 
-// ---------------------------------------------------------------------------
-// Root colors
-//
-// These are the only values a project has to set. Every other tone is derived
-// from them at runtime via color-mix(), so overriding a root token in plain
-// CSS (:root { --mw-primary-color: ... }) cascades to all of its variants -
-// including the lightened variants the dark theme needs.
-// ---------------------------------------------------------------------------
-
-// Brand
+// Root colors - the only values a project has to set. Every other tone is derived
+// from them at runtime with color-mix(), so overriding one in plain CSS cascades
+// to all of its variants, the dark theme's lightened ones included.
 $primary-color: #1031bb !default;
 $secondary-color: #bb5710 !default;
 
-// Neutrals - a touch of the brand hue, so grays sit next to the brand colors
-// instead of fighting them
+// A touch of the brand hue, so grays sit next to the brand instead of fighting it
 $gray-color: #6e6e78 !default;
-// Deep enough to read as dark, light enough that the surfaces derived from it
-// still have somewhere to go - see the surface stack below
+// Light enough that the surfaces derived from it still have somewhere to go
 $dark-background: #171f30 !default;
 $dark-text-color: #f0eef9 !default;
 $light-background: #e7e7f0 !default;
 $light-text-color: #131925 !default;
-// Text on solid colored surfaces, in both themes. The one token that cannot be
-// derived: a dark brand color needs a light label, a light one a dark label.
-// Set it to the opposite end of your palette from $primary-color.
+// The one token that cannot be derived - set it opposite $primary-color
 $accent-text-color: #f2f6fc !default;
 // Form controls stay light in both themes, so they get their own root value
 $form-elements-background: #f4f7fb !default;
 
-// Status - kept clear of the brand colors, so "accent" never reads as
-// "attention"
+// Kept clear of the brand colors, so "accent" never reads as "attention"
 $success-color: #157f1a !default;
 $warning-color: #d1bb21 !default;
 $danger-color: #d41708 !default;
 $info-color: #0780ca !default;
 
-// Ink on the handful of surfaces that stay a fixed grey in both themes and
-// therefore cannot take --mw-accent-text-color: the tooltip, `mw-btn-mini`,
-// `mw-info-mini` and the gallery arrows. Compile-time on purpose - these are
-// not meant to be retuned per project, they just should not be four copies of
-// the same literal in four unrelated files.
+// Ink on the surfaces that stay a fixed grey in both themes and therefore cannot
+// take --mw-accent-text-color: tooltip, mw-btn-mini, mw-info-mini, gallery arrows
 $fixed-surface-text: #efefef !default;
 
-// Uniform hover tone for every solid brand/status surface. Darkening, in both
-// themes: the label on a solid surface is $accent-text-color, and lightening
-// a solid surface is what breaks it.
+// Darkening in both themes: the label on a solid surface is $accent-text-color,
+// and lightening the surface is what breaks it
 $hover-shift: 15% !default;
 
-// How light a color has to be before it reads as ink on a dark surface, and how
-// dark before it reads as ink on a light one - OKLch lightness, 0 to 1. A bound,
-// not a target: a color already inside the range is used untouched, so a bright
-// brand color stays bright and only one that would drown gets moved.
-//
-// 0.52 is where the default blue clears 3:1 on a dark card - the floor a rule
-// or a large label needs. At 0.4 it sat at 1.9:1: a price nobody reads and an
-// outline button whose border nobody finds. 0.58 does the same job for the
-// yellow on a light card, which was at 2.5:1, and is as low as that end can go
-// without collecting company - the orange and the cyan sit at 0.57, so one
-// step further moves three colors instead of one.
-//
-// Which is the point of a bound: in both directions exactly one of the six root
-// colors is outside it and gets moved. The other five pass through byte for
-// byte, and a project that swaps the palette gets the same treatment for
-// whichever of its own colors needs it.
+// OKLch lightness a color needs to read as ink on a surface. A bound, not a
+// target: a color already inside it passes through untouched. 0.52 is where the
+// default blue clears 3:1 on a dark card, 0.58 does the same for the yellow on a
+// light one - and 0.58 is as low as that end goes without moving three colors.
 $ink-lightness-dark: 0.52 !default;
 $ink-lightness-light: 0.58 !default;
-// How much of the primary color the muted text gray picks up, so it belongs to
-// the palette instead of being a stock #888. 0% is a true gray.
+// How much primary the muted gray picks up, so it belongs to the palette. 0% is true gray.
 $muted-tint: 23% !default;
 
-// The surface stack - how far card and footer sit from the page background.
-// Each one scales the page's OKLch lightness *and* chroma by its factor and
-// keeps the hue, so the whole stack stays in one color family no matter how
-// tinted the page is.
-//
-// Below 1 steps toward black, above 1 toward white. Read them as "the card is
-// at 85% of the page's lightness": lower the dark factor or raise the light one
-// for more separation between a card and the page, move both toward 1 for a
-// flatter look.
-//
-// A card always steps *away* from the text color - down in the dark theme, up
-// in the light one - so content sits on the cleaner of the two surfaces. That is
-// also the one thing to watch when retuning: a near-black $dark-background
-// leaves nothing underneath, and a card at 0.6 of almost nothing is still
-// almost nothing. Keep the dark page around OKLch lightness 0.24 if you want
-// room for a low card factor.
+// The surface stack: each factor scales the page's OKLch lightness and chroma and
+// keeps the hue, so card and footer stay in the page's color family. A card always
+// steps *away* from the text color. Watch the floor when retuning - a card at 0.6
+// of a near-black page is still near-black, so keep the dark page around L 0.24.
 $card-surface-dark: 0.85 !default;
 $card-surface-light: 1.05 !default;
-// The footer band. In the dark theme it steps further out than the card, in the
-// light theme it steps the other way, so the band under the page reads as chrome
-// and not as another card. The header is not part of this - see below.
+// Steps further out than the card in the dark theme and the other way in the
+// light one, so the band reads as chrome rather than as another card
 $footer-surface-dark: 0.75 !default;
 $footer-surface-light: 0.95 !default;
 
-// The header bar. It stays dark in both themes, so it cannot be part of the
-// surface stack above: a project that only ever shows the light theme would be
-// styling its header through a dark page color it never configured, and the bar
-// would keep the framework default no matter what the palette says.
-//
-// It is built from the primary color instead - the one token every palette has
-// to set - darkened straight toward black, which is the ramp every color tool
-// shows as a color's shades. Kept well past the bottom of that ramp on purpose:
-// this deep the brand hue is a tint on near-black rather than a color of its
-// own, which is what keeps the bar reading as chrome behind the page.
-//
-// Lower it for a darker bar. The ink on the bar is near-white, so going far up
-// means overriding --mw-header-text-color and
-// --mw-header-navbar-list-active-color with it.
+// The bar stays dark in both themes, so it cannot come from the surface stack -
+// a light-only project would be styling it through a page color it never set.
+// Built from the primary instead, darkened so deep that the hue reads as a tint
+// on near-black. Going far up means overriding the header ink tokens with it.
 $header-surface: 14% !default;
 
-// How far the active navbar link is lifted off the primary colour. Lower is a
-// stronger, more saturated blue and closer to the brand tone; higher is paler
-// and carries more contrast against the bar.
-//
-// 25% lands on #435fd5 at 3.67:1 over the bar - past the 3:1 floor a large or
-// bold label needs, under the 4.5:1 an AA body-size label wants. That is a
-// deliberate trade for a nav item that is already marked by an underline and a
-// weight change as well as by colour; raise it toward 35% for the safe end.
+// 25% lands at 3.67:1 over the bar: past the 3:1 floor for a bold label, under
+// AA body size. A deliberate trade - the item also carries an underline and a
+// weight change. Raise it toward 35% for the safe end.
 $header-active-tint: 25% !default;
 
-// The shadow pair every elevation is built from - see elevation() below.
-//
-// $shadow-cast-dark is how far a shadow in the dark theme sits below the page
-// colour. A black shadow on a near-black page is invisible, which is why the
-// framework used to carry a single light glow instead; the glow survives as the
-// far layer, and this is the near one that puts weight back underneath it.
+// How far a dark-theme shadow sits below the page colour - a black shadow on a
+// near-black page is invisible, so this is the near layer that puts weight back
 $shadow-cast-dark: 0.3 !default;
-// Near (contact) and far (ambient) opacity per theme. The dark theme's far layer
-// is the light rim that reads as elevation on a dark page, so it stays low - a
-// bright glow carries much further than a dark shadow at the same alpha.
+// Near (contact) and far (ambient) opacity. The dark theme's far layer is a light
+// rim, so it stays low - a glow carries further than a shadow at the same alpha.
 $shadow-near-dark: 55% !default;
 $shadow-far-dark: 13% !default;
 $shadow-near-light: 14% !default;
 $shadow-far-light: 10% !default;
 
-// ---------------------------------------------------------------------------
-// Control sizes
-//
-// One height per step, shared by everything that can end up in a row next to
-// something else: input, select, textarea, button.
-//
-// Before this each control worked its height out from its own font size, its own
-// line-height and its own padding, and no two of them agreed - an input, a
-// select and a button side by side measured 32.2, 34.4 and 37.2 pixels. That is
-// the kind of flaw you see without being able to name it: the row just looks
-// slightly wrong.
-//
-// A minimum, not a fixed height, so a control whose content needs more room
-// still gets it. The step is what makes the trio line up; the font scale below
-// is what makes them look like one family.
-// ---------------------------------------------------------------------------
-// 32 / 36 / 40px - an even 4px step. The middle one used to be 2.35rem, which
-// made the ramp 32 / 37.6 / 41.6: a 5.6px step to the base size and a 4px one
-// past it, and a base field a shade taller than it needed to be.
-//
-// The padding is not what sets these. A field's height comes from the minimum
-// below, so trimming `padding-block` on its own changes where the text sits
-// inside the box and not how tall the box is.
+// Control sizes - 32 / 36 / 40px, shared by input, select, textarea and button so
+// the row lines up. A minimum, not a fixed height, and it is what sets a field's
+// height: trimming `padding-block` moves the text inside the box, not the box.
 $control-height-sm: 2rem !default;
 $control-height: 2.25rem !default;
 $control-height-lg: 2.5rem !default;
 
-// The font each step is set in. All three fields share it - the select used to
-// sit a whole step below the input beside it, which is why the two never looked
-// like a pair. Buttons stay one step above: a button carries a label, a field
-// carries data the user typed, and the label may be the louder of the two.
+// All three fields share it; buttons stay one step above, because a button
+// carries a label and a field carries what the user typed
 $control-font-sm: 0.8rem !default;
 $control-font: 0.9rem !default;
 $control-font-lg: 1rem !default;
 
-// Stated rather than inherited. `line-height: normal` is whatever the font
-// vendor decided, so an input and a select with the same padding still came out
-// different heights - and it changes the moment a project swaps the font stack.
+// Stated, not inherited: `normal` is whatever the font vendor decided, and it
+// changes the moment a project swaps the font stack
 $control-line-height: 1.35 !default;
 
-// ---------------------------------------------------------------------------
-// Motion
-//
-// Four durations and three curves, and every transition in the framework is
-// built from them. The point is not the numbers - it is that a hover, a drawer
-// and a modal that all say "0.3s ease" feel like three different products,
-// because 300ms is twice too slow for a colour swap and half too fast for a
-// panel crossing the screen.
-//
-// The curves: 'out' decelerates and is what almost everything wants, because
-// something arriving should land rather than stop. 'in-out' is symmetric, for
-// anything that moves from A to B and back. 'spring' overshoots a few percent,
-// which is what makes a press or a pop read as physical instead of animated.
-// ---------------------------------------------------------------------------
+// Motion - one scale for everything, because 300ms is twice too slow for a colour
+// swap and half too fast for a panel crossing the screen.
 $duration-instant: 110ms !default;
 $duration-fast: 180ms !default;
 $duration-base: 300ms !default;
 $duration-slow: 520ms !default;
 $duration-slower: 900ms !default;
 
-// The curves.
-//
-// 'out' was cubic-bezier(0.22, 1, 0.36, 1) for one revision, and it was wrong:
-// that curve is so front-loaded it covers about seventy percent of the distance
-// in the first quarter of the time. On a colour swap that reads as snappy. On
-// anything that actually travels - an image scaling inside a card, a panel
-// sliding - it reads as a jump followed by a crawl, which is the opposite of
-// smooth. This one decelerates evenly and is the right default for both.
+// Decelerates evenly. A front-loaded curve reads as snappy on a colour swap and
+// as a jump followed by a crawl on anything that travels.
 $ease-out: cubic-bezier(0.33, 1, 0.68, 1) !default;
 $ease-in-out: cubic-bezier(0.65, 0, 0.35, 1) !default;
 // A few percent of overshoot, not a bounce - the earlier 1.56 read as a wobble
 $ease-spring: cubic-bezier(0.34, 1.3, 0.64, 1) !default;
 
-// Anything that moves a large area rather than recolouring one - an image
-// zooming inside a card, a tile growing. Distance and duration go together: the
-// same 300ms that feels right on a 40px button feels snatched on a 300px photo,
-// because the eye reads speed as distance over time, not as time.
+// For anything that moves a large area: the 300ms that fits a 40px button feels
+// snatched on a 300px photo, because the eye reads speed as distance over time
 $duration-zoom: 650ms !default;
 
-// What --mw-transition actually animates.
-//
-// It used to be `all`, which is a footgun in two directions: it animates
-// properties nobody meant to animate - a width that changes at a breakpoint
-// crawls to its new value - and it forces the browser to check every property
-// on every change. The list below covers every paint-only property a hover,
-// focus or active state touches, and nothing that moves layout. Anything that
-// really does want to animate a size says so itself.
+// Every paint-only property a hover, focus or active state touches, and nothing
+// that moves layout. `all` would crawl a width that changed at a breakpoint.
 $transition-properties:
   color, background-color, background-image, border-color, box-shadow, opacity,
   transform, outline-color, outline-offset, filter, backdrop-filter, fill,
   stroke, text-decoration-color !default;
 
-// ---------------------------------------------------------------------------
-// Focus ring
-//
-// One ring for the whole framework, on :focus-visible only - a mouse click on a
-// button should not leave it outlined. 2px is the floor at which a ring stays
-// visible against a busy surface, and the offset is what keeps it from reading
-// as a border on the control itself.
-// ---------------------------------------------------------------------------
+// One ring for the whole framework, on :focus-visible only. 2px is the floor at
+// which it stays visible on a busy surface; the offset keeps it off the border.
 $focus-ring-width: 2px !default;
 $focus-ring-offset: 2px !default;
-// The soft halo a form field gets instead of a hard ring - a field already has a
-// border to recolour, so a second hard line around it reads as a mistake.
+// A field already has a border to recolour, so it gets a soft halo, not a ring
 $focus-halo-size: 3px !default;
 $focus-halo-opacity: 28% !default;
 
-// ---------------------------------------------------------------------------
-// Derivation helpers
-//
-// They emit color-mix() referring back to another --mw-* token instead of
-// baking a value at compile time.
-//
-// shade()/tint() mix `in hsl`, which behaves like color.adjust($lightness: ...)
-// and scales proportionally, so a derivation looks the same on every palette.
-// Mixing with black/white also lowers the saturation a little - that is why
-// hover tones read slightly softer than the base color. Alpha blending uses
-// `srgb` against `transparent`.
+// Derivation helpers - they emit color-mix() against another --mw-* token rather
+// than baking a value at compile time.
 //
-// A derived token may only reference a token whose value does not depend on the
-// active theme, i.e. a root color or a theme-prefixed one (dark-*/light-*).
-// Custom properties are substituted on the element they are declared on, so a
-// base token pointing at a theme alias would freeze the dark value on :root.
-// ---------------------------------------------------------------------------
+// A derived token may only reference one that does not depend on the active theme,
+// so a root color or a dark-*/light-* alias. Custom properties are substituted on
+// the element they are declared on, so pointing at a theme alias would freeze the
+// dark value on :root.
 
 // Reference another token as-is
 @function token($name) {
@@ -311,32 +172,26 @@ $focus-halo-opacity: 28% !default;
   );
 }
 
-// Translucent variant of an arbitrary color expression. fade() is the same thing
-// for a token name; this one takes whatever another helper handed back, which is
-// what the shadow tones below need.
+// Same as fade(), but for whatever another helper handed back rather than a name
 @function alpha($color, $amount) {
   @return string.unquote(
     'color-mix(in srgb, #{$color} #{$amount}, transparent)'
   );
 }
 
-// Darkened straight toward black in sRGB - the ramp a color tool prints as a
-// color's shades, where $amount is how much of the color survives. shade()
-// cannot stand in for it: mixing in hsl scales saturation along with lightness
-// and hands back a washed-out tone, which is what a hover state wants and what
-// a surface meant to still read as the brand color does not.
+// Darkened straight toward black, $amount being how much of the color survives.
+// shade() washes out the saturation on the way, which a surface must not do.
 @function deepen($name, $amount) {
   @return string.unquote(
     'color-mix(in srgb, var(--mw-#{$name}) #{$amount}, black)'
   );
 }
 
-// The two ink variants. They clamp lightness in OKLch and keep hue and chroma,
-// which is what makes them palette-agnostic: the same expression lifts a very
-// dark color, deepens a very light one and leaves everything in between alone.
-@function ink-on-dark($name) {
+// Clamp lightness in OKLch, keep hue and chroma: the same expression lifts a very
+// dark color, deepens a very light one and leaves everything between alone
+@function ink-on-dark($name, $lightness: $ink-lightness-dark) {
   @return string.unquote(
-    'oklch(from var(--mw-#{$name}) max(l, #{$ink-lightness-dark}) c h)'
+    'oklch(from var(--mw-#{$name}) max(l, #{$lightness}) c h)'
   );
 }
 
@@ -346,40 +201,25 @@ $focus-halo-opacity: 28% !default;
   );
 }
 
-// A theme surface derived from the page background: OKLch lightness and chroma
-// scaled by the same factor, hue kept. Below 1 steps toward black, above 1
-// toward white. Chroma rides along because that is what a hand-picked stack
-// does - a darker surface of the same hue carries less color, not the same
-// color at a lower lightness, which would read oversaturated.
+// Lightness and chroma scaled by the same factor, hue kept. Chroma rides along
+// because a darker surface carries less color, not the same color darker.
 @function surface($name, $factor) {
   @return string.unquote(
     'oklch(from var(--mw-#{$name}) calc(l * #{$factor}) calc(c * #{$factor}) h)'
   );
 }
 
-// Muted text tone. Built from a true gray on purpose, not by stepping the
-// theme's text color back: darkening keeps the source saturation and fading
-// keeps its hue, so a tinted text color hands its tint straight through - a
-// mint white page ends up with mint green secondary text. Starting neutral and
-// adding back a defined share of the brand keeps that under control. Opaque,
-// so it reads the same on the page and on a card.
+// Built from a true gray, not by stepping the text color back: that would hand a
+// tinted text color's tint straight through - a mint page, mint secondary text
 @function muted($lightness) {
   @return string.unquote(
     'color-mix(in oklab, oklch(#{$lightness} 0 0), var(--mw-primary-color) #{$muted-tint})'
   );
 }
 
-// Two-layer elevation.
-//
-// The near layer is the contact shadow - short offset, tight blur - that gives
-// an element weight and pins it to the surface underneath. The far layer is the
-// ambient spread that says how high it floats. One layer on its own reads as a
-// blur behind the box; the pair reads as light, which is the whole difference
-// between a framework that looks drawn and one that looks rendered.
-//
-// Both tones are theme-prefixed tokens, so the ramp is declared once per theme
-// and the same five level names work in either one - see the note on derived
-// tokens above for why they cannot be one shared set on :root.
+// Near is the contact shadow that pins the box down, far the ambient spread that
+// says how high it floats. One layer alone reads as a blur, the pair as light.
+// Theme-prefixed tokens, so the ramp is declared once per theme.
 @function elevation($theme, $y-near, $blur-near, $y-far, $blur-far) {
   @return string.unquote(
     '0 #{$y-near} #{$blur-near} var(--mw-#{$theme}-shadow-near),' +
@@ -387,61 +227,37 @@ $focus-halo-opacity: 28% !default;
   );
 }
 
-// Base colors that don't change between themes.
-// Emitted as --mw-<key>.
-//
-// A brand color has two jobs, and they need two tokens:
-//   --mw-primary-color        the exact brand tone, for anything it *fills* -
-//                             buttons, badges, bars, filled surfaces. The label
-//                             on top is --mw-primary-accent-text-color, which
-//                             falls back to the shared --mw-accent-text-color.
-//   --mw-primary-text-color   the same color as ink on a theme surface - text,
-//                             icons, focus rings, accent borders. Lives in the
-//                             theme maps below, because a color chosen to carry
-//                             a label is by definition too dark or too light to
-//                             be read *on* the page it sits on.
-// Same split for secondary and for every status color.
+// Emitted as --mw-<key>. A brand color has two jobs and needs two tokens:
+// --mw-primary-color is the tone it *fills* with, --mw-primary-text-color the
+// same color as ink on a theme surface. The second lives in the theme maps below,
+// because a color picked to carry a label cannot be read *on* the page as well.
+// Same split for secondary and every status color.
 $base-colors: (
   'primary-color': $primary-color,
   'primary-color-hover': shade('primary-color', $hover-shift),
-  // One rule for every tinted surface in the framework: 20% of the color, 45%
-  // while hovered. Both stay close enough to the surface underneath that the
-  // theme's own --mw-text-color keeps working on top - which is what makes a
-  // soft alert, badge or tag readable in the light *and* the dark theme.
+  // Every tinted surface in the framework, and both stay close enough to the one
+  // underneath that the theme's own --mw-text-color keeps working on top
   'primary-background': fade('primary-color', 30%),
   'primary-background-hover': fade('primary-color', 50%),
-  // Same surface under the name the status colors use, so a component can
-  // interpolate one token name across all six colors
+  // The name the status colors use, so a component can interpolate one token name
   'primary-info-background': token('primary-background'),
   'secondary-color': $secondary-color,
   'secondary-color-hover': shade('secondary-color', $hover-shift),
   'secondary-background': fade('secondary-color', 30%),
   'secondary-background-hover': fade('secondary-color', 50%),
   'secondary-info-background': token('secondary-background'),
-  // Text on any solid colored surface - buttons of every variant, table and
-  // panel headers, badges, tooltips, mini close buttons, stepper dots.
-  // Deliberately derived from neither a brand color nor a theme text color:
-  // it has to stay readable on a dark surface no matter how the palette or the
-  // active theme is retuned.
+  // Derived from neither a brand color nor a theme text color: it has to stay
+  // readable on a solid surface however the palette or the theme is retuned
   'accent-text-color': $accent-text-color,
-  // Per-color override of that label. One accent text color only works while
-  // the whole palette sits on the same side of the lightness scale - a neon
-  // green primary next to a deep blue secondary needs a dark label on the one
-  // and a light label on the other. Defaults to the shared token, so nothing
-  // changes until a project sets one:
-  //   :root { --mw-primary-accent-text-color: #000; }
-  // Every component that fills a surface with one of the six colors reads the
-  // matching token, so a button, a table header, a panel header, a badge and
-  // the burger button all follow the same override. The status colors carry
-  // the same token, see $status-colors.
+  // Per-color override, for a palette that does not sit on one side of the
+  // lightness scale. Defaults to the shared token, so nothing changes until a
+  // project sets one - every filled surface reads the matching token.
   'primary-accent-text-color': token('accent-text-color'),
   'secondary-accent-text-color': token('accent-text-color'),
   'gray-color': $gray-color,
   // Subtle neutral surface: zebra rows, disabled fields, tracks, skeletons
   'gray-background': fade('gray-color', 20%),
-  // Same surface under the name people reach for when they want a slightly
-  // set-off area *inside* a card - hint block, framed paragraph, form summary.
-  // An alias on purpose: one tone, two names, so nobody invents a third.
+  // Alias on purpose: one tone, two names, so nobody invents a third
   'surface-muted': token('gray-background'),
   // Heavy scrim behind modals and blocking spinners
   'overlay-background': fade('gray-color', 60%),
@@ -475,24 +291,29 @@ $status-colors: (
   'info-accent-text-color': token('accent-text-color'),
 );
 
+// The six colors a component offers variants in, as one map rather than a copy in
+// each component that loops over them.
+// The fill tone, not the ink tone - every consumer of this map paints with it
+$semantic-colors: (
+  primary: var(--mw-primary-color),
+  secondary: var(--mw-secondary-color),
+  info: var(--mw-info-color),
+  success: var(--mw-success-color),
+  warning: var(--mw-warning-color),
+  danger: var(--mw-danger-color),
+);
+
 // Dark theme colors. Emitted as --mw-dark-<key>, hence the prefixed references.
 $dark-theme-colors: (
   'page-background': $dark-background,
   'hero-image-filter': $hero-filter-dark,
-  // The surface stack - the card and footer factors and the reasoning behind
-  // them live with the derivation knobs above, so a project can retune the
-  // stack from one place instead of editing this map. The rule between the
-  // surfaces keeps its own factor: it runs against the card - lighter than a
-  // dark page, darker than a light one - or it disappears into what it
-  // separates, and that is not a per-project decision.
+  // Factors live with the derivation knobs above so the stack retunes from one
+  // place. The rule keeps its own: it runs against the card or it disappears.
   'card-background': surface('dark-page-background', $card-surface-dark),
   'footer-background': surface('dark-page-background', $footer-surface-dark),
   'border': surface('dark-page-background', 1.35),
   'shadow': fade('dark-text-color', 30%),
-  // The two tones every elevation level is mixed from, and the five-step ramp
-  // itself. A component names a level - `var(--mw-elevation-2)` - instead of
-  // inventing another `0 5px 9px`; before this the framework carried twelve
-  // different shadow values for what were really four heights.
+  // A component names a level instead of inventing another `0 5px 9px`
   'shadow-near': alpha(
       surface('dark-page-background', $shadow-cast-dark),
       $shadow-near-dark
@@ -505,21 +326,19 @@ $dark-theme-colors: (
   'elevation-5': elevation('dark', 10px, 20px, 30px, 64px),
   'text-color': $dark-text-color,
   'text-muted-color': muted(0.7),
-  // Every color as ink on this page. Derived, not hardcoded - a project that
-  // overrides a root color gets a readable dark-theme variant without setting a
-  // second value, and a palette that is already light passes through unchanged.
+  // Derived, so overriding a root color yields a readable dark variant for free
   'primary-text-color': ink-on-dark('primary-color'),
   'secondary-text-color': ink-on-dark('secondary-color'),
   'success-text-color': ink-on-dark('success-color'),
   'warning-text-color': ink-on-dark('warning-color'),
   'danger-text-color': ink-on-dark('danger-color'),
   'info-text-color': ink-on-dark('info-color'),
-  // Translucent accent line used for dividers, rules and outlines. Built from
-  // the ink tone, not the fill tone, or the line disappears into the page.
+  // From the ink tone, not the fill tone, or the line disappears into the page
   'border-accent': fade('dark-primary-text-color', 70%),
-  // The accent arc on the two round corners of every mw-surface. Full strength
-  // here: against a dark card the ink tone is the faintest it gets.
+  // Full strength: against a dark card the ink tone is the faintest it gets
   'corner-accent': token('dark-primary-text-color'),
+  // Not tint(): mixing toward white washes the arc out instead of brightening it
+  'corner-accent-hover': ink-on-dark('primary-color', 0.72),
 );
 
 // Light theme colors. Emitted as --mw-light-<key>.
@@ -530,10 +349,6 @@ $light-theme-colors: (
   'footer-background': surface('light-page-background', $footer-surface-light),
   'border': surface('light-page-background', 0.8),
   'shadow': fade('light-text-color', 30%),
-  // The two tones every elevation level is mixed from, and the five-step ramp
-  // itself. A component names a level - `var(--mw-elevation-2)` - instead of
-  // inventing another `0 5px 9px`; before this the framework carried twelve
-  // different shadow values for what were really four heights.
   'shadow-near': fade('light-text-color', $shadow-near-light),
   'shadow-far': fade('light-text-color', $shadow-far-light),
   'elevation-1': elevation('light', 1px, 2px, 1px, 4px),
@@ -543,8 +358,7 @@ $light-theme-colors: (
   'elevation-5': elevation('light', 10px, 20px, 30px, 64px),
   'text-color': $light-text-color,
   'text-muted-color': muted(0.5),
-  // Same idea, other direction: a color too light to be read on paper is
-  // deepened, everything else passes through as it is
+  // Other direction: a color too light to read on paper is deepened
   'primary-text-color': ink-on-light('primary-color'),
   'secondary-text-color': ink-on-light('secondary-color'),
   'success-text-color': ink-on-light('success-color'),
@@ -552,38 +366,31 @@ $light-theme-colors: (
   'danger-text-color': ink-on-light('danger-color'),
   'info-text-color': ink-on-light('info-color'),
   'border-accent': fade('light-primary-text-color', 70%),
-  // Held back a little against the dark theme: the same blue on a near-white
-  // card carries far more contrast than it does on a dark one, and at full
-  // strength the arc stops being a detail and starts being a frame.
+  // Held back: on a near-white card the same tone carries far more contrast, and
+  // at full strength the arc stops being a detail and starts being a frame
   'corner-accent': fade('light-primary-text-color', 80%),
+  // Full strength is the frame a resting card must not have and a hovered one wants
+  'corner-accent-hover': token('light-primary-text-color'),
 );
 
-// Header/navbar colors. The bar is dark in both themes, so every tone here is
-// built from the primary color rather than from a theme token: the header is the
-// one piece of chrome a light-only project would otherwise be styling through
-// dark-theme values it never set. Emitted as --mw-header-<key>, and each one is
-// still overridable on its own.
+// Emitted as --mw-header-<key>. Built from the primary rather than a theme token,
+// because the bar is dark in both themes - see $header-surface.
 $header-colors: (
   'background': deepen('primary-color', $header-surface),
   'text-color': tint('primary-color', 92%),
   'navbar-list-color': fade('header-text-color', 70%),
   'navbar-list-active-color': tint('primary-color', $header-active-tint),
-  // The burger sits on the primary button surface, and on the secondary one
-  // while the drawer is open, so it takes the label ink of each - not the
-  // header text color, which is picked for the dark bar behind it.
+  // The burger sits on a button surface, so it takes that label's ink
   'burgerbutton-color': token('primary-accent-text-color'),
   'burgerbutton-open-color': token('secondary-accent-text-color'),
   'border': fade('header-navbar-list-active-color', 40%),
 );
-// Drives the bar height, the anchor scroll offset and the mobile drawer padding.
-// 59px is the intrinsic height: 42px logo + 2 × spacing('3') + 1px border.
+// Drives bar height, anchor scroll offset and drawer padding. Intrinsic height is
+// 59px: 42px logo + 2 × spacing('3') + 1px border.
 $header-height: 62px;
 
-// Typography
-//
-// The stacks live here and not next to the typography rules, because this is
-// the file `@use 'main' with (...)` configures. No font is bundled - a project
-// that wants its own loads it and overrides the stack.
+// Here and not next to the typography rules, because this is the file
+// `@use 'main' with (...)` configures. No font is bundled.
 $font-family-base:
   -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu,
   Cantarell, 'Helvetica Neue', sans-serif !default;
@@ -650,9 +457,7 @@ $spacing: (
 );
 
 // Breakpoints
-// Card width at which a card footer stops being a row. Shared: the footer rule
-// lives in _cards.scss, the exception for a price in it in _pricing.scss, and
-// the two have to agree or a price gets the row back one pixel too late.
+// Shared by _cards.scss and _pricing.scss, which have to agree on it
 $mw-card-narrow: 360px !default;
 
 $breakpoints: (
@@ -669,7 +474,6 @@ $breakpoints: (
   '2xl': 1400px,
 );
 
-// Border radius
 $radius: (
   'none': 0,
   'xs': 2px,