Run any Skill in Manus with one click

qa-cratis-docs

Stars11

Forks5

UpdatedJune 7, 2026 at 11:21

Use this skill to visually QA rendered docs site pages after changes to source files under `Documentation/**` — screenshot pages headless in light AND dark, evaluate how they look against the aspire.dev bar, check diagrams/tables/code blocks render, and diagnose layout-shift ("flicker"/"twitch"/"pop") bugs. Trigger when someone asks to screenshot the docs, check how a docs page looks, review the docs visually, verify a diagram or table renders, compare the docs to aspire.dev, or investigate a flicker/jump/layout-shift on the docs site.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

Cratis

Cratis/Arc

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software Quality Assurance Analysts and TestersComputer and Mathematical Occupations·SOC 15-1253

SKILL.md

readonly

name

qa-cratis-docs

description

Visual & layout QA for the docs site

Scope this skill to visual checks for product or contributing docs whose source lives under Documentation/**. Site-level pages in Documentation/web are owned by the Documentation repo.

shot-scraper/Playwright aren't dependencies, but Chrome is. Use the committed Documentation/web/scripts/screenshot.mjs (drives system Chrome over CDP) — it captures light or dark, full-page, with client-side rendering settled.

Capture

cd Documentation/web && npm run dev        # serve at http://localhost:4321 (keep it running)
node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-dark.png dark
node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-light.png light

Then Read the PNG to evaluate it. Crop/zoom with the sharp already in node_modules (PIL/ImageMagick aren't installed):

node -e "require('sharp')('/tmp/es-dark.png').extract({left:300,top:600,width:900,height:500}).resize({width:1400}).toFile('/tmp/crop.png')"

Build the page list from web/src/generated/topics.json + the site-level slugs. The bar is aspire.dev (~/src/repos/aspire.dev/src/frontend) — study its site.css/mermaid.css for the depth cues (gradient glows, framed diagrams, lifted cards) that cratis.css is built from.

What to check on each page

Diagrams themed and correctly sized in both themes (pre-rendered SVG — should be present immediately, no pop).
Tables render as real tables (not raw | pipes — that's the GFM/MDX bug).
Code blocks not over-indented (no spurious leading whitespace in the source snippet) and lifted off the page.
Hero / cards have depth (glow, lift), inline code is a brand-tinted chip.
Light AND dark both read cleanly.

Diagnosing a flicker / twitch / layout-shift

The cause is almost always one of: font swap (fixed — font-display: optional + preload in Head.astro), client-side rendering settling, or Mermaid (fixed — build-time pre-render). To measure:

Inject a buffered layout-shift PerformanceObserver via CDP Page.addScriptToEvaluateOnNewDocument and sample document.documentElement height every ~16ms after navigate; print the timeline.
Use a fresh --user-data-dir for a cold (uncached) load; reuse it for a warm load. Many shifts only show cold.
For scroll-restoration flashes: scroll down, Page.reload, sample window.scrollY — if it lands short, content above is rendering late.
Run all CDP scripts serially — they collide on the debug port.

Caveats

Restart npm run dev after running npm run check — the gate's re-sync degrades a live dev server (pages 500, tables vanish). A degraded dev server makes screenshots lie; restart and re-verify before trusting a "broken" result.
The Astro dev toolbar appears mid-page in full-page captures — it's a dev-only overlay, not a real element.
prefers-color-scheme emulation can trigger astro-mermaid's theme observer on any client-rendered fallback diagram; pre-rendered diagrams are unaffected.

→ Rendering internals live in the Documentation repo.

More from this repository

same repository

cratis-react-page

Cratis/Arc

Step-by-step guidance for building a React page in a Cratis Arc application — listing data with DataPage, toolbar actions with CommandDialog, row selection, detail panels, observable queries, and MVVM. Use whenever building or modifying a React page that lists or displays data, adding a table or grid, wiring up Add/Edit/Delete actions, using DataPage, DataTableForQuery, CommandDialog, or any @cratis/components. Also trigger when connecting a React component to a proxy-generated query or observable query.

2026-06-1111

add-reactor

Cratis/Arc

Use this skill when asked to add a Chronicle reactor (automation or translation) to a Cratis-based project. Reactors observe events and produce side effects.

2026-06-0911

write-documentation

Cratis/Arc

Diátaxis Documentation Expert for Cratis projects. Writes high-quality DocFX documentation guided by the Diátaxis framework — classifying every page as a Tutorial, How-to Guide, Reference, or Explanation.

2026-06-0911

edit-cratis-docs

Cratis/Arc

Use this skill when changing, fixing, or improving Cratis documentation whose source file is under `Documentation/**` in a product or contributing repo. The content is split across repos (each product owns its docs in its own `Documentation/` folder; the `Documentation` repo aggregates them), so this skill finds the real source file, edits it, syncs, and verifies. Trigger whenever someone asks to edit/update/fix/reword a docs page, fix a broken link, correct a code example, update a guide or tutorial or reference page, or says a docs page is wrong/outdated — for Chronicle, Arc, Components, CLI, Fundamentals, or the contributing docs.

2026-06-0711

add-cratis-docs-page

Cratis/Arc

Use this skill when creating a NEW Cratis documentation page under `Documentation/**` in a product or contributing repo — a new tutorial chapter, how-to/guide, explanation/concept page, reference page, or scenario/recipe. Handles where the file goes (which product repo), wiring it into the sidebar nav (toc.yml + Diátaxis bucket), and verifying it renders. Trigger when someone asks to add/create/write a new docs page, document a new feature, add a guide/tutorial/recipe/concept to the docs, or add a new section to a product's documentation.

2026-06-0711

add-business-rule

Cratis/Arc

Use this skill when asked to add a validation rule, business rule, or uniqueness constraint to an existing command in a Cratis-based project.

2026-05-1611

name

qa-cratis-docs

description

Visual & layout QA for the docs site

Scope this skill to visual checks for product or contributing docs whose source lives under Documentation/**. Site-level pages in Documentation/web are owned by the Documentation repo.

Capture

cd Documentation/web && npm run dev        # serve at http://localhost:4321 (keep it running)
node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-dark.png dark
node scripts/screenshot.mjs http://localhost:4321/chronicle/concepts/event-source/ /tmp/es-light.png light

Then Read the PNG to evaluate it. Crop/zoom with the sharp already in node_modules (PIL/ImageMagick aren't installed):

node -e "require('sharp')('/tmp/es-dark.png').extract({left:300,top:600,width:900,height:500}).resize({width:1400}).toFile('/tmp/crop.png')"

What to check on each page

Diagrams themed and correctly sized in both themes (pre-rendered SVG — should be present immediately, no pop).
Tables render as real tables (not raw | pipes — that's the GFM/MDX bug).
Code blocks not over-indented (no spurious leading whitespace in the source snippet) and lifted off the page.
Hero / cards have depth (glow, lift), inline code is a brand-tinted chip.
Light AND dark both read cleanly.

Diagnosing a flicker / twitch / layout-shift

Inject a buffered layout-shift PerformanceObserver via CDP Page.addScriptToEvaluateOnNewDocument and sample document.documentElement height every ~16ms after navigate; print the timeline.
Use a fresh --user-data-dir for a cold (uncached) load; reuse it for a warm load. Many shifts only show cold.
For scroll-restoration flashes: scroll down, Page.reload, sample window.scrollY — if it lands short, content above is rendering late.
Run all CDP scripts serially — they collide on the debug port.

Caveats

Restart npm run dev after running npm run check — the gate's re-sync degrades a live dev server (pages 500, tables vanish). A degraded dev server makes screenshots lie; restart and re-verify before trusting a "broken" result.
The Astro dev toolbar appears mid-page in full-page captures — it's a dev-only overlay, not a real element.
prefers-color-scheme emulation can trigger astro-mermaid's theme observer on any client-rendered fallback diagram; pre-rendered diagrams are unaffected.

→ Rendering internals live in the Documentation repo.