tailwind-oklch 0.3.0 → 0.5.0

package/README.md

@@ -74,20 +74,41 @@ Set one axis at a time. The other two axes inherit from the parent or the root d
 
 The same pattern applies to `border-b-*` (border-bottom), `accent-*`, `from-*` (gradient from), `to-*` (gradient to), and `shadow-*`.
 
-### Shorthand Utilities (all axes at once)
+### Global Hue and Chroma
 
-The plugin generates shorthands that set all three axes in a single class:
+Most of the time, every color property on an element shares the same hue — the differences are in lightness and chroma. The `hue-*` utility sets the hue for **all** color properties at once:
 
+```html
+<!-- Set hue once, vary L and C per property -->
+<div class="hue-danger bg-1-mid text-10-lo border-3-mhi">
+  <button class="bg-5-mhi text-0-lo">Acknowledge</button>
+  <button class="bg-5-mhi text-10-lo">Cancel</button>
+</div>
 ```
-{property}-{L}-{C}-{H}
+
+`chroma-*` does the same for chroma:
+
+```html
+<!-- Everything low-chroma -->
+<div class="hue-primary chroma-lo bg-lc-1 text-lc-fore border-lc-3">
+```
+
+Per-property utilities (`bg-h-*`, `text-c-*`, etc.) still work as overrides when you need one property to differ.
+
+### Shorthand Utilities
+
+The plugin generates shorthands for common combinations:
+
+**Two-axis: `{property}-{L}-{C}`** — sets luminance and chroma, inherits hue from the cascade (set by `hue-*` or `:root` default):
+
+```html
+<div class="hue-accent bg-3-mhi text-10-lo border-2-mid">
 ```
 
-Examples:
+**Three-axis: `{property}-{L}-{C}-{H}`** — sets all three axes explicitly in a single class:
 
 ```html
-<div class="bg-3-mhi-accent">          <!-- L=3, C=medium-high, H=accent -->
-<p class="text-fore-lo-neutral">       <!-- L=foreground, C=low, H=neutral -->
-<div class="border-5-mid-primary">     <!-- L=5, C=medium, H=primary -->
+<div class="bg-3-mhi-accent text-fore-lo-neutral border-5-mid-primary">
 ```
 
 Available properties: `bg`, `text`, `border`, `border-b`, `accent`, `from`, `to`.
@@ -274,16 +295,25 @@ Override in a `@theme` block:
 
 ### Supported Properties
 
-| Prefix | CSS Property | Decomposed | Shorthand |
-|---|---|---|---|
-| `bg` | `background-color` | `bg-lc-*`, `bg-c-*`, `bg-h-*` | `bg-{L}-{C}-{H}` |
-| `text` | `color` | `text-lc-*`, `text-c-*`, `text-h-*` | `text-{L}-{C}-{H}` |
-| `border` | `border-color` | `border-lc-*`, `border-c-*`, `border-h-*` | `border-{L}-{C}-{H}` |
-| `border-b` | `border-bottom-color` | `border-b-lc-*`, `border-b-c-*`, `border-b-h-*` | `border-b-{L}-{C}-{H}` |
-| `accent` | `accent-color` | `accent-lc-*`, `accent-c-*`, `accent-h-*` | `accent-{L}-{C}-{H}` |
-| `from` | gradient from | `from-lc-*`, `from-c-*`, `from-h-*` | `from-{L}-{C}-{H}` |
-| `to` | gradient to | `to-lc-*`, `to-c-*`, `to-h-*` | `to-{L}-{C}-{H}` |
-| `shadow` | shadow color | `shadow-lc-*`, `shadow-c-*`, `shadow-h-*` | — |
+**Global context setters** (set all properties at once):
+
+| Utility | Sets |
+|---|---|
+| `hue-{H}` | Hue for all properties (`--bg-h`, `--tx-h`, `--bd-h`, etc.) |
+| `chroma-{C}` | Chroma for all properties (`--bg-c`, `--tx-c`, `--bd-c`, etc.) |
+
+**Per-property utilities:**
+
+| Prefix | CSS Property | Decomposed | 2-axis Shorthand | 3-axis Shorthand |
+|---|---|---|---|---|
+| `bg` | `background-color` | `bg-lc-*`, `bg-c-*`, `bg-h-*` | `bg-{L}-{C}` | `bg-{L}-{C}-{H}` |
+| `text` | `color` | `text-lc-*`, `text-c-*`, `text-h-*` | `text-{L}-{C}` | `text-{L}-{C}-{H}` |
+| `border` | `border-color` | `border-lc-*`, `border-c-*`, `border-h-*` | `border-{L}-{C}` | `border-{L}-{C}-{H}` |
+| `border-b` | `border-bottom-color` | `border-b-lc-*`, `border-b-c-*`, `border-b-h-*` | `border-b-{L}-{C}` | `border-b-{L}-{C}-{H}` |
+| `accent` | `accent-color` | `accent-lc-*`, `accent-c-*`, `accent-h-*` | `accent-{L}-{C}` | `accent-{L}-{C}-{H}` |
+| `from` | gradient from | `from-lc-*`, `from-c-*`, `from-h-*` | `from-{L}-{C}` | `from-{L}-{C}-{H}` |
+| `to` | gradient to | `to-lc-*`, `to-c-*`, `to-h-*` | `to-{L}-{C}` | `to-{L}-{C}-{H}` |
+| `shadow` | shadow color | `shadow-lc-*`, `shadow-c-*`, `shadow-h-*` | — | — |
 
 ### Light / Dark Mode
 

