58 lines
2.6 KiB
Markdown
58 lines
2.6 KiB
Markdown
# UI Design Code Bible
|
|
|
|
> **Documentation language:** English only. All maintained architecture documentation must be
|
|
> written in English.
|
|
>
|
|
> **Architectural decisions:** Every significant architectural decision **must** be recorded in
|
|
> [`decisions/10-decisions.md`](decisions/10-decisions.md) before or alongside the code change.
|
|
>
|
|
> **Single source of truth:** Architecture and technical design documentation belongs in `bible/`.
|
|
> Keep `README.md`, `CLAUDE.md`, and `AGENTS.md` minimal to avoid duplicate documentation.
|
|
|
|
This directory is the single source of truth for UI Design Code architecture, bundle contracts,
|
|
and reusable pattern conventions. It is structured so both humans and AI assistants can navigate
|
|
it quickly.
|
|
|
|
---
|
|
|
|
## Reading Map (Hierarchical)
|
|
|
|
### 1. Foundations (read first)
|
|
|
|
| File | What it covers |
|
|
|------|----------------|
|
|
| [architecture/system-overview.md](architecture/system-overview.md) | Product purpose, scope, repository composition |
|
|
| [architecture/submodule-integration-contract.md](architecture/submodule-integration-contract.md) | How host repositories consume this kit |
|
|
| [architecture/ui-pattern-catalog.md](architecture/ui-pattern-catalog.md) | Canonical pattern taxonomy and bundle status |
|
|
| [architecture/design-canon-map.md](architecture/design-canon-map.md) | Single-source map for canonical UI contracts and assets |
|
|
|
|
### 2. Runtime & Delivery
|
|
|
|
| File | What it covers |
|
|
|------|----------------|
|
|
| [architecture/demo-runtime-flows.md](architecture/demo-runtime-flows.md) | Demo app routes, render flow, failure behavior |
|
|
| [governance/documentation-policy.md](governance/documentation-policy.md) | Rules for maintaining architecture docs |
|
|
|
|
### 3. Governance (always current)
|
|
|
|
| File | What it covers |
|
|
|------|----------------|
|
|
| [decisions/10-decisions.md](decisions/10-decisions.md) | Architectural Decision Log (ADL) |
|
|
| [synthesis/source-repos.md](synthesis/source-repos.md) | Source repositories and Bible entrypoints |
|
|
| [synthesis/common-invariants.md](synthesis/common-invariants.md) | Shared rules extracted from source repos |
|
|
| [synthesis/normalization-matrix.md](synthesis/normalization-matrix.md) | Source → canonical convention mapping |
|
|
| [synthesis/ui-pattern-coverage-matrix.md](synthesis/ui-pattern-coverage-matrix.md) | UI pattern checklist and coverage status |
|
|
|
|
---
|
|
|
|
## Quick Orientation for AI Assistants
|
|
|
|
- Public reusable artifacts: `kit/`
|
|
- Bundle manifests: `exports/bundles/`
|
|
- Bundle index: `exports/index.yaml`
|
|
- Sync/apply tool: `tools/designsync/`
|
|
- Runnable reference app: `demo/`
|
|
|
|
Read order for most changes: system overview → submodule contract → affected bundle docs →
|
|
decision log.
|