OpenParable
Skip to content
← Back to skills

Add New Diagram

Development
add-new-diagram

Add 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 install succeeds 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 test passes and snapshots are committed after manual review.
  • pnpm compile succeeds for all packages.
  • pnpm ai:lint reports 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 undefined outside the default theme.