@skdx/tokens 0.26.0 → 0.28.0

package/dist/themes/OneLight.d.cts

@@ -1,12 +1,8 @@
 /**
- * Light counterpart of `one-dark`, following Atom's One Light scheme
- * (#fafafa background, #383a42 text). Palette source: atom/one-light-syntax
- * (MIT).
- *
- * `primary-500` is One Light's own blue (#4078f2), not a lightened One Dark
- * blue — the two schemes pick genuinely different blues, and 500 is the slot
- * consumers read for a plain accent. 600 is that blue darkened, since
- * #4078f2 carries only 4.05:1 under white label text.
+ * Light counterpart of `one-dark`, following One Light's scheme
+ * (#fafafa background, #383a42 text). Uses One Light's own blue (#4078f2);
+ * the two schemes specify different blues. At 500 it reaches only 4.05:1
+ * contrast; 600 darkens it for white text.
  *
  * @public
  */

package/dist/themes/OneLight.d.ts

@@ -1,12 +1,8 @@
 /**
- * Light counterpart of `one-dark`, following Atom's One Light scheme
- * (#fafafa background, #383a42 text). Palette source: atom/one-light-syntax
- * (MIT).
- *
- * `primary-500` is One Light's own blue (#4078f2), not a lightened One Dark
- * blue — the two schemes pick genuinely different blues, and 500 is the slot
- * consumers read for a plain accent. 600 is that blue darkened, since
- * #4078f2 carries only 4.05:1 under white label text.
+ * Light counterpart of `one-dark`, following One Light's scheme
+ * (#fafafa background, #383a42 text). Uses One Light's own blue (#4078f2);
+ * the two schemes specify different blues. At 500 it reaches only 4.05:1
+ * contrast; 600 darkens it for white text.
  *
  * @public
  */

package/dist/themes/PrimerDark.d.cts

@@ -2,7 +2,6 @@ import type { Theme } from '../utils/theme.cjs';
 /**
  * Primer Dark inspired theme: GitHub's dark mode — `#0d1117` canvas,
  * `#1f6feb` accent blue, and the Primer dark green/yellow/red scales.
- * Palette source: primer/primitives (MIT).
  *
  * @public
  */

package/dist/themes/PrimerDark.d.ts

@@ -2,7 +2,6 @@ import type { Theme } from '../utils/theme.js';
 /**
  * Primer Dark inspired theme: GitHub's dark mode — `#0d1117` canvas,
  * `#1f6feb` accent blue, and the Primer dark green/yellow/red scales.
- * Palette source: primer/primitives (MIT).
  *
  * @public
  */

package/dist/themes/RosePineDawn.d.cts

@@ -1,12 +1,8 @@
 /**
- * Light counterpart of `rose-pine`, built on the Rosé Pine Dawn variant
- * (#faf4ed base, #575279 text). Palette source: rose-pine/rose-pine-theme
- * (MIT).
- *
- * `primary-500` is Dawn's own iris (#907aa9) — Dawn restates every role
- * rather than lightening Main's, and its iris is markedly softer than
- * Main's #c4a7e7. 600 is that iris darkened, since #907aa9 carries only
- * 3.79:1 under white label text.
+ * Light counterpart of `rose-pine`, built on Rosé Pine Dawn
+ * (#faf4ed base, #575279 text). Uses Dawn's iris (#907aa9), which is softer
+ * than the dark palette's #c4a7e7. At 500 it reaches only 3.79:1 contrast;
+ * 600 darkens it for white text.
  *
  * @public
  */

package/dist/themes/RosePineDawn.d.ts

@@ -1,12 +1,8 @@
 /**
- * Light counterpart of `rose-pine`, built on the Rosé Pine Dawn variant
- * (#faf4ed base, #575279 text). Palette source: rose-pine/rose-pine-theme
- * (MIT).
- *
- * `primary-500` is Dawn's own iris (#907aa9) — Dawn restates every role
- * rather than lightening Main's, and its iris is markedly softer than
- * Main's #c4a7e7. 600 is that iris darkened, since #907aa9 carries only
- * 3.79:1 under white label text.
+ * Light counterpart of `rose-pine`, built on Rosé Pine Dawn
+ * (#faf4ed base, #575279 text). Uses Dawn's iris (#907aa9), which is softer
+ * than the dark palette's #c4a7e7. At 500 it reaches only 3.79:1 contrast;
+ * 600 darkens it for white text.
  *
  * @public
  */

