css-is-awesome 1.1.0

package/scss/README.md

@@ -0,0 +1,55 @@
+# scss/
+
+The Sass source of css-is-awesome. Tier 1 consumers want the compiled CSS in
+`dist/`; Tier 2 consumers (`@use` mixins, author their own class names) want
+the files in this folder. Imported through the npm package — don't copy these
+into your project.
+
+## Canonical example
+
+Per-component styles import the **zero-emit authoring barrel** — the whole API
+under one namespace, and nothing is printed until you call a mixin (safe inside
+a `.module.scss` under Next.js CSS Modules pure mode):
+
+```scss
+@use 'css-is-awesome/api' as cia;
+
+.hero-cta { @include cia.btn(primary, $r: full); @include cia.elevation(2); }
+```
+
+The global tokens (`:root { --… }`) are emitted once at your app root by the CSS
+bundle (`css-is-awesome`) or a theme stylesheet — not per component.
+
+Compile with Sass + a load path (or the modern package importer):
+
+```bash
+sass app.scss app.css --load-path=node_modules
+```
+
+## What lives here
+
+| Path                    | Purpose                                                        |
+| ----------------------- | -------------------------------------------------------------- |
+| `main.scss`             | Full library entry — tokens + resets + utilities.              |
+| `core.scss`             | Tokens + resets only (pair with your own utility set).         |
+| `utilities-only.scss`   | Drop-in `cia-*` utility classes, no tokens or resets.          |
+| `api.scss`              | **Zero-emit authoring barrel** — `@use 'css-is-awesome/api' as cia;`. Full mixin/function API, prints nothing until called. Use in component `.module.scss` files. |
+| `_index.scss`           | Kitchen-sink barrel — `api` **plus** the global `.cia-anim-*` utility CSS. |
+| `_mixins.scss`          | Core mixin API: `color`, `space`, `btn-base`, `font`, etc.     |
+| `_layout.scss`          | `container`, `grid`, `page-layout`, stack/inline helpers.      |
+| `_utilities.scss`       | `cia-*` utility class generator (margin, padding, color, …).   |
+| `_icons.scss`           | SVG + Font Awesome icon mixins (`svg`, `svg-text`, `fa`).      |
+| `_animations.scss`      | Keyframe library + `animate()` mixin + `cia-anim-*` utilities. |
+| `_generator.scss`       | SCSS maps → `:root { --token: value; }` writer.                |
+| `_system.scss`          | Compile-time constants (breakpoints, spacing scale, z-index).  |
+| `components/`           | Per-family component mixins (`buttons`, `forms`, `data`, …).   |
+| `theme/`                | Default theme maps (brand, colors, type, shape, shadows).      |
+| `recipes/`              | Opt-in presets — currently `bare-tags` (Tier 3, Pico-mode).    |
+| `examples/`             | Reference snippets, not part of the entry. Read, don't `@use`. |
+| `_app-styles.scss`      | Template for consumer-owned styles. NOT part of the library.   |
+
+## Deeper reading
+
+- Authoring rules, tier decisions, mixin contracts → `../AGENTS.md`
+- Full reference (~14 KB) → `../css-is-awesome.instructions.md`
+- Contributors (repo only) → `../CONTRIBUTING.md`

package/scss/_animations-utilities.scss

