Skip to content
Skills Library
Programming · Building & coding

dev-viewer

/dev-viewer

How to work on packages/viewer, the Vite + React + React Flow + ELK app that renders architecture.json. Use when adding or changing viewer components, hooks, layout, search, playback, styling, accessibility, or viewer tests and e2e specs.

Repository
archbook ↗
Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

How to work on packages/viewer, the Vite + React + React Flow + ELK app that renders architecture.json. Use when adding or changing viewer components, hooks, layout, search, playback, styling, accessibility, or viewer tests and e2e specs.

Original author description

How to work on packages/viewer, the Vite + React + React Flow + ELK app that renders architecture.json. Use when adding or changing viewer components, hooks, layout, search, playback, styling, accessibility, or viewer tests and e2e specs.

How it works

  1. Where code goes
  2. Running
  3. Constraints that break silently
  4. Tests
Original SKILL.md headings · 48 lines, 505 words
SKILL.md preview
---
name: dev-viewer
description: How to work on packages/viewer, the Vite + React + React Flow + ELK app that renders architecture.json. Use when adding or changing viewer components, hooks, layout, search, playback, styling, accessibility, or viewer tests and e2e specs.
---

# Developing the viewer

Layer overview and ESLint boundaries: `CONTRIBUTING.md`, section "Viewer layers". Read it first.

## Where code goes

| Folder        | Holds                                                                                  | Rule                                                                                   |
| ------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `Viewer.tsx`  | Composition of hooks and components                                                    | No logic of its own                                                                    |
| `components/` | `canvas/`, `panel/`, `timeline/`, `topbar/`, `ReloadBanner`, `ErrorScreen`, `kinds.ts` | Contexts and the kind-to-icon map live here                                            |
| `hooks/`      | Playback, selection, shortcuts, flow route, canvas focus, reduced motion               |                                                                                        |
| `data/`       | `useArchitecture` (loading and reload), `useHashRoute`, `useTheme`                     |                                                                                        |
| `graph/`      | ELK layout (`layout.ts`), canvas elements, highlight, flow usage                       | Pure: no `react`, `react-dom`, `lucide-react`; `@xyflow/react` only with `import type` |
| `lib/`        | Pure helpers (`playback`, `route`, `search`, `safeUrl`, `sourceUrl`, `loadState`, ...) | Same purity rule as `graph/`                                                           |

- Look items up through `indexArchitecture` from `@archbook/schema`, built once per document. Never search arrays by id in components.
- Styles are CSS modules (`*.module.css`) plus `styles/theme.css`.
- Prefer putting logic in `graph/` or `lib/` so it can be unit tested in Node.

## Running

- `pnpm dev:example` serves `examples/shop-checkout/archbook/architecture.json` with hot reload. Use `ARCHBOOK_FILE=/abs/path/architecture.json pnpm dev:example` for another file.
- `vite.config.ts` aliases `@archbook/schema` to its source, so the schema does not need building first.
- `dev-server.ts` mounts the same live reload hub as `archbook dev` (`createLiveReloadHub` from `@archbook/schema/node`). Reloads keep the last valid document and show `ReloadBanner`.

## Constraints that break silently

- **CSP.** The build injects `CONTENT_SECURITY_POLICY` from `csp.ts` (build only). No inline scripts, no external URLs, no `eval`. Zod runs jitless: `src/zodJitless.ts` must stay the first import in `main.tsx`.
- **Bundle size.** The main bundle stays under 500 kB. Heavy, rarely used code is loaded with `lazy()`/dynamic `import()` (see `panel/Markdown.tsx`).
- **ELK.** Layout runs in a worker (`elk-worker.min.js?url`) and falls back to `elk.bundled.js` on the main thread only when `Worker` is unavailable. An e2e test asserts the fallback is never requested in a normal run.
- **Reduced motion.** Anything animated must respect `usePrefersReducedMotion` (no travelling dot, camera jumps instead of gliding).
- **Accessibility.** Nodes and unlabelled edges are tab stops opened with Enter or Space; labelled edges are reached through their label button; hidden elements get `aria-hidden`. Search follows the WAI-ARIA combobox pattern, the timeline announces steps with `aria-live="polite"`. A key handled by a focused element must not also fire the global shortcut. Keep these patterns when adding UI.
- **Links.** Any URL from the document goes through `safeHref` (`lib/safeUrl.ts`).

## Tests

- Unit tests: `packages/viewer/test/*.test.ts`, Node environment.
- Component tests: `*.test.tsx` starting with `// @vitest-environment happy-dom`, using `@testing-library/react` with `cleanup` in `afterEach`.
- Anything that needs the real canvas (layout, `ResizeObserver`, CSP) goes to Playwright in `e2e/` (`viewer.spec.ts` for the built site, `dev.spec.ts` for `archbook dev`). The `problems` fixture fails a test on console errors, page errors or CSP violations.
- Coverage limits live in `packages/viewer/vitest.config.ts`. Raise them when coverage grows, never lower them.

```sh
pnpm --filter @archbook/viewer typecheck
pnpm --filter @archbook/viewer test
pnpm build && pnpm test:e2e   # once: pnpm exec playwright install chromium
```

Versions

The database has no other skills named dev-viewer.

Database snapshot: 13.11.2026 · package version f9d5f74f1641 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dev-cli
    How to work on packages/cli, the archbook command line tool. Use when adding or changing a CLI command, its options, prompts, errors or output, the core use cases, the io adapters (fs, git, claude, server), the headless Claude Code integration, the build, or CLI tests.
  • 100integrate-file-viewer
    MUST be used whenever integrating CogniteFileViewer into a Flows app to preview CDF files (PDFs, images, text). Do NOT manually wire up react-pdf or file resolution — this skill handles installation, Vite config, worker setup, and component usage. Triggers: file viewer, file…
  • 100react-native-better-pdf
    react-native-better-pdf, the native PDF viewer for React Native and Expo (PdfView, PdfDocument, PdfCache). Use when writing, reviewing or debugging code that shows or reads PDFs with react-native-better-pdf, when adding a PDF viewer to a React Native app, and when migrating an…
  • 96viewer
    Work on graph.html, the Konstruct graph viewer (Svelte 5 and TypeScript in viewer/, built into konstruct/outputs/viewer.html). Use for any change to how the graph, panel, search or styling looks or behaves.
  • 100tl-docs-viewer-create
    Create a React admin UI for browsing documentation folders with tree navigation, markdown rendering, Mermaid diagrams, and TOC generation. Use when adding a docs viewer to an admin interface.
  • 86architecture-viewer
    Open or update an architecture diagram with the selected builtin or custom viewer, preserving a neutral session handoff. Use when asked to inspect architecture interactively or continue an existing diagram session.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.