Add New Diagram
Developmentadd-new-diagramAdd New Diagram is an Agent Skill for development published in the hikerpig/pintora repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when adding a new diagram type to Pintora. Covers parser, artist, config, registration, snapshot tests, and user docs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/hikerpig/pintora/blob/HEAD/.ai/skills/add-new-diagram/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-new-diagram, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add a New Diagram Type
Preconditions
pnpm installsucceeds locally and the workspace builds.- You have read:
packages/pintora-diagrams/AGENTS.md.ai/docs/patterns/diagram-three-piece.md
Steps
1. Create the directory
mkdir -p packages/pintora-diagrams/src/<type>
2. Write the grammar
Create packages/pintora-diagrams/src/<type>/parser.ne. Use packages/pintora-diagrams/src/sequence/parser.ne as a reference.
3. Compile the grammar
pnpm --filter @pintora/diagrams gen-parser
This produces parser.ts alongside parser.ne. Commit both.
4. Write the artist
Create packages/pintora-diagrams/src/<type>/artist.ts. Use packages/pintora-diagrams/src/mindmap/artist.ts as a minimal reference or packages/pintora-diagrams/src/sequence/artist.ts as a full-featured one.
Rules:
- Read colors from
getConfig().themeConfig. Never hard-code hex values. - Emit relative coordinates. Avoid baked-in pixel offsets.
5. Write the config
Create packages/pintora-diagrams/src/<type>/config.ts exporting DEFAULT_CONFIG, configKey, and the config type. If new theme tokens are introduced, also update packages/pintora-core/src/themes/default.ts and any other theme variants.
6. Register the diagram
Create packages/pintora-diagrams/src/<type>/index.ts:
import { pintora } from '@pintora/core'
import parser from './parser'
import artist from './artist'
import { DEFAULT_CONFIG, configKey } from './config'
pintora.registerDiagram('<type>', {
parser,
artist,
configKey,
})
Re-export from packages/pintora-diagrams/src/index.ts (and from packages/pintora-standalone/src/index.ts if standalone needs to ship it).
7. Add a snapshot test
Create packages/pintora-diagrams/src/__tests__/<type>.spec.ts modelled on the existing per-diagram spec files in that directory.
Run the suite:
pnpm --filter @pintora/diagrams test -- <type>
Review the generated snapshot manually before committing it.
8. Add user documentation
Create website/docs/diagrams/<type>.mdx following the structure of website/docs/diagrams/sequence-diagram.mdx. Add a note at the top linking back to this skill for contributors.
9. Verify in the live editor
pnpm demo:dev
Open the demo, pick the new diagram type, and confirm it renders.
Done criteria
pnpm --filter @pintora/diagrams testpasses and snapshots are committed after manual review.pnpm compilesucceeds for all packages.pnpm ai:lintreports no new warnings.- Live editor renders the new diagram.
Common pitfalls
- Forgetting to rebuild grammar after editing
parser.ne— symptoms are stale parser errors. - Hard-coding theme colors — breaks dark mode.
- Skipping the standalone re-export — the diagram works in tests but not in the standalone bundle.
- Adding a config field without updating other themes — the field is
undefinedoutside the default theme.