@actioneer/ads 0.5.7 → 0.5.8

package/llms.txt

@@ -11,6 +11,7 @@
    - `ToastProvider` (from `@actioneer/ads`) — required to render toasts
    - `<MotionConfig reducedMotion="user">` (from `motion/react`) — honor the OS reduced-motion setting
 4. Import contract: `import { Button } from "@actioneer/ads";` — the exact named export, never `@actioneer/ads/button`, never an alias, never a local copy.
+5. Motion contract: every imported component keeps its built-in ADS motion. For consumer-authored semantic state motion, import the matching named preset from `@actioneer/ads`; never copy raw spring values or introduce a separate timing system. Apply principle 3 on every component import/use change.
 
 ## Tokens
 
@@ -34,16 +35,17 @@ Reference semantic roles, never raw color/dimension literals (ads-lint rejects l
 - `fill` — Quiet fill — secondary buttons, avatars, chips
 - `fill-foreground` — Quiet fill — secondary buttons, avatars, chips
 - `table-shell` — Quiet fill — secondary buttons, avatars, chips
+- `artifact-canvas`
 - `accent`
 - `accent-foreground`
-- `success`
-- `success-foreground`
-- `warning`
-- `warning-foreground`
-- `danger`
-- `danger-foreground`
-- `info`
-- `info-foreground`
+- `success` — success-700 on white = 5.48:1 (600 was 3.77:1, failed AA).
+- `success-foreground` — success-700 on white = 5.48:1 (600 was 3.77:1, failed AA).
+- `warning` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `warning-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `danger` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `danger-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `info` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
+- `info-foreground` — Amber-500 fill kept (it IS the caution signal); dark ink foreground
 - `border-primary`
 - `border-secondary`
 - `border-tertiary`
@@ -71,21 +73,25 @@ Delineate SURFACES (cards, panels, sidebars, page regions) with color contrast,
 
 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).
+- Do: 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).
 - Do: Keep static surfaces flat: Panel, plain Card, Kbd, Navbar, headers, rails, docs boxes, Tooltip, InlineDrawer — they read by fill/color.
 - Do: Ask 'can the user click this surface?' — if no, it's flat.
 - Don't: Reintroduce a shadow scale (shadow-xs/sm/md/lg/xl) — there is one token only, shadow-elevation.
 - Don't: Put a shadow on a non-interactive surface for decoration.
 
-### 3. Motion follows the design-engineering guide [lint: unbounded-transition, sluggish-easing, zero-scale-entrance, undersized-zoom-entrance]
+### 3. Motion follows the interaction [lint: unbounded-transition, sluggish-easing, zero-scale-entrance, undersized-zoom-entrance, raw-spring-config]
 
-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.
+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.
-- Do: Give pressable elements a --scale-press on :active (text/link exempt); start entrances ≥ scale 0.95 with opacity.
-- Do: Respect reduced motion: keep opacity/color fades, drop movement.
-- Don't: 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.
+- Do: 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.
+- Do: 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.
+- Do: Keep sliders, drag-resize, scrolling, and other pointer-following interactions immediate; motion begins after the committed value or destination changes.
+- Do: Give pressable elements local active feedback (text/link exempt); start entrances ≥ scale 0.95 with opacity.
+- Do: Wrap Motion components in MotionConfig reducedMotion='user'; keep useful opacity/color feedback and drop spatial movement.
+- Don't: 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.
+- Don't: Override or duplicate the motion already shipped inside an imported ADS component.
 - Don't: Animate keyboard-initiated or 100×/day actions (e.g. a command-palette toggle).
+- Don't: Add motion to a component only because it is visible; static structure and decorative chrome stay still.
 
 ### 4. Icons: Hugeicons, stroke only [lint: icon-package-import]
 
@@ -164,12 +170,37 @@ When tabs and a search field control the same content, they share one responsive
 
 ## Components
 
