npm package: @kenpan/zds-r8f3v1
Description: React component library built with MUI and TypeScript
Latest version: 0.5.0

# ZDS Component Library

A modern React component library built with MUI (Material-UI) and TypeScript. Designed for building beautiful, accessible, and consistent user interfaces. Optimized for Figma Make integration.

## Features

- **60+ Production-Ready Components** - Buttons, forms, dialogs, tables, navigation, and more
- **1194 Icons** - Comprehensive icon library as React components
- **MUI Foundation** - Built on Material-UI for robust theming and accessibility
- **TypeScript First** - Full type safety with comprehensive type exports
- **Design Tokens** - Consistent spacing, colors, typography, and shadows
- **Figma Make Ready** - Optimized with guidelines for AI-powered code generation
- **Accessible** - WCAG 2.1 compliant focus states and keyboard navigation

## Installation

```bash
npm install @kenpan/zds-r8f3v1 @mui/material @emotion/react @emotion/styled
```

### Peer Dependencies

```json
{
  "@emotion/react": "^11.0.0",
  "@emotion/styled": "^11.0.0",
  "@mui/material": "^6.0.0 || ^7.0.0",
  "@mui/x-data-grid": "^7.0.0 || ^8.0.0",
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}
```

## Quick Start

### 1. Set up the Theme Provider

```tsx
import { ThemeProvider } from '@mui/material/styles'
import CssBaseline from '@mui/material/CssBaseline'
import { theme } from '@kenpan/zds-r8f3v1/theme'

function App() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      {/* Your app */}
    </ThemeProvider>
  )
}
```

### 2. Import and Use Components

```tsx
import { Button, Card, CardHeader, Badge, Alert } from '@kenpan/zds-r8f3v1'
import { PlusIcon } from '@kenpan/zds-r8f3v1/icons'

function MyComponent() {
  return (
    <Card>
      <CardHeader 
        title="Dashboard" 
        actions={
          <Button variant="primary" iconLeading={<PlusIcon size={20} />}>
            Add Item
          </Button>
        }
      />
      <Alert color="success">Welcome to ZDS!</Alert>
    </Card>
  )
}
```

## Package Exports

```tsx
// Main components
import { Button, Card, Alert, Dialog, Table } from '@kenpan/zds-r8f3v1'

// Theme and design tokens
import { theme, gray, primaryScale, typography } from '@kenpan/zds-r8f3v1/theme'

// Icons (1194 icons available)
import { PlusIcon, ChevronDownIcon, SearchSmIcon } from '@kenpan/zds-r8f3v1/icons'
```

## Component Categories

### Base Components
- Button, ButtonGroup
- Card, CardHeader
- Badge, StatusBadge, IndicatorBadge
- Tag, Dot, Tooltip, Icon
- Accordion, AccordionItem

### Form Components
- InputField, InputNumber, InputSearch
- InputDropdown
- Checkbox, Radio, Switch
- Slider

### Feedback Components
- Alert
- Toast
- EmptyState
- Skeleton

### Layout Components
- PageHeader, SectionHeader
- ContentDivider
- BackgroundOverlay

### Navigation Components
- HeaderNavigation
- SidebarNavigation
- Breadcrumbs, HorizontalTabs
- SlideoutMenu

### Overlay Components
- Dialog, DialogHeader, DialogFooter
- Popover, PopoverHeader, PopoverContent, PopoverFooter
- Dropdown, DropdownMenu

### Data Display Components
- Table, TableCell
- ProgressBar, ProgressIndicator, LoadingIndicator
- Scorecard, Tile, DonutChart
- ActivityFeed, SelectionGroup
- Carousel

### Product Components
- ProductCard
- ProductBadges, ProductDescription

## Icons

The library includes 1194 pre-built icon components:

```tsx
import { 
  // Navigation
  ChevronDownIcon, ChevronUpIcon, ChevronLeftIcon, ChevronRightIcon,
  ArrowLeftIcon, ArrowRightIcon,
  
  // Actions
  PlusIcon, MinusIcon, XCloseIcon, CheckIcon,
  EditOneIcon, TrashOneIcon, SearchSmIcon,
  
  // Status
  CheckCircleIcon, AlertCircleIcon, InfoCircleIcon, HelpCircleIcon,
  
  // UI
  HomeLineIcon, SettingsOneIcon, UserOneIcon, BellOneIcon,
} from '@kenpan/zds-r8f3v1/icons'

// Usage
<PlusIcon size={24} />
<SearchSmIcon size={16} color="#376BFD" />
```

## Theme & Design Tokens

Access design tokens through the theme:

```tsx
import { useTheme } from '@mui/material/styles'

function MyComponent() {
  const theme = useTheme()
  
  return (
    <Box
      sx={{
        // Colors
        color: theme.palette.primary.main,
        bgcolor: theme.palette.grey[50],
        
        // Spacing (4px base)
        padding: theme.spacing(4), // 16px
        gap: theme.spacing(2), // 8px
        
        // Typography
        fontSize: 14,
        fontWeight: 500,
        
        // Shadows
        boxShadow: theme.shadows[1],
      }}
    >
      Content
    </Box>
  )
}
```

### Color Palette

| Color | Main | Usage |
|-------|------|-------|
| Primary | `#376BFD` | Primary actions, links |
| Success | `#17B26A` | Success states |
| Error | `#F04438` | Error states |
| Warning | `#F79009` | Warning states |
| Gray | `#697586` | Secondary text, borders |

## Figma Make Integration

This library is optimized for Figma Make with comprehensive guidelines:

1. Create a new Figma Make file
2. Ask the AI to install: `install @kenpan/zds-r8f3v1`
3. The AI reads `guidelines/` to understand component usage

### Guidelines Structure

```
guidelines/
├── Guidelines.md              # Main entry point
├── overview-components.md     # Component overview
├── overview-icons.md          # Icon system
├── design-tokens/
│   ├── colors.md             # Color tokens
│   ├── typography.md         # Typography tokens
│   └── spacing.md            # Spacing system
└── components/
    ├── button.md
    ├── dialog.md
    ├── forms.md
    ├── table.md
    ├── alert.md
    ├── card.md
    ├── badge.md
    ├── navigation.md
    └── layout.md
```

## Documentation

- [Guidelines.md](./guidelines/Guidelines.md) - Main entry point for Figma Make
- [overview-components.md](./guidelines/overview-components.md) - Component overview
- [overview-icons.md](./guidelines/overview-icons.md) - Icon system guide
- [design-tokens/colors.md](./guidelines/design-tokens/colors.md) - Color tokens
- [design-tokens/typography.md](./guidelines/design-tokens/typography.md) - Typography
- [design-tokens/spacing.md](./guidelines/design-tokens/spacing.md) - Spacing system

### Component Guidelines

- [Button](./guidelines/components/button.md)
- [Dialog](./guidelines/components/dialog.md)
- [Forms](./guidelines/components/forms.md)
- [Table](./guidelines/components/table.md)
- [Alert](./guidelines/components/alert.md)
- [Card](./guidelines/components/card.md)
- [Badge](./guidelines/components/badge.md)
- [Navigation](./guidelines/components/navigation.md)
- [Layout](./guidelines/components/layout.md)

## Development

```bash
# Install dependencies
npm install

# Generate icons
npm run generate:icons

# Build the library
npm run build

# Type checking
npm run typecheck
```

## License

MIT License - See [LICENSE](./LICENSE) for details.