Baseleg Docs

UX system

The Baseleg UX system defines the approved building blocks for all UI work: design tokens, components, and composition patterns. Its purpose is to prevent styling drift, keep UI decisions explicit and reviewable, and give every contributor a shared visual language.

Principles

  • Token-first: every colour, spacing value, radius, and shadow must come from a design token, not a hardcoded value.
  • Component-first: before writing custom UI, check if a component in @baseleg/ui already covers the need.
  • Pattern-explicit: interaction patterns (empty states, loading, errors) are documented and consistent across the product.
  • Minimal surface: prefer a small set of well-understood components over a large library of one-offs.

Rules

  1. Use @baseleg/ui components first. Only build custom UI when no existing component fits.
  2. All colours, spacing, typography, radius, and shadow values must use tokens. Do not hardcode e.g. #1e40af or 16px directly.
  3. Every new reusable component must be added to @baseleg/ui and documented in this section.
  4. New component libraries (external) require an ADR before adoption.
  5. Every view must implement loading, empty, error, and success states — see the empty / loading / error pattern.

Structure

SectionPurpose
Design tokensColour palette, spacing scale, typography, radius, shadows
StandardsRules for using the UI system in product code
ComponentsIndividual component specifications and variants
PatternsComposition patterns: empty/loading/error, page shells
DiagramsArchitecture and domain diagrams

How to document a new component

When adding a reusable component to @baseleg/ui:

  1. Implement it in packages/ui/.
  2. Create a page in docs/ux/components/<name>.md.
  3. Include: purpose and usage guidance, props/variants API, do/don’t examples, accessibility notes, and all required states (loading, empty, error, success where applicable).

When to raise an ADR

Raise an ADR before:

  • Adding an external component library (e.g. Headless UI, Radix, shadcn/ui).
  • Introducing a new approach to icons, animations, or custom CSS outside the token system.
  • Making breaking changes to the token scale that would require updating many components.