Reference
Principles

Engineering Principles

Six principle families guide the Ledger UI design system.

Trust

Templates must expose audit trails, provenance, and verifiable evidence affordances by default. Users should never have to search for proof — it should be visible at the appropriate level of detail.

  • Audit trails on every entity
  • Timestamps and attribution on records
  • Status indicators that are clear and unambiguous
  • Chain of custody visible in workflows

Sovereignty

All platform theming and policy changes are configuration, not code. No consuming application should need to fork or override the design system — everything is customizable through tokens and props.

  • Token overrides for visual identity
  • Template props for content structure
  • Theme modes (light, dark, compact) via configuration
  • Platform-agnostic components

Architecture

Modular packages, deployable independently, with clear dependency boundaries. Each package has a single responsibility and well-defined public API.

  • 8 composable packages with explicit dependencies
  • Build order enforced by Turbo
  • Bundle size budgets per package
  • ADRs document every architectural decision

Frontier

Offline-first UX states, low-bandwidth modes, accessibility and localization by default. The design system works in constrained environments, not just ideal ones.

  • 29 languages supported via @gtcx/i18n
  • RTL layout support built-in
  • WCAG AA accessibility baseline
  • Offline-aware UX patterns

Scale

Commodity-agnostic language. Extensible component taxonomy. The design system scales from a single application to dozens of consuming platforms.

  • Template API conventions (ADR-0003) enable consistent composition
  • Component bridge architecture supports extension
  • Token system enables per-platform customization

Craft

ADRs, tests, and docs required for every new component or template. Quality is a product surface, not an afterthought.

  • 301 tests across 8 packages
  • 70 Storybook stories with a11y checks
  • CI/CD with lint, typecheck, build, test, bundle size
  • Chromatic visual regression
  • This documentation site
ADR-0006 Demo Gallery FrameworkPRD