README.md

Documentation index for developers

Last updated: 2026-02-06

Doc requirements

• Audience: Developers (intermediate)
• Scope: Overview and essential workflows for this area
• Non-scope: Deep API reference or internal design rationale
• Owner: Jamie Scott Craik (@jscraik)
• Review cadence: Monthly or each release (whichever is sooner)

Contents

• Doc requirements
• Directory structure
• Start here
• Documentation quality checks
• Architecture docs
• Audit reports
• Guides
• Design system governance
• Transcripts
• Root documentation
• Workflow docs

This index helps you find the right doc fast. Start here, then jump into the category you need.

Directory structure

apps/                # Navigation index (canonical apps under platforms/)
docs/
├── architecture/    # System design and architecture documents
├── audits/          # Design system audits and compliance reports
├── design-system/   # Design system governance and coverage artifacts
├── guides/          # How-to guides and quick starts
├── features/        # Feature design specs and parity notes
├── foundations/     # Source reference materials (PDFs, specs)
└── work/            # Work logs, audits, and validation notes

Start here

• New to the repo? Read the root README.md first.
• For canonical onboarding routes (15-minute success paths), use ONBOARDING_COMMAND_CENTER.md.
• Releasing? Use RELEASE_CHECKLIST.md.
• Looking for the CLI? See packages/cli/README.md.
• Need structure help? See repo-map.md (canonical paths live under platforms/).

Documentation quality checks

Run documentation checks from the repo root:

pnpm doc:lint

Requirements:

• Vale installed locally (for example, brew install vale).
• pnpm install completed so repo scripts are available.

Architecture docs

Technical architecture and design decisions.

• WIDGET_ARCHITECTURE.md - Widget system architecture
• repo-map.md - High-level repository map
• ui-structure-map.md - UI library layout and component foldering map
• APPS_SDK_GAP_ANALYSIS.md - Apps SDK integration analysis
• cross-platform-design.md - Cross-platform architecture notes (legacy context included)
• WIDGET_SYSTEM_ENHANCEMENTS.md - Widget infrastructure enhancements
• template-library.md - Template library layout and parity rules
• template-api.md - Template and block API (internal)
• DESIGN_SYSTEM_FLOW.md - Token → UI → apps flow diagram
• TOP_LEVEL_INDEX.md - Canonical vs auxiliary top-level folders

Audit reports

Design system compliance audits and color reference documentation.

• APPS_SDK_COMPLIANCE_AUDIT.md - Apps SDK compliance audit
• COLOR_AUDIT_COMPLETE.md - Complete color system audit
• COLOR_REFERENCE.md - Color palette reference
• DESIGN_AUDIT_REPORT.md - Overall design audit report
• TEXT_COLOR_AUDIT_SUMMARY.md - Text color usage audit

Guides

Step-by-step guides for common tasks.

• ONBOARDING_COMMAND_CENTER.md - Canonical onboarding entrypoint and task routes
• PAGES_QUICK_START.md - Quick start guide for creating pages
• DESIGN_GUIDELINES.md - UI design and accessibility guidelines
• UI_COMPONENT_TOOLING.md - UI component tooling and QA sequence
• CHATGPT_INTEGRATION.md - Connect an MCP server to ChatGPT
• CLOUDFLARE_DEPLOYMENT.md - Deploy widgets to Cloudflare Workers
• PRIVATE_GUIDANCE_PACKAGE.md - Adopt @brainwav/design-system-guidance in consumer projects
• repo-structure-migration.md - Path changes from the 2026 restructure
• RELEASE_CHECKLIST.md - Release checklist

Design system governance

• CHARTER.md - Design system charter and rules
• UPSTREAM_ALIGNMENT.md - Apps SDK UI alignment log
• CONTRACT.md - Index of governing artifacts
• COVERAGE_MATRIX.md - Generated component coverage map

Transcripts

• docs/transcripts/README.md - Cleaned + raw video transcripts

Root documentation

Key project documentation remains at the repository root:

• README.md - Project overview and getting started
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history
• SECURITY.md - Security policies
• ATTRIBUTIONS.md - Third-party attributions
• AGENTS.md - AI agent system instructions

Workflow docs

• BUILD_PIPELINE.md - Build pipeline architecture and usage
• VERSION_SYNC.md - Version synchronization across packages
• RFC_TEMPLATE.md - RFC workflow template for design-system changes
• QA_EVIDENCE_SCHEMA.md - QA evidence requirements and CI gate artifacts
• quality-debt-radar.md - Canonical debt categories, freshness semantics, and warn-first rollout policy
• quality-debt-radar-rollout-checklist.md - Rollout and verification checklist for debt-radar adoption
• GOVERNANCE_SECURITY_PRIVACY.md - Security and privacy rules for governance artifacts
• TOKEN_ADD_CHECKLIST.md - Add a token without breaking token sources