@appdirect/design-system

AppDirect Design System components. Thin wrappers around Mantine v9.

Install

npm install @appdirect/design-system

Peer dependencies (install at the versions declared by this package):

• react, react-dom
• @mantine/core, @mantine/dates, @mantine/hooks

What ships in the package

Bundlers (Rspack, webpack, Vite, Next) should resolve the package entry to .js. You do not need transpilePackages / SWC includes for this package’s TypeScript. Keep loading *.module.css from the package with your CSS-modules rule.

Keep DESIGN.md in sync

Do not hand-copy the design spec. Wire consumers to pull the published file on install:

{
  "scripts": {
    "postinstall": "ad-sync-design-md",
    "sync-design-docs": "ad-sync-design-md"
  }
}

• Default destination: docs/DESIGN.md
• Repo-root destination: DESIGN_MD_PATH=DESIGN.md or ad-sync-design-md --out DESIGN.md
• Authoring source of truth in this monorepo: apps/design-system/DESIGN.md

App usage

Load token CSS once near the app root (standalone prototypes often use this package’s CSS re-exports; the tokens package is the same files):

import '@appdirect/design-system/css/foundations.css';
import '@appdirect/design-system/css/mantine.css';
// or:
// import '@appdirect/ad-design-tokens/css/foundations.css';
// import '@appdirect/ad-design-tokens/css/mantine.css';

Import product UI from this package, not raw @mantine/core, when a DS wrapper exists:

import { Button, TextInput, Stack, Card, PageContentHeader } from '@appdirect/design-system';

export function Example() {
  return (
    <Stack gap="md">
      <PageContentHeader title="Invoices" description="Open billing period" />
      <Card padding="md">
        <TextInput label="Search" />
        <Button variant="primary">Save</Button>
      </Card>
    </Stack>
  );
}

Use AppDirect button variants (primary, secondary, default, outline, danger, link, secret), not Mantine filled / light / subtle. Prefer --ad-* tokens for colour; avoid palette props like color="blue".

Shared helpers:

import { /* sizes, etc. */ } from '@appdirect/design-system/config';
import type { DSButtonVariant } from '@appdirect/design-system/types';

Stories (tooling only)

Storybook stories ship as reference source under dist/stories/. They are not a runtime export of React components.

// Index of every story: title, component, description, story names, imports
import stories from '@appdirect/design-system/stories';
// or open files via the package export:
// @appdirect/design-system/stories/Buttons/Button.stories.tsx

Prototype agents (add-feature) read node_modules/@appdirect/design-system/dist/stories/ (and the stories export) to copy composition patterns. The build fails when a story imports a Mantine component the design system has not adopted.

Contracts and ds-audit

npx ds-audit
# or: ./node_modules/.bin/ds-audit

Contracts live at @appdirect/design-system/contracts (index) and @appdirect/design-system/contracts/<id>. Use them with @appdirect/ds-enforce ESLint rules in apps that adopt the system.

Provider note

MantineProvider / theme setup stays in the host app (for example src/providers/ in micro-ui / prototype apps). This package does not export a provider.