frontend-textbooks
A coding-agent skill for generating designed HTML textbooks and print-ready PDFs
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/onepixelaway--frontend-textbooks)HTML
<a href="/listings/onepixelaway--frontend-textbooks"><img src="/api/listings/onepixelaway--frontend-textbooks/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Codex Manual Installation
Clone this repository into your Codex skills directory:
git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.codex/skills/frontend-textbooks cd ~/.codex/skills/frontend-textbooks npm ci npm run setup:browsers
Then ask Codex to use the `frontend-textbooks` skill when you want to turn manuscript text into a designed book and PDF.
Claude Code Manual Installation
Copy or clone the skill into Claude Code's skills directory:
git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.claude/skills/frontend-textbooks cd ~/.claude/skills/frontend-textbooks npm ci npm run setup:browsers
Then use it as a standalone skill by asking Claude Code to use `frontend-textbooks`.
Other Coding Agents
Other local coding assistants can use the same core skill if they can read files and run shell commands. Point the agent at this repository and ask it to start from:
SKILL.md
The skill file routes the agent to optional references only when needed:
- `references/intake-and-planning.md` - `references/visual-system.md` - `references/layout-and-html.md` - `references/verification-gates.md` - `references/reasoning-contracts.md` - `references/iteration.md`
`STYLE_PRESETS.md`, `page-base.css`, `html-template.md`, and browser internals are not default reads; agents open them only when changing the corresponding implementation.
Bundled commands resolve from the installed skill directory, so book inputs and outputs can remain in any workspace. Relative config paths resolve from `book.json`, not the shell working directory. Runtime packages are pinned in `package-lock.json`; the browser runner reuses installed or cached browsers first and installs into a persistent cache only as a logged final fallback.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 145 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: frontend-textbooks
- description: Create designed US Letter HTML textbooks, manuals, field guides, business books, and coffee-table books from supplied manuscripts, then verify and export matching PDFs. Use for new manuscript-to-book work, existing HTML book enhancement, print/mobile layout repair, manuscript-preserving diagrams or editorial imagery, and final book production.
- ---
- # Frontend Textbooks
- Turn a manuscript into a real book: editable HTML, a Letter PDF, cover options, verified assets, and evidence of manuscript preservation.
- ## Resolve the Skill
- Set the path once; keep project inputs and outputs in the user's workspace:
- ```bash
- SKILL_DIR="<absolute path to the directory containing this SKILL.md>"
- ```
- Run bundled commands through `node "$SKILL_DIR/scripts/book-pipeline.mjs"`.
- ## Ownership Boundary
- Scripts own deterministic work: parsing, stable source IDs, schemas, path safety, hashes, pagination measurements, diagnostics, screenshots, PDF export/inspection, caching, and manifests.
- The model owns judgment: audience and genre, user-facing color and typography recommendations, semantic classifications, theme/layout rationale, diagram, feature-page, and image choices, exception rationales, targeted repair decisions, and aesthetic approval. Express production decisions through the JSON contracts; do not encode them in prose for a script to interpret.
- ## Non-Negotiables
- - Preserve at least 90% of the manuscript unless the user explicitly requests abridgment. Preserve order, examples, tone, and vocabulary; additive tools never replace source prose.
- - Generate one original, manuscript-grounded local bitmap for every cover. It is mandatory, has no waiver, contains no baked-in typography, and may not be reused inside the book. A gradient, generic shape, SVG, stock placeholder, remote URL, or prior book's image is not cover artwork.
- - Produce HTML and PDF from the same source. Use US Letter, atomic designed pages, readable mobile flow, and no clipped content.
- - Make the result feel like a book, not a printed article or slide deck. Include appropriate front matter, page hierarchy, captions, running furniture, diagrams, and visual rhythm.
- - Keep production language out of reader-facing pages. Do not mention HTML, PDF export, Codex, AI, the skill, or a supplied manuscript inside the book unless requested.
- - Use distinct cover and part-divider assets. Never reuse cover art as an interior plate. Do not fabricate visual evidence.
- - Use bundled font files by default so HTML and PDF rendering stay deterministic and offline. `fontTheme` may select another registered typography pack independently of the color theme; `fontOverrides` declares a config-relative custom bundle with its license. A palette-only legacy style must choose one of those routes or set `fontMode: "system"` explicitly; bundled mode never silently falls back to machine fonts. Legacy `remote` configs normalize to bundled fonts, and their existing `allow-remote-fonts` plan exception remains accepted as a compatibility no-op.
- ## Default Workflow
- ### 1. Prepare inputs
- Create `book.json` and retain the source manuscript as Markdown. Author, title, and a config-relative `coverImage` target inside `outputDir` are required. Accept an author only from an explicit manuscript byline, user-supplied metadata, or a direct user statement; workspace paths, account names, Git identity, and unrelated prior projects are not reliable author sources. If no reliable author is available, ask for the byline before writing `book.json`. Relative paths always resolve from the directory containing `book.json`. Leave `style`, `themeOverrides`, `fontTheme`, and `fontOverrides` unresolved until the visual-system decision in step 2.
- Treat H1 as book metadata, H2 as chapters, and H3/H4 as interior sections. Use `### Chapter title {chapter}` only when an H3 must explicitly start a chapter; empty chapters are invalid. Use `themeOverrides` for validated palette adaptations. Set `selectedCoverRoute` to `photo` or `minimal`; the same route drives the option and final cover.
- Generate the stable source inventory:
- ```bash
- node "$SKILL_DIR/scripts/book-pipeline.mjs" inventory \
- --config book.json --manuscript manuscript.md
- ```
- ### 2. Choose color and typography with the user
- After reading the manuscript and `planning-inventory.json`, present three numbered visual-system choices grounded in its subject, tone, audience, and cultural context. Mark one as Recommended. Give each a short name, representative role-based hex swatches, and a display/body typography pairing from a registered bundled font theme. Include any requested font or typeface and palette; let the user mix a listed palette and typography or request another direction. Wait for the user's answer before planning, generating artwork, or building.
- Before naming bundled type, inspect the executable catalog with `node "$SKILL_DIR/scripts/font-catalog.mjs"`. If the user selects an unregistered Google Fonts family, run `node "$SKILL_DIR/scripts/acquire-google-fonts.mjs" --example`, create a request pinned to an immutable commit in the official `google/fonts` repository, and run it with `--project-root` and `--request`. Use the returned `fontOverrides`; never invent face filenames, weights, or license records.
- Record the answer in `book.json`: `style` and `themeOverrides` own color and image-prompt behavior; `fontTheme` independently selects a registered bundled typography pack. For an unregistered Google Fonts request, download official font files and license into the book workspace and declare the local bundle in `fontOverrides` instead of `fontTheme`. Resolved colors govern page CSS and artwork prompts; fonts govern HTML/PDF typography only. Keep the combined rationale in `book-plan.json.theme.rationale`. Read [references/intake-and-planning.md](references/intake-and-planning.md).
- ### 3. Make the model plan
- Read the manuscript and `planning-inventory.json`. Emit only schema-valid `book-plan.json` using `schemas/book-plan.schema.json`. Classify only salient blocks; unlisted blocks remain ordinary prose. Ground every classification, diagram, and feature page in stable source IDs. For designed nonfiction, plan 2–4 skim-worthy `visuals.featurePages` when the source supports them; at least one is required unless `waive-feature-pages` explains why the manuscript cannot support one. Record every policy waiver in `exceptions` with a concrete rationale.
- Read [references/reasoning-contracts.md](references/reasoning-contracts.md) when creating a plan, responding to repair tasks, or issuing an aesthetic verdict.
- ### 4. Generate the required cover artwork
- The plan must contain a grounded `visuals.cover` decision. Prepare the canonical request before generating anything:
- ```bash
- node "$SKILL_DIR/scripts/prepare-cover-image.mjs" \
- book.json manuscript.md book-plan.json
- ```
- When preparation returns `cover-generation-required`, read `cover-image-request.json`, call the available image-generation tool with its exact `prompt`, and save the result at its exact `targetAsset`. Its `palette` is compiled from the resolved theme colors and participates in the request hash. Reuse `palette.instruction` unchanged in prompts for any additional editorial illustrations. Do not rewrite the theme or palette prose or substitute supplied, stock, generic, or previously generated art. An occupied target without current matching provenance fails closed; `cover-ready` means the exact current request, receipt, and bytes were already revalidated. Then bind a newly generated bitmap to this manuscript and request:
- ```bash
- node "$SKILL_DIR/scripts/record-cover-image.mjs" \
- book.json manuscript.md book-plan.json
- ```
- If image generation is unavailable or fails, stop and report that cover generation is required. Never continue with an artwork-free or decorative-only fallback. The scripts reject missing, remote, escaping, corrupt, generic-alt, low-resolution, stale, and reused assets; the minimum effective cover resolution is 150 DPI in the actual configured crop (8.5 × 7.45 inches with the default cover band).
- ### 5. Build and verify at the right tier
- Use one public command surface:
- ```bash
- # Contract, source, asset, and deterministic build checks; no browser.
- node "$SKILL_DIR/scripts/book-pipeline.mjs" build \
- --config book.json --manuscript manuscript.md --plan book-plan.json --tier fast
- # Desktop/print/mobile verification and one contact sheet; no PDF.
- node "$SKILL_DIR/scripts/book-pipeline.mjs" verify \
- --config book.json --manuscript manuscript.md --plan book-plan.json --tier affected
- # Normal completion: verify, contact sheet, PDF, inspection, final manifest.
- node "$SKILL_DIR/scripts/book-pipeline.mjs" finalize \
- --config book.json --manuscript manuscript.md --plan book-plan.json --tier full
- ```
- Unchanged inputs reuse content-hashed results. Use `--force true` only when testing toolchain changes or invalidating a suspected cache error.
- ### 6. Handle targeted repairs
- On failure, read `.verification/repair-tasks.json`, its bounded source context, referenced screenshots, and only the named plan selections. Cover every independent actionable task that can be safely resolved in one `repair-actions.json`, validate the complete batch with `node "$SKILL_DIR/scripts/book-contract.mjs" validate-repairs .verification/repair-tasks.json repair-actions.json`, then apply the validated scoped changes together. Do not rerender after each action or reload the full manuscript or full render report unless the repair packet is insufficient.
- After each repair batch, run `verify --tier affected`. Repeat batched repair and affected verification until it passes; only then run `finalize --tier full` once. If finalization exposes a new repairable issue, batch the new tasks and return to affected verification before finalizing again. Use `.verification/diagnostics.json` for exact codes and measurements. Full evidence stays on disk; keep chat and command output compact.
- ### 7. Perform the visual judgment
- When finalization returns `review-required`, read `.verification/aesthetic-review-request.json`, inspect its full-page final cover, cover thumbnail/contact sheet, mobile cover, every planned feature-page screenshot at desktop and mobile sizes, every listed contact-sheet chunk, and every listed mobile evidence image, then inspect only the weakest full-size screenshots. Emit only `aesthetic-review.json` matching `schemas/aesthetic-review.schema.json`; copy the exact request and aggregate contact-sheet hashes. A `revise` verdict requires repairs. A `pass` verdict must reflect the actual hashed cover asset and route, cover hierarchy and crop, page rhythm, typography, feature-page and diagram clarity, whitespace, cohesion, and mobile reading.
- Resume without rerendering unchanged work:
- ```bash
- node "$SKILL_DIR/scripts/book-pipeline.mjs" finalize \
- --config book.json --manuscript manuscript.md --plan book-plan.json \
- --tier full --aesthetic-review aesthetic-review.json
- ```
- ### 8. Deliver
- Deliver the HTML, PDF, approximate page count, word and exact-block preservation percentages, and any material caveats. A complete run must have `artifact-manifest.json` with passing full verification, the exact cover asset hash and generation receipt, and, when required, a passing aesthetic review. Never report success when the selected final cover does not visibly use that asset.
- ## Design Decisions
- - Start chapters with actual prose, not unrequested opener spreads.
- - Use measured `.page.text-page` layouts for designed prose. Two columns suit analytical reading; one column suits slow emphasis; three columns suit short modular material.
- - Recommend color from the manuscript's meaning, not a generic genre preset, and let the user make the final choice before planning.
- - Add 2–4 manuscript-grounded full-page exhibits for designed nonfiction when the source supports them. Use `framework` for reusable lenses, `scorecard` for two-sided cases, and `numbers` for bounded comparative statistics; keep inline diagrams for sequence, hierarchy, anatomy, taxonomy, matrix, or system relationships.
- - Always generate manuscript-grounded cover artwork. Generate additional editorial images only when useful. The active theme template plus resolved theme colors are the sole sources of image-prompt prose and palette.
- - Treat short tail pages, sparse tools, and 4–6 item grids as deliberate compositions, not leftover blank space.
- - Use only the Photo and Minimal cover routes. Both must visibly integrate the required artwork; keep the selected route aligned with the final cover and evidence.
- Read only the reference needed for the current decision:
- - [references/intake-and-planning.md](references/intake-and-planning.md): intake defaults, content architecture, image policy, cover planning.
- - [references/visual-system.md](references/visual-system.md): diagram grammar, signature tools, imagery, page rhythm, cover quality.
- - [references/layout-and-html.md](references/layout-and-html.md): HTML architecture, measured pagination, atomic print CSS, mobile behavior.
- - [references/verification-gates.md](references/verification-gates.md): diagnostics, preservation, visual/PDF gates, delivery requirements.
- - [references/pdf-optimization.md](references/pdf-optimization.md): guarded direct export, installed-Chrome recovery, and standalone PDF inspection.
- - [references/reasoning-contracts.md](references/reasoning-contracts.md): strict plan, repair, exception, and aesthetic JSON contracts.
- - [references/iteration.md](references/iteration.md): incremental tiers, delta context, cache invalidation, and compact reporting.
- Do not read `STYLE_PRESETS.md`, `html-template.md`, `page-base.css`, browser internals, or all references by default. Read them only when changing the corresponding style, architecture, CSS, or tool implementation.
README.md · README · 275 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Frontend Textbooks
- A coding-agent skill for turning manuscripts, field guides, manuals, and long-form notes into designed HTML books and print-ready PDFs. It is packaged as a standalone skill: agents can start from `SKILL.md`, load the referenced support files, generate the HTML book, verify the rendered pages, and export a Letter-size PDF.
- ## What This Does
- **Frontend Textbooks** helps coding agents create book-like artifacts instead of dumping prose into a web page. It uses an HTML-first workflow: the editable source of truth is a browser-readable `index.html`, and the final PDF is exported from that same HTML after layout verification.
- The skill is built for textbook, manual, field-guide, executive briefing, and coffee-table-style books where typography, pacing, page rhythm, diagrams, covers, and print integrity matter.
- ### Key Features
- - **Print-Ready PDF Output** - Exports US Letter PDFs with page-safe CSS, printed backgrounds, and fixed-format designed pages.
- - **HTML First** - Produces a browser-readable HTML book before exporting the PDF, so the artifact stays inspectable and editable.
- - **Bundled Theme Typography** - Ships each font-bearing theme with redistributable licensed font files, copies the active faces and licenses into the book, and renders without font-network access.
- - **Enforced Manuscript Preservation** - Tracks stable source blocks and fails verification below 90% coverage instead of merely estimating preservation.
- - **Original Cover Artwork on Every Run** - Requires a unique manuscript-grounded local bitmap, binds it to the active theme prompt and manuscript hash, and fails closed instead of falling back to a typographic cover.
- - **Designed Book Rhythm** - Supports covers, title pages, tables of contents, part dividers, two-column reading pages, manuscript-grounded framework, scorecard, and numbers exhibits, diagrams, and chapter closers.
- - **Coffee-Table Feel When Appropriate** - Encourages image-led section dividers, spacious editorial pages, generated artwork, and strong cover routes when the manuscript calls for a more collectible book.
- - **Reusable Scaffold** - Includes a Markdown-to-book scaffold with focused Photo and Minimal cover options, browser-side pagination, chapter-close furniture, generated part images, mobile collapse behavior, and overflow assertions.
- - **Verification Scripts** - Provides Playwright-backed checks for readiness, allowlisted assets, source coverage, desktop/mobile overflow, every rendered page, and final PDF structure.
- - **Deterministic Pipeline** - One versioned command surface validates strict JSON contracts, caches content-addressed work, emits machine-readable diagnostics, and writes a final hash manifest.
- - **Model/Script Boundary** - Scripts own parsing and production mechanics; the model supplies compact plans, targeted repair decisions, exceptions, and aesthetic approval through schemas.
- - **Tiered Verification** - Fast builds avoid a browser, affected checks render changed source pages plus mobile, and full finalization verifies desktop/print/mobile and exports the PDF in one browser session.
- - **Compact Evidence** - Successful commands print a one-line summary while full reports, source accounting, screenshots, and ordered contact sheets remain on disk.
- ## Example Output
- These pages were rendered from an example PDF generated with the skill. The same workflow can produce textbook-style manuals, editorial field guides, and coffee-table-style books with image-led section pacing.
- <p>
- <img src="examples/walking-in-cover.png" width="220" alt="Example generated book cover">
- <img src="examples/walking-in-part-divider.png" width="220" alt="Example image-led part divider page">
- <img src="examples/walking-in-canvas.png" width="220" alt="Example framework canvas page">
- <img src="examples/walking-in-checklist.png" width="220" alt="Example two-column textbook page with a checklist">
- </p>
- ### Preview Every Theme
- The same fictional report, *Living with Dinosaurs*, is rendered below in every registered theme so typography, palette, composition, and image direction are easy to compare. Each row contains the cover and an image-led detail page. Click either large thumbnail to open the full-resolution JPEG.
- | Theme | Cover | Image-led detail |
- | --- | --- | --- |
- | `colbalt` | <a href="examples/theme-previews/living-with-dinosaurs/colbalt/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/colbalt/cover.jpg" width="300" alt="Colbalt cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/colbalt/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/colbalt/shared-morning.jpg" width="300" alt="Colbalt image-led detail preview"></a> |
- | `alumni` | <a href="examples/theme-previews/living-with-dinosaurs/alumni/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/alumni/cover.jpg" width="300" alt="Alumni cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/alumni/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/alumni/shared-morning.jpg" width="300" alt="Alumni image-led detail preview"></a> |
- | `mazius-libre` | <a href="examples/theme-previews/living-with-dinosaurs/mazius-libre/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/mazius-libre/cover.jpg" width="300" alt="Mazius Libre cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/mazius-libre/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/mazius-libre/shared-morning.jpg" width="300" alt="Mazius Libre image-led detail preview"></a> |
- | `regina-poppins` | <a href="examples/theme-previews/living-with-dinosaurs/regina-poppins/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/regina-poppins/cover.jpg" width="300" alt="Regina Poppins cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/regina-poppins/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/regina-poppins/shared-morning.jpg" width="300" alt="Regina Poppins image-led detail preview"></a> |
- | `monument-space` | <a href="examples/theme-previews/living-with-dinosaurs/monument-space/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/monument-space/cover.jpg" width="300" alt="Monument Space cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/monument-space/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/monument-space/shared-morning.jpg" width="300" alt="Monument Space image-led detail preview"></a> |
- | `sporting-agrandir` | <a href="examples/theme-previews/living-with-dinosaurs/sporting-agrandir/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/sporting-agrandir/cover.jpg" width="300" alt="Sporting Agrandir cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/sporting-agrandir/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/sporting-agrandir/shared-morning.jpg" width="300" alt="Sporting Agrandir image-led detail preview"></a> |
- | `millimetre-mondwest` | <a href="examples/theme-previews/living-with-dinosaurs/millimetre-mondwest/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/millimetre-mondwest/cover.jpg" width="300" alt="Millimetre Mondwest cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/millimetre-mondwest/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/millimetre-mondwest/shared-morning.jpg" width="300" alt="Millimetre Mondwest image-led detail preview"></a> |
- | `field-guide` | <a href="examples/theme-previews/living-with-dinosaurs/field-guide/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/field-guide/cover.jpg" width="300" alt="Field Guide cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/field-guide/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/field-guide/shared-morning.jpg" width="300" alt="Field Guide image-led detail preview"></a> |
- | `scholarly` | <a href="examples/theme-previews/living-with-dinosaurs/scholarly/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/scholarly/cover.jpg" width="300" alt="Scholarly cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/scholarly/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/scholarly/shared-morning.jpg" width="300" alt="Scholarly image-led detail preview"></a> |
- | `technical` | <a href="examples/theme-previews/living-with-dinosaurs/technical/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/technical/cover.jpg" width="300" alt="Technical cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/technical/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/technical/shared-morning.jpg" width="300" alt="Technical image-led detail preview"></a> |
- | `literary` | <a href="examples/theme-previews/living-with-dinosaurs/literary/cover.jpg"><img src="examples/theme-previews/living-with-dinosaurs/literary/cover.jpg" width="300" alt="Literary cover preview"></a> | <a href="examples/theme-previews/living-with-dinosaurs/literary/shared-morning.jpg"><img src="examples/theme-previews/living-with-dinosaurs/literary/shared-morning.jpg" width="300" alt="Literary image-led detail preview"></a> |
- The repository also includes a buildable [five-theme type-pairing fixture](examples/theme-gallery/index.html), using a separate fictional report for focused regression comparisons. Rebuild its HTML with `npm run build:theme-samples` or render all 15 fixture PNGs with `npm run render:theme-samples`.
- ## Why Codex Is Recommended
- Codex is highly recommended for this skill because it can combine file editing, shell scripts, browser/PDF verification, and image generation in one workflow. That matters for book production: the best results often need generated cover art, section-divider images, visual plates, and manuscript-grounded editorial illustrations, then a rendered PDF pass to confirm those assets actually print cleanly.
- ## Installation
- ### Codex Manual Installation
- Clone this repository into your Codex skills directory:
- ```bash
- git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.codex/skills/frontend-textbooks
- cd ~/.codex/skills/frontend-textbooks
- npm ci
- npm run setup:browsers
- ```
- Then ask Codex to use the `frontend-textbooks` skill when you want to turn manuscript text into a designed book and PDF.
- ### Claude Code Manual Installation
- Copy or clone the skill into Claude Code's skills directory:
- ```bash
- git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.claude/skills/frontend-textbooks
- cd ~/.claude/skills/frontend-textbooks
- npm ci
- npm run setup:browsers
- ```
- Then use it as a standalone skill by asking Claude Code to use `frontend-textbooks`.
- ### Other Coding Agents
- Other local coding assistants can use the same core skill if they can read files and run shell commands. Point the agent at this repository and ask it to start from:
- ```text
- SKILL.md
- ```
- The skill file routes the agent to optional references only when needed:
- - `references/intake-and-planning.md`
- - `references/visual-system.md`
- - `references/layout-and-html.md`
- - `references/verification-gates.md`
- - `references/reasoning-contracts.md`
- - `references/iteration.md`
- `STYLE_PRESETS.md`, `page-base.css`, `html-template.md`, and browser internals are not default reads; agents open them only when changing the corresponding implementation.
- Bundled commands resolve from the installed skill directory, so book inputs and outputs can remain in any workspace. Relative config paths resolve from `book.json`, not the shell working directory. Runtime packages are pinned in `package-lock.json`; the browser runner reuses installed or cached browsers first and installs into a persistent cache only as a logged final fallback.
- ## Usage
- ### Create a New Textbook or Field Guide
- ```text
- Use the frontend-textbooks skill to turn this manuscript into a print-ready PDF book.
- ```
- The skill will:
- 1. Locate or ingest the manuscript.
- 2. Analyze its subject, tone, audience, and cultural context.
- 3. Recommend a topic-aware color and typography system alongside two alternatives, honor any requested palette or typeface, and pause until the user chooses.
- 4. Infer a book structure that preserves the source text.
- 5. Plan the cover subject, chapter rhythm, structured diagrams, generated images, and 2–4 skim-worthy full-page exhibits when the manuscript supports them.
- 6. Generate and record a unique manuscript-grounded cover bitmap using the active theme's canonical prompt.
- 7. Generate a designed HTML book and matching PDF.
- 8. Verify page integrity, overflow, ordered text preservation, generated assets, cover evidence, and mobile readability.
- The public command surface is `scripts/book-pipeline.mjs`:
- ```bash
- # Generate stable source IDs for the model-authored plan.
- node scripts/book-pipeline.mjs inventory --config book.json --manuscript manuscript.md
- # Compile the canonical cover request, generate its target with an image tool,
- # then bind that exact bitmap to this manuscript and plan.
- node scripts/prepare-cover-image.mjs book.json manuscript.md book-plan.json
- node scripts/record-cover-image.mjs book.json manuscript.md book-plan.json
- # Deterministic build checks, without Chromium.
- node scripts/book-pipeline.mjs build --config book.json --manuscript manuscript.md --plan book-plan.json --tier fast
- # Changed-page desktop/mobile verification, without PDF export.
- node scripts/book-pipeline.mjs verify --config book.json --manuscript manuscript.md --plan book-plan.json --tier affected
- # Full rendered verification, ordered contact sheets, PDF export, and artifact manifest.
- node scripts/book-pipeline.mjs finalize --config book.json --manuscript manuscript.md --plan book-plan.json --tier full
- ```
- If the plan requires aesthetic review, the first full run returns `review-required`. Inspect every contact sheet plus every desktop/mobile feature-page image, write schema-valid `aesthetic-review.json`, and rerun with `--aesthetic-review aesthetic-review.json`; unchanged rendering and PDF work are reused.
- Pipeline stdout is always one compact JSON object, including failures. Full evidence remains on disk; `render-report.json` uses `schemaVersion: 2` and reports only failed or partial source blocks instead of a successful per-block inventory.
- ## Included Styles
- Interactive runs recommend three manuscript-grounded visual systems and wait for the user's color and typography choice. `book.json.style` plus `themeOverrides` control color and image-prompt behavior; `fontTheme` may independently select another registered bundled typography pack. A requested Google Fonts family that is not registered can be downloaded with its OFL license into the book workspace and declared through `fontOverrides`; the build still renders offline. Palette-only legacy styles must pair with `fontTheme`/`fontOverrides` or explicitly use `fontMode: "system"`—bundled mode never silently falls back to machine fonts. For direct or legacy configs without a style, the runtime fallback is `colbalt`, a cobalt editorial system defined in `themes/colbalt`:
- - Poppins-compatible local fallbacks for headings and labels by default
- - Halant-compatible local serif fallbacks for body copy by default
- - Deep cobalt hierarchy with lighter cobalt-blue accents
- - Warm paper background
- - Two-column editorial reading pages
- - Solid-band split cover support for generated or supplied artwork
- The scaffold also includes an `alumni` theme inspired by a warm single-ink editorial system: Bricolage Grotesque display type, Fraunces body copy, rust terracotta ink, and cream paper.
- Five additional themes adapt selected pairings from [“8 expressive free font combos for your next design”](https://dribbble.com/stories/2020/06/10/free-font-combinations) into executable, offline packs:
- | Theme | Rendered preview | Bundled typography | Palette and image direction |
- | --- | --- | --- | --- |
- | [`mazius-libre`](examples/theme-gallery/mazius-libre/index.html) | <a href="examples/theme-gallery/mazius-libre/index.html"><img src="examples/theme-gallery/mazius-libre/cover.png" width="112" alt="Mazius Libre theme cover"></a> | Mazius Display + Libre Baskerville | Graphite `#232323`, paper `#F9F9F9`, chartreuse `#E4FF5E`; moody hard-daylight photography with deep shadow and disciplined negative space. |
- | [`regina-poppins`](examples/theme-gallery/regina-poppins/index.html) | <a href="examples/theme-gallery/regina-poppins/index.html"><img src="examples/theme-gallery/regina-poppins/cover.png" width="112" alt="Regina Poppins theme cover"></a> | Shrikhand + Poppins | Golden `#FFDB60`, coral `#F74735`, plum `#3A2031`; grainy airbrushed illustration with rounded poster forms and natural shadows. |
- | [`monument-space`](examples/theme-gallery/monument-space/index.html) | <a href="examples/theme-gallery/monument-space/index.html"><img src="examples/theme-gallery/monument-space/cover.png" width="112" alt="Monument Space theme cover"></a> | Archivo Black + Space Mono | Paper `#F4F4EA`, signal red `#FF213A`, navy `#11182E`; limited-ink risograph illustration with exposed paper and coarse halftones. |
- | [`sporting-agrandir`](examples/theme-gallery/sporting-agrandir/index.html) | <a href="examples/theme-gallery/sporting-agrandir/index.html"><img src="examples/theme-gallery/sporting-agrandir/cover.png" width="112" alt="Sporting Agrandir theme cover"></a> | Sporting Grotesque + Barlow Semi Condensed | Electric blue `#0000FE`, off-white `#FBFBEF`, acid lime `#C9FF68`; naïve hand-drawn illustration with flat fields and scratchy fills. |
- | [`millimetre-mondwest`](examples/theme-gallery/millimetre-mondwest/index.html) | <a href="examples/theme-gallery/millimetre-mondwest/index.html"><img src="examples/theme-gallery/millimetre-mondwest/cover.png" width="112" alt="Millimetre Mondwest theme cover"></a> | Millimetre + Departure Mono | Sage `#AEB1A0`, ink black `#0A0A09`, signal orange `#FF7417`; bold screenprint-like illustration with heavy contours and matte graphic fields. |
- Set any ID as `book.json.style` to apply its complete palette, typography, and canonical image prompt:
- ```json
- {
- "style": "millimetre-mondwest"
- }
- ```
- Use the same ID as `fontTheme` when you only want its typography. Every complete theme binds generated artwork to its active semantic colors and keeps subjects ordinary, physically coherent, and at normal scale so the medium supplies the personality without making future book imagery surreal.
- The redistributable replacements preserve each original pairing’s direction without bundling personal-use, trial, or non-commercial files. Every source, immutable revision, license, and substitution rationale is recorded in [`themes/FONT_SOURCES.md`](themes/FONT_SOURCES.md).
- For example, `{"style":"colbalt","fontTheme":"alumni"}` keeps the cobalt palette and cover-art language while using Alumni's Bricolage Grotesque/Fraunces typography. Custom `fontOverrides` use the same display/body/UI roles and must declare every local face and license.
- Agents can inspect the executable packs with `node scripts/font-catalog.mjs`. For an unregistered Google Fonts request, `node scripts/acquire-google-fonts.mjs --example` prints the pinned request format; the completed command downloads faces and licenses from the official `google/fonts` repository and returns a ready-to-use `fontOverrides` object.
- Additional presets in `STYLE_PRESETS.md` include scholarly, field-guide, technical, literary, editorial journal, and product-manual directions. To make a preset available to the scaffold, add it as a module under `themes/` and register it in `themes/index.mjs`.
- ## Repository Contents
- ```text
- frontend-textbooks/
- SKILL.md
- STYLE_PRESETS.md
- page-base.css
- html-template.md
- animation-patterns.md
- package.json
- package-lock.json
- .github/workflows/ci.yml
- references/
- intake-and-planning.md
- iteration.md
- layout-and-html.md
- pdf-optimization.md
- reasoning-contracts.md
- verification-gates.md
- visual-system.md
- schemas/
- book-config.schema.json
- book-plan.schema.json
- diagnostics.schema.json
- repair-actions.schema.json
- repair-tasks.schema.json
- aesthetic-review.schema.json
- artifact-manifest.schema.json
- themes/
- alumni/
- index.mjs
- colbalt/
- index.mjs
- index.mjs
- scripts/
- book-pipeline.mjs
- book-contract.mjs
- build-html-book.mjs
- prepare-cover-image.mjs
- record-cover-image.mjs
- book-browser.mjs
- export-pdf.sh
- export-ready-pdf.sh
- export-local-chrome.sh
- verify-html-book.sh
- verify-rendered-book.sh
- inspect-pdf.sh
- run-book-browser.sh
- create-contact-sheet.mjs
- pdf-inspection.mjs
- tests/
- ```
- ## Design Philosophy
- Frontend Textbooks treats books as designed systems:
- - Preserve the manuscript.
- - Let HTML be the editable source.
- - Verify the PDF, not just the browser.
- - Keep publishing and hosting provider choices outside the book-production toolchain.
- - Make covers sell the book.
- - Make diagrams explain before they decorate.
- - Own whitespace.
- - Avoid generic AI visual habits.
- - Generate a unique manuscript-grounded cover image every time; use additional generated images when they add clarity, pacing, atmosphere, or book-like richness.
- ## Migration to Plan v3
- Plan v3 adds required `visuals.featurePages`. Designed nonfiction should provide 2–4 grounded `framework`, `scorecard`, or `numbers` decisions; a manuscript that cannot support one uses an empty array plus a justified `waive-feature-pages` exception. Version 2 plans fail with `book-plan.version must be one of: 3` until migrated. Existing projects without original cover art still fail closed: add a local `coverImage` target and complete `visuals.cover`, then run `prepare-cover-image.mjs`, generate the exact requested bitmap, and run `record-cover-image.mjs`. There is no artwork-free waiver. The only supported cover routes are `photo` and `minimal`.
- ## Credits
- Inspired by [Zara Zhang's `frontend-slides`](https://github.com/zarazhangrui/frontend-slides), especially the skill-first packaging idea, HTML-first artifact workflow, installation structure, and README organization. Thank you, Zara.
- The expressive pairing themes and their specimen palettes are based on selected pairings from [Renee Fleck’s Dribbble article “8 expressive free font combos for your next design”](https://dribbble.com/stories/2020/06/10/free-font-combinations), with the pairings curated and visually demonstrated by Davide Baratta. Thank you, Renee and Davide.
- ## License
- This project is available under the MIT License.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.