technicaldiagrams.comv0.1 · visual references for agents

Contributors and contribution process

Tom Granot defines the product direction and maintains the project. Codex authored the initial implementation, sample scenes, documentation, and provisional scores. AI authorship is recorded separately from human review.

The source repository is public. Fork it and open a pull request, or file an issue for a bug or missing diagram form. The site also exposes the catalog and example scene JSON so you can customize an example without cloning the repository.

Add an existing diagram form

  1. Find the closest family in src/lib/catalog.ts. Add a family only when the existing taxonomy cannot describe the form.
  2. Add a recipe with a stable ID, short description, specific useWhen and avoidWhen, primitive list, and accessible scene description.
  3. Build the example from the existing five primitives. Keep synthetic data labeled.
  4. Add scores with a rationale, reviewer context, date, and revision. Use the rubric.
  5. Run npm test and npm run build.
  6. Inspect the gallery preview, full-size recipe, and exports in light and dark themes. Check 320, 375, 414, 768, and desktop widths.
  7. Update the changelog and any documentation whose behavior changed.

The gallery, recipe page, API endpoints, and rankings derive from the catalog. New entries appear in those surfaces at build time.

Improve the primitive layer

Add a primitive only when existing shapes cannot express the required operation cleanly. Update the TypeScript union, parser allowlist, renderer, tests, and primitive reference together. Do not introduce arbitrary SVG or HTML execution through JSON.

When making a structural edit, test its effect on related labels and connectors. A node is a composition, not a layout constraint: moving its box alone will leave its text behind.

Revise a score

Export a local review and attach before/after screenshots to the change. Record the previous and new scores in docs/score-history.md, increment the recipe revision, and explain the observed difference. A score change should identify the example revision and viewport inspected.

Documentation ownership

The website reference pages come from src/content/docs/*.md. The README introduces the repository. CONTRIBUTING.md describes the local workflow, CONTRIBUTORS.md credits people and AI assistance, and docs/ stores release and review evidence.

Keep the API, website, and README aligned with the implementation. Do not claim runtime execution, shared scoring, a published package, or automatic layout until those features exist.

License and credits

The project’s original code, scenes, and documentation use the MIT License. Contributions use the same license.

Hanken Grotesk and IBM Plex Mono retain their SIL Open Font License 1.1 terms. Read the Hanken Grotesk notice, IBM Plex Mono notice, and third-party credits.