[Content Primitives] Define the cross-output component contract

[Vonng]

Context

OINK already has established patterns for output-format state, strict shortcode validation, Page Store feature flags, print rendering, and pure Markdown fallbacks. The new primitives need one written contract before their public authoring APIs are released.

Tracking issue: #3

Scope

Document and freeze the shared rules for all new content primitives:

• Output matrix for html, print, markdown, and rss, plus no-JavaScript behavior.
• Standard versus Markdown shortcode notation; nested collector versus inline-recursive implementation.
• Named versus positional arguments, including the rule that one call cannot mix them.
• Required parameters, strict boolean/integer handling, enum validation, unknown-parameter rejection, and errors containing .Position.
• Escaping rules for HTML and Markdown; author input must not be passed through safeHTML.
• Internal URL resolution, allowed external schemes, subpath-safe links, and external-link policy.
• Page Store feature flags, repeated rendering across summaries/output formats, and generated-ID collision handling.
• Semantic CSS tokens, dark mode, print, RTL, reduced motion, and forced-colors behavior.
• i18n ownership for visible strings and the alias/deprecation policy.
• Boundary between theme fixtures, regression-site documentation, browser tests, release, and hosted deployment.

Implementation notes

Use the existing implementations as precedents:

• layouts/_shortcodes/code-group.html
• layouts/all.md
• layouts/_partials/scripts.html
• layouts/_partials/code/markdown-escape.html
• layouts/_partials/code/register-id.html
• scripts/check-code-blocks.py

Deliverables

• Add docs/content-primitives.md containing the frozen contract and component output matrix.
• Record the initial public API for Badge, Kbd, Fields, FileTree, image zoom configuration, and Gallery.
• Record deferred parameters so later additions remain backwards compatible.

Acceptance criteria

• Every planned primitive has an explicit HTML/print/Markdown/RSS/no-JS representation.
• The document specifies exact allowed values and defaults, not examples only.
• Markdown output is required to remain free of component runtime HTML.
• The document identifies which components may load JavaScript and how absence from unrelated pages is verified.
• The document is linked from the implementation issues and updated when an intentional contract change is approved.

Out of scope

No component templates, styles, or runtimes are implemented in this issue.

[Vonng]

Implementation started on local branch codex/content-primitives-contract, based on f4bc981.

Current local slice:

• Added docs/content-primitives.md with the frozen authoring APIs, output matrix, validation/escaping/URL rules, runtime contract, deferred parameters, and separate delivery gates.
• Added scripts/check-content-primitives-contract.py and wired it into CI.
• Linked the implementation contracts from README.md.
• Clarified that Field descriptions retain source Markdown in Markdown output and use RenderString only for HTML/print/RSS.
• Kept standalone public Icon deferred and retained slash-separated nested shortcode names after checking Hugo's supported subdirectory lookup.

Local evidence:

• python3 scripts/check-content-primitives-contract.py
• python3 scripts/check-i18n.py
• python3 scripts/check-font-tokens.py
• Hugo Extended 0.164.0 example-site build with --panicOnWarning
• Existing enhanced code-block regression suite

All passed. This issue remains open until the implementation is committed and reviewed; this comment is local implementation evidence, not release or hosted-deployment evidence.