sn-md-to-html-report

Report HTML

Create the report text as a single-file HTML that has editorial judgment, web aesthetics, evidentiary order, and belongs only to this theme.

Core principles:Preserve factual assertions, restructure the reading and visual experience, and let the design grow out of the report's domain and content task. The theme's own world—its materials, tools, objects, and vocabulary—is the source of unique design choices.

Design judgment principles

The first screen is the thesis: On the first screen, first find the thing or mechanism in the report's domain that is most recognizable and best able to carry the theme's character, and present it in the form best suited to it: a title, image, animation, live demonstration, or an interactive moment. This choice must involve clear judgment; do not default to "big number + small label + supporting statistic + gradient emphasis," and use it only when it is truly the most natural and powerful entry point for the theme.
The typographic system carries the page's character: Heading fonts and body fonts must be intentionally paired; do not fall back on common font combinations that can be applied to any project. At the same time, establish a clear type scale, and consciously set font weight, width, and spacing. Let typography itself become a memorable part of the design, rather than merely a neutral container responsible for conveying content.
Structure is information: Structural devices such as numbering, kickers, dividers, and labels should convey real information about the content, not decorate it. Many generic designs use numbered markers (01/02/03), but this applies only when the content itself is a sequence—for example, a real process or a textual timeline in which the order carries information the reader needs. Before using numbered markers, think about whether they are actually meaningful.
Use motion consciously: First determine whether motion can serve the theme, reading, or information comprehension, then decide where to use it: page load sequence, scroll-triggered reveals, hover microinteractions, or ambient atmosphere. One well-choreographed key animation is often more powerful than scattered effects; the choice of motion must be subordinate to the overall aesthetic direction. Some themes are better handled with restraint; extra animation can weaken professionalism and make the page look like AI-generated template work.
Complexity matches vision: The more elaborate the visual direction, the more the execution needs sufficient layering, detail, and completeness; the more minimal the visual direction, the more precise spacing, type scale, alignment, and micro-details must be. Elegance is not about less, nor about more, but about executing the chosen direction well.
Treat copy seriously: Titles, leads, labels, buttons, and captions must all be treated as part of the design. The source report's content may be rewritten, compressed, merged, and organized in expression, but facts, wording, or strength of conclusions must not be invented. Copy, like visuals, can feel templated.

How to use design knowledge

Hierarchy: First decide what the reader looks at first, second, and third, then allocate scale, weight, whitespace, and position.
Contrast: create differences through font temperament, font size, light and dark, density, motion and stillness, and spatial relationships; do not rely only on color for emphasis.
Alignment and grid: body text, charts, cards, annotations, and navigation all land within the same set of grids and width tiers, avoiding right edges and left baselines drifting at will.
Proximity and grouping: evidence stays close to judgment, annotations stay close to their objects, related items are grouped, and unrelated items are pulled apart.
Repetition and variation: repetition establishes order, variation expresses chapter differences; the whole page cannot have a different system for each chapter, nor can every chapter be completely identical in form.
Figure-ground relationship: texture, background, atmosphere, and motion effects always recede behind the content and must not steal readability from body text and evidence.
Rhythm: long reports need weight, density, transitions, and pauses; it is not about stacking all modules with equal weight.

Hard rules

Markdown is source material, not page structure; do not copy it paragraph by paragraph, and do not cram all content into cards.
Write plan.mdfirst, then write HTML; do not touch HTML without a complete plan.
The page is by default a single-file HTML: semantic HTML + inline CSS; unless the user requests it or the project already has a resource system, do not split files and do not reference a CDN.
Domain metaphors may be used to organize visuals and structure, but the numbers, sources, cases, judgments, and conclusion strength in the page must come from the original report.
Do not invent logos, clients, testimonials, rankings, map locations, chart data, confidence levels, or seemingly plausible generalizations that the original text cannot support.
Charts, processes, timelines, map-style groupings, and the like must be self-contained and hand-written.

