Skip to main content
Glama

<script type="module" src="https://cdn.jsdelivr.net/npm/fluxygram@0.3"></script>

<fluxy-gram src="order.flux.json"></fluxy-gram>
{
  "type": "flow",
  "title": "How an order gets processed",
  "nodes": [
    { "id": "start", "label": "Order received", "kind": "start", "icon": "cart" },
    { "id": "stock", "label": "In stock?", "kind": "decision" },
    { "id": "pay", "label": "Charge", "icon": "card" },
    { "id": "done", "label": "Delivered", "kind": "end", "accent": true }
  ],
  "edges": [
    { "from": "start", "to": "stock" },
    { "from": "stock", "to": "pay", "label": "yes" },
    { "from": "pay", "to": "done" }
  ]
}

That's a complete diagram. With no steps, it uses the default motion of its type; add steps to tell your own story.

Diagram types

Type

Explains

Default motion

flow

steps, decisions, pipelines, user journeys

the path builds column by column; a particle runs along each new edge

architecture

systems, layers, services

layers appear bottom-up, then requests travel between services

timeline

history, roadmaps, releases

the camera moves from milestone to milestone

tree

hierarchies, org charts, categories

grows from the root, level by level

cycle

loops, feedback, anything that repeats

each stage appears around the ring; at the end it all loops

sequence

API calls, logins, protocols

participants appear, then each message crosses between lifelines

mindmap

ideas around a topic, plans, syllabi

the central idea first, then one branch at a time

You can switch a diagram's type at any time without losing its nodes and connections.

Related MCP server: @excalimate/mcp-server

Telling the story

Each step says what changes:

Field

What it does

show / hide

Elements that appear or disappear

flow

A particle travels along these connections

highlight

These nodes stand out, everything else dims

focus

The camera moves in on a node or group

state

success, error, warning or pending on nodes and connections (errors shake, pending spins)

caption

The sentence under the diagram

duration

Seconds this step stays on screen

notes

Speaker notes, only visible to the presenter

motion sets the style for the whole diagram, or per block and connection: how things enter (fade, scale, draw, slide), how they travel (particle, pulse, dash, packets), the speed, and whether the camera follows the action. At the end, the camera pulls back to show the whole picture.

Full documentation at docs.fluxygram.app: every field, every type with live examples, the component API and guides. Also: SKILL.md (format and storytelling rules) and the JSON Schema.

Editor and presentation mode

fluxygram.app/play is a canvas editor that runs entirely in your browser:

  • Drag blocks from the palette, drag from a block's dot to connect it, and edit everything in the side panel (or in the JSON tab, with live validation).

  • Build the story step by step: captions, states, timing and speaker notes.

  • Open or drop a .flux.json, download it, share a link (the diagram is compressed into the URL, no server involved) or export a single self-contained HTML file.

  • Present opens the diagram full screen for your audience. Press N for a second window with your notes, the next step and a timer.

Dragging a block pins it (x, y in the JSON); everything else keeps its automatic layout.

Live status (tracker mode)

The same diagram can also show where a real process is right now: an order, a delivery, a support ticket, a job application. Your app sets the current stage; done stages turn green, the current one shows its status, and every change animates.

<fluxy-gram src="order.flux.json" mode="tracker" stage="shipped"></fluxy-gram>
tracker.setStage('delivered', 'success'); // status: pending | success | warning | error

For branches that join or processes that loop back, pass history (the stages it went through). Try the live examples in the gallery and read the tracker guide: connecting it to your data, translations, ideas.

Install

npm install @fluxygram/element
import '@fluxygram/element'; // registers <fluxy-gram>

Package

What it is

@fluxygram/element

The <fluxy-gram> web component. Works in any framework, or none

@fluxygram/core

Format, validation, layout and motion. No DOM

fluxygram

Single-file build for <script> tags and CDNs

@fluxygram/markdown

