Design decisions
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.
Related
- Design contracts — current required behavior
- Research — dated evidence that informs decisions
- Proposals — ideas that have not been accepted