Convention: Playground Data Contract Comments

convention-playground-data-contracts Convention

active convention frontend

Project

Purpose

Every playground HTML file must have an  data contract comment block after the <body> tag. This is the bridge between visual prototype and SvelteKit production — it tells dev agents exactly what data, state, and API calls each page needs.

Format

Sections

Section	Purpose	Consumer
<code>@route</code>	SvelteKit path	Dev agent, QA
<code>@auth</code>	none / required / role:admin	Dev agent
<code>@complexity</code>	low / medium / high	Planning
<code>@api</code>	Every endpoint + what it returns	Dev agent, QA
<code>@state</code>	Reactive variables + where they come from	Dev agent
<code>@interactivity</code>	What user actions trigger	Dev agent
<code>@variants</code>	Visual states: what changes per data state. HTML shows most complex variant; others described as deltas. Dev agent writes {#if}/{:else} from this.	Dev agent, QA, Design review
<code>@gaps</code>	Backend work needed before page works	Planning
<code>@notes</code>	Edge cases, navigation, gotchas	Everyone

Complexity Scale

low — fetch + render, no writes (landing pages, read-only lists, auth redirects)
medium — form submit + navigation, single API write, client-side filtering
high — multi-step state, optimistic updates, device APIs, Stripe integration, role-based visibility

Rules

Comment goes immediately after <body> tag, before any content
@ prefix makes sections greppable: grep '@gaps' *.html
Every playground repo follows this format: westside-playground, mcd-tracker-playground, etc.
QA agents verify: every @api endpoint is called, every @state variable is bound
@gaps = pre-promotion backend TODO list. No promotion until gaps are resolved.

Pipeline

Playground HTML + @comments ← design + spec locked together
app.css copy + HTML→Svelte ← agent reads @api, @state, @interactivity
docker compose up ← test against @api endpoints locally
QA checks @api vs actual calls ← automated verification
Production ← confidence