Agent docs

Rules and artifacts for AI-assisted work on Sporting Scouter. Read these before generating UI.

Start here

• AGENTS.md (repo root) - constraints, canonical paths, composition rules.
• llms.txt - short index for agents.
• catalog.json - every published docs page with area and metadata.
• Changelog - release notes from CHANGELOG.md.
• Update consumer apps - Cursor prompt to sync a tagged release.

Authoring

• Template authoring - add a template without breaking tokens.
• MCP (future) - optional catalog server.

Non-negotiables

1. Semantic tokens only - no arbitrary Tailwind values.
2. Blue navigates, black commits.
3. Forms: formLayout() + field(); label, hint, and error from field.ts.
4. Authenticated apps: App Shell side nav - do not invent a new grid.
5. Canonical code: ui/, theme.css, site/ - not _ds_bundle or legacy styles.css.

Implementing product UI

Consumer monorepos (www, business, feedback). Copy the Cursor rule into .cursor/rules there. If a variant is missing, stop in the app and add it here using Designing a new layout below.

Cursor rule for consumer apps

When building or changing UI in this monorepo, follow the Sporting Scouter design system (https://design-system.sportingscouter.com).

1. Name the surface (review list, form, dialog, empty list, authenticated page).
2. Open that surface in the catalog: https://design-system.sportingscouter.com/catalog.json or the matching docs page. Copy the structure snippet.
3. Fill those slots with data. Keep the recipe's layout, names, and variants.
4. If the catalog has no page for that surface, compose only @sportingscouter/ui exports and theme.css semantic tokens.
5. If the snippet has no variant you need, stop. Do not invent it in the app - add it in the design-system repo first.

Before you finish:
- Classes come from recipe functions in @sportingscouter/ui.
- No arbitrary Tailwind values or palette utilities.
- Authenticated pages use appShell() with side nav.
- Forms use formLayout() + field(), with a visible label on every control.
- Read-only stars use starsFor() (whole stars). Score bar fill comes from ratingOf().
- Empty and loading states use emptyState() or asyncState().
- Do not copy demo HTML classes from the reference site (rv, b, pg).

Designing a new layout

UX and product agents working in the design-system repo when the catalog has no matching surface or variant. See also Template authoring and ui/COMPOSITION.md in the repo.

1. Confirm it is missing. Search catalog.json and Templates. Prefer extending an existing recipe or template over a new chrome.
2. Pick the page type. Authenticated UI: layout: 'app', appShell() + sideNav(). Public or marketing: layout: 'page'. Do not invent a new dashboard grid.
3. Compose with layout primitives - stack, layoutPanel, section, container, grid, formLayout, card, emptyState, asyncState. Add a new tv() recipe only when the structure repeats and cannot be a variant.
4. Add a recipe when required - ui/COMPOSITION.md; semantic tokens only; Radix for behaviour on composites; respect closed ui/GAPS.md entries.
5. Publish: nav.mjs entry, site/src/pages/<slug>.html with a structure snippet, npm run build in site/. No docs.css in product or templates.
6. Release: minor semver bump and consumer ds:sync after tag ui-vX.Y.Z (see AGENTS.md Versioning).