@stnd/styles 0.5.1 → 0.5.3

package/_standard-02-color.scss

@@ -1,5 +1,42 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Color System
+ * @category Foundation
+ * @description Seed-first OKLCH color engine. Set one thing — your light
+ * foreground color — and a full light/dark palette, ten semantic hues, and
+ * a shadow/elevation scale all derive from it via `oklch(from <seed> ...)`
+ * relative color syntax. Override at three depths: set `--color-light-foreground`
+ * alone (everything else follows); set individual `--color-light-*` /
+ * `--color-dark-*` tokens for per-scheme control; or theme fully via
+ * `[data-theme]` selectors, which re-resolve the whole token set at any
+ * element, not just `:root`.
+ *
+ * @property --color-light-foreground The primary light foreground seed. Change this alone and dark mode, all ten chromatic hues, and derived surfaces/borders/shadows follow.
+ * @property --color-light-background The root light background seed (default `white`).
+ * @property --color-dark-foreground Derived dark reading foreground (default ~85% lightness matching foreground hue).
+ * @property --color-dark-background Derived dark background (default ~20% lightness matching foreground hue).
+ * @property --color-background Active scheme background token.
+ * @property --color-foreground Active scheme foreground token.
+ * @property --color-accent Active accent color token (defaults to triadic +120°).
+ * @property --color-border Active border color token.
+ * @property --color-surface Active elevated surface background.
+ * @property --color-muted Active muted text color (~60% opacity).
+ * @property --color-subtle Active subtle UI text color (~40% opacity).
+ * @property --color-link Semantic link color token.
+ * @property --color-success Semantic success status color (`--color-green`).
+ * @property --color-warning Semantic warning status color (`--color-orange`).
+ * @property --color-error Semantic error status color (`--color-red`).
+ * @property --color-info Semantic info status color (`--color-blue`).
+ * @property --color-light Polarity alias resolving to the lighter tone of the active scheme.
+ * @property --color-dark Polarity alias resolving to the darker tone of the active scheme.
+ * @property --shadow Primary ambient shadow preset.
+ * @property .theme-light Forces light token set and color scheme on any subtree.
+ * @property .theme-dark Forces dark token set and color scheme on any subtree.
+ * @property .inverse Flips scheme to whichever mode is not currently active.
+ * @property [data-color-mode] Attribute forcing `"light"` or `"dark"` scheme mode.
+ */
+
 /* ==========================================================================
    STANDARD COLOR SYSTEM — Seed-First Architecture
 
@@ -42,18 +79,15 @@
   /* Tell browser we support both color schemes */
   color-scheme: light dark;
 
-  /* ===================================================================
-     STAGE 1: DARK SEED DERIVATION
-     The ink's soul carries into darkness.
-     Both dark seeds inherit hue from the light foreground — warm brown
-     ink begets a warm dark background and a warm soft foreground.
-     Themes override --color-dark-background / --color-dark-foreground
-     at [data-theme] specificity for a distinct dark mood.
-
-     Light fg #442f1c  →  oklch(0.30, 0.07, H≈60)  warm brown ink
-     Dark bg  derived  →  oklch(0.20, 0.02, H≈60)  same hue, very dark, muted
-     Dark fg  derived  →  oklch(0.85, 0.04, H≈60)  same hue, soft reading brightness
-     =================================================================== */
+  /**
+   * @component Dark Seed Derivation
+   * @category Foundation
+   * @description Both dark seeds inherit hue from the light foreground seed.
+   * Warm ink begets a warm dark background and a warm soft reading foreground.
+   *
+   * @property --color-dark-background Dark background matching foreground hue at ~20% lightness and muted chroma.
+   * @property --color-dark-foreground Dark foreground matching foreground hue at ~85% lightness for soft reading brightness.
+   */
 
   /* Dark background: foreground's hue at very low lightness, muted chroma */
   --color-dark-background: oklch(
@@ -71,17 +105,27 @@
       /* same hue — the vibe persists */
   );
 
