npm package: @shaggynator/brand-mf-ui
Description: Design system components for AI-assisted vibe coding
Latest version: 0.1.6

# @shaggynator/brand-mf-ui

A design system for AI-assisted "vibe coding" by Product Managers.

## Installation

```bash
npm install @shaggynator/brand-mf-ui
```

## Quick Start

### 1. Import Styles

In your root layout or global CSS file:

```tsx
// app/layout.tsx (Next.js)
import "@shaggynator/brand-mf-ui/styles.css";
```

Or in CSS (Tailwind v4 projects):

```css
/* app/globals.css */
@import "tailwindcss";
@import "@shaggynator/brand-mf-ui/styles.css";
```

### 2. Add Theme Classes

Add the required theme classes to your `<html>` or `<body>`:

```tsx
<html className="theme-light theme-desktop">
```

### 3. Use Components

```tsx
import { Button, Checkbox, RadioGroup, Radio } from "@shaggynator/brand-mf-ui";

export default function Page() {
  return (
    <div className="bg-canvas min-h-screen p-125">
      <div className="bg-surface rounded-lg p-100 flex flex-col gap-75">
        <Button variant="primary">Click me</Button>
        <Checkbox label="Accept terms" />
        <RadioGroup label="Choose option" defaultValue="a">
          <Radio value="a" label="Option A" />
          <Radio value="b" label="Option B" />
        </RadioGroup>
      </div>
    </div>
  );
}
```

---

## Exports

| Export Path                           | Description                                  |
| :------------------------------------ | :------------------------------------------- |
| `@shaggynator/brand-mf-ui`            | React components (Button, Checkbox, etc.)    |
| `@shaggynator/brand-mf-ui/styles.css` | Complete styles with Tailwind integration    |
| `@shaggynator/brand-mf-ui/tokens`     | Design tokens only (for custom integrations) |
| `@shaggynator/brand-mf-ui/icons`      | Icon components                              |

---

## Components

| Component    | Description                              |
| :----------- | :--------------------------------------- |
| `Button`     | Primary action element with variants     |
| `Checkbox`   | Boolean toggle with label                |
| `RadioGroup` | Container for mutually exclusive options |
| `Radio`      | Individual radio option                  |

---

## For Tailwind CSS v4 Projects

If your project uses Tailwind CSS v4, you can import just the design tokens and let Tailwind handle class generation:

```css
/* app/globals.css */
@import "tailwindcss";
@import "@shaggynator/brand-mf-ui/tokens";

/* Tell Tailwind to scan the package for class names */
@source "../node_modules/@shaggynator/brand-mf-ui/dist";
```

This ensures Tailwind includes all utility classes used by the components.

---

## AI Agent Setup

> **Important:** AI coding agents (Cursor, Windsurf, Cline, etc.) cannot read files inside `node_modules/` because it's excluded by `.gitignore`.

### Step 1: Copy Rules to Project Root

After installing, run this command from your project root:

```bash
cp -r node_modules/@shaggynator/brand-mf-ui/rules ./brand-mf-rules
```

### Step 2: Reference in Your Project

Add a reference to these rules in your project's `AGENTS.md`, `CLAUDE.md`, or equivalent:

```markdown
## Design System Rules

Follow the guidelines in:

- [brand-mf-rules/AI_GUIDELINES.md](./brand-mf-rules/AI_GUIDELINES.md)
- [brand-mf-rules/LAYOUT_RULES.md](./brand-mf-rules/LAYOUT_RULES.md)
```

### Automate with postinstall (Optional)

Add this to your `package.json` to auto-copy rules on install:

```json
{
  "scripts": {
    "postinstall": "cp -r node_modules/@shaggynator/brand-mf-ui/rules ./brand-mf-rules 2>/dev/null || true"
  }
}
```

### What's Included in Rules

| File               | Description                                      |
| :----------------- | :----------------------------------------------- |
| `AI_GUIDELINES.md` | Component patterns, design tokens, styling rules |
| `LAYOUT_RULES.md`  | Layout constraints and responsive patterns       |
| `manifest.json`    | Machine-readable rule definitions                |

---

## Design Tokens Reference

### Colors

```css
/* Backgrounds */
bg-canvas          /* Page background */
bg-surface         /* Card/container background */
bg-primary         /* Primary background */
bg-brand-primary   /* Brand color background */

/* Text */
text-fg-primary    /* Primary text */
text-fg-secondary  /* Secondary text */
text-fg-tertiary   /* Muted text */
text-fg-on-brand   /* Text on brand backgrounds */

/* Borders */
border-border-subtle  /* Light borders */
border-border-strong  /* Emphasis borders */
```

### Spacing

Use numeric spacing tokens: `gap-50`, `p-75`, `mb-100`, `px-125`

| Token | Value | Use              |
| :---- | :---- | :--------------- |
| `50`  | 8px   | Small spacing    |
| `75`  | 12px  | Default gaps     |
| `100` | 16px  | Standard padding |
| `125` | 20px  | Medium spacing   |
| `150` | 24px  | Large spacing    |
| `200` | 32px  | Section spacing  |

### Border Radius

```css
rounded-xs    /* 4px */
rounded-sm    /* 6px */
rounded-md    /* 8px - default for cards */
rounded-lg    /* 10px */
rounded-xl    /* 12px */
rounded-pill  /* 1000px - fully rounded */
```

---

## Troubleshooting

### CSS Not Loading

Ensure you've added the theme classes:

```html
<html class="theme-light theme-desktop"></html>
```

### Tailwind Classes Not Working

Add `@source` directive to tell Tailwind to scan the package:

```css
@source "../node_modules/@shaggynator/brand-mf-ui/dist";
```

### TypeScript Errors

Ensure your `tsconfig.json` includes:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}
```

---

## License

MIT