Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/onepixelaway--frontend-textbooks/badge.svg)](/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

i

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)

  1. ---
  2. name: frontend-textbooks
  3. 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.
  4. ---
  5. # Frontend Textbooks
  6. Turn a manuscript into a real book: editable HTML, a Letter PDF, cover options, verified assets, and evidence of manuscript preservation.
  7. ## Resolve the Skill
  8. Set the path once; keep project inputs and outputs in the user's workspace:
  9. ```bash
  10. SKILL_DIR="<absolute path to the directory containing this SKILL.md>"
  11. ```
  12. Run bundled commands through `node "$SKILL_DIR/scripts/book-pipeline.mjs"`.
  13. ## Ownership Boundary
  14. Scripts own deterministic work: parsing, stable source IDs, schemas, path safety, hashes, pagination measurements, diagnostics, screenshots, PDF export/inspection, caching, and manifests.
  15. 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.
  16. ## Non-Negotiables
  17. - 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.
  18. - 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.
  19. - Produce HTML and PDF from the same source. Use US Letter, atomic designed pages, readable mobile flow, and no clipped content.
  20. - 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.
  21. - 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.
  22. - Use distinct cover and part-divider assets. Never reuse cover art as an interior plate. Do not fabricate visual evidence.
  23. - 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.
  24. ## Default Workflow
  25. ### 1. Prepare inputs
  26. 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.
  27. 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.
  28. Generate the stable source inventory:
  29. ```bash
  30. node "$SKILL_DIR/scripts/book-pipeline.mjs" inventory \
  31. --config book.json --manuscript manuscript.md
  32. ```
  33. ### 2. Choose color and typography with the user
  34. 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.
  35. 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.
  36. 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).
  37. ### 3. Make the model plan
  38. 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.
  39. Read [references/reasoning-contracts.md](references/reasoning-contracts.md) when creating a plan, responding to repair tasks, or issuing an aesthetic verdict.
  40. ### 4. Generate the required cover artwork
  41. The plan must contain a grounded `visuals.cover` decision. Prepare the canonical request before generating anything:
  42. ```bash
  43. node "$SKILL_DIR/scripts/prepare-cover-image.mjs" \
  44. book.json manuscript.md book-plan.json
  45. ```
  46. 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:
  47. ```bash
  48. node "$SKILL_DIR/scripts/record-cover-image.mjs" \
  49. book.json manuscript.md book-plan.json
  50. ```
  51. 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).
  52. ### 5. Build and verify at the right tier
  53. Use one public command surface:
  54. ```bash
  55. # Contract, source, asset, and deterministic build checks; no browser.
  56. node "$SKILL_DIR/scripts/book-pipeline.mjs" build \
  57. --config book.json --manuscript manuscript.md --plan book-plan.json --tier fast
  58. # Desktop/print/mobile verification and one contact sheet; no PDF.
  59. node "$SKILL_DIR/scripts/book-pipeline.mjs" verify \
  60. --config book.json --manuscript manuscript.md --plan book-plan.json --tier affected
  61. # Normal completion: verify, contact sheet, PDF, inspection, final manifest.
  62. node "$SKILL_DIR/scripts/book-pipeline.mjs" finalize \
  63. --config book.json --manuscript manuscript.md --plan book-plan.json --tier full
  64. ```
  65. Unchanged inputs reuse content-hashed results. Use `--force true` only when testing toolchain changes or invalidating a suspected cache error.
  66. ### 6. Handle targeted repairs
  67. 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.
  68. 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.
  69. ### 7. Perform the visual judgment
  70. 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.
  71. Resume without rerendering unchanged work:
  72. ```bash
  73. node "$SKILL_DIR/scripts/book-pipeline.mjs" finalize \
  74. --config book.json --manuscript manuscript.md --plan book-plan.json \
  75. --tier full --aesthetic-review aesthetic-review.json
  76. ```
  77. ### 8. Deliver
  78. 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.
  79. ## Design Decisions
  80. - Start chapters with actual prose, not unrequested opener spreads.
  81. - 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.
  82. - Recommend color from the manuscript's meaning, not a generic genre preset, and let the user make the final choice before planning.
  83. - 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.
  84. - 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.
  85. - Treat short tail pages, sparse tools, and 4–6 item grids as deliberate compositions, not leftover blank space.
  86. - 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.
  87. Read only the reference needed for the current decision:
  88. - [references/intake-and-planning.md](references/intake-and-planning.md): intake defaults, content architecture, image policy, cover planning.
  89. - [references/visual-system.md](references/visual-system.md): diagram grammar, signature tools, imagery, page rhythm, cover quality.
  90. - [references/layout-and-html.md](references/layout-and-html.md): HTML architecture, measured pagination, atomic print CSS, mobile behavior.
  91. - [references/verification-gates.md](references/verification-gates.md): diagnostics, preservation, visual/PDF gates, delivery requirements.
  92. - [references/pdf-optimization.md](references/pdf-optimization.md): guarded direct export, installed-Chrome recovery, and standalone PDF inspection.
  93. - [references/reasoning-contracts.md](references/reasoning-contracts.md): strict plan, repair, exception, and aesthetic JSON contracts.
  94. - [references/iteration.md](references/iteration.md): incremental tiers, delta context, cache invalidation, and compact reporting.
  95. 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)

  1. # Frontend Textbooks
  2. 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.
  3. ## What This Does
  4. **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.
  5. 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.
  6. ### Key Features
  7. - **Print-Ready PDF Output** - Exports US Letter PDFs with page-safe CSS, printed backgrounds, and fixed-format designed pages.
  8. - **HTML First** - Produces a browser-readable HTML book before exporting the PDF, so the artifact stays inspectable and editable.
  9. - **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.
  10. - **Enforced Manuscript Preservation** - Tracks stable source blocks and fails verification below 90% coverage instead of merely estimating preservation.
  11. - **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.
  12. - **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.
  13. - **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.
  14. - **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.
  15. - **Verification Scripts** - Provides Playwright-backed checks for readiness, allowlisted assets, source coverage, desktop/mobile overflow, every rendered page, and final PDF structure.
  16. - **Deterministic Pipeline** - One versioned command surface validates strict JSON contracts, caches content-addressed work, emits machine-readable diagnostics, and writes a final hash manifest.
  17. - **Model/Script Boundary** - Scripts own parsing and production mechanics; the model supplies compact plans, targeted repair decisions, exceptions, and aesthetic approval through schemas.
  18. - **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.
  19. - **Compact Evidence** - Successful commands print a one-line summary while full reports, source accounting, screenshots, and ordered contact sheets remain on disk.
  20. ## Example Output
  21. 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.
  22. <p>
  23. <img src="examples/walking-in-cover.png" width="220" alt="Example generated book cover">
  24. <img src="examples/walking-in-part-divider.png" width="220" alt="Example image-led part divider page">
  25. <img src="examples/walking-in-canvas.png" width="220" alt="Example framework canvas page">
  26. <img src="examples/walking-in-checklist.png" width="220" alt="Example two-column textbook page with a checklist">
  27. </p>
  28. ### Preview Every Theme
  29. 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.
  30. | Theme | Cover | Image-led detail |
  31. | --- | --- | --- |
  32. | `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> |
  33. | `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> |
  34. | `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> |
  35. | `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> |
  36. | `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> |
  37. | `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> |
  38. | `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> |
  39. | `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> |
  40. | `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> |
  41. | `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> |
  42. | `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> |
  43. 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`.
  44. ## Why Codex Is Recommended
  45. 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.
  46. ## Installation
  47. ### Codex Manual Installation
  48. Clone this repository into your Codex skills directory:
  49. ```bash
  50. git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.codex/skills/frontend-textbooks
  51. cd ~/.codex/skills/frontend-textbooks
  52. npm ci
  53. npm run setup:browsers
  54. ```
  55. Then ask Codex to use the `frontend-textbooks` skill when you want to turn manuscript text into a designed book and PDF.
  56. ### Claude Code Manual Installation
  57. Copy or clone the skill into Claude Code's skills directory:
  58. ```bash
  59. git clone https://github.com/onepixelaway/frontend-textbooks.git ~/.claude/skills/frontend-textbooks
  60. cd ~/.claude/skills/frontend-textbooks
  61. npm ci
  62. npm run setup:browsers
  63. ```
  64. Then use it as a standalone skill by asking Claude Code to use `frontend-textbooks`.
  65. ### Other Coding Agents
  66. 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:
  67. ```text
  68. SKILL.md
  69. ```
  70. The skill file routes the agent to optional references only when needed:
  71. - `references/intake-and-planning.md`
  72. - `references/visual-system.md`
  73. - `references/layout-and-html.md`
  74. - `references/verification-gates.md`
  75. - `references/reasoning-contracts.md`
  76. - `references/iteration.md`
  77. `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.
  78. 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.
  79. ## Usage
  80. ### Create a New Textbook or Field Guide
  81. ```text
  82. Use the frontend-textbooks skill to turn this manuscript into a print-ready PDF book.
  83. ```
  84. The skill will:
  85. 1. Locate or ingest the manuscript.
  86. 2. Analyze its subject, tone, audience, and cultural context.
  87. 3. Recommend a topic-aware color and typography system alongside two alternatives, honor any requested palette or typeface, and pause until the user chooses.
  88. 4. Infer a book structure that preserves the source text.
  89. 5. Plan the cover subject, chapter rhythm, structured diagrams, generated images, and 2–4 skim-worthy full-page exhibits when the manuscript supports them.
  90. 6. Generate and record a unique manuscript-grounded cover bitmap using the active theme's canonical prompt.
  91. 7. Generate a designed HTML book and matching PDF.
  92. 8. Verify page integrity, overflow, ordered text preservation, generated assets, cover evidence, and mobile readability.
  93. The public command surface is `scripts/book-pipeline.mjs`:
  94. ```bash
  95. # Generate stable source IDs for the model-authored plan.
  96. node scripts/book-pipeline.mjs inventory --config book.json --manuscript manuscript.md
  97. # Compile the canonical cover request, generate its target with an image tool,
  98. # then bind that exact bitmap to this manuscript and plan.
  99. node scripts/prepare-cover-image.mjs book.json manuscript.md book-plan.json
  100. node scripts/record-cover-image.mjs book.json manuscript.md book-plan.json
  101. # Deterministic build checks, without Chromium.
  102. node scripts/book-pipeline.mjs build --config book.json --manuscript manuscript.md --plan book-plan.json --tier fast
  103. # Changed-page desktop/mobile verification, without PDF export.
  104. node scripts/book-pipeline.mjs verify --config book.json --manuscript manuscript.md --plan book-plan.json --tier affected
  105. # Full rendered verification, ordered contact sheets, PDF export, and artifact manifest.
  106. node scripts/book-pipeline.mjs finalize --config book.json --manuscript manuscript.md --plan book-plan.json --tier full
  107. ```
  108. 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.
  109. 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.
  110. ## Included Styles
  111. 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`:
  112. - Poppins-compatible local fallbacks for headings and labels by default
  113. - Halant-compatible local serif fallbacks for body copy by default
  114. - Deep cobalt hierarchy with lighter cobalt-blue accents
  115. - Warm paper background
  116. - Two-column editorial reading pages
  117. - Solid-band split cover support for generated or supplied artwork
  118. 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.
  119. 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:
  120. | Theme | Rendered preview | Bundled typography | Palette and image direction |
  121. | --- | --- | --- | --- |
  122. | [`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. |
  123. | [`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. |
  124. | [`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. |
  125. | [`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. |
  126. | [`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. |
  127. Set any ID as `book.json.style` to apply its complete palette, typography, and canonical image prompt:
  128. ```json
  129. {
  130. "style": "millimetre-mondwest"
  131. }
  132. ```
  133. 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.
  134. 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).
  135. 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.
  136. 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.
  137. 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`.
  138. ## Repository Contents
  139. ```text
  140. frontend-textbooks/
  141. SKILL.md
  142. STYLE_PRESETS.md
  143. page-base.css
  144. html-template.md
  145. animation-patterns.md
  146. package.json
  147. package-lock.json
  148. .github/workflows/ci.yml
  149. references/
  150. intake-and-planning.md
  151. iteration.md
  152. layout-and-html.md
  153. pdf-optimization.md
  154. reasoning-contracts.md
  155. verification-gates.md
  156. visual-system.md
  157. schemas/
  158. book-config.schema.json
  159. book-plan.schema.json
  160. diagnostics.schema.json
  161. repair-actions.schema.json
  162. repair-tasks.schema.json
  163. aesthetic-review.schema.json
  164. artifact-manifest.schema.json
  165. themes/
  166. alumni/
  167. index.mjs
  168. colbalt/
  169. index.mjs
  170. index.mjs
  171. scripts/
  172. book-pipeline.mjs
  173. book-contract.mjs
  174. build-html-book.mjs
  175. prepare-cover-image.mjs
  176. record-cover-image.mjs
  177. book-browser.mjs
  178. export-pdf.sh
  179. export-ready-pdf.sh
  180. export-local-chrome.sh
  181. verify-html-book.sh
  182. verify-rendered-book.sh
  183. inspect-pdf.sh
  184. run-book-browser.sh
  185. create-contact-sheet.mjs
  186. pdf-inspection.mjs
  187. tests/
  188. ```
  189. ## Design Philosophy
  190. Frontend Textbooks treats books as designed systems:
  191. - Preserve the manuscript.
  192. - Let HTML be the editable source.
  193. - Verify the PDF, not just the browser.
  194. - Keep publishing and hosting provider choices outside the book-production toolchain.
  195. - Make covers sell the book.
  196. - Make diagrams explain before they decorate.
  197. - Own whitespace.
  198. - Avoid generic AI visual habits.
  199. - Generate a unique manuscript-grounded cover image every time; use additional generated images when they add clarity, pacing, atmosphere, or book-like richness.
  200. ## Migration to Plan v3
  201. 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`.
  202. ## Credits
  203. 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.
  204. 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.
  205. ## License
  206. This project is available under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.