Quick start
Three steps. None of them block on the others.
step 01
Connect the MCP
Add the server to your assistant via the Connect page. Takes ~30 seconds.
step 02
Browse the playground
Open the playground, drag a control, watch the code update live.
step 03
Copy code + pitfalls
Use the 📋 Copy for AI button. Paste into your assistant.
Single-source data model
Every animation lives in content/animations/<id>/. Three files, no duplication. The site, the MCP server, and the verifier all read from the same generated catalog.json.
source
animations/<id>/
├ meta.yaml
├ main.dart
└ bad.dart
hand-edited
one PR per change
→
verify + build
dart format
flutter analyze
flutter build web
→ catalog.json
CI runs monthly
+ on every commit
→
consumers
● site — playground
● MCP — 4 tools
● verifier — status
all read the
same catalog
The three source files
meta.yaml — id, title, category, difficulty, tags, summary, verifiedOn, and a pitfalls array (claim, fix, source, confidence). Hand-edited; the schema is enforced in CI.main.dart — the canonical good example. Must pass dart format, flutter analyze, and build for web. This is what the site compiles a self-hosted preview from.bad.dart — a counter-example demonstrating each pitfall. It compiles but intentionally violates the lints — that's the proof the pitfall is real.
Pitfall confidence levels
Every pitfall carries a confidence pill. Higher confidence ⇒ more weight when an agent (or you) decides whether to act on it.
official-docs Source links to api.flutter.dev or flutter.dev. Highest confidence — the framework owns the claim.
measured There's a benchmark or DevTools timeline backing the claim. Reproducible from bad.dart.
github-issue Tracked in flutter/flutter or a maintained package's issue tracker. Linked directly; re-checked monthly.
community-consensus Multiple independent sources (Discord, Stack Overflow, blogs) agree. We cite the strongest one.
author-experience A maintainer hit it in production. Lowest confidence — take it as a heads-up, not a rule.
Contribute an animation
Fork, add a directory under content/animations/, open a PR. CI runs the verifier on your branch — once everything's green, a maintainer reviews the pitfalls.
Quality checklist
The PR template includes this. None of it is optional.
☐ meta.yaml validates against the schema
id (== folder), title, category (one of the 7), difficulty 1–5, tags[], summary, verifiedOn, and a pitfalls array (claim, fix, source, confidence). The schema is enforced in CI.
☐ main.dart passes the machine gate
dart format --set-exit-if-changed · flutter analyze (very_good_analysis) · flutter build web. This is what the site compiles a self-hosted preview from.
☐ bad.dart compiles (and shows the wrong way)
A counter-example demonstrating the pitfalls. It only needs to build — it intentionally violates lints, proving the pitfall is real, not theoretical.
☐ At least 3 sourced pitfalls
Each with claim, fix, source, and an honest confidence level. Prefer official docs; label experience-based ones as author-experience.
☐ provenBy points to a real test (when used)
If a pitfall claims a leak/state bug, back it with a test file under test/ — build-catalog fails if provenBy points nowhere.
☐ Verified on the current Flutter stable
meta.yaml verifiedOn names the SDK you verified against (e.g. Flutter 3.32 / 2026-06). CI re-runs monthly to catch deprecations.
☐ Summary explains why, not how
One or two sentences answering "when would I reach for this?" — the code already shows how.