@@ -0,0 +1,107 @@
+// ============================================================================
+// ANIMATIONS-UTILITIES — keyframes + .cia-anim-* + .cia-hover-* + global safety net
+// ============================================================================
+// Load ONCE globally. NOT safe to `@use` from a CSS Module (`.module.scss`)
+// because of the global `*, *::before, *::after` selector — CSS Modules
+// pure-mode rejects unscoped selectors.
+//
+// Counterpart to _animations.scss (which is the mixin surface).
+//
+// Two consumer patterns:
+//
+//   1. Full bundle (recommended) — main.scss already loads this file:
+//        @use 'css-is-awesome/scss/main';
+//
+//   2. Pieces — load this file once globally, then @use the mixin file
+//      from any .module.scss for the animate() / animate-on() API:
+//        // globals.scss (loaded once at app root)
+//        @use 'css-is-awesome/scss/animations-utilities';
+//
+//        // any-component.module.scss
+//        @use 'css-is-awesome/scss/animations' as anim;
+//        .my-spinner { @include anim.animate(spin, $iteration: infinite, $timing: linear); }
+//
+// The mixin's `animation-name: cia-spin` reference resolves at runtime
+// against the global @keyframes declared here — even when the mixin call
+// site is inside a CSS Module.
+// ============================================================================
+@use './animations' as a;
+
+// ----------------------------------------------------------------------------
+// KEYFRAME LIBRARY
+// ----------------------------------------------------------------------------
+// The definitions themselves live in `_animations.scss` (`keyframes-for()`),
+// next to the `animate()` mixin that has to be able to emit them on its own.
+// This module just asks for all of them, so the global bundle keeps shipping
+// the full set while there is only ONE copy of each definition to maintain.
+@each $name in a.animation-names() {
+  @include a.keyframes-for($name);
+}
+
+// ----------------------------------------------------------------------------
+// UTILITY CLASSES — .cia-anim-* + .cia-hover-*
+// ----------------------------------------------------------------------------
+
+.cia-anim-fade-in       { @include a.animate(fade-in); }
+.cia-anim-fade-in-fast  { @include a.animate(fade-in, $speed: fast); }
+.cia-anim-fade-in-slow  { @include a.animate(fade-in, $speed: slow); }
+
+.cia-anim-fade-out      { @include a.animate(fade-out); }
+.cia-anim-fade-out-fast { @include a.animate(fade-out, $speed: fast); }
+.cia-anim-fade-out-slow { @include a.animate(fade-out, $speed: slow); }
+
+.cia-anim-slide-up       { @include a.animate(slide-up); }
+.cia-anim-slide-up-fast  { @include a.animate(slide-up, $speed: fast); }
+.cia-anim-slide-up-slow  { @include a.animate(slide-up, $speed: slow); }
+
+.cia-anim-slide-down       { @include a.animate(slide-down); }
+.cia-anim-slide-down-fast  { @include a.animate(slide-down, $speed: fast); }
+.cia-anim-slide-down-slow  { @include a.animate(slide-down, $speed: slow); }
+
+.cia-anim-slide-left       { @include a.animate(slide-left); }
+.cia-anim-slide-left-fast  { @include a.animate(slide-left, $speed: fast); }
+.cia-anim-slide-left-slow  { @include a.animate(slide-left, $speed: slow); }
+
+.cia-anim-slide-right       { @include a.animate(slide-right); }
+.cia-anim-slide-right-fast  { @include a.animate(slide-right, $speed: fast); }
+.cia-anim-slide-right-slow  { @include a.animate(slide-right, $speed: slow); }
+
+.cia-anim-scale-in       { @include a.animate(scale-in); }
+.cia-anim-scale-in-fast  { @include a.animate(scale-in, $speed: fast); }
+.cia-anim-scale-in-slow  { @include a.animate(scale-in, $speed: slow); }
+
+.cia-anim-pop       { @include a.animate(pop); }
+.cia-anim-pop-fast  { @include a.animate(pop, $speed: fast); }
+.cia-anim-pop-slow  { @include a.animate(pop, $speed: slow); }
+
+.cia-anim-wiggle       { @include a.animate(wiggle); }
+.cia-anim-wiggle-fast  { @include a.animate(wiggle, $speed: fast); }
+.cia-anim-wiggle-slow  { @include a.animate(wiggle, $speed: slow); }
+
+// Loopers — infinite by default when used as utility
+.cia-anim-spin    { @include a.animate(spin,    $speed: slow, $iteration: infinite, $timing: linear); }
+.cia-anim-pulse   { @include a.animate(pulse,   $speed: slow, $iteration: infinite); }
+.cia-anim-shimmer { @include a.animate(shimmer, $speed: slow, $iteration: infinite, $timing: linear); }
+
+.cia-hover-lift  { @include a.animate-on(hover, lift); }
+.cia-hover-glow  { @include a.animate-on(hover, glow); }
+.cia-hover-press { @include a.animate-on(hover, press); }
+.cia-hover-fade  { @include a.animate-on(hover, fade); }
+
+// ----------------------------------------------------------------------------
+// GLOBAL REDUCED-MOTION SAFETY NET
+// ----------------------------------------------------------------------------
+// Lives here (not in the mixin file) because the `*, *::before, *::after`
+// selector is bare-global — CSS Modules pure-mode rejects it. Consumers
+// load this file once globally; .module.scss code @use's the mixin file
+// instead and inherits this safety net from the global scope.
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    /* stylelint-disable declaration-no-important -- !important is the canonical pattern for the global reduced-motion safety net: it must override any animation/transition declared anywhere in the document. */
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+    /* stylelint-enable declaration-no-important */
+  }
+}

