@gum-jsx/docs

Guides, element references, and runnable JSX examples for Gum. Consumers can use getGuides() for conceptual documentation and getGallery() for visual examples grouped by category. Gum Studio presents guides and element references at /gum/docs, and a searchable figure grid at /gum/gallery. getTopics() remains available as a combined guide and gallery catalog. The legacy topics/* package subpath maps to gallery files; guide files use the new docs/guides subpath and snake_case names. Content lives under docs/elements, docs/guides, and docs/gallery.

See the Gum project for getting started and the package overview.

Start reading

Start with Gum, units, and sizing.

Positioning explains pos, anchor, coordinate systems, and placement of whole containers.

Grid shares column widths across rows; TextGrid adds text conversion and spacing defaults.

Basic plotting is available: start with Plot, Graph, and SymLine, or try the curve and band, bars, and vector field showcases. The editor includes a Plotting category alongside layout, geometry, and text.

Network connects Node frames, or any other element with an id, using Edge arrows, including nodes inside fitted and rotated layouts. The editor's Networks category includes runnable examples of each.

Math helpers, arrays, vectors, colors, and seeded random data are built into JSX and exported for host code. The examples use these helpers directly.

Math authoring covers TeX and composable math elements. The editor includes a Math category with element references and topics for standalone exports, plot labels, and slides. Render formulas through Tex/Latex in a JSX file with gum, or use the math export library helpers. The gum-tex executable has been retired.

Maps gallery

Start with Making maps for a source-to-annotation walkthrough, then use the GeoMap reference for the full property list and helper details.

The Maps category contains six standalone figures backed by @gum-jsx/maps:

• World countries: ID-keyed country fills and shared borders.
• Projection gallery: four projections of the same atlas.
• US states: FIPS IDs and Albers USA insets.
• Projected city markers: matching overlays and globe clipping.
• Selected-region fit: a regional view with a projected route.
• GeoJSON edge cases: inline fixtures with holes and antimeridian cuts.

The CLI includes maps by default. From the workspace root, render an example with:

bun gum-jsx-cli/src/cli.ts gum-jsx-docs/docs/gallery/code/world_choropleth.jsx -o /tmp/world.svg

Content structure

The three reference collections use the same paired-file structure. Focused visual regressions live beside them and need code only:

docs/
  elements/
    text/<Name>.md     Element reference with YAML metadata
    code/<Name>.jsx    Self-contained, runnable element example
  guides/
    text/<name>.md     Conceptual guide; snake_case filename
    code/<name>.jsx    Self-contained, runnable guide example
  gallery/
    text/<name>.md     Visual example explanation
    code/<name>.jsx    Self-contained, runnable gallery example
visual-tests/
  code/<name>.jsx      Focused visual regression case
src/                  Read-only catalog and page loaders
src/skill.ts          Shared prompt and reference assembly for the plugin and MCP
test/examples.ts      Validate links, coverage, and rendering at several widths
test/skill.test.ts     Test skill content and documented Gum CLI commands
test/plugin.test.ts    Test plugin builds and ZIP packaging
prompt/               Maintained Gum authoring and skill prompt pieces
scripts/plugin-build.ts Generate the skill inside the plugin
scripts/plugin-pack.ts  Rebuild the plugin skill and package the plugin ZIP

There is no viewer, server, or Markdown renderer in this package. gum-jsx-edit's /docs route consumes the catalogs to show SVG cards and editable, live-rendered code/figure popups. There are no runtime package dependencies; gum-jsx-core, gum-jsx-math, and gum-jsx-maps are development dependencies for checking examples.

Every reference Markdown file starts with YAML front matter containing a category and a one-sentence description. The catalog uses these fields for grouping and skill reference indexes; neither appears in the rendered page body. For example:

---
category: layout
description: "Explain flex sizing, wrapping, and alignment in HStack and VStack."
---

# Stacks

bun run test renders all examples with the same 640 × 480 offer used by the CLI and previews, then checks 320, 480, 640, and 960px widths with natural height. It also exercises max_width / max_height wrapper props at five landscape and portrait sizes, including 240px-wide and 240px-high previews. It checks finite geometry and nonempty plot data areas at the default offer. Small previews may clip or crowd content. Regression checks also preserve comparison rows and verify that larger hosts do not widen content-sized figures with empty space. Whole-scene fit examples are checked in fixed rectangles. Standalone figures can set a design height, aspect, and font size; Studio scales the completed SVG for display. Compact content may hug its children, and adaptive layouts can use fill or wrapping when the composition calls for it.

Build the plugin

The Gum plugin lives in the top-level gum-jsx repository and combines authoring prompts with the layout, units, JSX, CLI, and rendering references. Its skill uses the gum commands directly when @gum-jsx/cli is on PATH, with workspace scripts as an alternative. From the workspace root or this package directory:

bun run plugin:build
bun run plugin:pack

plugin:build writes plugins/gum-jsx/skills/gum-jsx/SKILL.md and its references in the top-level repository. plugin:pack rebuilds that directory and creates dist/gum-jsx-plugin.zip in the top-level repository, with the plugin manifest at the archive root. Packaging requires the zip executable; building the directory alone does not. The scripts remain in gum-jsx-docs/scripts/.

The plugin directory is the sole generated authoring-skill output. Commit its generated skill files in the top-level repository, and commit maintained prompt and documentation changes in gum-jsx-docs. This lets GitHub marketplace installations include the complete plugin. The ZIP remains ignored by Git and can be attached to a release. Rebuilds replace the generated skill directory, so make edits in prompt/ and docs/ rather than in that output.

The entrypoint is assembled from head, intro, docs, refs, gen, and cli. It keeps the essential authoring rules together and links to generated indexes for guides, elements by category, and gallery figures. Element and gallery text and code are combined into one reference file per category; guides keep their own files. Every current page and runnable example is included, with local links rewritten to the relevant entry or embedded JSX example. The separate PDF package's API link points to its upstream README. The generated reference indexes include each page's description alongside its link.

The scripts read this package's inputs and write to the parent workspace, independently of the caller's working directory. Run them from a full gum-jsx checkout. From the workspace root:

bun gum-jsx-docs/scripts/plugin-build.ts
bun gum-jsx-docs/scripts/plugin-pack.ts

getSkillPrompt() returns the shared authoring instructions without frontmatter or CLI setup; pass { cli: true } to append the CLI workflow. buildSkillFiles() adds frontmatter and the linked reference pages, enabling CLI instructions by default. It only assembles content in memory; scripts/plugin-build.ts writes the plugin's skill directory. Tool-based hosts can use buildSkillFiles({ cli: false }) and mapSkillLinks() to adapt reference links without rewriting fenced examples. The MCP server uses this shared assembly and appends its rendering-tool prompt.

Consumers can also read individual pieces through the exported promptDir or @gum-jsx/docs/prompt/* subpath. Studio's own chat prompt and tool wiring remain separate from this portable skill.

bun run test also tests skill coverage, link reachability, prompt-example rendering, plugin rebuilds and packaging, and CLI behavior. Archive tests require zip and unzip.

Elements

• Layout: Svg, Box, Frame, Fitting, HStack, VStack, Spacer, and Group.
• Geometry: Rect, RoundedRect, Square, Circle, Ellipse, Line, Polyline, Polygon, and Path.
• Text: Text, Span, Bullets, and Slide.
• Networks: Network, Node, and Edge.
• Maps: GeoMap.
• Math: Latex, Tex, MathText, MathSymbol, MathSpan, MathRow, MathCol, MathBox, MathSpacer, and MathRule.

Gallery and guides

• Getting started: Gum, JSX, Units, Sizing, Style, and CLI.
• Geometry and layout: Positioning, Point values, Coordinates, Projections, and Stack.
• Embedding: Rendering, Custom elements, and Fonts.
• Numeric helpers: Math, Arrays, Vectors, Colors, Random.
• Maps: Making maps covers sources, styles, views, and projected annotations; Map routes nests a sampled Arrow inside GeoMap. Filtering and bounds selects country IDs while keeping a fixed longitude/latitude view.

Showcases

• Pendulum Physics: parameter-driven geometry, force arrows, and a math caption, ported from the old gallery.

• Particle in a Box: offset wavefunctions, hatched walls, and math labels, ported from the old gallery.

• Transformer Architecture: nested blocks with boundary-attached connections, ported from the old gallery.

• Two columns: an explicitly allocated figure and paragraph.

• Shape cards: reusable components and nested stacks.

• Positioned diagram: labels, nodes, and connectors using Group.

• Sampled curve: function sampling with SymLine.

• Layout choices: natural sizing versus explicit flex.

• Typography card: mixed fonts, wrapping, and preformatted text.

• Arrow caps and tips: thick shafts, fixed tips, and straight/curved/rounded routes.

• Flex limits and shrinkage and stack alignment: capped growth, shrinking, baselines, and stretch.

• Nested anchors, canvas clipping, and rounded box clipping: positioning and visible overflow.

• One paragraph, two widths and line boxes and baselines: measured text geometry.

• Reusing fragments and clipping and transforms: custom parent layout and placement.

Old gallery ports

All 25 examples from the old gum-jsx-docs/gala collection now have runnable sources and explanatory pages here. Alongside Pendulum Physics, Particle in a Box, and Transformer Architecture, the remaining ports are:

• Plotting: Axes with Arrows, Flux Capacitance, Complex Roots, Slick Bars, The Nexus, Manual Plot, Atomic Orbitals.
• Geometry: Spline Star, Metal Grid, Set Theory, Regular Polygons, Neon Rose, Space Rose, Anatomy of a Cell.
• Text: Punk Rock.
• Layout: Two Columns, UI Mockup.
• Networks: Macroeconomic Flows, Unit Distance, Any element as a node.
• Math: Shape Algebra, The Scenic Route, Stokes’ Theorem.

These examples use the current layout engine, data-coordinate marks, and shared palette. See the workspace feature map for planned work.

Run an example

From the parent gum-jsx workspace:

gum gum-jsx-docs/docs/guides/code/gum.jsx
gum gum-jsx-docs/docs/gallery/code/two_columns.jsx -o /tmp/two-columns.svg
gum gum-jsx-docs/docs/gallery/code/two_columns.jsx -o /tmp/two-columns.png --ratio 2
gum gum-jsx-docs/docs/elements/code/VStack.jsx -f tree --stats
bun --filter @gum-jsx/docs test
bun run visual-test
bun run typecheck

The CLI defaults to kitty graphics; use SVG or PNG output on other terminals. Examples use the current evaluator's bindings. Set size and font props on the figure itself or on an explicit Svg wrapper. Hosts add an Svg viewport when the example returns a bare element and preserve an explicit Svg root. No legacy packages, image files, custom fonts, network fetches, or generated assets are required. The test command renders SVG in memory and leaves the checkout unchanged. The workspace visual-test command renders every element example, every topic example, and every focused regression into a searchable standalone HTML report at gum-jsx-cli/visual-report/dist/index.html. Core behavior tests and synthetic layout fixtures remain in gum-jsx-core. The former core examples are consolidated into these collections; equivalent examples share one docs source, and previews are generated on demand.

Performance demos

Run bun run perf:demos from this repository or the workspace root to benchmark every JSX file under demos/. The suite measures evaluation, layout, SVG serialization, and complete renders separately. Use --smoke for a quick check, --filter '^demos/render/' for complete renders, and --json for saved results. See the workload notes for timing boundaries.

Load the content

Use these filesystem loaders in Bun, not in a browser bundle:

import {
  getElements, getGuides, getGallery, listElements, getElementText, getElementCode,
  prepareElementPage, elementsCodeDir,
} from '@gum-jsx/docs'

const { tags, cats, text, code } = getElements()
const page = prepareElementPage(text.Box!, code.Box!)
const entries = listElements() // { name, title, cat }[]
const guides = getGuides()    // { tags, cats, text, code }
const gallery = getGallery()  // { tags, cats, text, code }
const onePage = getElementText('Box')
const oneExample = getElementCode('Box')

getTopicText/getTopicCode, listTopics, prepareTopicPage, and the original topics directory aliases are also exported. Names are basenames, not paths. Catalog calls discover matching files each time; single-page reads do not load the rest of the collection. Text loaders remove optional machine-readable category lines. Page preparation appends a fenced JSX example and preserves relative Markdown links.

Categories are core, layout, geometry, plotting, maps, networks, text, math, api, and special. Every page needs YAML front matter with category and description. A Markdown viewer should resolve relative links against the original text file and map them to its own routes, rather than requiring routes in the content. Raw files are exposed through the ./docs/elements/*, ./docs/guides/*, and ./docs/gallery/* package subpaths.

Contributing

Add a Markdown page and same-named JSX file together. Begin the JSX with a short comment describing what it demonstrates. Prefer explicit sizes where allocation would otherwise be ambiguous and keep text readable. For examples with text, set the base font-size in pixels on Svg, then use em(...) for descendant font sizes, gaps, and padding. Elements with their own font defaults, such as Plot and Slide, need an explicit relative font-size to follow that base. Strokes, borders, corner radii, and fixed geometry can use pixels. Plot domain padding remains fractional. Run bun run test and inspect a PNG when changing a visual example.

These docs describe implemented behavior, not feature parity with old Gum. Development history and the porting inventory remain in the parent workspace's design, roadmap, and feature map.