@marianmeres/design-tokens 1.9.0 → 1.10.0

package/AGENTS.md

@@ -102,10 +102,11 @@ Entry points:
 2. Token naming: `--{prefix}color-{key}`, `--{prefix}color-{key}-hover`, etc.
 3. Prefix is auto-normalized — `"my"` and `"my-"` both produce `--my-color-*`. Empty string produces unprefixed.
 4. Hover/active auto-derived via `color-mix(in oklab, ...)` with a per-bucket strategy: **intent** colors (saturated brand) mix toward `black` / `white` 10%/20% (mode-aware); **role** colors (paired + single) mix toward `var(--{prefix}color-foreground)` 10%/20% for a softer, theme-tinted shift. `oklab` (rectangular) is used rather than `oklch` (polar) because polar hue interpolation collapses to a powerless hue on low-chroma colors mixed toward black/white, painting as a red/mauve shift on near-neutral themes. Disable with `deriveStates: false`.
-5. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background. Foreground contrast defaults to 50% — tune via `surfaceForegroundContrast`.
+5. Surface-intent tokens derived via `color-mix(in srgb, ...)` from intent + background. Foreground contrast defaults to 50% — tune via `surfaceForegroundContrast`. Note `surface-{intent}-border` mixes the intent color 30% **toward `background`** — it is the *outer* edge of an intent-tinted surface seen against the page, **not** an inner divider drawn on top of a surface.
 6. Theme files use `export default` with `ThemeSchema` type annotation. All bundled themes include an optional `surface-1` paired role (extra elevation).
 7. Formatting: tabs, 90-char line width, 4-space indent width (`deno fmt`)
 8. MCP handlers must return `Promise<string>` — framework contract from `jsr:@marianmeres/mcp-server/types`.
+9. **Layering semantics for dividers/hairlines**: `border` is calibrated against the **page background / muted** layer (≈ background + one step) and is hand-authored per theme — it may deliberately equal a `surface` step (e.g. dark themes where `border` == `surface` == the same neutral), so it is **not** a safe divider drawn *on top of* a `surface`. For an on-surface hairline/divider use `surface-1` (one curated step from `surface` in both modes). There is intentionally no dedicated `surface-border` token — `surface-1` covers the case, and the name would collide with the outer-edge meaning of `surface-{intent}-border` (see #5).
 
 ## Adding a New Theme
 

package/API.md

@@ -333,7 +333,7 @@ Required paired role keys.
 type RolePairedOptionalKey = "surface-1";
 ```
 
-Optional paired role keys. Conventional but not required — all bundled themes define `surface-1` as an additional elevation layer. Additional arbitrary string keys are also allowed.
+Optional paired role keys. Conventional but not required — all bundled themes define `surface-1` as an additional elevation layer. It also serves as the correct **hairline/divider color for content drawn _on_ a `surface`**: it sits one curated step from `surface` in both light and dark, so it always contrasts — unlike `border`, which is calibrated against the page background and can equal a surface step in dark mode. Additional arbitrary string keys are also allowed.
 
 ---
 
@@ -343,6 +343,10 @@ Optional paired role keys. Conventional but not required — all bundled themes
 type RoleSingleKey = "foreground" | "border" | "input" | "ring";
 ```
 
+Required single-value role keys.
+
+> **`border` is calibrated against the page background / muted layer** (≈ background + one step) and is hand-tuned per theme. It may deliberately coincide with a `surface` step — in several dark themes `border` and `surface` are the same neutral — so it is **not** a reliable divider when drawn _on top of_ a `surface`. Use `border` to outline a card _against_ the page; use [`surface-1`](#rolepairedoptionalkey) for a hairline/divider _on_ a surface. (Note: `surface-{intent}-border` is a separate generated token — the _outer_ edge of an intent-tinted surface seen against the background, not an on-surface divider.)
+
 ---
 
 ### `WithRequired` / `WithOptional` / `WithKnown`

package/README.md

@@ -37,11 +37,19 @@ const theme: ThemeSchema = {
 					background: { DEFAULT: "#ffffff", foreground: "#171717" },
 					muted: { DEFAULT: "#f5f5f5", foreground: "#737373" },
 					surface: { DEFAULT: "#e5e5e5", foreground: "#171717" },
-					// Optional extra elevation (all bundled themes include it):
+					// Optional extra elevation (all bundled themes include it).
+					// Also the correct hairline/divider color for content drawn
+					// *on* a surface — it sits one step from `surface` in both
+					// light and dark, so it always contrasts (unlike `border`).
 					"surface-1": { DEFAULT: "#d4d4d4", foreground: "#171717" },
 				},
 				single: {
 					foreground: "#171717",
+					// Hairline calibrated against the page background / muted
+					// layer. It may deliberately coincide with a `surface` step
+					// (in several dark themes `border` == `surface`), so use it to
+					// outline a card *against* the page — not as a divider drawn
+					// *on* a surface. Use `surface-1` for on-surface dividers.
 					border: { DEFAULT: "#d4d4d4" },
 					input: { DEFAULT: "#ffffff" },
 					ring: "color-mix(in srgb, #2563eb 25%, transparent)",

package/dist/css/red-sky-slate.css

@@ -7,7 +7,7 @@
 	--stuic-color-primary-foreground-hover:       #ffffff;
 	--stuic-color-primary-foreground-active:      #ffffff;
 
-	--stuic-color-accent:                         #38bdf8;
+	--stuic-color-accent:                         #0ea5e9;
 	--stuic-color-accent-hover:                   color-mix(in oklab, var(--stuic-color-accent), black 10%);
 	--stuic-color-accent-active:                  color-mix(in oklab, var(--stuic-color-accent), black 20%);
 	--stuic-color-accent-foreground:              #ffffff;
@@ -103,7 +103,7 @@
 	--stuic-color-primary-foreground-hover:       #ffffff;
 	--stuic-color-primary-foreground-active:      #ffffff;
 
-	--stuic-color-accent:                         #38bdf8;
+	--stuic-color-accent:                         #0284c7;
 	--stuic-color-accent-hover:                   color-mix(in oklab, var(--stuic-color-accent), white 10%);
 	--stuic-color-accent-active:                  color-mix(in oklab, var(--stuic-color-accent), white 20%);
 	--stuic-color-accent-foreground:              #ffffff;

package/dist/themes/red-sky-slate.js

@@ -7,7 +7,7 @@ const light = {
                 foreground: colors.white,
             },
             accent: {
-                DEFAULT: colors.sky[400],
+                DEFAULT: colors.sky[500],
                 foreground: colors.white,
             },
             destructive: {
@@ -64,7 +64,7 @@ const dark = {
                 foreground: colors.white,
             },
             accent: {
-                DEFAULT: colors.sky[400],
+                DEFAULT: colors.sky[600],
                 foreground: colors.white,
             },
             destructive: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/design-tokens",
-	"version": "1.9.0",
+	"version": "1.10.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",