@lnpg/pkgn-sol 1.0.0-beta.0

package/src/scss/maps/_spacing.scss

@@ -0,0 +1,63 @@
+/**
+ * pkgn-sol Design Foundation: Spacing Maps
+ *
+ * Structured spacing scale derived from the canonical spacing token layer.
+ *
+ * This map exists to provide a predictable, named scale (0..10) for
+ * margin/padding utilities and component rhythm, while keeping the underlying
+ * values locked to the token source.
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  maps.spacing
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use '../tokens/spacing' as spacing;
+
+/* --------------------------------------------------------------------------
+ - Spacing scale
+ ------------------------------------------------------------------------- */
+
+/**
+ * Spacing scale.
+ *
+ * Keys:
+ * - 0 is hard zero (unitless by design).
+ * - 1..10 are rem-based lengths derived from $base-spacing.
+ *
+ * Multipliers:
+ * 0:  0
+ * 1:  0.25x
+ * 2:  0.5x
+ * 3:  0.75x
+ * 4:  1x
+ * 5:  1.25x
+ * 6:  1.5x
+ * 7:  1.75x
+ * 8:  2x
+ * 9:  3x
+ * 10: 4x
+ *
+ * @type map
+ */
+$spacing: (
+  0: 0,
+  1: spacing.$base-spacing * 0.25,
+  2: spacing.$base-spacing * 0.5,
+  3: spacing.$base-spacing * 0.75,
+  4: spacing.$base-spacing,
+  5: spacing.$base-spacing * 1.25,
+  6: spacing.$base-spacing * 1.5,
+  7: spacing.$base-spacing * 1.75,
+  8: spacing.$base-spacing * 2,
+  9: spacing.$base-spacing * 3,
+  10: spacing.$base-spacing * 4,
+);

package/src/scss/maps/_theme.scss

@@ -0,0 +1,206 @@
+/**
+ * pkgn-sol Design Foundation: Theme Maps
+ *
+ * Structured theme registry derived from the canonical theme token layer.
+ *
+ * This map exists to provide a single, iterable surface for consumer-
+ * overridable theme primitives (branding, semantic colours, asset paths).
+ *
+ * IMPORTANT:
+ * - Theme values are intended to be overridden by consumers via:
+ *   `@use "tokens/theme" with (...)`
+ * - This map MUST mirror the theme token layer exactly.
+ * - This file must not introduce derived values, transformations, or logic.
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  maps.theme
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use '../tokens/fonts' as fonts;
+@use '../tokens/theme' as theme;
+
+/* ----------------------------------------------------------------------------
+ - Global feature flags
+ --------------------------------------------------------------------------- */
+
+/**
+ * Global feature flags.
+ *
+ * @type map
+ */
+$feature-flags: (
+  'theme-dark-mode': theme.$theme-dark-mode,
+);
+
+/* ----------------------------------------------------------------------------
+ - Namespace & prefixing
+ --------------------------------------------------------------------------- */
+
+/**
+ * Namespace & prefixing configuration.
+ *
+ * @type map
+ */
+$namespace: (
+  'theme-prefix': theme.$theme-prefix,
+);
+
+/* ----------------------------------------------------------------------------
+ - Font families (semantic roles)
+ --------------------------------------------------------------------------- */
+
+/**
+ * Theme-level font family roles.
+ *
+ * Note: These are single family names, not full stacks.
+ * Stacks are defined in the typography token layer.
+ *
+ * @type map
+ */
+$font-families: (
+  'base-font': theme.$base-font,
+  'heading-font': theme.$heading-font,
+  'code-font': theme.$code-font,
+);
+
+/* ----------------------------------------------------------------------------
+ - Base colours (structural)
+ --------------------------------------------------------------------------- */
+
+/**
+ * Structural / foundational colours.
+ *
+ * @type map
+ */
+$base-colours: (
+  'body-bg-color': theme.$body-bg-color,
+  'base-font-color': theme.$base-font-color,
+  'code-font-color': theme.$code-font-color,
+  'heading-font-color': theme.$heading-font-color,
+);
+
+/* ----------------------------------------------------------------------------
+ - Semantic brand colours
+ --------------------------------------------------------------------------- */
+
+/**
+ * Semantic brand colour roles.
+ *
+ * @type map
+ */
+$brand-colours: (
+  'primary-colour': theme.$primary-colour,
+  'secondary-colour': theme.$secondary-colour,
+  'tertiary-colour': theme.$tertiary-colour,
+);
+
+/* ----------------------------------------------------------------------------
+ - Semantic state colours
+ --------------------------------------------------------------------------- */
+
+/**
+ * Semantic state colours (UI feedback roles).
+ *
+ * @type map
+ */
+$state-colours: (
+  'success-colour': theme.$success-colour,
+  'info-colour': theme.$info-colour,
+  'warning-colour': theme.$warning-colour,
+  'danger-colour': theme.$danger-colour,
+);
+
+/* ----------------------------------------------------------------------------
+ - Light / dark aliases
+ --------------------------------------------------------------------------- */
+
+/**
+ * Light / dark surface aliases.
+ *
+ * @type map
+ */
+$surface-colours: (
+  'light-colour': theme.$light-colour,
+  'dark-colour': theme.$dark-colour,
+);
+
+/* ----------------------------------------------------------------------------
+ - Asset paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Asset path configuration.
+ *
+ * @type map
+ */
+$asset-paths: (
+  'base-font-path': theme.$base-font-path,
+);
+
+/* ----------------------------------------------------------------------------
+ - Font source paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Font source paths grouped by semantic role.
+ *
+ * @type map
+ */
+$font-sources: (
+  'base': (
+    'normal': theme.$base-font-source-path,
+    'italic': theme.$base-font-italic-source-path,
+  ),
+  'headings': (
+    'normal': theme.$heading-font-source-path,
+    'italic': theme.$heading-font-italic-source-path,
+  ),
+  'code': (
+    'normal': theme.$code-font-source-path,
+    'italic': theme.$code-font-italic-source-path,
+  ),
+);
+
+/**
+ * Selected font source metadata.
+ *
+ * @type map
+ */
+$font-source-format: (
+  'extension': fonts.$font-extension,
+  'format': fonts.$font-format,
+);
+
+/* ----------------------------------------------------------------------------
+ - Registry
+ --------------------------------------------------------------------------- */
+
+/**
+ * Top-level theme registry.
+ *
+ * Grouped maps intended for iteration by generators and utilities.
+ * Values are locked directly to the canonical theme token layer.
+ *
+ * @type map
+ */
+$theme: (
+  'feature-flags': $feature-flags,
+  'namespace': $namespace,
+  'font-families': $font-families,
+  'base-colours': $base-colours,
+  'brand-colours': $brand-colours,
+  'state-colours': $state-colours,
+  'surface-colours': $surface-colours,
+  'asset-paths': $asset-paths,
+  'font-sources': $font-sources,
+  'font-source-format': $font-source-format,
+);

package/src/scss/maps/_typography.scss