-  /* ===================================================================
-     STAGE 2: LIGHT PALETTE
-     Full spectrum generated from light foreground seed via inline
-     relative color syntax. Each color is a self-contained transform:
-       oklch(from <seed> <safe-L> <safe-C> calc(h + offset))
-
-     Channel keywords l, c, h resolve inside the function scope.
-     No extraction into intermediate custom properties needed.
-     Safety: clamp(0.65, l, 0.70) for bright vibrant tones, max(0.12, c) for saturation.
-     Achromatic seeds (h = none) → none treated as 0 in calc() per spec.
-     =================================================================== */
+  /**
+   * @component Light Palette
+   * @category Foundation
+   * @description Full 10-hue chromatic spectrum generated from light foreground seed via inline relative color syntax.
+   *
+   * @property --color-light-red Error / Red (+25° hue offset).
+   * @property --color-light-orange Attention / Orange (+55° hue offset).
+   * @property --color-light-yellow Warning / Yellow (+85° hue offset).
+   * @property --color-light-green Success / Green (+145° hue offset).
+   * @property --color-light-cyan Info / Cyan (+190° hue offset).
+   * @property --color-light-blue Link / Blue (+240° hue offset).
+   * @property --color-light-magenta Magic / Magenta (+300° hue offset).
+   * @property --color-light-purple Purple (+270° hue offset).
+   * @property --color-light-pink Pink (+350° hue offset).
+   * @property --color-light-brown Brown (+60° hue offset).
+   * @property --color-light-accent-complementary Complementary accent (+180°).
+   * @property --color-light-accent-analogous Analogous accent (+30°).
+   * @property --color-light-accent-triadic Triadic accent (+120°).
+   * @property --color-light-accent-auto Default accent strategy (triadic).
+   * @property --color-light-accent Active light mode accent color.
+   */
 
   /* Error / Red — foreground hue + 25° */
   --color-light-red: oklch(
@@ -162,14 +206,27 @@
   --color-light-accent-auto: var(--color-light-accent-triadic);
   --color-light-accent: var(--color-light-accent-auto);
 
-  /* ===================================================================
-     STAGE 2B: DARK PALETTE
-     Full spectrum generated from dark foreground seed.
-     NOT a simple lightening of the light palette — independent vibe.
-     A warm dark-foreground seed gives warm darks. A cool one gives
-     cool darks. Two different seeds, two different moods.
-     Safety: clamp(0.55, l, 0.70) for softer tones on dark surfaces.
-     =================================================================== */
+  /**
+   * @component Dark Palette
+   * @category Foundation
+   * @description Full 10-hue chromatic spectrum generated from dark foreground seed for comfortable dark surfaces.
+   *
+   * @property --color-dark-red Dark mode red (+25° hue offset).
+   * @property --color-dark-orange Dark mode orange (+55° hue offset).
+   * @property --color-dark-yellow Dark mode yellow (+85° hue offset).
+   * @property --color-dark-green Dark mode green (+145° hue offset).
+   * @property --color-dark-cyan Dark mode cyan (+190° hue offset).
+   * @property --color-dark-blue Dark mode blue (+240° hue offset).
+   * @property --color-dark-magenta Dark mode magenta (+300° hue offset).
+   * @property --color-dark-purple Dark mode purple (+270° hue offset).
+   * @property --color-dark-pink Dark mode pink (+350° hue offset).
+   * @property --color-dark-brown Dark mode brown (+60° hue offset).
+   * @property --color-dark-accent-complementary Dark complementary accent (+180°).
+   * @property --color-dark-accent-analogous Dark analogous accent (+30°).
+   * @property --color-dark-accent-triadic Dark triadic accent (+120°).
+   * @property --color-dark-accent-auto Default dark accent strategy.
+   * @property --color-dark-accent Active dark mode accent color.
+   */
 
   /* Error / Red — dark foreground hue + 25° */
   --color-dark-red: oklch(
@@ -246,10 +303,25 @@
   /* On-accent (text drawn on accent surfaces) */
   --color-dark-on-accent: var(--color-dark-background);
 
-  /* ===================================================================
-     STAGE 2C: COMPUTED PALETTES
-     Always available for explicit "light-in-dark" or "dark-in-light" UI.
-     =================================================================== */
+  /**
+   * @component Computed Palettes
+   * @category Foundation
+   * @description Computed scheme-specific tints for muted text, subtle UI elements, borders, and shadows.
+   *
+   * @property --color-light-muted Light muted text color (~60% opacity).
+   * @property --color-light-subtle Light subtle text color (~40% opacity).
+   * @property --color-light-border Light border color (~10% opacity).
+   * @property --color-light-surface Light surface background (3% foreground mixed with background).
+   * @property --color-light-on-accent Text color drawn on light accent backgrounds.
+   * @property --color-dark-muted Dark muted text color (~65% opacity).
+   * @property --color-dark-subtle Dark subtle text color (~45% opacity).
+   * @property --color-dark-border Dark border color.
+   * @property --color-dark-surface Dark surface background.
+   * @property --color-light-shadow-base Base shadow seed for light mode.
+   * @property --color-light-highlight Base specular highlight for light mode.
+   * @property --color-dark-shadow-base Base shadow seed for dark mode.
+   * @property --color-dark-highlight Base specular highlight for dark mode.
+   */
 
   /* Light Computed Palette */
   --color-light-muted: oklch(from var(--color-light-foreground) l c h / 0.6);
@@ -293,12 +365,32 @@
     from var(--color-dark-foreground) min(1, calc(l + 0.05)) c h / 0.11
   );
 
-  /* ===================================================================
-     STAGE 3: SEMANTIC TOKENS (Default → Light Palette)
-     These are the tokens components actually consume.
-     Never reference --color-light-* or --color-dark-* in components.
-     Always use --color-red, --color-background, etc.
-     =================================================================== */
+  /**
+   * @component Semantic Tokens
+   * @category Foundation
+   * @description Semantic color tokens consumed across all components and styles.
+   *
+   * @property --color-background Active scheme root background.
+   * @property --color-foreground Active scheme text foreground.
+   * @property --color-accent Active scheme primary accent color.
+   * @property --color-header Heading text color.
+   * @property --color-red Semantic red hue.
+   * @property --color-orange Semantic orange hue.
+   * @property --color-yellow Semantic yellow hue.
+   * @property --color-green Semantic green hue.
+   * @property --color-cyan Semantic cyan hue.
+   * @property --color-blue Semantic blue hue.
+   * @property --color-magenta Semantic magenta hue.
+   * @property --color-purple Semantic purple hue.
+   * @property --color-pink Semantic pink hue.
+   * @property --color-brown Semantic brown hue.
+   * @property --color-success Status color for success states (`--color-green`).
+   * @property --color-warning Status color for warnings (`--color-orange`).
+   * @property --color-error Status color for errors (`--color-red`).
+   * @property --color-info Status color for informative notices (`--color-blue`).
+   * @property --color-link Active scheme link color.
+   * @property --color-on-accent Text color for elements over accent backgrounds.
+   */
   --color-background: var(--color-light-background);
   --color-foreground: var(--color-light-foreground);
   --color-accent: var(--color-light-accent);
@@ -327,11 +419,24 @@
   --color-bold: var(--color-light-bold, var(--color-foreground));
   --color-on-accent: var(--color-background);
 
-  /* ===================================================================
-     STAGE 4: COMPUTED SEMANTIC COLORS
-     Derived from the scheme-aware --color-foreground/--color-background.
-     auto-adapt when the scheme switches.
-     =================================================================== */
+  /* Fixed 2026-07-14 — purple/pink/brown now correctly switch to dark
+     variants in all three dark-mode contexts, plus added missing
+     non-OKLCH fallbacks. */
+
+  /**
+   * @component Computed Semantics
+   * @category Foundation
+   * @description Scheme-aware computed colors derived from active foreground and background seeds.
+   *
+   * @property --color-muted Secondary text color (~60% alpha).
+   * @property --color-subtle Tertiary text and decorative icon color (~40% alpha).
+   * @property --color-border Standard structural border color (~10% alpha).
+   * @property --color-surface Elevated surface and card background.
+   * @property --color-light Polarity alias resolving to lighter color of active scheme.
+   * @property --color-dark Polarity alias resolving to darker color of active scheme.
+   * @property --color-darker Dark overlay tint.
+   * @property --color-glass Frosted glassmorphism background color (~80% alpha).
+   */
   --color-muted: var(--color-light-muted);
   --color-subtle: var(--color-light-subtle);
   --color-border: var(--color-light-border);
@@ -344,42 +449,25 @@
 
   --color-glass: oklch(from var(--color-background) l c h / 0.8);
 
-  /* ===================================================================
-     STAGE 5: SHADOWS & SURFACES
-     OKLCH-based for perceptually uniform elevation.
-     All derived from semantic pointers — auto-adapt to dark mode.
-     =================================================================== */
+  /**
+   * @component Surfaces & Elevation Colors
+   * @category Foundation
+   * @description Semantic elevation color seeds and surface hierarchy using perceptual OKLCH color spaces.
+   *
+   * @property --color-shadow Active base shadow color.
+   * @property --color-highlight Active specular highlight color.
+   * @property --color-surface-lowest Deepest recessed surface step.
+   * @property --color-surface-lower Sub-surface step mixed with transparency.
+   * @property --color-surface-low Low elevation surface step.
+   * @property --color-surface Base surface color.
+   * @property --color-surface-high Elevated surface step.
+   * @property --color-surface-highest Highest surface elevation step.
+   */
 
   /* Semantic Shadow Seeds */
   --color-shadow: var(--color-light-shadow-base);
   --color-highlight: var(--color-light-highlight);
 
-  /* Shadow building blocks — compose freely */
-  --shadow-ambient: 0 1px 1px var(--color-shadow); /* Felt more than seen */
-
-  /* This one pop a bit */
-  --shadow-lift:
-    0 4px 6px -1px var(--color-shadow), 0 2px 4px -2px var(--color-shadow);
-  /* Organicaly grows */
-  --shadow-glow: 0 4px var(--space) oklch(from var(--color-shadow) l c h / 0.15);
-  --shadow-inset:
-    inset 0 1px 3px var(--color-shadow), inset 0 -1px 0 0 var(--color-highlight);
-  --shadow-ring:
-    inset 0px 1px 1px var(--color-border),
-    inset 1px 0px 1px var(--color-border),
-    inset -1px 0px 1px var(--color-border),
-    inset 0px -1px 1px var(--color-border);
-
-  /* shadcn-style raised effect: inner highlight + border + shadow */
-  --shadow-raised:
-    inset 0 1px 0 0 var(--color-highlight), 0 0 0 1px var(--color-border),
-    var(--shadow-ambient);
-
-  /* Composed presets */
-  --shadow: var(--shadow-ambient), var(--shadow-ambient);
-  --shadow-lg: var(--shadow-ambient), var(--shadow-lift);
-  --shadow-xl: var(--shadow-ambient), var(--shadow-lift), var(--shadow-glow);
-
   /* Surface elevation scale */
   --color-surface-low: color-mix(
     in srgb,
@@ -404,14 +492,23 @@
     var(--color-surface-high)
   );
   --color-surface-higher: color-mix(in srgb, white 50%, transparent);
-  /* ===================================================================
-     STAGE 6: DESIGN TOKENS (Border Shorthands)
-     =================================================================== */
-  --border: 0 solid transparent;
+  /**
+   * @component Border Shorthands
+   * @category Foundation
+   * @description Pre-composed border shorthand tokens for clean layout boundaries.
+   *
+   * @property --border Standard border shorthand (`var(--stroke-width) solid var(--color-border)`).
+   * @property --border-accent Tinted accent border shorthand (`var(--stroke-width) solid oklch(...)`).
+   * @property --border-transparent Transparent layout placeholder border.
+   */
   --border-transparent: var(--stroke-width) solid transparent;
   --border-accent: var(--stroke-width) solid
     oklch(from var(--color-accent) l c h / 0.07);
-  --border: none;
+  /* Regressed to `0 solid transparent` at some point, then a prior audit
+     correctly flagged it as dead code but "fixed" it to `none` instead of
+     restoring the real value. Git history confirms the intended value —
+     unchanged across many commits before the regression — was this. */
+  --border: var(--stroke-width) solid var(--color-border);
 }
 
 /* =====================================================================
@@ -443,6 +540,9 @@
     --color-cyan: var(--color-dark-cyan);
     --color-blue: var(--color-dark-blue);
     --color-magenta: var(--color-dark-magenta);
+    --color-purple: var(--color-dark-purple);
+    --color-pink: var(--color-dark-pink);
+    --color-brown: var(--color-dark-brown);
 
     --color-link: var(--color-dark-link);
     --color-italic: var(--color-dark-italic, var(--color-foreground));
@@ -487,10 +587,19 @@
   }
 }
 
-/* =====================================================================
-   STAGE 7B: THEME UTILITIES (.inverse, .theme-dark, .theme-light)
-   Provides explicit control and local context switching.
-   ===================================================================== */
+/**
+ * @component Theme Classes & Mixins
+ * @category Foundation
+ * @description Utilities and classes for forcing color modes and contextual inversion on subtrees.
+ *
+ * @property .theme-light Forces light color scheme and tokens on the applied container.
+ * @property .theme-dark Forces dark color scheme and tokens on the applied container.
+ * @property .inverse Contextually inverts color scheme relative to current background mode.
+ * @property [data-theme] Scoped theme attribute allowing local theme switching on cards or panels.
+ * @property [data-color-mode] Attribute setting explicit `"light"` or `"dark"` mode.
+ * @property @mixin theme-light-tokens Mixin stamping active light palette tokens into a selector.
+ * @property @mixin theme-dark-tokens Mixin stamping active dark palette tokens into a selector.
+ */
 
 @mixin theme-light-tokens {
   --color-background: var(--color-light-background);
@@ -570,6 +679,9 @@
     --color-cyan: var(--color-dark-cyan);
     --color-blue: var(--color-dark-blue);
     --color-magenta: var(--color-dark-magenta);
+    --color-purple: var(--color-dark-purple);
+    --color-pink: var(--color-dark-pink);
+    --color-brown: var(--color-dark-brown);
     --color-link: var(--color-dark-link);
     --color-italic: var(--color-dark-italic, var(--color-foreground));
     --color-bold: var(--color-dark-bold, var(--color-foreground));
@@ -588,6 +700,9 @@
   --color-cyan: var(--color-dark-cyan);
   --color-blue: var(--color-dark-blue);
   --color-magenta: var(--color-dark-magenta);
+  --color-purple: var(--color-dark-purple);
+  --color-pink: var(--color-dark-pink);
+  --color-brown: var(--color-dark-brown);
   --color-link: var(--color-dark-link);
   --color-italic: var(--color-dark-italic, var(--color-foreground));
   --color-bold: var(--color-dark-bold, var(--color-foreground));
@@ -614,6 +729,9 @@
    STAGE 8: FALLBACKS — Graceful Degradation
    Browsers without OKLCH support (Safari <16.4, Chrome <111, FF <113)
    get concrete color values so the UI remains usable.
+
+   Fixed 2026-07-14 — added missing light/dark purple & pink fallbacks
+   below.
    ===================================================================== */
 @supports not (color: oklch(50% 0.2 180)) {
   #{$stnd-theme-scope} {
@@ -629,6 +747,8 @@
     --color-light-cyan: #2a8a8a;
     --color-light-blue: #3a60b0;
     --color-light-magenta: #9040a0;
+    --color-light-purple: #8050b0;
+    --color-light-pink: #c05090;
     --color-light-accent: #2a8a8a;
 
     /* Dark palette fallbacks */
@@ -639,6 +759,8 @@
     --color-dark-cyan: #50b0b0;
     --color-dark-blue: #6080d0;
     --color-dark-magenta: #b060c0;
+    --color-dark-purple: #a070d0;
+    --color-dark-pink: #d070a0;
     --color-dark-accent: #50b0b0;
 
     /* Computed fallbacks */