@agent-native/core 0.117.1 → 0.118.0

package/corpus/templates/design/.agents/skills/customizing-agent-native/SKILL.md

@@ -13,22 +13,93 @@ metadata:
 
 ## Rule
 
-Start with the public component and its props, slots, callbacks, and stable
-class names. If those seams are not enough, use the eject CLI to transfer the
-smallest supported feature into the app and make that copy app-owned. Never
-edit `node_modules`, deep-import a private source file at runtime, or patch an
-`@agent-native/*` package.
+Start with the app's registered design system and local UI adapters, then use
+the public feature's props, semantic components, controller, product slots,
+and callbacks. If those seams are not enough, use the eject CLI to transfer
+the smallest supported feature into the app and make that copy app-owned.
+Never edit `node_modules`, deep-import a private source file at runtime, or
+patch an `@agent-native/*` package.
 
 Use this order:
 
-1. Configure the public component.
-2. Compose public primitives behind a local app component.
-3. Eject the smallest feature into app-owned source.
-4. Propose a new Toolkit seam when the same override is useful in two apps.
+1. Set brand tokens with the build-time theme configuration when tokens are
+   enough.
+2. Register company components in `app/design-system.ts` with
+   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
+3. Configure a public feature through its semantic components, headless
+   controller, and product-level render slots.
+4. Compose app primitives behind the app's local UI adapter layer.
+5. Eject the smallest feature into app-owned source.
+6. Propose a new Toolkit seam when the same override is useful in two apps.
 
 Ejection is for intentional product customization, not for hiding an upgrade
 failure or replacing Core runtime behavior.
 