package/index.css

@@ -98,6 +98,7 @@
 
 :root:not(.dark) {
   --lc-dir: -1;
+  --lc-flip: 0;
   --lc-range-start: 0.95;
   --lc-range-end: 0.15;
 
@@ -127,6 +128,7 @@
 
 :root {
   --lc-dir: 1;
+  --lc-flip: 1;
 
   --bg-l: var(--l-5);
   --bg-c: var(--c-lo);
@@ -161,6 +163,38 @@
   --bdb-h: var(--hue-primary);
 }
 
+/* ── Global Hue ─────────────────────────────────────────────────────────
+   Set the hue for ALL color properties at once. Per-property hue
+   utilities (bg-h-*, text-h-*, etc.) still work as overrides.
+   Usage: hue-primary, hue-accent, hue-danger, etc. */
+
+@utility hue-* {
+  --bg-h: --value(--hue-*);
+  --tx-h: --value(--hue-*);
+  --bd-h: --value(--hue-*);
+  --bdb-h: --value(--hue-*);
+  --ac-h: --value(--hue-*);
+  --gf-h: --value(--hue-*);
+  --gt-h: --value(--hue-*);
+  --sh-h: --value(--hue-*);
+}
+
+/* ── Global Chroma ──────────────────────────────────────────────────────
+   Set the chroma for ALL color properties at once. Per-property chroma
+   utilities (bg-c-*, text-c-*, etc.) still work as overrides.
+   Usage: chroma-lo, chroma-mid, chroma-hi, etc. */
+
+@utility chroma-* {
+  --bg-c: --value(--c-*);
+  --tx-c: --value(--c-*);
+  --bd-c: --value(--c-*);
+  --bdb-c: --value(--c-*);
+  --ac-c: --value(--c-*);
+  --gf-c: --value(--c-*);
+  --gt-c: --value(--c-*);
+  --sh-c: --value(--c-*);
+}
+
 /* ── Background ──────────────────────────────────────────────────────── */
 
 @utility bg-lc-* {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwind-oklch",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "OKLCH color composition system for Tailwind CSS v4",
   "style": "index.css",
   "main": "index.css",
@@ -12,9 +12,6 @@
     "index.css",
     "plugin.js"
   ],
-  "scripts": {
-    "format": "oxfmt --write \"demo/src/**/*.{ts,tsx,js,mjs}\" \"demo/astro.config.mjs\""
-  },
   "peerDependencies": {
     "tailwindcss": ">=4.0.0"
   },
@@ -27,5 +24,8 @@
   "license": "MIT",
   "devDependencies": {
     "oxfmt": "^0.32.0"
+  },
+  "scripts": {
+    "format": "oxfmt --write \"demo/src/**/*.{ts,tsx,js,mjs}\" \"demo/astro.config.mjs\""
   }
-}
+}

package/plugin.js

@@ -1,17 +1,23 @@
 /**
  * tailwind-oklch shorthand generator
  *
- * Generates .{prop}-{L}-{C}-{H} utilities for all combinations of
- * the 0–10 luminance contrast scale × chroma × hue stops across bg/text/border.
+ * Generates two kinds of shorthand utilities:
  *
- * Each shorthand sets the three axis variables AND applies the
- * resolved color, so children can inherit and override single axes
- * via decomposed utilities (e.g. hover:bg-lc-8).
+ * Three-axis: .{prop}-{L}-{C}-{H}  — sets all three axes explicitly
+ *   e.g. bg-3-mhi-accent
+ *
+ * Two-axis:   .{prop}-{L}-{C}      — sets L and C, inherits H from
+ *   the cascade (set by hue-* or :root default)
+ *   e.g. bg-3-mhi (pair with hue-accent on a parent)
+ *
+ * Each shorthand sets the axis variables AND applies the resolved
+ * color, so children can inherit and override single axes via
+ * decomposed utilities (e.g. hover:bg-lc-8).
  *
  * Load via: @plugin "tailwind-oklch/plugin";
  */
 
