@makitt.io/mds — MAKITT Design System

Radix-grade React UI library + DTCG design tokens. Slot-driven, token-themed components you compose into admin pages: primitives, compounds, overlays, data, patterns, and app shells, plus a multi-theme token system with automatic hover / pressed / disabled color states.

Install

npm install @makitt.io/mds react react-dom
# pnpm add @makitt.io/mds react react-dom

react and react-dom (v19) are peer dependencies.

See the CHANGELOG for per-release notes — including the visual/token recalibrations (control sizes, radius, type ramp) that can shift rendering between minor versions.

Quickstart

// 1. Import the design tokens (CSS variables) and the component styles — tokens first.
import '@makitt.io/mds/css';
import '@makitt.io/mds/styles.css';

import { MdsProvider, Button, Stack } from '@makitt.io/mds';

// 2. Wrap your app once in MdsProvider (theme init + persistence + system detection).
export default function App() {
  return (
    <MdsProvider defaultTheme="light">
      <Stack gap="3">
        <Button onClick={() => alert('hi')}>Save</Button>
        <Button variant="secondary">Cancel</Button>
      </Stack>
    </MdsProvider>
  );
}

Styles are required. Without the two CSS imports above, every component renders unstyled — the components reference var(--token) values that live in @makitt.io/mds/css.

Theming

Themes are a token swap on a data-theme attribute. Use MdsProvider to apply and persist the theme, and the useTheme hook to read/change it:

import { useTheme } from '@makitt.io/mds';

function ThemeToggle() {
  const { theme, resolvedTheme, setTheme } = useTheme();
  return (
    <Button
      onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
    >
      {theme}
    </Button>
  );
}

theme is 'light' | 'dark' | 'system'. MdsProvider persists the choice to localStorage and resolves 'system' from prefers-color-scheme.

Tailwind (optional)

If you use Tailwind, extend it with the preset so MDS tokens are available as Tailwind theme values:

// tailwind.config.ts
import mdsPreset from '@makitt.io/mds/tailwind-preset';

export default {
  presets: [mdsPreset],
  // ...
};

Package exports

The root entry re-exports everything; subpaths let you tree-shake by layer.

| Import | What | | -------------------------------- | ---------------------------------------------------- | | @makitt.io/mds | All components, hooks, providers | | @makitt.io/mds/primitives | Button, TextField, Box, Stack, Badge, ScrollArea, … | | @makitt.io/mds/compounds | Modal, Tabs, Accordion, Field, Section, Menu, … | | @makitt.io/mds/overlays | Toast, Dialog, Drawer, Popover, Tooltip, CommandMenu | | @makitt.io/mds/data | Table, DataGrid, List, Card, Calendar, Chart, … | | @makitt.io/mds/patterns | StatCard, EmptyState, ErrorState, Hero, … | | @makitt.io/mds/shells | AppShell, Sidebar, Topbar, Page, PageHeader | | @makitt.io/mds/foundations | MdsProvider, Portal, FocusScope, stores | | @makitt.io/mds/hooks | useTheme, useDisclosure, useDebouncedValue, … | | @makitt.io/mds/tokens | Token values as a typed JS/TS object | | @makitt.io/mds/css | Token CSS custom properties (required) | | @makitt.io/mds/styles.css | Component styles (required) | | @makitt.io/mds/scss | Token SCSS map (@use) | | @makitt.io/mds/tailwind-preset | Tailwind preset |

Conventions

• All visual values are tokens — components never hardcode px / hex; theme by swapping tokens, not by overriding component CSS.
• Components are forwardRef, merge className, and spread props.
• WCAG 2.1 AA is the accessibility baseline.

Internal development (this monorepo)

Contributing to MDS itself (adding/changing components) starts here:

• CLAUDE.md / AGENTS.md — agent / dev entry points
• docs/authoring.md — authoring SSOT + new-component checklist
• docs/catalog.md — component catalog + layer-decision rules
• docs/principles.md — principles, a11y, dependency rules

pnpm build       # tokens + rollup + types + catalog (+ verify gates)
pnpm test        # vitest
pnpm storybook   # component explorer on :6007

License

Proprietary — © MAKITT. Published to npm for use across MAKITT's own repositories.