@wtai/design-system

v1.1.0

Published

4 months ago

Maya Design System - A comprehensive, framework-agnostic design system built with pure CSS and semantic tokens

0High
0Medium
0Low

wtai-team

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

npm install @maya/design-system

Basic Usage

Option 1: Complete CSS Bundle (Recommended)

<!-- Include the complete CSS with reset, base styles, and all components -->
<link rel="stylesheet" href="node_modules/@maya/design-system/css">

Option 2: Modular CSS (Performance Optimized)

<!-- Foundation CSS (required) -->
<link rel="stylesheet" href="node_modules/@maya/design-system/css/foundation">

<!-- Individual component CSS (choose what you need) -->
<link rel="stylesheet" href="node_modules/@maya/design-system/css/components/button">
<link rel="stylesheet" href="node_modules/@maya/design-system/css/components/form">

Option 3: React Components

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

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

🎨 Design Tokens

Maya Design System uses a 3-layer token architecture:

1. Base Tokens (Raw Primitives)

: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)

: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)

: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)

:root {
  --background: var(--palette-neutral-0);
  --foreground: var(--palette-neutral-950);
  --primary: var(--palette-blue-600);
}

Dark Theme

.dark {
  --background: var(--palette-neutral-950);
  --foreground: var(--palette-neutral-50);
  --primary: var(--palette-blue-400);
}

High Contrast Theme

.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

<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

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

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

📦 Package Exports

{
  "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

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)

import { Button } from '@maya/design-system';

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

Vue

<template>
  <button class="maya-button maya-button--variant-primary">
    Click me
  </button>
</template>

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

Angular

// angular.json
"styles": [
  "node_modules/@maya/design-system/css"
]

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

Vanilla HTML/CSS

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

🔧 Customization

Override CSS Variables

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

Create Custom Variants

.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:

/* 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:

Replace Tailwind classes with Maya CSS classes
Use CSS variables instead of Tailwind's color palette
Import Maya CSS instead of Tailwind CSS
Update component props to use Maya's variant system

📚 Documentation & Examples

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Documentation: docs.maya-design-system.com
Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ by the Maya Design System team