HTML Layout Systems Field Guide

Frameworks should be mined for the problems they solve, not the appearance they popularize.

Observation Docusaurus separates standalone pages from documentation routes; Fumadocs templates separate landing and docs route groups; Starlight makes hero, sidebar, and table-of-contents regions conditional on route data. These implementations preserve one product language without forcing one page skeleton. [S22][S23][S25][S27]

Inference The correct unit of variation is the route or surface, not necessarily the entire site. A site can use marketing persuasion, tutorial progression, API reference, changelog chronology, and operational status layouts while retaining shared tokens and recognizable navigation.

Fact Nielsen Norman Group’s guidance emphasizes that the visible opening matters because users continue only when the initial content appears promising; homepage guidance also prioritizes clarity and direction toward user goals. [S35][S36]

Observation Cruip’s public landing-page source directly composes Hero, Workflows, Features, Testimonials, and CTA. AstroWind exposes an even larger inventory including features, steps, blog posts, FAQs, statistics, and CTA. These are intentionally opinionated persuasion funnels. [S14][S16]

Recommendation An opinionated funnel is valid when the content can substantiate it. It becomes harmful when placeholder sections, generic logo walls, invented statistics, or irrelevant FAQs are added because the template contains them.

Observation Brittany Chiang’s route composes Hero, About, Jobs, Featured, Projects, and Contact, creating an identity-led professional narrative. The Multiverse starter instead renders a data-driven gallery immediately, making the work itself the dominant object. [S18][S20]

Fact Mintlify explicitly distinguishes tutorial, how-to, reference, and explanation content and provides different templates for each. [S33][S34]

Observation Starlight’s page implementation conditionally composes the hero, sidebar, content panel, and table of contents from route data. Its mobile table of contents is a distinct component rather than a scaled-down desktop region. [S23][S25][S26]

Recommendation Keep the documentation shell predictable, but let the content contract control the body topology. A quickstart, conceptual article, API reference, and architecture decision should not be forced into the same article template.

Fact Tailwind Plus markets substantially different template classes—including SaaS marketing, agency, personal, information product, API reference, and changelog templates—within one implementation ecosystem. [S06][S07][S08]

Fact HTML5 UP’s free templates include modular one-page storytelling and editorial article-index structures; Start Bootstrap provides regularly updated Bootstrap themes; Cruip offers free landing and dashboard starters across modern stacks. [S09][S10][S11][S12]

Fact Apple recommends layouts that adapt to context while remaining recognizably consistent. Material defines adaptive design as changing an interface for context. Fluent uses layout to create relationships and guide decisions. Spectrum foregrounds readability, input diversity, and inclusive design. [S01][S02][S03][S04][S05][S39]

Recommendation Standardize the semantic knowledge layer above the implementation framework: tokens, anatomy, behavior, content, permissions, evidence, analytics, responsive contracts, and release policy.

Fact The source files directly show the route compositions and conditional shell behavior summarized above. [S14][S16][S18][S20][S22][S25][S30][S32]

Fact Fumadocs describes content-source adapters and separates core logic from UI. Scalar’s typed configuration projects OpenAPI source into layout, navigation, models, search, examples, localization, and interaction. [S28][S30][S32]

Fact Research examining hundreds of large- and small-screen visualization pairs identified dozens of responsive strategies and emphasized the trade-off between density and preservation of the intended message. [S38]

Fact Material’s adaptive guidance treats context changes as potential structural changes, while Apple emphasizes graceful adaptation with recognizable consistency. [S01][S39]

1. State the communication outcome. Convert, inform, teach, establish credibility, compare, decide, reference, or operate.
2. Identify the user posture. Discover, evaluate, verify, learn, locate, execute, operate, decide, or experience.
3. Select the dominant object. Claim, product, person, project, task, concept, process, API, data, event, resource, or decision.
4. Define the proof burden. Demonstration, artifact, source citation, quantified result, code, credential, comparison, or live state.
5. Choose the site family and route shell. Marketing, portfolio, documentation, reference, editorial, analytical, or operational.
6. Choose topology and authoring mode. Linear, hierarchical, hub-and-spoke, faceted, chronological, matrix, spatial, or task flow; composition, content tree, data, schema, or hybrid.
7. Write the opening contract. State what must be understood, proven, and available before continuation.
8. Map responsive transformations. Preserve the decision, task, evidence, and orientation—not the desktop geometry.
9. Select design lineage and expression. Typography, containment, media, motion, color, and component choices now have a structural rationale.
10. Validate task fit and evidence integrity. Novelty is optional. Structural justification is mandatory.

type HtmlLayoutGenome = {
  communication: {
    purpose: "discover" | "evaluate" | "verify" | "learn" |
      "locate" | "execute" | "operate" | "decide" | "experience";
    audience: string[];
    dominantObject: "claim" | "product" | "person" | "project" |
      "task" | "concept" | "api" | "data" | "decision";
    requiredProof: string[];
  };

  family: {
    siteLanguage: string;
    surface: "marketing" | "portfolio" | "documentation" |
      "reference" | "editorial" | "analytical" | "operational";
    routePattern: string;
    shell: string;
  };

  generation: {
    authoringMode: "composition-driven" | "content-tree-driven" |
      "data-driven" | "schema-driven" | "hybrid";
    sourceOfTruth: string;
    contentSchema?: string;
  };

  structure: {
    archetype: string;
    topology: "linear" | "hierarchical" | "hub-and-spoke" |
      "faceted" | "chronological" | "matrix" | "spatial" | "task-flow";
    openingContract: {
      visitorQuestion: string;
      primaryObject: string;
      proofMode: string;
      primaryRoute: string;
      continuationCue: string;
    };
    sectionSequence: string[];
    evidenceGates: string[];
  };

  runtime: {
    enhancement: "none" | "minimal" | "moderate" | "application";
    performanceBudget: string;
    motionPurpose: string;
    embeddedMode: boolean;
    cssLayerContract?: string[];
  };

  responsive: {
    preserve: string[];
    regions: Array<{
      desktop: string;
      strategy: "reflow" | "replace" | "move" |
        "progressively-disclose" | "remove-with-justification";
      narrow: string;
    }>;
  };

  outputs: {
    human: string[];
    machine: Array<"json" | "markdown" | "llms.txt" |
      "openapi" | "schema-org" | "rss" | "mcp">;
  };

  validation: {
    taskFit: string[];
    structuralJustification: string[];
    repetitionRisks: string[];
    accessibility: string[];
    performance: string[];
    provenance: string[];
  };
};

Observation Fumadocs exposes a machine-readable llms.txt surface, and Scalar’s configuration includes MCP integration alongside human reference configuration. [S29][S32]

Recommendation HTML should be one projection of a canonical knowledge model. Generate machine surfaces from the same source when future search, agents, APIs, or updates benefit.

1. Preserve canonical source IDs. Add new sources rather than silently replacing evidence unless a source is permanently unavailable.
2. Record reviewed dates and revisions. For repositories, add commit SHAs when a future claim depends on exact source behavior.
3. Revalidate current framework capabilities. Layout APIs, route systems, accessibility behavior, and machine-output features can change.
4. Separate new observation from new recommendation. A popular implementation does not automatically become a normative rule.
5. Add layout records, not screenshots alone. Capture user posture, dominant object, proof model, topology, authoring mode, responsive transformation, and failure risks.
6. Retest the artifact. Validate links, internal anchors, semantic structure, keyboard navigation, contrast, zoom, print, forced-colors, and narrow layouts.