@webority/theme 0.82.0 → 0.83.0

package/scss/_tokens.scss

@@ -8,99 +8,149 @@
 :root {
     // Extended primary ramp — neutral indigo default; used for tints,
     // washes, hovers. Products override --wui-primary* with their brand.
+    /// meaning: Brand primary fill for primary buttons, selected states and the first chart series.
     --wui-primary: #4F46E5;
+    /// meaning: Primary fill while a control is hovered.
     --wui-primary-hover: #6366F1;
+    /// meaning: Primary fill while a control is pressed or active.
     --wui-primary-pressed: #4338CA;
+    /// meaning: Strongest soft primary fill or border tint that follows dark mode.
     --wui-primary-50: #818CF8;
+    /// meaning: Medium soft primary fill or border tint that follows dark mode.
     --wui-primary-30: #A5B4FC;
+    /// meaning: Light soft primary fill or border tint that follows dark mode.
     --wui-primary-20: #C7D2FE;
+    /// meaning: Lighter soft primary fill or border tint that follows dark mode.
     --wui-primary-15: #DDE1FD;
+    /// meaning: Pale soft primary fill or border tint that follows dark mode.
     --wui-primary-10: #E0E7FF;
+    /// meaning: Faintest soft primary fill or border tint that follows dark mode.
     --wui-primary-5: #EEF2FF;
 
     // Foreground ramp (cool blue-grey neutrals) — for text hierarchy
     // beyond Bootstrap's body-color / body-secondary-color.
+    /// meaning: Heading ink for page and section titles.
     --wui-text-heading: #071437;
+    /// meaning: Primary body text, a step softer than the heading ink.
     --wui-text-1: #252F4A;
+    /// meaning: Secondary text for descriptions, sub-labels and muted copy.
     --wui-text-2: #4B5675;
     // Tertiary text — hints, captions, labels, timestamps, placeholders. Was #78829D,
     // which measured 3.5:1 on white and 3.1:1 on a tinted panel: below WCAG AA (4.5:1)
     // everywhere it was used. A tier meant for readable-but-secondary copy has to BE
     // readable, so it darkens to 4.55:1 on every neutral surface. It stays clearly
     // lighter than --wui-text-2; --wui-text-4/5 remain for genuinely decorative use.
+    /// meaning: Tertiary text for hints, captions, labels, timestamps and placeholders.
     --wui-text-3: #687088;
+    /// meaning: Decorative faint ink, not for text a person must read.
     --wui-text-4: #99A1B7;
+    /// meaning: Faintest ink, for decorative marks and the strong border tone.
     --wui-text-5: #C4CADA;
 
     // Surfaces
+    /// meaning: Page background behind every surface in light mode.
     --wui-bg-page: #F4F6F8;
+    /// meaning: White card and panel surface, the lightest fill in light mode.
     --wui-bg-light: #FFFFFF;
+    /// meaning: Subtle raised surface, one step off the page.
     --wui-bg-elevated: #F9FBFC;
+    /// meaning: Muted fill for grouped areas and quiet controls.
     --wui-bg-muted: #F5F6FA;
     // Resting fill for every input-like control (text field, select, textarea, and the
     // combobox/phone/date/number wrappers) — a touch lighter than --wui-bg-muted so fields read
     // as their own surface. Change here to restyle every field's background at once.
+    /// meaning: Resting fill of every input-like control, such as fields, selects and textareas.
     --wui-field-bg: #F9FBFC;
     // Resting and hover border of every input-like control: a soft edge a step darker than
     // --wui-border-light, and the --wui-text-5 hover. They sit under WCAG 1.4.11's 3:1 by
     // design choice; check-contrast reports them as FAIL without failing the gate.
+    /// meaning: Resting border of every input-like control.
     --wui-field-border: #DFE2EA;
+    /// meaning: Hover border of every input-like control.
     --wui-field-border-hover: #C4CADA;
+    /// meaning: Default hairline border of cards, tables and dividers.
     --wui-border-light: #EBEDF3;
+    /// meaning: Softest border, for inner dividers.
     --wui-border-soft: #F4F6F8;
     // The unfilled part of a progress bar / meter. Darker than every surface it can sit on
     // (card, page, muted fill) so the empty track reads as a track, yet light enough that the
     // mid-yellow warning fill still separates from it.
+    /// meaning: Unfilled track of a progress bar or meter.
     --wui-progress-track: #E1E5EE;
+    /// meaning: Inset of the table wrapper and toolbar, which a table class can retune.
+    --wui-table-pad: 20px;
 
     // Gradients (hero, CTA)
+    /// meaning: Background gradient of the hero band on marketing pages.
     --wui-hero-gradient:
         radial-gradient(ellipse 120% 80% at 50% 30%,
             #818CF8 0%, #4F46E5 35%, #4338CA 75%, #312E81 100%);
+    /// meaning: Background gradient of the call-to-action band on marketing pages.
     --wui-cta-gradient:
         radial-gradient(ellipse 120% 100% at 50% 50%,
             #312E81 0%, #1E1B4B 60%, #0F0D2E 100%);
 
     // Easing curves — match locked design's CSS / Framer Motion exports
+    /// meaning: Easing curve matching the locked design's motion exports.
     --wui-ease-out-quart: cubic-bezier(0.22, 1, 0.36, 1);
+    /// meaning: Easing curve for interface transitions.
     --wui-ease-ui: cubic-bezier(0.32, 0.72, 0, 1);
     // Elastic / spring — overshoots the target then settles (the y > 1 control point).
     // Used by the tab ink-bar so a tab switch springs into place rather than sliding flat.
+    /// meaning: Overshooting easing for the tab ink bar's spring into place.
     --wui-ease-elastic: cubic-bezier(0.34, 1.56, 0.64, 1);
 
     // Elevation. In-page card tokens are flat (none). Overlay
     // rungs match $wui-shadow-overlay* in _variables.scss — one ink for menus,
     // popovers, modals. Do not hand-roll a third shadow.
+    /// meaning: Shadow under in-page cards, none in this theme so cards stay flat.
     --wui-shadow-card: none;
+    /// meaning: Shadow of a lifted card, none in this theme.
     --wui-shadow-card-lifted: none;
+    /// meaning: Shadow of a lifted card while it is hovered, none in this theme.
     --wui-shadow-card-lifted-hover: none;
+    /// meaning: Shadow of floating overlays such as menus and popovers.
     --wui-shadow-overlay: #{$wui-shadow-overlay};
+    /// meaning: Larger overlay shadow, for the largest floating surfaces.
     --wui-shadow-overlay-lg: #{$wui-shadow-overlay-lg};
 
     // Component-specific shadows. Used by slider thumbs and other interactive elements.
+    /// meaning: Shadow under a slider thumb and other small interactive elements.
     --wui-shadow-thumb: 0 2px 6px rgba(0, 0, 0, 0.1);
+    /// meaning: Shadow under a slider thumb while it is hovered.
     --wui-shadow-thumb-hover: 0 2px 12px rgba(0, 0, 0, 0.2);
 
     // The control height ladder: sm 32, md 36, lg 44. A button, field, select, segmented control, tab
     // or chip of one size shares its height, so a row of mixed controls lines up. On a phone-width or
     // touch screen md rises to 44px, the touch-target floor (media rule after this block).
+    /// meaning: Default height of a button, field, select or tab; larger on phones.
     --wui-control-height: 36px;
+    /// meaning: Height of the small control size, for dense toolbars and chips.
     --wui-control-height-sm: 32px;
+    /// meaning: Height of the large control size, for prominent buttons and fields.
     --wui-control-height-lg: 44px;
 
     // Scrollbar thumb — one quiet grey-blue at three interaction strengths.
+    /// meaning: Resting thumb colour of a thin scrollbar.
     --wui-scrollbar: rgba(145, 158, 171, 0.45);
+    /// meaning: Scrollbar thumb colour while it is hovered.
     --wui-scrollbar-hover: rgba(145, 158, 171, 0.65);
+    /// meaning: Scrollbar thumb colour while it is dragged.
     --wui-scrollbar-active: rgba(145, 158, 171, 0.85);
 
     // ---- Marketing surface ramp -------------------------------------
     // Soft tints + neutral washes used by mega-menu hover, callout cards,
     // and section accents. Distinct from --wui-bg-* (which are the
     // platform/portal palette).
+    /// meaning: Soft tint surface for marketing callouts and mega-menu hover.
     --wui-surface-soft: #F2EFFE;
+    /// meaning: Violet-tinted surface for marketing section accents and callout cards.
     --wui-surface-violet: #ECE4FE;
+    /// meaning: Near-white surface for marketing section accents.
     --wui-surface-violet-soft: #FCFCFC;
+    /// meaning: Neutral wash surface for marketing sections and panels.
     --wui-surface-mute: #F9FBFC;
+    /// meaning: Pure black ink, the highest-contrast text colour.
     --wui-ink: #000000;
 
     // ---- Foreground ramp aliases -----------------------------------
@@ -108,28 +158,39 @@
     // These point at the same hex values as --wui-text-* (kept as
     // aliases rather than duplicated literals so a re-tune of the text
     // ramp updates both sides at once).
+    /// meaning: Marketing alias of the primary body text ink.
     --wui-fg-2: var(--wui-text-1);
+    /// meaning: Marketing alias of the secondary text ink.
     --wui-fg-3: var(--wui-text-2);
+    /// meaning: Marketing alias of the tertiary text ink.
     --wui-fg-4: var(--wui-text-3);
+    /// meaning: Marketing alias of the faintest text ink.
     --wui-fg-5: var(--wui-text-5);
 
     // ---- Neutral ramp ----------------------------------------------
     // Used by table emphasis, dividers, and mega-menu hover surfaces.
+    /// meaning: Border tone of table emphasis rows and dividers.
     --wui-neutral-border-dark: #EBEDF3;
+    /// meaning: Faintest border tone, for dividers.
     --wui-neutral-border-light: #F9FBFC;
+    /// meaning: Muted background of table emphasis rows and mega-menu hover.
     --wui-neutral-bg-dark: #F5F6FA;
+    /// meaning: Faint background for table emphasis and mega-menu hover.
     --wui-neutral-bg-light: #F9FBFC;
 
     // ---- Accent-dark -----------------------------------------------
     // Darker primary for pressed/hover accents in CSS (not SCSS $link-hover).
     // Aliased onto --wui-primary-pressed so a product that rebrands the pressed
     // token once also updates this name (was a frozen indigo hex).
+    /// meaning: Pressed and hover accent colour in CSS, following the pressed primary.
     --wui-accent-dark: var(--wui-primary-pressed);
 
     // ---- Container width + responsive padding ----------------------
     // The standalone design uses a 1512px max canvas with generous side
     // padding that grows on wider viewports. Pair with .container-cloves.
+    /// meaning: Maximum width of the page container on every surface.
     --wui-container-max: 1512px;
+    /// meaning: Side padding of the page container, growing on wider viewports.
     --wui-container-pad: 24px;
 
     // ---- Primary "on-fill" text --------------------------------------
@@ -139,6 +200,7 @@
     // an active pagination page, a checked segmented option, .btn-primary's label.
     // Derived from $primary (_variables.scss): white when it clears AA on the primary, near-black
     // when the primary is too light for white. A runtime rebrand of --wui-primary sets it too.
+    /// meaning: Text and icon colour on a solid primary fill, such as a primary button label.
     --wui-primary-text: #{wui-hex($wui-primary-text)};
 
     // ---- Primary as text -----------------------------------------------
@@ -146,19 +208,28 @@
     // its own soft tint (_variables.scss). Every link, tab label, page number, selected option and
     // primary-coloured icon reads this, never --wui-primary, which is sized as a fill. Equal to
     // --wui-primary when the primary already clears AA. A runtime rebrand of --wui-primary sets it too.
+    /// meaning: Primary as text and small glyphs on light surfaces, passing AA contrast.
     --wui-primary-ink: #{wui-hex($wui-primary-ink)};
 
     // ---- Semantic status ramps -------------------------------------
     // Canonical info/success/warning/danger scales: `active` (text/icon on
     // light), the base `100` (vivid fills/dots), then tints 50/30/20/10/5.
     // Shared by the portal (aliased to --color-*) and marketing alerts/badges.
+    /// meaning: Info colour as text on light surfaces.
     --wui-info-text: #1460ba;
+    /// meaning: Info ink for icons and active states on light surfaces.
     --wui-info-active: #056EE9;
+    /// meaning: Vivid info fill for badges, dots and info buttons.
     --wui-info: #056EE9;
+    /// meaning: Info tint 50 for borders and the strongest soft info fill.
     --wui-info-50: #8DC2FF;
+    /// meaning: Info tint 30 for soft fills and borders of alerts and badges.
     --wui-info-30: #BBDBFF;
+    /// meaning: Info tint 20 for soft fills behind info alerts and badges.
     --wui-info-20: #D1E6FF;
+    /// meaning: Info tint 10, the soft background of info alerts and badges.
     --wui-info-10: #E9F3FF;
+    /// meaning: Faintest info tint, for hover washes and soft info backgrounds.
     --wui-info-5: #F3F9FF;
 
     // `-text` variants exist because the status colours are FILLS. #E82646 and #04B440
@@ -166,27 +237,44 @@
     // (4.4:1 and 2.8:1) — which is how a validation error message, of all things, came
     // to be unreadable. Darkening the base tokens would change every red button and
     // green badge in the system, so text gets its own value and the fills keep theirs.
+    /// meaning: Success colour as text on light surfaces, darkened to pass AA.
     --wui-success-text: #0e7531;
     // Deepened success fill for surfaces that carry WHITE text (progress-bar labels), mirroring
     // --wui-danger-strong below. The brighter --wui-success/-active are far too light for white
     // (2.78:1 / 2.78:1, under AA); this clears it (#0e7531 → 5.82:1). Keep white-on-success off
     // the other tokens so buttons/badges keep the vibrant fill.
+    /// meaning: Deep success fill behind white text, such as progress-bar labels.
     --wui-success-strong: #0e7531;
+    /// meaning: Active success fill, the deepest vivid success tone.
     --wui-success-active: #04B440;
+    /// meaning: Vivid success fill for badges, dots and success buttons.
     --wui-success: #04B440;
+    /// meaning: Success tint 50 for borders and the strongest soft success fill.
     --wui-success-50: #8BE3A9;
+    /// meaning: Success tint 30 for soft fills and borders of alerts and badges.
     --wui-success-30: #BAEECC;
+    /// meaning: Success tint 20 for soft fills behind success alerts and badges.
     --wui-success-20: #D1F4DD;
+    /// meaning: Success tint 10, the soft background of success alerts and badges.
     --wui-success-10: #E8FAEE;
+    /// meaning: Faintest success tint, for hover washes and soft success backgrounds.
     --wui-success-5: #F3FCF6;
 
+    /// meaning: Warning colour as text on light surfaces, darkened to pass AA.
     --wui-warning-text: #876100;
+    /// meaning: Active warning fill, the deepest vivid warning tone.
     --wui-warning-active: #DFA000;
+    /// meaning: Vivid warning fill for badges, dots and warning buttons.
     --wui-warning: #DFA000;
+    /// meaning: Warning tint 50 for borders and the strongest soft warning fill.
     --wui-warning-50: #FBD880;
+    /// meaning: Warning tint 30 for soft fills and borders of alerts and badges.
     --wui-warning-30: #FDE8B3;
+    /// meaning: Warning tint 20 for soft fills behind warning alerts and badges.
     --wui-warning-20: #FDEFCC;
+    /// meaning: Warning tint 10, the soft background of warning alerts and badges.
     --wui-warning-10: #FFF8E6;
+    /// meaning: Faintest warning tint, for hover washes and soft warning backgrounds.
     --wui-warning-5: #FEFBF2;
 
     // Error TEXT red. Shares the brand hue (350°) with --wui-danger-active (#E82646) but is
@@ -195,31 +283,48 @@
     // #E82646 is only 3.81:1. Do NOT swap this back to --wui-danger-active: that has been tried
     // three times and each time the a11y gate rejected the release. The brand red stays in use
     // for non-text danger (fills, borders, icons), which carry a 3:1 floor instead.
+    /// meaning: Error text colour for validation messages and danger text on light surfaces.
     --wui-danger-text: #CF1735;
     // Deepened danger fill for surfaces that carry WHITE text (btn-danger). The brighter
     // --wui-danger/-active below are too light for white (3.86:1 / 4.38:1, under AA); these
     // clear it — #C81340 → 5.80:1, hover → higher. Keep white-on-danger off the other tokens.
+    /// meaning: Deep danger fill behind white text, such as the danger button.
     --wui-danger-strong: #C81340;
+    /// meaning: Deep danger fill while a danger button with white text is hovered.
     --wui-danger-strong-hover: #AB1036;
+    /// meaning: Active danger fill, the deepest vivid danger tone.
     --wui-danger-active: #E82646;
+    /// meaning: Vivid danger fill for badges, dots and danger buttons.
     --wui-danger: #E82646;
+    /// meaning: Danger tint 50 for borders and the strongest soft danger fill.
     --wui-danger-50: #FC94AD;
+    /// meaning: Danger tint 30 for soft fills and borders of alerts and badges.
     --wui-danger-30: #FDBFCE;
+    /// meaning: Danger tint 20 for soft fills behind danger alerts and badges.
     --wui-danger-20: #FED4DE;
+    /// meaning: Danger tint 10, the soft background of danger alerts and badges.
     --wui-danger-10: #FFEAEF;
+    /// meaning: Faintest danger tint, for hover washes and soft danger backgrounds.
     --wui-danger-5: #FEF4F6;
 
     // Corner radii (DESIGN.md scale) — portal aliases as --radius-*
+    /// meaning: Small step of the corner radius scale.
     --wui-radius-sm: 8px;
+    /// meaning: Default step of the corner radius scale.
     --wui-radius: 10px;
+    /// meaning: Large step of the corner radius scale.
     --wui-radius-lg: 14px;
+    /// meaning: Extra-large step of the corner radius scale.
     --wui-radius-xl: 16px;
 
     // Field (input/select/datepicker/…) radius — a flat 8px corner across every
     // size, for a crisp plain-rounded field (no squircle). Change here to restyle
     // every field's corner at once.
+    /// meaning: Corner radius of every input-like control.
     --wui-field-radius: 8px;
+    /// meaning: Corner radius of a small input-like control.
     --wui-field-radius-sm: 8px;
+    /// meaning: Corner radius of a large input-like control.
     --wui-field-radius-lg: 8px;
 
     // ---- Chart colours ---------------------------------------------------
@@ -227,79 +332,135 @@
     // primary, so a product's rebrand reaches its charts; 2 to 8 were checked against it for
     // colour-blind separation (worst neighbouring pair ΔE 9.1). Aqua, yellow and pink sit under
     // 3:1 on white, which is why every chart also has a legend and a data table.
+    /// meaning: Colour of chart series 1, the brand primary.
     --wui-chart-1: var(--wui-primary);
+    /// meaning: Colour of chart series 2 of the eight categorical series.
     --wui-chart-2: #eb6834;
+    /// meaning: Colour of chart series 3 of the eight categorical series.
     --wui-chart-3: #1baf7a;
+    /// meaning: Colour of chart series 4 of the eight categorical series.
     --wui-chart-4: #eda100;
+    /// meaning: Colour of chart series 5 of the eight categorical series.
     --wui-chart-5: #e87ba4;
+    /// meaning: Colour of chart series 6 of the eight categorical series.
     --wui-chart-6: #008300;
+    /// meaning: Colour of chart series 7 of the eight categorical series.
     --wui-chart-7: #2a78d6;
+    /// meaning: Colour of chart series 8 of the eight categorical series.
     --wui-chart-8: #e34948;
     // One-hue ramp for magnitude (heatmap cells, calendar days), faint to strong, on the primary.
+    /// meaning: Faintest step of the magnitude ramp, for empty heatmap and calendar cells.
     --wui-chart-seq-0: var(--wui-bg-muted);
+    /// meaning: First step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-1: var(--wui-primary-10);
+    /// meaning: Second step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-2: var(--wui-primary-20);
+    /// meaning: Third step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-3: var(--wui-primary-30);
+    /// meaning: Fourth step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-4: var(--wui-primary-50);
+    /// meaning: Fifth step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-5: var(--wui-primary-hover);
+    /// meaning: Strongest step of the one-hue magnitude ramp for heatmap and calendar cells.
     --wui-chart-seq-6: var(--wui-primary-pressed);
     // Below and above a midpoint (variance, change against a target), with a grey middle.
+    /// meaning: Colour of values below the midpoint in a diverging chart.
     --wui-chart-diverging-low: #e34948;
+    /// meaning: Neutral midpoint colour of a diverging chart.
     --wui-chart-diverging-mid: #c4cada;
+    /// meaning: Colour of values above the midpoint in a diverging chart.
     --wui-chart-diverging-high: #2a78d6;
     // A context series (last period) and a donut's folded Other slice.
+    /// meaning: Context series colour, such as the last period, and the folded Other slice.
     --wui-chart-neutral: #99a1b7;
     // Ink: gridlines, the axis line, and tick and legend text. Aliases, so dark follows --color-*.
+    /// meaning: Gridline colour of charts.
     --wui-chart-grid: var(--color-border);
+    /// meaning: Axis line colour of charts.
     --wui-chart-axis: var(--color-border-strong);
+    /// meaning: Tick and legend text colour of charts.
     --wui-chart-label: var(--color-text-subtle);
 
     // ---- Portal dark palette ----------------------------------------
     // Marketing stays light. Portal flips [data-theme="dark"] and maps
     // --color-* aliases onto these so dark hexes live in theme/, not the app.
+    /// meaning: Dark page background, the base of every dark-mode surface.
     --wui-dark-bg-page: #0f1117;
+    /// meaning: Subtle dark background, one step off the dark page.
     --wui-dark-bg-elevated: #0d0f15;
+    /// meaning: Dark muted fill for grouped areas and quiet controls.
     --wui-dark-bg-muted: #232733;
+    /// meaning: Dark card and panel surface, one step above the dark page.
     --wui-dark-bg-surface: #181b23;
+    /// meaning: Dark hairline border of cards, tables and dividers.
     --wui-dark-border: #2a2f3a;
+    /// meaning: Stronger dark border for emphasised separators.
     --wui-dark-border-strong:#3a414f;
     // Field borders on the dark fills: the dark border and strong border values.
+    /// meaning: Resting border of input-like controls in dark mode.
     --wui-dark-field-border: #2a2f3a;
+    /// meaning: Hover border of input-like controls in dark mode.
     --wui-dark-field-border-hover: #3a414f;
     // Lighter than the dark page, surface and muted fill, so the empty track shows on all three.
+    /// meaning: Unfilled track of a progress bar or meter in dark mode.
     --wui-dark-progress-track: #323845;
+    /// meaning: Primary body text colour in dark mode.
     --wui-dark-text: #e6e8ee;
+    /// meaning: Secondary text colour in dark mode.
     --wui-dark-text-muted: #b4b9c6;
+    /// meaning: Tertiary text colour in dark mode, for hints and captions.
     --wui-dark-text-subtle: #8a90a0;
     // Primary as TEXT, rings and focus borders, and as the fill under near-black ink: the brand
     // primary lifted until it clears 4.5:1 on every dark surface and tint (_variables.scss), so a
     // brand set with wui-brand-primary reaches dark mode. A runtime override must clear the same.
+    /// meaning: Primary as text, rings, focus borders and the fill under dark ink in dark mode.
     --wui-dark-primary: #{wui-hex($wui-dark-primary)};
+    /// meaning: Primary fill while it is hovered in dark mode.
     --wui-dark-primary-hover: #{wui-hex($wui-dark-primary-hover)};
 
     // Dark mode shadow remaps — lighter shadows (white ink) for visibility on dark surfaces.
+    /// meaning: Slider thumb shadow in dark mode, drawn with light ink.
     --wui-dark-shadow-thumb: 0 2px 6px rgba(255, 255, 255, 0.1);
+    /// meaning: Slider thumb shadow while it is hovered in dark mode.
     --wui-dark-shadow-thumb-hover: 0 2px 12px rgba(255, 255, 255, 0.2);
 
     // Dark chart colours, mapped onto --wui-chart-* by the dark theme (_wui-aliases.scss); slot 1
     // follows --wui-dark-primary. The series set clears 3:1 on the dark page colour.
+    /// meaning: Dark-mode colour of chart series 2 of the categorical set.
     --wui-dark-chart-2: #d95926;
+    /// meaning: Dark-mode colour of chart series 3 of the categorical set.
     --wui-dark-chart-3: #199e70;
+    /// meaning: Dark-mode colour of chart series 4 of the categorical set.
     --wui-dark-chart-4: #c98500;
+    /// meaning: Dark-mode colour of chart series 5 of the categorical set.
     --wui-dark-chart-5: #d55181;
+    /// meaning: Dark-mode colour of chart series 6 of the categorical set.
     --wui-dark-chart-6: #008300;
+    /// meaning: Dark-mode colour of chart series 7 of the categorical set.
     --wui-dark-chart-7: #3987e5;
+    /// meaning: Dark-mode colour of chart series 8 of the categorical set.
     --wui-dark-chart-8: #e66767;
+    /// meaning: Dark-mode faintest step of the magnitude ramp, for empty heatmap cells.
     --wui-dark-chart-seq-0: #20242f;
+    /// meaning: Dark-mode first step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-1: #262c45;
+    /// meaning: Dark-mode second step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-2: #2f3a70;
+    /// meaning: Dark-mode third step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-3: #3b4ba0;
+    /// meaning: Dark-mode fourth step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-4: #5168d2;
+    /// meaning: Dark-mode fifth step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-5: #7a90ef;
+    /// meaning: Dark-mode strongest step of the magnitude ramp for heatmap and calendar cells.
     --wui-dark-chart-seq-6: #b3c1f7;
+    /// meaning: Dark-mode colour of values below the midpoint in a diverging chart.
     --wui-dark-chart-diverging-low: #e66767;
+    /// meaning: Dark-mode neutral midpoint colour of a diverging chart.
     --wui-dark-chart-diverging-mid: #3a414f;
+    /// meaning: Dark-mode colour of values above the midpoint in a diverging chart.
     --wui-dark-chart-diverging-high: #3987e5;
+    /// meaning: Dark-mode context series colour, such as the last period.
     --wui-dark-chart-neutral: #5d6475;
 
     // ---- Fluid type scale --------------------------------------------
@@ -307,12 +468,19 @@
     // stepping at Bootstrap's breakpoints. `base` sits close to Bootstrap's own 1rem body
     // size; every other step is derived at a consistent ratio, up and down. Additive only —
     // nothing in the shared theme consumes these yet, a product opts in per element.
+    /// meaning: Extra-small step of the fluid type scale; a product opts in per element.
     --wui-fs-xs: clamp(0.75rem, 0.73rem + 0.1vw, 0.8125rem);
+    /// meaning: Small step of the fluid type scale; a product opts in per element.
     --wui-fs-sm: clamp(0.8125rem, 0.79rem + 0.12vw, 0.875rem);
+    /// meaning: Body-size step of the fluid type scale, close to Bootstrap's 1rem.
     --wui-fs-base: clamp(0.95rem, 0.9rem + 0.25vw, 1.05rem);
+    /// meaning: Large step of the fluid type scale; a product opts in per element.
     --wui-fs-lg: clamp(1.05rem, 0.98rem + 0.35vw, 1.25rem);
+    /// meaning: Extra-large step of the fluid type scale; a product opts in per element.
     --wui-fs-xl: clamp(1.25rem, 1.15rem + 0.5vw, 1.5rem);
+    /// meaning: Double extra-large step of the fluid type scale; a product opts in per element.
     --wui-fs-2xl: clamp(1.5rem, 1.3rem + 1vw, 2rem);
+    /// meaning: Triple extra-large step of the fluid type scale; a product opts in per element.
     --wui-fs-3xl: clamp(1.875rem, 1.5rem + 1.75vw, 2.75rem);
 
     // ---- Font stacks ---------------------------------------------------
@@ -324,6 +492,7 @@
     // $font-family-base so a product can point ONLY its display headings (.h-display) at a
     // serif or another brand face by overriding this one token, without touching body copy.
     // Defaults to Webority Serif ($font-family-display).
+    /// meaning: Display typeface for headings marked as display text.
     --wui-font-display: #{$font-family-display};
 
     // ---- Z-index scale -------------------------------------------------
@@ -336,26 +505,41 @@
     // (select / date / phone / infotip) sit at 1600 so a combobox inside a modal
     // is not trapped under the dialog. Never invent a third number in component CSS —
     // pick a rung from this list.
+    /// meaning: Stacking layer of in-page dropdown menus.
     --wui-z-dropdown: 1000;
+    /// meaning: Stacking layer of sticky page chrome such as headers.
     --wui-z-sticky: 1020;
     // Desktop shell sidebar: its overflowing menus (the workspace switcher) paint over sticky page
     // content, while the fixed corner layers (consent banner, floating buttons) still cover it.
+    /// meaning: Stacking layer of the desktop shell sidebar and its overflowing menus.
     --wui-z-shell-sidebar: 1025;
+    /// meaning: Stacking layer of fixed corner layers such as the consent banner.
     --wui-z-fixed: 1030;
+    /// meaning: Stacking layer of the app shell base chrome and the splash.
     --wui-z-shell: 1040; // splash, shell base chrome
+    /// meaning: Stacking layer of the dim behind the mobile drawer.
     --wui-z-shell-scrim: 1044; // mobile drawer scrim
+    /// meaning: Stacking layer of the mobile sidebar drawer.
     --wui-z-shell-drawer: 1045; // mobile sidebar drawer
+    /// meaning: Stacking layer of the dim behind a modal dialog.
     --wui-z-modal-backdrop: 1500;
+    /// meaning: Stacking layer of a modal dialog above its backdrop.
     --wui-z-modal: 1505;
+    /// meaning: Stacking layer of the product tour, above modals and below menus.
     --wui-z-tour: 1550; // product tour: above a modal, below menus and popovers
+    /// meaning: Stacking layer of portalled select, date and phone menus and info tips.
     --wui-z-menu: 1600; // portalled select/date/phone menus + infotip
+    /// meaning: Stacking layer of popovers, on the same rung as menus.
     --wui-z-popover: 1600; // same rung as --wui-z-menu (above modal)
+    /// meaning: Stacking layer of tooltips, above menus and popovers.
     --wui-z-tooltip: 1650;
+    /// meaning: Stacking layer of toast notifications, the topmost layer.
     --wui-z-toast: 1700;
 
     // The weekday every calendar's week starts on: the date picker, the date range and the event
     // calendar. 0 = Sunday, 1 = Monday, through 6 = Saturday. A product sets it once here, a page or
     // a section can set it on an ancestor, and a control's own first-day attribute wins over both.
+    /// meaning: Weekday calendars start their week on, from 0 for Sunday to 6 for Saturday.
     --wui-first-day: 1;
 }