-module.exports = function ({ addUtilities }) {
+module.exports = function ({ addUtilities, matchUtilities }) {
   const luminances = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'base', 'fore', 'none', 'full'];
   const chromas = ['lo', 'mlo', 'mid', 'mhi', 'hi'];
   const hues = ['primary', 'accent', 'success', 'warning', 'danger', 'info', 'neutral'];
@@ -28,8 +34,16 @@ module.exports = function ({ addUtilities }) {
   const utilities = {};
 
   for (const prop of properties) {
+    // Two-axis shorthands: .{prop}-{L}-{C} — inherits H from cascade
     for (const l of luminances) {
       for (const c of chromas) {
+        utilities[`.${prop.prefix}-${l}-${c}`] = {
+          [prop.vars[0]]: `var(--l-${l})`,
+          [prop.vars[1]]: `var(--c-${c})`,
+          [prop.css]: `oklch(var(${prop.vars[0]}) var(${prop.vars[1]}) var(${prop.vars[2]}))`,
+        };
+
+        // Three-axis shorthands: .{prop}-{L}-{C}-{H}
         for (const h of hues) {
           utilities[`.${prop.prefix}-${l}-${c}-${h}`] = {
             [prop.vars[0]]: `var(--l-${l})`,
@@ -48,6 +62,21 @@ module.exports = function ({ addUtilities }) {
 
   for (const l of luminances) {
     for (const c of chromas) {
+      // Two-axis gradient shorthands — inherit H from cascade
+      utilities[`.from-${l}-${c}`] = {
+        '--gf-l': `var(--l-${l})`,
+        '--gf-c': `var(--c-${c})`,
+        '--tw-gradient-from': `oklch(var(--gf-l) var(--gf-c) var(--gf-h))`,
+        '--tw-gradient-stops': stopsExpr,
+      };
+      utilities[`.to-${l}-${c}`] = {
+        '--gt-l': `var(--l-${l})`,
+        '--gt-c': `var(--c-${c})`,
+        '--tw-gradient-to': `oklch(var(--gt-l) var(--gt-c) var(--gt-h))`,
+        '--tw-gradient-stops': stopsExpr,
+      };
+
+      // Three-axis gradient shorthands
       for (const h of hues) {
         utilities[`.from-${l}-${c}-${h}`] = {
           '--gf-l': `var(--l-${l})`,
@@ -68,4 +97,174 @@ module.exports = function ({ addUtilities }) {
   }
 
   addUtilities(utilities);
+
+  // ── Arbitrary hue values ────────────────────────────────────────────────
+  // hue-[180] → sets all hue properties to 180 (degrees).
+  // bg-h-[280] → sets only background hue to 280.
+
+  const hueVars = ['--bg-h', '--tx-h', '--bd-h', '--bdb-h', '--ac-h', '--gf-h', '--gt-h', '--sh-h'];
+
+  matchUtilities(
+    {
+      hue: (value) => Object.fromEntries(hueVars.map((v) => [v, value])),
+    },
+    { type: ['integer'] },
+  );
+
+  for (const prop of properties) {
+    matchUtilities(
+      {
+        [`${prop.prefix}-h`]: (value) => ({
+          [prop.vars[2]]: value,
+          [prop.css]: `oklch(var(${prop.vars[0]}) var(${prop.vars[1]}) var(${prop.vars[2]}))`,
+        }),
+      },
+      { type: ['integer'] },
+    );
+  }
+
+  // Gradient from/to arbitrary hue
+  matchUtilities(
+    {
+      'from-h': (value) => ({
+        '--gf-h': value,
+        '--tw-gradient-from': 'oklch(var(--gf-l) var(--gf-c) var(--gf-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+      'to-h': (value) => ({
+        '--gt-h': value,
+        '--tw-gradient-to': 'oklch(var(--gt-l) var(--gt-c) var(--gt-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+    },
+    { type: ['integer'] },
+  );
+
+  // Shadow arbitrary hue
+  matchUtilities(
+    {
+      'shadow-h': (value) => ({
+        '--sh-h': value,
+        '--tw-shadow-color': 'oklch(var(--sh-l) var(--sh-c) var(--sh-h))',
+      }),
+    },
+    { type: ['integer'] },
+  );
+
+  // ── Arbitrary chroma values ───────────────────────────────────────────
+  // chroma-[15] → sets all chroma properties to 0.15.
+  // bg-c-[20] → sets only background chroma to 0.20.
+
+  const chromaVars = ['--bg-c', '--tx-c', '--bd-c', '--bdb-c', '--ac-c', '--gf-c', '--gt-c', '--sh-c'];
+
+  const chromaValue = (value) => {
+    const v = Number(value) / 100;
+    return `${Math.round(v * 1e6) / 1e6}`;
+  };
+
+  matchUtilities(
+    {
+      chroma: (value) => {
+        const c = chromaValue(value);
+        return Object.fromEntries(chromaVars.map((v) => [v, c]));
+      },
+    },
+    { type: ['integer'] },
+  );
+
+  for (const prop of properties) {
+    matchUtilities(
+      {
+        [`${prop.prefix}-c`]: (value) => ({
+          [prop.vars[1]]: chromaValue(value),
+          [prop.css]: `oklch(var(${prop.vars[0]}) var(${prop.vars[1]}) var(${prop.vars[2]}))`,
+        }),
+      },
+      { type: ['integer'] },
+    );
+  }
+
+  // Gradient from/to arbitrary chroma
+  matchUtilities(
+    {
+      'from-c': (value) => ({
+        '--gf-c': chromaValue(value),
+        '--tw-gradient-from': 'oklch(var(--gf-l) var(--gf-c) var(--gf-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+      'to-c': (value) => ({
+        '--gt-c': chromaValue(value),
+        '--tw-gradient-to': 'oklch(var(--gt-l) var(--gt-c) var(--gt-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+    },
+    { type: ['integer'] },
+  );
+
+  // Shadow arbitrary chroma
+  matchUtilities(
+    {
+      'shadow-c': (value) => ({
+        '--sh-c': chromaValue(value),
+        '--tw-shadow-color': 'oklch(var(--sh-l) var(--sh-c) var(--sh-h))',
+      }),
+    },
+    { type: ['integer'] },
+  );
+
+  // ── Auto-flip luminance for arbitrary values ──────────────────────────
+  // bg-lc-[60] → light mode L=0.60, dark mode L=0.40 (simple 1−x flip).
+  // Uses --lc-flip (0 in light, 1 in dark) so the transform is pure CSS.
+  // Formula: L = v + flip × (1 − 2v)  where v = input / 100
+  //   flip=0 → v   (light: use value as-is)
+  //   flip=1 → 1−v (dark: reflect around 0.5)
+
+  const lcFlipValue = (value) => {
+    const v = Number(value) / 100;
+    const delta = 1 - 2 * v;
+    // Round to avoid floating-point noise in the CSS output
+    const vR = Math.round(v * 1e6) / 1e6;
+    const dR = Math.round(delta * 1e6) / 1e6;
+    return `calc(${vR} + var(--lc-flip) * ${dR})`;
+  };
+
+  for (const prop of properties) {
+    matchUtilities(
+      {
+        [`${prop.prefix}-lc`]: (value) => ({
+          [prop.vars[0]]: lcFlipValue(value),
+          [prop.css]: `oklch(var(${prop.vars[0]}) var(${prop.vars[1]}) var(${prop.vars[2]}))`,
+        }),
+      },
+      { type: ['integer'] },
+    );
+  }
+
+  // Gradient from/to auto-flip luminance
+  matchUtilities(
+    {
+      'from-lc': (value) => ({
+        '--gf-l': lcFlipValue(value),
+        '--tw-gradient-from': 'oklch(var(--gf-l) var(--gf-c) var(--gf-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+      'to-lc': (value) => ({
+        '--gt-l': lcFlipValue(value),
+        '--tw-gradient-to': 'oklch(var(--gt-l) var(--gt-c) var(--gt-h))',
+        '--tw-gradient-stops': stopsExpr,
+      }),
+    },
+    { type: ['integer'] },
+  );
+
+  // Shadow auto-flip luminance
+  matchUtilities(
+    {
+      'shadow-lc': (value) => ({
+        '--sh-l': lcFlipValue(value),
+        '--tw-shadow-color': 'oklch(var(--sh-l) var(--sh-c) var(--sh-h))',
+      }),
+    },
+    { type: ['integer'] },
+  );
 };