@handamade/psi-tokens 0.3.0

package/dist/utilities.css

@@ -0,0 +1,169 @@
+@layer psi.utilities {
+  .psi-gap-0 { gap: var(--psi-space-0); }
+  .psi-gap-2 { gap: var(--psi-space-2); }
+  .psi-gap-4 { gap: var(--psi-space-4); }
+  .psi-gap-6 { gap: var(--psi-space-6); }
+  .psi-gap-8 { gap: var(--psi-space-8); }
+  .psi-gap-12 { gap: var(--psi-space-12); }
+  .psi-gap-16 { gap: var(--psi-space-16); }
+  .psi-gap-20 { gap: var(--psi-space-20); }
+  .psi-gap-24 { gap: var(--psi-space-24); }
+  .psi-gap-32 { gap: var(--psi-space-32); }
+  .psi-gap-40 { gap: var(--psi-space-40); }
+  .psi-gap-48 { gap: var(--psi-space-48); }
+  .psi-gap-64 { gap: var(--psi-space-64); }
+  .psi-gap-80 { gap: var(--psi-space-80); }
+  .psi-gap-96 { gap: var(--psi-space-96); }
+  .psi-gap-120 { gap: var(--psi-space-120); }
+  .psi-gap-144 { gap: var(--psi-space-144); }
+
+  .psi-p-0 { padding: var(--psi-space-0); }
+  .psi-px-0 { padding-inline: var(--psi-space-0); }
+  .psi-py-0 { padding-block: var(--psi-space-0); }
+  .psi-p-2 { padding: var(--psi-space-2); }
+  .psi-px-2 { padding-inline: var(--psi-space-2); }
+  .psi-py-2 { padding-block: var(--psi-space-2); }
+  .psi-p-4 { padding: var(--psi-space-4); }
+  .psi-px-4 { padding-inline: var(--psi-space-4); }
+  .psi-py-4 { padding-block: var(--psi-space-4); }
+  .psi-p-6 { padding: var(--psi-space-6); }
+  .psi-px-6 { padding-inline: var(--psi-space-6); }
+  .psi-py-6 { padding-block: var(--psi-space-6); }
+  .psi-p-8 { padding: var(--psi-space-8); }
+  .psi-px-8 { padding-inline: var(--psi-space-8); }
+  .psi-py-8 { padding-block: var(--psi-space-8); }
+  .psi-p-12 { padding: var(--psi-space-12); }
+  .psi-px-12 { padding-inline: var(--psi-space-12); }
+  .psi-py-12 { padding-block: var(--psi-space-12); }
+  .psi-p-16 { padding: var(--psi-space-16); }
+  .psi-px-16 { padding-inline: var(--psi-space-16); }
+  .psi-py-16 { padding-block: var(--psi-space-16); }
+  .psi-p-20 { padding: var(--psi-space-20); }
+  .psi-px-20 { padding-inline: var(--psi-space-20); }
+  .psi-py-20 { padding-block: var(--psi-space-20); }
+  .psi-p-24 { padding: var(--psi-space-24); }
+  .psi-px-24 { padding-inline: var(--psi-space-24); }
+  .psi-py-24 { padding-block: var(--psi-space-24); }
+  .psi-p-32 { padding: var(--psi-space-32); }
+  .psi-px-32 { padding-inline: var(--psi-space-32); }
+  .psi-py-32 { padding-block: var(--psi-space-32); }
+  .psi-p-40 { padding: var(--psi-space-40); }
+  .psi-px-40 { padding-inline: var(--psi-space-40); }
+  .psi-py-40 { padding-block: var(--psi-space-40); }
+  .psi-p-48 { padding: var(--psi-space-48); }
+  .psi-px-48 { padding-inline: var(--psi-space-48); }
+  .psi-py-48 { padding-block: var(--psi-space-48); }
+  .psi-p-64 { padding: var(--psi-space-64); }
+  .psi-px-64 { padding-inline: var(--psi-space-64); }
+  .psi-py-64 { padding-block: var(--psi-space-64); }
+  .psi-p-80 { padding: var(--psi-space-80); }
+  .psi-px-80 { padding-inline: var(--psi-space-80); }
+  .psi-py-80 { padding-block: var(--psi-space-80); }
+  .psi-p-96 { padding: var(--psi-space-96); }
+  .psi-px-96 { padding-inline: var(--psi-space-96); }
+  .psi-py-96 { padding-block: var(--psi-space-96); }
+  .psi-p-120 { padding: var(--psi-space-120); }
+  .psi-px-120 { padding-inline: var(--psi-space-120); }
+  .psi-py-120 { padding-block: var(--psi-space-120); }
+  .psi-p-144 { padding: var(--psi-space-144); }
+  .psi-px-144 { padding-inline: var(--psi-space-144); }
+  .psi-py-144 { padding-block: var(--psi-space-144); }
+
+  .psi-m-0 { margin: var(--psi-space-0); }
+  .psi-mx-0 { margin-inline: var(--psi-space-0); }
+  .psi-my-0 { margin-block: var(--psi-space-0); }
+  .psi-m-2 { margin: var(--psi-space-2); }
+  .psi-mx-2 { margin-inline: var(--psi-space-2); }
+  .psi-my-2 { margin-block: var(--psi-space-2); }
+  .psi-m-4 { margin: var(--psi-space-4); }
+  .psi-mx-4 { margin-inline: var(--psi-space-4); }
+  .psi-my-4 { margin-block: var(--psi-space-4); }
+  .psi-m-6 { margin: var(--psi-space-6); }
+  .psi-mx-6 { margin-inline: var(--psi-space-6); }
+  .psi-my-6 { margin-block: var(--psi-space-6); }
+  .psi-m-8 { margin: var(--psi-space-8); }
+  .psi-mx-8 { margin-inline: var(--psi-space-8); }
+  .psi-my-8 { margin-block: var(--psi-space-8); }
+  .psi-m-12 { margin: var(--psi-space-12); }
+  .psi-mx-12 { margin-inline: var(--psi-space-12); }
+  .psi-my-12 { margin-block: var(--psi-space-12); }
+  .psi-m-16 { margin: var(--psi-space-16); }
+  .psi-mx-16 { margin-inline: var(--psi-space-16); }
+  .psi-my-16 { margin-block: var(--psi-space-16); }
+  .psi-m-20 { margin: var(--psi-space-20); }
+  .psi-mx-20 { margin-inline: var(--psi-space-20); }
+  .psi-my-20 { margin-block: var(--psi-space-20); }
+  .psi-m-24 { margin: var(--psi-space-24); }
+  .psi-mx-24 { margin-inline: var(--psi-space-24); }
+  .psi-my-24 { margin-block: var(--psi-space-24); }
+  .psi-m-32 { margin: var(--psi-space-32); }
+  .psi-mx-32 { margin-inline: var(--psi-space-32); }
+  .psi-my-32 { margin-block: var(--psi-space-32); }
+  .psi-m-40 { margin: var(--psi-space-40); }
+  .psi-mx-40 { margin-inline: var(--psi-space-40); }
+  .psi-my-40 { margin-block: var(--psi-space-40); }
+  .psi-m-48 { margin: var(--psi-space-48); }
+  .psi-mx-48 { margin-inline: var(--psi-space-48); }
+  .psi-my-48 { margin-block: var(--psi-space-48); }
+  .psi-m-64 { margin: var(--psi-space-64); }
+  .psi-mx-64 { margin-inline: var(--psi-space-64); }
+  .psi-my-64 { margin-block: var(--psi-space-64); }
+  .psi-m-80 { margin: var(--psi-space-80); }
+  .psi-mx-80 { margin-inline: var(--psi-space-80); }
+  .psi-my-80 { margin-block: var(--psi-space-80); }
+  .psi-m-96 { margin: var(--psi-space-96); }
+  .psi-mx-96 { margin-inline: var(--psi-space-96); }
+  .psi-my-96 { margin-block: var(--psi-space-96); }
+  .psi-m-120 { margin: var(--psi-space-120); }
+  .psi-mx-120 { margin-inline: var(--psi-space-120); }
+  .psi-my-120 { margin-block: var(--psi-space-120); }
+  .psi-m-144 { margin: var(--psi-space-144); }
+  .psi-mx-144 { margin-inline: var(--psi-space-144); }
+  .psi-my-144 { margin-block: var(--psi-space-144); }
+
+  .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); }
+  .psi-text-14-20-medium { font: var(--psi-text-14-20-medium); }
+  .psi-text-16-20-regular { font: var(--psi-text-16-20-regular); }
+  .psi-text-16-24-regular { font: var(--psi-text-16-24-regular); }
+  .psi-text-16-24-medium { font: var(--psi-text-16-24-medium); }
+  .psi-text-18-28-medium { font: var(--psi-text-18-28-medium); }
+  .psi-text-20-28-semibold { font: var(--psi-text-20-28-semibold); }
+  .psi-text-24-32-medium { font: var(--psi-text-24-32-medium); }
+  .psi-text-30-36-bold { font: var(--psi-text-30-36-bold); }
+  .psi-text-serif-18-28-regular { font: var(--psi-text-serif-18-28-regular); }
+  .psi-text-serif-20-30-regular { font: var(--psi-text-serif-20-30-regular); }
+  .psi-text-serif-20-32-regular { font: var(--psi-text-serif-20-32-regular); }
+  .psi-text-serif-24-36-regular { font: var(--psi-text-serif-24-36-regular); }
+  .psi-text-serif-28-40-regular { font: var(--psi-text-serif-28-40-regular); }
+  .psi-text-mono-13-20-regular { font: var(--psi-text-mono-13-20-regular); }
+  .psi-text-mono-14-20-regular { font: var(--psi-text-mono-14-20-regular); }
+  .psi-text-mono-15-24-regular { font: var(--psi-text-mono-15-24-regular); }
+  .psi-text-mono-15-24-medium { font: var(--psi-text-mono-15-24-medium); }
+
+  .psi-display-56-128-black { font: var(--psi-display-56-128-black); letter-spacing: -0.02em; text-transform: uppercase; }
+  .psi-display-36-64-black { font: var(--psi-display-36-64-black); letter-spacing: -0.02em; text-transform: uppercase; }
+  .psi-display-32-32-extrabold { font: var(--psi-display-32-32-extrabold); letter-spacing: -0.01em; text-transform: uppercase; }
+
+  .psi-container { max-width: var(--psi-container-max); margin-inline: auto; padding-inline: var(--psi-gutter); }
+  /* Gutter narrows under md — breakpoint baked at build time (D31). */
+  @media (max-width: 960px) {
+    :root { --psi-gutter: 1.5rem; }
+  }
+
+  .psi-media-tint { filter: var(--psi-media-tint); transition: filter var(--psi-duration-450) var(--psi-ease-soft); }
+  .psi-media-tint:hover, .psi-media-tint:focus-visible { filter: none; }
+
+  /* Reduced motion (D30): zero every duration token; anything driven by
+     --psi-duration-* complies for free. psi.utilities wins over psi.base. */
+  @media (prefers-reduced-motion: reduce) {
+    :root {
+      --psi-duration-150: 0.01ms;
+      --psi-duration-200: 0.01ms;
+      --psi-duration-350: 0.01ms;
+      --psi-duration-450: 0.01ms;
+      --psi-duration-600: 0.01ms;
+    }
+  }
+}

