@syncognito/maya/README.md

Maya Design System - Shared tokens and platform-specific components

# Maya Design System

A comprehensive design system with shared tokens and platform-specific components for React Native and Web applications.

## 🎯 **Structure**

```
maya/
├── tokens/          # Universal shared tokens
├── mobile/          # React Native specific tokens & components
├── web/             # Web platform tokens
├── admin-web/       # Admin dashboard specific tokens
├── user-web/        # User-facing web tokens
└── themes/          # Theme variables and colors
```

## 🎨 **Shared Tokens (Universal)**

Universal tokens that work across all platforms:

- **Colors**: Brand colors, semantic colors
- **Border Radius**: Scale values
- **Z-Index**: Layering scale
- **Animation**: Duration and easing

## 📱 **Mobile Platform**

Touch-friendly design optimized for React Native:

- **Typography**: Larger, more readable text (16px base)
- **Spacing**: Touch-friendly spacing with 44px minimum targets
- **Shadows**: React Native shadow objects
- **Colors**: Mobile-specific color variables

## 🌐 **Web Platform**

### **Web Shared**

- **Typography**: Standard web typography
- **Spacing**: Comfortable web spacing
- **Shadows**: Standard web shadows
- **Components**: Shared web components (Button, Card)

### **Admin Web**

- **Typography**: Compact, functional text
- **Spacing**: Dense, efficient spacing
- **Shadows**: Subtle elevation

### **User Web**

- **Typography**: Friendly, readable text
- **Spacing**: Comfortable, user-friendly spacing

## 🚀 **Usage**

### **Import Shared Tokens**

```tsx
import { tokens } from '@syncognito/maya/tokens';
```

### **Import Platform-Specific Tokens**

```tsx
// React Native
import { mobileTokens } from '@syncognito/maya/mobile';

// Web shared
import { webTokens } from '@syncognito/maya/web';

// Admin dashboard
import { adminWebTokens } from '@syncognito/maya/admin-web';

// User-facing web
import { userWebTokens } from '@syncognito/maya/user-web';
```

### **Import Theme Colors**

```tsx
// Web CSS variables
import '@syncognito/maya/themes/variables.css';

// React Native color objects
import { mayaColors } from '@syncognito/maya/themes/variables.mobile';
```

### **Use in Different Apps**

```tsx
// In React Native app
import { mobileTokens } from '@syncognito/maya/mobile';
import { mayaColors } from '@syncognito/maya/themes/variables.mobile';

// In admin web app
import { adminWebTokens } from '@syncognito/maya/admin-web';
import '@syncognito/maya/themes/variables.css';

// In user web app
import { userWebTokens } from '@syncognito/maya/user-web';
import '@syncognito/maya/themes/variables.css';
```

### **NativeWind Integration**

```js
// tailwind.config.js
const { mobileTokens } = require('@syncognito/maya/mobile');
const { mayaColors } = require('@syncognito/maya/themes/variables.mobile');

module.exports = {
  theme: {
    extend: {
      colors: {
        maya: mayaColors.day, // Use day theme as default
      },
      fontSize: mobileTokens.typography.fontSize,
      spacing: mobileTokens.spacing,
      borderRadius: mobileTokens.borderRadius,
    },
  },
};
```

## 🏗️ **Development**

```bash
# Build the design system
pnpm build

# Watch mode
pnpm dev

# Type checking
pnpm type-check

# Linting
pnpm lint
```

## 📦 **Package Exports**

```json
{
  "exports": {
    ".": "./dist/index.js",
    "./tokens": "./dist/tokens.js",
    "./mobile": "./dist/mobile/index.js",
    "./mobile/tokens": "./dist/mobile/tokens.js",
    "./web": "./dist/web/index.js",
    "./web/tokens": "./dist/web/tokens.js",
    "./admin-web": "./dist/admin-web/index.js",
    "./admin-web/tokens": "./dist/admin-web/tokens.js",
    "./user-web": "./dist/user-web/index.js",
    "./user-web/tokens": "./dist/user-web/tokens.js",
    "./themes": "./dist/themes/index.js",
    "./themes/variables.css": "./dist/themes/variables.css",
    "./themes/variables.mobile": "./dist/themes/variables.mobile.js"
  }
}
```

## 🎨 **Available Themes**

- **Day**: Light, professional theme
- **Evening**: Warm, muted theme
- **Night**: Dark theme
- **GenZ**: Vibrant, energetic theme
- **Cyberpunk**: Futuristic, neon theme
- **Retro**: Nostalgic, vintage theme

## 🎯 **Design Philosophy**

- **Shared tokens**: Only truly universal values
- **Platform optimization**: Each platform has its own UX patterns
- **User type separation**: Different tokens for admin vs user
- **Component sharing**: Web components shared between admin and user
- **Clear hierarchy**: Shared → Platform → User Type
- **Developer-friendly**: Simple, intuitive naming conventions

## 📱 **React Native Features**

- **Touch-friendly**: 44px minimum touch targets
- **Native shadows**: React Native shadow objects
- **Color objects**: Direct color values for NativeWind
- **Typography scale**: Mobile-optimized font sizes
- **Spacing system**: Touch-friendly spacing values

## 🌐 **Web Features**

- **CSS variables**: Theme-aware CSS custom properties
- **Component library**: Reusable React components
- **Responsive design**: Mobile-first approach
- **Accessibility**: WCAG compliant design tokens