@mastors/core 1.2.0 → 1.2.1

package/README.md

@@ -1,940 +1,271 @@
 # @mastors/core
 
-> The foundational layer of the Mastors ecosystem — design tokens, SCSS functions, mixins, generators, reset, responsive engine, and theme system.
+> Foundational tokens, mixins, functions, reset, and responsive engine for the Mastors ecosystem.
 
-[![npm](https://img.shields.io/npm/v/@mastors/core.svg)](https://www.npmjs.com/package/@mastors/core)
+[![npm version](https://img.shields.io/npm/v/@mastors/core.svg)](https://www.npmjs.com/package/@mastors/core)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
-[![sass](https://img.shields.io/badge/requires-sass%20%3E%3D1.80-CC6699.svg)](https://sass-lang.com)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Full stylesheet import](#full-stylesheet-import)
-  - [Public API (zero output)](#public-api-zero-output)
-  - [TypeScript / JavaScript](#typescript--javascript)
-- [Configuration](#configuration)
-  - [Feature flags](#feature-flags)
-  - [Dark mode strategy](#dark-mode-strategy)
-  - [Class prefix](#class-prefix)
-  - [Config via public API](#config-via-public-api)
-- [Design Tokens](#design-tokens)
-  - [Color](#color)
-  - [Spacing](#spacing)
-  - [Typography](#typography)
-  - [Border Radius](#border-radius)
-  - [Shadows](#shadows)
-  - [Z-Index](#z-index)
-  - [Opacity](#opacity)
-  - [Transitions](#transitions)
-- [Functions](#functions)
-  - [vars()](#vars)
-- [Mixins](#mixins)
-  - [Breakpoints](#breakpoints)
-  - [Theme](#theme)
-  - [Elevation](#elevation)
-  - [Transition](#transition)
-  - [Container](#container)
-  - [Pseudo](#pseudo)
-- [Responsive Engine](#responsive-engine)
-- [Container Queries](#container-queries)
-- [Fluid Typography](#fluid-typography)
-- [Theme System](#theme-system)
-- [Base Layer](#base-layer)
-- [Utility Classes](#utility-classes)
-- [Helpers](#helpers)
-- [Accessibility](#accessibility)
-- [Generator Engine](#generator-engine)
-- [Semantic Layer](#semantic-layer)
-- [Known Stubs](#known-stubs)
-- [Package Exports](#package-exports)
-- [Peer Dependencies](#peer-dependencies)
-- [Changelog](#changelog)
 
 ---
 
 ## Overview
 
-`@mastors/core` is the only required package in the Mastors ecosystem. It provides:
+`@mastors/core` is the foundation of the Mastors SCSS ecosystem. It provides:
 
-- **Design tokens** — color, spacing, typography, radius, shadows, z-index, opacity, and transitions as SCSS maps
-- **Functions** — `rem()`, `em()`, `color()`, `spacing()`, `tint()`, `shade()`, `alpha()`, `contrast()`, `fluid()`, `map-deep-get()`, `map-collect()`, `str-replace()`, `vars()`
-- **Mixins** — `bp()`, `dark-mode()`, `light-mode()`, `theme()`, `elevation()`, `transition()`, `container()`, `pseudo()`
-- **Generator engine** — `generate-utilities()`, `emit-custom-properties()`, and responsive-generator mixins used by all utility packages
-- **Reset** — modern CSS reset and document defaults
-- **Theme system** — CSS custom property-based light/dark theming with a full semantic contract
-- **Responsive engine** — breakpoint-aware utility variant generation (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
-- **Container queries** — `.cq-inline`, `.cq-size`, `cq()` mixin for `@container` rules
-- **Fluid typography** — `fluid-type()` mixin and function using `clamp()`
-- **Utility classes** — display, position, overflow, spacing, sizing, colors, borders (full directional radius scale), shadows, opacity, cursor, z-index, transforms, typography, animation, interaction, layout (aspect-ratio, object-fit/position, blend modes)
-- **Accessibility** — focus ring, reduced-motion, screen-reader utilities, print layer
-- **TypeScript types and runtime token mirror**
+- **Token system** — color, spacing, typography, radii, shadows, z-index, opacity, transitions, sizing
+- **Functions** — `rem()`, `em()`, `color()`, `spacing()`, `vars()`, `tint()`, `shade()`, `fluid()`, and more
+- **Mixins** — `bp()`, `dark-mode()`, `theme()`, `elevation()`, `transition()`, `container()`, `pseudo()`
+- **Generator engine** — `generate-utilities()`, `emit-custom-properties()`, `generate-responsive()`
+- **Utility classes** — display, spacing, sizing, colors, borders, shadows, typography, animation, interaction, layout, accessibility
+- **Theme system** — CSS custom property contract, light/dark themes, `data-theme` support
+- **Responsive engine** — breakpoint-prefixed variant generation, container queries, fluid typography
+- **TypeScript mirror** — runtime token access and full type definitions
 
-All other `@mastors/*` packages consume `@mastors/core/api` for shared tokens, functions, and mixins.
+All other `@mastors/*` packages consume `@mastors/core/api` as a peer dependency.
 
 ---
 
 ## Installation
 
 ```bash
-npm install @mastors/core sass
+npm install @mastors/core
 # or
-pnpm add @mastors/core sass
+pnpm add @mastors/core
+# or
+yarn add @mastors/core
 ```
 
-`sass >= 1.80.0` is required as a peer dependency.
+Requires `sass >= 1.80.0` as a peer dependency:
+
+```bash
+npm install --save-dev sass
+```
 
 ---
 
 ## Usage
 
-### Full stylesheet import
-
-Import the complete compiled stylesheet — reset, tokens, themes, utilities, helpers, and accessibility:
+### Import the full stylesheet
 
 ```scss
 @use "@mastors/core/scss";
 ```
 
-### Public API (zero output)
+This imports the complete output: reset, custom properties, themes, utilities, helpers, and accessibility classes.
 
-Import only the public API surface. No CSS is emitted — you get access to all tokens, functions, mixins, and config:
+### Use the public API (zero CSS output)
 
 ```scss
 @use "@mastors/core/api" as m;
 
 .card {
-  padding:          m.spacing(6);
-  background-color: m.color("neutral", 50);
-  border-radius:    m.radius("xl");
-  box-shadow:       m.vars(shadow-md);
-  transition:       box-shadow m.vars(duration-200) m.vars(ease-out);
+  padding:       m.spacing(6);
+  color:         m.color("primary", 700);
+  border-radius: m.radius("lg");
+  box-shadow:    m.vars(shadow-md);
+  transition:    transform m.vars(duration-200) m.vars(ease-out);
 
-  @include m.bp("lg") {
+  @include m.bp("md") {
     padding: m.spacing(10);
   }
 
   @include m.dark-mode {
-    background-color: m.color("neutral", 800);
-    color:            m.color("neutral", 100);
+    color: m.color("primary", 300);
   }
 }
 ```
 
-### TypeScript / JavaScript
-
-Access design token values at runtime for CSS-in-JS, design tools, or testing:
-
-```ts
-import { tokens } from '@mastors/core'
-
-const primary600   = tokens.color.primary['600']  // '#2563eb'
-const spacing4     = tokens.spacing['4']           // '1rem'
-const shadowMd     = tokens.shadow.md              // '0 4px 6px ...'
-const radiusXl     = tokens.radius.xl              // '0.75rem'
-const duration200  = tokens.duration['200']        // '200ms'
-```
-
-Import TypeScript types:
-
-```ts
-import type {
-  MastorsConfig,
-  Breakpoint,
-  ThemeMode,
-  Tokens,
-  ColorPalette,
-  SpacingKey,
-  RadiusKey,
-} from '@mastors/core'
-```
-
----
-
-## Configuration
-
-Override the global config map before importing core to customise behaviour. The config must be set before any `@use "@mastors/core"` statement in your project.
+### Import a single partial
 
 ```scss
-// styles/_config.scss — set BEFORE @use "@mastors/core"
-@use "@mastors/core/scss/config/settings" with (
-  $mastors-config: (
-    "prefix":    "",        // optional class prefix, e.g. "m-" -> .m-flex
-    "important": false,     // append !important to all utility declarations
-    "dark-mode": "class",   // "class" | "media"
-    "rtl":       false,     // enable RTL logical property variants
-  )
-);
+@use "@mastors/core/scss/tokens/color" as colors;
+@use "@mastors/core/scss/mixins/breakpoint" as bp;
 ```
 
-### Feature flags
+### JavaScript / TypeScript
 
-Disable any layer you don't need to reduce output size:
+```ts
+import { tokens } from '@mastors/core'
+import type { Breakpoint, SpacingKey, ColorPalette } from '@mastors/core'
 
-```scss
-@use "@mastors/core/scss/config/flags" with (
-  $enable-utilities:  true,
-  $enable-responsive: true,
-  $enable-helpers:    true,
-  $enable-a11y:       true,
-  $enable-themes:     true,
-);
+const primary = tokens.color.primary['600']  // '#2563eb'
+const space4  = tokens.spacing['4']          // '1rem'
 ```
 
-### Dark mode strategy
+---
 
-**Class-based** (default) — add `.dark` or `data-theme="dark"` to `<html>`:
+## Package Exports
 
-```html
-<html class="dark">...</html>
+```json
+{
+  ".":                       { "import": "./dist/index.mjs", "require": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./scss":                  "./scss/index.scss",
+  "./scss/*":                "./scss/*",
+  "./api":                   "./scss/api/_index.scss",
+  "./dist/mastors-core.css": "./dist/mastors-core.css"
+}
 ```
 
-**Media-query** — responds automatically to the OS preference:
+---
 
-```scss
-@use "@mastors/core/scss/config/settings" with (
-  $mastors-config: ("dark-mode": "media")
-);
-```
+## Public API (`@mastors/core/api`)
 
-### Class prefix
+Importing `@mastors/core/api` gives access to:
 
-Add a prefix to every generated utility class to prevent collisions:
+### Functions
 
-```scss
-$mastors-config: ("prefix": "m-") !default;
-// .m-flex, .m-block, .m-grid-cols-3, ...
-```
-
-### Config via public API
-
-As of v1.2, both the `$mastors-config` map / `config()` accessor and all `$enable-*` flags are forwarded through the public API surface. Downstream consumers no longer need a direct partial import to read them:
+| Function | Description |
+|---|---|
+| `color($name, $shade)` | Look up a palette color by name and shade |
+| `spacing($key)` | Look up a spacing token |
+| `radius($key)` | Look up a border-radius token |
+| `shadow($key)` | Look up a box-shadow token |
+| `z($key)` | Look up a z-index token |
+| `opacity($key)` | Look up an opacity token |
+| `duration($key)` | Look up a transition duration |
+| `easing($key)` | Look up an easing curve |
+| `vars($token, $fallback?)` | Emit `var(--mastors-{token})` with optional fallback |
+| `rem($px)` | Convert px to rem |
+| `em($px, $base?)` | Convert px to em |
+| `tint($color, $amount)` | Mix color toward white |
+| `shade($color, $amount)` | Mix color toward black |
+| `alpha($color, $opacity)` | Set color opacity |
+| `fluid($min, $max, $min-bp?, $max-bp?)` | Generate a fluid `clamp()` value |
+
+### Mixins
+
+| Mixin | Description |
+|---|---|
+| `bp($key)` | Mobile-first breakpoint media query |
+| `breakpoint-up($key)` | Alias for `bp()` |
+| `breakpoint-down($key)` | Max-width media query |
+| `respond-to($key)` | Alias for `bp()` |
+| `dark-mode` | Dark mode block (class or media, per config) |
+| `light-mode` | Light mode block |
+| `theme($name)` | `[data-theme="name"]` scoped block |
+| `elevation($level)` | Token-driven box-shadow by level |
+| `transition($props...)` | Token-driven transition shorthand |
+| `container($size?)` | Responsive container width |
+| `pseudo($display, $pos, $content)` | `::before` / `::after` boilerplate |
+| `cq($size, $name?)` | Container query block |
+| `fluid-type($min, $max, $min-bp?, $max-bp?)` | Fluid font-size via `clamp()` |
+
+### Config
 
 ```scss
 @use "@mastors/core/api" as m;
 
-// Read a config value
-$prefix: m.config("prefix");
+// Read config values
+$mode: m.config("dark-mode");   // "class" | "media"
 
-// Read feature flags
-@if m.$enable-responsive {
-  // emit responsive variants
-}
+// Check feature flags
+$enabled: m.$enable-flexer;
 ```
 
 ---
 
-## Design Tokens
-
-All tokens are available via the public API after `@use "@mastors/core/api" as m`.
+## Token Reference
 
 ### Color
 
-Six semantic palettes, each with 11 shades (50-950), plus `white`, `black`, and `transparent`.
+Palette keys: `primary`, `secondary`, `neutral`, `success`, `warning`, `danger`, `info`
+Shades: `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`
 
 ```scss
-m.color("primary", 600)    // #2563eb
-m.color("neutral", 100)    // #f3f4f6
-m.color("success", 500)    // #22c55e
-m.color("warning", 400)    // #fbbf24
-m.color("error", 600)      // #dc2626
-m.color("info", 500)       // #06b6d4
-m.color("white")           // #ffffff
-m.color("black")           // #000000
+m.color("primary", 600)   // #2563eb
+m.color("neutral", 100)   // #f5f5f5
 ```
 
-Palettes: `primary` - `neutral` - `success` - `warning` - `error` - `info`
-
 ### Spacing
 
-35-step scale from `0` to `96` (matching Tailwind's spacing scale):
-
-```scss
-m.spacing(0)    // 0px
-m.spacing(1)    // 0.25rem
-m.spacing(4)    // 1rem
-m.spacing(8)    // 2rem
-m.spacing(16)   // 4rem
-m.spacing(96)   // 24rem
-```
-
-Half-step keys (`0.5`, `1.5`, `2.5`, `3.5`) are also available:
-
-```scss
-m.spacing("0.5")  // 0.125rem
-m.spacing("1.5")  // 0.375rem
-```
-
-### Typography
-
-```scss
-// Font sizes (xs -> 9xl)
-m.font-size("sm")      // 0.875rem
-m.font-size("base")    // 1rem
-m.font-size("2xl")     // 1.5rem
-m.font-size("5xl")     // 3rem
-
-// Font families
-m.font-family("sans")  // system-ui, -apple-system, ...
-m.font-family("mono")  // ui-monospace, SFMono-Regular, ...
-
-// Font weights
-m.font-weight("semibold")  // 600
-m.font-weight("bold")      // 700
-
-// Line heights
-m.line-height("tight")     // 1.25
-m.line-height("normal")    // 1.5
-
-// Letter spacing
-m.letter-spacing("wide")   // 0.025em
-```
-
-### Border Radius
+35-step scale — `0` through `96`:
 
 ```scss
-m.radius("none")   // 0px
-m.radius("sm")     // 0.125rem
-m.radius("md")     // 0.375rem
-m.radius("lg")     // 0.5rem
-m.radius("xl")     // 0.75rem
-m.radius("2xl")    // 1rem
-m.radius("3xl")    // 1.5rem
-m.radius("full")   // 9999px
+m.spacing(0)   // 0
+m.spacing(1)   // 0.25rem
+m.spacing(4)   // 1rem
+m.spacing(16)  // 4rem
 ```
 
-### Shadows
-
-```scss
-m.shadow("xs")     // subtle shadow
-m.shadow("sm")     // small shadow
-m.shadow("md")     // medium shadow (default)
-m.shadow("lg")     // large shadow
-m.shadow("xl")     // extra large shadow
-m.shadow("2xl")    // page-level shadow
-m.shadow("inner")  // inset shadow
-m.shadow("none")   // none
-```
-
-### Z-Index
-
-```scss
-m.z("base")      // 0
-m.z("raised")    // 10
-m.z("dropdown")  // 100
-m.z("sticky")    // 200
-m.z("overlay")   // 300
-m.z("modal")     // 400
-m.z("toast")     // 500
-m.z("tooltip")   // 600
-m.z("max")       // 9999
-```
-
-### Opacity
-
-```scss
-m.opacity("0")    // 0
-m.opacity("50")   // 0.5
-m.opacity("75")   // 0.75
-m.opacity("100")  // 1
-```
-
-### Transitions
-
-```scss
-m.duration("150")   // 150ms
-m.duration("200")   // 200ms
-m.duration("300")   // 300ms
-
-m.easing("in-out")  // cubic-bezier(0.4, 0, 0.2, 1)
-m.easing("out")     // cubic-bezier(0, 0, 0.2, 1)
-m.easing("bounce")  // cubic-bezier(0.34, 1.56, 0.64, 1)
-```
-
----
-
-## Functions
-
-| Function | Description | Example |
-|---|---|---|
-| `rem($px)` | Convert px to rem | `rem(16px)` -> `1rem` |
-| `em($px)` | Convert px to em | `em(16px)` -> `1em` |
-| `color($palette, $shade)` | Get a color token | `color("primary", 600)` |
-| `spacing($key)` | Get a spacing token | `spacing(4)` -> `1rem` |
-| `radius($key)` | Get a radius token | `radius("xl")` -> `0.75rem` |
-| `shadow($key)` | Get a shadow token | `shadow("md")` |
-| `z($key)` | Get a z-index token | `z("modal")` -> `400` |
-| `opacity($key)` | Get an opacity token | `opacity("50")` -> `0.5` |
-| `duration($key)` | Get a duration token | `duration("200")` -> `200ms` |
-| `easing($key)` | Get an easing token | `easing("in-out")` |
-| `tint($c, $pct)` | Mix color with white | `tint(blue, 20%)` |
-| `shade($c, $pct)` | Mix color with black | `shade(blue, 20%)` |
-| `alpha($c, $a)` | Adjust alpha channel | `alpha(blue, 0.5)` |
-| `contrast($bg)` | Black or white for contrast (1) | `contrast(#1e40af)` -> white |
-| `fluid($min, $max)` | Clamp-based fluid value | `fluid(1rem, 2rem)` |
-| `map-deep-get($map, $keys...)` | Deep nested map access | `map-deep-get($tokens, "primary", "600")` |
-| `map-collect($maps...)` | Shallow-merge multiple maps | `map-collect($a, $b)` |
-| `str-replace($str, $search)` | Replace substring | `str-replace("a-b", "-", "_")` |
-| `vars($token, $fallback?)` | CSS custom property reference | `vars(shadow-md)` -> `var(--mastors-shadow-md)` |
-
-(1) `contrast()` uses a simplified linear luminance approximation without sRGB gamma expansion. The threshold is set to `0.35` (not the WCAG `0.179`) to compensate for the missing gamma step — this gives correct results across the neutral scale. Suitable for UI decisions; implement full sRGB linearisation for strict WCAG 2.1 contrast-ratio auditing.
-
-### vars()
-
-`vars()` lets you reference any emitted design token as a CSS custom property by name, without hard-coding the `--mastors-` prefix. If the token name ever changes or the prefix is reconfigured, only the function implementation needs to update — all call sites stay the same.
-
-```scss
-@use "@mastors/core/api" as m;
-
-.button {
-  // Basic token reference
-  color:       m.vars(accent);
-  box-shadow:  m.vars(shadow-sm);
-
-  // With CSS fallback (passed through verbatim)
-  background:  m.vars(surface-raised, #f9fafb);
-  transition:  opacity m.vars(duration-150) m.vars(ease-out);
-
-  &:hover {
-    box-shadow: m.vars(shadow-md);
-    transform:  translateY(-1px);
-  }
-}
-
-// Composes cleanly with other values in shorthand properties
-.chip {
-  border: 1px solid m.vars(border);
-  padding: m.rem(4px) m.rem(10px);
-}
-```
-
-Token names follow the same `--mastors-{name}` convention used in `:root`. Common examples:
-
-| Call | Emits |
-|---|---|
-| `m.vars(accent)` | `var(--mastors-accent)` |
-| `m.vars(surface)` | `var(--mastors-surface)` |
-| `m.vars(shadow-lg)` | `var(--mastors-shadow-lg)` |
-| `m.vars(duration-200)` | `var(--mastors-duration-200)` |
-| `m.vars(ease-in-out)` | `var(--mastors-ease-in-out)` |
-| `m.vars(border, #e5e7eb)` | `var(--mastors-border, #e5e7eb)` |
-
----
-
-## Mixins
-
 ### Breakpoints
 
-Mobile-first, min-width media queries using the named breakpoint map.
-
-```scss
-// Breakpoints: xs (0px) - sm (640px) - md (768px) - lg (1024px) - xl (1280px) - 2xl (1536px)
-
-@include m.bp("md") {
-  // Applies at 768px and above
-}
-
-@include m.breakpoint-down("lg") {
-  // Applies below 1024px
-}
-
-// Aliases
-@include m.respond-to("xl") { ... }
-@include m.breakpoint-up("sm") { ... }
-```
-
-### Theme
-
-```scss
-@include m.dark-mode {
-  // Activates when .dark is on <html> (class mode)
-  // or prefers-color-scheme: dark (media mode)
-  background-color: m.color("neutral", 900);
-}
-
-@include m.light-mode {
-  background-color: m.color("white");
-}
-
-@include m.theme("ocean") {
-  // Activates under [data-theme="ocean"]
-  --accent: #0891b2;
-}
-```
-
-### Elevation
-
-```scss
-@include m.elevation("sm");   // box-shadow: 0 1px 3px ...
-@include m.elevation("lg");   // box-shadow: 0 10px 15px ...
-@include m.elevation("none"); // box-shadow: none
-```
-
-### Transition
-
-```scss
-// All properties, 200ms, in-out easing (defaults)
-@include m.transition();
-
-// Specific properties
-@include m.transition((color, background-color), "150", "out");
-
-// Custom combination
-@include m.transition((transform, opacity), "300", "bounce");
-```
-
-### Container
-
-```scss
-.page-section {
-  @include m.container();
-  // max-width per breakpoint, auto horizontal margins, configurable padding
-}
-```
-
-### Pseudo
-
-```scss
-.icon::before {
-  @include m.pseudo();
-  // Sets display: block, position: absolute, content: ""
-}
-```
-
----
-
-## Responsive Engine
-
-The engine in `responsive/_engine.scss` wraps utility maps in breakpoint media queries. Sub-packages can call `@include engine.run($utilities)` directly for standalone use.
-
-For the standard workflow, responsive variant generation is built into `generate-utilities()` — any utility entry that declares `responsive: true` automatically emits both base classes and breakpoint-prefixed variants in a single call. No separate invocation is required.
-
-Generated class pattern: `.{breakpoint}\:{class}`
-
-```html
-<!-- Responsive display -->
-<div class="hidden md:block lg:flex">...</div>
-
-<!-- Responsive position -->
-<div class="relative md:absolute lg:sticky">...</div>
-
-<!-- Responsive layout (from @mastors/flexer or @mastors/gridder) -->
-<div class="flex flex-col md:flex-row lg:gap-8">...</div>
-```
-
-Utilities with responsive support at v1.0: `display`, `position`.
-Additional responsive utilities added in v1.2: `text-align`, `float`, `flex-direction` (via flexer), `grid-template-columns` (via gridder).
-
----
-
-## Container Queries
-
-Container queries are supported via `responsive/_container-queries.scss`.
-
-**Setup classes:**
-
-| Class | Effect |
+| Key | Min-width |
 |---|---|
-| `.cq-inline` | `container-type: inline-size` |
-| `.cq-size` | `container-type: size` |
-| `.cq-normal` | `container-type: normal` |
-| `[data-container]` | `container-type: inline-size` (attribute-based) |
+| `xs` | 0px (base) |
+| `sm` | 640px |
+| `md` | 768px |
+| `lg` | 1024px |
+| `xl` | 1280px |
+| `2xl` | 1536px |
 
-**Usage:**
+### Radii
 
-```html
-<div class="cq-inline">
-  <div class="child">Responds to container width, not viewport</div>
-</div>
-```
+`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`
 
-```scss
-@use "@mastors/core/api" as m;
-
-.child {
-  font-size: 1rem;
-
-  @include m.cq(40rem) {
-    font-size: 1.25rem;
-  }
-
-  // Named container query
-  @include m.cq(30rem, "card") {
-    padding: m.spacing(6);
-  }
-}
-```
-
----
-
-## Fluid Typography
-
-`responsive/_fluid-type.scss` provides clamp()-based fluid font sizes that scale between two viewport widths without media queries.
-
-```scss
-@use "@mastors/core/api" as m;
+### Shadows
 
-// As a mixin (applies font-size property)
-h1 { @include m.fluid-type(2rem, 3.75rem); }
+`xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner`, `none`
 
-// As a function (use in any property value)
-h1 { font-size: m.fluid-type(2rem, 3.75rem); }
+### Durations
 
-// Custom viewport range
-h2 { @include m.fluid-type(1.5rem, 3rem, 480px, 1440px); }
-```
+`75`, `100`, `150`, `200`, `300`, `500`, `700`, `1000` (ms)
 
-Opt-in preset scale for all heading levels:
+### Easings
 
-```scss
-@use "@mastors/core/scss/responsive/fluid-type" as ft;
-@include ft.fluid-scale();
-// Applies fluid-type() to h1-h6 and p
-```
+`linear`, `in`, `out`, `in-out`
 
 ---
 
 ## Theme System
 
-Core emits all design tokens as `--mastors-*` CSS custom properties on `:root`. Theme layers override a semantic subset.
-
-**Default (light) theme properties:**
-
-```css
-:root {
-  --mastors-bg:              #ffffff;
-  --mastors-bg-subtle:       #f9fafb;
-  --mastors-surface:         #ffffff;
-  --mastors-surface-raised:  #f9fafb;
-  --mastors-surface-overlay: #f3f4f6;
-  --mastors-text:            #111827;
-  --mastors-text-muted:      #6b7280;
-  --mastors-text-subtle:     #9ca3af;
-  --mastors-text-inverse:    #ffffff;
-  --mastors-border:          #e5e7eb;
-  --mastors-border-strong:   #9ca3af;
-  --mastors-accent:          #2563eb;
-  --mastors-accent-hover:    #1d4ed8;
-  --mastors-accent-subtle:   #eff6ff;
-  --mastors-accent-text:     #ffffff;
-}
-```
-
-**Dark theme** activates via `.dark` on `<html>` (or `prefers-color-scheme` in media mode):
-
-```html
-<html class="dark">...</html>
-```
-
-Use semantic custom properties directly in your CSS for automatic theme switching:
-
-```css
-.card {
-  background-color: var(--mastors-surface);
-  color:            var(--mastors-text);
-  border-color:     var(--mastors-border);
-}
-```
-
-Or use `vars()` in SCSS for the same result without the prefix noise:
-
 ```scss
-.card {
-  background-color: m.vars(surface);
-  color:            m.vars(text);
-  border-color:     m.vars(border);
-}
+// Class-based dark mode (default)
+// Activate with: <html class="dark">
+$mastors-config: ("dark-mode": "class") !default;
+
+// Media-query dark mode
+$mastors-config: ("dark-mode": "media") !default;
 ```
 
-Custom themes can be applied with any `data-theme` attribute:
+Custom theme:
 
 ```scss
-@use "@mastors/core/api" as m;
-
 @include m.theme("ocean") {
   --mastors-accent: #0891b2;
-  --mastors-accent-hover: #0e7490;
 }
 ```
 
 ```html
-<div data-theme="ocean">
-  <!-- accent color is teal inside here -->
-</div>
+<div data-theme="ocean">...</div>
 ```
 
 ---
 
-## Base Layer
-
-The base layer emits a modern CSS reset and document defaults when you import the full stylesheet:
-
-- `box-sizing: border-box` on all elements (declared once in `_reset.scss`)
-- Zero margin and padding on all elements
-- `img`, `video`, `canvas`, `svg` set to `display: block; max-width: 100%`
-- `input`, `button`, `textarea`, `select` inherit font
-- Smooth scroll behaviour on `html`
-- `-webkit-font-smoothing: antialiased` on `body`
-- Base `color` and `background-color` on `html` driven by semantic custom properties
-- Heading sizes (h1-h6) driven by the typography token scale
-- Code/pre elements default to the mono font family
-
----
-
-## Utility Classes
-
-When importing the full stylesheet, core emits these utility classes:
-
-| Group | Classes |
-|---|---|
-| Display | `.block` `.inline-block` `.inline` `.flex` `.inline-flex` `.grid` `.inline-grid` `.hidden` `.contents` `.table` `.table-cell` `.table-row` |
-| Position | `.static` `.relative` `.absolute` `.fixed` `.sticky` - `.inset-*` `.top-*` `.right-*` `.bottom-*` `.left-*` |
-| Overflow | `.overflow-auto/hidden/scroll/visible/clip` - `.overflow-x-*` `.overflow-y-*` |
-| Spacing | `.m-*` `.mx-*` `.my-*` `.mt/r/b/l/s/e-*` - `.p-*` `.px-*` `.py-*` `.pt/r/b/l/s/e-*` - `.gap-*` `.gap-x-*` `.gap-y-*` |
-| Sizing | `.w-*` `.h-*` - `.min-w-*` `.max-w-*` `.min-h-*` `.max-h-*` |
-| Colors | `.text-*` `.bg-*` (all palettes x all shades + semantic) |
-| Borders | `.border` `.border-*` `.rounded-*` `.rounded-{t\|b\|l\|r}-*` (full scale, all token steps) |
-| Shadows | `.shadow-*` |
-| Opacity | `.opacity-*` |
-| Cursor | `.cursor-pointer` `.cursor-not-allowed` `.cursor-grab` etc. |
-| Pointer events | `.pointer-events-none` `.pointer-events-auto` |
-| Z-index | `.z-base` `.z-dropdown` `.z-modal` `.z-tooltip` etc. |
-| Transforms | `.translate-x-*` `.translate-y-*` `.rotate-*` `.scale-*` `.origin-*` `.transform-gpu` `.transform-none` |
-| Typography | `.text-{left\|center\|right\|justify\|start\|end}` (responsive) · `.text-{xs…9xl}` · `.font-{thin…black}` · `.font-{sans\|mono\|display}` · `.italic` `.not-italic` · `.leading-*` · `.tracking-*` · `.underline` `.overline` `.line-through` `.no-underline` · `.decoration-{solid\|dashed\|dotted\|double\|wavy}` · `.decoration-{1\|2\|4\|8}` · `.uppercase` `.lowercase` `.capitalize` `.normal-case` · `.text-ellipsis` `.text-clip` · `.whitespace-*` · `.break-normal` `.break-words` `.break-all` `.break-keep` · `.align-{baseline\|top\|middle\|bottom}` · `.list-none` `.list-disc` `.list-decimal` · `.antialiased` `.subpixel-antialiased` |
-| Animation | `.transition` `.transition-{colors\|opacity\|shadow\|transform\|none\|all}` · `.duration-*` · `.ease-*` · `.delay-*` · `.animate-{spin\|ping\|pulse\|bounce\|fade-in\|fade-out\|slide-up\|slide-down\|scale-in\|none}` · `.fill-{none\|forwards\|backwards\|both}` · `.animation-{running\|paused}` · `.animate-repeat-{0\|1\|infinite}` |
-| Interaction | `.select-{none\|text\|all\|auto}` · `.resize-{none\|x\|y}` `.resize` · `.scroll-{auto\|smooth}` · `.snap-{none\|x\|y\|both\|mandatory\|proximity}` · `.snap-{start\|end\|center}` · `.snap-stop-{always\|normal}` · `.scroll-m-*` `.scroll-p-*` · `.touch-{auto\|none\|pan-x\|pan-y\|manipulation}` · `hover:opacity-*` `hover:bg-accent` `hover:underline` `hover:shadow-lg` `hover:scale-{105\|110}` `hover:-translate-y-1` · `focus:ring` `focus:ring-2` `focus:ring-offset-2` `focus:ring-none` · `disabled:opacity-50` `disabled:cursor-not-allowed` `disabled:pointer-events-none` |
-| Layout | `.aspect-{auto\|square\|video\|4-3\|3-2\|21-9\|9-16\|golden}` · `.object-{contain\|cover\|fill\|none\|scale-down}` · `.object-{center\|top\|bottom\|left\|right\|…}` · `.float-{left\|right\|none\|start\|end}` (responsive) · `.clear-*` · `.isolate` `.isolation-auto` · `.mix-blend-*` · `.bg-blend-*` · `.box-decoration-{clone\|slice}` · `.appearance-{none\|auto}` · `.will-change-{auto\|scroll\|contents\|transform}` |
-
-Display and position utilities support responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`). Text-align and float also support responsive prefixes.
-
----
-
-## Helpers
-
-| Class | Effect |
-|---|---|
-| `.visually-hidden`, `.vh` | Visually hidden, screen-reader accessible |
-| `.visually-hidden-focusable` | Hidden until focused (use for skip links) |
-| `.truncate` | Single-line text truncation with ellipsis |
-| `.line-clamp-{1-6}` | Multi-line text clamp |
-| `.break-words` | `overflow-wrap: break-word` |
-| `.break-all` | `word-break: break-all` |
-| `.break-keep` | `word-break: keep-all` |
-| `.ratio-auto` | `aspect-ratio: auto` |
-| `.ratio-square` | `aspect-ratio: 1 / 1` |
-| `.ratio-video` | `aspect-ratio: 16 / 9` |
-| `.ratio-portrait` | `aspect-ratio: 3 / 4` |
-| `.ratio-wide` | `aspect-ratio: 21 / 9` |
-| `.ratio-golden` | `aspect-ratio: 1.618 / 1` |
-| `.clearfix` | Float clearfix via `::after` |
-
----
-
-## Accessibility
-
-| Class / Rule | Effect |
-|---|---|
-| `.sr-only` | Visually hidden, announced by screen readers |
-| `.not-sr-only` | Undoes `.sr-only` |
-| `.visually-hidden`, `.vh` | Equivalent to `.sr-only` with `!important` guards |
-| `.visually-hidden-focusable` | Hidden until focused (skip-link pattern) |
-| `:focus-visible` | 2px primary-500 ring, 2px offset — keyboard only |
-| `:focus:not(:focus-visible)` | Removes ring for mouse/pointer users |
-| `prefers-reduced-motion: reduce` | Collapses all animation/transition durations to 0.01ms |
-| `.print\:hidden` | `display: none` inside `@media print` |
-| `.screen\:hidden` | `display: none` outside `@media print` (print-only element) |
-| `.print\:break-inside-avoid` | Prevents page breaks inside the element when printing |
-| `.print\:break-before` | Forces a page break before the element |
-| `.print\:break-after` | Forces a page break after the element |
-| `.print\:text-black` | Forces `color: #000` for print output |
-| `.print\:bg-white` | Forces `background: #fff` for print output |
-| `.print\:border-none` | Removes borders for print output |
-| `.print\:shadow-none` | Removes box-shadow for print output |
-| `a[href]::after` *(print)* | Appends `(url)` after links so destinations are visible on paper |
+## Build
 
----
-
-## Generator Engine
-
-The three generator mixins are the engine behind all utility class output in the Mastors ecosystem.
-
-### `generate-utilities($utilities)`
-
-Generates utility classes from a configuration map. Used by `@mastors/flexer`, `@mastors/gridder`, and all core utility partials.
-
-The mixin runs in two passes:
-- **Pass 1** — emits base (unprefixed) classes for every entry.
-- **Pass 2** — for every entry with `responsive: true`, iterates all breakpoints (skipping `xs`/0px) and emits breakpoint-prefixed variants inside `@media` blocks. Respects the `$enable-responsive` flag and the global prefix/`!important` config.
-
-```scss
-@use "@mastors/core/scss/generators/class-generator" as gen;
-
-@include gen.generate-utilities((
-  "text-align": (
-    property:   text-align,
-    prefix:     "text",
-    responsive: true,
-    values: (
-      "left":   left,
-      "center": center,
-      "right":  right,
-    ),
-  ),
-));
-// Emits: .text-left, .text-center, .text-right
-// And:   .sm\:text-left, .md\:text-left, … for all breakpoints
-```
-
-### `emit-custom-properties($map, $prefix)`
-
-Emits flat CSS custom properties from a token map onto the current selector.
-
-```scss
-:root {
-  @include gen.emit-custom-properties($spacing-tokens, "mastors-spacing");
-  // -> --mastors-spacing-4: 1rem; etc.
-}
-```
-
-### `emit-nested-custom-properties($map, $prefix)`
-
-Recursively emits custom properties from a nested map (e.g. color palettes).
-
-```scss
-:root {
-  @include gen.emit-nested-custom-properties($color-tokens, "mastors-color");
-  // -> --mastors-color-primary-500: #3b82f6; etc.
-}
-```
-
----
-
-## Semantic Layer
-
-The semantic layer in `semantic/` provides role-based SCSS variable aliases on top of the raw token maps. Use these in component SCSS instead of raw token references to get automatic theme compatibility.
-
-**Colors:**
-
-```scss
-@use "@mastors/core/scss/semantic/colors" as sem;
-
-.my-card {
-  background: sem.$color-surface;          // var(--mastors-surface)
-  color:      sem.$color-text;             // var(--mastors-text)
-  border:     1px solid sem.$color-border; // var(--mastors-border)
-}
-```
-
-**Spacing:**
-
-```scss
-@use "@mastors/core/scss/semantic/spacing" as sem;
-
-.section {
-  padding: sem.$space-section;    // spacing(16) = 4rem
-  gap:     sem.$space-component;  // spacing(4)  = 1rem
-}
-```
-
-**Typography:**
-
-```scss
-@use "@mastors/core/scss/semantic/typography" as sem;
+```bash
+# From the monorepo root
+pnpm build:core
 
-body { font-family: sem.$font-body; }   // system-ui stack
-code { font-family: sem.$font-mono; }   // monospace stack
+# Or from this package
+node build.js
 ```
 
----
-
-## Known Stubs
-
-Two files are intentionally empty at v1.0 and act as reserved extension points:
-
-| File | Purpose |
-|---|---|
-| `abstracts/_maps.scss` | Shared utility maps consumed by 3+ unrelated files. Empty until such maps exist. |
-| `vendors/_index.scss` | Third-party CSS overrides. Add a partial and `@forward` it here when needed. |
-| `base/_box-sizing.scss` | Retained as a named path slot; box-sizing is declared in `_reset.scss`. |
-
-These stubs are documented in each file's header comment.
-
----
-
-## Package Exports
-
-```scss
-/* Full stylesheet — reset + tokens + themes + utilities */
-@use "@mastors/core/scss";
+Build steps: clean → compile SCSS → regenerate `src/tokens.ts` → compile TypeScript.
 
-/* Public API — zero CSS output, all tokens/mixins/functions/config */
-@use "@mastors/core/api" as m;
+To regenerate the TypeScript token mirror without a full build:
 
-/* Individual partials */
-@use "@mastors/core/scss/tokens/color" as ct;
-@use "@mastors/core/scss/mixins/breakpoint" as bp;
-@use "@mastors/core/scss/functions/rem" as r;
-@use "@mastors/core/scss/functions/vars";       /* vars() standalone */
-@use "@mastors/core/scss/responsive/fluid-type" as ft;
-@use "@mastors/core/scss/config/settings";      /* $mastors-config, config() */
-@use "@mastors/core/scss/config/flags";         /* $enable-* flags */
-```
-
-```ts
-// Runtime token access
-import { tokens } from '@mastors/core'
-
-// TypeScript types
-import type { MastorsConfig, Breakpoint, ThemeMode, Tokens } from '@mastors/core'
+```bash
+node scripts/generate-tokens.js
 ```
 
----
-
-## Peer Dependencies
-
-| Package | Version |
-|---|---|
-| `sass` | `>= 1.80.0` |
+> `src/tokens.ts` is auto-generated — never edit it manually.
 
 ---
 
 ## Changelog
 
-### v1.2.0
-
-- **Added:** `vars($token, $fallback?)` function in `functions/_vars.scss` — wraps the `--mastors-` namespace so downstream consumers reference tokens as `var(--mastors-{name})` without hard-coding the prefix. Namespace stored in `$-namespace: "mastors" !default`. Forwarded through `functions/_index.scss` and exposed via `@use "@mastors/core/api"`.
-- **Added:** `config/_index.scss` shim — `@forward`s both `_settings.scss` and `_flags.scss`. `api/_index.scss` now includes `@forward "../config/index"`, exposing `config()` accessor and all `$enable-*` flags through the public API surface without a direct partial import.
-- **Added:** `utilities/_typography.scss` — full typography utility surface covering text-align (responsive), font-size (token-driven `@each`), font-weight (token-driven), font-family (token-driven), font-style (`.italic` / `.not-italic`), line-height / leading (token-driven), letter-spacing / tracking (token-driven), text-decoration (line + style + thickness), text-transform, text-overflow, white-space, word-break, text-indent, vertical-align, list-style, font-smoothing.
-- **Added:** `utilities/_animation.scss` — transition-property presets (`.transition`, `.transition-colors`, `.transition-opacity`, `.transition-shadow`, `.transition-transform`, `.transition-none`, `.transition-all`), token-driven `.duration-*` and `.delay-*`, token-driven `.ease-*`, named animation presets (`.animate-spin/ping/pulse/bounce/fade-in/fade-out/slide-up/slide-down/scale-in/none`), full `@keyframes` definitions prefixed `mastors-*`, animation fill-mode / play-state / iteration utilities.
-- **Added:** `utilities/_interaction.scss` — user-select, resize, scroll-behavior (`.scroll-auto` / `.scroll-smooth`), scroll-snap (type + align + stop + scroll-margin/padding), touch-action, and state-variant pseudo-class utilities: `hover:opacity-*`, `hover:bg-accent`, `hover:text-accent`, `hover:underline`, `hover:no-underline`, `hover:shadow-lg`, `hover:scale-105`, `hover:scale-110`, `hover:-translate-y-1`, `focus:ring`, `focus:ring-2`, `focus:ring-offset-2`, `focus:ring-none`, `disabled:opacity-50`, `disabled:cursor-not-allowed`, `disabled:pointer-events-none`.
-- **Added:** `utilities/_layout.scss` — aspect-ratio block (`.aspect-auto`, `.aspect-square`, `.aspect-video`, `.aspect-4-3`, `.aspect-3-2`, `.aspect-21-9`, `.aspect-9-16`, `.aspect-golden`; the `$-aspect-ratios` map is `!default`-overridable). Documented alongside object-fit and object-position which were already present.
-- **Added:** `accessibility/_print.scss` — `print:hidden`, `screen:hidden`, `print:break-inside-avoid`, `print:break-before`, `print:break-after`, `print:text-black`, `print:bg-white`, `print:border-none`, `print:shadow-none`, automatic `a[href]::after` link expansion, suppression for `#` and `javascript:` links.
-
-### v1.0.0
-
-- Initial public release
-- Full token system: color, spacing, typography, radii, shadows, z-index, opacity, transitions, sizing
-- Complete functions layer: `rem`, `em`, `color`, `spacing`, `radius`, `shadow`, `z`, `opacity`, `duration`, `easing`, `tint`, `shade`, `alpha`, `contrast`, `fluid`, `map-deep-get`, `map-collect`, `str-replace`
-- Complete mixins layer: `bp`, `respond-to`, `breakpoint-up`, `breakpoint-down`, `dark-mode`, `light-mode`, `theme`, `elevation`, `transition`, `container`, `pseudo`
-- **Fixed:** `generate-utilities()` now runs a two-pass emit — Pass 1 outputs base classes, Pass 2 automatically emits breakpoint-prefixed responsive variants for all entries with `responsive: true`. Previously responsive variants were silently not emitted.
-- **Fixed:** `generators/_responsive-generator.scss` replaced the `@content`-based no-op stub with a thin wrapper that correctly delegates to `engine.run()` for backward compatibility.
-- **Fixed:** `contrast()` luminance threshold corrected from `0.179` (WCAG linearised) to `0.35` (calibrated for the simplified non-gamma-expanded approximation in use). Prevents wrong light/dark decisions on mid-grey backgrounds.
-- **Added:** `stylelint` linting with `stylelint-config-standard-scss` — `pnpm lint` now runs real SCSS style checks. `postcss-scss`, `stylelint`, and `stylelint-config-standard-scss` added to `devDependencies`; `.stylelintrc.json` added to `packages/core`.
-- Generator engine: `generate-utilities` (with integrated responsive Pass 2), `emit-custom-properties`, `emit-nested-custom-properties`
-- Responsive engine with correct numeric breakpoint escaping (`2xl:` prefix)
-- Container queries: `.cq-inline`, `.cq-size`, `.cq-normal`, `[data-container]`, `cq()` mixin
-- Fluid typography: `fluid-type()` mixin + function + `fluid-scale()` preset
-- Full directional border-radius utility scale — all four sides x all token steps
-- Light and dark themes via CSS custom property semantic contract (15 semantic props)
-- Modern CSS reset — no duplicate `box-sizing` declarations
-- Accessibility layer: `:focus-visible` ring, `prefers-reduced-motion` override, `.sr-only`, `.visually-hidden`
-- Dual dark-mode strategy: class-based and media-query, configurable via `$mastors-config`
-
----
+See the [root CHANGELOG](../../README.md#changelog).
 
 ## License
 
-MIT (c) Mastors Contributors
+MIT © Mastors Contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastors/core",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Mastors Core — foundational tokens, mixins, functions, and SCSS architecture",
   "license": "MIT",
   "author": "Mastors Contributors",
@@ -51,8 +51,8 @@
     "stylelint-config-standard-scss": "^13.0.0",
     "typescript": "^5.3.0",
     "@mastors/build-utils": "2.0.0",
-    "@mastors/sass-config": "1.0.1",
-    "@mastors/tsconfig": "1.0.1"
+    "@mastors/tsconfig": "1.0.1",
+    "@mastors/sass-config": "1.0.1"
   },
   "peerDependencies": {
     "sass": ">=1.80.0"