Frontend Textbooks

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:

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:

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.

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 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:

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:

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).