[Feature]: Document CSS-only disclosure + click-to-pin and hover tooltips #162

What are you trying to show?

Diagrams where a second layer of detail exists but does not belong in the default view.

Two concrete cases:

1. Progressive detail. One diagram serving two audiences — the reader sees nine boxes, and can open one box to see its ports, retry policy, or SLA. This is the pressure valve for the §7 complexity budget: instead of splitting into overview + detail as two files, the detail lives in the same file, closed by default.
2. Secondary annotation. A metric, a threshold, or a topology sketch that would push the static diagram past 4/10 density if drawn inline, but that a reader may want on demand.

Today the skill has no documented answer for either. The only interaction it describes is step mode playback in references/animation.md, which is for ordered explanation — a different job from on-demand detail.

Proposed solution

A new optional primitive, references/primitive-disclosure.md, alongside the existing primitive-annotation.md / primitive-sketchy.md / primitive-terminal.md, plus one row in SKILL.md §6's optional-primitives list.

It would already be legal. I tested four approaches against the skill's own skills/diagram-design/scripts/self_check.py (v2.6.7):

So the last three pass with zero JavaScript and zero remote references. The gap is documentation, not capability — nothing in SKILL.md or the 53 reference files mentions :target, hover, or disclosure, so an agent will never produce these patterns unless a user asks for them by name.

Click — :target

<a href="#detail-ci" aria-label="Show detail for CI checks">
  <rect class="box" .../><text ...>CI checks</text>
</a>
...
<g class="detail" id="detail-ci"> ...detail lines... </g>

.detail { opacity: 0; }
.detail:target { opacity: 1; }

Hover — scoped :hover

<g class="hot">
  <rect class="box" .../><text ...>Deploy</text>
  <g class="tip" aria-hidden="true"> ...panel... </g>
</g>

.tip { opacity: 0; pointer-events: none; }
.hot:hover .tip { opacity: 1; }

The hover panel can hold anything SVG can hold, including a small nested diagram (I built one showing a load balancer fanning out to three pods).

Why this fits the philosophy — and where it does not

I want to be straight that this is in tension with the project's stance, and I am raising it rather than assuming the answer.

Where it fits:

• Zero JavaScript, so the one-script / canonical-controller rule is untouched.
• No remote references, so the single-file guarantee holds.
• :target state lives in the URL, so a specific open panel is linkable and reproducible — the same determinism property animation.md requires of ?motion=step&step=N.

Where it does not, and what a contract could require:

• Hover has no touch equivalent and disappears from PNG/SVG export and print. Any hover content would have to be strictly redundant — an elaboration of something already labeled, never the only place a fact appears.
• Click hides content by default, which cuts against "the source is complete." The mitigation is the same contract animation.md already uses: the closed state must be meaningful on its own, and a static capture must expose every panel.
• It could be abused to defeat the 9-node budget by hiding a 30-node diagram inside tooltips. A stated cap (say ≤4 disclosure targets, ≤3 lines each, no nested disclosure) would keep it honest.

If the verdict is that on-demand detail simply is not what this skill is for, that is a completely reasonable answer, and documenting the rejection — a line in the anti-patterns table saying disclosure is deliberately out of scope — would be almost as useful as adding it. Right now it is neither blessed nor forbidden, and it passes the linter, which means people will build it inconsistently.

I have working examples of all three techniques (click-to-pin, hover text tooltip, hover tooltip with a nested diagram) that pass self_check.py, and I'm glad to open a PR against a shape you specify. Wanted your call on the philosophy before writing the reference file.

Scope

New or changed primitive

Design-system fit

• I've checked the anti-patterns and 'When not to use' — this still seems worth drawing
• I'm willing to contribute the implementation or pair with a maintainer