tailwind-oklch 0.2.0 → 0.4.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">
 ```
 
-Examples:
+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="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="hue-accent bg-3-mhi text-10-lo border-2-mid">
+```
+
+**Three-axis: `{property}-{L}-{C}-{H}`** — sets all three axes explicitly in a single class:
+
+```html
+<div class="bg-3-mhi-accent text-fore-lo-neutral border-5-mid-primary">
 ```
 
 Available properties: `bg`, `text`, `border`, `border-b`, `accent`, `from`, `to`.
@@ -129,6 +150,40 @@ All utilities work with standard Tailwind modifiers:
 </input>
 ```
 
+### Relative Luminance Offsets
+
+Sometimes you don't want to set an absolute luminance — you want to nudge it relative to the inherited value. The `lc-up` and `lc-down` utilities shift luminance **toward more contrast** or **toward less contrast** without replacing the underlying `--bg-l` or `--tx-l` variable. This means children still inherit the original value.
+
+- **`lc-up-{N}`** — increase contrast (move away from the page color)
+- **`lc-down-{N}`** — decrease contrast (move toward the page color)
+
+Where `{N}` is 1–5, with each step equal to ~0.08 OKLCH lightness (roughly one position on the 0–10 scale).
+
+Available for `bg` and `text`:
+
+| Pattern | Effect |
+|---|---|
+| `bg-lc-up-{N}` | Background becomes more contrasting |
+| `bg-lc-down-{N}` | Background becomes less contrasting |
+| `text-lc-up-{N}` | Text becomes more contrasting |
+| `text-lc-down-{N}` | Text becomes less contrasting |
+
+The direction automatically adapts to light/dark mode — "up" always means more contrast with the page, "down" always means less, regardless of whether luminance values are increasing or decreasing.
+
+```html
+<!-- A card with a hover state one step brighter/darker than the parent -->
+<div class="bg-3-mlo-primary">
+  <button class="hover:bg-lc-up-1">Slightly more contrast on hover</button>
+  <span class="bg-lc-down-2">Subtler background, closer to page</span>
+</div>
+
+<!-- Muted secondary text that's two steps less contrasting than default -->
+<p class="text-fore-lo-neutral">
+  Primary text
+  <span class="text-lc-down-2">Secondary text</span>
+</p>
+```
+
 ### Gradients
 
 ```html
@@ -217,18 +272,48 @@ document.documentElement.style.setProperty('--hue-primary', '180');
 
 A numeric chroma scale (`c-10` through `c-95`) is also available for finer control in the decomposed utilities.
 
+### LC Adjustment Steps
+
+Used by the relative luminance offset utilities (`bg-lc-up-*`, `bg-lc-down-*`, etc.):
+
+| Step | OKLCH L offset | Approximate scale positions |
+|---|---|---|
+| `1` | 0.08 | ~1 step |
+| `2` | 0.16 | ~2 steps |
+| `3` | 0.24 | ~3 steps |
+| `4` | 0.32 | ~4 steps |
+| `5` | 0.40 | ~5 steps |
+
+Override in a `@theme` block:
+
+```css
+@theme {
+  --lc-adj-1: 0.06;   /* smaller steps */
+  --lc-adj-2: 0.12;
+}
+```
+
 ### 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

@@ -82,6 +82,14 @@
   --c-80: 0.24;
   --c-90: 0.27;
   --c-95: 0.30;
+
+  /* ── LC Adjustment Steps ───────────────────────────────────────────
+     Each step ≈ one position on the 0–10 scale (~0.08 OKLCH L). */
+  --lc-adj-1: 0.08;
+  --lc-adj-2: 0.16;
+  --lc-adj-3: 0.24;
+  --lc-adj-4: 0.32;
+  --lc-adj-5: 0.40;
 }
 
 /* ── Light-mode luminance contrast range ──────────────────────────────
@@ -89,6 +97,7 @@
    the page), 10/fore is near black (high contrast, like text). */
 
 :root:not(.dark) {
+  --lc-dir: -1;
   --lc-range-start: 0.95;
   --lc-range-end: 0.15;
 
@@ -117,6 +126,8 @@
    naturally flows to children that only set bg-lc-* or bg-c-*. */
 
 :root {
+  --lc-dir: 1;
+
   --bg-l: var(--l-5);
   --bg-c: var(--c-lo);
   --bg-h: var(--hue-primary);
@@ -150,6 +161,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-* {
@@ -167,6 +210,20 @@
   background-color: oklch(var(--bg-l) var(--bg-c) var(--bg-h));
 }
 
+/* ── Background LC Adjustments ───────────────────────────────────────
+   Nudge background luminance up (more contrast) or down (less contrast)
+   relative to the current --bg-l, without changing --bg-l itself. */
+
+@utility bg-lc-up-* {
+  --bg-l-adj: --value(--lc-adj-*);
+  background-color: oklch(clamp(0, calc(var(--bg-l) + var(--lc-dir) * var(--bg-l-adj)), 1) var(--bg-c) var(--bg-h));
+}
+
+@utility bg-lc-down-* {
+  --bg-l-adj: --value(--lc-adj-*);
+  background-color: oklch(clamp(0, calc(var(--bg-l) - var(--lc-dir) * var(--bg-l-adj)), 1) var(--bg-c) var(--bg-h));
+}
+
 /* ── Text ────────────────────────────────────────────────────────────── */
 
 @utility text-lc-* {
@@ -184,6 +241,20 @@
   color: oklch(var(--tx-l) var(--tx-c) var(--tx-h));
 }
 
+/* ── Text LC Adjustments ─────────────────────────────────────────────
+   Nudge text luminance up (more contrast) or down (less contrast)
+   relative to the current --tx-l, without changing --tx-l itself. */
+
+@utility text-lc-up-* {
+  --tx-l-adj: --value(--lc-adj-*);
+  color: oklch(clamp(0, calc(var(--tx-l) + var(--lc-dir) * var(--tx-l-adj)), 1) var(--tx-c) var(--tx-h));
+}
+
+@utility text-lc-down-* {
+  --tx-l-adj: --value(--lc-adj-*);
+  color: oklch(clamp(0, calc(var(--tx-l) - var(--lc-dir) * var(--tx-l-adj)), 1) var(--tx-c) var(--tx-h));
+}
+
 /* ── Border ──────────────────────────────────────────────────────────── */
 
 @utility border-lc-* {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwind-oklch",
-  "version": "0.2.0",
+  "version": "0.4.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,12 +1,18 @@
 /**
  * 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";
  */
@@ -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})`,