System Prompt

Pair this prompt with @operator-ds/manifest/components.json. It is also included at @operator-ds/manifest/agent-prompt.md.

# Building with OPERATOR (@operator-ds/react) — Agent Instructions

You are composing a UI from the OPERATOR component library. Follow these rules exactly. The machine-readable contract is `@operator-ds/manifest/components.json`: every component's props, allowed values, slots and composition rules, plus a short summary of each recipe. Treat it as the source of truth for component names, props, allowed values, slots, and composition rules. `@operator-ds/manifest/manifest.json` holds the same contract and also the complete recipe sources, which makes it many times larger: read it only when you need a recipe's files, or install the recipe with `operator-ds add <recipe>` instead.

If the project has the `operator-ds` command, use it instead of reading the contract file: `operator-ds search <need>` finds the component or recipe for a need, `operator-ds component <Name> --dense` prints one component with what each option is for, and `operator-ds check <paths>` checks what you wrote. `operator-ds init` writes these rules and a component index into your instruction file.

## Rules

1. **One canonical usage per component.** Use the `example` field in each manifest entry as the template. Do not invent alternative composition patterns.
2. **Only use props and values that appear in the manifest.** Every `variant`, `size`, etc. is an enum with a fixed `values` list. Never pass a value outside it. (In development the component prints a structured `INVALID_PROP_VALUE` error telling you the valid values — read it and correct yourself.)
3. **Flat, declarative props.** Pass data and configuration as props; do not wire up imperative logic the component already owns.
4. **Respect composition rules.** `composition_rules` and each entry's `composable_with` / `never_inside` define valid nesting. Example: a `Field` wraps exactly one form control; `CardFooter` contains `Button`/`ButtonGroup`.
5. **Interface labels render uppercase.** Component and pattern section headings, actions, tabs, short navigation/menu labels, and status badges use CSS uppercase with tracking. Write readable source text (e.g. `<Button>Deploy</Button>`); never uppercase data strings in JavaScript. Preserve body/help/error descriptions, field labels and values, names, IDs, code, and keyboard notation. In rich labels, wrap case-sensitive names in `<span className="normal-case tracking-normal">…</span>`; semantic `code`/`kbd` children preserve case automatically. Documentation page titles, navigation, and prose keep their authored case. Text-size utilities do not choose casing.
6. **Status is never color-only.** Use meaningful visible labels with `Badge`/`Alert`. `Badge appearance="text"` suits dense rows and detail panels; its wording carries the status without requiring a decorative dot or icon. Outlined badges remain available for standalone emphasis.
7. **Forms:** wrap controls in `<Field label="…">`. The control inherits id / error / description wiring from the Field — do not duplicate `id`/`aria-*`.
8. **Record details:** use `EntityPreview` for identity, facts, condition, and report quality in popovers, inspectors, and pages. Use `DescriptionList layout="details"` for smaller metadata groups and measurements. `OperationalStatus` shares that label-left/value-right layout for quality, source, and update time. Preserve supplied names, IDs, units, timestamps, and unknown states. Keep entity condition separate from data quality.

## Typography setup

Import `@operator-ds/tokens` at the application root and register the `@operator-ds/tailwind` plugin. The token import includes the bundled OPERATOR Sans and OPERATOR Mono variable fonts, with upright and italic faces at weights 300–700. Tailwind `font-sans` and `font-mono` resolve `--oprt-font-sans` and `--oprt-font-mono`; no application-specific font-family overrides are needed. Their CSS family aliases are `Operator Sans Family` and `Operator Mono Family`.

When importing token entry points selectively, also import `@operator-ds/tokens/fonts` once. Projects using standalone font downloads can load the included stylesheet instead. Use upright Sans for interface text and Mono for code, identifiers, and aligned data; disable programming ligatures in code and data roles. These Geist-derived fonts remain development candidates, with qualification limits documented in the bundled source notices. Preserve the included SIL Open Font License and attribution when redistributing fonts.

## Borders

Layout lines (tables, tabs, cards, dividers, panels) use `border-oprt-border`, which is deliberately quiet. `border-oprt-border-control` is the token for the boundary of anything a user clicks or types into (inputs, selects, checkboxes, radios, toggles, secondary buttons): it keeps at least 3:1 contrast against the surface it sits on. The components adopt it during the Stage 1 quality pass, so a control from this package may still draw its boundary with `border-oprt-border` for now. When you write a control's boundary yourself, use `border-oprt-border-control`; never use `border-oprt-border` as a control outline.

## Reading the manifest

Each component entry (the same shape in `components.json` and `manifest.json`) has: `description`, `props` (each with `type`, and for enums `values` + `default`), optional `slots`, `composable_with`, `never_inside`, and a copy-paste `example`. A `union` prop lists its allowed shapes in `types`; read its description to choose the shape required by the mode.

## Using a pattern recipe

`patterns` contains the copyable application recipes and their current dependency lists. `Object.keys(patterns)` is the complete, current inventory. In `components.json` each recipe has its description, `layout`, `dependencies`, the size of each file and the `operator-ds add` command that installs it; `manifest.json` adds the complete sources.

- A recipe is not an export of `@operator-ds/react`. Its `layout` shows the canonical local import and usage after copying its source.
- Copy every entry in `files` (from `manifest.json`) into your application's component directory, using each key as its relative destination and its value as the complete file contents. Preserve the directory structure so relative imports continue to resolve. A recipe's `files` already include the shared helpers and nested modules it imports.
- `dependencies` lists packages imported by those files. Use the existing OPERATOR token CSS, operational token CSS, and Tailwind preset setup; these are styled React recipes, not standalone CSS bundles.
- `composed_of` lists the core manifest components used by the recipe and its local dependencies. Consult their canonical APIs when adapting the recipe.
- These recipes use labeled training data and local demonstration state. Replace sample arrays, timestamps, and callbacks with application-owned data and handlers. No recipe supplies a live telemetry hook, backend connection, delivery guarantee, or operational freshness policy.
- Keep visible labels alongside status colors, UTC time labels, keyboard controls, loading and empty states, and explicit unavailable/stale states when connecting real data.

## Self-correction loop

When you render in a dev environment and see a JSON error like:

```json
{
  "component": "Button",
  "error": "INVALID_PROP_VALUE",
  "prop": "variant",
  "received": "success",
  "valid_values": ["primary", "secondary", "tertiary", "danger"],
  "suggestion": "… use Badge for status display."
}
```

…replace the offending value with one from `valid_values` (or follow `suggestion`), then re-render.

Build in layers: foundations define appearance; core controls define shared interactions; larger components reuse those controls; patterns consume public APIs. Use Chart for native OPERATOR SVG visualization, DataGrid for controlled table workflows, and SplitPane/TimeRange/EventTimeline for coordinated workspaces. Do not copy private component internals into patterns.