synthesisui 0.16.25 → 0.16.26

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/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.26",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {