@lnpg/pkgn-sol 1.0.0-beta.0

package/src/scss/tokens/_dark-theme.scss

@@ -0,0 +1,50 @@
+/**
+ * pkgn-sol Design Foundation: Dark Theme Tokens
+ *
+ * Canonical dark theme configuration for pkgn-sol's theme token contract.
+ *
+ * This module configures the default values defined in `tokens/theme`
+ * using `@forward ... with (...)`. The underlying variables remain
+ * configurable by consumers.
+ *
+ * Purpose:
+ * - Provide a ready-to-use dark preset
+ * - Preserve the single canonical theme contract
+ * - Allow framework entrypoints to opt into dark defaults
+ *
+ * This file is intentionally configuration-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  tokens.theme
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use './colours' as colours;
+
+/* --------------------------------------------------------------------------
+   Dark theme overrides
+--------------------------------------------------------------------------- */
+
+/**
+ * Configure the canonical theme token module with dark defaults.
+ */
+@forward './theme' with (
+  $theme-dark-mode: true,
+  $body-bg-color: colours.$grey-shade-80,
+  $base-font-color: colours.$grey-tint-80,
+  $code-font-color: colours.$grey-tint-80,
+  $heading-font-color: colours.$grey-tint-80,
+  $primary-colour: colours.$base-blue,
+  $secondary-colour: colours.$base-indigo,
+  $tertiary-colour: colours.$base-purple,
+  $success-colour: colours.$base-green,
+  $info-colour: colours.$base-cyan,
+  $warning-colour: colours.$base-orange,
+  $danger-colour: colours.$base-red
+);

package/src/scss/tokens/_fonts.scss

@@ -0,0 +1,81 @@
+/**
+ * pkgn-sol Design Foundation: Font Tokens
+ *
+ * Canonical font-face primitives for generating @font-face rules.
+ *
+ * This token layer defines:
+ * - Shared font-face metadata (display/style/weight range)
+ * - Canonical source paths per font group (base/headings/code)
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  tokens.fonts
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+/* --------------------------------------------------------------------------
+ - Font source extension
+ ------------------------------------------------------------------------- */
+
+/**
+ * Canonical bundled font extension.
+ *
+ * Sol emits one font source per @font-face rule. This toggle controls the
+ * asset extension used by the generated source paths.
+ *
+ * Supported values: 'ttf', 'woff2'.
+ *
+ * @type string
+ */
+$font-extension: 'ttf' !default;
+
+/**
+ * CSS format label matching the selected font extension.
+ *
+ * TTF files must be emitted using the CSS format label 'truetype'.
+ * WOFF2 files use the matching 'woff2' label.
+ *
+ * @type string
+ */
+$font-format: null;
+
+@if $font-extension == 'ttf' {
+  $font-format: 'truetype';
+} @else {
+  $font-format: $font-extension;
+}
+
+/* --------------------------------------------------------------------------
+ - Shared font-face primitives
+ ------------------------------------------------------------------------- */
+
+/**
+ * Font loading strategy.
+ *
+ * @type string
+ */
+$font-display: swap;
+
+/**
+ * Canonical font styles.
+ *
+ * @type string
+ */
+$font-style-normal: normal;
+$font-style-italic: italic;
+
+/**
+ * Variable font weight range used by Montserrat variable files.
+ *
+ * Represented as a Sass list to mirror CSS syntax: `font-weight: 100 900;`
+ *
+ * @type list
+ */
+$font-weight-range: 100 900;

package/src/scss/tokens/_index.scss

