[Content Primitives] Integrate theme primitives into the regression site

[Vonng]

Goal

Use the OINK site as the bilingual documentation, integration, and regression surface for the theme's everyday content primitives.

Theme roadmap: pgsty/oink#3

This issue deliberately tracks the consumer-site layer. Theme implementation remains in pgsty/oink, and local rendering, theme release, module pinning, and hosted deployment are separate completion gates.

Theme dependencies

• Cross-output contract: [Content Primitives] Define the cross-output component contract oink#4
• Badge and Kbd: [Content Primitives] Add Badge and Kbd oink#5
• Fields and Field: [Content Primitives] Add Fields and Field MVP oink#6
• FileTree: [Content Primitives] Add the core FileTree shortcode family oink#7
• Shared image foundation / imgproc: [Media] Define shared image resolution and harden imgproc oink#8
• Image Zoom: [Media] Add opt-in native Image Zoom oink#9
• Gallery: [Media] Add a content Gallery that reuses Image Zoom oink#10

A component can land here incrementally after its theme issue is ready; this issue does not require one monolithic site PR.

Scope

Documentation and examples

• Extend the existing content/docs/content/components.md page; do not create a parallel component catalog.
• Submit the matching Simplified Chinese page at content/docs/content/components.zh.md in the same change.
• Document stable syntax, defaults, invalid-input behavior, output fallbacks, configuration, and non-goals.
• Add representative examples covering light/dark themes, desktop/mobile layouts, long values and filenames, and nested content.
• Clearly distinguish opt-in interactive features from zero-JavaScript primitives.

Markdown, print, RSS, and no-JS coverage

• Add the new examples to the generated Markdown fixture/golden surface.
• Verify that the documented plain-text notation matches the theme contract.
• Add focused build assertions for print and RSS where a golden alone is insufficient.
• Verify that unrelated pages do not load the image runtime and that all content remains readable without JavaScript.

Browser and accessibility regression coverage

Extend the existing browser suites, especially:

• tests/browser/content-components.spec.mjs
• tests/browser/accessibility.spec.mjs
• responsive coverage where needed

Cover:

• responsive layout and overflow behavior;
• keyboard operation and focus restoration for the zoom dialog;
• Escape, explicit close, and backdrop close;
• no nested interactive controls;
• axe checks in representative light/dark and desktop/mobile states;
• long text, deep FileTree nesting, and missing/invalid parameter build failures.

Theme checkout and release verification

• During development, use the sibling theme checkout through the ignored Hugo workspace mechanism (go.work / HUGO_MODULE_WORKSPACE).
• Record the exact theme revision used for local verification.
• After the theme release exists, update the site's Hugo module pin in a separate, reviewable change.
• Run the relevant focused tests first, then the full site suite.
• Treat hosted verification as a later, explicit gate after the site change is deployed.

Suggested implementation slices

• Contract documentation and test helpers.
• Badge/Kbd examples and regressions.
• Fields examples and regressions.
• FileTree examples and regressions.
• Shared image fixture and imgproc compatibility cases.
• Image Zoom examples, configuration, and interaction tests.
• Gallery examples and shared-runtime tests.
• Pin the released theme version and verify the hosted pages.

Acceptance criteria

• English and .zh.md documentation ship together for every exposed component.
• Examples render correctly in light/dark and desktop/mobile modes.
• Markdown goldens have intentional, reviewed changes.
• Print/RSS/no-JS representations are stable and readable.
• Interactive behavior passes keyboard, focus, and axe checks.
• Unrelated pages do not receive the media runtime.
• The exact local theme revision and the later released module version are recorded separately.
• Local regression success is not described as a theme release or hosted deployment.

Non-goals

• Implementing theme shortcodes, SCSS, or JavaScript in this repository.
• Duplicating the component catalog under a new information architecture.
• Blocking early documentation slices on Gallery.
• Treating a local Hugo build as release or production evidence.

