Skip to content

Design decisions

Accepted decisions that explain why OINK’s current contracts and implementation have their present shape.
Accepted rationale

A decision explains why OINK selected one compatible design instead of another. The five contracts define the required current behavior. The implementation and its checkers define the executable facts.

OINK previously kept reviews, PRDs, and execution notes in a local plan/ directory, which made useful reasoning hard to find and allowed abandoned designs to appear authoritative. Accepted rationale now lives here, beside the contracts it supports, in the same bilingual, versioned site.

Decision map

Decision What it settles
Warnings and safe fallbacks Why ordinary preview survives invalid input while publication remains strict
Configuration model Where configuration belongs, how pages override it, and why OINK has no parallel configuration namespace
Markdown-first authoring Why native Markdown is preferred and Docs, Blog, Book, and Landing extend shared systems
Generated configuration schema Why the editor schemas are a generated projection, and how the drift gate keeps a third configuration authority from appearing
Optional CLI and result contract Independent Go executable, versioned diagnostics, coverage, and explicit write boundaries for the local CLI candidate
Visual presets Paper default, Slate compatibility, opt-in Appearance menu, independent mode and font boundaries
Expo albums Resource bundles, optional metadata, shared appearance, and album viewing
Blog gallery Article covers, shared Expo geometry, independent preferences, and readable captions
Table reading Explicit .expand, independent .wide, and a direct corner action with native table restoration
Translation comparison One switch, real same-origin translations, a lazy two-pane reader, and heading-based sync

| Component refinement | Shared styling, divided cards, compact steps and command strips | | Unified diagram reading | Shared Mermaid and local PlantUML viewing, source export and demand loading | | Local search refinement | Mixed queries, real section anchors, partial matches and section scope |

Record format

An accepted decision records its context, choice, consequences, and evidence that the choice remains current. It does not repeat a parameter reference or tutorial. Each decision links to its contract and verification checks, and its English and Simplified Chinese pages change together.

When a decision changes, update the implementation, checker, affected contract, and decision record in one delivery. Preserve the previous decision in Git history and the release changelog rather than leaving two active answers in the navigation tree.