@@ -0,0 +1,100 @@
+/**
+ * pkgn-sol Design Foundation: Tokens Index
+ *
+ * Public API surface for all canonical design tokens.
+ *
+ * This file defines the *authoritative import boundary* for the token layer.
+ * All consumers (internal or external) must import tokens through this file
+ * rather than individual token modules.
+ *
+ * This file intentionally:
+ * - Re-exports token modules using `@forward`
+ * - Defines a stable, versionable public API
+ * - Avoids eager loading, logic, or side effects
+ *
+ * IMPORTANT:
+ * - This file MUST NOT use `@use`
+ * - This file MUST NOT define variables
+ * - This file MUST NOT perform calculations or validation
+ *
+ * Consumers should import tokens via:
+ *
+ *   @use "tokens" as tokens;
+ *
+ * Internal layers (maps, core, utilities) may also rely on this
+ * index to ensure consistent load order and override behaviour.
+ *
+ * @module
+ * @group  tokens
+ * @access public
+ * @since  0.1.0
+ */
+
+/* ----------------------------------------------------------------------------
+ - Core theme primitives
+ --------------------------------------------------------------------------- */
+
+/**
+ * Theme tokens.
+ *
+ * Consumer-overridable primitives defining branding, colours,
+ * fonts, feature flags, and asset paths.
+ *
+ * This is the root of the override surface.
+ */
+@forward 'theme';
+
+/* ----------------------------------------------------------------------------
+ - Configuration & options
+ --------------------------------------------------------------------------- */
+
+/**
+ * Option tokens.
+ *
+ * Canonical configuration values derived from the theme layer
+ * that influence system consumption (prefixing, dark mode, paths).
+ */
+@forward 'options';
+
+/* ----------------------------------------------------------------------------
+ - Design primitives
+ --------------------------------------------------------------------------- */
+
+/**
+ * Colour tokens.
+ *
+ * Canonical colour primitives and ramps.
+ */
+@forward 'colours';
+
+/**
+ * Spacing tokens.
+ *
+ * Base spacing primitive used to derive spacing scales.
+ */
+@forward 'spacing';
+
+/**
+ * Typography tokens.
+ *
+ * Font families, weights, sizes, line-heights, and spacing primitives.
+ */
+@forward 'typography';
+
+/**
+ * Font-face tokens.
+ *
+ * Canonical font metadata used to construct @font-face declarations.
+ */
+@forward 'fonts';
+
+/**
+ * Dark theme tokens.
+ *
+ * Preset configuration of the canonical theme token contract that
+ * applies pkgn-sol's dark defaults while preserving consumer overrides.
+ *
+ * Intended for framework integrations or applications that want
+ * a ready-to-use dark palette without redefining theme primitives.
+ */
+@forward 'dark-theme';

package/src/scss/tokens/_options.scss

@@ -0,0 +1,77 @@
+/**
+ * pkgn-sol Design Foundation: Option Tokens
+ *
+ * Canonical configuration primitives derived from the theme layer.
+ *
+ * These tokens expose high-level, cross-cutting options that influence
+ * how the design system is *consumed*, not how it is *styled*.
+ *
+ * Typical consumers include:
+ * - CSS variable generation
+ * - Utility class namespaces
+ * - Feature toggles (e.g. dark mode)
+ * - Asset path resolution (fonts, icons, etc.)
+ *
+ * This file intentionally:
+ * - Re-exports selected theme values under stable option semantics
+ * - Avoids redefining or transforming theme data
+ * - Acts as the single source of truth for system-wide configuration
+ *
+ * This file is intentionally data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  tokens.options
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use './theme' as theme;
+
+/* ---------------------------------------------------------------------------
+ - Namespace & prefixing
+ -------------------------------------------------------------------------- */
+
+/**
+ * Global CSS namespace prefix.
+ *
+ * Used to scope generated CSS variables, utility classes, and
+ * any other emitted identifiers that must remain collision-safe.
+ *
+ * @type string
+ */
+$sol-prefix: theme.$theme-prefix;
+
+/* ---------------------------------------------------------------------------
+ - Feature flags
+ -------------------------------------------------------------------------- */
+
+/**
+ * Dark mode enablement flag.
+ *
+ * This token represents *capability*, not implementation.
+ * Consumers are responsible for deciding how dark mode is applied
+ * (media queries, data attributes, class toggles, etc.).
+ *
+ * @type boolean
+ */
+$dark-mode: theme.$theme-dark-mode;
+
+/* ---------------------------------------------------------------------------
+ - Asset paths
+ -------------------------------------------------------------------------- */
+
+/**
+ * Base font asset path.
+ *
+ * Used as the root for resolving font-face source URLs.
+ * This is intentionally centralised to ensure all font assets
+ * remain relocatable without touching individual font definitions.
+ *
+ * @type string
+ */
+$font-path: theme.$base-font-path;

package/src/scss/tokens/_spacing.scss

