check

HTML quality gate

build.Run calls Analyze on the final serialization buffer before writing index.html or replacing output/. Errors preserve the previous output; warnings ship with actionable diagnostics. build and every serve rebuild share this gate.

Parsing: x/net/html. CSS selectors: Cascadia. Raw attributes: parse/v2/html. All run locally in the Go binary. No browser, Node, Java or HTTP validator service. The earlier config/template gate shares diagnostics and overrides; its warnings join this final report. The link gate adds links.* policy groups spanning config, template source and final output; fragment discovery extends them in the final DOM gate.

Architecture

• document.go: one final DOM, source tokens/byte locations, selectors and shared facts.
• catalog.go: the rule catalog with every rule's summary and help.
• validate.go: overrides, deterministic diagnostics and failure status.
• The catalog also registers build/bundle/hint/compaction/release notices; an AST regression test catches uncatalogued emitted IDs. Lighthouse owns a dynamic lighthouse.<audit-id> namespace, described by the lighthouse.* family entry.
• rules_html.go: syntax/repair detection, content models, IDs, references and JSON.
• rules_jsonld.go: block ownership and cached JSON-goLD expansion of exact script text.
• rules_commerce.go, commerce_jsonld.go: optional offer/checkout discovery, concrete Stripe secret shapes and focused semantic agreement on the same expanded JSON-LD. internal/commercecheck checks the optional public config contract before rendering.
• rules_seo.go, rules_social.go, rules_discovery.go: metadata, preview identity, snippet controls, readable structure and fragment discovery; shared static target index.
• sharing.go, rules_sharing.go, rules_share_media.go, rules_discord.go, rules_farcaster.go: declared platform contracts, strict JSON, initial metadata and bounded emitted-media inspection.
• accessibility.go: cached ID/label/composite facts, native disabled/focus helpers.
• rules_accessibility.go, rules_relationships.go, rules_focus.go, rules_aria.go: names, typed relationships, focus candidates and focused widget state checks.
• rules_interaction.go: form intent/numbers, native disclosures and autoplay requests.
• rules_performance.go: independent checks.
• rules_fonts.go: cached final CSS/font/preload analysis; exact emitted sidecars and already-read asset metadata supplied through Options. Scope.
• Matching _test.go files: small fixtures, individual rules, boundaries and fuzz seeds.
• internal/compile/validation_test.go: publication safety and actionable asset remedies.

Each rule is Rule{RuleInfo{ID, Summary, Help}, Check func(*Document) []Diagnostic}. Register it in DefaultRules (catalog.go) with its one-line Summary and a 2 to 5 sentence Help (trigger, why it matters, how to resolve); lfm rules <id> prints both and a test rejects missing or malformed help. Adding a rule does not change the build pipeline. Findings carry severity, stable rule ID, file, UTF-8 byte offset/column, line, element, explanation and fix. No source/data-URL payloads are dumped into diagnostics.

doc, err := validate.Parse([]byte(`<img src="hero.webp">`), validate.Options{})
if err != nil { t.Fatal(err) }
// Select a single rule; fragments do not need metadata for unrelated rules.
for _, rule := range validate.DefaultRules() {
    if rule.ID == "a11y.images" {
        report := validate.Run(doc, []validate.Rule{rule}, nil)
        // Assert report.Diagnostics, severity, location and edge cases.
    }
}
nodes, err := doc.Query(`main > section:nth-child(2) img:not([alt])`)

Default rules

Size thresholds use decimal bytes conservatively, following the current Googlebot limit. The warning leaves headroom; this is a compiler policy, not a ranking guarantee. CSS/JS/media/DOM budgets are advisory authoring defaults, not standards limits.

The report ranks data-URL occurrences by their total contribution, counts repeated embeds, and associates compiler-produced URLs with every known source asset. Automatic packing externalizes eligible resources before this final gate. Remaining size warnings/errors identify pins/pre-authored embeds and suggest source/override fixes. Unknown/pre-authored data URLs still have MIME, bytes and a final-document location. Compression does not change the HTML size gate.

Generator-default audit

Implements the deterministic subset of UI/UX generator defaults. style.go builds one small cascade from every final stylesheet (inline and emitted sidecars): Cascadia matching, specificity/source order, !important, inline styles, inheritance of typographic properties and simple var() lookups. It resolves the desktop/base context and ignores print, reduced-motion, dark-scheme and max-width-only rules. Colors are compared in OKLab. No layout, rendering or browser is involved.

• Strong signals are recognizable stock signatures and warn individually with the exact element or stylesheet location, why it reads as generated and the smallest alternative.
• Weak signals (single orb or glass layer, centered hero, pills everywhere, roster fonts, plain equal cards, grey body text on a dark solid backdrop…) only count in design.defaults.
• Deliberate use: data-design-reason="why this subject needs it" on an element or ancestor exempts that subtree; the combination finding reports how many signals were justified. Whole rules follow build.validation.rules like every other ID.
• Limits: class/selector heuristics cannot judge taste, layout geometry, scripted styles, canvas output or whether a pattern suits the subject. Review with the guide's swap and deletion tests; the audit removes the mechanical part of that review.

SEO/GEO audit coverage

The SEO/GEO guide defines the authoring contract; Content/copy owns wording. Normal builds enforce the reliable local subset on final bytes without rewriting content or adding knobs.

