@dowel-ui/themes 0.5.0 → 0.8.0

package/src/preset.ts

@@ -0,0 +1,191 @@
+import { contrastRatio, formatOklch, oklchToLinearRgb, type Oklch } from "./colour";
+
+/**
+ * Deriving a theme preset from a single colour.
+ *
+ * A preset in this system reassigns four tokens per mode and inherits
+ * everything else, so building one is not a palette exercise — it is picking a
+ * primary and then answering three questions the shipped presets already
+ * answer: what it looks like pressed, what it looks like in dark mode, and what
+ * text can be read on it.
+ *
+ * The deltas below are read off the presets that ship. They are not arbitrary:
+ * every one of those passes the contrast audit in both modes, so starting from
+ * the same relationships means a derived preset starts somewhere that works.
+ */
+
+/** Lightness step from the base colour to its hover state, in light mode. */
+const LIGHT_HOVER_DELTA = -0.045;
+/** And to its active state, which is a press and reads as further down. */
+const LIGHT_ACTIVE_DELTA = -0.083;
+
+/**
+ * Dark mode raises lightness and drops chroma.
+ *
+ * A colour that reads as saturated on white reads as glaring on near-black, and
+ * one dark enough to sit on white disappears into the background.
+ */
+const DARK_LIGHTNESS_DELTA = 0.115;
+const DARK_CHROMA_DELTA = -0.015;
+const DARK_HOVER_DELTA = 0.045;
+const DARK_ACTIVE_DELTA = -0.045;
+
+/** The near-white the shipped presets use for text on a saturated colour. */
+const LIGHT_FOREGROUND: Oklch = { l: 0.985, c: 0.002, h: 265 };
+
+/** WCAG 2.2 AA for normal text; a button label is normal text. */
+export const TEXT_MINIMUM = 4.5;
+
+function clampLightness(value: number): number {
+  return Math.min(0.99, Math.max(0.01, value));
+}
+
+function ratio(a: Oklch, b: Oklch): number {
+  return contrastRatio(oklchToLinearRgb(a.l, a.c, a.h), oklchToLinearRgb(b.l, b.c, b.h));
+}
+
+/**
+ * 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.
+ */
+export function foregroundFor(background: Oklch): Oklch {
+  const dark: Oklch = { l: 0.155, c: 0.03, h: background.h };
+  return ratio(LIGHT_FOREGROUND, background) >= ratio(dark, background)
+    ? LIGHT_FOREGROUND
+    : dark;
+}
+
+export interface PresetMode {
+  primary: Oklch;
+  primaryHover: Oklch;
+  primaryActive: Oklch;
+  primaryForeground: Oklch;
+}
+
+export interface DerivedPreset {
+  light: PresetMode;
+  dark: PresetMode;
+}
+
+export 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;
+}
+
+export function derivePreset(input: Oklch, options: DeriveOptions = {}): DerivedPreset {
+  // Clamped on the way in as well as on the way out. Every value this returns
+  // is one it is responsible for, including the one it was handed: a preset
+  // built on pure black is not a preset anyone can use, and passing it through
+  // untouched would mean the only unusable value in the output is the one that
+  // was never checked.
+  const primary: Oklch = { ...input, l: clampLightness(input.l), c: Math.max(0, input.c) };
+
+  const light: PresetMode = {
+    primary,
+    primaryHover: { ...primary, l: clampLightness(primary.l + LIGHT_HOVER_DELTA) },
+    primaryActive: { ...primary, l: clampLightness(primary.l + LIGHT_ACTIVE_DELTA) },
+    primaryForeground: foregroundFor(primary),
+  };
+
+  const darkPrimary: Oklch = {
+    l: clampLightness(options.darkLightness ?? primary.l + DARK_LIGHTNESS_DELTA),
+    c: Math.max(0, primary.c + DARK_CHROMA_DELTA),
+    h: primary.h,
+  };
+
+  const dark: PresetMode = {
+    primary: darkPrimary,
+    primaryHover: { ...darkPrimary, l: clampLightness(darkPrimary.l + DARK_HOVER_DELTA) },
+    primaryActive: { ...darkPrimary, l: clampLightness(darkPrimary.l + DARK_ACTIVE_DELTA) },
+    primaryForeground: foregroundFor(darkPrimary),
+  };
+
+  return { light, dark };
+}
+
+export 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.
+ */
+export function checkPreset(preset: DerivedPreset): ContrastCheck[] {
+  const checks: ContrastCheck[] = [];
+
+  for (const [mode, values] of [
+    ["Light", preset.light],
+    ["Dark", preset.dark],
+  ] as const) {
+    for (const [state, background] of [
+      ["primary", values.primary],
+      ["primary-hover", values.primaryHover],
+      ["primary-active", values.primaryActive],
+    ] as const) {
+      checks.push({
+        label: `${mode}: primary-foreground on ${state}`,
+        ratio: ratio(values.primaryForeground, background),
+        minimum: TEXT_MINIMUM,
+        passes: ratio(values.primaryForeground, background) >= TEXT_MINIMUM,
+      });
+    }
+  }
+
+  return checks;
+}
+
+function block(selector: string, mode: PresetMode): string {
+  return [
+    `${selector} {`,
+    `  --primary: ${formatOklch(mode.primary)};`,
+    `  --primary-hover: ${formatOklch(mode.primaryHover)};`,
+    `  --primary-active: ${formatOklch(mode.primaryActive)};`,
+    `  --primary-foreground: ${formatOklch(mode.primaryForeground)};`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * 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.
+ */
+export function formatPreset(name: string, preset: DerivedPreset): string {
+  return [
+    `/* Theme preset: ${name}.`,
+    ` * Apply with data-theme="${name}" on the <html> element. Only the brand-carrying`,
+    ` * tokens are reassigned; every neutral, radius and motion token is inherited. */`,
+    "",
+    block(`[data-theme="${name}"]`, preset.light),
+    "",
+    block(`.dark[data-theme="${name}"]`, preset.dark),
+    "",
+  ].join("\n");
+}
+
+/** A name usable as a `data-theme` value. */
+export function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "custom";
+}

package/src/presets/blue.css

@@ -0,0 +1,30 @@
+/* Theme preset: blue.
+ * Apply with data-theme="blue" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Blue theme (MIT © 2024 Eduardo Calvo): brand
+ * oklch(0.67 0.17 257.78), brand-secondary oklch(0.59 0.21 258.02). As in every
+ * SmoothUI-derived preset, the brand is --primary and the secondary — the deep
+ * end of SmoothUI's gradients — is --primary-active.
+ *
+ * Hue 258 sits between `ocean` (232, a cyan-leaning blue) and the default
+ * (275, an indigo): this is the plain blue neither of them is. */
+
+[data-theme="blue"] {
+  /* The brand is 2.90:1 under white text and 3.03:1 as text on white. 0.555 is
+     the lightest value that clears 4.5:1 for both; hue and chroma are kept.
+     The secondary's chroma is capped at 0.175, the most sRGB holds at 0.472. */
+  --primary: oklch(0.555 0.17 257.78);
+  --primary-hover: oklch(0.51 0.17 257.78);
+  --primary-active: oklch(0.472 0.175 258.02);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="blue"] {
+  /* SmoothUI's exact values: 6.5:1 under dark text on the brand, 4.6:1 on the
+     secondary. Hover is capped at the chroma sRGB holds at 0.715. */
+  --primary: oklch(0.67 0.17 257.78);
+  --primary-hover: oklch(0.715 0.145 257.78);
+  --primary-active: oklch(0.59 0.21 258.02);
+  --primary-foreground: oklch(0.155 0.03 257.78);
+}

package/src/presets/candy.css

@@ -0,0 +1,37 @@
+/* Theme preset: candy.
+ * Apply with data-theme="candy" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Candy theme (MIT © 2024 Eduardo Calvo). Candy is two colours,
+ * not one: a pink brand, oklch(0.72 0.2 352.53), and a deeper brand-secondary,
+ * oklch(0.66 0.21 354.31), that SmoothUI uses as the far end of its gradients.
+ * Dowel has one brand colour and no gradient token, so the pair is mapped onto
+ * the states it already has: the brand is --primary, and the secondary is
+ * --primary-active — pressing moves further down the same gradient. Hover
+ * follows the brand hue. */
+
+[data-theme="candy"] {
+  /* SmoothUI's pink is 2.62:1 under white text and 2.74:1 as text on white —
+     short of 4.5:1 twice, and this token is the focus ring too. Lightness is
+     brought down to 0.58, the lightest value that clears 4.5:1 for both, with
+     hue and chroma untouched. The active state carries brand-secondary's hue
+     at the standard step down, its chroma capped at 0.2, the most sRGB holds
+     at 0.497. */
+  --primary: oklch(0.58 0.2 352.53);
+  --primary-hover: oklch(0.535 0.2 352.53);
+  --primary-active: oklch(0.497 0.2 354.31);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="candy"] {
+  /* SmoothUI's exact values. Its brand does not change between modes, and on
+     near-black both of them already carry dark text: 7.2:1 on the brand, 5.7:1
+     on the secondary. Hover is capped at chroma 0.16, the most sRGB holds at
+     that lightness. Near `rose`, but not the same colour: rose is a red at hue
+     17 and a dark primary of 0.645; candy is a cooler pink, 25° away, and far
+     brighter in dark mode. */
+  --primary: oklch(0.72 0.2 352.53);
+  --primary-hover: oklch(0.765 0.16 352.53);
+  --primary-active: oklch(0.66 0.21 354.31);
+  --primary-foreground: oklch(0.155 0.03 352.53);
+}

package/src/presets/green.css

@@ -0,0 +1,34 @@
+/* Theme preset: green.
+ * Apply with data-theme="green" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Green theme (MIT © 2024 Eduardo Calvo): brand
+ * oklch(0.7 0.15 162.48), brand-secondary oklch(0.6 0.13 163.23). As in every
+ * SmoothUI-derived preset, the brand is --primary and the secondary — the deep
+ * end of SmoothUI's gradients — is --primary-active.
+ *
+ * The closest of the six to an existing preset: `emerald` is at hue 162 too,
+ * and in light mode the two are nearly the same colour, because contrast
+ * pushes both to the same place. The difference is dark mode, where green is
+ * SmoothUI's bright mint at 0.7/0.15 and emerald a deeper 0.645/0.12. */
+
+[data-theme="green"] {
+  /* The brand is 2.39:1 under white text and 2.50:1 as text on white. 0.54 is
+     the lightest value that clears 4.5:1 for both. Green is where sRGB is
+     narrowest at that lightness: it holds 0.115 chroma, not SmoothUI's 0.15,
+     so that is what is written — the value the screen can show. Hover and
+     the secondary are capped the same way, at 0.105 and 0.095. */
+  --primary: oklch(0.54 0.115 162.48);
+  --primary-hover: oklch(0.495 0.105 162.48);
+  --primary-active: oklch(0.457 0.095 163.23);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="green"] {
+  /* SmoothUI's brand exactly: 7.8:1 under dark text. The secondary's chroma is
+     0.125, just inside sRGB where SmoothUI's 0.13 is not; 5.2:1. */
+  --primary: oklch(0.7 0.15 162.48);
+  --primary-hover: oklch(0.745 0.15 162.48);
+  --primary-active: oklch(0.6 0.125 163.23);
+  --primary-foreground: oklch(0.155 0.03 162.48);
+}

package/src/presets/index.css

@@ -5,3 +5,9 @@
 @import "./rose.css";
 @import "./amber.css";
 @import "./monochrome.css";
+@import "./candy.css";
+@import "./indigo.css";
+@import "./blue.css";
+@import "./red.css";
+@import "./orange.css";
+@import "./green.css";

package/src/presets/indigo.css

@@ -0,0 +1,36 @@
+/* Theme preset: indigo.
+ * Apply with data-theme="indigo" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Indigo theme (MIT © 2024 Eduardo Calvo): brand
+ * oklch(0.65 0.22 300.21), brand-secondary oklch(0.54 0.23 286.53). As in every
+ * SmoothUI-derived preset, the brand is --primary and the secondary — the deep
+ * end of SmoothUI's gradients — is --primary-active.
+ *
+ * Next to `violet` (hue 302), the brand hue is almost the same: SmoothUI's
+ * "indigo" is a violet in OKLCH terms, and the indigo is its secondary, 14°
+ * bluer. What separates the two presets is that pressing indigo turns to that
+ * true indigo, and that its dark mode keeps the full 0.22 chroma where violet
+ * drops to 0.175. */
+
+[data-theme="indigo"] {
+  /* The brand is 3.41:1 under white text and 3.56:1 as text on white. 0.58 is
+     the lightest value that clears 4.5:1 for both; hue and chroma are kept. */
+  --primary: oklch(0.58 0.22 300.21);
+  --primary-hover: oklch(0.535 0.22 300.21);
+  --primary-active: oklch(0.497 0.23 286.53);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="indigo"] {
+  /* The brand is SmoothUI's exact value: 5.5:1 under dark text. The secondary
+     is not. One foreground serves every state, so the pressed fill has to
+     carry the same dark text, and at 0.54 it reaches only 3.49:1. It is raised
+     to 0.605, the first lightness that clears 4.5:1, keeping its hue; its
+     chroma is capped at 0.225 and hover's at 0.185, the most sRGB holds at
+     those lightnesses. */
+  --primary: oklch(0.65 0.22 300.21);
+  --primary-hover: oklch(0.695 0.185 300.21);
+  --primary-active: oklch(0.605 0.225 286.53);
+  --primary-foreground: oklch(0.155 0.03 300.21);
+}

package/src/presets/orange.css

@@ -0,0 +1,34 @@
+/* Theme preset: orange.
+ * Apply with data-theme="orange" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Orange theme (MIT © 2024 Eduardo Calvo): brand
+ * oklch(0.75 0.17 47.65), brand-secondary oklch(0.68 0.21 40.59). As in every
+ * SmoothUI-derived preset, the brand is --primary and the secondary — the deep
+ * end of SmoothUI's gradients — is --primary-active.
+ *
+ * Not `amber`: amber sits at hue 70 and in light mode is an ochre; orange is
+ * 22° redder, and in light mode reads as a burnt orange rather than a brown. */
+
+[data-theme="orange"] {
+  /* The largest adjustment of the six. SmoothUI's orange is 2.28:1 under white
+     text and 2.38:1 as text on white; like amber, a bright orange cannot be
+     read on a light background at all. 0.565 is the lightest value that clears
+     4.5:1 for both, and at that lightness sRGB holds only 0.15 chroma, so that
+     is what is written — the value the screen can show. Hover and the
+     secondary are capped the same way, at 0.14 and 0.145. */
+  --primary: oklch(0.565 0.15 47.65);
+  --primary-hover: oklch(0.52 0.14 47.65);
+  --primary-active: oklch(0.482 0.145 40.59);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="orange"] {
+  /* SmoothUI's values, with the brand's chroma at 0.16: 0.17 is just outside
+     sRGB at this lightness. 8.4:1 under dark text on the brand, 6.3:1 on the
+     secondary. Hover is capped at the chroma sRGB holds at 0.795. */
+  --primary: oklch(0.75 0.16 47.65);
+  --primary-hover: oklch(0.795 0.125 47.65);
+  --primary-active: oklch(0.68 0.21 40.59);
+  --primary-foreground: oklch(0.155 0.03 47.65);
+}

package/src/presets/red.css

@@ -0,0 +1,33 @@
+/* Theme preset: red.
+ * Apply with data-theme="red" on the <html> element. Only the brand-carrying
+ * tokens are reassigned; every neutral, radius and motion token is inherited.
+ *
+ * From SmoothUI's Red theme (MIT © 2024 Eduardo Calvo): brand
+ * oklch(0.67 0.21 24.28), brand-secondary oklch(0.62 0.25 28.23). As in every
+ * SmoothUI-derived preset, the brand is --primary and the secondary — the deep
+ * end of SmoothUI's gradients — is --primary-active.
+ *
+ * Near `rose`, but warmer: rose sits at hue 17 and leans pink; red is at 24
+ * and presses towards 28, a vermilion. In dark mode red is also brighter and
+ * more saturated — 0.67/0.21 against rose's 0.645/0.17. Worth knowing: the
+ * brand is now close to `--destructive`, so a primary and a destructive button
+ * side by side are told apart by their labels rather than their colour. */
+
+[data-theme="red"] {
+  /* The brand is 3.16:1 under white text and 3.30:1 as text on white. 0.58 is
+     the lightest value that clears 4.5:1 for both; hue and chroma are kept.
+     The secondary's chroma is capped at 0.2, the most sRGB holds at 0.497. */
+  --primary: oklch(0.58 0.21 24.28);
+  --primary-hover: oklch(0.535 0.21 24.28);
+  --primary-active: oklch(0.497 0.2 28.23);
+  --primary-foreground: oklch(0.985 0.002 265);
+}
+
+.dark[data-theme="red"] {
+  /* SmoothUI's exact values: 6.0:1 under dark text on the brand, 4.8:1 on the
+     secondary. Hover is capped at the chroma sRGB holds at 0.715. */
+  --primary: oklch(0.67 0.21 24.28);
+  --primary-hover: oklch(0.715 0.175 24.28);
+  --primary-active: oklch(0.62 0.25 28.23);
+  --primary-foreground: oklch(0.155 0.03 24.28);
+}

package/src/tokens.css

@@ -140,6 +140,8 @@
 
   --animate-accordion-open: accordion-open var(--duration-normal) var(--ease-out-quint);
   --animate-accordion-close: accordion-close var(--duration-fast) var(--ease-in-quint);
+  --animate-collapse-down: collapse-down var(--duration-normal) var(--ease-out-quint);
+  --animate-collapse-up: collapse-up var(--duration-fast) var(--ease-in-quint);
 
   @keyframes fade-in {
     from {
@@ -242,6 +244,24 @@
     }
   }
 
+  @keyframes collapse-down {
+    from {
+      height: 0;
+    }
+    to {
+      height: var(--radix-collapsible-content-height);
+    }
+  }
+
+  @keyframes collapse-up {
+    from {
+      height: var(--radix-collapsible-content-height);
+    }
+    to {
+      height: 0;
+    }
+  }
+
   @keyframes spin {
     to {
       transform: rotate(360deg);