@vegastack/design-tokens 0.1.0 → 0.4.0

package/dist/utilities.css

@@ -51,12 +51,18 @@
       --scroll-fade-t: 0px;
     }
     to {
-      --scroll-fade-t: var(--_scroll-fade-size-t, var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10))));
+      --scroll-fade-t: var(
+        --_scroll-fade-size-t,
+        var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10)))
+      );
     }
   }
   @keyframes scroll-fade-reveal-b {
     from {
-      --scroll-fade-b: var(--_scroll-fade-size-b, var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10))));
+      --scroll-fade-b: var(
+        --_scroll-fade-size-b,
+        var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10)))
+      );
     }
     to {
       --scroll-fade-b: 0px;
@@ -67,12 +73,18 @@
       --scroll-fade-s: 0px;
     }
     to {
-      --scroll-fade-s: var(--_scroll-fade-size-s, var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10))));
+      --scroll-fade-s: var(
+        --_scroll-fade-size-s,
+        var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10)))
+      );
     }
   }
   @keyframes scroll-fade-reveal-e {
     from {
-      --scroll-fade-e: var(--_scroll-fade-size-e, var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10))));
+      --scroll-fade-e: var(
+        --_scroll-fade-size-e,
+        var(--scroll-fade-size, min(12%, calc(var(--spacing) * 10)))
+      );
     }
     to {
       --scroll-fade-e: 0px;
@@ -553,7 +565,6 @@
   }
 }
 