[Vonng]

Local integration implementation record (2026-08-12)

The bilingual consumer-site integration and durable regression surface are complete in the local working trees.

Exact local revisions

• Theme: pgsty/oink, branch codex/content-primitives-contract, base commit f4bc9813885194d305a33f1f4841d10d04a61d6b, with the Content Primitives implementation still uncommitted in the working tree.
• Site: pgsty/oink.pgsty.com, branch codex/content-primitives-site, base commit 132e7e02f9d4e9b124ba3d202f1b9e0d54b50ccd, with this integration still uncommitted in the working tree.
• Local validation uses the ignored go.work / HUGO_MODULE_WORKSPACE mechanism to resolve the sibling theme checkout. go.mod intentionally remains pinned to released OINK v0.2.0 until a new theme release exists.

Documentation and fixtures

• Extended the existing EN/ZH component catalog rather than creating a parallel information architecture.
• Added stable, matching EN/ZH sections for Badge/Kbd, Fields, FileTree, shared images/Image Zoom, Gallery, and output/failure contracts.
• Documented strict argument types, defaults, invalid-input behavior, output fallbacks, opt-in Zoom configuration, exclusions, non-goals, and the deliberate deferral of a public Icon shortcode.
• Added a small local WebP fixture used by both languages.
• Added generated Markdown goldens for both component pages.

Durable regression coverage

• Added Hugo build assertions for semantic HTML plus Markdown, Print, and RSS output; invalid parameters must fail with their source position.
• Added seven Playwright component tests covering semantics, deep/long FileTree content, Gallery breakpoints, pointer and keyboard Zoom operation, Escape/close/backdrop behavior, focus restoration, linked-image exclusion, runtime omission on unrelated pages, no-JS behavior, and missing HTMLDialogElement.
• Extended axe coverage to the bilingual component pages across light/dark and 360/768/820/1024/1200/1440 px states, plus open Zoom dialogs.
• Made test-owned Hugo builds use --noBuildLock; tests use the local module workspace when present, so they do not contend with a developer's running Hugo server.

Verification results

Theme compatibility matrix:

• Hugo Extended 0.164.0: warning-free example build plus i18n (32 locales / 105 keys), typography, cross-output contract, enhanced code blocks, primitives, shared media, Image Zoom, Gallery, and git diff --check all pass.
• Hugo Extended 0.160.1 (compatibility floor): warning-free example build plus enhanced code blocks, primitives, shared media, Image Zoom, and Gallery all pass.

Consumer site:

• HUGO_MODULE_WORKSPACE=go.work npm run build -- --noBuildLock: pass; EN 275 pages and ZH 273 pages.
• npm run test:hugo-build: 9/9 pass.
• npm run test:md-output: 14/14 pass.
• Markdown style: 83 Chinese files checked; translation parity: 80/80 files and 732 headings.
• Rendered Markdown: 192 content pages / 19,923 text nodes; rendered links: 350 pages / 13,911 internal links / 2,465 fragments.
• npm run test:alt-site: pass; offline-search indexes contain 92 EN and 92 ZH entries.
• npm run test:favicons: 15/15 pass.
• npm run test:content-components: 7/7 pass.
• Focused npm run test:a11y: 27/27 pass.
• npm run test:responsive-shell: 17/17 pass.
• npm run test:code-blocks: 17/17 pass.
• Prettier and git diff --check: pass.

Remaining delivery gates

This record is local implementation evidence, not release or hosted-deployment evidence. The issue should remain open until:

1. the theme change is committed, reviewed, merged, and released;
2. the site updates go.mod to that released theme version in a separate reviewable change;
3. the site change is committed, reviewed, merged, and deployed; and
4. the hosted EN/ZH pages and asset/runtime loading are verified.

Until step 2, a plain build without HUGO_MODULE_WORKSPACE=go.work correctly resolves v0.2.0 and cannot render the new shortcodes.