package/dist/themes/SkandaDark.d.cts

@@ -1,11 +1,7 @@
 /**
- * Dark counterpart of `skanda-light` — the Skanda blue on deep slate
- * surfaces. Together they form the `skanda` brand's light/dark pair (see
- * `brands`).
- *
- * The ramp is centred one step lighter than the light theme's: `primary-600`
- * is the filled-action slot in both modes, and a mid-blue tuned to sit on
- * white is too dark to read as an accent on `#0f172a`.
+ * Dark counterpart of `skanda-light` — Skanda blue on deep slate.
+ * The ramp is shifted one step lighter; mid-blue tuned for white becomes
+ * too dark as an accent on `#0f172a`.
  *
  * @public
  */

package/dist/themes/SkandaDark.d.ts

@@ -1,11 +1,7 @@
 /**
- * Dark counterpart of `skanda-light` — the Skanda blue on deep slate
- * surfaces. Together they form the `skanda` brand's light/dark pair (see
- * `brands`).
- *
- * The ramp is centred one step lighter than the light theme's: `primary-600`
- * is the filled-action slot in both modes, and a mid-blue tuned to sit on
- * white is too dark to read as an accent on `#0f172a`.
+ * Dark counterpart of `skanda-light` — Skanda blue on deep slate.
+ * The ramp is shifted one step lighter; mid-blue tuned for white becomes
+ * too dark as an accent on `#0f172a`.
  *
  * @public
  */

package/dist/themes/SynthwaveLight.d.cts

@@ -1,11 +1,7 @@
 /**
- * Light counterpart of `synthwave-dark` — the neon pink primary on pale
- * lavender surfaces.
- *
- * Synthwave '84 is a dark-only scheme upstream, so unlike the other bundled
- * pairs this light mode has no published palette to match; it is a
- * deliberate derivation, holding the neon's hue while dropping lightness far
- * enough to survive on paper. The dark mode takes the real #ff7edb.
+ * Light counterpart of `synthwave-dark` — neon pink primary on pale lavender.
+ * This light mode is a deliberate derivation: the dark theme uses the real
+ * neon pink (#ff7edb), but dropped here to survive on paper.
  *
  * @public
  */

package/dist/themes/SynthwaveLight.d.ts

@@ -1,11 +1,7 @@
 /**
- * Light counterpart of `synthwave-dark` — the neon pink primary on pale
- * lavender surfaces.
- *
- * Synthwave '84 is a dark-only scheme upstream, so unlike the other bundled
- * pairs this light mode has no published palette to match; it is a
- * deliberate derivation, holding the neon's hue while dropping lightness far
- * enough to survive on paper. The dark mode takes the real #ff7edb.
+ * Light counterpart of `synthwave-dark` — neon pink primary on pale lavender.
+ * This light mode is a deliberate derivation: the dark theme uses the real
+ * neon pink (#ff7edb), but dropped here to survive on paper.
  *
  * @public
  */

package/dist/themes/brands.d.cts

@@ -1,11 +1,8 @@
 import type { Theme, ThemeColorMode } from '../utils/theme.cjs';
 /**
  * A brand is one visual identity with a complete {@link Theme} per color
- * mode. The brand decides identity (palette hues, type, radii, motion); the
- * mode decides light or dark appearance. Consumers resolve a user's brand
- * preference plus color-mode preference to `brand.themes[mode]` and hand
- * that theme to the existing `themeToCss`/`applyTheme` pipeline — the
- * resolved theme is an ordinary `Theme`, so nothing downstream changes.
+ * mode — the brand decides identity (palette, type, radii, motion), the
+ * mode decides light or dark appearance.
  *
  * @public
  */
@@ -18,23 +15,19 @@ export interface Brand {
     themes: Record<ThemeColorMode, Theme>;
 }
 /**
- * Every bundled brand with its light/dark theme pair, in the same order the
- * pre-brand `themes` array introduced them. This array is the authoritative
- * brand registry — tests derive the brand-and-mode support matrix from it,
- * so a brand missing either mode fails validation rather than falling back
- * to another brand's values.
+ * Every bundled brand with its light/dark theme pair in stable order —
+ * the authoritative brand registry for the brand-and-mode support matrix.
  *
  * @public
  */
 export declare const brands: Brand[];
