npm package: @ofi-summer-ai/mark-ui
Description: Mark UI component library — React + Tailwind CSS 4 + shadcn/ui
Latest version: 0.1.1

# @ofi-summer-ai/mark-ui

[![npm version](https://img.shields.io/npm/v/@ofi-summer-ai/mark-ui)](https://www.npmjs.com/package/@ofi-summer-ai/mark-ui)
[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/OFI-Summer-AI/mark-ui/blob/main/LICENSE)
[![react](https://img.shields.io/badge/react-19-blue)](https://react.dev)
[![tailwind](https://img.shields.io/badge/tailwindcss-4-blue)](https://tailwindcss.com)

> **Full documentation:** [github.com/OFI-Summer-AI/mark-ui](https://github.com/OFI-Summer-AI/mark-ui/tree/main/docs)

A production-ready React component library built on [shadcn/ui](https://ui.shadcn.com/) and [Radix UI](https://www.radix-ui.com/), styled with Tailwind CSS 4. Ships 47 accessible UI primitives plus a suite of higher-level custom components for marketing and dashboard applications.

---

## Installation

```bash
# pnpm (recommended)
pnpm add @ofi-summer-ai/mark-ui

# npm
npm install @ofi-summer-ai/mark-ui

# yarn
yarn add @ofi-summer-ai/mark-ui
```

### Required CSS import

The library ships a compiled stylesheet that must be imported once in your application entry point:

```ts
// main.tsx or App.tsx
import '@ofi-summer-ai/mark-ui/style.css'
```

Without this import, components will render without styles.

---

## Quick Start

```tsx
import '@ofi-summer-ai/mark-ui/style.css'

import { Button } from '@ofi-summer-ai/mark-ui'
import { Card, CardHeader, CardTitle, CardContent } from '@ofi-summer-ai/mark-ui'
import { Badge } from '@ofi-summer-ai/mark-ui'
import KPICard from '@ofi-summer-ai/mark-ui/components'

export default function Dashboard() {
  return (
    <div className="p-6 space-y-4">
      <div className="flex items-center gap-2">
        <h1 className="text-2xl font-bold">Dashboard</h1>
        <Badge variant="secondary">Beta</Badge>
      </div>

      <div className="grid grid-cols-3 gap-4">
        <KPICard
          title="Total Reach"
          value="124,500"
          trend={12.4}
          trendLabel="vs last month"
        />
        <KPICard
          title="Engagement Rate"
          value="4.8%"
          trend={-1.2}
        />
        <KPICard
          title="Posts Published"
          value={38}
          trend={5.0}
        />
      </div>

      <Card>
        <CardHeader>
          <CardTitle>Actions</CardTitle>
        </CardHeader>
        <CardContent className="flex gap-2">
          <Button>Create Post</Button>
          <Button variant="outline">View Analytics</Button>
          <Button variant="ghost">Settings</Button>
        </CardContent>
      </Card>
    </div>
  )
}
```

---

## Component Overview

### Primitives (shadcn/ui)

| Component | Description |
|-----------|-------------|
| `Accordion` | Vertically stacked expandable sections |
| `Alert` | Contextual feedback banners (info, warning, error) |
| `AlertDialog` | Modal dialog requiring user confirmation before an action |
| `Avatar` | Circular user/brand image with initials fallback |
| `Badge` | Small status or label indicator |
| `Breadcrumb` | Hierarchical page location trail |
| `Button` | Versatile action trigger with multiple variants and sizes |
| `Calendar` | Date picker calendar grid (uses react-day-picker) |
| `Card` | Contained surface for grouping related content |
| `Carousel` | Horizontally scrollable slide container (Embla) |
| `Chart` | Recharts-based chart container with built-in theming |
| `Checkbox` | Binary toggle input with indeterminate state support |
| `Collapsible` | Single section expand/collapse without animation overhead |
| `Command` | Accessible command palette / combobox (cmdk) |
| `Dialog` | Modal overlay dialog |
| `Drawer` | Slide-in panel from screen edge (vaul) |
| `DropdownMenu` | Floating action menu anchored to a trigger |
| `Empty` | Placeholder for empty states |
| `Field` | Form field wrapper combining Label + Input + error message |
| `Form` | React Hook Form integration with validation messages |
| `HoverCard` | Rich preview card revealed on hover |
| `Input` | Single-line text input |
| `InputGroup` | Input with leading/trailing add-ons |
| `InputOtp` | One-time password segmented input (input-otp) |
| `Label` | Accessible form label |
| `NavigationMenu` | Top-level site navigation with dropdown support |
| `Pagination` | Page number navigation control |
| `Popover` | Non-modal floating content panel |
| `Portal` | Renders children into a portal outside the DOM tree |
| `Progress` | Linear progress bar |
| `ScrollArea` | Custom-styled scrollable region |
| `Select` | Single-value dropdown selector |
| `Separator` | Horizontal or vertical divider line |
| `Sheet` | Slide-in side panel (Dialog variant) |
| `Sidebar` | Collapsible application sidebar with nested nav support |
| `Skeleton` | Animated loading placeholder shape |
| `Slider` | Range or value slider input |
| `Sonner` | Toast notification system (Sonner/`Toaster`) |
| `Switch` | Binary toggle switch |
| `Table` | Accessible HTML table with styled rows and cells |
| `Tabs` | Tabbed content panels |
| `Textarea` | Multi-line text input |
| `Toggle` | Single pressable button that retains active state |
| `ToggleGroup` | Group of mutually-exclusive or multi-select toggles |
| `Tooltip` | Short text hint revealed on hover/focus |
| `CountrySelector` | Flag + country name selector with search |

### Custom Components

| Component | Description |
|-----------|-------------|
| `BrandLogo` | Displays a brand image with automatic initials fallback |
| `ErrorState` | Full-area error display with optional retry button |
| `LoadingState` | Centered spinning loader for async content |
| `ShineBorderButton` | Button with animated gradient border (requires framer-motion) |
| `TooltipHover` | Enriched tooltip with title, body text, and optional action |
| `KPICard` | Metric card with value, trend indicator, and icon slot |
| `FacebookIcon` | Facebook SVG icon |
| `InstagramIcon` | Instagram SVG icon |
| `LinkedInIcon` | LinkedIn SVG icon |
| `TikTokIcon` | TikTok SVG icon |
| `DynamicTable` | Full-featured data table with sorting, filtering, and pagination |
| `AvatarDropdown` | User avatar that opens a profile/sign-out dropdown |
| `BreadcrumbRouter` | Auto-generated breadcrumbs from the current react-router path |
| `AppHeaderActions` | Header action bar rendering router links, links, buttons, or custom nodes |
| `EditImageModal` | AI image editing modal with upload, prompt, and preview |
| `ChatInput` | Chat message input with send button and keyboard shortcut |
| `ChatMessage` | Single rendered chat message bubble (user or assistant) |
| `ChatMessagesList` | Scrollable list of `ChatMessage` components |
| `TypingIndicator` | Animated three-dot typing indicator |

---

## Theming

The library uses CSS custom properties for all design tokens. Override them in your global stylesheet after importing `@ofi-summer-ai/mark-ui/style.css`:

```css
/* your-app/globals.css */
:root {
  --primary: #6366f1;           /* Brand primary color */
  --on-primary: #ffffff;        /* Text on primary color */
  --primary-container: #e0e7ff; /* Primary container background */

  --secondary: #0f172a;
  --background: #ffffff;
  --surface: #f8fafc;
  --radius: 0.5rem;             /* Border radius base */
}
```

### Key CSS Variables

| Variable | Default (light) | Purpose |
|----------|----------------|---------|
| `--primary` | `#D946EF` | Brand accent color |
| `--secondary` | `#0b3948` | Secondary brand color |
| `--background` | `#fcfcfb` | Page background |
| `--surface` | `#fcfcfb` | Card/panel surface |
| `--on-surface` | `#333231` | Text on surface |
| `--outline` | `#a39a8e` | Border color |
| `--outline-variant` | `#ebe6e0` | Subtle border color |
| `--muted` | `#f4f4f5` | Muted background |
| `--muted-foreground` | `#71717a` | Muted text |
| `--radius` | `0.625rem` | Base border radius |
| `--error` | `#b3261e` | Error/destructive color |
| `--success` | `#4ac087` | Success color |

Chart-specific variables `--chart-1` through `--chart-10` control the default palette used by the `Chart` primitive.

---

## Dark Mode

The library uses **class-based** dark mode. Add the `.dark` class to your `<html>` element (or any ancestor) to activate the dark theme:

```tsx
// Toggle dark mode
document.documentElement.classList.toggle('dark')
```

```html
<!-- Static dark mode -->
<html class="dark">
```

Dark mode variables are defined under both `.dark` and `[data-theme="dark"]` selectors, so both conventions are supported:

```html
<html data-theme="dark">
```

---

## Peer Dependencies

| Package | Version | Required |
|---------|---------|----------|
| `react` | `>=18.0.0` | Required |
| `react-dom` | `>=18.0.0` | Required |
| `react-router-dom` | any | Optional — needed for `BreadcrumbRouter` and the `"router"` action type in `AppHeaderActions` |
| `framer-motion` | any | Optional — needed for `ShineBorderButton` |

All other dependencies (Radix UI, Recharts, Sonner, etc.) are bundled with the library.

---

## Exports

The library offers three entry points:

```ts
// Full library — all primitives + custom components
import { Button, KPICard, DynamicTable } from '@ofi-summer-ai/mark-ui'

// Only shadcn/ui primitives
import { Button, Card } from '@ofi-summer-ai/mark-ui/primitives'

// Only custom components
import KPICard from '@ofi-summer-ai/mark-ui/components'

// Required stylesheet
import '@ofi-summer-ai/mark-ui/style.css'
```

---

## Documentation

Full per-component documentation lives on GitHub:

- [Getting Started](https://github.com/OFI-Summer-AI/mark-ui/blob/main/docs/README.md)
- [Primitives](https://github.com/OFI-Summer-AI/mark-ui/tree/main/docs/primitives)
- [Custom Components](https://github.com/OFI-Summer-AI/mark-ui/tree/main/docs/components)

> Browse all docs at [github.com/OFI-Summer-AI/mark-ui/tree/main/docs](https://github.com/OFI-Summer-AI/mark-ui/tree/main/docs)