@handamade/psi-tokens 0.21.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/components/field.d.ts

@@ -1,3 +1,16 @@
 /** Field component tokens (--psi-field-*). Label/message/error colors alias
- * gated semantic fg tokens; gap is the label→control→message grid gap (D49). */
+ * gated semantic fg tokens; gap is the label→control→message grid gap (D49).
+ *
+ * label-height (D92) is the label's line box: the line height of
+ * --psi-text-14-20-medium, which the label's `font` shorthand sets. A font
+ * shorthand exposes no line-height variable to read, and --psi-space-* is
+ * scoped to gap/padding/margin, so the height is a standalone 20px literal
+ * (the --psi-toolbar-control-width precedent). The label holds it as its
+ * min-block-size, and --psi-toolbar-action-offset is derived from it, so a
+ * filter row's unlabelled button and its labelled controls read one source.
+ * Change it together with the label's font. --psi-toolbar-action-offset
+ * resolves from this token and `gap` at the theme root: overriding either on
+ * a narrower scope inside a Toolbar align="start" row also needs
+ * --psi-toolbar-action-offset set on that same scope, or the row's button
+ * keeps the theme-root offset. */
 export declare const fieldVars: Record<string, string>;

package/dist/components/field.js

@@ -1,5 +1,18 @@
 /** Field component tokens (--psi-field-*). Label/message/error colors alias
- * gated semantic fg tokens; gap is the label→control→message grid gap (D49). */
+ * gated semantic fg tokens; gap is the label→control→message grid gap (D49).
+ *
+ * label-height (D92) is the label's line box: the line height of
+ * --psi-text-14-20-medium, which the label's `font` shorthand sets. A font
+ * shorthand exposes no line-height variable to read, and --psi-space-* is
+ * scoped to gap/padding/margin, so the height is a standalone 20px literal
+ * (the --psi-toolbar-control-width precedent). The label holds it as its
+ * min-block-size, and --psi-toolbar-action-offset is derived from it, so a
+ * filter row's unlabelled button and its labelled controls read one source.
+ * Change it together with the label's font. --psi-toolbar-action-offset
+ * resolves from this token and `gap` at the theme root: overriding either on
+ * a narrower scope inside a Toolbar align="start" row also needs
+ * --psi-toolbar-action-offset set on that same scope, or the row's button
+ * keeps the theme-root offset. */
 export const fieldVars = {
     "label-fg": "var(--psi-fg-secondary)",
     "message-fg": "var(--psi-fg-tertiary)",
@@ -11,4 +24,5 @@ export const fieldVars = {
     // foreground the contrast matrix does not gate.
     "required-text-fg": "var(--psi-fg-secondary)",
     gap: "var(--psi-space-6)",
+    "label-height": "20px",
 };

package/dist/components/field.vars.css

@@ -6,5 +6,6 @@
     --psi-field-marker-fg: var(--psi-fg-danger);
     --psi-field-required-text-fg: var(--psi-fg-secondary);
     --psi-field-gap: var(--psi-space-6);
+    --psi-field-label-height: 20px;
   }
 }

package/dist/components/toolbar.d.ts

@@ -9,5 +9,15 @@
  * Dialog's width={400|560|720} precedent — no shared scale reaches this
  * range (sizeScale tops at 48, spacingScale at 144, both for heights/gaps
  * not component widths).
+ *
+ * action-offset (D92) moves an unlabelled button or link onto the control
+ * line of a `Toolbar align="start"` row: a Field's control starts one label
+ * line and one field gap below the Field's top. It is derived from Field's
+ * own tokens rather than restated, so the two cannot drift. The calc()
+ * resolves where it is declared, `:where(:root, [data-psi-theme])`: retuning
+ * --psi-field-label-height or --psi-field-gap there moves the button too;
+ * retuning either on a narrower scope needs this token set on that scope.
+ * Bound to margin-block-start in toolbar.module.css (Toolbar CSS may read
+ * only --psi-toolbar-* and the scales, so it reads Field through this).
  */
 export declare const toolbarVars: Record<string, string>;

package/dist/components/toolbar.js

@@ -9,7 +9,18 @@
  * Dialog's width={400|560|720} precedent — no shared scale reaches this
  * range (sizeScale tops at 48, spacingScale at 144, both for heights/gaps
  * not component widths).
+ *
+ * action-offset (D92) moves an unlabelled button or link onto the control
+ * line of a `Toolbar align="start"` row: a Field's control starts one label
+ * line and one field gap below the Field's top. It is derived from Field's
+ * own tokens rather than restated, so the two cannot drift. The calc()
+ * resolves where it is declared, `:where(:root, [data-psi-theme])`: retuning
+ * --psi-field-label-height or --psi-field-gap there moves the button too;
+ * retuning either on a narrower scope needs this token set on that scope.
+ * Bound to margin-block-start in toolbar.module.css (Toolbar CSS may read
+ * only --psi-toolbar-* and the scales, so it reads Field through this).
  */
 export const toolbarVars = {
     "control-width": "200px",
+    "action-offset": "calc(var(--psi-field-label-height) + var(--psi-field-gap))",
 };

package/dist/components/toolbar.vars.css

@@ -1,5 +1,6 @@
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-toolbar-control-width: 200px;
+    --psi-toolbar-action-offset: calc(var(--psi-field-label-height) + var(--psi-field-gap));
   }
 }

package/dist/components.css

@@ -158,6 +158,7 @@
     --psi-field-marker-fg: var(--psi-fg-danger);
     --psi-field-required-text-fg: var(--psi-fg-secondary);
     --psi-field-gap: var(--psi-space-6);
+    --psi-field-label-height: 20px;
   }
 }
 
@@ -407,6 +408,7 @@
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-toolbar-control-width: 200px;
+    --psi-toolbar-action-offset: calc(var(--psi-field-label-height) + var(--psi-field-gap));
   }
 }
 

package/dist/guidance.json

@@ -54,7 +54,7 @@
     "Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.",
     "--psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).",
     "Wrap labeled form controls in Field — label association, description/error line, aria-describedby and aria-invalid come wired; don't hand-roll label+message rows.",
-    "Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"end\" of Fields (D87).",
+    "Field is for a control with a *visible* label. A toolbar filter control named by aria-label or placeholder takes neither a Field nor a hand-rolled label row — compare filter-toolbar (no labels) with table-pagination (\"Rows per page\" visible, so Field). Filters with visible labels submitted together by a Find button are filter-form: a Toolbar as=\"form\" align=\"start\" of Fields with one-line labels, where a field's error line is the Field's own and hangs below its control (D87, D92).",
     "Use Dialog for blocking modal flows — title/footer slots, dismissible gate; danger stays on the footer Buttons, one accent per group."
   ],
   "states": {
@@ -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.21.0",
+  "version": "0.23.0",
   "license": "MIT",
   "type": "module",
   "exports": {