-/** The default brand — `skanda`, whose light theme is `defaultTheme`/`skanda-light`. @public */
+/** Default brand (`skanda-light`). @public */
 export declare const defaultBrand: Brand;
-/** Looks up a brand by its stable identifier; `undefined` for unknown names so callers can apply their own fallback. @public */
+/** Looks up a brand by its stable identifier; `undefined` if not found. @public */
 export declare function getBrand(name: string): Brand | undefined;
 /**
  * Looks up the brand that owns a theme name (either mode) — e.g.
- * `'one-dark'` → the `one` brand. Useful for migrating persisted
- * pre-brand theme-name preferences to a brand preference.
+ * `'one-dark'` → the `one` brand.
  *
  * @public
  */

package/dist/themes/brands.d.ts

@@ -1,11 +1,8 @@
 import type { Theme, ThemeColorMode } from '../utils/theme.js';
 /**
  * A brand is one visual identity with a complete {@link Theme} per color
- * mode. The brand decides identity (palette hues, type, radii, motion); the
- * mode decides light or dark appearance. Consumers resolve a user's brand
- * preference plus color-mode preference to `brand.themes[mode]` and hand
- * that theme to the existing `themeToCss`/`applyTheme` pipeline — the
- * resolved theme is an ordinary `Theme`, so nothing downstream changes.
+ * mode — the brand decides identity (palette, type, radii, motion), the
+ * mode decides light or dark appearance.
  *
  * @public
  */
@@ -18,23 +15,19 @@ export interface Brand {
     themes: Record<ThemeColorMode, Theme>;
 }
 /**
- * Every bundled brand with its light/dark theme pair, in the same order the
- * pre-brand `themes` array introduced them. This array is the authoritative
- * brand registry — tests derive the brand-and-mode support matrix from it,
- * so a brand missing either mode fails validation rather than falling back
- * to another brand's values.
+ * Every bundled brand with its light/dark theme pair in stable order —
+ * the authoritative brand registry for the brand-and-mode support matrix.
  *
  * @public
  */
 export declare const brands: Brand[];
-/** The default brand — `skanda`, whose light theme is `defaultTheme`/`skanda-light`. @public */
+/** Default brand (`skanda-light`). @public */
 export declare const defaultBrand: Brand;
-/** Looks up a brand by its stable identifier; `undefined` for unknown names so callers can apply their own fallback. @public */
+/** Looks up a brand by its stable identifier; `undefined` if not found. @public */
 export declare function getBrand(name: string): Brand | undefined;
 /**
  * Looks up the brand that owns a theme name (either mode) — e.g.
- * `'one-dark'` → the `one` brand. Useful for migrating persisted
- * pre-brand theme-name preferences to a brand preference.
+ * `'one-dark'` → the `one` brand.
  *
  * @public
  */

package/dist/themes/createBrandTheme.d.cts