package/scss/_animations.scss

@@ -0,0 +1,248 @@
+// ============================================================================
+// ANIMATIONS — Mixin-only surface (safe to @use from .module.scss)
+// ============================================================================
+// Philosophy: a fixed keyframe vocabulary, theme-driven duration + easing.
+// Every animation reads from --duration-* and --ease so swapping themes
+// changes the feel (Terminal snappy, Glass floaty) with zero code change.
+//
+// Respects prefers-reduced-motion — all animations collapse to 0s.
+//
+// This file is the MIXIN surface. The keyframe definitions, .cia-anim-*
+// utility classes, and the global *, *::before, *::after reduced-motion
+// safety net live in _animations-utilities.scss — load that ONCE globally
+// (via main.scss or your app's global SCSS entry).
+//
+// Why split: top-level rules + global selectors here would fail Next.js
+// CSS Modules pure-mode (`Selector "*, *::before, *::after" is not pure`)
+// when a `.module.scss` does `@use 'css-is-awesome/scss/animations' as anim;`.
+// Mixin-only files are safe to @use from any scoped context.
+// ============================================================================
+@use 'sass:map';
+@use 'sass:list';
+@use 'sass:meta';
+
+// ----------------------------------------------------------------------------
+// ANIMATION VOCABULARY
+// ----------------------------------------------------------------------------
+// Maps animation slug → keyframe name. The keyframes themselves live in
+// _animations-utilities.scss (loaded globally). The mixin emits the name as
+// a string reference, which resolves at runtime against the globally-loaded
+// @keyframes — even when the mixin call site is inside a CSS Module.
+
+$_anims: (
+  fade-in:     cia-fade-in,
+  fade-out:    cia-fade-out,
+  slide-up:    cia-slide-up,
+  slide-down:  cia-slide-down,
+  slide-left:  cia-slide-left,
+  slide-right: cia-slide-right,
+  scale-in:    cia-scale-in,
+  pop:         cia-pop,
+  pulse:       cia-pulse,
+  shimmer:     cia-shimmer,
+  spin:        cia-spin,
+  wiggle:      cia-wiggle,
+);
+
+$_speeds: (
+  fast:   var(--duration-fast,   180ms),
+  normal: var(--duration-normal, 240ms),
+  slow:   var(--duration-slow,   380ms),
+);
+
+// ----------------------------------------------------------------------------
+// MIXIN API
+// ----------------------------------------------------------------------------
+// @include animate(fade-in);
+// @include animate(slide-up, $speed: slow);
+// @include animate(spin, $speed: slow, $iteration: infinite, $timing: linear);
+// ----------------------------------------------------------------------------
+
+// ----------------------------------------------------------------------------
+// KEYFRAME LIBRARY — the single definition of every cia keyframe.
+//
+// This lives here, next to `animate()`, rather than in `_animations-utilities`
+// because `animate()` has to be able to emit the keyframe it references. The
+// utilities module loops over these for the global bundle, so there is exactly
+// one copy of each definition.
+//
+// `@at-root` hoists the block out of whatever selector called `animate()`, and
+// co-emitting is what makes the reference survive CSS Modules: a top-level
+// `@keyframes` gets hashed to a local name while an `animation-name` written
+// elsewhere does not. Emitted together, both are renamed or neither is —
+// the same reason `spinner()` and `skeleton()` already do this.
+// ----------------------------------------------------------------------------
+/// Every animation name `animate()` and `keyframes-for()` accept.
+/// Exposed so the utilities bundle can loop the full set without duplicating
+/// the registry, and so consumers can enumerate what's available.
+@function animation-names() {
+  @return map.keys($_anims);
+}
+
+// Names already emitted in THIS compilation. Sass resets module state per
+// compiled file, which is exactly the granularity we want: one copy per output
+// file (CSS Modules needs its own hashed copy per module), never 42 copies in
+// one bundle because 30 utility classes each asked for one.
+$_emitted: ();
+
+@mixin keyframes-for($name) {
+  $keyframe: map.get($_anims, $name);
+  @if not $keyframe {
+    @error "keyframes-for(): unknown animation '#{$name}'. Known: #{map.keys($_anims)}";
+  }
+
+  @if not list.index($_emitted, $name) {
+    $_emitted: list.append($_emitted, $name) !global;
+    @include _emit-keyframe($name);
+  }
+}
+
+@mixin _emit-keyframe($name) {
+  @at-root {
+    @if $name == fade-in {
+      @keyframes cia-fade-in { from { opacity: 0; } to { opacity: 1; } }
+    } @else if $name == fade-out {
+      @keyframes cia-fade-out { from { opacity: 1; } to { opacity: 0; } }
+    } @else if $name == slide-up {
+      @keyframes cia-slide-up {
+        from { opacity: 0; transform: translateY(8px); }
+        to   { opacity: 1; transform: translateY(0); }
+      }
+    } @else if $name == slide-down {
+      @keyframes cia-slide-down {
+        from { opacity: 0; transform: translateY(-8px); }
+        to   { opacity: 1; transform: translateY(0); }
+      }
+    } @else if $name == slide-left {
+      @keyframes cia-slide-left {
+        from { opacity: 0; transform: translateX(8px); }
+        to   { opacity: 1; transform: translateX(0); }
+      }
+    } @else if $name == slide-right {
+      @keyframes cia-slide-right {
+        from { opacity: 0; transform: translateX(-8px); }
+        to   { opacity: 1; transform: translateX(0); }
+      }
+    } @else if $name == scale-in {
+      @keyframes cia-scale-in {
+        from { opacity: 0; transform: scale(0.96); }
+        to   { opacity: 1; transform: scale(1); }
+      }
+    } @else if $name == pop {
+      @keyframes cia-pop {
+        0%   { transform: scale(1); }
+        40%  { transform: scale(1.06); }
+        100% { transform: scale(1); }
+      }
+    } @else if $name == pulse {
+      @keyframes cia-pulse {
+        0%, 100% { opacity: 1; }
+        50%      { opacity: 0.55; }
+      }
+    } @else if $name == shimmer {
+      @keyframes cia-shimmer {
+        0%   { background-position: -200% 0; }
+        100% { background-position: 200% 0; }
+      }
+    } @else if $name == spin {
+      @keyframes cia-spin {
+        from { transform: rotate(0deg); }
+        to   { transform: rotate(360deg); }
+      }
+    } @else if $name == wiggle {
+      @keyframes cia-wiggle {
+        0%, 100% { transform: rotate(0deg); }
+        25%      { transform: rotate(-2deg); }
+        75%      { transform: rotate(2deg); }
+      }
+    }
+  }
+}
+
+@mixin animate(
+  $name,
+  $speed: normal,
+  $delay: 0s,
+  $iteration: 1,
+  $fill: both,
+  $timing: var(--ease, cubic-bezier(0.33, 0.66, 0.33, 1))
+) {
+  $keyframe: map.get($_anims, $name);
+
+  // A raw duration (`1s`, `750ms`) passes through. Only an unrecognised
+  // *keyword* is an error — rejecting raw values forced consumers to hand-roll
+  // the entire animation just to keep a duration the scale doesn't carry, which
+  // is exactly what Boiler's spinners did.
+  $duration: map.get($_speeds, $speed);
+  @if not $duration and meta.type-of($speed) == 'number' {
+    $duration: $speed;
+  }
+
+  @if not $keyframe {
+    @error "animate(): unknown animation '#{$name}'. Known: #{map.keys($_anims)}";
+  }
+  @if not $duration {
+    @error "animate(): unknown speed '#{$speed}'. Known: fast, normal, slow, or a duration like 1s";
+  }
+
+  // Co-emit the keyframe this rule references. Without it, `animate()` on the
+  // documented per-component path (`css-is-awesome/api`, or a theme <link> for
+  // tokens) emitted an `animation-name` pointing at nothing — valid CSS, no
+  // error, no animation. Duplicate identical @keyframes across files are
+  // harmless and gzip away; a dangling reference is not.
+  @include keyframes-for($name);
+
+  animation-name: $keyframe;
+  animation-duration: $duration;
+  animation-delay: $delay;
+  animation-iteration-count: $iteration;
+  animation-fill-mode: $fill;
+  animation-timing-function: $timing;
+
+  @media (prefers-reduced-motion: reduce) {
+    /* stylelint-disable declaration-no-important -- !important is the canonical pattern for honoring prefers-reduced-motion: it must override any inline animation declared by component author or third-party CSS. */
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    /* stylelint-enable declaration-no-important */
+  }
+}
+
+// ----------------------------------------------------------------------------
+// HOVER / INTERACTION HELPERS
+// ----------------------------------------------------------------------------
+// @include animate-on(hover, lift);
+// @include animate-on(hover, glow);
+// ----------------------------------------------------------------------------
+
+@mixin animate-on($event: hover, $effect: lift) {
+  transition:
+    transform  var(--duration-fast, 180ms) var(--ease, ease),
+    box-shadow var(--duration-fast, 180ms) var(--ease, ease),
+    opacity    var(--duration-fast, 180ms) var(--ease, ease);
+
+  @if $effect == lift {
+    &:#{$event} {
+      transform: translateY(-2px);
+      box-shadow: var(--shadow-md);
+    }
+  } @else if $effect == glow {
+    &:#{$event} {
+      box-shadow: var(--glow-md);
+    }
+  } @else if $effect == press {
+    &:#{$event} {
+      transform: translateY(1px) scale(0.99);
+    }
+  } @else if $effect == fade {
+    &:#{$event} {
+      opacity: 0.7;
+    }
+  } @else {
+    @error "animate-on(): unknown effect '#{$effect}'. Known: lift, glow, press, fade";
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+    &:#{$event} { transform: none; }
+  }
+}

