npm package: @maya-design-system/design-system
Description: Maya Design System - A comprehensive, framework-agnostic design system built with pure CSS and semantic tokens
Latest version: 2.0.0

# Maya Design System

A comprehensive, framework-agnostic design system built with pure CSS and semantic tokens.

##  **What is Maya Design System?**

Maya Design System is a **pure CSS-based design system** that provides:
- **Framework-agnostic components** - Use with React, Vue, Angular, or vanilla HTML
- **Comprehensive token system** - Base, semantic, and component-level design tokens
- **Multiple theme support** - Light, dark, and high-contrast themes
- **Zero external dependencies** - Pure CSS with no framework lock-in

##  **Quick Start**

### **Installation**

```bash
npm install @maya-design-system/design-system
```

### **Basic Usage**

#### **Option 1: Complete CSS Bundle (recommended)**
```js
// Bundler-friendly import (Vite, Next.js, webpack, etc.)
import '@maya-design-system/design-system/css'; // loads maya.css
```

```html
<!-- Plain HTML usage -->
<link
  rel="stylesheet"
  href="node_modules/@maya-design-system/design-system/dist/css/maya.css"
>
```

#### **Option 2: Modular CSS (load only what you need)**
```js
import '@maya-design-system/design-system/css/foundation';
import '@maya-design-system/design-system/css/components/button';
import '@maya-design-system/design-system/css/components/overlay';
```

```html
<!-- Foundation layer is required -->
<link
  rel="stylesheet"
  href="node_modules/@maya-design-system/design-system/dist/css/maya-foundation.css"
>
<!-- Add whichever component bundles you rely on -->
<link rel="stylesheet" href="node_modules/@maya-design-system/design-system/dist/css/components/button.css">
<link rel="stylesheet" href="node_modules/@maya-design-system/design-system/dist/css/components/overlay.css">
```

#### **Option 3: React usage (roadmap)**
The package exposes ready-made React components for rapid prototyping. These will be promoted to a supported API in a future minor release.

```tsx
import { Button, Alert, Card } from '@maya-design-system/design-system';

export function App() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Alert variant="success">Success message</Alert>
      <Card>Card content</Card>
    </div>
  );
}
```

> **Tip:** The CSS bundle already includes focus states, tokens, and theme support. When consuming the React helpers you can still cherry-pick the CSS using Option 2 for optimal performance.

## **What’s new in 2.0.0 Beta?**

- **Full catalog coverage** – 28 components ship with modular CSS bundles (structure, overlay, feedback, data display, navigation, forms, etc.).
- **Consistent iconography** – Inline SVG glyphs replace emoji usage in alerts, toast notifications, and supporting utilities for predictable rendering.
- **Improved responsive documentation** – The docs navigation mirrors the component gallery: sticky on desktop, stacked on mobile for easier browsing.
- **Refined build pipeline** – `generate-tokens` and `build-css-modular` output the refreshed artifacts used by Maya’s showcase app.

##  **Design Tokens**

Maya Design System uses a **3-layer token architecture**:

### **1. Base Tokens (Raw Primitives)**
```css
:root {
  /* Color Palettes */
  --palette-neutral-0: #ffffff;
  --palette-neutral-50: #fafafa;
  --palette-neutral-100: #f5f5f5;
  /* ... more neutral colors */
  
  --palette-blue-600: #2563eb;
  --palette-green-600: #059669;
  --palette-red-600: #dc2626;
  
  /* Spacing Scale */
  --spacing-4: 1rem;
  --spacing-8: 2rem;
  --spacing-16: 4rem;
  
  /* Typography */
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-weight-medium: 500;
}
```

### **2. Semantic Tokens (Meaningful Names)**
```css
:root {
  /* Semantic Colors */
  --primary: var(--palette-blue-600);
  --primary-foreground: var(--palette-neutral-0);
  --primary-hover: var(--palette-blue-700);
  
  --success: var(--palette-green-600);
  --success-foreground: var(--palette-neutral-0);
  
  --background: var(--palette-neutral-0);
  --foreground: var(--palette-neutral-950);
}
```

### **3. Component Tokens (Specific Use Cases)**
```css
:root {
  /* Button-specific tokens */
  --button-primary-bg: var(--primary);
  --button-primary-fg: var(--primary-foreground);
  --button-primary-hover: var(--primary-hover);
  
  /* Alert-specific tokens */
  --alert-success-bg: var(--success);
  --alert-success-fg: var(--success-foreground);
}
```

## 🌓 **Theming**

### **Light Theme (Default)**
```css
:root {
  --background: var(--palette-neutral-0);
  --foreground: var(--palette-neutral-950);
  --primary: var(--palette-blue-600);
}
```

### **Dark Theme**
```css
.dark {
  --background: var(--palette-neutral-950);
  --foreground: var(--palette-neutral-50);
  --primary: var(--palette-blue-400);
}
```

### **High Contrast Theme**
```css
.high-contrast {
  --background: var(--palette-neutral-1000);
  --foreground: var(--palette-neutral-0);
}
```

## 🧩 **Components**

### **Available Components**

