Build order
Repository와 Docs가 서로 drift하지 않도록 작업 순서를 고정합니다.
- Organize the GitHub repository first. Canonical implementation, taxonomy, guidance, and decision records must have clear owners.
- Build the Docs information architecture and page skeleton second. Navigation and page templates must be stable before content is poured into them.
- Connect canonical sources into those page skeletons third. A Docs page should present source-owned information rather than become a second source of truth.
철학부터 세우기
표현과 이름을 정하기 전에 trade-off를 통해 믿음, 원칙, 실행 규칙의 층위를 분리합니다.
- direct design-system collision;
- adjacent AI, developer-tool, enterprise-software, or design-tool collision;
- pronunciation and spelling stability in the languages the system expects to use;
- misleading dominant meanings or unwanted associations;
- whether the explanation is truly derived from the philosophy or retrofitted after the fact.
- Make complexity legible.
- Calibrate attention.
- Respect delegation, preserve control.
- Let evidence change the system.
Canonical source model
Implementation, catalog, guidance와 presentation의 책임을 나눕니다.
packages/wbds/ — implementation source
Owns reusable CSS/JS behavior and runtime-facing contracts. A Docs specimen must use these implementations directly where possible instead of visually re-creating them in page-local CSS.
catalog/ — machine-readable taxonomy and maturity
Owns structured inventory, maturity, state vocabularies, reference provenance, and documentation coverage metadata. Navigation/index generation should increasingly derive from catalog/content metadata instead of duplicated HTML lists.
docs/ — canonical human-readable guidance and decisions
Owns principles, foundations, usage rules, accessibility intent, build/governance rules, reference synthesis, and decision history.
apps/site/ — presentation layer
Owns Docs presentation, navigation, search, locale/theme controls, specimen framing, and page composition.
Review hosting fallback
Preview가 불가능할 때도 canonical source와 review artifact를 분리합니다.
- Build a static review snapshot from the same canonical Docs sources.
- Publish only the rendered review artifact to the dedicated gh-pages branch.
- Do not copy canonical authoring/source files into the review branch.
- Do not run the full GitHub Actions/CI verification suite for intermediate review.
- Keep main, package publication, tags, and Production untouched.
- Treat the GitHub Pages snapshot as a review surface only; the canonical repository branch remains the source of truth.
- Record the snapshot source commit and checkpoint in the artifact.