@@ -0,0 +1,127 @@
+/**
+ * pkgn-sol Design Foundation: Typography Maps
+ *
+ * Structured map groupings derived from the typography token layer.
+ *
+ * These maps provide consistent, named access to typography primitives and
+ * computed scales (e.g. weights, heading sizes) while keeping all values
+ * locked to the canonical token source.
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  maps.typography
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use '../tokens/typography' as typography;
+
+/* --------------------------------------------------------------------------
+ - Font families
+ ------------------------------------------------------------------------- */
+
+/**
+ * Font family stacks.
+ *
+ * @type map
+ */
+$font-families: (
+  'base-font-family': typography.$base-font-family,
+  'heading-font-family': typography.$heading-font-family,
+  'code-font-family': typography.$code-font-family,
+);
+
+/* --------------------------------------------------------------------------
+ - Font weights
+ ------------------------------------------------------------------------- */
+
+/**
+ * Numeric font weight scale.
+ *
+ * @type map
+ */
+$font-weights: (
+  'thin-font-weight': typography.$thin-font-weight,
+  'lighter-font-weight': typography.$lighter-font-weight,
+  'light-font-weight': typography.$light-font-weight,
+  'normal-font-weight': typography.$normal-font-weight,
+  'medium-font-weight': typography.$medium-font-weight,
+  'semibold-font-weight': typography.$semibold-font-weight,
+  'bold-font-weight': typography.$bold-font-weight,
+  'bolder-font-weight': typography.$bolder-font-weight,
+  'black-font-weight': typography.$black-font-weight,
+);
+
+/* --------------------------------------------------------------------------
+ - Font sizes
+ ------------------------------------------------------------------------- */
+
+/**
+ * Font size scale, including derived heading sizes.
+ *
+ * @type map
+ */
+$font-sizes: (
+  'base-font-size': typography.$base-font-size,
+  'font-size-h1': typography.$font-size-h1,
+  'font-size-h2': typography.$font-size-h2,
+  'font-size-h3': typography.$font-size-h3,
+  'font-size-h4': typography.$font-size-h4,
+  'font-size-h5': typography.$font-size-h5,
+  'font-size-h6': typography.$font-size-h6,
+);
+
+/* --------------------------------------------------------------------------
+ - Formatting
+ ------------------------------------------------------------------------- */
+
+/**
+ * Core typographic formatting rules.
+ *
+ * @type map
+ */
+$formatting: (
+  'base-font-weight': typography.$base-font-weight,
+  'heading-font-weight': typography.$heading-font-weight,
+  'base-line-height': typography.$base-line-height,
+  'heading-line-height': typography.$heading-line-height,
+);
+
+/* --------------------------------------------------------------------------
+ - Spacing
+ ------------------------------------------------------------------------- */
+
+/**
+ * Vertical spacing tokens related to typography.
+ *
+ * @type map
+ */
+$spacing: (
+  'base-margin-bottom': typography.$base-margin-bottom,
+  'heading-margin-bottom': typography.$heading-margin-bottom,
+);
+
+/* --------------------------------------------------------------------------
+ - Registry
+ ------------------------------------------------------------------------- */
+
+/**
+ * Top-level typography registry.
+ *
+ * Grouped maps for consumption by mixins/utilities.
+ *
+ * @type map
+ */
+$typography: (
+  'font-families': $font-families,
+  'font-weights': $font-weights,
+  'font-sizes': $font-sizes,
+  'formatting': $formatting,
+  'spacing': $spacing,
+);

package/src/scss/mixins/_colours.scss

