@mastors/core 1.1.0

package/scss/semantic/_colors.scss

@@ -0,0 +1,29 @@
+// semantic/_colors.scss
+// Semantic color aliases mapped from primitive color tokens.
+// ─────────────────────────────────────────────────────────────
+
+// Semantic color aliases — role-based names that map to CSS custom properties.
+// Use these in component CSS instead of raw token references for themability.
+
+// These are SCSS variable aliases pointing to the custom properties
+// 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-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-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/_index.scss

@@ -0,0 +1,6 @@
+// semantic/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "colors";
+@forward "spacing";
+@forward "typography";

package/scss/semantic/_spacing.scss

@@ -0,0 +1,13 @@
+// semantic/_spacing.scss
+// Semantic spacing aliases (layout-level naming).
+// ─────────────────────────────────────────────────────────────
+
+@use "../tokens/spacing" as sp;
+
+// 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

package/scss/semantic/_typography.scss

@@ -0,0 +1,13 @@
+// semantic/_typography.scss
+// Semantic typography aliases (role-based naming).
+// ─────────────────────────────────────────────────────────────
+
+@use "../tokens/typography" as ty;
+
+// 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

package/scss/themes/_base-theme.scss

@@ -0,0 +1,28 @@
+// themes/_base-theme.scss
+// Shared theme structure — reference doc only, not emitted.
+// ─────────────────────────────────────────────────────────────
+
+// 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
+//   --mastors-accent-subtle   ← light accent tint
+//   --mastors-accent-text     ← text on accent backgrounds
+

package/scss/themes/_dark.scss

@@ -0,0 +1,59 @@
+// themes/_dark.scss
+// Dark theme CSS custom property overrides.
+// ─────────────────────────────────────────────────────────────
+
+@use "../tokens/color" as ct;
+
+// 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
+
+$dark-mode-strategy: "class" !default;
+
+@if $dark-mode-strategy == "class" {
+  [data-theme="dark"],
+  .dark {
+    --mastors-bg:              #{ct.color("neutral", 950)};
+    --mastors-bg-subtle:       #{ct.color("neutral", 900)};
+    --mastors-surface:         #{ct.color("neutral", 900)};
+    --mastors-surface-raised:  #{ct.color("neutral", 800)};
+    --mastors-surface-overlay: #{ct.color("neutral", 700)};
+
+    --mastors-text:            #{ct.color("neutral", 50)};
+    --mastors-text-muted:      #{ct.color("neutral", 400)};
+    --mastors-text-subtle:     #{ct.color("neutral", 500)};
+    --mastors-text-inverse:    #{ct.color("neutral", 900)};
+
+    --mastors-border:          #{ct.color("neutral", 700)};
+    --mastors-border-strong:   #{ct.color("neutral", 500)};
+
+    --mastors-accent:          #{ct.color("primary", 400)};
+    --mastors-accent-hover:    #{ct.color("primary", 300)};
+    --mastors-accent-subtle:   #{ct.color("primary", 950)};
+    --mastors-accent-text:     #{ct.color("neutral", 950)};
+  }
+} @else {
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --mastors-bg:              #{ct.color("neutral", 950)};
+      --mastors-bg-subtle:       #{ct.color("neutral", 900)};
+      --mastors-surface:         #{ct.color("neutral", 900)};
+      --mastors-surface-raised:  #{ct.color("neutral", 800)};
+      --mastors-surface-overlay: #{ct.color("neutral", 700)};
+
+      --mastors-text:            #{ct.color("neutral", 50)};
+      --mastors-text-muted:      #{ct.color("neutral", 400)};
+      --mastors-text-subtle:     #{ct.color("neutral", 500)};
+      --mastors-text-inverse:    #{ct.color("neutral", 900)};
+
+      --mastors-border:          #{ct.color("neutral", 700)};
+      --mastors-border-strong:   #{ct.color("neutral", 500)};
+
+      --mastors-accent:          #{ct.color("primary", 400)};
+      --mastors-accent-hover:    #{ct.color("primary", 300)};
+      --mastors-accent-subtle:   #{ct.color("primary", 950)};
+      --mastors-accent-text:     #{ct.color("neutral", 950)};
+    }
+  }
+}

