@handamade/psi-tokens 0.22.0 → 0.24.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/components/button.js

@@ -73,4 +73,16 @@ export const buttonVars = {
     "32-font": "var(--psi-control-32-font)",
     "40-font": "var(--psi-control-40-font)",
     "48-font": "var(--psi-control-48-font)",
+    // ── Icon size (D97) — a direct svg child, half the height: 12/16/20/24.
+    // Derived, not restated, so a height retuned at the root moves the icon.
+    // The calc() resolves where it is declared: a retune on a narrower scope
+    // must set the icon size there too. IconButton does not bind it.
+    "24-icon-size": "calc(var(--psi-button-24-height) / 2)",
+    "32-icon-size": "calc(var(--psi-button-32-height) / 2)",
+    "40-icon-size": "calc(var(--psi-button-40-height) / 2)",
+    "48-icon-size": "calc(var(--psi-button-48-height) / 2)",
+    // ── Label cap (D98) — off by default. A consumer sets it on its own class;
+    // it caps a label wrapped in a direct <span> and ends it in an ellipsis.
+    // Size-invariant: the surrounding layout sets the cap, not the button.
+    "label-max-width": "none",
 };

package/dist/components/button.vars.css

@@ -56,5 +56,10 @@
     --psi-button-32-font: var(--psi-control-32-font);
     --psi-button-40-font: var(--psi-control-40-font);
     --psi-button-48-font: var(--psi-control-48-font);
+    --psi-button-24-icon-size: calc(var(--psi-button-24-height) / 2);
+    --psi-button-32-icon-size: calc(var(--psi-button-32-height) / 2);
+    --psi-button-40-icon-size: calc(var(--psi-button-40-height) / 2);
+    --psi-button-48-icon-size: calc(var(--psi-button-48-height) / 2);
+    --psi-button-label-max-width: none;
   }
 }

package/dist/components/menu.js

@@ -18,4 +18,7 @@ export const menuVars = {
     "separator-border": "var(--psi-border-faint)",
     // D82 — the ring on a focused item; until then the browser drew its own.
     "focus-ring": "var(--psi-border-focus)",
+    // D99 — MenuText, a line that is not an action. fgSecondary on the menu
+    // surface (bgSecondary) is already gated at 4.5:1, so no new pair.
+    "text-fg": "var(--psi-fg-secondary)",
 };

package/dist/components/menu.vars.css

@@ -12,5 +12,6 @@
     --psi-menu-item-fg-disabled: var(--psi-fg-quaternary);
     --psi-menu-separator-border: var(--psi-border-faint);
     --psi-menu-focus-ring: var(--psi-border-focus);
+    --psi-menu-text-fg: var(--psi-fg-secondary);
   }
 }

package/dist/components.css

@@ -79,6 +79,11 @@
     --psi-button-32-font: var(--psi-control-32-font);
     --psi-button-40-font: var(--psi-control-40-font);
     --psi-button-48-font: var(--psi-control-48-font);
+    --psi-button-24-icon-size: calc(var(--psi-button-24-height) / 2);
+    --psi-button-32-icon-size: calc(var(--psi-button-32-height) / 2);
+    --psi-button-40-icon-size: calc(var(--psi-button-40-height) / 2);
+    --psi-button-48-icon-size: calc(var(--psi-button-48-height) / 2);
+    --psi-button-label-max-width: none;
   }
 }
 
@@ -226,6 +231,7 @@
     --psi-menu-item-fg-disabled: var(--psi-fg-quaternary);
     --psi-menu-separator-border: var(--psi-border-faint);
     --psi-menu-focus-ring: var(--psi-border-focus);
+    --psi-menu-text-fg: var(--psi-fg-secondary);
   }
 }
 

package/dist/guidance.json

@@ -151,6 +151,12 @@
         12,
         16
       ],
+      "iconSize": [
+        12,
+        16,
+        20,
+        24
+      ],
       "gap": [
         4,
         8,
@@ -186,11 +192,13 @@
     },
     "note": "Per-size geometry is data, not CSS literals (D54). Arrays are indexed by sizes[]. Read a value as --psi-control-{size}-{prop} for the label ramp and --psi-control-value-{size}-{prop} for the value ramp; components alias these as --psi-{component}-{size}-{prop}, which is the layer to override. The value ramp is one step tighter than the label ramp because a left-aligned value wants less air than a centred label (D55).",
     "iconInset": "A leading icon sits one step closer to the edge than text — an icon is a solid shape with no side bearing (D55). Applied by .size{n}:has(> svg:first-child) on Button. IconButton is height-only: it is square with padding 0, so no padding/gap/font token applies to it.",
+    "iconSize": "A direct svg child of a Button renders at --psi-button-{size}-icon-size, half the button's height (12/16/20/24 at 24/32/40/48), whatever the icon's own size prop: CSS width and height beat the attributes an icon writes (D97). Pass icons without a size. A wrapped icon is not sized, as it gets no inset. IconButton does not bind the ramp; its icon keeps its own size (20 by default).",
+    "labelMaxWidth": "A label wrapped in a direct <span> is capped by --psi-button-label-max-width, default none, and ends in an ellipsis past the cap (D98). Set the token on your own class; it is size-invariant. A bare text label is not capped (wrap it, as a trailing icon already requires). The full text stays the accessible name, and Psi adds no title.",
     "iconInsetLimits": "The selector matches on element order, and :first-child ignores text nodes. Two consequences. (1) An icon wrapped in a <span> never matches — fails safe, no inset; set --psi-button-{size}-padding-inline-icon yourself. (2) A TRAILING icon (<Button>Next<IconChevronRight /></Button>) makes the svg the first ELEMENT child, so the rule fires and narrows the start (text) side while the icon keeps full padding — the inverse of the intent. CSS cannot tell the two apart without a DOM signal. Put the icon first, or override --psi-button-{size}-padding-inline-icon to match --psi-button-{size}-padding-inline to disable the inset.",
     "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 +494,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 +590,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/scope-map.json

@@ -463,6 +463,9 @@
     "menu-separator-border": [
       "border"
     ],
+    "menu-text-fg": [
+      "text"
+    ],
     "navbar-bg": [
       "surface"
     ],

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.24.0",
   "license": "MIT",
   "type": "module",
   "exports": {