Validating MicroSim quality and standards
Capturing screenshots for preview images
Adding or managing icons for MicroSims
Generating index pages for MicroSim directories
Quality scoring and standardization checks
Synchronizing iframe heights from JS source files
Setting up runtime iframe auto-resize via postMessage
Scaffolding MicroSim directories (main.html, index.md, metadata.json) from TODO JSON specs
Testing whether interactive controls are fully visible inside the iframe (Playwright)
Reviewing a MicroSim's visual layout for rendering defects (Claude Vision)
Auditing diagram/MicroSim coverage across chapters (status, difficulty, Bloom's levels)

Step 1: Identify Utility Type

Match the user's request to the appropriate utility guide:

Routing Table

Trigger Keywords	Guide File	Purpose
standardize, quality, validate, score, check, audit	`references/standardization.md`	Quality validation and scoring
screenshot, capture, preview, image, thumbnail	`references/screen-capture.md`	Automated screenshot generation
icons, add icons, favicon, logo	`references/add-icons.md`	Icon management for MicroSims
index page, microsim list, grid, directory, catalog, update the microsim listings, update the list of microsims, create a grid view, generate a listing	`references/index-generator.md`	Generate index page with grid cards
TODO, todo json, extract specs, diagram specs, unimplemented, create microsim todo, todo files, extract diagrams, unimplemented microsims	`scripts/create-microsim-todo-json-files.py`	Extract unimplemented diagram specs into TODO JSON files
scaffold microsims, scaffold from todo, scaffold sims, create microsim stubs, generate microsim scaffolding, stub out microsims, create scaffold files, generate scaffold from json, microsim stubs from todo	`scripts/scaffold-microsims-from-todo.py`	Generate `main.html`, `index.md`, and `metadata.json` stub files for each TODO JSON spec that does not yet have an implementation
fix iframe heights, sync iframe heights, correct iframe heights, iframe height, canvas height, sync heights, update iframe heights	`scripts/sync-iframe-heights.py`	Set every sim iframe to CANVAS_HEIGHT + 2, resolving CANVAS_HEIGHT from the .js comment / metadata.json / main.html / computed vars, across the sim's own index.md and all embeds
canvas height strategy, where is the height stored, height convention, how do iframe heights work, store height for mermaid/vis-network, metadata canvasHeight, no js height	`references/canvas-height-strategy.md`	The build-time height convention: resolution order, per-library storage, metadata.json fallback, and downstream hand-off
iframe auto height, iframe auto resize, iframe postMessage, runtime iframe resize, microsim auto resize, auto-size iframe, iframe self-resize	`references/iframe-auto-height.md`	Runtime postMessage protocol so embedded MicroSims report their own height to the parent page
test iframe, controls clipped, controls cut off, are controls visible, test iframe heights, verify controls fit, check if sims fit, iframe visibility	`references/iframe-tester.md` (runs `scripts/test-iframe-heights.py`)	Playwright check that every interactive control is fully visible inside the iframe at its declared height
review layout, layout review, looks off, looks wrong, clipped labels, overlapping controls, residual stroke, draw order, visual QA, review the sim	`references/layout-reviewer.md`	Claude Vision review of a sim's rendered layout — walks a checklist, diagnoses defects, patches source
diagram report, diagram reports, visualization coverage, audit diagrams, audit microsims, diagram status, microsim status report	`references/diagram-reports.md` (runs `scripts/diagram-report.py`)	Generate status reports of all diagrams/MicroSims across chapters (type, status, Bloom's levels, UI complexity, difficulty)

Decision Tree

Need to check MicroSim quality/standards?
  → YES: standardization.md

Need to capture screenshots for previews?
  → YES: screen-capture.md

Need to add or manage icons?
  → YES: add-icons.md

Need to generate/update the MicroSim index page?
  → YES: index-generator.md

Need to extract unimplemented diagram specs into TODO files?
  → YES: Run scripts/create-microsim-todo-json-files.py

Need to scaffold sim directories (main.html, index.md, metadata.json) from those TODO JSON files?
  → YES: Run scripts/scaffold-microsims-from-todo.py

Need to fix, sync, or correct iframe heights?
  → YES: Run scripts/sync-iframe-heights.py

Need iframes to auto-resize at runtime via postMessage?
  → YES: references/iframe-auto-height.md

Need to verify interactive controls are fully visible inside the iframe?
  → YES: references/iframe-tester.md (runs scripts/test-iframe-heights.py)

Need to review whether a sim's rendered layout looks right (not just fits)?
  → YES: references/layout-reviewer.md

Need a status report of all diagrams/MicroSims across chapters?
  → YES: references/diagram-reports.md (runs scripts/diagram-report.py)

Iframe-height utilities at a glance

Three utilities touch iframe height — they are complementary, not redundant:

Utility	Question it answers	Tool
`scripts/sync-iframe-heights.py`	"Do all iframes use the sim's `CANVAS_HEIGHT` + 2?" (build-time)	Python
`references/canvas-height-strategy.md`	"Where is `CANVAS_HEIGHT` stored for each library type, and how does it flow?" (convention)	Doc
`references/iframe-tester.md`	"Do the controls actually fit at that height?" (geometric)	Playwright
`references/layout-reviewer.md`	"Does the rendering inside the canvas look right?" (visual)	Claude Vision

Step 2: Load the Matched Guide or Run the Script

For reference-based utilities, read the corresponding guide file from references/ and follow its workflow.

For Python script utilities, run the script directly:

TODO JSON extractor:

python3 /path/to/skills/microsim-utils/scripts/create-microsim-todo-json-files.py --project-dir /path/to/project

Report the summary output to the user (chapters scanned, total specs found, already implemented, TODO files written, output directory).

Scaffold from TODO JSON:

python3 /path/to/skills/microsim-utils/scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project

Report the summary output to the user (TODO specs processed, scaffolded, skipped). Use --force only if the user explicitly asks to regenerate stubs; the script never overwrites an existing main.html regardless of --force.

Iframe height sync:

python3 /path/to/skills/microsim-utils/scripts/sync-iframe-heights.py --project-dir /path/to/project --verbose

Report the summary output to the user (sims synced, CANVAS_HEIGHT comments inserted, iframe heights updated).

Step 3: Execute Utility

Each guide contains:

Purpose and use cases
Prerequisites
Step-by-step workflow
Output format
Best practices

Available Utilities

standardization.md

Purpose: Validate MicroSim quality against standards

Checks:

Required file presence (main.html, index.md)
Code structure and patterns
Accessibility features
Documentation completeness
Responsive design implementation

Output: Quality score (0-100) with recommendations

screen-capture.md

Purpose: Capture high-quality screenshots for social media previews

Script: ~/.local/bin/bk-capture-screenshot <microsim-directory-path>

Features:

Uses Chrome headless mode with localhost server
Handles JavaScript-heavy visualizations (p5.js, vis-network, Chart.js)
Waits 3 seconds for proper rendering
Creates consistent 1200x800 image sizes

Output: PNG screenshot named {microsim-name}.png in MicroSim directory

add-icons.md

Purpose: Add favicon and icons to MicroSim directories

Creates:

favicon.ico
apple-touch-icon.png
Other platform-specific icons

index-generator.md

Purpose: Generate comprehensive MicroSim index page

Creates:

Grid-based card layout
Screenshots for each MicroSim
Alphabetically sorted entries
MkDocs Material card format
Updates mkdocs.yml navigation

create-microsim-todo-json-files.py

Purpose: Extract unimplemented MicroSim diagram specifications from chapter content and create TODO JSON files

Script: scripts/create-microsim-todo-json-files.py --project-dir /path/to/project

How it works:

Scans all docs/chapters/*/index.md files for #### Diagram: headers
Extracts sim-id, library, Bloom level, learning objective, and full specification from <details> blocks
Skips any sim-id that already has a directory with main.html under docs/sims/
Writes one JSON file per unimplemented diagram to docs/sims/TODO/

Output: Individual JSON files in docs/sims/TODO/{sim-id}.json with fields:

sim_id, diagram_name, chapter_number, chapter_title
library, bloom_level, bloom_verb, learning_objective
completion_status: "specified", extracted_date, specification

Important: Always pass --project-dir pointing to the project root (the directory containing mkdocs.yml). If omitted, the script walks up from its own location to find mkdocs.yml, which may find the wrong project.

scaffold-microsims-from-todo.py

Purpose: Generate scaffold (stub) files for each MicroSim that has a TODO JSON spec but no implementation yet. This is the natural next step after create-microsim-todo-json-files.py.

Script: scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project

How it works:

Reads each docs/sims/TODO/<sim-id>.json
For any sim-id that does NOT already have docs/sims/<sim-id>/main.html, creates the directory with three stub files:
- main.html — placeholder canvas with the spec embedded as a comment
- index.md — frontmatter, learning objective, iframe embed, full spec
- metadata.json — mapped from the TODO JSON
Skips any sim-id whose main.html already exists (so real implementations are never clobbered)

Flags:

--project-dir — Project root containing mkdocs.yml (required or auto-detected)
--force — Overwrite existing index.md and metadata.json stubs. Never overwrites an existing main.html, even with --force, because that file may contain a real implementation.

Output: Summary showing TODO specs processed, scaffolded, and skipped (already implemented).

Important: Always pass --project-dir pointing to the project root. The script auto-detects by walking up from cwd to find mkdocs.yml if omitted.

sync-iframe-heights.py

Purpose: Set every iframe that shows a sim to CANVAS_HEIGHT + 2, using each sim's resolved CANVAS_HEIGHT as the single source of truth. See references/canvas-height-strategy.md for the full convention (resolution order, per-library storage, downstream hand-off).

Script: scripts/sync-iframe-heights.py --project-dir /path/to/project

How it works:

Resolves each sim's CANVAS_HEIGHT from the first source that has it:
1. // CANVAS_HEIGHT: <int> in the first ~15 lines of <id>.js (primary)
2. "canvasHeight": <int> in metadata.json (the consistent place for sims with no .js — Mermaid, vis-network, Chart.js, Leaflet, vis-timeline, Plotly, custom HTML)
3.  in main.html (back-compat)
4. computed drawHeight + controlHeight (+ graphHeight) from <id>.js, then inserts the // CANVAS_HEIGHT comment on line 2
Sets iframe height = CANVAS_HEIGHT + 2 (2px for iframe border) in:
- The sim's own docs/sims/<id>/index.md
- Every page under docs/ that embeds the sim, matched by the sims/<id>/main.html path. Layout-agnostic: handles the standard docs/chapters/<chapter>/index.md and the nested docs/bands/<band>/chapters/<chapter>/index.md used only by the health-education textbook, plus teacher guides. Poster embeds and the learning-graph viewer are never touched.
Reports all changes with colored output

Flags:

--project-dir — Project root containing mkdocs.yml (required or auto-detected)
--sim <sim-id> — Sync a single sim instead of all
--dry-run — Preview changes without writing files
--write-metadata — Backfill each sim's metadata.json canvasHeight field (off by default; use once to migrate no-.js sims into the structured store)
--verbose — Show the resolved height and source for every sim

Output: Summary showing sims resolved (by source), iframe heights updated (own-index vs embeds), and any metadata backfilled.

Important: Always pass --project-dir pointing to the project root. The script auto-detects by walking up from cwd to find mkdocs.yml if omitted.

iframe-auto-height.md

Purpose: Runtime alternative to sync-iframe-heights.py. Documents the two-part postMessage protocol that lets an embedded MicroSim report its own measured content height to the parent page, which then resizes the iframe automatically.

When to use: Sims with responsive or content-dependent heights that are hard to predict at build time (e.g., diagram-overlay sims whose height depends on the longest callout text). Coexists with sync-iframe-heights.py without conflict.

What's in the guide:

The 'microsim-resize' message contract (type, height fields)
Drop-in parent-side listener block for docs/js/extra.js
Child-side reporter snippets for diagram-overlay, p5.js, and Mermaid sims
Why to match by event.source === iframe.contentWindow (not by URL)
Caveats: one-shot vs. live, target origin, sandbox attributes, fullscreen mode
Reference implementation paths in the digital-citizenship project

Setup is one-time per project: add the listener block once to docs/js/extra.js, then any MicroSim that posts the microsim-resize message participates automatically.

iframe-tester.md

Purpose: Verify that every interactive control (button, slider, dropdown, checkbox) is fully visible inside the iframe at its declared height — a geometric check using a real headless browser.

Script: scripts/test-iframe-heights.py (Playwright)

How it works:

Finds all MicroSim directories under docs/sims/
Reads each index.md to get the declared iframe height
Loads main.html in a viewport constrained to that height
Checks every interactive element's bounding box against the iframe boundary
Reports PASS/FAIL with a suggested height for failures

Prerequisites: pip install playwright && playwright install chromium

When to use: controls appear clipped at the bottom of a sim, or auditing iframe sizing across all sims after a batch generation. Complements sync-iframe-heights.py (which propagates the height) — run the tester to confirm the propagated height actually works.

A legacy Node.js version was retired during consolidation; the Python script is the only supported implementation.

layout-reviewer.md

Purpose: Review a sim's rendered layout with Claude Vision — catches defects geometric checks miss: clipped row labels, overlapping controls, text rendered with residual strokes, panel overflow, low-contrast labels, draw-order bugs, and library-specific rendering issues.

Tool: Claude Vision (reads the screenshot PNG directly) + bk-capture-screenshot

How it works:

Reads the iframe height from index.md, captures a screenshot at that height
Walks references/visual-checklist.md item by item (PASS / FAIL / N/A)
For each FAIL, consults references/common-fixes.md and applies the smallest patch
Re-captures and re-walks; stops after 3 review-patch cycles

Reference files: references/visual-checklist.md (every item to inspect), references/common-fixes.md (symptom → root cause → edit).

When to use: right after generating a new sim (proactive QA), or when the iframe height is correct but something inside the canvas looks wrong. For "controls clipped at the edge" only, run iframe-tester.md first.

Examples

Example 1: Quality Check

User: "Check if my bouncing-ball MicroSim meets standards" Routing: Keywords "check", "standards" → references/standardization.md Action: Read standardization.md and follow its workflow

Example 2: Capture Screenshot

User: "Create a preview image for the timeline MicroSim" Routing: Keywords "preview", "image" → references/screen-capture.md Action: Run ~/.local/bin/bk-capture-screenshot /path/to/docs/sims/timeline

Example 3: Update Index

User: "Update the MicroSim index page with all new sims" Routing: Keywords "index", "update" → references/index-generator.md Action: Read index-generator.md and follow its workflow

Example 4: Create TODO JSON Files

User: "Create MicroSim TODO JSON files" Routing: Keywords "TODO", "create microsim todo" → scripts/create-microsim-todo-json-files.py Action: Run python3 scripts/create-microsim-todo-json-files.py --project-dir /path/to/project and report results (chapters scanned, specs found, already implemented, TODO files written)

Example 5: Scaffold MicroSims from TODO JSON

User: "scaffold the microsims" or "create the stub files for the TODO sims" or "generate scaffold files from the JSON specs" Routing: Keywords "scaffold microsims", "stub out microsims", "scaffold from todo" → scripts/scaffold-microsims-from-todo.py Action: Run python3 scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project and report results (TODO specs processed, scaffolded, skipped). Typically follows immediately after create-microsim-todo-json-files.py.

Example 6: Fix Iframe Heights

User: "fix the iframe heights" or "sync the iframe heights" or "correct the iframe heights" Routing: Keywords "fix iframe heights", "sync iframe heights", "correct iframe heights" → scripts/sync-iframe-heights.py Action: Run python3 scripts/sync-iframe-heights.py --project-dir /path/to/project --verbose and report results (sims synced, comments inserted, iframe heights updated)

Example 7: Set Up Iframe Auto-Resize

User: "make the iframes auto-size" or "set up iframe auto height" or "I want microsims to report their own height" Routing: Keywords "iframe auto height", "auto-size iframe", "iframe postMessage" → references/iframe-auto-height.md Action: Read iframe-auto-height.md and follow the two-part setup: paste the parent-side listener block at the top of docs/js/extra.js, then ensure the relevant MicroSims post { type: 'microsim-resize', height } after layout settles. Confirm both sides are in place and report which sims now participate.

Example 8: Test Iframe Control Visibility

User: "check if my sims fit" or "are the controls visible" or "test iframe heights" Routing: Keywords "check if sims fit", "controls visible", "test iframe heights" → references/iframe-tester.md Action: Read iframe-tester.md, ensure Playwright is installed, then run python3 scripts/test-iframe-heights.py --sims-dir docs/sims and present the PASS/FAIL table. Offer to fix failing heights.

Example 9: Review a Sim's Visual Layout

User: "this sim looks off" or "review the layout" or "the labels look clipped" Routing: Keywords "looks off", "review layout", "clipped labels" → references/layout-reviewer.md Action: Read layout-reviewer.md, capture a screenshot at the sim's iframe height, read the PNG with Claude Vision, walk visual-checklist.md, and patch defects per common-fixes.md (max 3 cycles).

Common Workflows

After Creating New MicroSim

Run standardization.md to validate quality
Run ~/.local/bin/bk-capture-screenshot <microsim-path> to create preview image
Run references/layout-reviewer.md (Claude Vision) to catch rendering defects
Run references/iframe-tester.md (Playwright) to confirm controls fit at the iframe height
Run index-generator.md to add to index page

Bulk Quality Audit

Use standardization.md to audit all MicroSims in a project and generate a quality report.

Integration Notes

These utilities work with the standard MicroSim directory structure:

docs/sims/<microsim-name>/
├── main.html       # Main visualization
├── index.md        # Documentation
├── *.js            # JavaScript code
├── style.css       # Styles (optional)
└── <name>.png      # Preview screenshot (created by screen-capture)

microsim-utils

MicroSim Utilities

Overview

When to Use This Skill