@actioneer/ads-mcp 0.5.7 → 0.5.8

package/README.md

@@ -19,11 +19,15 @@ All five tools read the L1 catalog (`ads-manifest.json`).
 | Tool | Purpose |
 |---|---|
 | `search_components(query, kind?, limit?)` | Enumerate what exists by name or purpose → exact export names, families, kinds, descriptions. |
-| `get_component(name)` | Full record for one EXACT export: the exact `import { … } from "@actioneer/ads"`, props, variant/size vocabulary, showcase URL, and a copy-paste usage example. Returns an error (never invents) on an unknown name. |
+| `get_component(name)` | Full record for one EXACT export: exact import, props, variants, showcase URL, usage example, and the mandatory motion contract. Returns an error (never invents) on an unknown name. |
 | `get_token(role)` | The semantic token(s) for a role/utility/purpose (`brand`, `bg-danger`, `muted text`) so the agent references a token, not a literal ads-lint would reject. |
-| `get_principles(id?, enforcedByLint?)` | The 9 ADS design principles (elevation = actionability, borderless surfaces, minimal-information-per-screen, square dots, stroke-only icons, container-fluid responsiveness, …). Each flags whether `ads-lint` auto-checks it — pair the `[lint]` ones with `lint_snippet`, self-apply the `[judgment]` ones. Teaches on-brand UX the catalog + linter can't. |
+| `get_principles(id?, enforcedByLint?)` | The 11 ADS design principles, including the required Animate UI-derived motion contract. Each flags whether `ads-lint` auto-checks it. |
 | `lint_snippet(code)` | Runs a snippet through `@actioneer/ads-lint` (consumer mode) and returns the verdict — deep imports, aliasing, external-UI, literals, weak motion. |
 
+Every component lookup carries principle 3 automatically. Imported ADS
+components keep their built-in motion; consumer-authored state motion imports a
+named role preset from `@actioneer/ads`. Raw spring parameters are lint errors.
+
 ## Wiring it into Claude Code / Cursor (`.mcp.json`)
 
 **Installed as a package** (recommended for consumer repos):

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "importPath": "@actioneer/ads",
   "styleImport": "@import \"@actioneer/ads/styles.css\";",
   "families": [
@@ -16,11 +16,11 @@
     "Chat"
   ],
   "counts": {
-    "total": 792,
+    "total": 818,
     "component": 357,
-    "type": 347,
+    "type": 349,
     "hook": 10,
-    "util": 78
+    "util": 102
   },
   "tokens": [
     {
@@ -208,6 +208,16 @@
       ],
       "description": "Quiet fill — secondary buttons, avatars, chips"
     },
+    {
+      "name": "--color-artifact-canvas",
+      "role": "artifact-canvas",
+      "utilities": [
+        "bg-artifact-canvas",
+        "text-artifact-canvas",
+        "border-artifact-canvas"
+      ],
+      "description": ""
+    },
     {
       "name": "--color-accent",
       "role": "accent",
@@ -235,7 +245,7 @@
         "text-success",
         "border-success"
       ],
-      "description": ""
+      "description": "success-700 on white = 5.48:1 (600 was 3.77:1, failed AA)."
     },
     {
       "name": "--color-success-foreground",
@@ -244,7 +254,7 @@
         "text-success-foreground",
         "bg-success-foreground"
       ],
-      "description": ""
+      "description": "success-700 on white = 5.48:1 (600 was 3.77:1, failed AA)."
     },
     {
       "name": "--color-warning",
@@ -254,7 +264,7 @@
         "text-warning",
         "border-warning"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-warning-foreground",
@@ -263,7 +273,7 @@
         "text-warning-foreground",
         "bg-warning-foreground"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-danger",
@@ -273,7 +283,7 @@
         "text-danger",
         "border-danger"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-danger-foreground",
@@ -282,7 +292,7 @@
         "text-danger-foreground",
         "bg-danger-foreground"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-info",
@@ -292,7 +302,7 @@
         "text-info",
         "border-info"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-info-foreground",
@@ -301,7 +311,7 @@
         "text-info-foreground",
         "bg-info-foreground"
       ],
