# Spark Design Operating Model

> The system is excellent only when the implementation, documentation, showcase, registry, and agent contract all describe the same product truth.

## Purpose

Showcase companion: `#/system-operating-model`.

Spark Design should feel like a world-class product system, not a folder of UI parts. Every addition must improve four surfaces at once:

- **Product surface:** components are elegant, restrained, accessible, and token-driven.
- **System surface:** registry, package exports, CLI copies, and metadata stay isomorphic.
- **Documentation surface:** users can understand when to use a component, how to install it, and how to extend it without reading source first.
- **Agent surface:** AI tools can select, compose, and verify components from manifest intent instead of guessing from names.

## Principles

### 1. Quiet Excellence

Prefer durable hierarchy over decoration. Components should look precise at rest, clear in motion, and trustworthy under edge cases.

Required signals:

- Stable spacing, radius, typography, and focus states across all `data-style` values.
- Semantic color usage through tokens, never one-off palettes in component source.
- Interaction feedback that clarifies state without delaying work.
- Empty, loading, disabled, error, and dense-content states handled deliberately.

### 2. Isomorphic Maintenance

The map must stay aligned with the terrain. A component is not complete until every public surface agrees.

Required surfaces:

- `registry/` implementation and dependencies.
- `registry/meta.json` and `cli/registry/meta.json`.
- `src/components/index.ts` public exports.
- Showcase config, demo, props table, and localized labels.
- `registry/agent-manifest.json` intent, slots, states, a11y, recipes, and anti-patterns.
- P3 headers and P2 module maps when membership changes.

### 3. AI-Friendly Semantics

Spark should be easy for agents to use correctly under time pressure.

Agent-facing data must answer:

- What user intent does this component satisfy?
- When should an agent choose a different component?
- What slots and states are expected?
- What accessibility obligations are non-negotiable?
- Which components compose well together?
- Which anti-patterns produce generic or unsafe UI?

If the manifest cannot answer those questions, update the manifest before treating the component as complete.

### 4. Showcase as Product

The showcase is the primary trust surface. It should teach by showing real, polished product usage instead of dumping prop variants.

Every component page should include:

- A strong Overview example that represents the common production use case.
- One focused block per major dimension: size, state, composition, or variant.
- Snippets that compile and match the preview.
- Installation instructions for CLI-first usage.
- Props that match the actual exported API.
- Copy that explains when to use the component, not just what props exist.

## Component Addition Flow

Use this sequence for every new component or public API change:

1. **Define intent:** Write the component purpose, non-goals, expected states, and likely compositions.
2. **Check reuse:** Search existing `basic/*`, `chat/*`, and `agent-manifest.json` before creating anything new.
3. **Implement in registry:** Keep registry source standalone, tokenized, typed, and free of package-private imports.
4. **Export publicly:** Add package-facing re-exports under `src/components/` and `src/components/index.ts`.
5. **Sync registry metadata:** Regenerate and validate `registry/meta.json`; sync CLI registry copies.
6. **Teach the showcase:** Add demo blocks, config entry, props metadata, and localized page labels.
7. **Teach agents:** Add or update `registry/agent-manifest.json` with intent, states, a11y, composition, anti-patterns, and hints.
8. **Update DIP docs:** Refresh P3 headers, P2 maps, and root docs when topology or commands change.
9. **Verify:** Run the narrow checks that prove the touched surfaces are aligned.

## Quality Gates

Minimum gates for component work:

```bash
npm run check:agent-manifest
npm run check:agent-coverage
npm run check:ai-docs
npm run check:registry-meta
npm run check:registry
npm run check:showcase
npm run check:showcase-quality
npm run check:token-antipatterns
```

Before publishing or merging broad system work, also run:

```bash
npm run lint
npm run test:run
npm run build
npm run size
```

## Review Rubric

Use this rubric before calling project-wide polish complete:

| Area | Passing standard |
| ---- | ---------------- |
| Structure | Source of truth is clear; registry, CLI, package exports, and docs agree. |
| Components | APIs are small, typed, tokenized, accessible, and composed from existing primitives. |
| Showcase | Pages feel product-grade, scannable, and useful for both beginners and advanced users. |
| Docs | Guides explain decisions, not only commands; SOPs prevent drift. |
| AI contract | Manifest and token ontology make correct component selection obvious. |
| Maintenance | Verification commands prove the actual changed surfaces, not only a narrow build path. |

`npm run check:ai-docs` guards the AI-facing semantic layer: package exports,
published files, relative links, and Showcase companion pages for the operating
model, prompt recipes, and component selection guide.

`npm run check:showcase-quality` guards the public documentation surface:
registry-to-showcase coverage, demo exports, props metadata, and locale coverage.
The default props metadata baseline is 70% and should only move upward. The
Showcase registry config must not keep parallel `legacy*` maps; `categories`,
`props`, `dependencies`, and `timeline` are the single source of truth. Duplicate
component keys inside `props` or `dependencies` are blocked because they silently
overwrite documentation data.

## Anti-Patterns

- Adding a component because a demo needs one instead of validating reusable intent.
- Shipping source without CLI registry and metadata alignment.
- Updating showcase copy without updating agent semantics.
- Writing a component that looks good only in one theme or one `data-style`.
- Treating the homepage as marketing while component pages remain weak.
- Letting docs say "token-driven" while source uses raw colors or arbitrary geometry.

## Coverage Ratchet

`npm run check:showcase-quality` currently enforces a baseline for component page structure, props metadata, and locale coverage. When props tables or localized copy improve, raise the script thresholds instead of letting quality gains remain informal.

## North Star

Spark Design should help humans and agents build calm, coherent AI product interfaces. The strongest version of the project is clean enough for beginners, explicit enough for maintainers, and structured enough for AI systems to use without guesswork.