# Agent Token Ontology

`registry/tokens/ontology.json` is the machine-readable companion to Spark
Design token CSS. It explains what token families mean, where agents should use
them, and which patterns are forbidden.

## Package Entry

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

Use this before inventing custom colors, spacing, radii, or motion values.

## Selection Order

1. Pick the correct axis: `data-theme` for color, `data-style` for layout rhythm.
2. Pick a token family by intent, not by visual resemblance.
3. Check `avoidFor` and `agentRules` before using a family.
4. Use existing semantic utilities or `var(--token-name)` bindings.
5. Do not hard-code hex, raw rgba overlays, arbitrary radii, or one-off spacing.

## Agent Defaults

- Use `data-theme="light"` and `data-style="neutral"` when no preference is known.
- Use `compact` or `dense` only for data-heavy surfaces.
- Use `soft` for airy onboarding or approachable product surfaces.
- Use `sharp` only when square geometry is an explicit visual direction.
- Use semantic color families for status; do not repurpose accent colors for errors or warnings.

## Maintenance

When token CSS changes the public semantic surface:

1. Update `registry/tokens/ontology.json`.
2. Run `npm run check:token-ontology`.
3. Update this document if the agent decision model changes.