@mastors/core 1.1.0 → 2.0.0

package/scss/functions/_color.scss

@@ -3,7 +3,6 @@
 // ─────────────────────────────────────────────────────────────
 
 @use "sass:color";
-@use "sass:list";
 @use "sass:math";
 @use "../tokens/color" as ct;
 
@@ -23,6 +22,21 @@
 }
 
 /// Return black or white for maximum contrast against $bg.
+///
+/// Method: simplified linear luminance (no sRGB gamma expansion).
+/// The three RGB coefficients (0.2126 / 0.7152 / 0.0722) are the WCAG
+/// standard weights, but they are meant to be applied to *linearised*
+/// channel values (after the 0.04045 piecewise inverse-gamma step).
+/// Skipping gamma expansion makes mid-tones appear lighter than they
+/// really are, so the WCAG threshold (0.179) would incorrectly return
+/// $dark for many mid-grey backgrounds.
+///
+/// To compensate, the threshold is adjusted to ~0.35 — empirically
+/// calibrated for the non-linearised approximation used here. This
+/// gives correct light/dark decisions across the full neutral scale.
+///
+/// Do NOT use the return value for strict WCAG 2.1 contrast-ratio
+/// calculations; implement full sRGB linearisation for that use case.
 @function contrast($bg, $light: white, $dark: black) {
   $luminance: 0.2126 * color.channel($bg, "red",   $space: rgb) / 255
             + 0.7152 * color.channel($bg, "green", $space: rgb) / 255
@@ -33,34 +47,3 @@
     @return $light;
   }
 }
-
-/// Quick palette accessor — shorthand for ct.color()
-@function palette($name, $shade: null) {
-  @return ct.color($name, $shade);
-}
-
-/// Emit a color as rgb() with optional opacity.
-@function rgb-color($name, $shade, $opacity: 1) {
-  $c: ct.color($name, $shade);
-  @if $opacity == 1 { @return $c; }
-  $r: color.channel($c, "red",   $space: rgb);
-  $g: color.channel($c, "green", $space: rgb);
-  $b: color.channel($c, "blue",  $space: rgb);
-  @return rgb($r $g $b / $opacity);
-}
-
-/// Create a stepped tint/shade ramp on the fly.
-@function color-ramp($base, $steps: 5, $dir: "tint") {
-  $result: ();
-  @for $i from 1 through $steps {
-    $pct: math.div($i * 100%, $steps + 1);
-    $step: null;
-    @if $dir == "tint" {
-      $step: tint($base, $pct);
-    } @else {
-      $step: shade($base, $pct);
-    }
-    $result: list.append($result, $step, comma);
-  }
-  @return $result;
-}

package/scss/functions/_em.scss

