@dowel-ui/themes 0.4.0 → 0.7.0

package/dist/index.d.ts

@@ -1,3 +1,212 @@
+//#region src/colour.d.ts
+/**
+ * OKLCH → sRGB, and WCAG contrast.
+ *
+ * The design tokens are authored in OKLCH because its lightness is
+ * perceptually even. WCAG contrast, however, is defined on sRGB relative
+ * luminance — so checking the palette means actually converting it rather than
+ * eyeballing the lightness numbers, which are not the same thing.
+ */
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+/** Parses `oklch(L C H)` or `oklch(L C H / A)`. L may be a percentage. */
+declare function parseOklch(value: string): {
+  l: number;
+  c: number;
+  h: number;
+  alpha: number;
+} | undefined;
+/** Linear-light sRGB, before gamma encoding. Luminance is defined on these. */
+declare function oklchToLinearRgb(l: number, c: number, h: number): Rgb;
+/** WCAG 2.x relative luminance. */
+declare function luminance(rgb: Rgb): number;
+/**
+ * Composites a translucent colour over an opaque one.
+ *
+ * Several tokens are alpha values over a surface — an overlay, a tinted alert
+ * background. Measuring them without compositing would report the contrast of a
+ * colour nobody ever sees.
+ */
+declare function composite(foreground: Rgb, alpha: number, background: Rgb): Rgb;
+declare function contrastRatio(a: Rgb, b: Rgb): number;
+/** `oklch(...)` string to linear RGB, composited over `over` if translucent. */
+declare function resolveColour(value: string, over?: Rgb): Rgb | undefined;
+/** Gamma-encoded sRGB, 0–255, from linear-light sRGB. */
+declare function encodeSrgb(rgb: Rgb): {
+  r: number;
+  g: number;
+  b: number;
+};
+/** Linear-light sRGB from gamma-encoded channels, each 0–255. */
+declare function decodeSrgb(r: number, g: number, b: number): Rgb;
+interface Oklch {
+  l: number;
+  c: number;
+  h: number;
+}
+/**
+ * Linear-light sRGB to OKLCH.
+ *
+ * The inverse of `oklchToLinearRgb`, needed because people pick colours as hex
+ * and the tokens are authored in OKLCH. Round-tripping through this is lossy
+ * only where the input is outside the OKLCH gamut the tokens use, which a hex
+ * value from a colour input never is.
+ */
+declare function linearRgbToOklch(rgb: Rgb): Oklch;
+/** `#rrggbb` (or `#rgb`) to OKLCH. Undefined for anything else. */
+declare function hexToOklch(hex: string): Oklch | undefined;
+declare function oklchToHex({ l, c, h }: Oklch): string;
+/** An OKLCH triple as the tokens write it. */
+declare function formatOklch({ l, c, h }: Oklch): string;
+//#endregion
+//#region src/preset.d.ts
+/** WCAG 2.2 AA for normal text; a button label is normal text. */
+declare const TEXT_MINIMUM = 4.5;
+/**
+ * Text for a saturated background: near-white, or a dark tint of its own hue.
+ *
+ * Whichever reads better, rather than always white. A light primary — amber,
+ * lime — cannot carry white text at 4.5:1 no matter how it is nudged, and the
+ * shipped `amber` preset is dark-on-light for exactly this reason.
+ */
+declare function foregroundFor(background: Oklch): Oklch;
+interface PresetMode {
+  primary: Oklch;
+  primaryHover: Oklch;
+  primaryActive: Oklch;
+  primaryForeground: Oklch;
+}
+interface DerivedPreset {
+  light: PresetMode;
+  dark: PresetMode;
+}
+interface DeriveOptions {
+  /**
+   * Lightness of the dark-mode primary.
+   *
+   * Overridable because it is the one derived value with no single right
+   * answer: how bright a brand reads on near-black is a judgement about the
+   * brand, not about contrast.
+   */
+  darkLightness?: number;
+}
+declare function derivePreset(input: Oklch, options?: DeriveOptions): DerivedPreset;
+interface ContrastCheck {
+  label: string;
+  ratio: number;
+  minimum: number;
+  passes: boolean;
+}
+/**
+ * The pairs a derived preset is responsible for.
+ *
+ * Only these four per mode: every other pair in the system is inherited from
+ * the base tokens, which the audit already covers. Reporting the inherited ones
+ * would be reporting on something the person cannot change from here.
+ */
+declare function checkPreset(preset: DerivedPreset): ContrastCheck[];
+/**
+ * The preset as a stylesheet, in the same shape as the ones that ship.
+ *
+ * Deliberately the same file format rather than a bespoke export: what comes
+ * out of here can be dropped into `packages/themes/src/presets/` unchanged, and
+ * is then covered by the same audit as everything else.
+ */
+declare function formatPreset(name: string, preset: DerivedPreset): string;
+/** A name usable as a `data-theme` value. */
+declare function slugify(name: string): string;
+//#endregion
+//#region src/figma.d.ts
+/**
+ * The tokens, in the shape a design tool reads.
+ *
+ * The CSS is the source of truth and stays that way — nothing here is a second
+ * palette to keep in step. This reads the same `tokens.css`, `base.css` and
+ * preset files the components consume, resolves every `var()` the way a
+ * browser would, and writes the result as W3C Design Tokens (DTCG): the format
+ * Tokens Studio for Figma imports directly, and the one every other design
+ * tool is converging on.
+ *
+ * Colours come out as sRGB hex. Figma has no OKLCH; converting here, with the
+ * same maths the contrast audit uses, means the swatch a designer sees is the
+ * colour a user gets — rather than whatever a tool makes of an `oklch()` string
+ * it cannot parse.
+ */
+/** A flat map of custom property name (without the leading `--`) to raw value. */
+type Declarations = Record<string, string>;
+/** A W3C Design Tokens document: nested groups whose leaves carry `$type` and `$value`. */
+interface DesignToken {
+  $type: "color" | "dimension" | "fontFamily" | "number";
+  $value: string | number | string[];
+  $description?: string;
+}
+interface DesignTokenGroup {
+  [key: string]: DesignToken | DesignTokenGroup | string | undefined;
+  $description?: string;
+}
+/**
+ * The declarations inside the first block whose selector is exactly `selector`.
+ *
+ * Exact, not substring: `.dark` must not match `.dark[data-theme="ocean"]`, and
+ * `:root` must not match `:root[dir="rtl"]`. Whitespace inside a value is
+ * collapsed, because a font stack written over four lines is one value.
+ */
+declare function parseTokenCss(css: string, selector: string): Declarations;
+/**
+ * Resolves `var(--x)` references the way the cascade would.
+ *
+ * `scopes` are searched in order, so a mode's own declarations shadow the root's
+ * and the root's shadow the raw scale — which is exactly what `.dark { --x }`
+ * over `:root { --x }` over `@theme { --x }` means. A fallback inside the
+ * `var()` is used when nothing defines the name, and an unresolvable reference
+ * is left as written rather than silently dropped.
+ */
+declare function resolveReferences(value: string, scopes: Declarations[]): string;
+/** `oklch(...)` to `#rrggbb`, or `#rrggbbaa` when it carries alpha. */
+declare function cssColourToHex(value: string): string | undefined;
+/**
+ * A length in px, for the values the scale is written in.
+ *
+ * Handles the two shapes the tokens use: a plain `rem`/`px`, and the radius
+ * ladder's `calc(<rem> * var(--radius-scale, 1))`, which is resolved with the
+ * given scale so an exported theme carries the corner radius it was designed
+ * with rather than a formula Figma cannot evaluate.
+ */
+declare function cssLengthToPx(value: string, radiusScale?: number): number | undefined;
+/** The four tokens a derived preset owns, as declarations, per mode. */
+declare function presetDeclarations(preset: DerivedPreset): {
+  light: Declarations;
+  dark: Declarations;
+};
+interface DesignTokensInput {
+  /** Named in the document, e.g. "ocean" or a studio preset's slug. */
+  name: string;
+  /** The `@theme` block of tokens.css: the raw scales. */
+  scale: Declarations;
+  /** The `:root` block of base.css. */
+  light: Declarations;
+  /** The `.dark` block of base.css. */
+  dark: Declarations;
+  /** A preset's overrides, layered over `light` and `dark`. */
+  preset?: {
+    light: Declarations;
+    dark: Declarations;
+  };
+  /** The `--radius-scale` the theme was designed at. */
+  radiusScale?: number;
+}
+/**
+ * The whole theme, as a design-tokens document.
+ *
+ * Three sets: `core` (the raw scales, the same in both modes), `light` and
+ * `dark` (the semantic colours, resolved). A designer enables `core` plus one
+ * mode, which mirrors exactly how the CSS composes.
+ */
+declare function toDesignTokens(input: DesignTokensInput): DesignTokenGroup;
+//#endregion
 //#region src/index.d.ts
 /**
  * Typed surface of the theme layer. The CSS is the implementation; these
@@ -20,5 +229,5 @@ declare const RADIUS_SCALE_PROPERTY = "--radius-scale";
 declare function isThemePreset(value: string): value is ThemePreset;
 declare function isColorMode(value: string): value is ColorMode;
 //#endregion
-export { COLOR_MODES, ColorMode, DARK_CLASS, RADIUS_SCALE_PROPERTY, THEME_ATTRIBUTE, THEME_PRESETS, ThemePreset, isColorMode, isThemePreset };
+export { COLOR_MODES, ColorMode, type ContrastCheck, DARK_CLASS, type Declarations, type DeriveOptions, type DerivedPreset, type DesignToken, type DesignTokenGroup, type DesignTokensInput, type Oklch, type PresetMode, RADIUS_SCALE_PROPERTY, type Rgb, TEXT_MINIMUM, THEME_ATTRIBUTE, THEME_PRESETS, ThemePreset, checkPreset, composite, contrastRatio, cssColourToHex, cssLengthToPx, decodeSrgb, derivePreset, encodeSrgb, foregroundFor, formatOklch, formatPreset, hexToOklch, isColorMode, isThemePreset, linearRgbToOklch, luminance, oklchToHex, oklchToLinearRgb, parseOklch, parseTokenCss, presetDeclarations, resolveColour, resolveReferences, slugify, toDesignTokens };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;cAMa;KAUD,sBAAsB;cAErB;KAED,oBAAoB;;cAGnB;;cAGA;;;;;cAMA;iBAEG,cAAc,gBAAgB,SAAS;iBAIvC,YAAY,gBAAgB,SAAS"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/colour.ts","../src/preset.ts","../src/figma.ts","../src/index.ts"],"mappings":";;;;;;;;;UASiB;EACf;EACA;EACA;;;iBAIc,WACd;EACG;EAAW;EAAW;EAAW;;;iBAkBtB,iBAAiB,WAAW,WAAW,YAAY;;iBAqBnD,UAAU,KAAK;;;;;;;;iBAWf,UAAU,YAAY,KAAK,eAAe,YAAY,MAAM;iBAQ5D,cAAc,GAAG,KAAK,GAAG;;iBASzB,cAAc,eAAe,OAAO,MAAM;;iBAU1C,WAAW,KAAK;EAAQ;EAAW;EAAW;;;iBAW9C,WAAW,WAAW,WAAW,YAAY;UAS5C;EACf;EACA;EACA;;;;;;;;;;iBAWc,iBAAiB,KAAK,MAAM;;iBAqB5B,WAAW,cAAc;iBAqBzB,aAAa,GAAG,GAAG,KAAK;;iBAOxB,cAAc,GAAG,GAAG,KAAK;;;;cC9I5B;;;;;;;;iBAiBG,cAAc,YAAY,QAAQ;UAOjC;EACf,SAAS;EACT,cAAc;EACd,eAAe;EACf,mBAAmB;;UAGJ;EACf,OAAO;EACP,MAAM;;UAGS;;;;;;;;EAQf;;iBAGc,aAAa,OAAO,OAAO,UAAS,gBAAqB;UA+BxD;EACf;EACA;EACA;EACA;;;;;;;;;iBAUc,YAAY,QAAQ,gBAAgB;;;;;;;;iBA0CpC,aAAa,cAAc,QAAQ;;iBAcnC,QAAQ;;;;;;;;;;;;;;;;;;;KCpKZ,eAAe;;UAGV;EACf;EACA;EACA;;UAGe;GACd,cAAc,cAAc;EAC7B;;;;;;;;;iBAec,cAAc,aAAa,mBAAmB;;;;;;;;;;iBA6C9C,kBAAkB,eAAe,QAAQ;;iBAsBzC,eAAe;;;;;;;;;iBAoBf,cAAc,eAAe;;iBA0B7B,mBAAmB,QAAQ;EACzC,OAAO;EACP,MAAM;;UAWS;;EAEf;;EAEA,OAAO;;EAEP,OAAO;;EAEP,MAAM;;EAEN;IAAW,OAAO;IAAc,MAAM;;;EAEtC;;;;;;;;;iBAgFc,eAAe,OAAO,oBAAoB;;;;;;;;cCvN7C;KAUD,sBAAsB;cAErB;KAED,oBAAoB;;cAGnB;;cAGA;;;;;cAMA;iBAEG,cAAc,gBAAgB,SAAS;iBAIvC,YAAY,gBAAgB,SAAS"}