package/scss/themes/_index.scss

@@ -0,0 +1,6 @@
+// themes/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "light";
+@forward "dark";
+@forward "base-theme";

package/scss/themes/_light.scss

@@ -0,0 +1,31 @@
+// themes/_light.scss
+// Light theme CSS custom property overrides.
+// ─────────────────────────────────────────────────────────────
+
+@use "../tokens/color" as ct;
+
+// Light theme — explicit override (identical to base, but declared
+// so a .light class or data-theme can be toggled back from dark).
+
+:root,
+[data-theme="light"],
+.light {
+  --mastors-bg:              #{ct.color("white")};
+  --mastors-bg-subtle:       #{ct.color("neutral", 50)};
+  --mastors-surface:         #{ct.color("white")};
+  --mastors-surface-raised:  #{ct.color("neutral", 50)};
+  --mastors-surface-overlay: #{ct.color("neutral", 100)};
+
+  --mastors-text:            #{ct.color("neutral", 900)};
+  --mastors-text-muted:      #{ct.color("neutral", 500)};
+  --mastors-text-subtle:     #{ct.color("neutral", 400)};
+  --mastors-text-inverse:    #{ct.color("white")};
+
+  --mastors-border:          #{ct.color("neutral", 200)};
+  --mastors-border-strong:   #{ct.color("neutral", 400)};
+
+  --mastors-accent:          #{ct.color("primary", 600)};
+  --mastors-accent-hover:    #{ct.color("primary", 700)};
+  --mastors-accent-subtle:   #{ct.color("primary", 50)};
+  --mastors-accent-text:     #{ct.color("white")};
+}

package/scss/tokens/_color.scss

@@ -0,0 +1,100 @@
+// tokens/_color.scss
+// Design token map: color palette (primitives).
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$color-tokens: (
+  "primary": (
+    "50":  #eff6ff,
+    "100": #dbeafe,
+    "200": #bfdbfe,
+    "300": #93c5fd,
+    "400": #60a5fa,
+    "500": #3b82f6,
+    "600": #2563eb,
+    "700": #1d4ed8,
+    "800": #1e40af,
+    "900": #1e3a8a,
+    "950": #172554,
+  ),
+  "neutral": (
+    "50":  #f9fafb,
+    "100": #f3f4f6,
+    "200": #e5e7eb,
+    "300": #d1d5db,
+    "400": #9ca3af,
+    "500": #6b7280,
+    "600": #4b5563,
+    "700": #374151,
+    "800": #1f2937,
+    "900": #111827,
+    "950": #030712,
+  ),
+  "success": (
+    "50":  #f0fdf4,
+    "100": #dcfce7,
+    "200": #bbf7d0,
+    "300": #86efac,
+    "400": #4ade80,
+    "500": #22c55e,
+    "600": #16a34a,
+    "700": #15803d,
+    "800": #166534,
+    "900": #14532d,
+    "950": #052e16,
+  ),
+  "warning": (
+    "50":  #fffbeb,
+    "100": #fef3c7,
+    "200": #fde68a,
+    "300": #fcd34d,
+    "400": #fbbf24,
+    "500": #f59e0b,
+    "600": #d97706,
+    "700": #b45309,
+    "800": #92400e,
+    "900": #78350f,
+    "950": #451a03,
+  ),
+  "error": (
+    "50":  #fef2f2,
+    "100": #fee2e2,
+    "200": #fecaca,
+    "300": #fca5a5,
+    "400": #f87171,
+    "500": #ef4444,
+    "600": #dc2626,
+    "700": #b91c1c,
+    "800": #991b1b,
+    "900": #7f1d1d,
+    "950": #450a0a,
+  ),
+  "info": (
+    "50":  #ecfeff,
+    "100": #cffafe,
+    "200": #a5f3fc,
+    "300": #67e8f9,
+    "400": #22d3ee,
+    "500": #06b6d4,
+    "600": #0891b2,
+    "700": #0e7490,
+    "800": #155e75,
+    "900": #164e63,
+    "950": #083344,
+  ),
+  "white": #fff,
+  "black": #000,
+  "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;
+}

package/scss/tokens/_index.scss