-      "description": ""
+      "description": "Amber-500 fill kept (it IS the caution signal); dark ink foreground"
     },
     {
       "name": "--color-border-primary",
@@ -398,6 +408,20 @@
       "importPath": "@actioneer/ads",
       "module": "interactive"
     },
+    {
+      "name": "backdropVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "checkDrawTransition",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
     {
       "name": "cn",
       "family": "Primitives / utilities",
@@ -405,6 +429,34 @@
       "importPath": "@actioneer/ads",
       "module": "cn"
     },
+    {
+      "name": "drawerBackdropVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "drawerOffset",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "fadeTransition",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "floatVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
     {
       "name": "interactive",
       "family": "Primitives / utilities",
@@ -412,6 +464,125 @@
       "importPath": "@actioneer/ads",
       "module": "interactive"
     },
+    {
+      "name": "menuVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "modalPanelVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "screenVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springCarousel",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springControl",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springDialog",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springDisclosure",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springEffect",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springHighlight",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springOverlay",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springProgress",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springRadio",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springSheet",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springSidebar",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "springSwitch",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "toastVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
+    {
+      "name": "tooltipVariants",
+      "family": "Primitives / utilities",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "motion"
+    },
     {
       "name": "AudioWaveform",
       "family": "Foundations",
@@ -544,7 +715,9 @@
         "description",
         "error",
         "required",
-        "htmlFor"
+        "htmlFor",
+        "errorId",
+        "descriptionId"
       ]
     },
     {
@@ -740,20 +913,22 @@
       "kind": "component",
       "importPath": "@actioneer/ads",
       "module": "spinner",
-      "description": "Use for an indeterminate loading state (e.g. inside a Button's isLoading, or standalone while content is fetching) — not for measurable/determinate progress.",
+      "description": "Use the nine-squircle Spinner for indeterminate work; choose its variant by work scope and use Progress or ProgressCircle when completion can be measured.",
       "showcaseUrl": "https://ads.actioneer.dev/#/spinner",
       "variants": {
         "size": {
           "values": [
+            "xs",
             "sm",
             "md",
             "lg"
           ],
           "default": "md",
           "options": {
-            "sm": "Compact size for inline use, e.g. paired with muted text describing what's loading.",
-            "md": "Default size for standalone loading states.",
-            "lg": "Largest size for prominent, page-level loading moments."
+            "xs": "Dense 14px control slot, reserved for the tightest inline UI.",
+            "sm": "Standard 16px icon slot for buttons, rows, fields, and modal copy.",
+            "md": "Default 24px standalone loading state inside a bounded region.",
+            "lg": "Prominent 32px state for a blocked surface or page."
           }
         },
         "color": {
@@ -766,6 +941,7 @@
         }
       },
       "props": [
+        "variant",
         "label"
       ]
     },
@@ -959,6 +1135,13 @@
       "importPath": "@actioneer/ads",
       "module": "spinner"
     },
+    {
+      "name": "SpinnerVariant",
+      "family": "Foundations",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "spinner"
+    },
     {
       "name": "StepperProps",
       "family": "Foundations",
@@ -1029,6 +1212,13 @@
       "importPath": "@actioneer/ads",
       "module": "setting-row"
     },
+    {
+      "name": "SPINNER_VARIANTS",
+      "family": "Foundations",
+      "kind": "util",
+      "importPath": "@actioneer/ads",
+      "module": "spinner"
+    },
     {
       "name": "stepperMarkerVariants",
       "family": "Foundations",
@@ -1170,7 +1360,7 @@
       "kind": "component",
       "importPath": "@actioneer/ads",
       "module": "segmented",
-      "description": "Use for a small set (2-4) of mutually exclusive, always-visible options — like a range or view-mode switcher — not for navigation or long lists.",
+      "description": "Use for a small set (2-4) of mutually exclusive, always-visible options — like a range or view-mode switcher — not for navigation or long lists. Radius follows control size: 4px at sm and 8px at md/lg; tracks and options are never fully rounded.",
       "showcaseUrl": "https://ads.actioneer.dev/#/segmented",
       "variants": {
         "size": {
@@ -1589,6 +1779,7 @@
         "startContent",
         "danger",
         "disabled",
+        "restoreFocus",
         "onSelect"
       ]
     },
@@ -3100,7 +3291,8 @@
         "sortDescriptor",
         "onSortChange",
         "allowsSorting",
-        "isStatic"
+        "isStatic",
+        "resizableColumns"
       ]
     },
     {
@@ -3263,7 +3455,7 @@
       "kind": "component",
       "importPath": "@actioneer/ads",
       "module": "tabs",
-      "description": "Use Tabs to switch between mutually exclusive views/sections that share the same page context, not for page-level navigation. Always reach for the primary (pill) variant — it is the default; use secondary only when explicitly asked for it. When Tabs and a scoped search field coexist, compose one responsive control row with tabs leading and search trailing; do not stack search above tabs at widths where both fit.",
+      "description": "Use Tabs to switch between mutually exclusive views/sections that share the same page context, not for page-level navigation. Always reach for the primary recessed-track variant — it is the default; use secondary only when explicitly asked for it. Tab radius follows control size (4px sm, 8px md/lg), never rounded-full. When Tabs and a scoped search field coexist, compose one responsive control row with tabs leading and search trailing; do not stack search above tabs at widths where both fit.",
       "showcaseUrl": "https://ads.actioneer.dev/#/tabs",
       "variants": {
         "variant": {
@@ -3274,8 +3466,8 @@
           ],
           "default": "primary",
           "options": {
-            "primary": "Filled muted pill track with tabs sliding behind a shared elevated thumb. The house default — use it for every tab surface unless the underline is explicitly requested.",
-            "secondary": "No pill background — a thin brand-colored underline (or side rail when vertical) slides beneath the active tab against a hairline rail; use for flush, lower-emphasis section tabs."
+            "primary": "Filled muted track with tabs sliding behind a shared elevated segment. The house default — use it for every tab surface unless the underline is explicitly requested.",
+            "secondary": "No track background — a thin neutral-ink underline (or side rail when vertical) slides beneath the active tab against a hairline rail; use for flush, lower-emphasis section tabs."
           }
         },
         "orientation": {
@@ -4652,7 +4844,12 @@
         "state",
         "interactive",
         "size",
+        "tileGridSize",
+        "eyeScale",
+        "eyeColor",
+        "animateOnMount",
         "color",
+        "colorPreset",
         "trackPointer"
       ]
     },