+Before using any component below, preserve its built-in motion and apply the motion contract in Setup step 5.
+
 ### Primitives / utilities
 
 - [TooltipProvider] — component [docs](https://ads.actioneer.dev/#/tooltip)
 - [InteractiveProps] — TypeScript type
+- [backdropVariants] — utility
+- [checkDrawTransition] — utility
 - [cn] — utility
+- [drawerBackdropVariants] — utility
+- [drawerOffset] — utility
+- [fadeTransition] — utility
+- [floatVariants] — utility
 - [interactive] — utility
+- [menuVariants] — utility
+- [modalPanelVariants] — utility
+- [screenVariants] — utility
+- [springCarousel] — utility
+- [springControl] — utility
+- [springDialog] — utility
+- [springDisclosure] — utility
+- [springEffect] — utility
+- [springHighlight] — utility
+- [springOverlay] — utility
+- [springProgress] — utility
+- [springRadio] — utility
+- [springSheet] — utility
+- [springSidebar] — utility
+- [springSwitch] — utility
+- [toastVariants] — utility
+- [tooltipVariants] — utility
 
 ### Foundations
 
@@ -193,7 +224,7 @@ When tabs and a search field control the same content, they share one responsive
 - [ScrollBar] — component [docs](https://ads.actioneer.dev/#/review/scroll-area)
 - [SettingList] — component (variants: isPressable: true|false) [docs](https://ads.actioneer.dev/#/review/setting-row)
 - [SettingRow] — component (variants: isPressable: true|false) [docs](https://ads.actioneer.dev/#/review/setting-row)
-- [Spinner] — Use for an indeterminate loading state (e.g. inside a Button's isLoading, or standalone while content is fetching) — not for measurable/determinate progress. (variants: size: sm|md|lg; color: current|primary|muted) [docs](https://ads.actioneer.dev/#/spinner)
+- [Spinner] — Use the nine-squircle Spinner for indeterminate work; choose its variant by work scope and use Progress or ProgressCircle when completion can be measured. (variants: size: xs|sm|md|lg; color: current|primary|muted) [docs](https://ads.actioneer.dev/#/spinner)
 - [Stepper] — component (variants: status: complete|current|upcoming|error; size: sm|md) [docs](https://ads.actioneer.dev/#/review/stepper)
 - [Text] — Use Text for any body copy, caption, or inline run of prose instead of a raw p/span tag. [docs](https://ads.actioneer.dev/#/typography)
 - [Tooltip] — Use to label a single hover/focus-triggered element (icon-only buttons, avatars, truncated text) with a short informational hint — not for actions or content that needs to stay open. [docs](https://ads.actioneer.dev/#/tooltip)
@@ -215,6 +246,7 @@ When tabs and a search field control the same content, they share one responsive
 - [SettingListProps] — TypeScript type
 - [SettingRowProps] — TypeScript type
 - [SpinnerProps] — TypeScript type
+- [SpinnerVariant] — TypeScript type
 - [StepperProps] — TypeScript type
 - [StepperStatus] — TypeScript type
 - [StepperStep] — TypeScript type
@@ -225,6 +257,7 @@ When tabs and a search field control the same content, they share one responsive
 - [fileDropzoneVariants] — utility
 - [inputBaseClass] — utility
 - [settingRowVariants] — utility
+- [SPINNER_VARIANTS] — utility
 - [stepperMarkerVariants] — utility
 
 ### Form controls
@@ -237,7 +270,7 @@ When tabs and a search field control the same content, they share one responsive
 - [NumberField] — Use for a bounded numeric quantity (e.g. seats, width, count) that benefits from stepper buttons and min/max clamping, not free-form numeric text entry. [docs](https://ads.actioneer.dev/#/number-field)
 - [Radio] — Use for choosing exactly one option from a small, fully visible set — wrap Radio options in a RadioGroup that owns the shared name and controlled value. [docs](https://ads.actioneer.dev/#/radio)
 - [RadioGroup] — component [docs](https://ads.actioneer.dev/#/radio)
-- [SegmentedControl] — 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. (variants: size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/segmented)
+- [SegmentedControl] — 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. (variants: size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/segmented)
 - [Select] — Use for a single choice from a closed list of options in a form, especially when pairing with Field for a labeled control. (variants: size: sm|md|lg) [docs](https://ads.actioneer.dev/#/select)
 - [Slider] — Use for a single controlled numeric value picked from a bounded range (volume, brightness, threshold) — pair with Field or Label/Text for an accessible, labeled control. [docs](https://ads.actioneer.dev/#/slider)
 - [Switch] — Use for a single binary on/off preference that applies immediately, not as part of a form submitted later. [docs](https://ads.actioneer.dev/#/switch)
@@ -381,7 +414,7 @@ When tabs and a search field control the same content, they share one responsive
 - [TableRow] — component [docs](https://ads.actioneer.dev/#/table)
 - [TabList] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg) [docs](https://ads.actioneer.dev/#/tabs)
 - [TabPanel] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
-- [Tabs] — 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. (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
+- [Tabs] — 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. (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
 - [TabSeparator] — component (variants: variant: primary|secondary|pill; orientation: horizontal|vertical; size: sm|md|lg; selected: true|false) [docs](https://ads.actioneer.dev/#/tabs)
 - [Timeline] — Use for a vertical rail of dated events — version history, audit trails, activity/status feeds. [docs](https://ads.actioneer.dev/#/timeline)
 - [TimelineItem] — component [docs](https://ads.actioneer.dev/#/timeline)
@@ -582,6 +615,7 @@ When tabs and a search field control the same content, they share one responsive
 - [ProgressCircle] — Use for a compact circular loading/progress indicator (determinate or indeterminate) where a linear bar doesn't fit, e.g. inline with a caption or a small avatar-sized control. [docs](https://ads.actioneer.dev/#/progress-circle)
 - [Ripple] — component [docs](https://ads.actioneer.dev/#/ripple)
 - [Skeleton] — Placeholder the shape of content that's still loading — size it via className and pair with circle for avatars. [docs](https://ads.actioneer.dev/#/skeleton)
+- [AgentIconColorPreset] — TypeScript type
 - [AgentIconName] — TypeScript type
 - [AgentIconProps] — TypeScript type
 - [AgentIconState] — TypeScript type

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",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Actioneer Design System 1.0 — React 19 + Tailwind v4 component library.",
   "type": "module",
   "sideEffects": [