synthesisui 0.16.25 → 0.16.27

package/dist/claude-md.js

@@ -290,6 +290,13 @@ against their own, so the last one written wins, which is what the call site rea
 If an override is ignored, that component predates the resolver: regenerate it with
 \`npx synthesisui@latest component <slug> <name>\` rather than reaching for \`!\`.
 
+**Motion is selection, not improvisation.** The base is quiet: nothing moves until a person
+asks. When they do, pick from the **Motion vocabulary** in GUIDE.md - \`animate-<name>\`
+utilities already compiled on this system's clock - and never hand-roll \`@keyframes\` or raw
+durations. A motion the vocabulary lacks is a gap like any other: file it (\`request_token\`
+MCP tool, or \`npx synthesisui@latest request\`) and say what you chose from the vocabulary
+instead.
+
 Only write something new when nothing in the manifest covers the purpose - and when you do,
 say which entry you considered and why it did not fit, then FILE it while the reasoning is
 still yours: the \`request_component\` MCP tool, or \`npx synthesisui@latest request component

package/dist/commands/doctor.js

@@ -191,6 +191,7 @@ const KIND_LABEL = {
     radius: "radius",
     spacing: "spacing",
     font: "type",
+    motion: "motion",
 };
 /** "1 file", "2 files" - a report that says "1 files read" on its very first
  *  line spends credibility before it has said anything. */

package/dist/doctor/scan.js

@@ -59,6 +59,28 @@ const RADIUS = new RegExp(`(?:border-?[Rr]adius\\s*:\\s*${OPEN}|rounded(?:-[a-z]
 const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem)`, "g");
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
+/**
+ * MOTION, the family the scan never read (item 12, F3).
+ *
+ * A transition or animation declaration carrying a literal clock - `300ms`,
+ * `.2s`, a hand-tuned `cubic-bezier` - is timing decided outside the system,
+ * exactly like a hex outside the palette. Anchored to the property so a
+ * number elsewhere on the line (a scale factor, a z-index) is never read as
+ * time; the value normalizer makes `.3s` and `300ms` one literal, so the
+ * system's own duration token gets NAMED, not just flagged.
+ */
+const MOTION_PROP = /\b(?:transition|animation)(?:-(?:duration|delay|timing-function)|Duration|Delay|TimingFunction)?\s*:\s*["'`]?([^;}"'`\n]*)/g;
+const TIME_LITERAL = /(\d*\.?\d+)(ms|s)\b/g;
+const BEZIER = /cubic-bezier\([^)]*\)/g;
+/** `duration-300`, `duration-[350ms]`, `delay-75` - Tailwind's stock clock. */
+const TW_TIME = /\b(?:duration|delay)-(?:\[([^\]]+)\]|(\d+)\b)/g;
+const TW_EASE = /\bease-\[([^\]]+)\]/g;
+/** `animate-fade-up`, `animate-[wiggle_1s_ease]` - checked against the
+ *  installed vocabulary, so only when the system ships one. */
+const ANIMATE_UTIL = /\banimate-(\[[^\]]+\]|[a-z0-9-]+)/g;
+/** tailwindcss-animate's grammar (the shadcn bridge): `animate-in`/`-out` are
+ *  composable micro-transition idiom, not a keyframe selection to police. */
+const ANIMATE_IDIOM = new Set(["none", "in", "out"]);
 /**
  * Uses of the system. Coverage is meaningless without them.
  *
@@ -308,6 +330,61 @@ export function scanSource(file, source, table) {
                 continue;
             push("font", stack);
         }
+        for (const m of line.matchAll(MOTION_PROP)) {
+            const value = m[1];
+            const base = (m.index ?? 0) + m[0].length - value.length;
+            for (const t of value.matchAll(TIME_LITERAL)) {
+                // `0s` is idiom (disabling a transition), not a clock chosen by hand.
+                if (Number.parseFloat(t[1]) === 0)
+                    continue;
+                push("motion", `${t[1]}${t[2]}`, base + (t.index ?? 0));
+            }
+            for (const b of value.matchAll(BEZIER)) {
+                push("motion", b[0], base + (b.index ?? 0));
+            }
+            // A `ds-*` animation name that the installed css never declares renders
+            // as NOTHING, silently - the keyframe cousin of a phantom token.
+            if (table.keyframes.size > 0) {
+                for (const w of value.matchAll(/\b(ds-[a-z0-9-]+)\b/g)) {
+                    if (!table.keyframes.has(w[1]))
+                        phantoms.push({ name: `@keyframes ${w[1]}`, line: at });
+                }
+            }
+        }
+        for (const m of line.matchAll(TW_TIME)) {
+            const literal = m[1] ?? `${m[2]}ms`;
+            // `duration-[var(--ds-motion-durations-base)]` is the token being USED.
+            if (literal.startsWith("var("))
+                continue;
+            if (Number.parseFloat(literal) === 0)
+                continue;
+            push("motion", literal, m.index ?? -1);
+        }
+        for (const m of line.matchAll(TW_EASE)) {
+            if (m[1].startsWith("var("))
+                continue;
+            push("motion", m[1], m.index ?? -1);
+        }
+        // Vocabulary checks exist only when there is a vocabulary: a system that
+        // ships no keyframes left nothing to select from, and silence is honest.
+        if (table.keyframes.size > 0 && table.slug) {
+            const scope = `ds-${table.slug}-`;
+            const vocabulary = new Set([...table.keyframes]
+                .filter((k) => k.startsWith(scope))
+                .map((k) => k.slice(scope.length)));
+            for (const m of line.matchAll(ANIMATE_UTIL)) {
+                const name = m[1];
+                if (name.startsWith("[")) {
+                    // An arbitrary animation is a whole hand-rolled shorthand in a
+                    // class - improvisation by definition once a vocabulary exists.
+                    push("motion", `animate-${name}`, m.index ?? -1);
+                    continue;
+                }
+                if (ANIMATE_IDIOM.has(name) || vocabulary.has(name))
+                    continue;
+                push("motion", `animate-${name}`, m.index ?? -1);
+            }
+        }
     });
     return {
         file,
@@ -328,6 +405,7 @@ export function diagnose(files) {
         radius: 0,
         spacing: 0,
         font: 0,
+        motion: 0,
     };
     for (const f of flat)
         counts[f.kind] += 1;

package/dist/doctor/tokens.js

@@ -19,6 +19,7 @@ export const EMPTY_TABLE = {
     byName: new Map(),
     byValue: new Map(),
     declared: new Set(),
+    keyframes: new Set(),
 };
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
     .toString(16)
@@ -91,6 +92,14 @@ function args(body) {
  */
 export function normalizeValue(raw) {
     const v = raw.trim().toLowerCase().replace(/\s+/g, " ");
+    // Time lands on milliseconds: `.3s`, `0.3s` and `300ms` are one value, the
+    // same way every colour lands on 8-digit hex. Without this, a system that
+    // authors `--ds-motion-durations-base: 0.3s` never names an author's `300ms`.
+    const time = /^(\d*\.?\d+)(ms|s)$/.exec(v);
+    if (time) {
+        const ms = Number.parseFloat(time[1]) * (time[2] === "s" ? 1000 : 1);
+        return `${ms}ms`;
+    }
     const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])?$/.exec(v);
     if (short) {
         const d = (c) => c + c;
@@ -369,6 +378,7 @@ export function buildTable(input) {
         byName,
         byValue,
         declared: parseDeclaredNames(input.css),
+        keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };
 }
 /**
@@ -433,6 +443,7 @@ const FAMILY = {
     radius: "--ds-radius-",
     spacing: "--ds-spacing-",
     font: "--ds-typography-",
+    motion: "--ds-motion-",
 };
 export function tokenFor(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal));

package/dist/guide.js

@@ -1,4 +1,5 @@
 import { nextFontSnippet } from "./fonts.js";
+import { animationShorthand, classifyKeyframe, describeKeyframe, isFullRotation, } from "./motion.js";
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 const list = (items) => items.length ? items.map((i) => `\`${i}\``).join(", ") : "_(none)_";
 const dataAttrs = (variants) => Object.entries(variants).map(([axis, opts]) => `data-${kebab(axis)}="${Object.keys(opts).join("|")}"`);
@@ -136,6 +137,25 @@ ${depLines.join("\n")}
     const hasTailwind = "theme.css" in payload.artifacts;
     const hasParts = Object.values(components).some((r) => r.parts && Object.keys(r.parts).length > 0);
     const componentLines = Object.entries(components).map(([cname, recipe]) => componentEntry(cname, recipe));
+    // Motion vocabulary: the system's keyframes, named and usable. Intent is
+    // classified from the frames (same logic that compiled the animate-*
+    // utilities into theme.css), so what this section PROMISES about a utility's
+    // clock is what the CSS actually does.
+    const INTENT_LINE = {
+        entrance: "entrance · runs once on mount",
+        exit: "exit · runs once, before removal",
+        loop: "ambient loop · infinite - decorative, use sparingly",
+        attention: "attention · one shot, only when asked",
+    };
+    const keyframeLines = Object.entries(motion.keyframes).map(([kname, frames]) => {
+        const kf = frames;
+        const intent = classifyKeyframe(kname, kf);
+        const usage = hasTailwind
+            ? `\`animate-${kebab(kname)}\``
+            : `\`animation: ${animationShorthand(`ds-${slug}-${kebab(kname)}`, intent, isFullRotation(kf))}\``;
+        return `- ${usage} - ${INTENT_LINE[intent]} (${describeKeyframe(kf)})`;
+    });
+    const patternLines = Object.entries(motion.patterns ?? {}).map(([pname, p]) => `- **${pname}** (on ${p.trigger}): ${p.description}`);
     // Engagement blocks (gamification library) - category apart from core components.
     const blockEntries = Object.entries(doc.blocks ?? {});
     const blockLines = blockEntries.map(([bname, recipe]) => componentEntry(bname, recipe));
@@ -365,11 +385,35 @@ ${hasTailwind
   scale \`--ds-typography-scale-<key>-font-size\`${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${list(Object.keys(foundations.typography.scale))}.
 - Motion: durations \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) and
   easings \`--ds-motion-easings-<key>\` (${list(Object.keys(motion.easings))}). Use them on
-  \`transition\`/\`animation\` (e.g. \`transition: color var(--ds-motion-durations-fast) var(--ds-motion-easings-standard)\`)
-  so timing stays on-brand. The DS ships timing tokens, **not** a runtime - for entrance/reveal/stagger
-  pair them with a motion lib (e.g. \`motion\`/Framer) or CSS \`@keyframes\`.
+  \`transition\` (e.g. \`transition: color var(--ds-motion-durations-fast) var(--ds-motion-easings-standard)\`)
+  so timing stays on-brand. For ANIMATION, this system ships a named vocabulary - see
+  **Motion vocabulary** below; never hand-roll \`@keyframes\` or raw durations.
 - When **creating a new component** the DS does not cover yet: compose it from these semantic
   tokens to inherit the system's identity; do not invent colors/measures outside the scale.
+${keyframeLines.length > 0
+        ? `
+---
+
+## Motion vocabulary
+
+The base is QUIET: nothing moves until someone asks. When they do, animation is **selection
+from this list**, not improvisation - these are the system's own animations, already compiled
+into ${hasTailwind ? "`theme.css` as ready utilities" : `\`tokens.css\` as \`@keyframes ds-${slug}-<name>\``}, each on the clock its intent calls for:
+
+${keyframeLines.join("\n")}
+${patternLines.length > 0
+            ? `
+Interaction patterns the system pairs with them:
+
+${patternLines.join("\n")}
+`
+            : ""}
+Rules: entrances run once, never on scroll-loop; ambient loops are decoration, one per view is
+plenty; \`prefers-reduced-motion\` is already honored in the shipped CSS (a floor collapses all
+animations) - don't undo it. If a request needs a motion this vocabulary lacks, do NOT hand-roll
+\`@keyframes\` or raw durations: file it (\`request_token\` via MCP, or \`synthesisui request\`) and
+tell the person what you chose from the vocabulary instead.`
+        : ""}
 
 ---
 

package/dist/index.js

@@ -37,9 +37,21 @@ Usage - deterministic, FREE:
   synthesisui upgrade <slug>               update an installed DS + regenerate your components + migration brief
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui clean [--force]              strip create-next-app boilerplate (dry run without --force)
-  synthesisui doctor [paths…] [--verbose]  audit for DRIFT: every design value written by
-                                           hand, the token your system already has for it, and the
-                                           laws your system carries for what you use
+
+Usage - governance (deterministic, FREE):
+  synthesisui adopt [--write]              turn the design system you ALREADY have into a contract
+                                           your agent follows - without touching your CSS
+  synthesisui connect                      wire your agent: the check as an editor hook, the system
+                                           as MCP tools, and a contract that stops repeating itself
+  synthesisui doctor [paths…] [--verbose]  audit for DRIFT: every design value written by hand, the
+                                           token your system already has for it, coherence, and the
+                                           record over time
+  synthesisui request [component|token]    the queue of what your agent needed and the system
+                                           refused to invent (--done <id> closes one)
+  synthesisui sync                         send the local record - checks, fixes, open requests -
+                                           to your system's dashboard (by hand, never automatic)
+  synthesisui hook                         the check itself; installed by connect, run by your editor
+  synthesisui mcp                          the system as tools; installed by connect, run by your agent
 
 Usage - AI, USES CREDITS (login required):
   synthesisui generate "<desc>"            AI-create a NEW component your DS doesn't have (token-only recipe)
@@ -73,12 +85,15 @@ Options:
   -h, --help         this help
 
 Examples:
+  synthesisui adopt                        # you already have a system: start here
   synthesisui login
   synthesisui init --target next
   synthesisui init --target next --ds halogen   bootstrap + bring a system in
   synthesisui doctor
   synthesisui doctor apps/web packages/ui   # scope the read in a monorepo
   synthesisui doctor --strict
+  synthesisui connect                      # before opening your agent
+  synthesisui sync                         # after a session, or from CI
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3

package/dist/motion.js

@@ -0,0 +1,115 @@
+/**
+ * Motion intent, classified from the frames alone - the CLI copy.
+ *
+ * The web side (`apps/web/src/lib/ds/motion-vocabulary.ts`) uses this exact
+ * logic to decide the clock behind each `animate-<name>` utility it compiles
+ * into theme.css. The GUIDE this package writes has to DESCRIBE those same
+ * utilities, and the CLI is zero-dependency, so the logic exists twice - like
+ * the ledger's summarize. The web spec imports both copies and fails on drift.
+ *
+ * Intent from geometry:
+ *   entrance   starts off-identity, lands on identity → runs once, fills both
+ *   exit       the reverse → runs once
+ *   loop       round trip, full rotation, or travel with no identity at
+ *              either end (marquee, shimmer) → ambient, infinite
+ *   attention  a round trip that is a gesture, not a mood (shake, tada)
+ *              → one shot
+ *
+ * The one non-geometric input: a round trip is ambiguous (pulse loops, shake
+ * does not), and the tiebreak is the keyframe's NAME - authored, part of the
+ * contract, not a guess about it.
+ */
+const offsetOf = (key) => {
+    if (key === "from")
+        return 0;
+    if (key === "to")
+        return 100;
+    const n = Number.parseFloat(key);
+    return Number.isNaN(n) ? 0 : n;
+};
+const isIdentityValue = (prop, value) => {
+    const v = value.trim();
+    if (prop === "opacity")
+        return v === "1";
+    if (prop === "transform") {
+        if (v === "none")
+            return true;
+        return [...v.matchAll(/([a-zA-Z]+)\(([^)]*)\)/g)].every(([, fn, args]) => {
+            const nums = args.split(",").map((a) => Number.parseFloat(a));
+            if (fn.startsWith("translate"))
+                return nums.every((n) => n === 0);
+            if (fn.startsWith("scale"))
+                return nums.every((n) => n === 1);
+            if (fn.startsWith("rotate") || fn.startsWith("skew"))
+                return nums.every((n) => n === 0);
+            return false;
+        });
+    }
+    return false;
+};
+const isIdentityFrame = (decls) => Object.entries(decls).every(([p, v]) => isIdentityValue(p, v));
+const LOOP_NAMES = /pulse|spin|rotate|orbit|float|drift|marquee|breathe|shimmer|sheen|glow|ping|wave|bounce|ambient|scroll/i;
+export function classifyKeyframe(name, frames) {
+    const ordered = Object.entries(frames).sort(([a], [b]) => offsetOf(a) - offsetOf(b));
+    if (ordered.length < 2)
+        return "attention";
+    const first = ordered[0][1];
+    const last = ordered[ordered.length - 1][1];
+    const fullTurn = /rotate\(\s*-?(360|720)deg\s*\)/.test(last.transform ?? "");
+    if (fullTurn)
+        return "loop";
+    const firstId = isIdentityFrame(first);
+    const lastId = isIdentityFrame(last);
+    if (JSON.stringify(first) === JSON.stringify(last)) {
+        // A round trip that never touches rest is a mood hovering around its own
+        // state (a flame at 0.7 opacity) → loop. One that departs FROM rest is
+        // ambiguous - pulse loops, shake does not - and only there the authored
+        // NAME breaks the tie.
+        if (!firstId)
+            return "loop";
+        return LOOP_NAMES.test(name) ? "loop" : "attention";
+    }
+    if (!firstId && lastId)
+        return "entrance";
+    if (firstId && !lastId) {
+        // Leaving is disappearing: an exit fades out. Rest → offset with the
+        // opacity intact is a conveyor starting its lap (marquee), not a goodbye.
+        const gone = Number.parseFloat(last.opacity ?? "") === 0;
+        return gone ? "exit" : "loop";
+    }
+    return "loop";
+}
+export const isFullRotation = (frames) => Object.values(frames).some((decls) => /rotate\(\s*-?(360|720)deg\s*\)/.test(decls.transform ?? ""));
+export function animationShorthand(scopedName, intent, fullTurn) {
+    switch (intent) {
+        case "entrance":
+        case "exit":
+            return `${scopedName} var(--ds-motion-durations-base, 200ms) var(--ds-motion-easings-standard, ease) both`;
+        case "loop":
+            return fullTurn
+                ? `${scopedName} var(--ds-motion-durations-ambient, 1s) linear infinite`
+                : `${scopedName} var(--ds-motion-durations-ambient, 2s) var(--ds-motion-easings-gentle, ease-in-out) infinite`;
+        case "attention":
+            return `${scopedName} var(--ds-motion-durations-slow, 400ms) var(--ds-motion-easings-standard, ease)`;
+    }
+}
+export function describeKeyframe(frames) {
+    const verbs = new Set();
+    for (const decls of Object.values(frames)) {
+        if ("opacity" in decls)
+            verbs.add("fades");
+        const t = decls.transform ?? "";
+        if (/translate/.test(t))
+            verbs.add("slides");
+        if (/scale/.test(t))
+            verbs.add("scales");
+        if (/rotate/.test(t))
+            verbs.add("rotates");
+        if (/skew/.test(t))
+            verbs.add("skews");
+        for (const prop of Object.keys(decls))
+            if (prop !== "opacity" && prop !== "transform")
+                verbs.add(`moves ${prop}`);
+    }
+    return [...verbs].join(", ") || "animates";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.25",
+  "version": "0.16.27",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {