Customizing Agent-Native

Rule

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. 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:

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.