@useloops/design-system

The React + TypeScript design system for the Loops platform and marketing website. Built on MUI v9 + Emotion, documented in Storybook, and published as a tree-shakeable npm library.

Architecture decisions and their rationale live in docs/adr/README.md.

Commands

bun install          # install deps (use bun, never npm/npx)
bun run dev          # Storybook dev server on :6006 (primary dev loop)
bun run component    # scaffold a new component (hygen)
bun run icons        # regenerate icons from Figma (setup below)
bun test             # run unit tests
bun run tsc          # typecheck (tsc --noEmit)
bun run package      # build the npm library (Rollup, CJS + ESM + .d.ts)
bun run build        # build the static Storybook site

Synchronising icons with Figma

• Create a personal access token in Figma: Settings → Security → Personal access tokens
• Create an .env file at scripts/useloops-icon-generator/.env
• Install packages: cd scripts/useloops-icon-generator && bun install
• Run bun run icons from the root dir
• Check the Brand Core/Icons story in Storybook to verify the expected icons updated

Storybook

Run bun run dev (port 6006). We're on Storybook 10 (@storybook/react-vite).

Controls are defined explicitly per story — TypeScript docgen is disabled, so each story declares its own argTypes/args (no auto-inferred controls). See ADR-0001 for the rationale and how to re-enable inference.

Importing

Three import styles are supported (see ADR-0002 for the why):

// 1. Barrel — imports from the root
import { Button, Avatar, Text } from '@useloops/design-system';

// 2. System-level
import { Button, Avatar, Text } from '@useloops/design-system/WebCore';
import { Navigation, Header, KpiIndicator } from '@useloops/design-system/Platform';
import { Icon } from '@useloops/design-system/BrandCore';
import { PlanTierCard, TickGroup } from '@useloops/design-system/Marketing';
import { ThemeProvider, useTheme } from '@useloops/design-system/theme';
import { omitProps, pluralise, useBreakpoint } from '@useloops/design-system/utils';

// 3. Individual component — best for tree-shaking
import Button from '@useloops/design-system/WebCore/Button';
import Navigation from '@useloops/design-system/Platform/Navigation';
import Icon from '@useloops/design-system/BrandCore/Icon';

Type definitions ship with every import style:

import Button, { ButtonProps } from '@useloops/design-system/WebCore/Button';

Available systems

• BrandCore — brand-specific components (Icon)
• Marketing — marketing page components (PlanTierCard, TickGroup, PlanFeatureTable)
• Platform — platform-specific components (Navigation, Header, KpiIndicator, …)
• WebCore — core web components (Button, Avatar, TextField, Text, …)
• theme — theme configuration and provider
• utils — utility functions and hooks