package/scss/_app-styles.scss

@@ -0,0 +1,15 @@
+// ============================================================================
+// APP STYLES — Project-Owned Custom Styles
+// ============================================================================
+// This file belongs to YOUR PROJECT, not the boilerplate.
+// The boilerplate will NEVER overwrite this file during /update-project syncs.
+//
+// Use this file for:
+//   - Custom animations specific to your app
+//   - App-specific layout patterns
+//   - Unique styles that don't belong in the shared design system
+//   - Project-level utility classes
+//
+// This is NOT an override file — it's for NEW styles your project needs.
+// For theme colors, use _theme.scss instead.
+// ============================================================================

package/scss/_generator.scss

@@ -0,0 +1,174 @@
+// ============================================================================
+// GENERATOR - SCSS Maps → CSS Custom Properties
+// ============================================================================
+// Loops over theme maps and system maps to generate CSS custom properties.
+// This is the bridge: SCSS data → :root { --token: value; }
+// Replaces the old _tokens.scss
+// ============================================================================
+@use 'sass:map';
+@use 'sass:list';
+@use 'sass:meta';
+@use 'sass:string';
+@use './theme' as t;
+@use './system' as s;
+
+// ----------------------------------------------------------------------------
+// HELPER: Generic map-to-vars generator
+// ----------------------------------------------------------------------------
+@mixin _vars($map, $prefix: '') {
+  @each $key, $value in $map {
+    @if $prefix != '' {
+      --#{$prefix}-#{$key}: #{$value};
+    } @else {
+      --#{$key}: #{$value};
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// VALIDATION: Ensure theme maps have required keys
+// ----------------------------------------------------------------------------
+$_required-light-keys: (
+  background-default, surface-default, text-primary, text-secondary,
+  text-muted, text-inverse, text-link, border-default, border-focus,
+  action-primary-default, action-primary-hover, action-primary-active,
+  success-default, warning-default, error-default, info-default,
+);
+
+@mixin _validate-theme {
+  @each $key in $_required-light-keys {
+    @if not map.has-key(t.$theme-light, $key) {
+      @warn "Theme missing required light color: #{$key}";
+    }
+  }
+  @each $key in $_required-light-keys {
+    @if not map.has-key(t.$theme-dark, $key) {
+      @warn "Theme missing required dark color: #{$key}";
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// GENERATE: All light mode tokens
+// ----------------------------------------------------------------------------
+@mixin generate-light {
+  // Brand colors (from theme)
+  @include _vars(t.$theme-brand, 'brand');
+
+  // Semantic colors - light (from theme)
+  @include _vars(t.$theme-light);
+
+  // Border radius (from theme)
+  @include _vars(t.$theme-radius, 'radius');
+
+  // Shadows - light (from theme)
+  @include _vars(t.$theme-shadows-light, 'shadow');
+
+  // Fonts (from theme)
+  @each $key, $stack in t.$theme-fonts {
+    --font-#{$key}: #{list.join($stack, (), comma)};
+  }
+
+  // Spacing scale (from system)
+  //
+  // The numbered scale is the source of truth (locked decision); the t-shirt
+  // names are aliases. They now emit as var() REFERENCES to the numbered
+  // token rather than as duplicate literals, so a theme that sets --space-4
+  // moves --space-md with it.
+  //
+  // Previously both emitted as independent literals that happened to hold the
+  // same value. A theme could only declare the six t-shirt names, while
+  // components overwhelmingly call space(4)/space(1) -> var(--space-4). So
+  // themes could not change spacing at all: the token they set and the token
+  // components read were different variables. That is why swapping a theme
+  // repainted colours but never re-proportioned the page.
+  @each $key, $value in s.$spacing-scale {
+    --space-#{$key}: #{$value};
+  }
+  @each $key in (0, none, 2xs) {
+    --space-#{$key}: #{map.get(s.$spacing, $key)};
+  }
+  @each $alias, $num in s.$spacing-aliases {
+    --space-#{$alias}: var(--space-#{$num});
+  }
+
+  // Z-index (from system)
+  @include _vars(s.$z-layers, 'z');
+
+  // Typography (from system)
+  @include _vars(s.$font-sizes, 'font-size');
+  @include _vars(s.$font-weights, 'font-weight');
+  @include _vars(s.$line-heights, 'line-height');
+
+  // Durations (from system)
+  @include _vars(s.$durations, 'duration');
+
+  // Opacity (from system)
+  @include _vars(s.$opacities, 'opacity');
+
+  // Component tokens (Feature 1.3) — emit each entry as a CSS custom
+  // property on :root. Themes may override these selectively in their
+  // own :root block without forking the library.
+  @include _vars(t.$theme-components);
+}
+
+// ----------------------------------------------------------------------------
+// GENERATE: Dark mode overrides only
+// ----------------------------------------------------------------------------
+@mixin generate-dark {
+  // Semantic colors - dark (from theme)
+  @include _vars(t.$theme-dark);
+
+  // Shadows - dark (from theme)
+  @include _vars(t.$theme-shadows-dark, 'shadow');
+}
+
+// ----------------------------------------------------------------------------
+// GENERATE: Full theme (light base + dark variant)
+// ----------------------------------------------------------------------------
+@mixin generate-theme {
+  @include _validate-theme;
+
+  // :where() drops these library defaults to zero specificity so ANY theme
+  // declaration outruns them regardless of load order.
+  //
+  // Without it, a theme file dropped in as theme.css (which emits a bare
+  // `:root` so it works with no markup change) ties this block at (0,1,0) —
+  // and the documented load order is theme first, library second, so the
+  // LIBRARY won. Colours were unaffected because only themes declare them,
+  // but every token the library also emits — the spacing scale, z-layers,
+  // font sizes — silently ignored the theme.
+  //
+  // Specificity only ever decreases here, so nothing that used to win can
+  // start losing. Consumers overriding tokens from their own `:root` now win
+  // outright instead of depending on source order. Deliberately :where() and
+  // not @layer — see the project rule against layered CSS.
+  :where(:root) {
+    @include generate-light;
+  }
+
+  [data-theme="light"] {
+    @include generate-light;
+  }
+
+  [data-theme="dark"] {
+    @include generate-dark;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      @include generate-dark;
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// GENERATE: Scoped theme (for component-level theming)
+// ----------------------------------------------------------------------------
+@mixin generate-scoped($mode: light) {
+  @if $mode == light {
+    @include generate-light;
+  } @else {
+    @include generate-dark;
+  }
+}