```fluxygram code blocks become diagrams. remark and markdown-it plugins

@fluxygram/astro

Astro and Starlight integration

@fluxygram/docusaurus

Docusaurus plugin

@fluxygram/mcp

MCP server for AI agents (also hosted at https://fluxygram.app/mcp)

Docs sites (Docusaurus, Astro, Starlight, VitePress, Next.js MDX) and Obsidian: see integrations.

The component picks English or Spanish from the page or browser language (the lang attribute wins when set).

For agents

The skill in skills/fluxygram teaches an agent the format, how to pick the diagram type and how to write good steps, plus a recipe for diagramming a whole codebase.

Claude Code

/plugin marketplace add Fluxygram/fluxygram
/plugin install fluxygram@fluxygram

Cursor, Windsurf, Codex, Copilot and other coding agents: save the skill in your project and point the agent at it.

MCP server (Claude, Cursor, VS Code, Windsurf, any MCP client): connect https://fluxygram.app/mcp, or run npx -y @fluxygram/mcp. The agent can then validate its diagrams and give you a link to watch them. Setup.

curl -o FLUXYGRAM.md https://fluxygram.app/skill.md

ChatGPT, Gemini, Claude.ai: the website has a "Copy prompt" button for each one that includes the whole skill; paste the answer in the editor.

Contributing

Questions, ideas and diagrams go to Discussions; bugs and concrete requests to issues. Read CONTRIBUTING.md to set up the project and open a pull request. Contributors sign the CLA once, on their first PR. Security problems: SECURITY.md.

pnpm install
pnpm dev        # site, editor and presentation mode on http://localhost:5173
pnpm typecheck

Path

What it is

packages/core

Format, validation, layout and motion. No framework, no DOM

packages/element

<fluxy-gram> web component (SVG, CSS transitions, Web Animations)

packages/fluxygram

Single-file build for CDNs

site

Landing, editor, viewer and presentation mode (Vite), deployed on Cloudflare Workers

docs

Documentation at docs.fluxygram.app (Astro Starlight), in English and Spanish

skills/fluxygram

Agent skill and examples, also a Claude Code plugin (.claude-plugin/)

License

  • packages/*, skills/fluxygram and docs: MIT. Use, embed and ship them anywhere.

  • site (landing, editor, presentation mode): FSL-1.1-ALv2. Free to read, modify and self-host for your own use; not to offer as a competing commercial service. Every release becomes Apache 2.0 after two years.

Details in LICENSE.md.


Español

Diagramas que se explican solos. Describes cualquier cosa en un JSON y Fluxygram la dibuja y la cuenta paso a paso, con movimiento que ayuda a entender.

  • Siete tipos de diagrama: flow (procesos y decisiones), architecture (sistemas por capas), timeline (historia y roadmaps), tree (jerarquías), cycle (ciclos), sequence (quién le habla a quién, en orden) y mindmap (ideas alrededor de un tema). Cada uno se mueve a su manera, y se puede cambiar de tipo sin perder el contenido.

  • Pasos opcionales: sin ellos, el diagrama usa el movimiento de su tipo. Con ellos decides qué aparece, por dónde viaja la partícula, qué se resalta, a dónde va la cámara, los estados (éxito, error, advertencia, en progreso) en bloques y conexiones, el texto de cada paso y su duración.

  • Editor visual en fluxygram.app/play: arrastras bloques, los conectas, armas la historia paso a paso y compartes un link, descargas el JSON o exportas un HTML. Todo pasa en tu navegador.

  • Modo presentación: el diagrama a pantalla completa para tu público y, con la tecla N, una segunda ventana con tus notas, el siguiente paso y un cronómetro.

  • Estado en vivo (modo seguimiento): el mismo diagrama muestra en qué etapa va un proceso real (un pedido, un domicilio, un ticket, una postulación). Tu aplicación cambia stage y el diagrama se anima: lo cumplido en verde, la etapa actual con su estado. Pruébalo en la galería y lee la guía.

  • Para agentes: la carpeta skills/fluxygram le enseña a cualquier agente a escribir diagramas. En Claude Code se instala con /plugin marketplace add Fluxygram/fluxygram y /plugin install fluxygram@fluxygram; para ChatGPT, Gemini o Claude.ai, el sitio tiene un botón "Copiar prompt".

  • Documentación completa en docs.fluxygram.app/es, con ejemplos en vivo de cada tipo.

  • Paquetes en npm: @fluxygram/element (el componente), @fluxygram/core (el formato) y fluxygram (un solo archivo para usar desde un CDN).

  • El sitio y el componente se muestran en inglés o español según el idioma del navegador.

Contribuir

Las preguntas e ideas van en Discussions y los errores en issues, en inglés o español. La guía está en CONTRIBUTING.md; en tu primer pull request firmas el CLA una sola vez.

Licencia

  • packages/*, skills/fluxygram y docs: MIT. Se pueden usar, incrustar y distribuir en cualquier parte.

  • site (landing, editor, modo presentación): FSL-1.1-ALv2. Libre para leer, modificar e instalar para uso propio; no para ofrecerlo como un servicio comercial que compita. Cada versión pasa a Apache 2.0 a los dos años.

Detalles en LICENSE.md.

Available Tools

4 tools
get_exampleGet an example diagramA
Read-only
Inspect

Returns a complete example diagram to learn from or adapt. Without a name, lists the available examples (recipes, software architecture, OAuth login, order process, timelines, live order trackers and more).

Inputs: lang, name.

get_guideFluxygram format guideA
Read-only
Inspect

How to write a Fluxygram diagram: the seven diagram types and when to use each, nodes, edges, steps with captions, motion, live status (tracker mode), icons and the storytelling rules. Call it before writing your first diagram.

Inputs: no named parameters.

validate_diagramValidate a diagramA
Read-only
Inspect

Checks a Fluxygram diagram with the same validator the viewer uses. Returns "valid" with a short summary, or every problem with its path so you can fix it. Always validate before sharing.

Inputs: diagram (required), lang.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool targets a distinct phase of the workflow: learning (get_guide, get_example), validating, and sharing. The only mild overlap is between get_guide and get_example, since both are 'learn the format' helpers, but the descriptions clearly separate syntax rules from concrete examples.

    Naming Consistency5/5

    All four tools use a clean snake_case verb_noun pattern (get_*, share_*, validate_*) with predictable get/get/share/validate semantics.

    Tool Count4/5

    Four tools is on the lean side, but the server's scope is narrow (write, validate, and share a link-embedded diagram) and each tool earns its place. No filler or duplicate tools.

    Completeness4/5

    The core lifecycle is covered: learn the format, see an example, validate with the viewer's own validator, and produce a view/editor/present link. Minor gaps exist — no tool to decode or inspect an existing share link, and no export to image/file, but agents can work around both.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers