---
name: document-design
description: Compose actual Document Studio document HTML from final-language copy and assets, including distinct covers, detailed bodies, charts and image art direction. Use for new or changed visual composition; preserve selected expression and supported evidence, then hand the reviewed HTML to export.
---

# HTML document design

In the explicitly opted-in [Editorial Consulting Mode](../report-html-pptx/references/editorial-consulting-mode.md), an **early representative HTML preview** is a bounded comparison of substantive visual directions only. Keep it under `planning/previews/`; use real supported copy or conspicuously labelled illustrative content and inspect the rendered sample when possible. It is not canonical `html/index.html`, not final art direction for all pages, and never a verified production Design/Export receipt. After the author selects the direction, return to deep research/writing; resume this normal HTML design workflow only from the accepted final-language manuscript, with freedom to revise the exploratory geometry to fit the evidence and body copy.

For new full work, the [accepted guide baseline](../report-html-pptx/references/accepted-composition-default.md) is the routine composition level: expressive/rich with calm readable detailed bodies. Inspect its relevant actual body pages and implement meaningful images, native diagrams and varied reading relationships in the current content. Preserve explicit style/templates; do not treat this as a fixed canvas, page sequence or image quota.

Reuse the current brief, actual final-language copy, page map and assets. Document composition is fixed to HTML under [authoring routes](../report-html-pptx/system/authoring-routes.md); default delivery uses [HTML-to-PPTX](../html-to-pptx/SKILL.md). Templates constrain actual size, identity and accepted layout; they do not trigger native authoring. Routine missing preferences use the orchestrator's working defaults. Local edits preserve the unaffected composition.

When the user selects an **approved Company Pack**, consult `../report-html-pptx/scripts/select_layout_grammar.py` before choosing each major page relationship. Supply document family, page job, actual content roles, density and intended use; inspect matching evidence IDs, brand constraints and permissible variations. Treat these results as **adaptable design relationships**, never pixels to clone. Preserve Brand DNA where justified, choose composition freely for new content, and use the neutral design path explicitly when no reviewed grammar fits. Do not use suggested, stale or unreviewed rules in a production document; the package approval and source-rights checks remain separate.

**Approved grammar composition contract (after final-language manuscript):** Enumerate actual pages, reader questions, reading order and stable `element_id`/role pairs in `content/page-brief.json` (`layout-page-brief/1.0`), using only verified and rights-cleared `html/assets` files. Run `../report-html-pptx/scripts/plan_layout_grammar.py --project PROJECT --page-brief content/page-brief.json --company-pack PACK` to produce `content/layout-plan.json`. Consume its per-page `rules[].relationships`, `element_roles`, source evidence and permissible variation as authoritative constraints, not as preformatted layout geometry. Resolve `needs_revision` conflicts in the manuscript/map before drawing; `neutral_fallback` is general design, not approved corporate grammar. Let each page's real content determine typography-, image-, narrative-, diagram- or data-led form; do not stamp a universal source-page template across distinct page jobs.

In actual `html/index.html`, give each planned page one `data-page-id`, and give every rule-governed content element its approved `data-grammar-element-id` and whitespace-separated `data-grammar-rule-ids`. IDs must exactly match the page contract; keep native labels and verified assets. Use `html_grammar_contract.py` to identify missing/duplicate/foreign traces, then `audit_layout_grammar.py --project PROJECT` for **rendered** relationships, clipping/overflow and page screenshots. `PASS` for semantic traces is not geometric PASS; geometric PASS is not human/vision approval. Review the actual cover and substantive body pages plus all flagged pages at output size, revise, rerender, and retain explicit `UNVERIFIED` if the browser is unavailable. A changed source, copy, font, pack, canvas or HTML invalidates the affected check; retain the separate PPTX export inspection.

Reader question → supported relationship → **choose the visual medium** → art-directed asset when needed → native labels → composition. For covers, hero images, complex objects/3D scenes or disputed code-only results, use [visual-medium selection](references/visual-medium-selection.md) before detailed HTML. HTML is the layout/integration source, not an instruction to draw every subject in CSS/SVG. Prefer actual generated or verified visuals when pictorial fidelity matters; keep exact business text, data and connectors native. A typography-only or purely native diagram remains valid. Use [design system](../report-html-pptx/system/design-system.md) and [tokens](../report-html-pptx/system/design-tokens.json) for purpose, family, font/grid/palette defaults. Numeric values stay in tokens; scripts/build_design_css.py generates the shared CSS. Reading/report and live-viewing density remain distinct even though both produce PPTX. Recompose live content for distance; preserve detailed conditions in its reading companion when needed.
For new arrow-connected process/relationship diagrams, treat each item as a separate card area and center its title and explanatory text within that area, including the first and last items. Keep connectors in separate lanes; use equal item widths for equivalent stages. Follow [arrow diagram alignment](references/arrow-diagram-alignment.md). Preserve explicit accepted-template alignment outside the requested scope.
New Korean text uses bundled Pretendard (the Korean family); Japanese uses bundled Pretendard JP. Mark each bilingual passage's actual language. Preserve accepted template fonts with located provenance; do not replace either language's required font with a generic fallback or treat embedding alone as actual rendering proof.

Select useful actual relationships from [DEMO cases](../report-html-pptx/references/demo-esg-design.md) and [expression](../report-html-pptx/references/design-expression.md). Start the relevant `select_esg_reference.py --summary` / `select_creative_reference.py --summary` for at most three short case identities. Expand only selected cases and inspect their actual relevant visuals; do not routinely open the full 100KB casebook or 121KB gallery HTML. Reuse accepted selections. Creativity and visual intensity are independent. Official fonts/assets and meaningful detail stay intact; purposeful color, texture, scale and asymmetry can extend the defaults.

For substantive pages apply [body composition](../report-html-pptx/references/body-composition.md); open a relevant [body study](../report-html-pptx/assets/body-compositions/index.html) only after selecting its page job. Compose connected scenes/local labels, dominant/supporting mosaics, cross-column prose/photo flow or whole/detail views according to the actual question. A cover is not body-quality evidence. Do not repeat an image-and-table split, cards or unsupported oversized numbers on every page. A useful prose/table-only page remains valid.

Use actual paragraphs and source assets from the first meaningful page; do not design around lorem ipsum or empty image slots and call it a proof. Record dominant element and reading sequence in the existing map. Keep project-relative files under html/assets, native business text/table cells/labels and meaningful SVG connectors. Author a specific page directly when a generator cannot express the relationship. [DEMO CSS/examples](../report-html-pptx/assets/demo-esg-design/index.html) and [consulting parts](../report-html-pptx/references/consulting-parts.md) are adaptable relationships, not compulsory page sequences.

When the medium choice calls for a scene, source/generate and inspect the actual hero asset before polishing its surrounding CSS; do not replace a needed building, person or material with placeholder geometry that merely passes the grid audit. Before rich image production, give [visual assets](../visual-assets/SKILL.md) a concrete job through [asset requests](references/visual-asset-requests.md): meaning/subjects, image role, final frame/aspect, crop protection, view, quiet overlay zone, caption, reference role and actual/concept status. Important Korean/Japanese labels, quantities and connectors stay native. Research acquires factual originals; generated facilities/activities are concepts. Planned overlay coordinates are confirmed only after inspecting actual output.

Integrate actual returned files and inspect focal subject, crop, source/concept disclosure, label association and series consistency at final size. Mixed-ratio groups use deliberate edges/heights and caption baselines while preserving packshot/poster identity. Use [image placement](../report-html-pptx/references/demo-esg-image-layout.md) and [user image composition](../report-html-pptx/references/user-image-composition.md) only for their relevant relationship.

Apply writing's [semantic line-break decisions](../document-writing/references/semantic-linebreaks.md) to the actual HTML: preserve the copy, add only justified local breaks, and retain natural wrapping within each reading unit. Keep zero extra paragraph gap when the intent is a simple line break. Recalculate text height, adjacent blocks and footer clearance after adding lines. Do not squeeze type or freeze every physical line.

For a new full document, inspect every page at final size and read titles, prose, prompts, table cells, captions and footer boundaries. For a revision, inspect affected pages plus the sequence; global font/style/canvas changes reopen the full affected set. Readable margins alone do not establish Korean clarity or spacing: return language problems to writing. Keep each text-flow candidate's page/block/line and an actual reviewed disposition under [completion quality](../report-html-pptx/references/completion-quality.md).

Review the sequence and all changed/dense/long-language/new-image pages with [visual review](../report-html-pptx/references/demo-esg-review.md) and [text flow](../report-html-pptx/references/text-flow-and-wrapping.md). Repair relationship/geometry before reducing type. Bind final checks through [project state](../report-html-pptx/system/project-state.md); do not build the whole QA graph before a first useful composition. Global fonts/CSS/canvas changes reopen affected coverage. Return reviewed actual HTML, asset/label IDs and scoped findings to export; HTML review does not certify final PPTX appearance.

## Implement varied explanation in actual body pages

Apply [expression and rhythm](../report-html-pptx/references/visual-expression-and-rhythm.md) before settling on each major body composition. Use appropriate photos/annotated images, illustrations, charts, process/relationship diagrams, timelines and substantive prose from the actual question. Follow useful image choices through to real assets; do not leave placeholders or recommendations only. Mark actual dominant form and narrative movement when practical. Review the body sequence separately for table dependence and repeated visual/narrative patterns, including tables disguised as cards. Keep precise comparison tables where they serve the reader and record why a repeated series is justified.

Report page titles and subheads use [nominal heading style](../report-html-pptx/references/report-heading-style.md). Apply writing's actual phrasing, preserve expected/proposed/completed status, and check headings at final size and after export. HTML report markup declares data-heading-style="nominal"; an explicit message/preserve exception applies only to its agreed scope.

## Apply the measured production contract

For varied intentional body/grid relationships, use data-demo-design-key and the scoped deviation target under [v4 execution](../report-html-pptx/references/workflow-execution.md). Do not waive other body samples or grids. Solid line-only SVG groups may opt into data-pptx-native="lines" for editable connectors; keep important labels as native sibling text. Complex figures retain the supported snapshot path and require actual export inspection.

Use the orchestrator's compact stage packet; do not infer canvas/density from PPTX. Follow [production contract](../report-html-pptx/references/production-contract.md) for token CSS, actual body/frame/grid markers, located intentional deviations and platform-font measurement. Record reference relationship and actual implementation in the existing map. A reference read or a declared CSS variable does not establish application. Run its design audit, then the existing editorial/visual checks; keep those results separate. Preserve user assets and accepted templates.