ontotwin-atlas-styling

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

1. State the styling scope in FPF terms:

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

2. 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.
3. Edit the smallest surface that expresses the requested change: CSS tokens/layout first, then component state, then renderer/interaction helpers.
4. 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.