@@ -0,0 +1,43 @@
+/**
+ * pkgn-sol Design Foundation: Spacing Tokens
+ *
+ * Canonical spacing primitives used across the design system.
+ *
+ * Spacing tokens define the base rhythm for layout, components,
+ * and vertical flow. All derived spacing values (margins, paddings,
+ * gaps, stack spacing, etc.) should be computed from these primitives
+ * rather than introducing arbitrary values downstream.
+ *
+ * This file is intentionally minimal and data-only:
+ * - No selectors
+ * - No functions
+ * - No mixins
+ * - No side effects
+ *
+ * @module
+ * @group  tokens.spacing
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+/* -------------------------------------------------------------------------- 
+ - Base spacing
+ ------------------------------------------------------------------------- */
+
+/**
+ * Base spacing unit.
+ *
+ * Represents the fundamental spacing increment for the system.
+ * Commonly used as the reference for:
+ * - Vertical rhythm
+ * - Component padding
+ * - Stack spacing
+ * - Grid gutters (directly or indirectly)
+ *
+ * All spacing scales should be derived as multiples or fractions
+ * of this value to preserve visual consistency.
+ *
+ * @type number (length)
+ */
+$base-spacing: 1rem;

package/src/scss/tokens/_theme.scss

@@ -0,0 +1,325 @@
+/**
+ * pkgn-sol Design Foundation: Theme Tokens
+ *
+ * Consumer-overridable theme primitives.
+ *
+ * This file defines the *customisation surface* of the design system.
+ * All values declared here are intended to be overridden by consumers
+ * at import time using Sass's `@use ... with (...)` mechanism.
+ *
+ * Responsibilities:
+ * - Branding (fonts, colours)
+ * - Global feature flags (e.g. dark mode)
+ * - Asset paths
+ * - Semantic colour roles
+ *
+ * Non-responsibilities:
+ * - No derived values
+ * - No calculations
+ * - No CSS output
+ * - No maps
+ *
+ * Downstream token layers (options, typography, fonts, etc.) must treat
+ * these values as authoritative inputs and MUST NOT re-declare defaults.
+ *
+ * @module
+ * @group  tokens.theme
+ * @access public
+ * @since  0.1.0
+ * @author LNPG Development Team
+ */
+
+@use './colours' as colours;
+@use './fonts' as fonts;
+
+/* ----------------------------------------------------------------------------
+ - Global feature flags
+ --------------------------------------------------------------------------- */
+
+/**
+ * Dark mode enablement flag.
+ *
+ * This flag represents *capability*, not behaviour.
+ * How dark mode is implemented (media queries, classes, attributes)
+ * is left entirely to consuming layers.
+ *
+ * @type boolean
+ */
+$theme-dark-mode: false !default;
+
+/* ----------------------------------------------------------------------------
+ - Namespace & prefixing
+ --------------------------------------------------------------------------- */
+
+/**
+ * Global namespace prefix.
+ *
+ * Used to scope generated CSS variables, utility classes, and any other
+ * emitted identifiers to avoid collisions with host applications.
+ *
+ * @type string
+ */
+$theme-prefix: 'lg-' !default;
+
+/* ----------------------------------------------------------------------------
+ - Font families (semantic roles)
+ --------------------------------------------------------------------------- */
+
+/**
+ * Base (body) font family.
+ *
+ * This should be a human-readable font name, not a font stack.
+ * Fallback stacks belong in the typography token layer.
+ *
+ * @type string
+ */
+$base-font: 'Montserrat' !default;
+
+/**
+ * Heading font family.
+ *
+ * Split from base font intentionally to allow independent branding
+ * without structural changes.
+ *
+ * @type string
+ */
+$heading-font: 'Montserrat' !default;
+
+/**
+ * Code / monospace font family.
+ *
+ * Defaults to a system monospace identifier rather than a bundled font.
+ *
+ * @type string
+ */
+$code-font: 'ui-monospace' !default;
+
+/* ----------------------------------------------------------------------------
+ - Base colours (structural)
+ --------------------------------------------------------------------------- */
+
+/**
+ * Application background colour.
+ *
+ * @type color
+ */
+$body-bg-color: colours.$grey-tint-80 !default;
+
+/**
+ * Default body text colour.
+ *
+ * @type color
+ */
+$base-font-color: colours.$grey-shade-80 !default;
+
+/**
+ * Inline code text colour.
+ *
+ * @type color
+ */
+$code-font-color: colours.$grey-shade-80 !default;
+
+/**
+ * Heading text colour.
+ *
+ * @type color
+ */
+$heading-font-color: colours.$grey-shade-80 !default;
+
+/* ----------------------------------------------------------------------------
+ - Semantic brand colours
+ --------------------------------------------------------------------------- */
+
+/**
+ * Primary brand colour.
+ *
+ * @type color
+ */
+$primary-colour: colours.$base-blue !default;
+
+/**
+ * Secondary brand colour.
+ *
+ * @type color
+ */
+$secondary-colour: colours.$base-indigo !default;
+
+/**
+ * Tertiary brand colour.
+ *
+ * @type color
+ */
+$tertiary-colour: colours.$base-purple !default;
+
+/* ----------------------------------------------------------------------------
+ - Semantic state colours
+ --------------------------------------------------------------------------- */
+
+/**
+ * Success state colour.
+ *
+ * @type color
+ */
+$success-colour: colours.$base-green !default;
+
+/**
+ * Informational state colour.
+ *
+ * @type color
+ */
+$info-colour: colours.$base-cyan !default;
+
+/**
+ * Warning state colour.
+ *
+ * @type color
+ */
+$warning-colour: colours.$base-orange !default;
+
+/**
+ * Danger / error state colour.
+ *
+ * @type color
+ */
+$danger-colour: colours.$base-red !default;
+
+/* ----------------------------------------------------------------------------
+ - Light / dark aliases
+ --------------------------------------------------------------------------- */
+
+/**
+ * Light surface colour.
+ *
+ * @type color
+ */
+$light-colour: colours.$grey-tint-80 !default;
+
+/**
+ * Dark surface colour.
+ *
+ * @type color
+ */
+$dark-colour: colours.$grey-shade-80 !default;
+
+/* ----------------------------------------------------------------------------
+ - Asset paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Base font asset path.
+ *
+ * This path is prepended by font-face generators when resolving font URLs.
+ * Keeping this value centralised allows fonts to be relocated without
+ * touching individual font definitions.
+ *
+ * @type string
+ */
+$base-font-path: '../assets/fonts' !default;
+
+/* ----------------------------------------------------------------------------
+ - Base font source paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Base font (normal) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$base-font-source-stem: 'montserrat/Montserrat-Variable-Font' !default;
+
+/**
+ * Base font (italic) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$base-font-italic-source-stem: 'montserrat/Montserrat-Variable-Italic-Font' !default;
+
+/**
+ * Base font (normal) source path.
+ *
+ * @type string
+ */
+$base-font-source-path: '#{$base-font-source-stem}.#{fonts.$font-extension}';
+
+/**
+ * Base font (italic) source path.
+ *
+ * @type string
+ */
+$base-font-italic-source-path: '#{$base-font-italic-source-stem}.#{fonts.$font-extension}';
+
+/* ----------------------------------------------------------------------------
+ - Heading font source paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Heading font (normal) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$heading-font-source-stem: 'montserrat/Montserrat-Variable-Font' !default;
+
+/**
+ * Heading font (italic) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$heading-font-italic-source-stem: 'montserrat/Montserrat-Variable-Italic-Font' !default;
+
+/**
+ * Heading font (normal) source path.
+ *
+ * @type string
+ */
+$heading-font-source-path: '#{$heading-font-source-stem}.#{fonts.$font-extension}';
+
+/**
+ * Heading font (italic) source path.
+ *
+ * @type string
+ */
+$heading-font-italic-source-path: '#{$heading-font-italic-source-stem}.#{fonts.$font-extension}';
+
+/* ----------------------------------------------------------------------------
+ - Code font source paths
+ --------------------------------------------------------------------------- */
+
+/**
+ * Code font (normal) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$code-font-source-stem: 'montserrat/Montserrat-Variable-Font' !default;
+
+/**
+ * Code font (italic) source stem.
+ *
+ * The selected extension is controlled by `tokens/fonts.$font-extension`.
+ *
+ * @type string
+ */
+$code-font-italic-source-stem: 'montserrat/Montserrat-Variable-Italic-Font' !default;
+
+/**
+ * Code font (normal) source path.
+ *
+ * @type string
+ */
+$code-font-source-path: '#{$code-font-source-stem}.#{fonts.$font-extension}';
+
+/**
+ * Code font (italic) source path.
+ *
+ * @type string
+ */
+$code-font-italic-source-path: '#{$code-font-italic-source-stem}.#{fonts.$font-extension}';