- **Button** - Primary, secondary, destructive variants
- **Alert** - Success, warning, info, error variants
- **Card** - Basic card with header, content, footer
- **Input** - Text input with focus states
- **Modal** - Overlay dialog with backdrop
- **Navigation** - Responsive navigation menu
- **Table** - Data table with zebra striping
- **Form** - Form elements with validation states

### **Component Usage**

#### **Pure CSS Classes**
```html
<button class="maya-button maya-button--variant-primary maya-button--size-lg">
  Primary Button
</button>

<div class="maya-alert maya-alert--variant-success">
  <span class="maya-alert__icon">✓</span>
  <span class="maya-alert__message">Success message</span>
</div>
```

#### **React Components**
```jsx
import { Button, Alert } from '@maya-design-system/design-system';

<Button variant="primary" size="lg">Primary Button</Button>
<Alert variant="success" icon="✓">Success message</Alert>
```

##  **Package Exports**

```json
{
  "exports": {
    ".": "./dist/index.js",                    // React components
    "./css": "./dist/css/maya.css",            // Complete CSS bundle
    "./css/min": "./dist/css/maya.min.css",    // Minified CSS bundle
    "./css/foundation": "./dist/css/maya-foundation.css", // Foundation only
    "./css/foundation/min": "./dist/css/maya-foundation.min.css", // Foundation minified
    "./css/components/button": "./dist/css/components/button.css", // Button component
    "./css/components/form": "./dist/css/components/form.css", // Form components
    "./css/components/data-display": "./dist/css/components/data-display.css", // Data display
    "./tokens": "./dist/tokens/tokens.json"    // Token data
  }
}
```

##  **Build & Development**

### **Available Scripts**
```bash
npm run build              # Build everything
npm run build:css:modular  # Generate modular CSS (foundation + components)
npm run build:tokens       # Generate tokens.json
npm run build:website      # Build documentation website
npm run dev:website        # Development server
```

### **Build Output**
```
dist/
├── index.js           # CommonJS bundle
├── index.mjs          # ES Module bundle
├── index.d.ts         # TypeScript definitions
├── css/               # CSS files
│   ├── maya.css       # Complete CSS bundle (25KB)
│   ├── maya.min.css   # Minified CSS bundle (22KB)
│   ├── maya-foundation.css # Foundation only (9KB)
│   └── components/    # Individual component CSS
│       ├── button.css
│       ├── form.css
│       └── data-display.css
├── tokens/            # Token data
│   └── tokens.json
└── website/           # Documentation website
```

##  **Framework Support**

### **React (Primary)**
```jsx
import { Button } from '@maya-design-system/design-system';

<Button variant="primary">Click me</Button>
```

### **Vue**
```vue
<template>
  <button class="maya-button maya-button--variant-primary">
    Click me
  </button>
</template>

<script>
import '@maya-design-system/design-system/css';
</script>
```

### **Angular**
```typescript
// angular.json
"styles": [
  "node_modules/@maya-design-system/design-system/css"
]

// component.html
<button class="maya-button maya-button--variant-primary">
  Click me
</button>
```

### **Vanilla HTML/CSS**
```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/@maya-design-system/design-system/css">
</head>
<body>
  <button class="maya-button maya-button--variant-primary">
    Click me
  </button>
</body>
</html>
```

##  **Customization**

### **Override CSS Variables**
```css
:root {
  /* Override primary color */
  --primary: #ff6b6b;
  --primary-hover: #ff5252;
  
  /* Override spacing */
  --spacing-4: 1.5rem;
  --spacing-8: 3rem;
}
```

### **Create Custom Variants**
```css
.maya-button--variant-custom {
  background-color: var(--palette-purple-600);
  color: var(--palette-neutral-0);
}

.maya-button--variant-custom:hover {
  background-color: var(--palette-purple-700);
}
```

## 📱 **Responsive Design**

All components are built with responsive design in mind:

```css
/* Mobile-first approach */
.maya-card {
  padding: var(--spacing-4);
}

/* Tablet and up */
@media (min-width: 768px) {
  .maya-card {
    padding: var(--spacing-6);
  }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .maya-card {
    padding: var(--spacing-8);
  }
}
```

## ♿ **Accessibility**

- **WCAG 2.1 AA compliant** color contrast ratios
- **Keyboard navigation** support for all interactive elements
- **Screen reader** friendly markup and ARIA labels
- **Focus management** for modals and overlays
- **High contrast** theme support

##  **Migration from Tailwind**

If you're migrating from a Tailwind-based design system:

1. **Replace Tailwind classes** with Maya CSS classes
2. **Use CSS variables** instead of Tailwind's color palette
3. **Import Maya CSS** instead of Tailwind CSS
4. **Update component props** to use Maya's variant system

##  **Documentation & Examples**

- [Component Gallery](https://maya-design-system.com)
- [Token Explorer](https://maya-design-system.com/tokens)
- [Theme Builder](https://maya-design-system.com/themes)
- [Migration Guide](https://maya-design-system.com/migrate)

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

## 🆘 **Support**

- **Documentation**: [docs.maya-design-system.com](https://docs.maya-design-system.com)
- **Issues**: [GitHub Issues](https://github.com/your-org/maya-design-system/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/maya-design-system/discussions)

---

**Built with ❤ by the Maya Design System team**