@@ -10,14 +10,14 @@
 /// @param {Number} $context - context font size in px (default: base)
 /// @return {Number} em value
 @function em($px, $context: vars.$base-font-size) {
-  $base: null;
+  $base: 0;
   @if math.compatible($px, 1px) {
     $base: math.div($px, 1px);
   } @else {
     $base: $px;
   }
 
-  $ctx: null;
+  $ctx: 0;
   @if math.compatible($context, 1px) {
     $ctx: math.div($context, 1px);
   } @else {

package/scss/functions/_index.scss

@@ -1,11 +1,5 @@
 // functions/_index.scss
 // ─────────────────────────────────────────────────────────────
-// NOTE: _vars.scss is intentionally NOT forwarded here.
-// _string.scss already defines vars() and vars-or().
-// _vars.scss defines a single-token vars($token, $fallback) variant
-// under a different signature — forwarding both causes a "two modules
-// define vars" conflict. Consumers who need the _vars.scss variant
-// should @use it directly.
 
 @forward "color";
 @forward "math";

package/scss/functions/_math.scss

@@ -19,22 +19,3 @@
   $intercept: $min-val - $slope * $min-vw;
   @return clamp(#{$min-val}, #{$slope * 100vw} + #{$intercept}, #{$max-val});
 }
-
-/// Strip the unit from a number: strip-unit(16px) → 16
-@function strip-unit($number) {
-  @return math.div($number, ($number * 0 + 1));
-}
-
-/// Round to N decimal places: round-to(3.14159, 2) → 3.14
-@function round-to($number, $decimals: 2) {
-  $n: math.pow(10, $decimals);
-  @return math.div(math.round($number * $n), $n);
-}
-
-/// Linear interpolation between two values
-/// @param {Number} $a    - start value
-/// @param {Number} $b    - end value
-/// @param {Number} $t    - interpolation factor (0–1)
-@function lerp($a, $b, $t) {
-  @return $a + ($b - $a) * $t;
-}

package/scss/functions/_string.scss

@@ -20,38 +20,3 @@
 @function to-string($value) {
   @return #{$value};
 }
-
-/// Reference any design token as a CSS custom property (var()).
-/// Builds the --mastors-{category}-{keys...} expression at zero runtime cost.
-///
-/// Usage:
-///   color:              vars(color, primary, 500);  → var(--mastors-color-primary-500)
-///   padding:            vars(spacing, 4);           → var(--mastors-spacing-4)
-///   border-radius:      vars(radius, lg);           → var(--mastors-radius-lg)
-///   transition-duration:vars(duration, 200);        → var(--mastors-duration-200)
-///   z-index:            vars(z, modal);             → var(--mastors-z-modal)
-///   box-shadow:         vars(shadow, md);           → var(--mastors-shadow-md)
-///
-/// @param {String} $category - Token category prefix (color, spacing, radius…)
-/// @param {ArgList} $keys    - One or more path segments
-/// @return {String}          - CSS var() expression
-@function vars($category, $keys...) {
-  $prop: "--mastors-#{$category}";
-  @each $key in $keys {
-    $prop: "#{$prop}-#{$key}";
-  }
-  @return var(#{$prop});
-}
-
-/// vars() with a fallback value.
-/// Usage: color: vars-or(color, #3b82f6, primary, 500);
-/// @param {String} $category - Token category prefix
-/// @param {*}     $fallback  - Fallback value if custom property is not set
-/// @param {ArgList} $keys    - Path segments
-@function vars-or($category, $fallback, $keys...) {
-  $prop: "--mastors-#{$category}";
-  @each $key in $keys {
-    $prop: "#{$prop}-#{$key}";
-  }
-  @return var(#{$prop}, #{$fallback});
-}

package/scss/generators/_class-generator.scss

@@ -10,13 +10,34 @@
 @use "../variables/breakpoints" as bpvars;
 
 /// Core utility class generator engine.
+/// Emits base utility classes AND, for any entry with responsive: true,
+/// also emits breakpoint-prefixed variants via the built-in responsive pass.
+///
+/// @param {Map} $utilities - map of utility configs, each with:
+///   - property    {String}  CSS property name
+///   - values      {Map}     class-suffix → value pairs
+///   - prefix      {String}  optional class prefix (e.g. "flex")
+///   - responsive  {Boolean} emit responsive variants (default false)
+///
+/// Usage:
+///   @include generate-utilities((
+///     "flex-direction": (
+///       property:    flex-direction,
+///       prefix:      "flex",
+///       values: ("row": row, "col": column, "row-reverse": row-reverse),
+///       responsive:  true,
+///     ),
+///   ));
 @mixin generate-utilities($utilities) {
   $cls-prefix: cfg.config("prefix");
-  $use-important: cfg.config("important");
+  $important: null;
+  @if cfg.config("important") {
+    $important: !important;
+  }
 
   // ── Pass 1: base (unprefixed) classes ──────────────────────
   @each $name, $config in $utilities {
-    $prop: map.get($config, property);
+    $prop:   map.get($config, property);
     $values: map.get($config, values);
     $prefix: map.get($config, prefix);
 
@@ -26,52 +47,42 @@
         $class-name: "#{$cls-prefix}#{$prefix}-#{$suffix}";
       }
       .#{$class-name} {
-        @if $use-important {
-          #{$prop}: $value !important;
-        } @else {
-          #{$prop}: $value;
-        }
+        #{$prop}: $value $important;
       }
     }
   }
 
   // ── Pass 2: responsive variants (.sm\:, .md\:, …) ─────────
+  // Only runs when $enable-responsive is true and at least one
+  // utility in the map declares responsive: true.
   @if flags.$enable-responsive {
     @each $bp-key, $bp-value in bpvars.$breakpoints {
-      @if $bp-value != 0 {
+      // xs (0px) → no media query wrapper; base classes already cover it.
+      @if $bp-value != 0px {
         @media (min-width: #{$bp-value}) {
           @each $name, $config in $utilities {
             @if map.get($config, responsive) == true {
-              $prop: map.get($config, property);
+              $prop:   map.get($config, property);
               $values: map.get($config, values);
               $prefix: map.get($config, prefix);
 
               @each $suffix, $value in $values {
-                $class: null;
-                @if $prefix {
-                  $class: "#{$cls-prefix}#{$prefix}-#{$suffix}";
-                } @else {
-                  $class: "#{$cls-prefix}#{$suffix}";
-                }
+                $class: if($prefix, "#{$cls-prefix}#{$prefix}-#{$suffix}", "#{$cls-prefix}#{$suffix}");
 
-                // Escape numeric-leading breakpoint keys (e.g. "2xl" → "\32 xl")
-                $first: string.slice("#{$bp-key}", 1, 1);
-                $rest: string.slice("#{$bp-key}", 2);
-                $safe-bp: null;
-                @if $first == "0" or $first == "1" or $first == "2" or $first == "3" or
-                    $first == "4" or $first == "5" or $first == "6" or $first == "7" or
-                    $first == "8" or $first == "9" {
-                  $safe-bp: "\\3#{$first} #{$rest}";
-                } @else {
-                  $safe-bp: "#{$bp-key}";
-                }
+                // CSS identifiers cannot start with a digit.
+                // Escape numeric-leading breakpoint keys (e.g. "2xl" → "\32 xl").
+                $first:   string.slice("#{$bp-key}", 1, 1);
+                $rest:    string.slice("#{$bp-key}", 2);
+                $safe-bp: if(
+                  $first == "0" or $first == "1" or $first == "2" or $first == "3" or
+                  $first == "4" or $first == "5" or $first == "6" or $first == "7" or
+                  $first == "8" or $first == "9",
+                  "\\3#{$first} #{$rest}",
+                  "#{$bp-key}"
+                );
 
                 @at-root .#{$safe-bp}\:#{$class} {
-                  @if $use-important {
-                    #{$prop}: $value !important;
-                  } @else {
-                    #{$prop}: $value;
-                  }
+                  #{$prop}: $value $important;
                 }
               }
             }

package/scss/generators/_responsive-generator.scss

@@ -4,14 +4,18 @@
 
 // NOTE: Responsive class generation is now handled directly inside
 // generate-utilities() in _class-generator.scss (Pass 2).
+//
 // This file previously contained a generate-responsive() mixin that
 // accepted @content blocks but never emitted any CSS itself, making it
 // a silent no-op. That stub has been removed to prevent confusion.
+//
 // — If you need to run the responsive engine standalone (e.g. from a
 //   sub-package that builds its own $utilities map independently of
 //   generate-utilities), use the engine mixin directly:
+//
 //     @use "@mastors/core/scss/responsive/engine" as engine;
 //     @include engine.run($my-utilities);
+//
 // — For the standard case, simply pass your $utilities map to
 //   generate-utilities() and set responsive: true on any entry that
 //   needs breakpoint variants — the responsive pass runs automatically.

package/scss/helpers/_visually-hidden.scss

@@ -1,39 +1,26 @@
 // helpers/_visually-hidden.scss
 // Visually hides content while keeping it accessible to screen readers.
 // ─────────────────────────────────────────────────────────────
-// The canonical implementation lives in accessibility/_screen-reader.scss
-// (.sr-only / .not-sr-only — the modern standard class names).
-// This file provides the legacy aliases (.visually-hidden, .vh,
-// .visually-hidden-focusable) that map onto the same rules, so existing
-// codebases using either naming convention continue to work without
-// duplicating any declarations.
 
-@use "../accessibility/screen-reader" as *;
+// Shared styles as a placeholder to avoid cross-module @extend issues
+%visually-hidden-base {
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  clip: rect(0, 0, 0, 0) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+}
 
-// Legacy aliases — extend the canonical sr-only rules
-// so no extra CSS is emitted; both class names share one rule block.
 .visually-hidden,
 .vh {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border-width: 0;
+  @extend %visually-hidden-base;
 }
 
 // Undo visually-hidden when focused (e.g. skip links)
 .visually-hidden-focusable:not(:focus):not(:focus-within) {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border-width: 0;
+  @extend %visually-hidden-base;
 }

package/scss/mixins/_breakpoint.scss

@@ -9,10 +9,10 @@
 /// @param {String} $bp - breakpoint key (sm, md, lg, xl, 2xl)
 @mixin bp($bp) {
   $value: map.get(bpvars.$breakpoints, $bp);
-  @if not $value {
+  @if $value == null {
     @error "bp(): unknown breakpoint '#{$bp}'. Available: #{map.keys(bpvars.$breakpoints)}";
   }
-  @if $value == 0 {
+  @if $value == 0px {
     @content;
   } @else {
     @media (min-width: #{$value}) { @content; }
@@ -26,7 +26,7 @@
 /// Emit styles below a named breakpoint
 @mixin breakpoint-down($bp) {
   $value: map.get(bpvars.$breakpoints, $bp);
-  @if not $value {
+  @if $value == null {
     @error "breakpoint-down(): unknown breakpoint '#{$bp}'";
   }
   @media (max-width: #{$value - 0.02px}) { @content; }

package/scss/mixins/_transition.scss

@@ -10,7 +10,7 @@
 /// @param {String} $duration  - duration token key (default: "200")
 /// @param {String} $easing    - easing token key (default: "in-out")
 @mixin transition($properties: (all), $duration: "200", $easing: "in-out") {
-  $dur: tr.duration($duration);
+  $dur:  tr.duration($duration);
   $ease: tr.easing($easing);
   $transitions: ();
   @each $prop in $properties {

package/scss/responsive/_engine.scss

@@ -8,8 +8,10 @@
 
 // Responsive engine — generates breakpoint-prefixed variants
 // of any utility that declares responsive: true.
+//
 // Class pattern:  .{bp}\:{utility}
 // Example output: .sm\:hidden, .md\:flex, .lg\:gap-8
+//
 // Sub-packages pass their $utilities map here via @include engine.run()
 // so the engine iterates breakpoints and re-emits the classes.
 
@@ -19,11 +21,11 @@
   @if flags.$enable-responsive {
     @each $bp-key, $bp-value in bpvars.$breakpoints {
       // Skip xs — no prefix, already emitted as base classes
-      @if $bp-value != 0 {
+      @if $bp-value != 0px {
         @media (min-width: #{$bp-value}) {
           @each $name, $config in $utilities {
             @if map.get($config, responsive) == true {
-              $prop: map.get($config, property);
+              $prop:   map.get($config, property);
               $values: map.get($config, values);
               $prefix: map.get($config, prefix);
 
@@ -39,7 +41,7 @@
                 // When the breakpoint key begins with a number (e.g. "2xl"),
                 // escape it using the CSS identifier-escape syntax: \3X  (space after hex).
                 $first: string.slice("#{$bp-key}", 1, 1);
-                $rest: string.slice("#{$bp-key}", 2);
+                $rest:  string.slice("#{$bp-key}", 2);
                 $safe-bp: null;
                 @if $first == "0" or $first == "1" or $first == "2" or $first == "3" or
                     $first == "4" or $first == "5" or $first == "6" or $first == "7" or

package/scss/responsive/_fluid-type.scss

@@ -7,6 +7,7 @@
 
 // Fluid type scale — font sizes that scale smoothly between two viewport widths.
 // Uses clamp() so no media queries are needed.
+//
 // Usage in component SCSS:
 //   @use "@mastors/core/api" as m;
 //   font-size: m.fluid-type(1rem, 1.5rem);
@@ -16,7 +17,7 @@
 /// @param {Number} $max-size  - maximum font size (rem)
 /// @param {Number} $min-vw    - viewport at which min applies (px, default 320px)
 /// @param {Number} $max-vw    - viewport at which max applies (px, default 1280px)
-@mixin apply-fluid-type($min-size, $max-size, $min-vw: 320px, $max-vw: 1280px) {
+@mixin fluid-type($min-size, $max-size, $min-vw: 320px, $max-vw: 1280px) {
   font-size: mathfn.fluid($min-size, $max-size, $min-vw, $max-vw);
 }
 
@@ -30,11 +31,11 @@
 // Include with: @use "@mastors/core/scss/responsive/fluid-type" as ft;
 //               @include ft.fluid-scale();
 @mixin fluid-scale {
-  h1 { @include apply-fluid-type(2rem,    3.75rem); }
-  h2 { @include apply-fluid-type(1.5rem,  3rem); }
-  h3 { @include apply-fluid-type(1.25rem, 2.25rem); }
-  h4 { @include apply-fluid-type(1.125rem, 1.875rem); }
-  h5 { @include apply-fluid-type(1rem,    1.5rem); }
-  h6 { @include apply-fluid-type(0.875rem, 1.25rem); }
-  p  { @include apply-fluid-type(0.875rem, 1.125rem); }
+  h1 { @include fluid-type(2rem,    3.75rem); }
+  h2 { @include fluid-type(1.5rem,  3rem); }
+  h3 { @include fluid-type(1.25rem, 2.25rem); }
+  h4 { @include fluid-type(1.125rem, 1.875rem); }
+  h5 { @include fluid-type(1rem,    1.5rem); }
+  h6 { @include fluid-type(0.875rem, 1.25rem); }
+  p  { @include fluid-type(0.875rem, 1.125rem); }
 }

package/scss/semantic/_colors.scss

@@ -9,21 +9,21 @@
 // emitted by themes/_base-theme.scss, _light.scss, _dark.scss.
 // Downstream packages can @use this file to access semantic names.
 
-$color-bg: var(--mastors-bg) !default;
-$color-bg-subtle: var(--mastors-bg-subtle) !default;
-$color-surface: var(--mastors-surface) !default;
-$color-surface-raised: var(--mastors-surface-raised) !default;
-$color-surface-overlay: var(--mastors-surface-overlay) !default;
+$color-bg:              var(--mastors-bg)               !default;
+$color-bg-subtle:       var(--mastors-bg-subtle)        !default;
+$color-surface:         var(--mastors-surface)          !default;
+$color-surface-raised:  var(--mastors-surface-raised)   !default;
+$color-surface-overlay: var(--mastors-surface-overlay)  !default;
 
-$color-text: var(--mastors-text) !default;
-$color-text-muted: var(--mastors-text-muted) !default;
-$color-text-subtle: var(--mastors-text-subtle) !default;
-$color-text-inverse: var(--mastors-text-inverse) !default;
+$color-text:            var(--mastors-text)             !default;
+$color-text-muted:      var(--mastors-text-muted)       !default;
+$color-text-subtle:     var(--mastors-text-subtle)      !default;
+$color-text-inverse:    var(--mastors-text-inverse)     !default;
 
-$color-border: var(--mastors-border) !default;
-$color-border-strong: var(--mastors-border-strong) !default;
+$color-border:          var(--mastors-border)           !default;
+$color-border-strong:   var(--mastors-border-strong)    !default;
 
-$color-accent: var(--mastors-accent) !default;
-$color-accent-hover: var(--mastors-accent-hover) !default;
-$color-accent-subtle: var(--mastors-accent-subtle) !default;
-$color-accent-text: var(--mastors-accent-text) !default;
+$color-accent:          var(--mastors-accent)           !default;
+$color-accent-hover:    var(--mastors-accent-hover)     !default;
+$color-accent-subtle:   var(--mastors-accent-subtle)    !default;
+$color-accent-text:     var(--mastors-accent-text)      !default;

package/scss/semantic/_spacing.scss

@@ -6,8 +6,8 @@
 
 // Semantic spacing aliases — layout-level naming on top of raw scale tokens.
 
-$space-inline: sp.spacing(1) !default; // 0.25rem — tight inline gap
-$space-element: sp.spacing(2) !default; // 0.5rem  — within a component
-$space-component: sp.spacing(4) !default; // 1rem    — between component parts
-$space-section: sp.spacing(16) !default; // 4rem    — between page sections
-$space-page: sp.spacing(24) !default; // 6rem    — page-level breathing room
+$space-inline:     sp.spacing(1)   !default; // 0.25rem — tight inline gap
+$space-element:    sp.spacing(2)   !default; // 0.5rem  — within a component
+$space-component:  sp.spacing(4)   !default; // 1rem    — between component parts
+$space-section:    sp.spacing(16)  !default; // 4rem    — between page sections
+$space-page:       sp.spacing(24)  !default; // 6rem    — page-level breathing room

package/scss/semantic/_typography.scss

@@ -6,8 +6,8 @@
 
 // Semantic typography role aliases.
 
-$font-display: ty.font-family("sans") !default; // Hero headings
-$font-heading: ty.font-family("sans") !default; // h1–h6
-$font-body: ty.font-family("sans") !default; // p, li, td
-$font-mono: ty.font-family("mono") !default; // code, pre, kbd
-$font-ui: ty.font-family("sans") !default; // labels, buttons, nav
+$font-display:  ty.font-family("sans")  !default; // Hero headings
+$font-heading:  ty.font-family("sans")  !default; // h1–h6
+$font-body:     ty.font-family("sans")  !default; // p, li, td
+$font-mono:     ty.font-family("mono")  !default; // code, pre, kbd
+$font-ui:       ty.font-family("sans")  !default; // labels, buttons, nav

package/scss/themes/_base-theme.scss

@@ -5,21 +5,26 @@
 // The light and dark themes (_light.scss, _dark.scss) are the actual emitters.
 // This file documents the full semantic custom property contract
 // that all themes must implement, without producing any CSS output.
+//
 // Semantic custom properties contract:
+//
 //   Surfaces
 //   --mastors-bg              ← page background
 //   --mastors-bg-subtle       ← subdued page background
 //   --mastors-surface         ← card / panel surface
 //   --mastors-surface-raised  ← elevated surface (dropdowns, tooltips)
 //   --mastors-surface-overlay ← modal/overlay surface
+//
 //   Text
 //   --mastors-text            ← primary text
 //   --mastors-text-muted      ← secondary / supporting text
 //   --mastors-text-subtle     ← tertiary / placeholder text
 //   --mastors-text-inverse    ← text on dark/accent surfaces
+//
 //   Borders
 //   --mastors-border          ← default border
 //   --mastors-border-strong   ← emphasis border
+//
 //   Brand / Accent
 //   --mastors-accent          ← primary brand color
 //   --mastors-accent-hover    ← accent hover state

package/scss/themes/_dark.scss

@@ -2,18 +2,17 @@
 // Dark theme CSS custom property overrides.
 // ─────────────────────────────────────────────────────────────
 
-@use "../tokens/color" as ct;
+@use "../tokens/color"   as ct;
+@use "../config/settings" as cfg;
 
 // Dark theme — inverts surface/text/border semantics.
-// Strategy is controlled by $dark-mode-strategy (default: "class").
-//   "class"  → activated by .dark / [data-theme="dark"] on <html>
-//   "media"  → activated by prefers-color-scheme: dark
+// Activated by .dark class on <html> (class mode)
+// or automatically via prefers-color-scheme (media mode).
 
-$dark-mode-strategy: "class" !default;
+$-dark-selectors: '[data-theme="dark"], .dark';
 
-@if $dark-mode-strategy == "class" {
-  [data-theme="dark"],
-  .dark {
+@if cfg.config("dark-mode") == "class" {
+  #{$-dark-selectors} {
     --mastors-bg:              #{ct.color("neutral", 950)};
     --mastors-bg-subtle:       #{ct.color("neutral", 900)};
     --mastors-surface:         #{ct.color("neutral", 900)};

package/scss/tokens/_color.scss

@@ -83,18 +83,14 @@ $color-tokens: (
     "900": #164e63,
     "950": #083344,
   ),
-  "white": #fff,
-  "black": #000,
+  "white": #ffffff,
+  "black": #000000,
   "transparent": transparent,
 ) !default;
 
 // Accessor: color("primary", 600)
 @function color($palette, $shade: null) {
   $p: map.get($color-tokens, $palette);
-
-  @if $shade {
-    @return map.get($p, "#{$shade}");
-  }
-
-  @return $p;
+  @if $shade == null { @return $p; }
+  @return map.get($p, "#{$shade}");
 }

package/scss/tokens/_shadows.scss

@@ -4,14 +4,16 @@
 
 @use "sass:map";
 
+// Multi-layer shadow values must be wrapped in extra parens inside a map
+// so the comma is not misread as a map-entry separator.
 $shadow-tokens: (
-  "xs":    (0 1px 2px 0 rgb(0 0 0 / 5%)),
-  "sm":    (0 1px 3px 0 rgb(0 0 0 / 10%), 0 1px 2px -1px rgb(0 0 0 / 10%)),
-  "md":    (0 4px 6px -1px rgb(0 0 0 / 10%), 0 2px 4px -2px rgb(0 0 0 / 10%)),
-  "lg":    (0 10px 15px -3px rgb(0 0 0 / 10%), 0 4px 6px -4px rgb(0 0 0 / 10%)),
-  "xl":    (0 20px 25px -5px rgb(0 0 0 / 10%), 0 8px 10px -6px rgb(0 0 0 / 10%)),
-  "2xl":   (0 25px 50px -12px rgb(0 0 0 / 25%)),
-  "inner": (inset 0 2px 4px 0 rgb(0 0 0 / 5%)),
+  "xs":    (0 1px 2px 0 rgb(0 0 0 / 0.05)),
+  "sm":    (0 1px 3px 0 rgb(0 0 0 / 0.10), 0 1px 2px -1px rgb(0 0 0 / 0.10)),
+  "md":    (0 4px 6px -1px rgb(0 0 0 / 0.10), 0 2px 4px -2px rgb(0 0 0 / 0.10)),
+  "lg":    (0 10px 15px -3px rgb(0 0 0 / 0.10), 0 4px 6px -4px rgb(0 0 0 / 0.10)),
+  "xl":    (0 20px 25px -5px rgb(0 0 0 / 0.10), 0 8px 10px -6px rgb(0 0 0 / 0.10)),
+  "2xl":   (0 25px 50px -12px rgb(0 0 0 / 0.25)),
+  "inner": (inset 0 2px 4px 0 rgb(0 0 0 / 0.05)),
   "none":  none,
 ) !default;
 

package/scss/tokens/_sizing.scss

@@ -5,7 +5,8 @@
 @use "sass:map";
 
 $sizing-tokens: (
-  "0":    0,
+  // Fixed scale (shares spacing scale keys)
+  "0":    0px,
   "px":   1px,
   "1":    0.25rem,
   "2":    0.5rem,
@@ -23,15 +24,17 @@ $sizing-tokens: (
   "72":   18rem,
   "80":   20rem,
   "96":   24rem,
+  // Fractions
   "1\\/2":  50%,
-  "1\\/3":  33.3333%,
-  "2\\/3":  66.6667%,
+  "1\\/3":  33.333333%,
+  "2\\/3":  66.666667%,
   "1\\/4":  25%,
   "3\\/4":  75%,
   "1\\/5":  20%,
   "2\\/5":  40%,
   "3\\/5":  60%,
   "4\\/5":  80%,
+  // Keywords
   "auto":    auto,
   "full":    100%,
   "screen":  100vw,