@@ -0,0 +1,12 @@
+// tokens/_index.scss
+// ─────────────────────────────────────────────────────────────
+
+@forward "color";
+@forward "spacing";
+@forward "typography";
+@forward "shadows";
+@forward "radii";
+@forward "transitions";
+@forward "z-index";
+@forward "opacity";
+@forward "sizing";

package/scss/tokens/_opacity.scss

@@ -0,0 +1,28 @@
+// tokens/_opacity.scss
+// Design token map: opacity scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$opacity-tokens: (
+  "0":   0,
+  "5":   0.05,
+  "10":  0.1,
+  "15":  0.15,
+  "20":  0.2,
+  "25":  0.25,
+  "30":  0.3,
+  "40":  0.4,
+  "50":  0.5,
+  "60":  0.6,
+  "70":  0.7,
+  "75":  0.75,
+  "80":  0.8,
+  "90":  0.9,
+  "95":  0.95,
+  "100": 1,
+) !default;
+
+@function opacity($key) {
+  @return map.get($opacity-tokens, "#{$key}");
+}

package/scss/tokens/_radii.scss

@@ -0,0 +1,21 @@
+// tokens/_radii.scss
+// Design token map: border-radius scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$radius-tokens: (
+  "none":  0px,
+  "sm":    0.125rem,
+  "base":  0.25rem,
+  "md":    0.375rem,
+  "lg":    0.5rem,
+  "xl":    0.75rem,
+  "2xl":   1rem,
+  "3xl":   1.5rem,
+  "full":  9999px,
+) !default;
+
+@function radius($key) {
+  @return map.get($radius-tokens, $key);
+}

package/scss/tokens/_shadows.scss

@@ -0,0 +1,20 @@
+// tokens/_shadows.scss
+// Design token map: box-shadow elevation scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$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%)),
+  "none":  none,
+) !default;
+
+@function shadow($key) {
+  @return map.get($shadow-tokens, $key);
+}

package/scss/tokens/_sizing.scss

@@ -0,0 +1,47 @@
+// tokens/_sizing.scss
+// Design token map: width / height / size scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$sizing-tokens: (
+  "0":    0,
+  "px":   1px,
+  "1":    0.25rem,
+  "2":    0.5rem,
+  "4":    1rem,
+  "8":    2rem,
+  "12":   3rem,
+  "16":   4rem,
+  "20":   5rem,
+  "24":   6rem,
+  "32":   8rem,
+  "40":   10rem,
+  "48":   12rem,
+  "56":   14rem,
+  "64":   16rem,
+  "72":   18rem,
+  "80":   20rem,
+  "96":   24rem,
+  "1\\/2":  50%,
+  "1\\/3":  33.3333%,
+  "2\\/3":  66.6667%,
+  "1\\/4":  25%,
+  "3\\/4":  75%,
+  "1\\/5":  20%,
+  "2\\/5":  40%,
+  "3\\/5":  60%,
+  "4\\/5":  80%,
+  "auto":    auto,
+  "full":    100%,
+  "screen":  100vw,
+  "svw":     100svw,
+  "dvw":     100dvw,
+  "min":     min-content,
+  "max":     max-content,
+  "fit":     fit-content,
+) !default;
+
+@function sizing($key) {
+  @return map.get($sizing-tokens, "#{$key}");
+}

package/scss/tokens/_spacing.scss

@@ -0,0 +1,48 @@
+// tokens/_spacing.scss
+// Design token map: spacing scale.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$spacing-tokens: (
+  "0":    0px,
+  "px":   1px,
+  "0\\.5":  0.125rem,
+  "1":    0.25rem,
+  "1\\.5":  0.375rem,
+  "2":    0.5rem,
+  "2\\.5":  0.625rem,
+  "3":    0.75rem,
+  "3\\.5":  0.875rem,
+  "4":    1rem,
+  "5":    1.25rem,
+  "6":    1.5rem,
+  "7":    1.75rem,
+  "8":    2rem,
+  "9":    2.25rem,
+  "10":   2.5rem,
+  "11":   2.75rem,
+  "12":   3rem,
+  "14":   3.5rem,
+  "16":   4rem,
+  "20":   5rem,
+  "24":   6rem,
+  "28":   7rem,
+  "32":   8rem,
+  "36":   9rem,
+  "40":   10rem,
+  "44":   11rem,
+  "48":   12rem,
+  "52":   13rem,
+  "56":   14rem,
+  "60":   15rem,
+  "64":   16rem,
+  "72":   18rem,
+  "80":   20rem,
+  "96":   24rem,
+) !default;
+
+// Accessor: spacing(4) → 1rem
+@function spacing($key) {
+  @return map.get($spacing-tokens, "#{$key}");
+}

