cocoindex-diagrams

name

cocoindex-diagrams

description

This skill should be used when creating, editing, or reviewing inline SVG diagrams for the CocoIndex docs site (anything under docs/src/content/docs/**). It encodes the component-based primitive system under docs/src/components/diagrams/, the palette + shape semantics, the preview-and-verify loop using headless Chrome with the /docs base path, and the pitfalls that cost iterations to discover. Trigger phrases include "add a diagram to the docs", "edit this diagram", "replace the SVG in core_concepts", "make a diagram for processing_component", "check how the diagram looks".

CocoIndex Docs Diagrams

Inline SVG diagrams in the docs are authored as Astro components under docs/src/components/diagrams/, composed from shape-semantic primitives that share a palette and styling. Static .svg files exported from design tools are legacy — always build new diagrams with the primitives.

When this skill applies

Apply this skill when:

• Adding a new diagram to a docs page (.mdx under docs/src/content/docs/).
• Editing or replacing an existing diagram component.
• Reviewing a rendered diagram for layout or style issues.
• Reworking a legacy <img src="/docs/img/...svg"> reference.

Do not apply for:

• Marketing-site diagrams under cocoindex.github.io/ (different style, different primitives).
• General SVG editing outside docs/src/components/diagrams/.

The canonical reference

Read docs/src/components/diagrams/README.md first. It documents the shape vocabulary, palette vars, shared CSS classes, animation conventions, directory layout, and MDX embedding pattern. This SKILL.md assumes that reference is current — do not duplicate it here.

Then consult the three references bundled with this skill for the session-specific knowledge that isn't in the project README:

• references/workflow.md — the preview loop (headless Chrome + base-path gotcha), how to crop and view output, rebuild discipline.
• references/pitfalls.md — the traps that repeatedly cost iterations (dg-step opacity, color unification, magic-number insets, labels without auto-wrap).
• references/layout-patterns.md — layout idioms (horizontal arrows, symmetric padding, compactness, bindings vs arrows).

Core procedure

When asked to create or edit a diagram, proceed in this order:

1. Read the reference materials

Load docs/src/components/diagrams/README.md plus the three references above. Skim, don't memorize — refer back when designing.

2. Design the layout before writing code

Sketch positions with concrete numbers in a config object at the top of the .astro file. Prefer absolute coordinates with a viewBox sized to content, and use named constants for box dimensions and column offsets.

Derive container size from content, not the other way around. Start from inner widths, gaps, and pad; compute APP_W = sum(cols) + (n-1) * GAP + 2 * APP_PAD_X. Downstream siblings (Target System, Drive Folder right) reference APP.x + APP_W, not a hardcoded x. Same for vertical: pick row centers so top-pad == bottom-pad. This keeps padding balanced on all four sides as you iterate. See references/layout-patterns.md.

3. Compose from primitives

Use the shape-semantic primitives:

Shape	Meaning	Primitive
Sharp rectangle	Data (file, chunk, row)	DataBox
Round-cornered rectangle	Subsystem / logic	LogicBox (memoized + status props, slot)
Cream container with header	A Processing Component	ProcessingComponent (slot in local coords; memoized + status)
Peach container with header	A CocoIndex App	AppContainer (slot in local coords)
Bullet (flat left, rounded right)	Target state	TargetBullet
Animated dashed arrow with head	Flow / causation	FlowArrow
Static dashed line, no head	Binding / identity	Connector

Delta state + cache status annotations (orthogonal, on any shape):

Prop	Values	Visual
state	new, updated, removed, changed, idle	Palm-green / gold / pink / thin-pink fill (state cascade is prevented by direct-child CSS combinator — see pitfalls).
status	cache-ready, refreshing	Top-left badge. Cache-ready writes its check in on hover; refreshing spins on hover. Both suppressed when state="removed".
highlight	true	Thick palm border for "currently-discussed element"

New shape primitives should compose on top of ShapeGroup, not re-implement the wrapper <g> + state class + title + badge logic.

4. Render labels with foreignObject

All label-bearing primitives (DataBox, LogicBox, ProcessingComponent, TargetBullet) use <foreignObject> with a flex-centered <div class="dg-fo-label"> so the browser auto-wraps labels against the box width. Just pass label="..." — never pre-split into manual lines.

5. Preview and verify before reporting done

Run the preview script bundled with this skill:

scripts/preview.sh <docs-slug>
# Example: scripts/preview.sh programming_guide/core_concepts

The script handles: building Astro, mirroring dist/ into a temp path that matches the site's /docs base URL (critical — see pitfalls), spinning up a local HTTP server on a free port, screenshotting with headless Chrome, and printing paths to PNG crops. Read the PNGs with the Read tool to self-check before reporting the diagram done.

Do NOT report a diagram complete based solely on "the build compiled". Always render and look. Small issues like overlapping labels, dimmed rows, or wrong arrow styles are invisible from code alone.

6. Iterate on visual feedback

Common iterations (see pitfalls for full details):

• Elements faded at ~35% opacity → dg-step leaking onto static rows; remove it.
• Boxes rendering black in the preview → CSS base-path mismatch (not a code bug).
• Labels overlapping → <foreignObject> not used, or box too narrow for the string.
• Arrows to wrong targets → mixing absolute vs. PC-local coordinate space.

MDX embedding pattern

Import with an absolute path from the site root so it works at any docs depth:

---
title: Core Concepts
---
import ComponentWithChunks from '/src/components/diagrams/concepts/ComponentWithChunks.astro';

## Processing Component

<ComponentWithChunks />

Discipline

• Shape carries meaning. Pick primitives by semantics, not "what looks right".
• No manual line-splitting. If a label overflows, widen the box or shorten the label.
• Absolute coords for outer layout; local coords inside slotted containers. ProcessingComponent's slot renders children with (0, 0) = container top-left.
• All flow arrows use the same color. Default coral; variant="palm" / "muted" only when semantically meaningful.
• Bindings are silent. Connector (static, dashed, no arrowhead) for "X is bound to Y" — Drive Folder → file, vector → Vector Database.
• Padding balanced on ALL sides. Left == right inside every container, and top == bottom. Derive the container's width/height from its content (APP_W = sum(cols) + (n-1)*GAP + 2*APP_PAD_X); downstream siblings reference APP.x + APP_W, not a hardcoded x. See references/layout-patterns.md "Balanced padding on all sides".
• Prefer compactness. Diagrams should read well at docs column width; stretch only when a visual story demands it.
• Never use dg-step for static content. It's opacity-35% by default and only lights up on hover — reserved for progressive-reveal narratives (e.g. "panel 1 → 2 → 3").
• All animations are idle by default, active on .dg-root:hover. Flow-drift, delta-pulse, check-draw, refresh-spin — each gated the same way. No always-on motion on a static page. When adding a new @keyframes rule, register it in the @media (prefers-reduced-motion: reduce) block at the bottom of diagrams.css.
• State rules in CSS use the direct-child combinator (.dg-state-X > .dg-box), not descendant. A state class on a container (PC with pcState="updated") would otherwise cascade into every nested .dg-box. Each shape primitive owns its own state on its own ShapeGroup-wrapped <g>.
• Compose new shape primitives on ShapeGroup, not from scratch. It owns the wrapper <g>, state/highlight class composition, <title>deleted</title> tooltip, and the MemoMark/StatusBadge badges (with suppression when removed). Never re-implement any of that.

Iteration expectations

Expect 2–4 preview cycles for any non-trivial diagram. After the first render, opacity/color/overlap issues almost always surface that weren't visible from code inspection. Budget for the loop — don't try to land the diagram in one shot.

Starter template

See assets/starter.astro for a minimal shape-semantic diagram skeleton. Copy and adapt rather than writing from scratch.