@@ -0,0 +1,304 @@
+/**
+ * pkgn-sol Design Foundation: Colour Mixins
+ *
+ * CSS custom property (variable) emitters for the canonical colour registries.
+ *
+ * This layer exists to bridge:
+ *   tokens -> maps -> functions -> mixins -> selectors (e.g. :root)
+ *
+ * Responsibilities:
+ * - Emit stable `:root` (or theme-scope) CSS variables for colour scales
+ * - Optionally emit companion `*-rgb` variables for opacity-friendly usage
+ * - Provide targeted emitters (single scale / subset) for consumers & generators
+ *
+ * Design notes:
+ * - We keep naming explicit and predictable.
+ * - We avoid "smart" transformations: keys become variable names, as-is.
+ * - Defaults are opinionated, but everything is parameterised for consumers.
+ * - This file does not assume where it is included (core vs. consumer build).
+ *
+ * References / alignment:
+ * - Bootstrap's approach of emitting both hex vars and `*-rgb` vars is widely
+ *   used because it enables `rgba(var(--x-rgb), <alpha>)` patterns.
+ *
+ * @module
+ * @group  mixins.colours
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use 'sass:color';
+@use '../functions/colours' as fn;
+
+/* ----------------------------------------------------------------------------
+ - Internal helpers
+ --------------------------------------------------------------------------- */
+
+/**
+ * Builds a CSS custom property name.
+ *
+ * Example output (default):
+ *   --sol-colour-grey-tint-80
+ *
+ * @access private
+ *
+ * @param  {string} $key
+ * @param  {string} $var-prefix   Must include the leading `--` (default: --sol-)
+ * @param  {string} $group        Group namespace appended after prefix
+ *
+ * @return {string}
+ */
+@function _css-var-name($key, $var-prefix, $group) {
+  @if meta.type-of($key) != 'string' {
+    @error "Expected $key to be type 'string', got '#{meta.type-of($key)}'";
+  }
+
+  @if meta.type-of($var-prefix) != 'string' {
+    @error "Expected $var-prefix to be type 'string', got '#{meta.type-of($var-prefix)}'";
+  }
+
+  @if meta.type-of($group) != 'string' {
+    @error "Expected $group to be type 'string', got '#{meta.type-of($group)}'";
+  }
+
+  @return '#{$var-prefix}#{$group}-#{$key}';
+}
+
+/**
+ * Returns the `r, g, b` triple for a Sass colour.
+ *
+ * @access private
+ *
+ * @param  {color} $c
+ *
+ * @return {string}  e.g. "13, 110, 253"
+ */
+@function _rgb-triplet($c) {
+  @if meta.type-of($c) != 'color' {
+    @error "Expected $c to be a Sass color, got '#{meta.type-of($c)}'";
+  }
+
+  @return '#{color.channel($c, 'red', $space: rgb)}, #{color.channel($c, 'green', $space: rgb)}, #{color.channel($c, 'blue', $space: rgb)}';
+}
+
+/**
+ * Emits a single CSS custom property declaration.
+ *
+ * @access private
+ *
+ * @param  {string} $name   Full var name including `--`
+ * @param  {*}      $value
+ *
+ * @return {void}
+ */
+@mixin _emit-var($name, $value) {
+  @if meta.type-of($name) != 'string' {
+    @error "Expected $name to be type 'string', got '#{meta.type-of($name)}'";
+  }
+
+  #{$name}: #{$value};
+}
+
+/* ----------------------------------------------------------------------------
+ - Public emitters
+ --------------------------------------------------------------------------- */
+
+/**
+ * Emits CSS variables for a single colour scale.
+ *
+ * By default, emits:
+ * - `--sol-colour-<token-key>` for each entry in the scale map
+ * - Optional: `--sol-colour-<token-key>-rgb` companions (r,g,b triplets)
+ *
+ * Typical usage:
+ *   :root { @include colour-scale-vars("grey"); }
+ *   [data-theme="dark"] { @include colour-scale-vars("grey"); }
+ *
+ * @param  {string} $scale
+ * @param  {string} $var-prefix   Leading custom prop prefix (default: --sol-)
+ * @param  {string} $group        Namespace segment (default: colour)
+ * @param  {bool}   $with-rgb     Emit `*-rgb` vars (default: true)
+ * @param  {string} $rgb-suffix   Suffix for rgb vars (default: -rgb)
+ *
+ * @return {void}
+ */
+@mixin colour-scale-vars(
+  $scale,
+  $var-prefix: '--sol-',
+  $group: 'colour',
+  $with-rgb: true,
+  $rgb-suffix: '-rgb'
+) {
+  // Strict scale access with actionable errors.
+  $m: fn.colour-scale($scale);
+
+  @each $key, $val in $m {
+    // Keys are strings in your maps by design.
+    $name: _css-var-name($key, $var-prefix, $group);
+
+    @include _emit-var($name, $val);
+
+    @if $with-rgb == true {
+      @if meta.type-of($val) != 'color' {
+        @error "Expected scale '#{$scale}' key '#{$key}' to be a Sass color, got '#{meta.type-of($val)}'";
+      }
+
+      @include _emit-var('#{$name}#{$rgb-suffix}', _rgb-triplet($val));
+    }
+  }
+}
+
+/**
+ * Emits CSS variables for *all* registered colour scales.
+ *
+ * @param  {list|null} $scales     Optional subset (e.g. ("grey","blue"))
+ * @param  {string}    $var-prefix Leading custom prop prefix (default: --sol-)
+ * @param  {string}    $group      Namespace segment (default: colour)
+ * @param  {bool}      $with-rgb   Emit `*-rgb` vars (default: true)
+ * @param  {string}    $rgb-suffix Suffix for rgb vars (default: -rgb)
+ *
+ * @return {void}
+ */
+@mixin colour-scales-vars(
+  $scales: null,
+  $var-prefix: '--sol-',
+  $group: 'colour',
+  $with-rgb: true,
+  $rgb-suffix: '-rgb'
+) {
+  $use-scales: $scales;
+
+  @if $use-scales == null {
+    $use-scales: fn.colour-scales();
+  } @else if meta.type-of($use-scales) == 'string' {
+    // Developer ergonomics: allow a single scale passed as a string.
+    $use-scales: ($use-scales);
+  }
+
+  @if meta.type-of($use-scales) != 'list' {
+    @error "Expected $scales to be a list (or null), got '#{meta.type-of($use-scales)}'";
+  }
+
+  @each $scale in $use-scales {
+    @include colour-scale-vars(
+      $scale,
+      $var-prefix: $var-prefix,
+      $group: $group,
+      $with-rgb: $with-rgb,
+      $rgb-suffix: $rgb-suffix
+    );
+  }
+}
+
+/**
+ * Emits a *curated* set of "base" colour variables that developers typically
+ * expect to exist at root scope.
+ *
+ * Why this exists:
+ * - Scales are great for systems and utilities.
+ * - Apps still want a handful of stable "primitives" they can reach for.
+ *
+ * Important:
+ * - Your current colour registry is scale-based and does not define semantic
+ *   roles like `primary` (those live in theme).
+ * - So this mixin is intentionally parameterised: you pass a map of
+ *   `{ "name": <color> }` values you consider "base".
+ *
+ * Example:
+ *   @include base-colour-vars((
+ *     "black": #000,
+ *     "white": #fff
+ *   ));
+ *
+ * @param  {map}    $base-map
+ * @param  {string} $var-prefix
+ * @param  {string} $group
+ * @param  {bool}   $with-rgb
+ * @param  {string} $rgb-suffix
+ *
+ * @return {void}
+ */
+@mixin base-colour-vars(
+  $base-map,
+  $var-prefix: '--sol-',
+  $group: 'colour',
+  $with-rgb: true,
+  $rgb-suffix: '-rgb'
+) {
+  @if meta.type-of($base-map) != 'map' {
+    @error "Expected $base-map to be a map, got '#{meta.type-of($base-map)}'";
+  }
+
+  @each $key, $val in $base-map {
+    @if meta.type-of($key) != 'string' {
+      @error "Expected base colour key to be a string, got '#{meta.type-of($key)}'";
+    }
+
+    @if meta.type-of($val) != 'color' {
+      @error "Expected base colour '#{$key}' to be a Sass color, got '#{meta.type-of($val)}'";
+    }
+
+    $name: _css-var-name($key, $var-prefix, $group);
+
+    @include _emit-var($name, $val);
+
+    @if $with-rgb == true {
+      @include _emit-var('#{$name}#{$rgb-suffix}', _rgb-triplet($val));
+    }
+  }
+}
+
+/**
+ * Top-level convenience mixin to emit everything colour-related for `:root`
+ * (or any selector you wrap it in).
+ *
+ * This intentionally does NOT create selectors.
+ * You decide the scope, e.g.:
+ *
+ *   :root {
+ *     @include colour-root-vars();
+ *   }
+ *
+ *   [data-theme="dark"] {
+ *     @include colour-root-vars($with-rgb: false);
+ *   }
+ *
+ * @param  {list|null} $scales
+ * @param  {map|null}  $base-map
+ * @param  {string}    $var-prefix
+ * @param  {string}    $group
+ * @param  {bool}      $with-rgb
+ * @param  {string}    $rgb-suffix
+ *
+ * @return {void}
+ */
+@mixin colour-root-vars(
+  $scales: null,
+  $base-map: null,
+  $var-prefix: '--sol-',
+  $group: 'colour',
+  $with-rgb: true,
+  $rgb-suffix: '-rgb'
+) {
+  @if $base-map {
+    @include base-colour-vars(
+      $base-map,
+      $var-prefix: $var-prefix,
+      $group: $group,
+      $with-rgb: $with-rgb,
+      $rgb-suffix: $rgb-suffix
+    );
+  }
+
+  @include colour-scales-vars(
+    $scales: $scales,
+    $var-prefix: $var-prefix,
+    $group: $group,
+    $with-rgb: $with-rgb,
+    $rgb-suffix: $rgb-suffix
+  );
+}