@handamade/psi-tokens 0.22.0 → 0.23.0

package/README.md

@@ -29,7 +29,7 @@ Then set the theme on your root element:
 
 All tokens are CSS custom properties: `--psi-bg-primary`, `--psi-fg-secondary`, `--psi-space-12`, etc.
 
-**utilities.css is required**: it carries `.psi-container`, `.psi-text-*`, `.psi-display-*` utility classes and the `prefers-reduced-motion` zeroing for all duration tokens (D30) — required for NavBar rendering and accessibility compliance.
+**utilities.css is required**: it carries `.psi-container`, `.psi-text-*`, `.psi-display-*`, `.psi-fg-*` (D94) utility classes and the `prefers-reduced-motion` zeroing for all duration tokens (D30) — required for NavBar rendering and accessibility compliance.
 
 ## Creating a custom theme
 

package/dist/guidance.json

@@ -190,7 +190,7 @@
     "radius": "Control radius is size-invariant (D56) — it does NOT ride the size ramp, because border-radius sits on each component's base rule and all four sizes resolve to radius-8. One dial, --psi-control-radius, is the layer to override, aliased per component: --psi-button-radius (Button, and IconButton via the same token), --psi-input-radius, --psi-select-radius, --psi-checkbox-box-radius, and --psi-tooltip-radius. Checkbox and Tooltip cap themselves with min(var(--psi-control-radius), var(--psi-radius-4)) and min(…, var(--psi-radius-6)) respectively so neither over-rounds a small object — but the published radius scale's floor is radius-4, so Checkbox's cap is a no-op for every on-scale value a theme can set; it only bites at an off-scale value like 0px. Tooltip's higher ceiling does track a sharper theme, down to radius-4. Tag and Switch stay --psi-radius-full: pill-ness is component identity, not theme expression. A theme retunes every control's shape by setting --psi-control-radius once. Psi now has two radius dials, not one: --psi-control-radius (here, for interactive controls) and --psi-surface-radius (for elevated surfaces — Dialog, Panel, Menu). --psi-card-radius sits on neither dial, so a theme that retunes controls or surfaces leaves Card at its own default of radius-8."
   },
   "utilities": {
-    "note": "Every utility class shipped in utilities.css, generated from the same source as the CSS (D79). Scaled utility families set one property each and create no layout context: .psi-gap-* sets gap only, so pair it with display:flex or grid yourself. The bare/fixed utilities (.psi-container, .psi-media-tint, .psi-sr-only) set several. Import @handamade/psi-tokens/utilities.css — it is required, not optional; .psi-container and the reduced-motion duration zeroing live there.",
+    "note": "Every utility class shipped in utilities.css, generated from the same source as the CSS (D79). Scaled utility families set one property each and create no layout context: .psi-gap-* sets gap only, so pair it with display:flex or grid yourself. The bare/fixed utilities (.psi-container, .psi-media-tint, .psi-sr-only) set several. Every utility sits in @layer psi.utilities, above @layer psi.components, so on a component root it beats the component's own value (D94). Import @handamade/psi-tokens/utilities.css — it is required, not optional; .psi-container and the reduced-motion duration zeroing live there.",
     "families": [
       {
         "prefix": "psi-gap-*",
@@ -486,6 +486,26 @@
           "psi-my-144"
         ]
       },
+      {
+        "prefix": "psi-fg-*",
+        "property": "color",
+        "scale": null,
+        "classes": [
+          "psi-fg-primary",
+          "psi-fg-secondary",
+          "psi-fg-tertiary",
+          "psi-fg-quaternary",
+          "psi-fg-primary-inverted",
+          "psi-fg-static-white",
+          "psi-fg-static-black",
+          "psi-fg-on-accent",
+          "psi-fg-accent",
+          "psi-fg-success",
+          "psi-fg-warning",
+          "psi-fg-danger",
+          "psi-fg-on-inverted"
+        ]
+      },
       {
         "prefix": "psi-text-*",
         "property": "font",
@@ -562,6 +582,19 @@
       "psi-display-32-32-extrabold",
       "psi-display-36-64-black",
       "psi-display-56-128-black",
+      "psi-fg-accent",
+      "psi-fg-danger",
+      "psi-fg-on-accent",
+      "psi-fg-on-inverted",
+      "psi-fg-primary",
+      "psi-fg-primary-inverted",
+      "psi-fg-quaternary",
+      "psi-fg-secondary",
+      "psi-fg-static-black",
+      "psi-fg-static-white",
+      "psi-fg-success",
+      "psi-fg-tertiary",
+      "psi-fg-warning",
       "psi-gap-0",
       "psi-gap-12",
       "psi-gap-120",

package/dist/utilities.css

@@ -121,6 +121,20 @@
   .psi-mx-144 { margin-inline: var(--psi-space-144); }
   .psi-my-144 { margin-block: var(--psi-space-144); }
 
+  .psi-fg-primary { color: var(--psi-fg-primary); }
+  .psi-fg-secondary { color: var(--psi-fg-secondary); }
+  .psi-fg-tertiary { color: var(--psi-fg-tertiary); }
+  .psi-fg-quaternary { color: var(--psi-fg-quaternary); }
+  .psi-fg-primary-inverted { color: var(--psi-fg-primary-inverted); }
+  .psi-fg-static-white { color: var(--psi-fg-static-white); }
+  .psi-fg-static-black { color: var(--psi-fg-static-black); }
+  .psi-fg-on-accent { color: var(--psi-fg-on-accent); }
+  .psi-fg-accent { color: var(--psi-fg-accent); }
+  .psi-fg-success { color: var(--psi-fg-success); }
+  .psi-fg-warning { color: var(--psi-fg-warning); }
+  .psi-fg-danger { color: var(--psi-fg-danger); }
+  .psi-fg-on-inverted { color: var(--psi-fg-on-inverted); }
+
   .psi-text-12-16-regular { font: var(--psi-text-12-16-regular); }
   .psi-text-12-16-medium { font: var(--psi-text-12-16-medium); }
   .psi-text-14-20-regular { font: var(--psi-text-14-20-regular); }

package/llms.txt

@@ -14,6 +14,7 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 - Override --psi-{component}-* tokens for one-off component theming; never fork semantic tokens.
 - Scales are pixel-true: --psi-space-8 is 8px (0.5rem). Typography: --psi-text-{size}-{lh}-{weight}.
 - Themes: import base.css + {theme}.css + components.css + utilities.css; set data-psi-theme="{name}" ({light,dark,acme,ember}).
+- Foreground utilities (D94): `.psi-fg-<role>` sets `color: var(--psi-fg-<role>)` for every fg token (`psi-fg-primary`, `psi-fg-secondary`, `psi-fg-tertiary`, `psi-fg-on-accent`, `psi-fg-danger`, …). Like every utility it sits in `@layer psi.utilities` and beats a component's own colour.
 - Scoped tokens bind only their declared property groups (D46): fg* → text properties, bg*/fill*/scrim* → surfaces, border* → borders, --psi-space-* → gaps/padding/margin. Cross-family bindings that are design decisions carry both scopes (fgDanger: text+border for error borders; fillAccent: surface+border for selected controls). The token build enforces component bindings; the repo's stylelint rule (psi/token-scopes) enforces first-party consumer CSS (component modules + apps/). External consumers aren't gated automatically — dist/scope-map.json carries the machine-readable scopes to lint against.
 
 ## Motion (--psi-duration-*, --psi-ease-*)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-tokens",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "license": "MIT",
   "type": "module",
   "exports": {