@@ -1,44 +1,36 @@
 import type { Theme, ThemeColorMode, ThemeOverride } from '../utils/theme.cjs';
 /**
- * Internal seed for {@link createBrandTheme} — the handful of decisions that
- * actually define a brand's palette. Everything else (ramp shape, semantic
- * role assignment, contrast enforcement) is derived.
+ * Seed for {@link createBrandTheme}: brand hues and chroma. Ramp shape,
+ * semantic roles, contrast enforcement are derived.
  */
 export interface BrandSeed {
-    /** Theme name, e.g. `'midnight-light'`. Becomes `theme.name`. */
+    /** Theme name (e.g. `'midnight-light'`); becomes `theme.name`. */
     name: string;
-    /** Which mode's semantic roles to derive — the ramps themselves are mode-independent. */
+    /** Which mode's semantic roles to derive (ramps are mode-independent). */
     mode: ThemeColorMode;
     /** Primary hue in degrees, 0–360 (e.g. 272 for violet). */
     primaryHue: number;
-    /** Saturation of the primary ramp, 0–100. Lower it toward 0 for a monochrome brand. @default 75 */
+    /** Primary ramp saturation, 0–100. Toward 0 for monochrome. @default 75 */
     primaryChroma?: number;
-    /** Hue the grays are tinted toward. @default primaryHue */
+    /** Gray tint hue. @default primaryHue */
     neutralHue?: number;
-    /** How much tint the grays carry, 0–100. @default 8 */
+    /** Gray tint amount, 0–100. @default 8 */
     neutralChroma?: number;
-    /** Hues for the intent ramps. @default { success: 145, warning: 40, danger: 0 } */
+    /** Intent ramp hues. @default { success: 145, warning: 40, danger: 0 } */
     intentHues?: {
         success?: number;
         warning?: number;
         danger?: number;
     };
-    /** Saturation of the intent ramps, 0–100. @default 70 */
+    /** Intent ramp saturation, 0–100. @default 70 */
     intentChroma?: number;
-    /** Merged last, so a brand can still hand-pick anything the seed derives — in practice the shadow tint, which isn't derivable from hue. */
+    /** Hand-picked overrides merged last (typically shadow tint). */
     override?: ThemeOverride;
 }
 /**
- * Generates a complete {@link Theme} from a {@link BrandSeed}: three-plus
- * ramps built from the seed's hues, semantic roles assigned per mode, and
- * every WCAG AA pair the contrast test checks (body text 4.5:1, muted text
- * and focus ring 3:1 against the page background, inverted text 4.5:1 against
- * `primary-600`) driven to threshold by adjusting lightness rather than being
- * hand-tuned and hoped for.
- *
- * Internal on purpose: it is the seam a visual theme builder will call, not a
- * public token API — brands that ship today are hand-written theme objects,
- * and only `midnight` is generated so far (see `MidnightBrand.ts`).
+ * Generate {@link Theme} from {@link BrandSeed}: ramps from hues, semantic
+ * roles per mode, WCAG AA pairs enforced to threshold via lightness walk.
+ * Internal: visual theme builders call this; hand-written themes are the public API.
  *
  * @example
  * ```ts

package/dist/themes/createBrandTheme.d.ts

@@ -1,44 +1,36 @@
 import type { Theme, ThemeColorMode, ThemeOverride } from '../utils/theme.js';
 /**
- * Internal seed for {@link createBrandTheme} — the handful of decisions that
- * actually define a brand's palette. Everything else (ramp shape, semantic
- * role assignment, contrast enforcement) is derived.
+ * Seed for {@link createBrandTheme}: brand hues and chroma. Ramp shape,
+ * semantic roles, contrast enforcement are derived.
  */
 export interface BrandSeed {
-    /** Theme name, e.g. `'midnight-light'`. Becomes `theme.name`. */
+    /** Theme name (e.g. `'midnight-light'`); becomes `theme.name`. */
     name: string;
-    /** Which mode's semantic roles to derive — the ramps themselves are mode-independent. */
+    /** Which mode's semantic roles to derive (ramps are mode-independent). */
     mode: ThemeColorMode;
     /** Primary hue in degrees, 0–360 (e.g. 272 for violet). */
     primaryHue: number;
-    /** Saturation of the primary ramp, 0–100. Lower it toward 0 for a monochrome brand. @default 75 */
+    /** Primary ramp saturation, 0–100. Toward 0 for monochrome. @default 75 */
     primaryChroma?: number;
-    /** Hue the grays are tinted toward. @default primaryHue */
+    /** Gray tint hue. @default primaryHue */
     neutralHue?: number;
-    /** How much tint the grays carry, 0–100. @default 8 */
+    /** Gray tint amount, 0–100. @default 8 */
     neutralChroma?: number;
-    /** Hues for the intent ramps. @default { success: 145, warning: 40, danger: 0 } */
+    /** Intent ramp hues. @default { success: 145, warning: 40, danger: 0 } */
     intentHues?: {
         success?: number;
         warning?: number;
         danger?: number;
     };
-    /** Saturation of the intent ramps, 0–100. @default 70 */
+    /** Intent ramp saturation, 0–100. @default 70 */
     intentChroma?: number;
-    /** Merged last, so a brand can still hand-pick anything the seed derives — in practice the shadow tint, which isn't derivable from hue. */
+    /** Hand-picked overrides merged last (typically shadow tint). */
     override?: ThemeOverride;
 }
 /**
- * Generates a complete {@link Theme} from a {@link BrandSeed}: three-plus
- * ramps built from the seed's hues, semantic roles assigned per mode, and
- * every WCAG AA pair the contrast test checks (body text 4.5:1, muted text
- * and focus ring 3:1 against the page background, inverted text 4.5:1 against
- * `primary-600`) driven to threshold by adjusting lightness rather than being
- * hand-tuned and hoped for.
- *
- * Internal on purpose: it is the seam a visual theme builder will call, not a
- * public token API — brands that ship today are hand-written theme objects,
- * and only `midnight` is generated so far (see `MidnightBrand.ts`).
+ * Generate {@link Theme} from {@link BrandSeed}: ramps from hues, semantic
+ * roles per mode, WCAG AA pairs enforced to threshold via lightness walk.
+ * Internal: visual theme builders call this; hand-written themes are the public API.
  *
  * @example
  * ```ts

package/dist/utils/aliases.d.cts

@@ -1,121 +1,51 @@
 /**
- * The semantic alias layer: the vocabulary component skins are allowed to name.
+ * The semantic alias layer: `var()` indirection for component skins.
  *
- * Why this file exists
- * -------------------
- * `@skdx/skins` is forbidden from containing a colour literal — every colour
- * it declares must resolve through a token. But the surface a theme actually
- * defines is small: five ramps (`primary`, `neutral`, `success`, `warning`,
- * `danger`) and ten `semantic` entries. A button skin needs more than that. It
- * needs to say "the background of a pressed primary action" and "the border of
- * an invalid field", and neither exists as a theme-authored token.
+ * Aliases point at ramp steps and semantic entries themes already define. A
+ * theme redeclaring `--skdx-color-primary-600` makes every alias pointing
+ * there re-resolve, so adding a theme costs one line per alias, not 38.
  *
- * The naive fix is to add those names to `SemanticColors` and set them in all
- * 38 themes. That is 38 files edited per alias added, and every one of those
- * edits is a chance for a theme to drift out of step with the others.
+ * Aliases are emitted at `:root`, below theme declarations in the cascade,
+ * letting a theme override an alias when the derivation is mode-dependent.
+ * {@link darkColorAliases} uses this escape hatch for aliases that put ink
+ * directly on the page and need opposite ends of the ramp in dark mode.
  *
- * This layer takes the other option: aliases are **pure `var()` indirection**,
- * declared once at `:root`, pointing at ramp steps and semantic entries the
- * themes already define. No alias holds a colour — it holds the *name of* a
- * colour. So when `[data-skdx-theme="nord-dark"]` redeclares
- * `--skdx-color-primary-600` at its own higher-specificity selector, every alias
- * pointing at that step re-resolves to Nord's value automatically. Adding a
- * theme costs nothing here, and adding an alias costs one line rather than 38.
- *
- * This is also why the aliases are emitted at `:root` rather than inside each
- * theme block: they must sit *below* the theme declarations in the cascade so a
- * theme can still override an alias outright when the derivation is wrong for
- * it. {@link darkColorAliases} is exactly that escape hatch in use: a ramp runs
- * light-to-dark in every theme, so the aliases that put ink directly on the
- * page need the opposite end in dark mode.
- *
- * Choosing the ramp step
- * ----------------------
- * A dark theme's ramp is authored for dark — `NordDark`'s `primary-600` is
- * already a step that works as a filled background on a dark surface, the same
- * way `DefaultTheme`'s is on a light one. So a single step choice per alias is
- * correct in both modes for the *filled* aliases. It does not hold for aliases
- * that put ink or a wash directly on the page — see {@link darkColorAliases},
- * which was written after measuring 22 of 38 themes failing WCAG contrast.
- *
- * @see docs/architecture/skin-token-map.md for the per-property mapping table.
+ * @see packages/skins/README.md for how a skin consumes these aliases.
  */
 /**
- * Every alias, as `[name, value]` pairs where `value` is always a `var()`
- * reference — never a literal. Grouped by the question a skin author asks.
- *
- * Kept as data rather than a hand-written CSS string so
- * `aliases.test.ts` can assert the no-literal rule mechanically over the whole
- * set, which is the only thing standing between this file and the exact class
- * of drift the skins package's Stylelint rule exists to prevent.
+ * Alias entries as `[name, value]` pairs, where `value` is always a `var()` reference.
+ * Kept as data so `aliases.test.ts` can assert the no-literal rule.
  */
 export declare const colorAliases: ReadonlyArray<readonly [string, string]>;
 /**
- * The aliases a dark theme re-points, and what it re-points them to.
- *
- * Why this exists
- * ---------------
- * The base table above picks one ramp step per alias and claims that is correct
- * in both modes. For most aliases it is: a theme authors its ramp for its own
- * mode, so `primary-600` is a usable filled background whichever way the page
- * faces.
- *
- * It is *not* true for the aliases that put ink directly on the page. A ramp
- * runs light at 50 to dark at 950 in every theme, dark ones included — that is
- * what makes a ramp a ramp. So `--skdx-color-text-danger: danger-700` is dark
- * red: correct on a white page, and nearly invisible on a charcoal one. The
- * same applies to every "wash + dark ink" status pairing, and to the neutral
- * fills (`surface-sunken`, `track`, `skeleton`) that assume the page is lighter
- * than they are.
- *
- * Measured before writing this: 22 of the 38 themes had at least one contrast
- * failure, every one of them a dark theme, and every failure in this list.
- * Input text sat at 1.07:1 and the tooltip at 1.00:1.
- *
- * The fix uses the escape hatch the base table was designed around — a theme
- * may override an alias, because `[data-skdx-theme="…"]` outranks `:root`. These
- * overrides are emitted automatically for every theme whose `mode` is `'dark'`,
- * so the cost stays "one line per alias" rather than "one edit per theme", and
- * a new dark theme is correct the day it lands without anyone remembering this
- * file exists.
- *
- * Steps mirror around the middle of the ramp: 700 → 300, 800 → 200, 50 → 950.
- * That keeps the light and dark treatments the same *distance* from their
- * background rather than merely both legible.
+ * Dark-mode alias overrides. Base table picks one ramp step per alias; it fails
+ * for aliases putting ink directly on the page (ramp runs 50–950 in all themes,
+ * so dark-page inks become invisible). These overrides automatically emit for
+ * themes where `mode` is `'dark'`. Steps mirror around ramp center: 700 → 300,
+ * keeping equal distance from background.
  */
 export declare const darkColorAliases: ReadonlyArray<readonly [string, string]>;
 /**
- * Renders {@link darkColorAliases} at `selector`, for a theme whose mode is dark.
- *
- * @param selector - The theme's own selector, e.g. `'[data-skdx-theme="nord-dark"]'`.
+ * Renders {@link darkColorAliases} at the theme selector.
+ * @param selector - Theme selector, e.g. `'[data-skdx-theme="nord-dark"]'`.
  * @public
  */
 export declare function darkAliasesToCss(selector: string): string;
 /**
- * Renders {@link colorAliases} as a `:root` rule block.
- *
- * Emitted *after* `foundationToCss()` and *before* the theme blocks in
- * `@skdx/tokens/css`. Order matters in one direction only: an alias must be
- * able to be overridden by a theme, and `:root` loses to
- * `[data-skdx-theme="…"]` on specificity regardless of source order, so the
- * position here is for readability rather than correctness.
- *
- * @returns A CSS string, e.g. `':root {\n  --skdx-color-action-primary-bg: var(--skdx-color-primary-600);\n  …\n}\n'`.
+ * Renders {@link colorAliases} as a `:root` rule block. `:root` always loses
+ * to `[data-skdx-theme="…"]` on specificity.
  *
+ * @returns CSS string; emitted after `foundationToCss()` and before theme blocks.
  * @example
  * ```ts
  * import { foundationToCss, aliasesToCss } from '@skdx/tokens';
- *
  * fs.writeFileSync('tokens.css', foundationToCss() + aliasesToCss());
  * ```
- *
  * @public
  */
 export declare function aliasesToCss(): string;
 /**
- * {@link colorAliases} as a plain object, for consumers applying tokens through
- * JS rather than a stylesheet (the alias counterpart to `themeToCssVars`).
- *
+ * {@link colorAliases} as a plain object for JS consumers (counterpart to `themeToCssVars`).
  * @public
  */
 export declare function aliasesToCssVars(): Record<string, string>;