package/llms.txt

@@ -0,0 +1,46 @@
+# @handamade/psi-tokens
+
+OKLCH formula-based design tokens. Code is the source of truth; all artifacts generated.
+
+## Machine-readable artifacts
+- dist/resolved/{light,dark,acme,ember}.json: every token with OKLCH, hex, and derivation formula
+- dist/guidance.json: variant intent, usage rules, state derivation, typography defaults, motion/layout/fonts notes, recipes
+- dist/dtcg/{theme}.json: W3C DTCG format export
+- dist/components/{name}.vars.css: component-token declarations (--psi-{component}-*)
+
+## Rules for generated code
+- Use semantic tokens (--psi-bg-*, --psi-fg-*, --psi-fill-*, --psi-border-*) in app CSS.
+- 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}).
+
+## Motion (--psi-duration-*, --psi-ease-*)
+- Durations: 150/200/350/450/600ms. Easings: --psi-ease-standard, --psi-ease-in-out, --psi-ease-soft.
+- Always drive transitions/animations with duration/ease tokens; never hardcode times or curves.
+- Under prefers-reduced-motion, all --psi-duration-* zero out (D30) — no per-component opt-out needed.
+
+## Layout (--psi-container-max, --psi-gutter, --psi-z-*)
+- .psi-container: max-width 1312px, gutter 40px stepping to 24px under the md breakpoint.
+- --psi-z-nav (100), --psi-z-overlay (1000), --psi-z-tooltip (1100).
+- Breakpoints (sm 560 / md 960) are build-time constants (D31), not CSS vars: `import { breakpoints } from "@handamade/psi-tokens/types"` for any @media-driven JS/CSS-in-JS.
+
+## Typography: display, serif, mono
+- Fluid display tier: --psi-display-{min}-{max}-{weight} (e.g. --psi-display-56-128-black), clamp-based and pixel-true at both endpoints; pair with the matching .psi-display-* utility class for tracking/uppercase.
+- Serif and mono are first-class combo roles alongside sans: --psi-text-serif-{size}-{lh}-{weight} and --psi-text-mono-{size}-{lh}-{weight}, same naming shape as the sans scale.
+
+## Scrims and borders
+- --psi-scrim-soft/medium/heavy: bgPrimary-derived translucent overlays (0.25/0.35/0.82 alpha) for text-over-media legibility.
+- --psi-border-faint: low-contrast hairline border (fgPrimary at 0.08 alpha), used by Card/NavBar and other bordered surfaces.
+
+## Media tint (--psi-media-tint, .psi-media-tint)
+- --psi-media-tint is a brand-defined filter chain (D35); apply the .psi-media-tint utility class to media elements to get a tinted-at-rest, true-color-on-hover/focus treatment, transitioning over --psi-duration-450 / --psi-ease-soft.
+
+## Dark-first brands
+- A brand theme can declare `base: "dark"` (see ember) so its formulas derive from the dark palette instead of light — use this for brands whose primary surface is a dark canvas rather than treating dark as an inverted afterthought.
+
+## Brand fonts (D29)
+- Font roles (sans/serif/mono/display) are brand-level. The DS ships no font files — consumers load each brand's webfonts themselves (e.g. ember: Archivo for display/sans, IBM Plex Serif/Mono).
+- Brand font stacks fully apply when data-psi-theme is set on the root <html> element. In nested subtree theming, --psi-text-*/--psi-display-* combos keep the default stacks, since unregistered custom properties only substitute at :root.
+
+## Component overrides (D34)
+- A brand's theme file may declare `componentOverrides: Record<string, string>` (e.g. ember: button-font → mono, card-radius → 0, media-tint → its filter chain), emitted in the brand's own theme file (e.g. dist/ember.css) inside `@layer psi.components`. Prefer this over forking a component's CSS Module for brand-specific token values.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@handamade/psi-tokens",
+  "version": "0.3.0",
+  "type": "module",
+  "exports": {
+    "./*.css": "./dist/*.css",
+    "./components/*": "./dist/components/*",
+    "./resolved/*": "./dist/resolved/*",
+    "./dtcg/*": "./dist/dtcg/*",
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./guidance.json": "./dist/guidance.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt"
+  ],
+  "dependencies": {
+    "culori": "^4.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.ts",
+    "dev": "tsx --watch scripts/build.ts --watch",
+    "new-theme": "tsx scripts/new-theme.ts"
+  }
+}