ontotwin-atlas-styling - SKILL.md Agent Skill

name: ontotwin-atlas-styling description: Use when Claude Code is changing OntoTwin dense semantic atlas visuals, lenses, point styling, labels, rails, responsive behavior, or analyst workflow UI.

OntoTwin Atlas Styling

Use this project skill when the task changes visual styling, dense semantic map fidelity, lens presets, point colors, label rendering, sidecar layout, search/finder placement, table drawer, responsive behavior, or analyst workflow UI.

Portability level: harness-specific. The styling and verification checklist is portable, but the invocation examples, .claude/skills/ location, and subagent names are Claude Code project conventions.

FPF Grounding

Before spec-sensitive work, check the active FPF runtime with get_fpf_index_status or the available FPF MCP equivalent. Stop and report the missing access if no FPF runtime or generated spec docs are available.

Prefer the fpf-memory-mcp skill when available. Use available runtime tools such as get_fpf_index_status and query_fpf_spec; do not invent FPF selectors or canonical wording from memory.

Use these FPF selectors:

A.7: visual role, method, work, status, description, and specification are separate.
A.15: a style method or UI plan is not evidence that the UI worked.
E.10: promise, ability, performance, work, and evidence labels must not blur.
E.10.D2: style describes and specifies the atlas; it is not the ontology itself.
F.18: local style names, lens names, and mappings need explicit context and version.

Required Reading

Read these before editing:

README.md
docs/demo-playbook.md
docs/lens-options.md
docs/atlas-adapter-contract.md
docs/claude-code-subagent-interest-model.md
src/styles.css
src/main.jsx
src/atlasLabels.js
src/atlasInteraction.js
src/memberAtlas.js

Visual Contract

Preserve this product anatomy unless the task explicitly changes it:

full white atlas map as the primary surface
dense tiny multicolor points with an island and bridge feel
dark green finder/header treatment
left/top command affordance that does not compete with the map
right sidecar for inspect/view/settings instead of scattered floating panels
bottom table drawer for selected rows
shadowed topic labels that remain clickable targets
lens presets for Ontology, Risk, Coverage, Work, and FPF
mobile behavior at a 390 px viewport without overlapping controls

Style is allowed to improve fidelity and usability, but it must not imply production evidence that the data path has not proven.

Atlas Fidelity Rubric

Reference plane: the dense semantic-atlas visual pattern (a white map of tiny multicolor points with shadowed region labels), used as a visual product reference only. It is not proof of OntoTwin ontology, graph, count, privacy, or backend performance.

For readiness claims, capture and compare:

desktop 1440x900 initial map
desktop selected topic or family
desktop selected record after DOC-68000000
mobile 390x844 initial map
mobile 390x844 sidecar plus table state

Pass/fail criteria:

full white map stays primary
tiny multicolor points form island/bridge density without oversized markers
labels have shadow/halo treatment and remain clickable
the finder is the only search surface
desktop workflow uses a single right sidecar plus bottom table drawer
zoom/pan/search does not create blank-canvas or off-frame selected states
mobile 390x844 has no overlapping finder, controls, tabs, drawer, or status text

If screenshots or viewport-specific evidence are absent, report a browser-proof gap rather than visual approval.

Lens And Label Rules

Lens presets are coordinated view contracts:

projection mode
color basis
point size
opacity
label visibility and posture
count/source disclosures

Do not change a lens only by color if the associated projection, density, labels, and claim scope should change together.

Labels are configured data, not decorative text. A map label must have:

manifest source or demo config source
group or record target
search alias behavior
click target behavior
hit target coverage
zoom/visibility threshold

Claude Code Route

State the styling scope in FPF terms:

Promise:
Ability:
Performance:
Evidence:
Style surface:
Data/ontology surface:
Stop/replan trigger:

Invoke subagents before broad visual changes:
- analyst-workflow-ui-reviewer for search, sidecar, table, settings, labels, lasso, export.
- qa-evidence-gate-reviewer for proof scope.
- health-privacy-disclosure-reviewer if screenshots, counts, table, lasso, or export are affected.
- react-library-boundary-reviewer if styles become package exports or tokens.
- When analyst-workflow-ui-reviewer has only read/search tools, treat it as static review unless the main session supplies screenshots, DOM notes, or browser-check evidence.
Edit the smallest surface that expresses the requested change: CSS tokens/layout first, then component state, then renderer/interaction helpers.
Run focused tests for affected helpers, then browser checks for the actual UI.

If Claude Code subagents are unavailable because of auth, quota, model, or tool limits, do not treat a local checklist as subagent approval. Record the blocker, perform a provisional local review by the same interests, and keep the readiness claim open until real subagent review can run.

If autoreview is unavailable because of auth, quota, model, or CLI limits, record the exact command and blocker. Do not claim autoreview clean.

Browser Proof Checklist

After visual or interaction edits, verify the affected subset and report exact scope:

desktop atlas opens without error overlay
DOC-68000000 search zooms/selects correctly
FPF or Ability search selects the expected group
visible label click updates selection
keyboard label shortcut still works
sidecar switches between Inspect and View
table drawer opens for the active selection
lens presets change projection plus render settings
mobile 390 px viewport has no control overlap
mobile 390x844 proof covers finder, label selection, Inspect/View tabs, Sample table, zoom controls, selected status, and rail collapse/reopen
no old floating Table/Guide/Export stack reappears
counts stay scoped to exact, aggregate, sampled, estimated, or loaded-tile evidence

Claude Code Prompt Example

/ontotwin-atlas-styling

Task: make the local atlas closer to the dense semantic-atlas reference while preserving OntoTwin workflow clarity.

Use active FPF selectors A.7, A.15, E.10, E.10.D2, and F.18.
Treat styling as description/specification, not production evidence.
Preserve clickable labels, one search surface, right sidecar workflow, table drawer, and mobile 390 px usability.
Invoke analyst-workflow-ui-reviewer and qa-evidence-gate-reviewer before closing.
Run npm test, npm run build, and browser checks for search, label click, sidecar, table drawer, lenses, and mobile layout.

Acceptance Checks

Visual changes preserve the adapter and ontology boundaries.
CSS and component names remain domain-neutral where they belong to the reusable library.
Hard-coded domain labels stay in demo manifest/config, not reusable styling components.
Label hit testing and selection tests still pass.
Desktop and mobile browser evidence covers the changed interaction.
Autoreview is clean after non-trivial edits.