Public Page Publication Protocol v2: Clean Public Surface

Phase 1 — Classify the Project and the Page Role

Determine and report: project name, project type, primary purpose, target audience, current maturity, intended public identity, whether a page is justified at all, the role of the page if it exists, and the primary public unit.

RoleWhen to uselanding pagePrimary public impression surface; drives the first-contact decisionproject overviewExplains what the project is and does in public termsorientation pageHelps a reader understand structure and navigatedocumentation entrypointRoutes a reader into a deeper docs surfaceshowcaseDemonstrates capability, results, or workportfolio surfaceOrganises multiple projects or pieces of workarchivePresents completed, historical, or inactive materialreading surfacePrimarily for reading (articles, essays, releases)distribution surfaceProvides access to downloadable or consumable artefactssupport surfaceSupports a repository or product (changelog, status, help)

UnitExamplesrepositoryThe repo itself is the primary public unitstatic pageA GitHub Pages or hosted HTML surfacedocumentation surfaceRendered documentationartifact collectionA set of downloadable or consumable artefactsrelease surfaceTagged releases or versioned assetsportfolio entryA single project in a portfolioinstitutional or informational pageAbout, contact, organisational identity

What is this project in public terms?

What should a visitor understand within the first seconds?

What should a visitor do next?

What is the page’s primary message and supporting message?

Is the page the primary public surface or a supporting surface?

What belongs in the page? What explicitly does not?

Phase 2 — Analyse the Source Surface

Inspect the workspace enough to make sound page-publication decisions. Determine and report: current semantic HTML structure, whether DOM order matches reading order, whether the page remains understandable before CSS is applied, whether HTML5 semantic elements are used appropriately, heading hierarchy coherence, layout dependencies (fixed widths, absolute positioning, z-index layering), overflow risks, JavaScript presence and justification, external CSS library or framework presence and justification, accessibility baseline signals, SEO metadata presence, current public-facing content, entry files, internal and external links, visual identity signals, assets, metadata, favicon and social preview signals, whether the page is isolated or entangled with non-page content, and whether a published page already exists.

Phase 3 — Run the Public-Surface Risk Audit

Check and report: sensitive or private content that should not appear on the page, internal-only notes or drafts, assets with unclear licence or attribution status, content that may not fit the intended public audience, links that expose unfinished or unintended surfaces, broken or stale internal links the page depends on, linked external surfaces that are unready or incoherent with the intended public surface, content that misrepresents project status or maturity, stale or aspirational claims presented as current public reality, structural mixing between page content and repository-only content, and technical deployment risks.

Publication-blocking issues (treat as blocking unless explicitly justified):

Uncontrolled horizontal page scroll

Broken responsive behaviour on mobile or desktop

Overlapping content at normal viewport sizes

Invalid or non-standard HTML used as structure

Essential content generated only through CSS pseudo-elements

Public-facing page without a coherent h1/title relationship

Public-facing page with materially missing metadata

JavaScript required for basic reading of static content

Visual structure that misrepresents the page’s actual public role

External-link stop rule: Do not publish a page that points users into broken, abandoned, contradictory, or premature external surfaces. Do not publish a page that creates a false sense of completeness through broken or misleading internal navigation.

Phase 4 — Design the Public Page Model

Before generating or editing files, decide and report: the semantic HTML5 skeleton of the page, logical DOM order, heading hierarchy, the responsive model, whether layout should use normal flow, flex, grid, or a combination, spacing scale, maximum content width strategy, decorative background strategy, whether JavaScript is needed at all, whether any external CSS library or framework is justified, the accessibility baseline, the SEO baseline, the role and content categories of the page, what the visitor should see first, the primary and supporting messages, the next action if any, whether the page should be single-surface or multi-page, where the page source should live, what deployment model applies, and what level of visual identity is justified.

LevelWhen to useMinimal identityPage is primarily functional, referential, internal-adjacent, temporary, or low-maintenanceCoherent identityPage should feel intentional and project-specific without requiring a full brand systemStrong branded identityPage is a flagship public surface, showcase, portfolio-facing surface, or primary discovery surface

Do not generate extra sections by default

Do not generate multi-page structure by default

Do not generate decorative assets by default

Do not generate interactivity by default

Do not let visual ambition outrun project identity

Prefer the smallest correct public surface

Phase 5 — Define the Minimum Page Package

Generate only the elements justified by the page model. Possible elements: page entry file, stylesheet, script, favicon, social/share preview image, title, description, canonical link, navigation, footer, public links, and minimal supporting assets.

Build semantic HTML before writing CSS

Keep DOM order aligned with reading order

Use HTML5 semantic elements where appropriate

Keep heading hierarchy coherent

Separate content structure from visual decoration

Use CSS backgrounds instead of empty background elements where possible

Use ::before and ::after only for non-essential decoration

Define a spacing scale before applying margins, padding, and gaps

Use flex for simple one-dimensional layouts; use grid only when two-dimensional layout is needed

Avoid fixed widths and heights unless explicitly justified

Prevent uncontrolled horizontal scroll

Add JavaScript only for justified behaviour

Add external CSS libraries or frameworks only if justified by the page model

If an element is skipped, state why

Phase 6 — Review Before Any Publication Action

Before committing, deploying, configuring a page source, or pushing, produce a concise review covering: semantic HTML structure and coherence, DOM order, whether CSS is only handling presentation (not compensating for wrong structure), responsive behaviour across relevant viewport sizes, absence of horizontal scroll, absence of overflow or container escape, decorative layer implementation, JavaScript justification and scoping, accessibility baseline, SEO metadata presence, what the page is for, what it includes and excludes, what public claims it makes, which files were added or modified, where the page source will live, which decisions are frozen, which still require confirmation, and which risks remain.

Phase 7 — Execute Publication

After confirmation, perform the minimum clean publication sequence required by the environment. Possible actions: isolate the page source if needed, create or update the page surface, execute the publication sequence required by the actual deployment model, stage and commit files intentionally, push the page source, configure the page source location, publish metadata and page identity elements, and verify the live public surface.

Source-based deployment

Artifact-based deployment

Platform-managed page hosting

Externally hosted static deployment

Phase 8 — Final Post-Publication Checklist

After publication, produce a checklist of only the relevant remaining manual tasks. Possible items: verify semantic structure in the rendered page, verify logical reading order, verify heading hierarchy, verify no unintended horizontal scroll, verify responsive behaviour by resizing the viewport, verify no content overlaps at normal viewport sizes, verify that media and wide elements stay inside their containers, verify that decorative layers do not interfere with reading, verify that JavaScript is not required for basic reading, verify keyboard navigation, verify visible focus states, verify basic contrast readability, verify alt text where images carry meaning, verify live and mobile rendering, verify title and description, verify share preview, verify favicon, verify links, and confirm that excluded material stayed excluded.