Turn natural-language intent and grounded data into SVGs that are beautiful to people and addressable by machines.

Semantic SVG is an open-source LLM skill plus deterministic compiler. The LLM directs the story and visual grammar; the compiler owns coordinates, XML, stable IDs, provenance, and verification. The finished file can be read as a poster, inspected as structured data, and enlarged without losing detail.

The five-second showcase plays automatically and loops directly in this README.

The example above contains 504 visible detail rows, 2,520 atomic fields, and 2,648 text elements in one black-and-orange SVG. Small type is intentional: it stays non-overlapping and becomes fully readable when the vector is enlarged.

Open the 35-second workflow video

The autoplay preview gives the first read immediately. The longer recording shows the real artifact at multiple zoom levels: a human can scan the whole composition, then inspect individual labels, types, sources, and machine-addressable IDs.

Raw LLM-generated SVG tends to produce fragile XML, invented labels, drifting coordinates, and text collisions. Semantic SVG separates creative judgment from deterministic execution:

natural-language brief + grounded data
                  ↓
        story and visual grammar
                  ↓
     ArtifactSpec or detail inventory
                  ↓
       deterministic SVG compiler
                  ↓
 semantic QA + browser render + zoom review
                  ↓
          finished semantic SVG

Every meaningful object can carry id, data-node-id, data-edge-id, data-source-ref, coordinates, relation types, and embedded JSON metadata. The picture remains a real picture; the data remains queryable.

For 8-30 high-salience concepts. It emphasizes hierarchy, graph paths, annotations, metrics, and a strong first read.

npm run build:example

Open examples/knowledge-atlas.svg.

For hundreds of details that must coexist without collision. It uses fixed row and column geometry, clipped text regions, stable identifiers, and zoom-native reading.

npm run build:image-wall

Open examples/opencrab-image-intelligence-evidence-wall.svg. Its example data comes from seven image-related ontology packs, but the renderer itself does not require OpenCrab.

Node.js 20 or newer is required. The current core has no runtime dependencies.

git clone https://github.com/AlexAI-MCP/semantic-svg.git
cd semantic-svg
npm test
npm run build:example
npm run preview

Visit http://127.0.0.1:4175/ for the local preview.

Install it as a local Codex skill:

git clone https://github.com/AlexAI-MCP/semantic-svg.git ~/.codex/skills/semantic-svg
cd ~/.codex/skills/semantic-svg
npm test

Codex can then load the root SKILL.md as semantic-svg while keeping the compiler, fixtures, and verification scripts beside it.

Build a custom artifact:

node ./bin/semantic-svg.mjs build ./my-artifact.json \
  --out ./my-artifact.svg \
  --report ./my-artifact.qa.json

Validate an existing result:

node ./bin/semantic-svg.mjs validate ./my-artifact.svg \
  --spec ./my-artifact.json

Give SKILL.md to a skill-capable coding agent and ask naturally:

이 CSV의 사업 흐름을 검정과 오렌지만 사용한 세로형 SVG로 만들어줘.
전체 구조는 한눈에 읽히고, 확대하면 모든 세부 행의 값과 출처를 읽을 수 있어야 해.
각 항목에 안정적인 ID와 sourceRef를 남기고 글자 겹침을 검사해.

The skill turns that request into a repeatable production loop. It supports supplied JSON, CSV, GeoJSON, graph exports, database snapshots, or any normalized local data.

OpenCrab is an optional source adapter, not a dependency. adapters/opencrab.example.mjs maps an already-authorized pack snapshot into ArtifactSpec without making network calls.

When the adapter is used:

• authorization and pack selection happen outside the renderer;
• package IDs and evidence references remain provenance, not decoration;
• private evidence is excluded from public artifacts by default;
• the same compile, semantic QA, render, zoom, and revision gates still apply.

Semantic SVG works exactly the same way without OpenCrab.

ArtifactSpec is the contract between an LLM and the renderer. It contains:

• meta: title, audience, summary, source label, and provenance;
• metrics: grounded visible values;
• nodes: stable IDs, labels, groups, values, and optional coordinates;
• edges: typed, directed, evidence-linked relationships;
• annotations: concise explanations connected to semantic objects;
• timeline: ordered process or decision stages;
• style: preset, palette, and motion preferences.

See schema/artifact-spec.schema.json and examples/knowledge-atlas.json.

A successful CLI exit is not visual proof. Release requires:

1. deterministic compile;
2. XML and semantic validation;
3. stable and unique machine IDs;
4. browser rendering at wide and narrow viewports;
5. 100% zoom inspection for composition;
6. enlarged inspection for small-text readability;
7. text collision, clipping, contrast, and empty-region review;
8. revision when any gate fails.

The evidence-wall fixture additionally checks the four-times information-density target and the exact black/orange palette.

bin/                 CLI
src/                 compiler, layout, spec, validator
schema/              ArtifactSpec JSON Schema
examples/            grounded specs, SVGs, inventories, QA reports
adapters/            optional source integrations
scripts/             evidence-wall builder and local preview
docs/assets/          README image and workflow video
test/                 deterministic, semantic, density, and palette checks
SKILL.md              LLM operating instructions

Contributions are welcome for visual presets, maps, matrices, evidence chains, font metrics, overlap validators, accessible palettes, international text layout, and adapters for CSV, GeoJSON, graph databases, and ontology packs.

Every rendering contribution should include a grounded input, generated SVG, QA report, and browser screenshot. See CONTRIBUTING.md.

The MIT-licensed core includes the skill, spec, compiler, validator, presets, examples, and local adapters. Future hosted services may add private connectors, collaborative review, managed batch rendering, visual regression infrastructure, and template distribution without removing core local functionality.

MIT