graview-lens
graview-lens is one of Graview's 31 authoring skills: instructions an AI coding assistant such as Claude Code or Codex reads before it changes a Graview app. What it teaches: Build a Graview lens that binds ROLES rather than field names, so a second domain can reuse it unchanged — and prove the reuse rather than asserting it.
Installed into a project by graview skills install ., and read by whichever assistant is working beside you.
The skill
Build a lens
A lens is a picture that knows nothing about your domain. The timeline does not know what a duty is; it knows there is a start, an end and a column. The coverage matrix does not know what a requirement is; it knows there are rows, columns and an edge that fills a cell. That indirection is the entire point: a lens written for one app is used unchanged by another.
The framework ships five, each built from the public primitives — which makes them the worked example of the authoring API. Read one before writing your own:
packages/primitives/src/lens/timeline.tsx— intervals in columnspackages/primitives/src/lens/calendar.tsx— the same intervals, by datepackages/primitives/src/lens/coverage.tsx— a bipartite mappingpackages/primitives/src/lens/board.tsx— position given by the domain (discs for codes of three characters, tokens for words;arrange: "shelf"when the x and y are categories rather than coordinates)packages/primitives/src/lens/plan.tsx— an outline, with points inside it
(reach.tsx beside them is a view, not a lens: no roles to rebind.)
Read the plan if yours draws anything: a name is fitted to its shape at a height (fitLabel, spanAt from @graview/layout), names are painted last, what will not fit goes in a key, and useDrawnSize asks whether, at THIS size, a person can read it or press it.
Start it with the scaffolder — `graview lens grounds-map --roles regions,markers
--binds entities` — which writes all eight rules below already in place, and the reuse test beside it, red on purpose.
Do this
- Name the roles, not the fields. A lens declares
requiredRoles: ["start", "end"]; an app says which of ITS fields fill them. If your lens namesdutyIdanywhere, it is not a lens.
- Choose which shape of binding you need. There are two, and assuming there was one is how the first version of this got it wrong: - fields — a kind's own field names onto roles (
{ session: { start: "start", end: "end" } }). The timeline. - entities — roles onto whole kinds and edges ({ rows: { kind: "skill" }, link: { edge: "develops" } }). The matrix. A relationship that IS a node — a person's strength in a skill — bindslink: { path: ["inSkill", "has"] }, column end first; each cell carries the nodes it walked through: choosing it selects its row, its column and them, anddescribePlacesays each row's columns through them.
- Fail loudly on a bad binding. Throw a named error saying which role and what was missing. A lens that renders empty when misbound costs an hour. Loud means THE PANEL SAYS SO: every view host sits behind an error boundary, so a throw draws its message in the view's place, named with the kind and the view, and the rest stands. Give the error a
hintproperty and the panel prints it under the message, which is where a sentence about what to bind instead belongs.
- Mark every real thing as a target. Anything standing for a node gets
data-graview-pick={id}. That one attribute is the whole contract: the host routes a click on it to that node, gives it a tab stop and a role, and a single click selects it in place while a double click travels. A span you cannot click is the bug this prevents.
Drawing in SVG? The framework sets the role; you set the aria-label. A <g>, <polygon>, <circle>, <rect>, <path>, <ellipse>, <polyline>, <line> or <use> carrying the mark becomes a button like any <span>, but a shape has no text to be named by: unlabeled, it is a stop that announces nothing. Name it after the thing it stands for.
- Read
implicatedandflagged. Empty means "no emphasis", NOT "nothing is related". Expose what you decide asdata-graview-emphasisso it can be checked — a claim that exists only as a color cannot be checked.
- Render at three fidelities.
glyphis a chip;summaryis denser content, not the same content scaled down;fullis the picture.
nodesis THE GROUP'S MEMBERS, and nothing else. A lens mounted over a kind'smanycell receives that kind's members inViewProps.nodes— not the graph. Every interesting lens draws more than one kind (a board has slots and occupants, a matrix has rows and columns, a map has regions and markers), and every other kind comes fromstore.graph, narrowed back tonodesfor the group's own kind so the scene's horizon still applies. Built fromnodesalone, a map drew its ground with nothing on it: a tidy, wrong picture.
budget is the most to draw. A host may hand a lens a few members with budget and total: hold what you read from the store to it too, and say "+N more" (withMore does). A real catalog is thousands; a lens that draws them all at 6% stalls the city.
- Take an arrangement, and say what you have no place for. Every picture over a kind can be sorted, filtered and grouped from the declaration alone —
arrangeable(schema, kind)(@graview/core/arrange) offers the fields by type, the edges by far end, the lifecycle and the standing — and the stop carries it asin.sort,in.filter,in.groupandin.q, beside the calendar's ownin.at. In your lens's component:
``tsx const { nodes, arranged, bar } = useArranging(props, { lensAllows: { group: false }, // a board has nowhere to group allow: options.arranging, // the app's say: false, or per part arrangedBy: options.arrangedBy, // how the picture opens }); return <>{bar}<Picture nodes={nodes} /></>; ``
bar is the framework's own row (ArrangeBar), drawn at full fidelity unless declined; nodes are the members as arranged; arranged.groups are there when the picture has a place for headings, as the calendar's agenda does. Declare arrangedBy on the app's lenses entry too, in the grammar ({ group: "held-at" }), so graview check holds it to the bound kind and graview describe can say it. A person who arranged the list can ask your picture the same thing in the same words.
- Register your own with a title, and declare the rest. A lens you wrote is registered with a title as the fourth argument:
.register("gardener", { cardinality: "many", fidelity: "full" }, View, { title: "Who tends what" }). Untitled, it is reachable only by focusing the group. Before writing one, look for it among the shipped lenses — a calendar, a status board, a coverage, a blocks place — which are declared as data, with no registration:graview-shipped-lens.
Roles live in two places, and they do different jobs
defineNode("shift", { fieldRoles: { start: "from" } }) is what everything that is NOT a lens reads: the graph's own responder answering "when is it", the generated docs. A lens reads bindings, but a timeline or calendar binding no start draws at the kind's natural time, fieldRoles.when (also in a document). Bind the lens; declare fieldRoles for the rest.
graview check NOTES it when the two disagree about one role. Often that is a mistake; sometimes it is right, because a role name belongs to a lens and fieldRoles has one namespace for all of them: a rota means the hour a shift starts by start, and its calendar means the day. Look once, then decide.
Then find out whether it worked
pnpm build && npx graview check ./dist/domain/app.jsThe checker reads lenses in defineApp and reports lens-role-unbound, lens-binding-missing-field and lens-binding-undeclared-kind; what it says of a titled shipped lens is graview-shipped-lens. graview describe lists the places that draw. Report the output.
And prove the reuse. This is the claim a lens exists to support, and the one the checker cannot make for you — it NOTES every lens in lenses that the framework did not ship (lens-authored-here) so the question gets asked out loud, and the answer is yours. Write a test that builds it against a domain it was not designed for, then point at it with provenBy: "tests/lens-reuse.test.ts" and the note stands down:
it("works in a domain nothing here is about", () => {
// The board lens, pointed at a seating plan.
const built = buildBoard(nodes, edges, { slots: { kind: "seat" } }, schema);
expect(built.empty).toEqual(["seat-4"]);
});If you cannot write that test, say so plainly: you have written a view rather than a lens, and that is a legitimate thing to have written.
What the check cannot see
- Whether the picture is legible. Run it and look, in both schemes.
- Whether it survives being drawn small. The Graview renders the focused view at natural size and scales it;
pnpm shrunkmeasures whether it clips. - Whether the roles you chose generalize, or merely rename your own fields.