@maya-design-system/design-system

v2.0.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/design-system

Basic Usage

Option 1: Complete CSS Bundle (recommended)

// Bundler-friendly import (Vite, Next.js, webpack, etc.)
import '@maya-design-system/design-system/css'; // loads maya.css

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

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';

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

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)

: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/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/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/design-system/css';
</script>

Angular

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

<!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

: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