package/scss/tokens/_transitions.scss

@@ -0,0 +1,27 @@
+// tokens/_transitions.scss
+// Design token map: duration and easing curves.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$duration-tokens: (
+  "75":   75ms,
+  "100":  100ms,
+  "150":  150ms,
+  "200":  200ms,
+  "300":  300ms,
+  "500":  500ms,
+  "700":  700ms,
+  "1000": 1000ms,
+) !default;
+
+$easing-tokens: (
+  "linear":      linear,
+  "in":          cubic-bezier(0.4, 0, 1, 1),
+  "out":         cubic-bezier(0, 0, 0.2, 1),
+  "in-out":      cubic-bezier(0.4, 0, 0.2, 1),
+  "bounce":      cubic-bezier(0.34, 1.56, 0.64, 1),
+) !default;
+
+@function duration($key) { @return map.get($duration-tokens, "#{$key}"); }
+@function easing($key)   { @return map.get($easing-tokens, $key); }

package/scss/tokens/_typography.scss

@@ -0,0 +1,63 @@
+// tokens/_typography.scss
+// Design token map: type scale, font families, weights, tracking.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$font-size-tokens: (
+  "xs":   0.75rem,
+  "sm":   0.875rem,
+  "base": 1rem,
+  "lg":   1.125rem,
+  "xl":   1.25rem,
+  "2xl":  1.5rem,
+  "3xl":  1.875rem,
+  "4xl":  2.25rem,
+  "5xl":  3rem,
+  "6xl":  3.75rem,
+  "7xl":  4.5rem,
+  "8xl":  6rem,
+  "9xl":  8rem,
+) !default;
+
+$font-family-tokens: (
+  "sans":  (system-ui, -apple-system, "BlinkMacSystemFont", "Segoe UI", "Roboto", sans-serif),
+  "serif": ("Georgia", "Cambria", "Times New Roman", "Times", serif),
+  "mono":  (ui-monospace, "SFMono-Regular", "Menlo", "Monaco", "Consolas", monospace),
+) !default;
+
+$font-weight-tokens: (
+  "thin":       100,
+  "extralight": 200,
+  "light":      300,
+  "normal":     400,
+  "medium":     500,
+  "semibold":   600,
+  "bold":       700,
+  "extrabold":  800,
+  "black":      900,
+) !default;
+
+$line-height-tokens: (
+  "none":    1,
+  "tight":   1.25,
+  "snug":    1.375,
+  "normal":  1.5,
+  "relaxed": 1.625,
+  "loose":   2,
+) !default;
+
+$letter-spacing-tokens: (
+  "tighter": -0.05em,
+  "tight":   -0.025em,
+  "normal":   0,
+  "wide":     0.025em,
+  "wider":    0.05em,
+  "widest":   0.1em,
+) !default;
+
+@function font-size($key) { @return map.get($font-size-tokens, $key); }
+@function font-family($key) { @return map.get($font-family-tokens, $key); }
+@function font-weight($key) { @return map.get($font-weight-tokens, $key); }
+@function line-height($key) { @return map.get($line-height-tokens, $key); }
+@function letter-spacing($key) { @return map.get($letter-spacing-tokens, $key); }

package/scss/tokens/_z-index.scss

@@ -0,0 +1,21 @@
+// tokens/_z-index.scss
+// Design token map: z-index stacking layers.
+// ─────────────────────────────────────────────────────────────
+
+@use "sass:map";
+
+$z-index-tokens: (
+  "base":     0,
+  "raised":   10,
+  "dropdown": 100,
+  "sticky":   200,
+  "overlay":  300,
+  "modal":    400,
+  "toast":    500,
+  "tooltip":  600,
+  "max":      9999,
+) !default;
+
+@function z($key) {
+  @return map.get($z-index-tokens, $key);
+}