Quick Start 2
Create a VizSpec
Define a named visualization using the VizSpec Editor — a form-driven interface with a live graph preview. No JSON editing required.
What you'll use
The VizSpec Editor at compose/vizspec/.
A saved VizSpec immediately appears as a selectable view in the Lab.
Steps
1
Open the VizSpec Editor
Click ✦ VizSpec in the top navigation.
You arrive on a blank draft. The right panel shows an onboarding guide
with three steps — it will be replaced by the live graph preview once you
complete the first two.
2
Start from a preset or load an existing VizSpec
In the Quick start section at the top of the left panel,
you have two options:
Presets — apply a bundle of defaults (color, size, panels, lenses) onto the current draft. The identity fields (id, label, dataset) are preserved. Good for quickly trying a different configuration style.
Load existing VizSpec — pull a saved VizSpec into the draft for editing. Select it from the dropdown and click Load. The draft is populated with all its settings, ready to modify and save under a new name.
Presets — apply a bundle of defaults (color, size, panels, lenses) onto the current draft. The identity fields (id, label, dataset) are preserved. Good for quickly trying a different configuration style.
Load existing VizSpec — pull a saved VizSpec into the draft for editing. Select it from the dropdown and click Load. The draft is populated with all its settings, ready to modify and save under a new name.
3
Set the identity
Open the Identity section and fill in:
ID — a unique slug used as the filename:
Label — the display name shown in the Lab's visualization selector. Example: Department Overview.
Dataset — select the dataset this VizSpec should load. The editor immediately offers only the attributes that exist in that dataset.
ID — a unique slug used as the filename:
viz-{id}.json.
Use lowercase letters, numbers, and hyphens only. Example: dept-overview.Label — the display name shown in the Lab's visualization selector. Example: Department Overview.
Dataset — select the dataset this VizSpec should load. The editor immediately offers only the attributes that exist in that dataset.
4
Configure defaults — and see the preview
Open Defaults and set:
Color by — the attribute that colors nodes by default. This field is required. As soon as you set it (and you've chosen a dataset), the live graph preview renders in the right panel.
Size by — optional. Scales nodes by a numeric attribute.
Edge opacity — a slider from 0 (invisible) to 1 (fully opaque).
Active edge layers — if the dataset has multiple edge types, choose which ones are visible by default. You can enable or disable layers individually with checkboxes.
Show edges — global toggle for edge visibility.
Color by — the attribute that colors nodes by default. This field is required. As soon as you set it (and you've chosen a dataset), the live graph preview renders in the right panel.
Size by — optional. Scales nodes by a numeric attribute.
Edge opacity — a slider from 0 (invisible) to 1 (fully opaque).
Active edge layers — if the dataset has multiple edge types, choose which ones are visible by default. You can enable or disable layers individually with checkboxes.
Show edges — global toggle for edge visibility.
5
Set the default filter attribute
Open Interactions and pick a Default filter attribute.
This pre-selects the filter attribute in the Lab sidebar, so the user lands
on the right grouping immediately. It also defines which attribute
drives the lens triggers — your filter choices in the Lab will activate
the lenses configured in the next step.
6
Enable lenses
Open Lenses. Each available lens has a checkbox and,
when enabled, a trigger selector. Assign each lens to a trigger:
You also set a default lens per trigger — the one that activates automatically when the trigger fires.
filter_1 — fires when 1 filter value is active →
good for bridge,
isolation,
periphery,
weak_tiesfilter_2 — fires when 2 filter values are active →
good for contrast,
densitynode_click — fires when a node is selected →
use for egoYou also set a default lens per trigger — the one that activates automatically when the trigger fires.
7
Configure the shell
Open Shell to control the visible UI around the graph:
Visible panels — check the panels that should appear in the Lab sidebar: Legend (color/size legend), Metrics (network statistics cards), Compute (betweenness / PageRank buttons).
Topbar — uncheck to hide the top navigation bar (useful for embed / kiosk mode).
Sidebar collapsible — whether the user can collapse the sidebar.
Visible panels — check the panels that should appear in the Lab sidebar: Legend (color/size legend), Metrics (network statistics cards), Compute (betweenness / PageRank buttons).
Topbar — uncheck to hide the top navigation bar (useful for embed / kiosk mode).
Sidebar collapsible — whether the user can collapse the sidebar.
8
Save the VizSpec
Click Save in the top bar. A modal appears:
Filename — pre-filled from the ID you set. Format:
If the file already exists, an overwrite warning appears — enable the Overwrite toggle to replace it.
Click Confirm save. The VizSpec is written to disk and immediately available in the Lab's visualization selector.
Filename — pre-filled from the ID you set. Format:
viz-{id}.json.
You can edit it, but keep the viz- prefix.If the file already exists, an overwrite warning appears — enable the Overwrite toggle to replace it.
Click Confirm save. The VizSpec is written to disk and immediately available in the Lab's visualization selector.
The Draft JSON panel
At the bottom of the left sidebar, a collapsible Draft JSON panel shows the raw JSON of your current draft in real time. You can:
- Click ↑ to expand the panel to full height
- Click ⎘ to copy the JSON to clipboard
- Edit the JSON directly in the textarea — click Apply to inject your changes into the form
The JSON panel is useful for advanced users who want to fine-tune fields not yet exposed in the form, or to copy a draft between environments.
VizSpec sections reference
| Section | Required fields | Optional fields |
|---|---|---|
| Identity | id, label, dataset | — |
| Defaults | node_color, active_edge_layers | node_size, edge_opacity, show_edges, label_threshold |
| Interactions | — | filter |
| Lenses | lenses_default (when lenses declared) | any combination of 7 lenses |
| Shell | — | topbar, sidebar_collapsible, panels, motion |
| Theme | — | any CSS custom property (e.g. --color-accent) |
Next step
Once you have two or more VizSpecs, you can assemble them into a side-by-side
multi-panel view in Quick Start 3 — Build a Cockpit.