Known-private URL rejection covers literal local/private IPs and reserved local/test hostnames; it is not a DNS or reachability test. Initial text checks exclude scripts, styles, templates, JS-disabled fallbacks, hidden/ARIA-hidden content, canvas/SVG/media and form-value text. Closed details contribute their summary; open details contribute their content; unopened dialogs are excluded. Ordinary static CSS is not interpreted. Heading/accessibility names may use image alt or ARIA labels without treating those labels as an explanatory body. Fragment warnings describe explicit HTML blockers; CSS can override hidden states.

Contracts: Open Graph fields/arrays, robots/snippet controls, native fragment reveal.

UI/UX audit coverage

The UI/UX guide owns interaction/accessibility requirements. Every normal build checks the reliable HTML subset below, without changing authored behavior, adding a browser dependency or expanding CLI/config syntax.

Hard findings identify broken native structure/associations. Warnings identify supported static evidence or a behavior to verify; delegated JS, custom pause controls and CSS visibility cannot be inferred from markup alone. Findings include fixes and final-file locations; relationship/focus conflicts add the other element's location. Naming also checks closed native dialogs/disclosures; explicitly hidden/ARIA-hidden controls are excluded. Focus-candidate checks account for initial native inactive/disabled state. Inert templates are excluded. No handler execution, CSS layout or resource fetching occurs in normal validation.

Contracts: ARIA 1.2, accessible names, native forms, native focus, keyboard patterns.

Sharing/distribution audit coverage

The sharing guide owns platform design. Normal builds validate declared integrations only; they do not require a social SDK, account or extra metadata for platforms a product does not use.

Already-read sidecars are supplied in Options.Assets; no file/network reads or pixel decoding occur in validation. Byte limits apply to exact emitted JSON/media; image dimensions use bounded headers. Unknown remote resources are not reported as verified. Asset packing resolves known local media fields in inline platform JSON to public sidecars, preserving navigation/state and unknown fields. Ambiguous JSON is never repaired before validation; linked JSON contents stay authored. Both Discord JSON MIME aliases are recognized; use application/json for inline Go-template interpolation so raw script strings receive JSON escaping. The vendor MIME can otherwise leave & literally inside JSON URLs; known config URL mismatches get a specific repair hint. Existing severity overrides apply.

Contracts checked 2026-10-16: Discord link-preview payloads, component fields, Farcaster embeds, Snapchat stickers. X's observed compatibility boundaries and examples remain in the sharing guide.

Commerce audit coverage

Commerce coverage follows Commerce. Config-stage commerce.config, commerce.price and commerce.fields are registered alongside final rules in lfm rules; the same overrides apply before rendering. The optional data.commerce.offers convention keeps unknown fields, quote/variable prices, custom domains and handwritten layouts available. Compiler-consumed operational fields do not produce unused-value noise. No Stripe requests or Caddy file generation occur during a build. Published price/billing/tax basis, live provider state, client capabilities and deployment/fulfilment remain acceptance checks.

Overrides and testing

Everything runs automatically. Optional config under build.validation.rules maps rule IDs to "off", "warn" or "error"; unknown IDs/levels fail configuration. An override changes all findings from that rule. Required config/template execution checks accept only error; advisory template checks can also be tuned. Omitting it keeps default levels. Use lfm rules for the catalog and lfm.json syntax; lfm compile always reports diagnostics.

Lifecycle notices obey the same controls. "release.browser": "off" suppresses that setup advisory; setting it to error rejects a release before output replacement. "lighthouse.*": "off" controls all installed-version audit findings; an exact lighthouse.<audit-id> override takes precedence. The audit still runs and reports scores/manual checks. Unknown fixed IDs and invalid levels remain config errors.

{"build":{"validation":{"rules":{"a11y.images":"error","perf.budgets":"off"}}}}

go test ./internal/check -run TestSyntax
go test ./internal/compile -run TestValidationGateAndExactBytes
go test ./internal/check -fuzz FuzzAnalyze -fuzztime 10s
go test ./internal/check -run '^$' -bench Analyze -benchmem

Scope and source evidence

x/net/html intentionally repairs malformed markup. We additionally compare its parsed/serialized structure with original token events, allowing legal optional end tags and implied document/table containers. Raw attribute checks use a lexer because x/net drops duplicate attributes. A rendered-template check prevents the compiler's first parse from hiding authoring errors before the final gate.

Compile findings name index.html; lfm check uses the target URL path or file name. Supplementary findings name the virtual rendered-template.html: lines belong to expanded template output, not original partial/template line numbers. Analysis never mutates the serialization buffer.

This is a focused, extensible static validator, not complete WHATWG conformance certification or an accessibility audit. The repair detector relies on x/net's tree builder; foreign text is delegated to it. Content models cover the listed restricted structures; arbitrary attributes, every HTML context, CSS layout, computed accessible names, browser API behavior, network resources and live Core Web Vitals require additional checks. Inert template content is excluded from active metadata/ID/reference/name checks. No network request is made.

design.ground reports errors for warm-light backgrounds on any element, paper/noise/ruled textures on grounds or full-cover overlays, and torn, zigzag or perforated gradient edges. Warm background-colour findings exclude tiny elements (area below 256 px², or a lone known dimension at most 4 px), hidden, clipped and entirely off-screen elements; page grounds and full-cover wrappers remain protected from size and position exclusions. Unknown sizes are not assumed small. It uses the default light CSS cascade and has no data-design-reason exemption. See page checks.