# Spark Design AI Entrypoint

This file is the shortest path for design and coding agents that need to use
Spark Design correctly.

## Read Order

1. `registry/agent-manifest.json` — choose components by intent, slots, states, accessibility, composition, and anti-patterns.
2. `registry/tokens/ontology.json` — choose token families by semantic purpose before writing styles.
3. `docs/guides/system-operating-model.md` — quality bar for structure, showcase, AI semantics, and maintenance gates.
4. `docs/agent/component-selection.md` — decision order, name boundaries, recipes, and manifest maintenance.
5. `docs/agent/prompt-recipes.md` — copyable prompts for install, screen composition, AI workflows, component changes, and audits.
6. `docs/guides/agent-usage.md` — consumption rules for CLI copy vs package import.
7. Component source only after the manifest tells you which component to use.

For npm package consumers:

```ts
import manifest from 'sparkdesign/agent-manifest.json'
import ontology from 'sparkdesign/token-ontology.json'
```

## Default Decisions

- Prefer `npx sparkdesign@latest add <component>` when building a business app that should own component source.
- Prefer `import { Component } from 'sparkdesign'` only for prototypes, showcase usage, or projects already using the package runtime.
- Use `basic/*` for product primitives and `chat/*` for assistant, tool, file, reasoning, and response flows.
- Choose components by manifest intent and anti-patterns before matching by name.
- Use `data-theme` for color and `data-style` for density, radius, and rhythm.
- Treat showcase, docs, registry metadata, and agent manifest updates as one public contract when a component changes.

## Hard Rules

- Do not invent duplicate components when a Spark component already matches the intent.
- Do not hard-code hex colors, raw rgb/rgba overlays, arbitrary radii, or one-off px spacing in published UI source.
- Do not flatten structured AI output into plain Markdown when `Response`, `ToolInvocationCard`, `PermissionCard`, or related chat components apply.
- Do not use accent colors to communicate status without text or icon labels.
- Do not bypass portal theme inheritance for Dialog, Drawer, Tooltip, DropdownMenu, Toast, or other floating layers.

## Verification Commands

Run these before handing work back:

```bash
npm run check:agent-manifest
npm run check:token-ontology
npm run check:token-antipatterns
npm run lint
npm run test:run
```

For publishing or registry-affecting changes, also run:

```bash
npm run check:registry-meta
npm run check:registry
npm run build
npm run size
```

## When Unsure

If the manifest and ontology do not describe the pattern you need, update them
before relying on source-code intuition. The semantic map must stay aligned with
the implementation terrain.