@@ -4917,6 +5114,13 @@
         "circle"
       ]
     },
+    {
+      "name": "AgentIconColorPreset",
+      "family": "Feedback",
+      "kind": "type",
+      "importPath": "@actioneer/ads",
+      "module": "agent-icon"
+    },
     {
       "name": "AgentIconName",
       "family": "Feedback",
@@ -8688,7 +8892,7 @@
       "title": "Elevation = actionability",
       "rule": "The single shadow-elevation token is an affordance: it goes ONLY on surfaces the user can act on. Never elevate something that can't be clicked. There is no shadow scale.",
       "do": [
-        "Elevate actionable surfaces: pressable/hoverable cards, primary CTAs, control thumbs (Switch, Slider, active pills), and interactive floating layers (Modal, Drawer, Popover, Dropdown, listboxes, Toast).",
+        "Elevate actionable surfaces: pressable/hoverable cards, primary CTAs, control thumbs (Switch, Slider, active tab segments), and interactive floating layers (Modal, Drawer, Popover, Dropdown, listboxes, Toast).",
         "Keep static surfaces flat: Panel, plain Card, Kbd, Navbar, headers, rails, docs boxes, Tooltip, InlineDrawer — they read by fill/color.",
         "Ask 'can the user click this surface?' — if no, it's flat."
       ],
@@ -8701,23 +8905,28 @@
     {
       "id": "motion-follows-guide",
       "number": 3,
-      "title": "Motion follows the design-engineering guide",
-      "rule": "Every easing/duration/scale flows from a token (--ease-*, --duration-*, --scale-press), mirrored for Motion in src/lib/motion.ts. UI animations stay under 300ms, exits run faster than enters, and reduced motion is respected everywhere.",
+      "title": "Motion follows the interaction",
+      "rule": "Component motion follows the closest Animate UI interaction pattern, using role-specific presets defined in src/lib/motion.ts and exported from the ADS root barrel. Direct manipulation stays immediate, small CSS feedback stays local, and reduced motion is respected everywhere.",
       "do": [
-        "Use strong curves only — the ease-out utility is the right default; overlays scale in origin-aware from their trigger.",
-        "Give pressable elements a --scale-press on :active (text/link exempt); start entrances ≥ scale 0.95 with opacity.",
-        "Respect reduced motion: keep opacity/color fades, drop movement."
+        "Treat motion as part of every ADS component import: preserve the component's built-in motion, and import any composition-level preset from the ADS root barrel.",
+        "Map the component family before choosing motion: tabs/segments use control; checkbox/radio/switch use selection; menus use highlight; popovers/tooltips use overlay; modal/drawer use dialog/sheet; accordion/collapsible use disclosure; progress, carousel, and sidebar use their matching presets.",
+        "Keep sliders, drag-resize, scrolling, and other pointer-following interactions immediate; motion begins after the committed value or destination changes.",
+        "Give pressable elements local active feedback (text/link exempt); start entrances ≥ scale 0.95 with opacity.",
+        "Wrap Motion components in MotionConfig reducedMotion='user'; keep useful opacity/color feedback and drop spatial movement."
       ],
       "dont": [
-        "Use a slow-starting (accelerating) easing on UI, an unbounded all-property transition, a scale-from-zero entrance, or a UI duration at or over 300ms.",
-        "Animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle)."
+        "Invent raw spring values inside a component, recreate a global duration/easing token scale, use an unbounded all-property transition, or start an entrance at scale zero.",
+        "Override or duplicate the motion already shipped inside an imported ADS component.",
+        "Animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle).",
+        "Add motion to a component only because it is visible; static structure and decorative chrome stay still."
       ],
       "enforcedByLint": true,
       "lintRules": [
         "unbounded-transition",
         "sluggish-easing",
         "zero-scale-entrance",
-        "undersized-zoom-entrance"
+        "undersized-zoom-entrance",
+        "raw-spring-config"
       ]
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actioneer/ads-mcp",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "ADS MCP server: lets an agent in Claude Code / Cursor discover and import the Actioneer Design System",
   "type": "module",
   "bin": {

package/src/tools.mjs

@@ -14,7 +14,8 @@ export function createTools({ manifest }) {
       description:
         "Search the ADS catalog for components/utilities/hooks by name or purpose. " +
         "Returns exact export names (import from '@actioneer/ads'), families, kinds, and descriptions. " +
-        "Use this first to discover what exists before importing.",
+        "Use this first to discover what exists before importing; every component use must preserve " +
+        "its built-in motion and apply the required motion contract returned by get_component.",
       inputSchema: {
         type: "object",
         properties: {
@@ -29,7 +30,8 @@ export function createTools({ manifest }) {
       name: "get_component",
       description:
         "Get the full record for one ADS export by its EXACT name: the exact import statement, " +
-        "props, variant/size vocabulary, showcase URL, and a copy-paste usage example. " +
+        "props, variant/size vocabulary, showcase URL, a copy-paste usage example, and the mandatory " +
+        "Animate UI-derived motion contract for components. " +
         "Returns an error if the name is not an exact export (never invents one).",
       inputSchema: {
         type: "object",
@@ -98,7 +100,7 @@ export function createTools({ manifest }) {
         (r) => `- ${r.name} (${r.kind}, ${r.family})${r.description ? ` — ${r.description}` : ""}`
       );
       return text(
-        `${results.length} match(es) — import from "${manifest.importPath}":\n${lines.join("\n")}`
+        `${results.length} match(es) — import from "${manifest.importPath}":\n${lines.join("\n")}\n\nBefore using a component, call get_component for its required motion contract.`
       );
     },