@keenmate/pure-css 1.0.0-rc03 → 1.0.0-rc05

package/src/scss/_base-css-variables.scss

@@ -146,80 +146,21 @@
   --base-border-radius-lg: #{$base-border-radius-lg};
 }
 
-// ============================================================================
-// ALERT COLOR DERIVATION MIXINS
-// ============================================================================
-// These mixins use color-mix() to automatically derive alert colors from
-// semantic base colors (--pa-success-bg, --pa-danger-bg, etc.)
-//
-// Light mode: dark text on subtle backgrounds
-// Dark mode: light text on tinted backgrounds
-//
-// Themes call the appropriate mixin instead of hardcoding 12+ CSS variables.
-// Override specific variables after the mixin call if needed.
-// ============================================================================
-
-// Light mode: dark text on subtle backgrounds
-@mixin output-pa-alert-variables-light {
-  // Success
-  --pa-alert-success-text: color-mix(in srgb, var(--pa-success-bg) #{$alert-text-mix-light}, black);
-  --pa-alert-success-bg: color-mix(in srgb, var(--pa-success-bg) #{$alert-bg-opacity-light}%, transparent);
-  --pa-alert-success-border: color-mix(in srgb, var(--pa-success-bg) #{$alert-border-opacity-light}%, transparent);
-
-  // Danger
-  --pa-alert-danger-text: color-mix(in srgb, var(--pa-danger-bg) #{$alert-text-mix-light}, black);
-  --pa-alert-danger-bg: color-mix(in srgb, var(--pa-danger-bg) #{$alert-bg-opacity-light}%, transparent);
-  --pa-alert-danger-border: color-mix(in srgb, var(--pa-danger-bg) #{$alert-border-opacity-light}%, transparent);
-
-  // Warning
-  --pa-alert-warning-text: color-mix(in srgb, var(--pa-warning-bg) #{$alert-text-mix-light}, black);
-  --pa-alert-warning-bg: color-mix(in srgb, var(--pa-warning-bg) #{$alert-bg-opacity-light}%, transparent);
-  --pa-alert-warning-border: color-mix(in srgb, var(--pa-warning-bg) #{$alert-border-opacity-light}%, transparent);
-
-  // Info
-  --pa-alert-info-text: color-mix(in srgb, var(--pa-info-bg) #{$alert-text-mix-light}, black);
-  --pa-alert-info-bg: color-mix(in srgb, var(--pa-info-bg) #{$alert-bg-opacity-light}%, transparent);
-  --pa-alert-info-border: color-mix(in srgb, var(--pa-info-bg) #{$alert-border-opacity-light}%, transparent);
-}
-
-// Dark mode: white text on tinted backgrounds (white text is always readable)
-@mixin output-pa-alert-variables-dark {
-  // Success
-  --pa-alert-success-text: #ffffff;
-  --pa-alert-success-bg: color-mix(in srgb, var(--pa-success-bg) #{$alert-bg-opacity-dark}%, transparent);
-  --pa-alert-success-border: color-mix(in srgb, var(--pa-success-bg) #{$alert-border-opacity-dark}%, transparent);
-
-  // Danger
-  --pa-alert-danger-text: #ffffff;
-  --pa-alert-danger-bg: color-mix(in srgb, var(--pa-danger-bg) #{$alert-bg-opacity-dark}%, transparent);
-  --pa-alert-danger-border: color-mix(in srgb, var(--pa-danger-bg) #{$alert-border-opacity-dark}%, transparent);
-
-  // Warning
-  --pa-alert-warning-text: #ffffff;
-  --pa-alert-warning-bg: color-mix(in srgb, var(--pa-warning-bg) #{$alert-bg-opacity-dark}%, transparent);
-  --pa-alert-warning-border: color-mix(in srgb, var(--pa-warning-bg) #{$alert-border-opacity-dark}%, transparent);
-
-  // Info
-  --pa-alert-info-text: #ffffff;
-  --pa-alert-info-bg: color-mix(in srgb, var(--pa-info-bg) #{$alert-bg-opacity-dark}%, transparent);
-  --pa-alert-info-border: color-mix(in srgb, var(--pa-info-bg) #{$alert-border-opacity-dark}%, transparent);
-}
-
 // ============================================================================
 // DERIVED TOKENS — TEXT CONTRAST TIERS + SURFACE TINTS
 // ============================================================================
-// These tokens use `color-mix(... var(--pa-text-color-1) ...)` to derive
+// These tokens use `color-mix(... var(--pc-text-color-1) ...)` to derive
 // theme-aware contrast levels. They MUST be emitted at every selector that
-// could carry an override of --pa-text-color-1, because CSS custom property
+// could carry an override of --pc-text-color-1, because CSS custom property
 // substitution bakes nested var() references at the *defining element*, not
-// the using element. If we only defined these at `:root, .pa-mode-light`,
+// the using element. If we only defined these at `:root, .pc-mode-light`,
 // the light-mode text colour would be frozen into the value, and elements
-// inside `.pa-mode-dark` (which overrides --pa-text-color-1 at body) would
+// inside `.pc-mode-dark` (which overrides --pc-text-color-1 at body) would
 // inherit the light-mode-baked tier values → low contrast on dark surfaces.
 //
 // Emitting at all three selectors causes each scope to recompute the tiers
-// against its own --pa-text-color-1. The selector list `:root, .pa-mode-light,
-// .pa-mode-dark` covers html, body in light mode, and body in dark mode —
+// against its own --pc-text-color-1. The selector list `:root, .pc-mode-light,
+// .pc-mode-dark` covers html, body in light mode, and body in dark mode —
 // regardless of which class layout each theme uses for mode switching.
 //
 // This is a TOP-LEVEL rule (not inside the mixin) because themes only call
@@ -228,421 +169,455 @@
 // dark-mode tiers without changing any theme code.
 //
 // Override these per-theme by redefining them in the same scope you
-// override --pa-text-color-1.
+// override --pc-text-color-1.
 // ============================================================================
 
 :root,
-.pa-mode-light,
-.pa-mode-dark {
-  --pa-text-strong:    color-mix(in srgb, var(--pa-text-color-1) 85%, transparent);
-  --pa-text-secondary: color-mix(in srgb, var(--pa-text-color-1) 70%, transparent);
-  --pa-text-tertiary:  color-mix(in srgb, var(--pa-text-color-1) 55%, transparent);
-  --pa-surface-hover:  color-mix(in srgb, var(--pa-text-color-1) 4%, transparent);
-  --pa-surface-track:  color-mix(in srgb, var(--pa-text-color-1) 12%, transparent);
+.pc-mode-light,
+.pc-mode-dark {
+  --pc-text-strong:    color-mix(in srgb, var(--pc-text-color-1) 85%, transparent);
+  --pc-text-secondary: color-mix(in srgb, var(--pc-text-color-1) 70%, transparent);
+  --pc-text-tertiary:  color-mix(in srgb, var(--pc-text-color-1) 55%, transparent);
+  --pc-surface-hover:  color-mix(in srgb, var(--pc-text-color-1) 4%, transparent);
+  --pc-surface-track:  color-mix(in srgb, var(--pc-text-color-1) 12%, transparent);
 }
 
 // ============================================================================
-// PURE ADMIN THEME CSS VARIABLES OUTPUT MIXIN
+// PURE-CSS FOUNDATION TOKENS — the base runtime custom-property contract
 // ============================================================================
-// This mixin outputs all themeable SCSS variables as --pa-* CSS custom properties.
-// Components use var(--pa-*) for runtime theme switching capability.
+// pure-css is a *foundation*: it ships only the BASE token contract — the
+// tokens its own CSS (grid / utilities / reboot / scrollbars) consumes, plus
+// the universal theming primitives (surfaces, text, accent, links, border,
+// the semantic role identities + their utility text colours, the theme
+// palette slots, and the border-radius scale).
 //
-// Usage in theme file:
-//   :root, .theme-light {
-//     @include output-pa-css-variables;
-//   }
-//   .theme-dark {
-//     @include output-pa-css-variables;
-//   }
+// COMPONENT tokens (buttons, cards, tables, modals, badges, tooltips, panels,
+// command palette, multiselect, sentiment scale, form spacing, the derived
+// contextual/alert surfaces, admin layout chrome, …) are NOT emitted here —
+// they are pure-admin's contract, emitted by pure-admin's
+// `output-pc-component-variables` + `output-pc-alert-variables-{light,dark}`.
+// Those mixins read the same shared $-variable vocabulary defined in
+// `variables/*`, so themes still override one place; only the *emission* of
+// component custom properties lives with the components that use them.
 // ============================================================================
 
-@mixin output-pa-css-variables {
-  // =========================================================================
-  // COLOR SCHEME SIGNAL
+@mixin output-pc-css-variables {
   // Tells the browser whether this scope is light or dark so native UA
-  // elements (scrollbars, form controls) and `light-dark()` resolve
-  // correctly. Drives web components (e.g. <web-multiselect>) that ship
-  // adaptive palettes via `light-dark()`. Override $theme-color-scheme
-  // before importing variables for always-dark themes; for dual-mode
-  // themes leave default `light` here and add `color-scheme: dark;` to
-  // the `.pa-mode-dark` block.
-  // =========================================================================
+  // elements (scrollbars, form controls) and `light-dark()` resolve correctly.
+  // Override $theme-color-scheme before importing variables for always-dark
+  // themes; for dual-mode themes leave `light` and add `color-scheme: dark;`
+  // to the `.pc-mode-dark` block.
   color-scheme: #{$theme-color-scheme};
 
-  // =========================================================================
-  // CORE COLORS
-  // =========================================================================
-
-  // Background colors
-  --pa-main-bg: #{$main-bg};
-  --pa-page-bg: #{$page-bg};
-  --pa-subtle-bg: #{$subtle-bg};
+  // Surfaces
+  --pc-main-bg: #{$main-bg};
+  --pc-page-bg: #{$page-bg};
+  --pc-subtle-bg: #{$subtle-bg};
 
-  // Text colors
-  --pa-text-color-1: #{$text-color-1};
-  --pa-text-color-2: #{$text-color-2};
+  // Text
+  --pc-text-color-1: #{$text-color-1};
+  --pc-text-color-2: #{$text-color-2};
 
-  // Accent colors
-  --pa-accent: #{$accent-color};
-  --pa-accent-hover: #{$accent-hover};
-  // -light derives from --pa-accent at runtime so theme overrides cascade.
-  // SCSS-only consumers still get $accent-light from variables/_base.scss via the !default chain.
-  --pa-accent-light: color-mix(in srgb, var(--pa-accent) 5%, transparent);
+  // Accent — -light derives from --pc-accent at runtime so theme overrides cascade.
+  --pc-accent: #{$accent-color};
+  --pc-accent-hover: #{$accent-hover};
+  --pc-accent-light: color-mix(in srgb, var(--pc-accent) 5%, transparent);
 
   // Links — derive from accent so theme overrides cascade automatically.
-  // Hover mixes 25% toward currentColor (inherited text colour at the use site),
-  // so it auto-darkens on light themes and auto-lightens on dark themes
-  // without per-mode declarations.
-  --pa-link-color: var(--pa-accent);
-  --pa-link-color-hover: color-mix(in srgb, var(--pa-link-color), currentColor 50%);
-  --pa-link-color-visited: var(--pa-link-color);
-
-  // Border. A pure pass-through of the base border colour — emit it as a live reference to
-  // --base-border-color (not a baked literal) so it follows a RUNTIME --base-* override (a
-  // theme toggling --base-border-color at :root/.pa-mode-dark), while the build-time value
-  // stays the fallback. Keeps utilities/components that read --pa-border-color theme-responsive.
-  --pa-border-color: var(--base-border-color, #{$border-color});
-
-  // =========================================================================
-  // ROLE COLORS — single source of truth for the four semantic roles.
-  // Button surfaces (--pa-btn-{success,warning,danger,info}-bg) and
-  // contextual surfaces (--pa-{success,warning,danger,info}-bg) below
-  // both reference these via var() so a theme can override one place
-  // and the change cascades everywhere.
-  //
-  // --pa-warning here is also the "off-target / approaching-limit" axis
-  // colour used by KPI components — orange-500, deliberately distinct
-  // from the previous Bootstrap yellow.
-  // =========================================================================
-
-  --pa-success: #{$base-success-color};
-  --pa-warning: #{$base-warning-color};
-  --pa-danger:  #{$base-danger-color};
-  --pa-info:    #{$base-info-color};
-
-  // =========================================================================
-  // SENTIMENT SCALE — 5-step direction-of-change.
-  // Used by KPI / data-display components for indicating directional
-  // movement (delta colours, sparkline trend colours, etc.).
-  // The middle three values alias the role colours so a theme that
-  // retunes --pa-success / --pa-danger automatically retunes the
-  // matching sentiment positions; the outliers (very-positive /
-  // very-negative) are explicit darker shades.
-  //
-  // Sentiment is on a *different axis* from role colours — direction
-  // (ordinal: -2 to +2) vs. urgency (categorical: success / warning /
-  // danger / info). They coexist intentionally.
-  // =========================================================================
-
-  --pa-very-positive: #{$base-very-positive};
-  --pa-positive:      var(--pa-success);
-  --pa-neutral:       #{$base-neutral};
-  --pa-negative:      var(--pa-danger);
-  --pa-very-negative: #{$base-very-negative};
-
-  // (Text contrast tiers and surface tints are emitted as a top-level rule
-  // OUTSIDE this mixin — see below — because their values use
-  // `var(--pa-text-color-1)` and CSS custom property substitution bakes
-  // nested var() at the *defining element*, not the using element. That
-  // means tier vars defined here at `:root, .pa-mode-light` would freeze
-  // the light-mode text colour into them; under `.pa-mode-dark` (which
-  // overrides --pa-text-color-1 at body) the tiers would still resolve
-  // against the light value. Emitting them at all three selectors
-  // simultaneously fixes the substitution scope.)
-
-  // =========================================================================
-  // CHART / SPARKLINE
-  // =========================================================================
-  // Single height token used by every KPI showcase that renders a sparkline
-  // / trendline (terminal grid, sparkline list, hero+supporting, bento).
-  // Centralised so the line proportions stay consistent across designs;
-  // override globally for taller or shorter trendlines, or per-component
-  // if a particular layout (e.g. a "hero" pattern) wants a different size.
-
-  --pa-chart-trendline-height: 3rem;
-  --pa-chart-trendline-stroke: 2.1;     // SVG user-space units (viewBox-relative)
-
-  // =========================================================================
-  // DETAIL POPOVER — Bloomberg-dark by default, regardless of host
-  // theme, for the terminal/data-dashboard aesthetic. Override the
-  // five tokens to adopt a theme-aware popover instead.
-  // =========================================================================
-
-  --pa-detail-bg:        rgba(15, 17, 21, 0.97);
-  --pa-detail-text:      #ffffff;
-  --pa-detail-row-label: rgba(255, 255, 255, 0.75);
-  --pa-detail-title:     rgba(255, 255, 255, 0.55);
-  --pa-detail-shadow:    0 1.4rem 3.6rem rgba(0, 0, 0, 0.55);
+  // Hover mixes 50% toward currentColor (inherited text colour at the use site),
+  // so it auto-darkens on light themes and auto-lightens on dark themes.
+  --pc-link-color: var(--pc-accent);
+  --pc-link-color-hover: color-mix(in srgb, var(--pc-link-color), currentColor 50%);
+  --pc-link-color-visited: var(--pc-link-color);
+
+  // Border — a live reference to --base-border-color (so a runtime --base-*
+  // override cascades), with the build-time value as the literal fallback.
+  --pc-border-color: var(--base-border-color, #{$border-color});
+
+  // Semantic role identities — the single source for the four roles. Component
+  // surfaces (--pc-*-bg, alerts, buttons) derive from these via var() in
+  // pure-admin, so retuning a role here cascades everywhere.
+  --pc-success: #{$base-success-color};
+  --pc-warning: #{$base-warning-color};
+  --pc-danger:  #{$base-danger-color};
+  --pc-info:    #{$base-info-color};
+
+  // Role text colours — consumed by the .text-{success,danger,warning,info}
+  // utilities (utilities.scss). Kept in the base contract for that reason.
+  --pc-success-text: #{$success-text};
+  --pc-danger-text:  #{$danger-text};
+  --pc-warning-text: #{$warning-text};
+  --pc-info-text:    #{$info-text};
+
+  // Theme palette slots (1–9) + paired contrast text. Consumed by the
+  // .text-color-* utilities; themes override $color-N for branded palettes.
+  --pc-color-1: #{$color-1};
+  --pc-color-2: #{$color-2};
+  --pc-color-3: #{$color-3};
+  --pc-color-4: #{$color-4};
+  --pc-color-5: #{$color-5};
+  --pc-color-6: #{$color-6};
+  --pc-color-7: #{$color-7};
+  --pc-color-8: #{$color-8};
+  --pc-color-9: #{$color-9};
+  --pc-color-1-text: #{$color-1-text};
+  --pc-color-2-text: #{$color-2-text};
+  --pc-color-3-text: #{$color-3-text};
+  --pc-color-4-text: #{$color-4-text};
+  --pc-color-5-text: #{$color-5-text};
+  --pc-color-6-text: #{$color-6-text};
+  --pc-color-7-text: #{$color-7-text};
+  --pc-color-8-text: #{$color-8-text};
+  --pc-color-9-text: #{$color-9-text};
+
+  // Border-radius scale
+  --pc-border-radius-sm: #{$border-radius-sm};
+  --pc-border-radius: #{$border-radius};
+  --pc-border-radius-lg: #{$border-radius-lg};
+}
+
+// ============================================================================
+// COMPONENT CSS VARIABLES — pure-admin's contract (DEFINED here, EMITTED there)
+// ============================================================================
+// These emit the component-scoped --pc-* tokens (buttons, cards, tables,
+// panels, badges, tooltips, command palette, multiselect, sentiment scale,
+// form spacing, the derived contextual/alert surfaces, admin layout chrome).
+//
+// They are DEFINED in pure-css only because they read the shared $-variable
+// vocabulary that lives in `variables/*` (in scope here via `@use variables/
+// index as *`); a Sass mixin resolves those globals from its definition site,
+// so it must be authored where the vocabulary is visible.
+//
+// They are NOT part of pure-css's shipped output: base.scss / pure-css.scss do
+// NOT call them, so the foundation bundle emits base tokens only. Consumers
+// that ship the components (pure-admin core, themes) opt in by calling
+// output-pc-component-variables + output-pc-alert-variables-{light,dark}
+// alongside output-pc-css-variables. This keeps the EMISSION with the
+// components while the shared token vocabulary stays single-sourced.
+// ============================================================================
+
+@mixin output-pc-component-variables {
+  // =========================================================================
+  // SENTIMENT SCALE — 5-step direction-of-change (KPI / data-display).
+  // Middle three alias the role colours so retuning --pc-success / --pc-danger
+  // retunes the matching sentiment positions; outliers are explicit shades.
+  // =========================================================================
+  --pc-very-positive: #{$base-very-positive};
+  --pc-positive:      var(--pc-success);
+  --pc-neutral:       #{$base-neutral};
+  --pc-negative:      var(--pc-danger);
+  --pc-very-negative: #{$base-very-negative};
+
+  // =========================================================================
+  // CHART / SPARKLINE — shared trendline sizing.
+  // =========================================================================
+  --pc-chart-trendline-height: 3rem;
+  --pc-chart-trendline-stroke: 2.1;     // SVG user-space units (viewBox-relative)
+
+  // =========================================================================
+  // DETAIL POPOVER — Bloomberg-dark by default regardless of host theme.
+  // Override the five tokens to adopt a theme-aware popover instead.
+  // =========================================================================
+  --pc-detail-bg:        rgba(15, 17, 21, 0.97);
+  --pc-detail-text:      #ffffff;
+  --pc-detail-row-label: rgba(255, 255, 255, 0.75);
+  --pc-detail-title:     rgba(255, 255, 255, 0.55);
+  --pc-detail-shadow:    0 1.4rem 3.6rem rgba(0, 0, 0, 0.55);
 
   // =========================================================================
   // LAYOUT COLORS
   // =========================================================================
 
   // Navbar
-  --pa-navbar-bg: #{$navbar-bg};
-  --pa-navbar-border-color: #{$navbar-border-color};
-  --pa-navbar-text: #{$navbar-text};
-  --pa-navbar-text-secondary: #{$navbar-text-secondary};
-  --pa-navbar-profile-name-color: #{$navbar-profile-name-color};
+  --pc-navbar-bg: #{$navbar-bg};
+  --pc-navbar-border-color: #{$navbar-border-color};
+  --pc-navbar-text: #{$navbar-text};
+  --pc-navbar-text-secondary: #{$navbar-text-secondary};
+  --pc-navbar-profile-name-color: #{$navbar-profile-name-color};
 
   // Sidebar
-  --pa-sidebar-bg: #{$sidebar-bg};
-  --pa-sidebar-text: #{$sidebar-text};
-  --pa-sidebar-text-secondary: #{$sidebar-text-secondary};
-  --pa-sidebar-submenu-bg: #{$sidebar-submenu-bg};
-  --pa-sidebar-submenu-hover-bg: #{$sidebar-submenu-hover-bg};
-  --pa-sidebar-submenu-active-bg: #{$sidebar-submenu-active-bg};
-  --pa-sidebar-submenu-active-text: #{$sidebar-submenu-active-text};
+  --pc-sidebar-bg: #{$sidebar-bg};
+  --pc-sidebar-text: #{$sidebar-text};
+  --pc-sidebar-text-secondary: #{$sidebar-text-secondary};
+  --pc-sidebar-submenu-bg: #{$sidebar-submenu-bg};
+  --pc-sidebar-submenu-hover-bg: #{$sidebar-submenu-hover-bg};
+  --pc-sidebar-submenu-active-bg: #{$sidebar-submenu-active-bg};
+  --pc-sidebar-submenu-active-text: #{$sidebar-submenu-active-text};
 
   // Footer
-  --pa-footer-bg: #{$footer-bg};
-  --pa-footer-border-color: #{$footer-border-color};
+  --pc-footer-bg: #{$footer-bg};
+  --pc-footer-border-color: #{$footer-border-color};
 
   // =========================================================================
   // BUTTON COLORS
   // =========================================================================
 
   // Primary (uses accent color)
-  --pa-btn-primary-bg: #{$btn-primary-bg};
-  --pa-btn-primary-bg-hover: #{$btn-primary-bg-hover};
-  // -light derives from --pa-btn-primary-bg at runtime so theme overrides cascade.
-  --pa-btn-primary-bg-light: color-mix(in srgb, var(--pa-btn-primary-bg) 5%, transparent);
-  --pa-btn-primary-text: #{$btn-primary-text};
+  --pc-btn-primary-bg: #{$btn-primary-bg};
+  --pc-btn-primary-bg-hover: #{$btn-primary-bg-hover};
+  --pc-btn-primary-bg-light: color-mix(in srgb, var(--pc-btn-primary-bg) 5%, transparent);
+  --pc-btn-primary-text: #{$btn-primary-text};
 
   // Secondary
-  --pa-btn-secondary-bg: #{$btn-secondary-bg};
-  --pa-btn-secondary-bg-hover: #{$btn-secondary-bg-hover};
-  --pa-btn-secondary-text: #{$btn-secondary-text};
-  // Outline-variant border + text colour. Defaults to --pa-btn-secondary-bg
-  // so the resting outline matches the colour the hover fill animates to.
-  // Was previously $btn-secondary-text (#ffffff) which rendered invisible on
-  // any light theme — pre-existing bug, not a 2.7.0 regression.
-  --pa-btn-secondary-outline-color: var(--pa-btn-secondary-bg);
+  --pc-btn-secondary-bg: #{$btn-secondary-bg};
+  --pc-btn-secondary-bg-hover: #{$btn-secondary-bg-hover};
+  --pc-btn-secondary-text: #{$btn-secondary-text};
+  --pc-btn-secondary-outline-color: var(--pc-btn-secondary-bg);
 
   // Success — bg references role colour for runtime cascade
-  --pa-btn-success-bg: var(--pa-success);
-  --pa-btn-success-bg-hover: #{$btn-success-bg-hover};
-  --pa-btn-success-text: #{$btn-success-text};
+  --pc-btn-success-bg: var(--pc-success);
+  --pc-btn-success-bg-hover: #{$btn-success-bg-hover};
+  --pc-btn-success-text: #{$btn-success-text};
 
   // Danger — bg references role colour for runtime cascade
-  --pa-btn-danger-bg: var(--pa-danger);
-  --pa-btn-danger-bg-hover: #{$btn-danger-bg-hover};
-  --pa-btn-danger-text: #{$btn-danger-text};
+  --pc-btn-danger-bg: var(--pc-danger);
+  --pc-btn-danger-bg-hover: #{$btn-danger-bg-hover};
+  --pc-btn-danger-text: #{$btn-danger-text};
 
   // Warning — bg references role colour for runtime cascade
-  --pa-btn-warning-bg: var(--pa-warning);
-  --pa-btn-warning-bg-hover: #{$btn-warning-bg-hover};
-  --pa-btn-warning-text: #{$btn-warning-text};
+  --pc-btn-warning-bg: var(--pc-warning);
+  --pc-btn-warning-bg-hover: #{$btn-warning-bg-hover};
+  --pc-btn-warning-text: #{$btn-warning-text};
 
   // Info — bg references role colour for runtime cascade
-  --pa-btn-info-bg: var(--pa-info);
-  --pa-btn-info-bg-hover: #{$btn-info-bg-hover};
-  --pa-btn-info-text: #{$btn-info-text};
+  --pc-btn-info-bg: var(--pc-info);
+  --pc-btn-info-bg-hover: #{$btn-info-bg-hover};
+  --pc-btn-info-text: #{$btn-info-text};
 
   // Light
-  --pa-btn-light-bg: #{$btn-light-bg};
-  --pa-btn-light-bg-hover: #{$btn-light-bg-hover};
-  --pa-btn-light-text: #{$btn-light-text};
+  --pc-btn-light-bg: #{$btn-light-bg};
+  --pc-btn-light-bg-hover: #{$btn-light-bg-hover};
+  --pc-btn-light-text: #{$btn-light-text};
 
   // Dark
-  --pa-btn-dark-bg: #{$btn-dark-bg};
-  --pa-btn-dark-bg-hover: #{$btn-dark-bg-hover};
-  --pa-btn-dark-text: #{$btn-dark-text};
-
-  // =========================================================================
-  // CONTEXTUAL/SEMANTIC COLORS
-  // =========================================================================
-
-  // Success — bg references role colour for runtime cascade.
-  // -light/-subtle/-border derive from --pa-success at runtime so theme overrides cascade.
-  // -hover stays compile-time (color.adjust-derived darker shade, not opacity-based).
-  --pa-success-bg: var(--pa-success);
-  --pa-success-bg-hover: #{$success-bg-hover};
-  --pa-success-bg-light: color-mix(in srgb, var(--pa-success) 10%, transparent);
-  --pa-success-bg-subtle: color-mix(in srgb, var(--pa-success) 8%, transparent);
-  --pa-success-border: color-mix(in srgb, var(--pa-success) 20%, transparent);
-  --pa-success-text: #{$success-text};
-  --pa-success-text-light: #{$success-text-light};
-
-  // Danger — bg references role colour for runtime cascade.
-  --pa-danger-bg: var(--pa-danger);
-  --pa-danger-bg-hover: #{$danger-bg-hover};
-  --pa-danger-bg-light: color-mix(in srgb, var(--pa-danger) 10%, transparent);
-  --pa-danger-bg-subtle: color-mix(in srgb, var(--pa-danger) 8%, transparent);
-  --pa-danger-border: color-mix(in srgb, var(--pa-danger) 20%, transparent);
-  --pa-danger-text: #{$danger-text};
-  --pa-danger-text-light: #{$danger-text-light};
-
-  // Warning — bg references role colour for runtime cascade.
-  --pa-warning-bg: var(--pa-warning);
-  --pa-warning-bg-hover: #{$warning-bg-hover};
-  --pa-warning-bg-light: color-mix(in srgb, var(--pa-warning) 10%, transparent);
-  --pa-warning-bg-subtle: color-mix(in srgb, var(--pa-warning) 8%, transparent);
-  --pa-warning-border: color-mix(in srgb, var(--pa-warning) 20%, transparent);
-  --pa-warning-text: #{$warning-text};
-  --pa-warning-text-light: #{$warning-text-light};
-
-  // Info — bg references role colour for runtime cascade.
-  --pa-info-bg: var(--pa-info);
-  --pa-info-bg-hover: #{$info-bg-hover};
-  --pa-info-bg-light: color-mix(in srgb, var(--pa-info) 10%, transparent);
-  --pa-info-bg-subtle: color-mix(in srgb, var(--pa-info) 8%, transparent);
-  --pa-info-border: color-mix(in srgb, var(--pa-info) 20%, transparent);
-  --pa-info-text: #{$info-text};
-  --pa-info-text-light: #{$info-text-light};
+  --pc-btn-dark-bg: #{$btn-dark-bg};
+  --pc-btn-dark-bg-hover: #{$btn-dark-bg-hover};
+  --pc-btn-dark-text: #{$btn-dark-text};
+
+  // =========================================================================
+  // CONTEXTUAL/SEMANTIC SURFACES — derive from the base role identities.
+  // -bg/-light/-subtle/-border derive at runtime so theme overrides cascade;
+  // -bg-hover / -text-light stay compile-time. (The role text colours
+  // --pc-{success,danger,warning,info}-text live in the base contract.)
+  // =========================================================================
+  --pc-success-bg: var(--pc-success);
+  --pc-success-bg-hover: #{$success-bg-hover};
+  --pc-success-bg-light: color-mix(in srgb, var(--pc-success) 10%, transparent);
+  --pc-success-bg-subtle: color-mix(in srgb, var(--pc-success) 8%, transparent);
+  --pc-success-border: color-mix(in srgb, var(--pc-success) 20%, transparent);
+  --pc-success-text-light: #{$success-text-light};
+
+  --pc-danger-bg: var(--pc-danger);
+  --pc-danger-bg-hover: #{$danger-bg-hover};
+  --pc-danger-bg-light: color-mix(in srgb, var(--pc-danger) 10%, transparent);
+  --pc-danger-bg-subtle: color-mix(in srgb, var(--pc-danger) 8%, transparent);
+  --pc-danger-border: color-mix(in srgb, var(--pc-danger) 20%, transparent);
+  --pc-danger-text-light: #{$danger-text-light};
+
+  --pc-warning-bg: var(--pc-warning);
+  --pc-warning-bg-hover: #{$warning-bg-hover};
+  --pc-warning-bg-light: color-mix(in srgb, var(--pc-warning) 10%, transparent);
+  --pc-warning-bg-subtle: color-mix(in srgb, var(--pc-warning) 8%, transparent);
+  --pc-warning-border: color-mix(in srgb, var(--pc-warning) 20%, transparent);
+  --pc-warning-text-light: #{$warning-text-light};
+
+  --pc-info-bg: var(--pc-info);
+  --pc-info-bg-hover: #{$info-bg-hover};
+  --pc-info-bg-light: color-mix(in srgb, var(--pc-info) 10%, transparent);
+  --pc-info-bg-subtle: color-mix(in srgb, var(--pc-info) 8%, transparent);
+  --pc-info-border: color-mix(in srgb, var(--pc-info) 20%, transparent);
+  --pc-info-text-light: #{$info-text-light};
 
   // =========================================================================
   // CARD COLORS
   // =========================================================================
-  --pa-card-bg: #{$card-bg};
-  --pa-card-header-bg: #{$card-header-bg};
-  --pa-card-footer-bg: #{$card-footer-bg};
-  --pa-card-tabs-bg: #{$card-tabs-bg};
+  --pc-card-bg: #{$card-bg};
+  --pc-card-header-bg: #{$card-header-bg};
+  --pc-card-footer-bg: #{$card-footer-bg};
+  --pc-card-tabs-bg: #{$card-tabs-bg};
 
   // =========================================================================
   // INPUT/FORM COLORS
   // =========================================================================
-  --pa-input-bg: #{$input-bg};
-  --pa-input-border: #{$input-border};
-  --pa-input-text: #{$input-text};
-  --pa-input-focus-border-color: #{$input-focus-border-color};
-  --pa-select-focus-border-color: #{$select-focus-border-color};
-  --pa-textarea-focus-border-color: #{$textarea-focus-border-color};
+  --pc-input-bg: #{$input-bg};
+  --pc-input-border: #{$input-border};
+  --pc-input-text: #{$input-text};
+  --pc-input-focus-border-color: #{$input-focus-border-color};
+  --pc-select-focus-border-color: #{$select-focus-border-color};
+  --pc-textarea-focus-border-color: #{$textarea-focus-border-color};
 
   // Checkbox
-  --pa-checkbox-border-color: #{$checkbox-border-color};
-  --pa-checkbox-border-color-hover: #{$checkbox-border-color-hover};
-  --pa-checkbox-border-color-checked: #{$checkbox-border-color-checked};
-  --pa-checkbox-bg: #{$checkbox-bg};
-  --pa-checkbox-bg-checked: #{$checkbox-bg-checked};
-  --pa-checkbox-bg-indeterminate: #{$checkbox-bg-indeterminate};
-  --pa-checkbox-checkmark-color: #{$checkbox-checkmark-color};
-  --pa-checkbox-focus-shadow: #{$checkbox-focus-shadow};
+  --pc-checkbox-border-color: #{$checkbox-border-color};
+  --pc-checkbox-border-color-hover: #{$checkbox-border-color-hover};
+  --pc-checkbox-border-color-checked: #{$checkbox-border-color-checked};
+  --pc-checkbox-bg: #{$checkbox-bg};
+  --pc-checkbox-bg-checked: #{$checkbox-bg-checked};
+  --pc-checkbox-bg-indeterminate: #{$checkbox-bg-indeterminate};
+  --pc-checkbox-checkmark-color: #{$checkbox-checkmark-color};
+  --pc-checkbox-focus-shadow: #{$checkbox-focus-shadow};
 
   // Input group
-  --pa-input-group-prepend-bg: #{$input-group-prepend-bg};
-  --pa-input-group-prepend-text: #{$input-group-prepend-text};
-  --pa-input-group-append-bg: #{$input-group-append-bg};
-  --pa-input-group-append-text: #{$input-group-append-text};
+  --pc-input-group-prepend-bg: #{$input-group-prepend-bg};
+  --pc-input-group-prepend-text: #{$input-group-prepend-text};
+  --pc-input-group-append-bg: #{$input-group-append-bg};
+  --pc-input-group-append-text: #{$input-group-append-text};
 
   // =========================================================================
   // TABLE COLORS
   // =========================================================================
-  --pa-table-bg: #{$table-bg};
-  --pa-table-header-bg: #{$table-header-bg};
-  --pa-table-stripe: #{$table-stripe};
-  --pa-table-hover-bg: #{$table-hover-bg};
-  --pa-table-hover-accent-color: #{$table-hover-accent-color};
+  --pc-table-bg: #{$table-bg};
+  --pc-table-header-bg: #{$table-header-bg};
+  --pc-table-stripe: #{$table-stripe};
+  --pc-table-hover-bg: #{$table-hover-bg};
+  --pc-table-hover-accent-color: #{$table-hover-accent-color};
 
   // =========================================================================
   // MODAL COLORS
   // =========================================================================
-  --pa-modal-overlay-bg: #{$modal-overlay-bg};
-  --pa-modal-content-bg: #{$modal-content-bg};
-
-  // =========================================================================
-  // ALERT COLORS - Now derived via output-pa-alert-variables-light/dark mixins
-  // Themes must call the appropriate mixin after output-pa-css-variables
-  // =========================================================================
+  --pc-modal-overlay-bg: #{$modal-overlay-bg};
+  --pc-modal-content-bg: #{$modal-content-bg};
 
   // =========================================================================
   // BADGE COLORS
   // =========================================================================
-  --pa-badge-success-bg: #{$badge-success-bg};
-  --pa-badge-success-text: #{$badge-success-text};
-  --pa-badge-warning-bg: #{$badge-warning-bg};
-  --pa-badge-warning-text: #{$badge-warning-text};
-  --pa-badge-info-bg: #{$badge-info-bg};
-  --pa-badge-info-text: #{$badge-info-text};
-  --pa-badge-danger-bg: #{$badge-danger-bg};
-  --pa-badge-danger-text: #{$badge-danger-text};
+  --pc-badge-success-bg: #{$badge-success-bg};
+  --pc-badge-success-text: #{$badge-success-text};
+  --pc-badge-warning-bg: #{$badge-warning-bg};
+  --pc-badge-warning-text: #{$badge-warning-text};
+  --pc-badge-info-bg: #{$badge-info-bg};
+  --pc-badge-info-text: #{$badge-info-text};
+  --pc-badge-danger-bg: #{$badge-danger-bg};
+  --pc-badge-danger-text: #{$badge-danger-text};
 
   // Composite badge
-  --pa-composite-badge-icon-bg: #{$composite-badge-icon-bg};
-  --pa-composite-badge-label-bg: #{$composite-badge-label-bg};
-  --pa-composite-badge-label-text: #{$composite-badge-label-text};
-  --pa-composite-badge-label-hover-bg: #{$composite-badge-label-hover-bg};
+  --pc-composite-badge-icon-bg: #{$composite-badge-icon-bg};
+  --pc-composite-badge-label-bg: #{$composite-badge-label-bg};
+  --pc-composite-badge-label-text: #{$composite-badge-label-text};
+  --pc-composite-badge-label-hover-bg: #{$composite-badge-label-hover-bg};
 
   // =========================================================================
   // TOOLTIP & POPOVER COLORS
   // =========================================================================
-  --pa-tooltip-bg: #{$tooltip-bg};
-  --pa-tooltip-text: #{$tooltip-text};
-  --pa-popover-content-bg: #{$popover-content-bg};
-  --pa-popover-text-light: #{$popover-text-light};
-  --pa-popover-text-dark: #{$popover-text-dark};
+  --pc-tooltip-bg: #{$tooltip-bg};
+  --pc-tooltip-text: #{$tooltip-text};
+  --pc-popover-content-bg: #{$popover-content-bg};
+  --pc-popover-text-light: #{$popover-text-light};
+  --pc-popover-text-dark: #{$popover-text-dark};
 
   // =========================================================================
   // LOADER COLORS
   // =========================================================================
-  --pa-loader-overlay-bg: #{$loader-overlay-bg};
+  --pc-loader-overlay-bg: #{$loader-overlay-bg};
 
   // =========================================================================
   // PROFILE PANEL COLORS
   // =========================================================================
-  --pa-profile-overlay-bg: #{$profile-overlay-bg};
+  --pc-profile-overlay-bg: #{$profile-overlay-bg};
 
   // =========================================================================
   // DETAIL PANEL COLORS
   // =========================================================================
-  --pa-detail-panel-overlay-bg: #{$detail-panel-overlay-bg};
-  --pa-detail-panel-selected-bg: #{$detail-panel-selected-bg};
-  --pa-detail-panel-z-index: #{$detail-panel-z-index};
+  --pc-detail-panel-overlay-bg: #{$detail-panel-overlay-bg};
+  --pc-detail-panel-selected-bg: #{$detail-panel-selected-bg};
+  --pc-detail-panel-z-index: #{$detail-panel-z-index};
 
   // =========================================================================
   // COMMAND PALETTE COLORS
   // =========================================================================
-  --pa-command-palette-backdrop-bg: #{$command-palette-backdrop-bg};
-  --pa-command-palette-item-hover-bg: #{$command-palette-item-hover-bg};
-  --pa-command-palette-item-active-bg: #{$command-palette-item-active-bg};
-  --pa-command-palette-highlight-bg: #{$command-palette-highlight-bg};
-  --pa-command-palette-highlight-text: #{$command-palette-highlight-text};
-  --pa-command-palette-key-bg: #{$subtle-bg};
-  --pa-command-palette-key-text: #{$text-color-1};
-  --pa-command-palette-key-font-size: #{$font-size-xs};
-  --pa-command-palette-key-font-weight: #{$font-weight-semibold};
+  --pc-command-palette-backdrop-bg: #{$command-palette-backdrop-bg};
+  --pc-command-palette-item-hover-bg: #{$command-palette-item-hover-bg};
+  --pc-command-palette-item-active-bg: #{$command-palette-item-active-bg};
+  --pc-command-palette-highlight-bg: #{$command-palette-highlight-bg};
+  --pc-command-palette-highlight-text: #{$command-palette-highlight-text};
+  --pc-command-palette-key-bg: #{$subtle-bg};
+  --pc-command-palette-key-text: #{$text-color-1};
+  --pc-command-palette-key-font-size: #{$font-size-xs};
+  --pc-command-palette-key-font-weight: #{$font-weight-semibold};
 
   // =========================================================================
   // MULTISELECT COLORS
   // =========================================================================
-  --pa-multiselect-dropdown-bg: #{$multiselect-dropdown-bg};
-  --pa-multiselect-dropdown-border: #{$multiselect-dropdown-border};
-  --pa-multiselect-dropdown-text: #{$multiselect-dropdown-text};
-  --pa-multiselect-hint-bg: #{$multiselect-hint-bg};
-  --pa-multiselect-hint-border: #{$multiselect-hint-border};
-  --pa-multiselect-option-hover-bg: #{$multiselect-option-hover-bg};
-  --pa-multiselect-pill-bg: #{$multiselect-pill-bg};
-  --pa-multiselect-pill-border: #{$multiselect-pill-border};
-
-  // =========================================================================
-  // CUSTOM THEME COLORS (1-9)
-  // Themes can override $color-1 through $color-9 to define branded colors
-  // =========================================================================
-  --pa-color-1: #{$color-1};
-  --pa-color-2: #{$color-2};
-  --pa-color-3: #{$color-3};
-  --pa-color-4: #{$color-4};
-  --pa-color-5: #{$color-5};
-  --pa-color-6: #{$color-6};
-  --pa-color-7: #{$color-7};
-  --pa-color-8: #{$color-8};
-  --pa-color-9: #{$color-9};
-
-  // Theme color slots - text/contrast colors
-  --pa-color-1-text: #{$color-1-text};
-  --pa-color-2-text: #{$color-2-text};
-  --pa-color-3-text: #{$color-3-text};
-  --pa-color-4-text: #{$color-4-text};
-  --pa-color-5-text: #{$color-5-text};
-  --pa-color-6-text: #{$color-6-text};
-  --pa-color-7-text: #{$color-7-text};
-  --pa-color-8-text: #{$color-8-text};
-  --pa-color-9-text: #{$color-9-text};
-
-  // =========================================================================
-  // STRUCTURAL (themeable via CSS variables)
-  // =========================================================================
-  --pa-border-radius-sm: #{$border-radius-sm};
-  --pa-border-radius: #{$border-radius};
-  --pa-border-radius-lg: #{$border-radius-lg};
+  --pc-multiselect-dropdown-bg: #{$multiselect-dropdown-bg};
+  --pc-multiselect-dropdown-border: #{$multiselect-dropdown-border};
+  --pc-multiselect-dropdown-text: #{$multiselect-dropdown-text};
+  --pc-multiselect-hint-bg: #{$multiselect-hint-bg};
+  --pc-multiselect-hint-border: #{$multiselect-hint-border};
+  --pc-multiselect-option-hover-bg: #{$multiselect-option-hover-bg};
+  --pc-multiselect-pill-bg: #{$multiselect-pill-bg};
+  --pc-multiselect-pill-border: #{$multiselect-pill-border};
+
+  // =========================================================================
+  // FORM SPACING — the complete anatomy of a form's spacing. Runtime-tunable;
+  // the inline "gap" family chains to --pc-form-gap so one knob moves them all.
+  //   VERTICAL RHYTHM: --pc-label-gap (label→control), --pc-help-gap
+  //     (control→help), --pc-field-gap (field→field), --pc-form-actions-offset
+  //     (last field→actions row).
+  //   INLINE: --pc-form-gap (shared + label↔icon), --pc-choice-gap (between
+  //     options), --pc-choice-inner-gap (control↔label), --pc-form-actions-gap
+  //     (between buttons), --pc-field-horizontal-gap (label col↔input col).
+  // =========================================================================
+  --pc-form-gap: #{$form-gap};
+  --pc-choice-gap: var(--pc-form-gap);
+  --pc-choice-inner-gap: #{$spacing-sm};
+  --pc-form-actions-gap: var(--pc-form-gap);
+  --pc-field-horizontal-gap: #{$spacing-base};
+  --pc-label-gap: #{$form-label-margin-bottom};
+  --pc-help-gap: #{$form-help-margin-top};
+  --pc-field-gap: #{$form-group-margin-bottom};
+  --pc-form-actions-offset: #{$spacing-base};
+}
+
+// ============================================================================
+// ALERT COLOR DERIVATION MIXINS — also pure-admin's contract (see above).
+// ============================================================================
+// Derive alert colours from the semantic role surfaces (--pc-success-bg, etc.)
+// via color-mix(). Consumers call the light or dark variant after
+// output-pc-component-variables. Light: dark text on subtle backgrounds.
+// Dark: white text on tinted backgrounds. Not emitted by pure-css's own bundle.
+// ============================================================================
+
+// Light mode: dark text on subtle backgrounds
+@mixin output-pc-alert-variables-light {
+  // Success
+  --pc-alert-success-text: color-mix(in srgb, var(--pc-success-bg) #{$alert-text-mix-light}, black);
+  --pc-alert-success-bg: color-mix(in srgb, var(--pc-success-bg) #{$alert-bg-opacity-light}%, transparent);
+  --pc-alert-success-border: color-mix(in srgb, var(--pc-success-bg) #{$alert-border-opacity-light}%, transparent);
+
+  // Danger
+  --pc-alert-danger-text: color-mix(in srgb, var(--pc-danger-bg) #{$alert-text-mix-light}, black);
+  --pc-alert-danger-bg: color-mix(in srgb, var(--pc-danger-bg) #{$alert-bg-opacity-light}%, transparent);
+  --pc-alert-danger-border: color-mix(in srgb, var(--pc-danger-bg) #{$alert-border-opacity-light}%, transparent);
+
+  // Warning
+  --pc-alert-warning-text: color-mix(in srgb, var(--pc-warning-bg) #{$alert-text-mix-light}, black);
+  --pc-alert-warning-bg: color-mix(in srgb, var(--pc-warning-bg) #{$alert-bg-opacity-light}%, transparent);
+  --pc-alert-warning-border: color-mix(in srgb, var(--pc-warning-bg) #{$alert-border-opacity-light}%, transparent);
+
+  // Info
+  --pc-alert-info-text: color-mix(in srgb, var(--pc-info-bg) #{$alert-text-mix-light}, black);
+  --pc-alert-info-bg: color-mix(in srgb, var(--pc-info-bg) #{$alert-bg-opacity-light}%, transparent);
+  --pc-alert-info-border: color-mix(in srgb, var(--pc-info-bg) #{$alert-border-opacity-light}%, transparent);
+}
+
+// Dark mode: white text on tinted backgrounds (white text is always readable)
+@mixin output-pc-alert-variables-dark {
+  // Success
+  --pc-alert-success-text: #ffffff;
+  --pc-alert-success-bg: color-mix(in srgb, var(--pc-success-bg) #{$alert-bg-opacity-dark}%, transparent);
+  --pc-alert-success-border: color-mix(in srgb, var(--pc-success-bg) #{$alert-border-opacity-dark}%, transparent);
+
+  // Danger
+  --pc-alert-danger-text: #ffffff;
+  --pc-alert-danger-bg: color-mix(in srgb, var(--pc-danger-bg) #{$alert-bg-opacity-dark}%, transparent);
+  --pc-alert-danger-border: color-mix(in srgb, var(--pc-danger-bg) #{$alert-border-opacity-dark}%, transparent);
+
+  // Warning
+  --pc-alert-warning-text: #ffffff;
+  --pc-alert-warning-bg: color-mix(in srgb, var(--pc-warning-bg) #{$alert-bg-opacity-dark}%, transparent);
+  --pc-alert-warning-border: color-mix(in srgb, var(--pc-warning-bg) #{$alert-border-opacity-dark}%, transparent);
+
+  // Info
+  --pc-alert-info-text: #ffffff;
+  --pc-alert-info-bg: color-mix(in srgb, var(--pc-info-bg) #{$alert-bg-opacity-dark}%, transparent);
+  --pc-alert-info-border: color-mix(in srgb, var(--pc-info-bg) #{$alert-border-opacity-dark}%, transparent);
 }