89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# Voyage playground screenshot convention (v4.3)
|
||
|
||
This directory holds reference screenshots for the Voyage playground
|
||
(`playground/voyage-playground.html`). They serve as a visual baseline for
|
||
manual review of design changes and as fixtures for the Wave 7 axe-core
|
||
Playwright spec (`tests/e2e/voyage-playground-a11y.spec.mjs`).
|
||
|
||
Screenshots are NOT auto-committed. The `tests/e2e/snapshots/` directory
|
||
(produced by Playwright in Wave 7) is the test-baseline; this directory
|
||
holds curated illustrative captures for documentation.
|
||
|
||
## Mappestruktur
|
||
|
||
```
|
||
docs/screenshots/
|
||
README.md ← this file
|
||
dashboard/ ← project-dashboard fleet-grid views
|
||
artifact-detail/ ← drill-down render of brief/plan/review
|
||
annotation/ ← gutter-badge + sidebar + active highlight states
|
||
dark-mode/ ← screenshots taken with html[data-theme="dark"]
|
||
light-mode/ ← screenshots taken with html[data-theme="light"]
|
||
```
|
||
|
||
Each subfolder contains PNGs named by feature + variant, e.g.
|
||
`dashboard/fleet-grid-with-progress-tile.png`,
|
||
`annotation/active-anchor-yellow-tint.png`.
|
||
|
||
## Hooks (window.__voyage)
|
||
|
||
The playground exposes three automation hooks for headless screenshot
|
||
scripts. They are namespaced under `window.__voyage` to avoid global
|
||
pollution:
|
||
|
||
| Method | Purpose |
|
||
|--------|---------|
|
||
| `window.__voyage.navigate(surface)` | Switch surface. `surface ∈ ['dashboard', 'detail', 'render', 'a11y']` |
|
||
| `window.__voyage.scheduleRender(state)` | Pre-populate state. `state.markdown` triggers `mountRender`; `state.artifacts` triggers `renderDashboard` |
|
||
| `window.__voyage.getProjectArtifacts()` | Returns the last-loaded `ProjectArtifacts` object (or `null`) |
|
||
|
||
The hook surface mirrors the pattern used in
|
||
`plugins/llm-security/playground/llm-security-playground.html`
|
||
(`window.__navigate`, `window.__scheduleRender`).
|
||
|
||
## Producing screenshots — Playwright headless (Wave 7+)
|
||
|
||
Wave 7 ships a Playwright spec
|
||
(`tests/e2e/voyage-playground-a11y.spec.mjs`). Reuse its setup for
|
||
screenshots:
|
||
|
||
```js
|
||
// tests/e2e/snapshot-helper.mjs (NOT committed in v4.3 — illustrative)
|
||
import { test } from '@playwright/test';
|
||
|
||
test('dashboard with all artifacts', async ({ page }) => {
|
||
await page.goto('file://' + process.cwd() + '/playground/voyage-playground.html');
|
||
await page.evaluate(() => {
|
||
window.__voyage.scheduleRender({
|
||
artifacts: {
|
||
basePath: 'demo',
|
||
brief: { path: 'brief.md', content: '...' },
|
||
plan: { path: 'plan.md', content: '...' },
|
||
review: null,
|
||
research: [],
|
||
architecture: { overview: null, gaps: null, looseFiles: [] },
|
||
progress: null,
|
||
looseFiles: [],
|
||
}
|
||
});
|
||
});
|
||
await page.screenshot({ path: 'docs/screenshots/dashboard/fleet-grid-demo.png' });
|
||
});
|
||
```
|
||
|
||
## Producing screenshots — manuelt
|
||
|
||
1. Åpne `playground/voyage-playground.html` i Chrome/Firefox.
|
||
2. Hvis du trenger et bestemt UI-state, paste relevant artifact-innhold i
|
||
textarea og trykk Render.
|
||
3. macOS: `Cmd+Shift+4`, deretter `Space` for vindu-skjermbilde.
|
||
4. Lagre med beskrivende filnavn under riktig undermappe ovenfor.
|
||
|
||
## Konvensjon for nye screenshots
|
||
|
||
- Bruk PNG, ikke JPG (lossless for tekst-tunge UIer).
|
||
- Kjør i konsistent viewport (1280×800 anbefales for desktop-baseline).
|
||
- Ta dark- og light-mode-varianter parvis når komponenten har visuelle
|
||
forskjeller mellom temaene.
|
||
- Ikke commit screenshots med personidentifiserende info eller hemmelig
|
||
artifact-innhold.
|