npm package: @nenad-spaceinch/component-library
Description: Stand-alone React component library with design system tokens and Figma Code Connect integration
Author: Nenad SpaceInch
Latest version: 0.3.0

# MA Component Library

Stand-alone React component library with design system tokens and Figma Code Connect integration.

## 🎯 Overview

This library provides a collection of fully self-contained React components built with:
- **Design Tokens**: CSS variable-based theming system
- **Figma Code Connect**: Direct integration with Figma design files
- **TypeScript**: Full type safety and IntelliSense support
- **Stand-alone Components**: No external CSS framework dependencies (Tailwind, etc.)

## 📦 Installation

```bash
npm install @nenad-spaceinch/component-library
# or
yarn add @nenad-spaceinch/component-library
# or
pnpm add @nenad-spaceinch/component-library
```

### Peer Dependencies

```json
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}
```

## 🚀 Quick Start

### 1. Import Styles

Import the design system styles in your app entry point:

```tsx
// Import design tokens and theme
import '@nenad-spaceinch/component-library/styles/primitives.css';
import '@nenad-spaceinch/component-library/styles/semantics.css';
import '@nenad-spaceinch/component-library/styles/theme';
import '@nenad-spaceinch/component-library/styles/styles.css';
```

### 2. Use Components

```tsx
import { Button, Input, Dropdown, DropdownItem } from '@nenad-spaceinch/component-library';

function App() {
  return (
    <div>
      <Button primary onClick={() => console.log('Clicked!')}>
        Click Me
      </Button>
      
      <Input placeholder="Enter text..." />
      
      <Dropdown width="320px">
        <DropdownItem>Option 1</DropdownItem>
        <DropdownItem>Option 2</DropdownItem>
      </Dropdown>
    </div>
  );
}
```

## 📚 Components

### Base Components
- **Button** - Flexible button with variants (primary, secondary, tertiary), modes (main, inverse, destructive), and sizes
- **Input** - Text input with icon support
- **Search** - Search input with dropdown integration
- **Checkbox** - Checkbox with label and indeterminate state
- **RadioButton** - Radio button with label
- **Toggle** - Toggle switch with label
- **Dropdown** - Dropdown menu with items, headers, footers, and search
- **Table helpers** - Compose tables with `TableHeaderCell`, `TableCell`, `CellItemPlaceholder`, and `renderTableSchema`
- **Tag** - Labeled tag with color variants
- **StatusTag** - Status indicator tag
- **StatusDot** - Status indicator dot
- **Avatar** - User avatar with image, initials, and status dot
- **Divider** - Horizontal or vertical divider
- **ProgressBar** - Progress indicator
- **Breadcrumbs** - Navigation breadcrumbs
- **Tab** & **TabBar** - Tabbed navigation
- **FilterSelector** - Multi-select filter with tags
- **Counter** - Numeric counter badge
- **Logo** - Brand logo component

### Section Components
- **PageHeader** - Complete page header with breadcrumbs, title, and actions
- **Sidebar** - Navigation sidebar

## 🎨 Design System

### Tokens

The library uses a three-tier token system:

1. **Primitives** (`primitives.css`) - Raw values (scales, base colors)
2. **Semantics** (`semantics.css`) - Semantic tokens (spacing, sizing, radius)
3. **Theme** (`theme.ts` + `themes/*.css`) - Color tokens for active theme

### Token Prefixes
- `---` (triple-dash): Layout & sizing tokens (spacing, size, radius, weight)
- `--` (double-dash): Color tokens (background, text, border, button)

### Typography Classes
- Headings: `heading-[size]-[weight]` (e.g., `heading-xl-bold`)
- Labels: `label-[size]` (e.g., `label-m`)
- Body: `body-[size]-[weight]` (e.g., `body-m-regular`)
- Paragraphs: `paragraph-[size]-[weight]` (e.g., `paragraph-m-regular`)

### Elevation Classes
- Shadow effects: `elevation-[size]` (e.g., `elevation-l`)

## 🎭 Themes

Switch themes by changing the import in `styles/theme.ts`:

Available themes:
- `grape-crush.css` (default)
- `blue-taffy.css`
- `neptune-dream.css`
- `rock-candy.css`

## 📖 Documentation

**Main Implementation Resource:** [Global Instructions](./Instructions/global-instructions.md)

For detailed guidance on components, tokens, and architecture:
- [Global Instructions](./Instructions/global-instructions.md) - Complete implementation guide
- [Layout Instructions](./Instructions/layout-instructions.md) - Page layout patterns and best practices
- [Token Reference](./Instructions/token-reference.md) - Design token reference

## 🔗 Figma Code Connect

This library is designed to work with Figma's Code Connect feature. Design components in Figma files are mapped to the corresponding components in this library.

## 🛠️ Development

```bash
# Type checking
npm run type-check

# Build library
npm run build
```

## 📄 License

ISC