Skip to main content

ADR 001: Select Component Library

Date: 2025-08-18

Status: Accepted

Decision Makers: @jannis-jutso, @cathrinTruchan, @qhantom, @kaischwetz @cr0ssing

Context​

We evaluated preselected React component libraries to standardize the UI layer for CIVITAS/Core. The evaluation focused on 10 criteria: design philosophy, Figma UI kit availability, component variety (esp. data table), branding/multi-branding, client-side theming, accessibility, community/support, performance & bundle size, documentation, extensibility, and license.

Assumptions:

  • The Material UI (MUI) used in the Masterportal does not serve as a design reference for CIVITAS/Core.
  • The default shadcn design aligns with the CIVITAS/Core design vision.
  • CIVITAS/Core would like to migrate to Material 3 Expressive when stable component libraries are available (watching maturity).

Possible Extensions (independent of the base library):

  • Charts: Apache ECharts
  • Data tables: TanStack Table

Checked Architecture Principles​

  • Model-centric data flow: none — choice of component library does not affect data flow architecture directly.
  • Distributed architecture with unified user experience: full — single library promotes consistent UX across distributed apps.
  • Modular design: full — shadcn promotes composable, file-scoped components and tokens.
  • Integration capability through defined interfaces: full — React props/contracts and headless primitives (Radix UI) provide clear interfaces.
  • Open source as the default: full — shadcn, Radix UI, Tailwind, and candidate libs are OSS.
  • Cloud-native architecture: none — UI library selection is orthogonal to runtime/deployment.
  • Prefer standard solutions over custom development: full — adopt a widely-used OSS library rather than bespoke components.
  • Self-contained deployment: full — shadcn pattern (copy-in components) avoids runtime CDN/vendor lock, enabling isolated builds.
  • Technological consistency to ensure maintainability: full — one approved library reduces divergence and maintenance effort.
  • Multi-tenancy: none — handled at application/platform layer, not the UI component library.
  • Security by design: partial — lighter dependency graph reduces surface; however, app-layer security, authZ/authN remain out of scope.

Decision​

Adopt shadcn as the primary React component library for CIVITAS/Core.

Reasons:

  • Design philosophy & future-proofing: shadcn provides a lightweight, flexible foundation suitable for our own design system. In contrast, MUI’s upcoming transition to Material 3 Expressive implies a non-trivial migration path and uncertainty over the long-term lifespan of Material 2.
  • Theming & branding: shadcn (Tailwind CSS tokens + CSS variables) enables fine-grained, multi-brand theming without fighting a prescriptive design language.
  • Performance & bundle size: shadcn’s opt-in, copy-in model avoids importing large, pre-bundled suites; tree-shaking is more effective.
  • Accessibility: built on Radix UI primitives with strong a11y defaults while keeping control of markup for auditability.
  • Extensibility: composing primitives scales better for bespoke experiences than overriding opinionated widgets.

Consequences​

Positive:

  • Consistent UX with a flexible base that aligns to CIVITAS/Core’s design vision.
  • Reduced migration risk vs. waiting for stable Material 3 Expressive and deprecating Material 2.
  • Smaller baseline and clearer ownership of component code (copy-in model), improving debuggability and longevity.
  • Straightforward multi-brand and client-side theming via tokens and CSS variables.

Negative / Trade-offs:

  • More responsibility on our side to curate, document, and enforce patterns (design system governance required).
  • Fewer “batteries-included” complex widgets (e.g., advanced data grid, charts) — must integrate TanStack Table and ECharts (or equivalents).
  • Component updates are not automatic; copied components must be periodically synced with upstream patterns.

Operational Implications:

  • Establish a Design System repo (tokens, foundations, component recipes)
  • Storybook for documentation.
  • Optional: governance process for adding/altering components (PR templates, a11y checks, visual regression tests).
  • Optional: starter templates for app teams (Next.js + Tailwind + shadcn + Radix + TanStack Table + ECharts).

Alternatives​

  • Material UI (MUI) — Wide adoption, rich component set, and strong accessibility. But tightly bound to Material Design and risky due to upcoming Material 3 migration.
  • Mantine — Modern, many components, solid docs. Downsides: outdated Figma kit, smaller community, weaker a11y.
  • Kern UX — Excellent accessibility and design-token support, but opinionated government-style design and less flexible branding.

See also​