Design System Monorepo

This repository is a Melos-managed Flutter monorepo for a scalable design system and component library.

Architecture

• packages/ds_tokens: semantic design tokens implemented as ThemeExtensions.
• packages/ds_foundation: reusable UI primitives built on top of tokens.
• packages/ds_components: product-ready components built on top of foundation and tokens.
• apps/catalog: a Storybook-style catalog package for documenting and validating components.
• Root app shell: the existing Flutter host in the repository root runs apps/catalog immediately on supported Flutter targets.

Component Coverage

The component layer currently includes:

• Actions: buttons
• Inputs: text fields
• Feedback: badges and banners
• Surfaces: cards and chips
• Navigation/content rows: list tiles
• Overlays: dialogs

The catalog app includes dedicated pages for buttons, inputs, surfaces, feedback, dialogs, list items, and typography so the library shows a broader set of realistic app primitives.

Dependency Rules

• ds_tokens must not depend on any local package.
• ds_foundation may depend only on ds_tokens.
• ds_components may depend only on ds_foundation and ds_tokens.
• Apps may depend on any package, but packages must never depend on apps.
• Keep public APIs small. Prefer defaults, variant enums, and theme-driven styling over deeply nested configuration.

One-Time Setup

dart pub global activate melos
flutter pub get
melos bootstrap
melos run run:catalog
melos run test
melos run test:goldens

If you use FVM, prefer:

fvm flutter pub get
melos bootstrap
melos run run:catalog

Common Workflows

flutter pub get
melos run analyze
melos run format
melos run test
melos run test:goldens
melos run run:catalog

Important: this workspace root is a Flutter package, so use flutter pub ... at the repo root, not dart pub ....

Adding A New Component

1. Create the component in packages/ds_components/lib/src/<component>/.
2. Check whether new semantic tokens are needed. If so, add them in ds_tokens first.
3. Keep the public API variant-based and theme-driven with sensible defaults.
4. Ensure the component works with the shared theme and reads as part of the same visual system.
5. Add semantics, keyboard focus behavior, and text-scale resilience as part of the initial implementation.
6. Add or extend golden tests in packages/ds_components/test/goldens/.
7. Add a catalog page or expand an existing page in apps/catalog/lib/pages/.
8. Run melos run analyze, melos run test, and melos run test:goldens before publishing changes.