-
 /* ---------------------------------------------------------------------------
  * scrollbar-* — minimal native scrollbar helpers (VegaStack addition; not in
  * upstream shadcn tailwind.css). Used by message-scroller's viewport.
@@ -573,7 +584,6 @@
   scrollbar-gutter: stable;
 }
 
-
 /* ---------------------------------------------------------------------------
  * motion-* — the state-feedback animation vocabulary (VegaStack addition,
  * Phase M). Mount-triggered CSS animations for the "keyed presence" mechanism:
@@ -586,9 +596,18 @@
  *                         (the "success bounce" — spring ease, tiny overshoot).
  *   - motion-enter-up   : fade+rise arrival for content (chat messages,
  *                         skeleton→content reveal).
+ *   - motion-flash      : highlight-on-change ring pulse (live updates); color
+ *                         via --vs-flash-color, defaults to `ring`.
  *   - motion-shake      : horizontal error jiggle. Replayable: re-trigger by
  *                         remounting (key bump) or toggling the class after
  *                         `animationend`.
+ *   - motion-indeterminate : the ONE sanctioned looping utility — the sweeping
+ *                         segment of an indeterminate Progress. Looping motion is
+ *                         otherwise banned; an indeterminate bar has no other way
+ *                         to say "still working" (audit M-06).
+ *
+ * `motion-dock-in` / `motion-dock-out` below are the one PAIR in this family and
+ * the one that is not keyed presence — see their own header.
  * ------------------------------------------------------------------------- */
 @keyframes vs-pop-in {
   from {
@@ -643,70 +662,135 @@
   animation: vs-shake var(--duration-slow) var(--motion-ease-standard);
 }
 
+@keyframes vs-flash {
+  /* Highlight-on-change ring pulse (Wave 1, Attio record-flash adaptation):
+   * a 2px ring in the component's own accent (defaults to `ring`) swells and
+   * settles. End state = rest, so the base.css reduced-motion collapse renders
+   * it invisible. Override the color per call-site via `--vs-flash-color`
+   * (e.g. `[--vs-flash-color:var(--info)]` on a live-updating row). */
+  0% {
+    box-shadow: 0 0 0 0 transparent;
+  }
+  50% {
+    box-shadow: 0 0 0 2px var(--vs-flash-color, var(--ring));
+  }
+  to {
+    box-shadow: 0 0 0 0 transparent;
+  }
+}
+
+@utility motion-flash {
+  animation: vs-flash var(--duration-slow) var(--motion-ease-standard);
+}
+
+@keyframes vs-indeterminate {
+  /* Indeterminate progress (audit M-06, 2026-09-07): a 35%-wide segment sweeps the
+   * track and returns. The 0% and 100% stops are IDENTICAL on purpose — the global
+   * prefers-reduced-motion reset in base.css collapses every animation to its `to`
+   * state, so a reduced-motion user sees a static 35% segment resting at the start
+   * of the track instead of a bar that reads as 100% complete. */
+  0% {
+    inset-inline-start: 0%;
+  }
+  50% {
+    inset-inline-start: 65%;
+  }
+  100% {
+    inset-inline-start: 0%;
+  }
+}
+
+@utility motion-indeterminate {
+  animation: vs-indeterminate var(--duration-indeterminate)
+    var(--motion-ease-standard) infinite;
+}
+
 /* ---------------------------------------------------------------------------
- * .vs-marketing — the marketing dark-ground SCOPE MECHANISM (Phase B, audit
- * 17-brand-direction §Color & surface, CX-10). Marketing surfaces (hero,
- * section bands, the Terminal primitive) render the warm ramp's DARK end
- * regardless of the page/product theme — `.dark` alone can't express "product
- * light + marketing dark on the SAME page," which is exactly the co-existing
- * case this class exists for (docs-home is light by default but its hero is
- * dark-first). Any subtree wrapped in `.vs-marketing` (see the
- * `MarketingSurface` primitive, and `Terminal`, which self-scopes) gets the
- * same semantic custom properties `.dark` sets, scoped LOCALLY instead of
- * gated on the page-root class — every `bg-background` / `text-foreground` /
- * `border-border` / `bg-brand` utility inside it resolves through these, with
- * NO component code changes (any existing token-built component composes
- * correctly, since only the custom-property VALUES change, never the
- * utility-to-var wiring).
+ * motion-dock-in / motion-dock-out — the docked-control enter/exit pair
+ * (audit D11 amendment #7, 2026-09-07).
  *
- * Values are a RATIONED, MANUALLY-SYNCED duplicate of the resolved oklch()
- * output of `packages/design-tokens/tokens/semantic.dark.tokens.json` (the same
- * values `.dark` sets) — the same "one sanctioned literal duplication"
- * precedent as the `overlay` scrim token in that file. The principled fix is
- * a THIRD generated Style Dictionary platform run in `build-tokens.mjs`
- * (source `semantic.dark.tokens.json`, selector `.vs-marketing` instead of
- * `.dark`) so this can never drift silently — that's a tokens-BUILD-PIPELINE
- * change outside this component-level addition; flagged for whoever owns
- * `packages/design-tokens/build-tokens.mjs` next. If `semantic.dark.tokens.json`
- * changes, update this block to match (or land the generated version).
+ * A docked control — a bottom action bar, a floating scroll-to-end button —
+ * stays MOUNTED and flips a `data-active` attribute, so its motion is a
+ * transition, not a keyed animation. That is why this is a pair rather than one
+ * `@utility`: the two states carry different timing, which is the whole point.
  *
- * LIMITATION (documented, not fixed here): Base UI floating surfaces portal
- * to `<body>`, OUTSIDE this scoped subtree — a popover/tooltip/menu/dialog
- * opened from inside a `.vs-marketing` surface renders with the PAGE theme,
- * not the marketing dark ground. Marketing surfaces rarely need portals (a
- * hero/section band is not app chrome); the docs-home dogfood doesn't use one.
+ * The doctrine these encode: **an exit is never slower than its enter.** Both
+ * bars previously entered at `duration-base` and left at `duration-slow` with a
+ * `scale-95`, so dismissing one took half again as long as summoning it and the
+ * bar shrank as it went. Vercel, Linear and Base UI's own defaults all leave at
+ * or faster than they arrive. Enter is 150ms `emphasized`; exit is 100ms `exit`;
+ * a docked bar translates and fades and does not scale — scale reads as a popup,
+ * and a bar sliding off its own edge does not need it.
+ *
+ * 100ms has exactly one role in the system — this exit — so it lives here, in
+ * the utility that names it, rather than becoming a fifth global duration token
+ * that would invite reuse D11 did not sanction.
+ *
+ * These own the timing, the fade and the inert-while-hidden guard. The DISTANCE
+ * stays at the call site as ordinary `translate-*` utilities, because it is
+ * per-dock geometry (a bottom bar clears its own height plus the safe-area
+ * inset; an edge button clears 100%) and because Tailwind composes `translate-x`
+ * and `translate-y` through custom properties that a `translate:` declaration
+ * here would clobber — a horizontally-centred bar would lose its centring.
+ *
+ * The global prefers-reduced-motion reset in base.css collapses both to 0.01ms.
+ *
+ *   <div data-active={open}
+ *        className="data-[active=true]:motion-dock-in  data-[active=true]:translate-y-0
+ *                   data-[active=false]:motion-dock-out data-[active=false]:translate-y-full" />
  * ------------------------------------------------------------------------- */
-.vs-marketing {
-  color-scheme: dark;
-
-  --background: oklch(0.175 0.003 75);
-  --foreground: oklch(0.922 0.003 75);
-  --card: oklch(0.205 0.003 75);
-  --card-foreground: oklch(0.922 0.003 75);
-  --popover: oklch(0.205 0.003 75);
-  --popover-foreground: oklch(0.922 0.003 75);
-
-  --primary: oklch(0.922 0.003 75);
-  --primary-foreground: oklch(0.145 0.003 75);
-  --primary-hover: oklch(0.97 0.003 75);
-  --primary-active: oklch(0.994 0.002 75);
-
-  --secondary: oklch(0.269 0.003 75);
-  --secondary-foreground: oklch(0.922 0.003 75);
-  --muted: oklch(0.269 0.003 75);
-  --muted-foreground: oklch(0.66 0.003 75);
-  --muted-foreground-faint: oklch(0.559 0.003 75);
-  --accent: oklch(0.269 0.003 75);
-  --accent-foreground: oklch(0.967 0.003 75);
-
-  --border: oklch(0.269 0.003 75);
-  --input: var(--border);
-  --ring: var(--primary);
-  --overlay: oklch(0 0 0 / 0.55);
-
-  /* Brand phosphor — DARK half (13.3:1 on this ground, MK's pick), independent
-     of whether `.dark` is present anywhere in the ancestor chain. Marker roles
-     only (live-state dot, sparkline endpoint, eyebrow highlight, terminal
-     prompt glyph) — see design.md §Brand & Marketing. */
-  --brand: oklch(0.86 0.21 148);
+@utility motion-dock-in {
+  transition-property: translate, opacity;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: var(--motion-ease-emphasized);
+  opacity: 1;
 }
+
+@utility motion-dock-out {
+  transition-property: translate, opacity;
+  transition-duration: 100ms;
+  transition-timing-function: var(--motion-ease-exit);
+  opacity: 0;
+  /* A docked-out control is off-screen: it must not swallow clicks on the way
+     out, and it must not be a hit target while parked. */
+  pointer-events: none;
+}
+
+/* ---------------------------------------------------------------------------
+ * BrandIcon theme-aware artwork swap (`<BrandIcon variant="auto">`).
+ *
+ * Single-colour brands ship artwork that only reads on ONE surface — GitHub's
+ * brand mark is #181717, invisible on a dark canvas. `thesvg` therefore ships
+ * `light` (dark ink, FOR light surfaces) and `dark` (white ink, FOR dark
+ * surfaces) variants; `auto` renders both and lets CSS reveal the right one.
+ *
+ * These are plain attribute selectors, NOT Tailwind utilities, on purpose:
+ * `@vegastack/design` is a published package, and a consumer's Tailwind build
+ * does not scan our `src`. A `dark:` utility authored inside the package would
+ * silently never be generated downstream (it wasn't generated in our own docs
+ * either — see the dead `packages/icons` @source). Shipping the rules in the
+ * stylesheet consumers already import makes the swap work everywhere.
+ *
+ * `.vs-marketing` is included so a brand mark inside the marketing dark ground
+ * picks the dark artwork even while the page theme is light.
+ * ------------------------------------------------------------------------- */
+[data-brand-artwork="light"] {
+  display: contents;
+}
+[data-brand-artwork="dark"] {
+  display: none;
+}
+.dark [data-brand-artwork="light"],
+.vs-marketing [data-brand-artwork="light"] {
+  display: none;
+}
+.dark [data-brand-artwork="dark"],
+.vs-marketing [data-brand-artwork="dark"] {
+  display: contents;
+}
+
+/* `.vs-marketing`'s semantic variables and `color-scheme: dark` now live in
+ * generated theme.css. build-tokens.mjs emits the scope from the SAME resolved
+ * Style Dictionary dark run as `.dark`, and verify-theme-parity.mjs rejects any
+ * variable-set or value drift. The artwork selectors above remain here because
+ * they are presentation behavior, not token data. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design-tokens",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "VegaStack design tokens (DTCG → Tailwind v4 theme + TS)",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,9 @@
     "url": "git+https://github.com/VegaStack/vegastack-design.git",
     "directory": "packages/design-tokens"
   },
+  "engines": {
+    "node": ">=24.14.0"
+  },
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -18,25 +21,27 @@
   "exports": {
     ".": {
       "types": "./dist/tokens.d.ts",
-      "import": "./dist/tokens.js"
+      "import": "./dist/tokens.js",
+      "require": "./dist/tokens.cjs",
+      "default": "./dist/tokens.js"
     },
     "./theme.css": "./dist/theme.css",
     "./base.css": "./dist/base.css",
     "./utilities.css": "./dist/utilities.css",
-    "./tokens.json": "./dist/tokens.json"
+    "./tokens.json": "./dist/tokens.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node build-tokens.mjs && node ../../tooling/contrast-check.mjs dist/theme.css && tsup src/tokens.ts --format esm,cjs --dts --out-dir dist",
+    "lint": "node ../../tooling/verify-theme-parity.mjs dist/theme.css && node ../../tooling/contrast-check.mjs dist/theme.css && node ../../tooling/design-lint.mjs --token-css src",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "style-dictionary": "5.5.0",
-    "typescript": "^6.0.3",
-    "@vegastack/typescript-config": "0.0.0"
+    "@vegastack/typescript-config": "workspace:*",
+    "style-dictionary": "5.5.2",
+    "typescript": "catalog:"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
-  },
-  "scripts": {
-    "build": "node build-tokens.mjs && node ../../tooling/contrast-check.mjs dist/theme.css && tsup src/tokens.ts --format esm --dts --out-dir dist",
-    "lint": "node ../../tooling/contrast-check.mjs dist/theme.css && node ../../tooling/design-lint.mjs --token-css src",
-    "typecheck": "tsc --noEmit"
+    "access": "public"
   }
-}
+}