[Tracking] Everyday content primitives roadmap

[Vonng]

Purpose

Track the implementation of OINK's everyday content primitives: small, high-frequency building blocks for engineering documentation that remain semantic, responsive, accessible, and useful outside the normal HTML/JavaScript path.

The implementation is intentionally split into independent issues so that each issue can serve as its scope contract and implementation record.

Product decision and order

P0 — freeze the shared contract

• [Content Primitives] Define the cross-output component contract #4 — define validation, escaping, output notation, URL rules, Page Store/runtime rules, and the HTML/print/Markdown/RSS/no-JS matrix.

P1 — ship the high-value zero-JavaScript primitives

• [Content Primitives] Add Badge and Kbd #5 — Badge and Kbd.
• [Content Primitives] Add Fields and Field MVP #6 — reduced Fields/Field MVP.
• [Content Primitives] Add the core FileTree shortcode family #7 — core FileTree family after a Hugo compatibility spike.

P2 — build the shared media foundation, then Zoom

• [Media] Define shared image resolution and harden imgproc #8 — shared image resolution plus imgproc hardening.
• [Media] Add opt-in native Image Zoom #9 — opt-in native dialog enhancement.

P3 — add Gallery after the media contract is proven

• [Media] Add a content Gallery that reuses Image Zoom #10 — grid/caption layer that reuses the image resolver and Zoom runtime.

Consumer-site integration and regression record

• [Content Primitives] Integrate theme primitives into the regression site oink.pgsty.com#2 — bilingual component documentation, Markdown goldens, browser/axe coverage, module pinning, and hosted verification.

Dependency graph

contract (#4)
├── Badge/Kbd (#5)
├── Fields (#6)
├── FileTree (#7)
└── image foundation (#8)
    └── Image Zoom (#9)
        └── Gallery (#10)

Each completed vertical slice feeds the site integration issue.

Key scope decisions

• Badge, Kbd, reduced Fields, and core FileTree are the first implementation wave.
• Image behavior starts with a shared resolver and imgproc compatibility work; Zoom does not own a second resolution path.
• Image Zoom is opt-in and page-scoped, uses one native <dialog>, and has no non-HTML runtime.
• Gallery is later work and must reuse Zoom instead of creating another lightbox.
• A standalone public icon shortcode is deferred. Components may use a small private, allowlisted icon registry where it materially improves their own UI.
• Kbd uses a positional-only public API.
• Fields advanced metadata (kind, location, since, deprecated, link) is deferred until the reduced MVP is proven.
• FileTree does not read the filesystem, claim role="tree", or require JavaScript.
• No TypeScript compiler, API playground, arbitrary color/class API, remote build-time image fetch, pan/drag/editor behavior, or second lightbox enters this roadmap.

Shared definition of done

Every public primitive must have:

• strict required-parameter and enum validation with source position;
• safe escaping and centralized URL handling;
• stable HTML, print, Markdown, and RSS behavior;
• readable output when JavaScript is unavailable;
• responsive and dark-mode-safe styling;
• English documentation and matching Simplified Chinese .zh.md documentation;
• focused template/build tests plus the appropriate browser and accessibility coverage;
• examples for long content and relevant mobile/dark states;
• conditional runtime loading only when interaction is present and enabled.

Delivery gates

Do not collapse these into one “done” state:

1. theme source and focused tests;
2. local consumer-site rendering against an exact sibling checkout revision;
3. theme release;
4. consumer-site Hugo module pin and regression suite;
5. hosted deployment verification.

Implementation-record convention

• Keep each child issue's body aligned with the agreed scope and acceptance criteria.
• Record design deviations, compatibility findings, test commands/results, and release evidence as issue comments.
• Link implementation PRs and follow-up issues from the relevant child issue.
• Close a child only when its own acceptance criteria are satisfied; later release/deployment gates stay open in the site issue when applicable.

[Vonng]

Roadmap implementation checkpoint (2026-08-12)

All planned implementation slices in #4 through #10 now exist and pass their local theme and consumer-site validation gates on the current working branches.

Decisions carried into implementation

• Shipped: Badge, Kbd, Fields/Field, FileTree, a shared image resolver with hardened imgproc, opt-in native Image Zoom, and Gallery reusing the same resolver/dialog/runtime.
• Deferred deliberately: a public Icon shortcode, TypeScript compiler-driven type tables, automatic filesystem reads, advanced image pan/wheel zoom/editing, and a second Gallery lightbox/carousel.
• Preserved: semantic HTML, strict position-aware validation, no JavaScript for non-interactive primitives, Page Store-based on-demand runtime loading, and dedicated Markdown/Print/RSS fallbacks.

Implementation records

• Contract: [Content Primitives] Define the cross-output component contract #4 (comment)
• Badge/Kbd: [Content Primitives] Add Badge and Kbd #5 (comment)
• Fields: [Content Primitives] Add Fields and Field MVP #6 (comment)
• FileTree: [Content Primitives] Add the core FileTree shortcode family #7 (comment)
• Shared media / imgproc: [Media] Define shared image resolution and harden imgproc #8 (comment)
• Image Zoom: [Media] Add opt-in native Image Zoom #9 (comment)
• Gallery: [Media] Add a content Gallery that reuses Image Zoom #10 (comment)
• Consumer-site integration: [Content Primitives] Integrate theme primitives into the regression site oink.pgsty.com#2 (comment)

Final local verification

• Theme branch codex/content-primitives-contract, base f4bc9813885194d305a33f1f4841d10d04a61d6b: Hugo Extended 0.164.0 and compatibility-floor 0.160.1 builds/checker matrices pass.
• Consumer branch codex/content-primitives-site, base 132e7e02f9d4e9b124ba3d202f1b9e0d54b50ccd: bilingual build/static checks, 14 Markdown goldens, 9 Hugo-build tests, 7 component browser tests, 27 focused axe cases, 17 responsive/blog tests, and 17 code-block tests pass.

This is a local implementation checkpoint. Changes are not committed, pushed, merged, released, pinned, or hosted yet, so the roadmap and child issues remain open for normal review and delivery.