Workflow

Read content and task: read through the source report and confirm the topic, domain, audience, purpose, core judgments, evidence, limitations, repeated content, tables, diagrams, and appendices.
First pass: brainstorm a short design plan: first diverge into 2-3 design directions that fit the content based on the brief, report domain, content task, evidence structure, and audience, without touching specific HTML. Express each direction with a compact token system: Color as 4-6 named hex values with their semantic uses explained; Type defines display, body, and utility / mono if needed; Layout uses a one-sentence concept and an ASCII wireframe; Signature defines the only design element on this page that will be remembered.
Review and revise the short design plan: check each direction against the brief and report content to see whether it truly has a content source. If any part looks like a generic default answer for similar pages rather than a choice made for the current report, that part must be revised, and note what was changed and why. After confirming relative uniqueness, choose 1 direction to move into the full plan.
Second pass: full page plan: based on the revised short design plan, expand the information structure, first-screen strategy, page topology, navigation, chapter layouts, transition rhythm, and evidence attachment methods; use hierarchy, contrast, alignment, proximity, grouping, and repetition / variation to organize information.
Do content design chapter by chapter: for each chapter, write clearly 内容形状 -> 章节版面 -> 呈现形式 -> 排版处理. The granularity should reach the paragraph or judgment level, not be let go for the whole chapter; long discussions also need lead-ins, pull quotes, side notes, or judgment blocks.
Define the design contract and checklist: before writing HTML, put the tokens, font roles, width tiers, chapter layout mapping, motion strategy, responsive degradation, fact boundaries, generic-template self-check, and inspection angles into plan.mdThe checklist is a contract before starting work, not a remedy afterward.
Write HTML: only implement plan.md, and do not start a separate visual or structural system at the HTML stage. First build the full-page skeleton, then fill in content and charts; all color, font, and key layout choices must derive from the short design plan.
Review by inspection angle: check item by item for factual fidelity, thematic fit, aesthetic consistency, typographic hierarchy, layout grid, content shaping, restrained motion, accessibility, responsiveness, and shareability; fix anything that does not pass.

plan.md must include

Audience / purpose: who reads it, and what they should do after reading.
Short design plan: brainstorm 2-3 directions based on the brief and content signals; each direction includes Color, Type, Layout, and Signature.
Relative distinctiveness review: which parts look like default answers, what was changed, and why; after confirmation, choose 1 direction.
First-screen strategy: what thematic-domain representative object opens the piece, what it leads the reader into, and how it forms focus and figure-ground relationships.
Information structure and layout strategy: topology, skeleton, navigation, chapter layouts, transition rhythm, width tiers, and mobile degradation.
Chapter-by-chapter content design table: each chapter's content shape, chapter layout, presentation form, typographic treatment, and evidence attachment method.
Design contract: tokens, font roles, grid / width tiers, navigation type, chapter layout mapping, motion strategy, key contrast, and generic-template self-check.
checklist: confirm the design contract is complete before writing HTML; sign off item by item according to the inspection angles before delivery.

Reference files

Before brainstorming the short design plan, read references/01-aesthetic-direction.md。
Before finalizing layout and chapter-by-chapter content design, read references/02-layout-and-content-design.md。
Before writing HTML, read references/03-design-contract.md and complete the checklist.
Before delivery, read references/04-review-angles.md and review by angle.

HTML requirements

Use CSS tokens to manage color, fonts, spacing, borders, width tiers, and motion parameters.
Desktop must genuinely use horizontal space; mobile must have no page-level horizontal scrolling, while long tables and code blocks may scroll locally.
If navigation exists, it must be usable: anchors can jump, the current chapter is perceptible, it is keyboard accessible, and it can degrade on small screens.
Charts and diagrams inherit the page tokens and do not start a separate set of colors and font sizes; color must not be the only encoding.
Headings, lead-ins, labels, annotations, and chart copy must be edited, and must not output template-speak.