+## Use A Company Design System
+
+Keep the explicit, typed registration seam in `app/design-system.ts`:
+
+```tsx
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import {
+  AcmeActionButtonAdapter,
+  AcmeDialogAdapter,
+} from "./design-system/acme-adapter";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  components: {
+    ActionButton: AcmeActionButtonAdapter,
+    Dialog: AcmeDialogAdapter,
+  },
+});
+```
+
+Adapters translate the semantic Toolkit contract into company component props.
+They are ordinary React components and may use MUI-style providers, React Aria,
+CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
+optional interoperability hooks, not Tailwind or CVA requirements.
+
+The contract has nine leaf components (`ActionButton`, `IconButton`,
+`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
+and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
+`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
+behavior, not date picking. Behavior adapters own their portal, focus,
+keyboard, dismissal, and stacking implementation while honoring the semantic
+props and `portalContainer` interop contract.
+
+App product code imports standard controls from its local adapter path, usually
+`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
+pages, routes, or domain components. That bypasses the app seam and makes a
+future design-system replacement incomplete. Toolkit feature packages remain
+valid imports; configure their presentation through the registered semantic
+components, controller, and product slots.
+
+Run the published conformance kit against a complete adapter in its own CI:
+
+```tsx
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+
+await assertDesignSystemConformance({
+  adapterName: "Acme",
+  components,
+  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+});
+```
+
+New components and optional props are minor contract changes. Required props,
+removed APIs, or behavioral changes require a new contract major.
+
+## Customize A Shared Feature
+
+Prefer feature-level headless controllers over rebuilding individual widgets.
+One controller must power both the Toolkit default view and every custom render
+path so behavior, actions, analytics, accessibility state, and error handling
+cannot drift. Use a product-level render slot to replace the view while keeping
+that controller. Eject only when the controller and slots cannot express the
+required product behavior.
+
 ## Eject A Feature
 
 Discover and inspect the ejection units published by installed first-party
@@ -104,11 +175,14 @@ UI ownership may change; product contracts should not:
   Core. Do not copy those runtimes into the app.
 - Keep local adapters narrow so package upgrades still improve every surface
   the app has not intentionally taken ownership of.
+- Keep page, route, and domain code on local UI adapter imports. Never reach
+  around the registered design system with direct Toolkit UI primitive imports.
 
 ## App Shapes
 
-- **Template app:** begin with its existing local adapters and domain UI. Use
-  Toolkit for repeated workspace UI; eject only the unit being customized.
+- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
+  and domain UI. Use Toolkit features for repeated workspace behavior; eject
+  only the unit being customized.
 - **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
   Core. Compose or eject Toolkit presentation such as chat-history UI around it.
 - **Headless app:** stay action-first while no UI is needed. When adding a UI,
@@ -135,6 +209,7 @@ UI ownership may change; product contracts should not:
 - Don't copy Core auth, DB, action, agent-loop, or transport internals.
 - Don't manually copy a first-party unit with a missing recipe; fix its manifest.
 - Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
+- Don't fork feature state into a custom view; consume the feature's controller.
 
 ## Related Skills
 

package/corpus/templates/design/.agents/skills/frontend-design/SKILL.md

@@ -57,10 +57,26 @@ Default to Apple/Linear-level restraint: make the primary workflow obvious, then
 
 ## Agent-Native UI Rules
 
-- Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.
-- **Use shadcn/ui primitives for standard UI**: `DropdownMenu`, `Popover`, `Dialog`, `AlertDialog`, `Sheet`, `Tabs`, `Tooltip`, `Select`, `Command`, `Sidebar`, `Table`, `Card`, `Badge`, `Skeleton`, and related primitives.
+- Agent-native apps use React and Vite. The default adapter uses Tailwind CSS,
+  shadcn/ui, and `@tabler/icons-react`, but an app may register a different
+  company design system in `app/design-system.ts`.
+- **Use the app's design-system seam for standard UI.** Inspect
+  `app/design-system.ts`, `ToolkitProvider`, and the local UI adapter directory
+  before choosing a primitive. Use shadcn primitives when they are the active
+  adapter; use the registered company components when they are not.
 - **When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
 - Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
+- Pages, routes, and domain components must import controls through the app's
+  local adapter path, usually `@/components/ui/*`. Never import
+  `@agent-native/toolkit/ui/*` directly in app product code.
+- Toolkit/Core feature presentation flows through the semantic components from
+  `@agent-native/toolkit/design-system`. Their props express intent, emphasis,
+  size, controlled values, and behavior; they do not require Tailwind, CVA, or
+  `className`.
+- For deeper feature customization, consume the feature-level headless
+  controller through its product render slot. The same controller must power
+  the default and custom views. Eject the smallest supported unit only after
+  tokens, semantic components, controllers, and slots are insufficient.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
@@ -103,10 +119,14 @@ For substantial frontend work:
 2. Start the dev server when the app needs one.
 3. Verify with browser screenshots at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
+5. When registering or changing a company adapter, run
+   `@agent-native/toolkit/conformance`, including mixed-overlay focus,
+   `portalContainer`, and z-index stacking checks.
 
 ## Related Skills
 
 - **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
+- **customizing-agent-native** — Design-system registration, feature controllers, product slots, conformance, and ejection
 - **self-modifying-code** — The agent can edit source code to apply design changes
 - **storing-data** — All data lives in SQL; use actions for data access
 - **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching

package/corpus/templates/design/.agents/skills/shadcn-ui/SKILL.md

@@ -17,10 +17,33 @@ This skill keeps shadcn/ui work project-aware. Components are source files in th
 ## First Steps
 
 1. Work from the app root that owns `components.json`.
-2. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
-3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
-4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
-5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+2. In an Agent Native app, inspect `app/design-system.ts` and
+   `ToolkitProvider` before choosing a primitive. A registered company design
+   system takes precedence over the default shadcn adapter.
+3. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+4. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## Agent Native Adapter Rule
+
+Pages, routes, and domain components import controls through the app's local UI
+adapter layer. Never import `@agent-native/toolkit/ui/*` directly in app product
+code. Direct imports bypass `app/design-system.ts` and make Toolkit/Core
+surfaces use different controls from the app.
+
+When shadcn is the app's adapter, add or update the local primitive and keep
+product code on that local import. When a company design system is registered,
+adapt its components to the semantic contracts from
+`@agent-native/toolkit/design-system`; do not recreate a parallel shadcn
+surface. The semantic API is styling-runtime agnostic, so do not require
+Tailwind, CVA, or `className` in customer adapters.
+
+For shared Toolkit features, customize presentation through semantic
+components, a feature-level controller, and product-level render slots. Keep
+the same controller for default and custom views. Use the conformance kit for
+behavior components whose focus, portal, keyboard, dismissal, or stacking
+behavior comes from the company design system.
 
 ## Adding Or Updating Components
 
@@ -91,5 +114,6 @@ Do not wrap triggers in extra divs just to place a Button or Link inside them.
 ## Related Skills
 
 - **frontend-design** — Product UX, visual direction, responsive polish, and verification
+- **customizing-agent-native** — Registered design systems, controllers, slots, conformance, and ejection
 - **actions** — Data fetching and mutation patterns for agent-native apps
 - **security** — User data, forms, external input, and action safety

package/corpus/templates/design/app/components/design/CanvasContextMenu.tsx

@@ -106,6 +106,7 @@ export type CanvasContextMenuAction =
   | "copy-as-code"
   | "copy-as-svg"
   | "copy-as-png"
+  | "rotate-clockwise"
   | "flip-horizontal"
   | "flip-vertical"
   | "toggle-ui"
@@ -176,6 +177,7 @@ export interface CanvasContextMenuLabels {
   copyAsCode: string;
   copyAsSvg: string;
   copyAsPng: string;
+  rotateClockwise: string;
   flipHorizontal: string;
   flipVertical: string;
   toggleUiShow: string;
@@ -219,6 +221,7 @@ export interface CanvasContextMenuShortcuts {
   copyAsCode: string;
   copyAsSvg: string;
   copyAsPng: string;
+  rotateClockwise: string;
   flipHorizontal: string;
   flipVertical: string;
   toggleUi: string;
@@ -296,6 +299,7 @@ export interface CanvasContextMenuProps {
   canCopyAsCode?: boolean;
   canCopyAsSvg?: boolean;
   canCopyAsPng?: boolean;
+  canRotateClockwise?: boolean;
   canFlipHorizontal?: boolean;
   canFlipVertical?: boolean;
   canToggleUi?: boolean;
@@ -356,6 +360,7 @@ export interface CanvasContextMenuProps {
   onCopyAsCode?: CanvasContextMenuActionHandler;
   onCopyAsSvg?: CanvasContextMenuActionHandler;
   onCopyAsPng?: CanvasContextMenuActionHandler;
+  onRotateClockwise?: CanvasContextMenuActionHandler;
   onFlipHorizontal?: CanvasContextMenuActionHandler;
   onFlipVertical?: CanvasContextMenuActionHandler;
   onToggleUi?: CanvasContextMenuActionHandler;
@@ -409,6 +414,7 @@ const DEFAULT_LABELS: CanvasContextMenuLabels = {
   copyAsCode: "Copy as code",
   copyAsSvg: "Copy as SVG",
   copyAsPng: "Copy as PNG",
+  rotateClockwise: "Rotate 90° clockwise",
   flipHorizontal: "Flip horizontal",
   flipVertical: "Flip vertical",
   toggleUiShow: "Show UI",
@@ -452,6 +458,7 @@ const DEFAULT_SHORTCUTS: CanvasContextMenuShortcuts = {
   copyAsCode: "",
   copyAsSvg: "",
   copyAsPng: "⇧⌘C",
+  rotateClockwise: "",
   flipHorizontal: "⇧H",
   flipVertical: "⇧V",
   toggleUi: "⌘\\",
@@ -464,7 +471,7 @@ type ActionCallbackMap = Partial<
 
 // design-editor menu chrome: compact, dark-border, subtle shadow, no animation jitter
 const MENU_CONTENT_CLASS =
-  "w-52 min-w-[200px] rounded-[6px] border border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] py-[3px] px-[3px] text-[12px] text-foreground shadow-[0_4px_16px_rgba(0,0,0,0.16),0_0_0_0.5px_rgba(0,0,0,0.08)] outline-none";
+  "w-52 min-w-[200px] rounded-[6px] border border-[var(--design-editor-control-border)] bg-[var(--design-editor-panel-bg)] py-[3px] px-[3px] text-[12px] text-foreground shadow-[0_4px_16px_rgba(0,0,0,0.16),0_0_0_0.5px_rgba(0,0,0,0.08)] outline-none data-[state=open]:!animate-none data-[state=closed]:!animate-none";
 // design row height ~28px, full-width highlight on hover, no icon gap waste
 const MENU_ITEM_CLASS =
   "flex h-7 cursor-default select-none items-center rounded-[4px] px-2 py-0 text-[12px] leading-none gap-0 focus:bg-[var(--design-editor-selection-color)] focus:text-white data-[disabled]:pointer-events-none data-[disabled]:opacity-35";
@@ -525,6 +532,7 @@ export const CanvasContextMenu = forwardRef<
     canCopyAsCode = selectedCount > 0,
     canCopyAsSvg = selectedCount > 0,
     canCopyAsPng = selectedCount > 0,
+    canRotateClockwise = false,
     canFlipHorizontal = selectedCount > 0,
     canFlipVertical = selectedCount > 0,
     canToggleUi = true,
@@ -565,6 +573,7 @@ export const CanvasContextMenu = forwardRef<
     onCopyAsCode,
     onCopyAsSvg,
     onCopyAsPng,
+    onRotateClockwise,
     onFlipHorizontal,
     onFlipVertical,
     onToggleUi,
@@ -650,6 +659,7 @@ export const CanvasContextMenu = forwardRef<
       "copy-as-code": onCopyAsCode,
       "copy-as-svg": onCopyAsSvg,
       "copy-as-png": onCopyAsPng,
+      "rotate-clockwise": onRotateClockwise,
       "flip-horizontal": onFlipHorizontal,
       "flip-vertical": onFlipVertical,
       "toggle-ui": onToggleUi,
@@ -665,6 +675,7 @@ export const CanvasContextMenu = forwardRef<
       onCopyAsCode,
       onCopyAsPng,
       onCopyAsSvg,
+      onRotateClockwise,
       onCopyProps,
       onCreateComponent,
       onReprompt,
@@ -1073,6 +1084,13 @@ export const CanvasContextMenu = forwardRef<
             <CanvasMenuSeparator />
 
             <ContextMenuGroup>
+              <CanvasMenuItem
+                hidden={isHiddenAction("rotate-clockwise")}
+                disabled={!canRun("rotate-clockwise", canRotateClockwise)}
+                label={labels.rotateClockwise}
+                shortcut={shortcuts.rotateClockwise}
+                onSelect={(event) => runAction("rotate-clockwise", event)}
+              />
               <CanvasMenuItem
                 hidden={isHiddenAction("flip-horizontal")}
                 disabled={!canRun("flip-horizontal", canFlipHorizontal)}

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -533,6 +533,8 @@ interface DesignCanvasProps {
   selectedSelector?: string | null;
   selectedSelectorCandidates?: string[];
   selectedSelectorGroups?: string[][];
+  /** Visual treatment for selection mirrors in responsive peer previews. */
+  passiveSelectionStyle?: "default" | "soft";
   hoveredSelector?: string | null;
   hoveredSelectorCandidates?: string[];
   lockedSelectors?: string[];
@@ -1058,6 +1060,7 @@ export function DesignCanvas({
   selectedSelector,
   selectedSelectorCandidates = [],
   selectedSelectorGroups = [],
+  passiveSelectionStyle = "default",
   hoveredSelector,
   hoveredSelectorCandidates = [],
   lockedSelectors = [],
@@ -2969,6 +2972,7 @@ export function DesignCanvas({
       {
         type: "select-elements",
         selectorGroups: selectedSelectorGroups,
+        passiveSelectionStyle,
       },
       "*",
     );
@@ -2978,8 +2982,14 @@ export function DesignCanvas({
             type: "hover-element",
             selector: hoveredSelector,
             selectorCandidates: hoveredSelectorCandidates,
+            hoverStyle: passiveSelectionStyle,
           }
-        : { type: "hover-element", selector: "", selectorCandidates: [] },
+        : {
+            type: "hover-element",
+            selector: "",
+            selectorCandidates: [],
+            hoverStyle: passiveSelectionStyle,
+          },
       "*",
     );
     // Re-send motion tracks so the preview bridge is ready after a reload.
@@ -3038,6 +3048,7 @@ export function DesignCanvas({
     selectedSelector,
     selectedSelectorCandidates,
     selectedSelectorGroups,
+    passiveSelectionStyle,
     shaderFillPreview,
     spacePanActive,
     statePreviewTarget,