# @ai-created/ui agent entrypoint

This repository and package include a machine-readable design-system contract for AI agents. Never infer component props, variants, tokens, or behavior from model memory.

## Required sequence

1. Read `design-system.manifest.json` or query it with `npm run agent:query -- component <id>`.
2. For page-level work, select a reviewed archetype with `npm run agent:query -- templates`.
3. Import only public APIs from `@ai-created/ui`.
4. Use semantic tokens through the shared CSS and Tailwind preset. Never consume `--ref-*` values in product UI.
5. Implement every applicable loading, empty, error, permission, disabled, focus, and responsive state.
6. Run `npm run agent:check`. A justified departure requires a scoped, owned, expiring exception in `ai-created-ui.config.json`.

## Canonical authority

1. runtime behavior and public API: `src/**`, `src/index.ts`
2. design tokens: `styles/tokens.css`
3. framework mappings: `tailwind-preset.js`
4. component and construction guidance: `playground/src/components/design-system/componentDocs.ts`, `playground/src/components/design-system/specs/details.ts`, `playground/src/components/design-system/specs/construction.ts`, `playground/src/components/design-system/specs/registry.ts`
5. system guidelines: `playground/src/components/design-system/principal-spec/registry.ts`
6. narrative documentation: `AGENTS.md`, `DESIGN-SYSTEM.md`, `README.md`, `CLAUDE.md`

The generated manifest is a consumption projection only. It never overrides canonical source.

## Appearance and accent contract

- The supported `accentNames` are `red`, `green`, `blue`, `orange`, `yellow`, `purple`, `teal`, `pink`, and `magenta`. Accent-aware semantic tokens follow the selected accent; destructive and status tokens remain fixed.
- The public appearance APIs are `ThemeProvider`, `useTheme`, `accentNames`, and the `Accent` type.
- For a fixed product accent, use controlled mode with `<ThemeProvider accent="blue">`. `onAccentChange` reports requested changes in either mode, but controlled mode does not persist them. Render the matching `data-accent` on the root document before paint; do not initialize a fixed choice from saved preferences.
- For a persisted user preference, use uncontrolled mode with `<ThemeProvider defaultAccent="blue">`. Resolution order is valid `localStorage["accent"]`, existing `html[data-accent]`, `defaultAccent`, then `red`. `setAccent` persists changes and calls `onAccentChange` in uncontrolled mode. Before hydration, server-render the fallback `html[data-accent]` that matches `defaultAccent` and replace it with any valid stored accent so the first paint matches the resolved preference.

## Machine resources

- Full context: `llms-full.txt` or `/llms-full.txt`
- Component and guideline contract: `design-system.manifest.json` or `/design-system/manifest.json`
- DTCG-shaped tokens: `/design-system/tokens.json`
- Page templates: `templates/agent/manifest.json`
- Universal operating rules: `AGENTS.md`
- Query CLI: `npm run agent:query -- <command>`
- Consumer currency check: `npx ai-created-ui-agent consumer-status`
- Human and operator runbook: `docs/consumer-update-automation.md`

## Downstream consumer lifecycle

1. Install an immutable `vX.Y.Z` tag. Existing sites remain on that release until their owner deliberately adopts another one; consumers never follow `main`.
2. Opt into update discovery with Renovate. Merge the documented `@ai-created/ui` package rule into the consumer's own Renovate configuration; no central registration is required.
3. Renovate detects a newer GitHub tag and opens a pull request that updates both `package.json` and `package-lock.json`. The consumer owns any optional schedule and Dependency Dashboard settings.
4. Run the consumer's own install, typecheck, lint, tests, design-policy validation, accessibility checks, and production build. Provider previews may help review but do not replace those compatibility checks.
5. Review release notes and visible or behavioral impact, then merge manually. Design-system dependency updates do not auto-merge.
6. Verify the consumer's normal deployment completed and smoke-test the affected workflow.
7. Optionally run `npx ai-created-ui-agent consumer-status` on a schedule to make staleness visible. This command reports status; it does not update, merge, or deploy the consumer.

Use `docs/consumer-update-automation.md` for setup, configuration, review, troubleshooting, and removal. Use `docs/examples/consumer-renovate.json` as a standalone example or copy only its package rule into an existing Renovate configuration.

## Coverage

- 22 documented component, provider, utility, and motion families
- 96 verified public exports
- 7 principal guideline chapters
- 6 production page templates