Orientation
State chapter, scope, status, and source before detail.
04 · design system
Swiss Code
Make the shared visual, structural, interaction, and provenance rules explicit.
08shared principles
One structure
Chapter anatomy
Contract
Name inputs, transformations or interactions, outputs, and limitations.
Evidence
Keep provenance, uncertainty, applicability, and missingness visible.
Action
End with a test, decision, implementation step, or next reading.
Validation
Define how the method, decision, or interface can fail.
One layout
Design tokens
grid
- columns
- 12
- max_width_px
- 1240
- gutter_px
- 20
- content_split
- [3, 9]
- card_split
- [3, 5, 4]
spacing
- base_unit_px
- 8
- section_min_px
- 48
- section_max_px
- 96
typography
- family
- Helvetica Neue, Helvetica, Arial, sans-serif
- headline_style
- large, compact, left-aligned, negative tracking
- label_style
- uppercase, compact, letter-spaced
- body_measure_ch
- 76
palette
- paper
- #050505
- card
- #090909
- ink
- #f5f5f2
- soft
- #a7abb0
- line
- #343434
- accent
- #39bfff
breakpoints
- stacked_px
- 780
- compact_px
- 620
Design principles
Rules before components
Clarity before ornament
Every graphical element must carry structure, state, evidence, or action.
One grid, many depths
Overview, catalog, contract, and reading detail use the same twelve-column logic.
Visible provenance
Every generated chapter states the YAML contract and any linked long-form source.
Stable navigation
The three chapters and Swiss Code stay in the same order and position.
Explicit state
Active chapter, filters, uncertainty, applicability, and status cannot depend on color alone.
Reversible interaction
Drill-down, adaptation, and comparison preserve a path back to the prior state.
Responsive hierarchy
Mobile layouts stack the same semantic order rather than inventing a separate page.
YAML first
Routes, chapter order, tokens, structure, labels, and content bindings are edited in YAML and compiled.
YAML first
Content provenance
Canonical files
content/research-system.yamlcontent/books.yamlcontent/content.yamlcontent/structure.yaml
Generated outputs
web/public/research/research-system.cssweb/public/research/swiss-code/index.htmlweb/public/research/methods/index.htmlweb/public/research/methods/evidence-reading-workflow/index.htmlweb/public/research/methods/oracling/index.htmlweb/public/research/methods/oracling/reading-room/index.htmlweb/public/research/interfaces/index.html
Generated HTML and CSS are publication artifacts. Edit their YAML or linked source and recompile; do not author the generated files directly.
SC-EVIDENCE-001
Evidence and Citation Architecture
Keep discovery, private source material, reviewed evidence, versioned knowledge, and published prose distinct but traceable.
Open the operational method →Safari
Discover
Capture the canonical source page and its identity; a saved tab is not yet evidence.
Zotero
Preserve and annotate
Keep metadata, lawful attachments, annotations, locators, and private reading notes together.
calyr.aí catalog
Review and extract
Convert selected annotations into atomic claims with evidence level, applicability, limitations, and source location.
Git
Version
Store reviewed YAML records, schemas, and prose; exclude credentials and normally exclude copyrighted full documents.
calyr.aí
Publish and verify
Build text from reviewed claims and verify that every externally checkable assertion resolves to supporting evidence.
- A highlight is not automatically a reviewed claim.
- A paraphrase and a verbatim excerpt remain distinguishable.
- Every published claim retains portable source identity and an exact locator.
- AI may retrieve, compare, and draft; it may not invent evidence or silently upgrade interpretation into fact.
- Private attachments, credentials, and the Zotero database never enter the public repository.
Release contract
Validation gates
- YAML parses and cross-references resolve.
- All three chapter routes and Swiss Code are present in the shared navigation.
- Each page exposes its canonical YAML source.
- Desktop and compact layouts retain the same semantic order.
- Internal routes resolve without fallback.
- Production build completes before publication.