@mindviz/ui

Shared component library for the MindViz app suite. Built with React, TypeScript, and Tailwind CSS v4.

Install (local)

In any app in this monorepo, add to package.json:

"dependencies": {
  "@mindviz/ui": "file:../mindviz-ui"
}

Then npm install.

Setup

1. Import design tokens

In your app's globals.css (or equivalent), import the tokens before your Tailwind directives:

@import "@mindviz/ui/tokens.css";
@import "tailwindcss";

2. Configure Tailwind to scan library components

In your app's CSS (Tailwind v4) or tailwind.config.js (v3), add the library source to the content paths so Tailwind can detect the class names used in the components:

Tailwind v4 (globals.css):

@source "../../mindviz-ui/src/**/*.tsx";

Tailwind v3 (tailwind.config.js):

content: [
  // ...existing paths
  '../../mindviz-ui/src/**/*.{ts,tsx}',
],

3. (Optional) Map semantic tokens in Tailwind

The components use CSS variables (var(--accent), var(--surface), etc.) directly, so they work without further Tailwind config. If you want to use the token names as Tailwind utilities (e.g. bg-accent), extend your theme:

/* Tailwind v4 — globals.css */
@theme inline {
  --color-background:    var(--background);
  --color-foreground:    var(--foreground);
  --color-surface:       var(--surface);
  --color-border:        var(--border);
  --color-accent:        var(--accent);
  --color-muted:         var(--muted);
  --color-danger:        var(--danger);
  --color-warning:       var(--warning);
  --color-success:       var(--success);
}

Components

Primitives

| Component | Description | |-----------|-------------| | Button | Variants: primary secondary outline ghost danger. Sizes: sm md lg touch. Supports loading and icon props. | | Input | Labelled text input with error state | | Textarea | Labelled textarea with error state | | Select | Labelled select dropdown with error state | | Checkbox | Inline checkbox with label | | PasswordInput | Password field with show/hide toggle | | Label | Standalone accessible label with optional required indicator | | Switch | Toggle switch with label and description | | RadioGroup | Radio button group with direction, description, and disabled options | | Spinner | Loading spinner | | Avatar | User avatar with initials fallback | | Progress | Linear progress bar with variants: accent success warning danger muted |

Layout

| Component | Description | |-----------|-------------| | Card | Surface card with configurable padding (none sm md lg) | | Badge | Pill badge. Variants: default accent success warning danger muted | | Separator | Horizontal/vertical divider with optional label | | SectionHeader | Section title with icon, description, action button, and status badge | | Collapsible | Expand/collapse section with trigger and content | | EmptyState | Centered placeholder for empty views | | Skeleton | Loading skeleton (base, card, list item, text block variants) |

Overlays

| Component | Description | |-----------|-------------| | Modal | Accessible dialog with backdrop, Escape-to-close, footer, and animation options | | ConfirmDialog | Confirmation dialog with customizable actions | | AuthModal | Login / Register / Forgot password modal with OAuth support | | Tooltip | Hover-triggered tooltip with arrow, configurable position and delay | | Popover | Click-triggered popover with portal rendering and outside-click dismiss | | MobileDrawer | Slide-in panel from left/right/bottom with backdrop overlay |

Navigation

| Component | Description | |-----------|-------------| | Sidebar | Collapsible sidebar with logo, nav items, badges, user footer, and sign out | | Dropdown | Dropdown menu with icon, label, and divider items | | Tabs | Pill-style tab bar with icon, badge count, and status indicators |

Feedback

| Component | Description | |-----------|-------------| | Alert | Alert banner. Variants: info success warning danger | | ToastProvider + useToast | Toast notification system with multiple variants and positions |

Content

| Component | Description | |-----------|-------------| | ColorPicker | Preset color swatches + custom color input | | ThemeToggle | Light / Dark / System theme switcher dropdown |

Error Handling

| Component | Description | |-----------|-------------| | ErrorBoundary | React error boundary with inline and full-page modes, copy error + retry |

Legal

| Component | Description | |-----------|-------------| | CookieConsent | GDPR cookie consent banner with granular consent options |

All components accept a className prop for overrides.

Utilities

import { cn } from '@mindviz/ui';
// cn(...) → clsx + tailwind-merge helper

Development

npm run dev    # watch mode
npm run build  # production build