MASE - Meta Architecture Style Engine

A comprehensive, theme-aware styling engine for modern web applications. MASE provides atomic CSS utilities, design token management, and multi-platform materialization with full TypeScript support.

🚀 Features

Core Capabilities

• 700+ Atomic CSS Utilities - Complete coverage of all modern CSS properties
• Design Token System - Centralized token management with theme support
• Multi-Platform Materialization - Generate styles for Web, React Native, PDF, and more
• Constitutional Styling - Enforce design system rules and governance
• Dark Mode Support - Automatic theme switching with CSS variables
• Full TypeScript Support - Type-safe development with comprehensive type definitions
• Style Governance - Built-in validation and compliance checking
• Performance Optimization - Caching and efficient style resolution

Integration Options

• PostCSS Plugin - Automatic CSS variable generation
• Atomic CSS Generator - Utility-first approach similar to Tailwind
• Tailwind Preset - Seamless integration with existing Tailwind projects
• CSS-in-JS - Support for styled-components, emotion, and more
• React Integration - React Provider and hooks for runtime styling

Specialized Handlers

• Layout - Display, position, visibility, z-index, overflow, object-fit
• Flexbox - Complete flexbox utilities with justify/align support
• Grid - Full CSS Grid support with template columns/rows
• Typography - Font size, weight, line-height, text alignment
• Color - Background, text, and border colors
• Effects - Shadows, border radius, opacity
• Background - Background image, position, repeat, size, gradients
• Border - Border radius, width, color, style, outline
• Transform - Scale, rotate, translate, skew, perspective
• Transition - Transition properties, timing functions, animations
• Interactivity - Cursor, pointer events, resize, scroll behavior
• Tables - Border collapse, spacing, layout, caption side
• SVG - Fill, stroke, stroke width
• Accessibility - Forced color adjust, screen reader utilities, focus states
• Filters - Blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, saturate, sepia, backdrop-filter

📦 Installation

npm install @damarkuncoro/meta-architecture-style-engine

Peer Dependencies

npm install @damarkuncoro/meta-architecture@^2.0.4 react@>=18.0.0 postcss@^8.0.0

🎯 Quick Start

Option 1: PostCSS Plugin (Recommended)

postcss.config.js

export default {
  plugins: [
    require('@damarkuncoro/meta-architecture-style-engine/postcss')({
      prefix: '--',
      rootSelector: ':root',
      generateDarkMode: true,
      darkModeAttribute: 'data-theme="dark"'
    })
  ]
}

styles.css

/* MASE CSS variables are automatically injected */

body {
  font-family: system-ui, sans-serif;
  color: var(--color-text-primary);
  background-color: var(--color-background);
}

.button {
  background-color: var(--color-primary);
  color: var(--color-white);
  padding: var(--space-md);
  border-radius: var(--radius-md);
}

Option 2: Atomic CSS Generator

import { AtomicCSSGenerator } from '@damarkuncoro/meta-architecture-style-engine';
import { TOKENS } from '@damarkuncoro/meta-architecture-style-engine';

const generator = new AtomicCSSGenerator();
const css = generator.generate(TOKENS, {
  prefix: 'mase-',
  selector: ':root',
  includeReset: true
});

console.log(css);

Option 3: Tailwind Preset

tailwind.config.js

import { createMasePreset } from '@damarkuncoro/meta-architecture-style-engine/tailwind';

export default {
  presets: [
    createMasePreset({
      useCssVariables: true,
      variablePrefix: '--'
    })
  ]
}

Option 4: React Integration

import { StyleProvider, useStyleContract } from '@damarkuncoro/meta-architecture-style-engine';

function App() {
  return (
    <StyleProvider>
      <YourComponent />
    </StyleProvider>
  );
}

function YourComponent() {
  const { resolveStyles } = useStyleContract();
  const styles = resolveStyles({
    backgroundColor: 'primary',
    padding: 'md',
    borderRadius: 'md'
  });
  
  return <div style={styles}>Hello MASE!</div>;
}

📚 Documentation

Getting Started

• Quick Start Guide - Get started with MASE in minutes
• Developer Guide: CSS Class Discovery - How to find available CSS classes
• Migration Guide - Migrate from other systems
• Troubleshooting - Common issues and solutions

Architecture & Concepts

• Architecture Diagram - System architecture overview
• Constitutional Styling - Core styling philosophy
• DSL Reference - Domain-specific language guide
• Constitution Pattern - Design pattern documentation

Integration Guides

• CSS Import Guide - Using MASE with CSS imports
• Atomic CSS Complete Guide - Complete utility reference
• Next.js Integration - Next.js specific setup
• React Native Integration - React Native setup
• Storybook Integration - Storybook integration
• Token Conventions - Design token best practices

Development Documentation

• Development Guide - Contributing to MASE
• Integration Layer Review - Integration layer analysis
• Recommendations Implementation - Implemented improvements
• DSL Analysis - DSL design and architecture
• Refactoring Plan - Code improvement strategies
• Code Quality Report - DRY, SOLID, and reusability analysis

Specifications

• Constitutional Styling
• Spacing Constitution
• Typography Constitution
• Color Constitution
• Layer Constitution
• Effect Constitution
• Grid Constitution

Examples

• Basic Examples - Simple component examples
• Advanced Examples - Complex use cases
• Integration Examples - Integration patterns

🎨 Utility Classes Reference

Layout

.block { display: block; }
.flex { display: flex; }
.grid { display: grid; }
.relative { position: relative; }
.z-10 { z-index: 10; }

Flexbox

.flex-row { flex-direction: row; }
.items-center { align-items: center; }
.justify-between { justify-content: space-between; }
.gap-4 { gap: 1rem; }

Grid

.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.col-span-2 { grid-column: span 2 / span 2; }

Spacing

.p-4 { padding: 1rem; }
.m-4 { margin: 1rem; }
.gap-4 { gap: 1rem; }

Typography

.text-lg { font-size: 1.125rem; }
.font-bold { font-weight: 700; }
.leading-relaxed { line-height: 1.625; }

Color

.bg-primary { background-color: var(--color-primary); }
.text-white { color: var(--color-white); }
.border-gray-200 { border-color: var(--color-gray-200); }

Effects

.rounded-md { border-radius: 0.375rem; }
.shadow-lg { box-shadow: var(--shadow-lg); }
.opacity-50 { opacity: 0.5; }

Filters

.blur-md { filter: blur(8px); }
.brightness-125 { filter: brightness(1.25); }
.backdrop-blur-md { backdrop-filter: blur(8px); }

Interactivity

.cursor-pointer { cursor: pointer; }
.pointer-events-none { pointer-events: none; }
.select-none { user-select: none; }

🌙 Dark Mode

MASE provides automatic dark mode support:

/* Light mode */
.button {
  background-color: var(--color-primary);
  color: var(--color-white);
}

/* Dark mode */
[data-theme="dark"] .button {
  background-color: var(--color-primary-dark);
  color: var(--color-white-dark);
}

Theme Switching

function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem('theme', theme);
}

// Initialize theme
const savedTheme = localStorage.getItem('theme');
const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
setTheme(savedTheme || systemTheme);

🔧 CLI Commands

MASE provides a comprehensive CLI with the following commands:

# Initialize MASE in your project
npx mase init

# Compile style contracts
npx mase compile <contract-file>

# Validate contracts
npx mase validate <contract-file>

# Validate token configuration
npx mase validate-tokens [config-file]

# Validate CSS syntax
npx mase validate-css <css-file>

# Generate CSS
npx mase generate-css

# Generate Atomic CSS (all utilities)
npx mase generate-css --format atomic

# Generate CSS with JIT mode (only used classes)
npx mase generate-css --format atomic --content "./src/**/*.{html,js,ts,jsx,tsx}"

# Watch for changes
npx mase watch <contract-file>

# Audit CSS file
npx mase audit-css <css-file>

# Audit design system
npx mase audit

# Inspect style contracts
npx mase inspect <contract-file>

# Generate documentation
npx mase doc

# List all design tokens
npx mase list-tokens

# List registered CSS handlers
npx mase handlers

# Import CSS files
npx mase css-import <css-file>

Validation Commands

# Validate token configuration (default: mase.tokens.js)
npx mase validate-tokens
npx mase validate-tokens --strict  # Enable strict validation
npx mase validate-tokens --fix    # Auto-fix issues
npx mase validate-tokens --json   # Output JSON

# Validate CSS syntax
npx mase validate-css styles.css
npx mase validate-css --duplicates styles.css  # Check for duplicates
npx mase validate-css --json styles.css       # Output JSON

# Validate style contracts
npx mase validate contract.mase

Audit Commands

# Audit CSS file
npx mase audit-css atomic.css
npx mase audit-css atomic.css --json  # Output JSON
npx mase audit-css atomic.css --max-unused 10  # Fail if >10 unused variables
npx mase audit-css atomic.css --max-duplicate-selectors 5  # Fail if >5 duplicates

# Audit design system governance
npx mase audit

Developer Scripts

# List all available design tokens
npm run list-tokens

# List all registered CSS handlers
npm run list-handlers

# Generate documentation specification
npm run generate-doc-spec

# Audit CSS file
npm run audit:css

Handler Inspection & Coverage

MASE exposes a dedicated CLI command to inspect atomic handlers and their token coverage:

# List all registered handlers with basic metadata
npx mase handlers

# Filter by domain (e.g. typography, layout, colors)
npx mase handlers --domain typography

# Show only "dead" handlers (handlers that currently handle zero tokens)
npx mase handlers --dead-only

# Sort handlers by token coverage (most productive first)
npx mase handlers --sort tokens

# Output JSON with aggregated statistics
npx mase handlers \
  --json \
  --stats \
  --group-by domain

# Stream handler metadata as NDJSON (1 JSON object per line)
npx mase handlers \
  --json \
  --format ndjson

Key options:

• --domain <domain> – filter by handler domain (e.g. layout, typography, colors).
• --source <decorator|factory|all> – filter by registration source.
• --min-tokens <count> – show handlers with tokenCount below the given threshold.
• --dead-only – convenience alias to list only handlers with tokenCount = 0.
• --sort <field> – sort by domain, type, priority, or tokens.
• --stats / --stats-only – include only aggregated statistics (optionally without items).
• --group-by domain – group statistics by handler domain.
• --json – output JSON instead of the human-readable table.
• --format <pretty|ndjson> – control JSON format; ndjson streams one object per line.

📊 Performance

MASE is optimized for performance:

• Caching - 50-90% improvement for repeated style resolutions
• Efficient Generation - Minimal CSS output with no duplicates
• Type Safety - Compile-time type checking reduces runtime errors
• Lazy Evaluation - Only generate what's needed

Benchmarks

Run performance benchmarks:

npm run benchmark

Expected results:

• Style Resolution (No Cache): ~0.5-2ms per operation
• Style Resolution (With Cache): ~0.01-0.1ms per operation (90-95% faster)
• Cache Hit Rate: 100% for repeated operations

🏗️ Architecture

MASE follows a layered architecture:

┌─────────────────────────────────────────┐
│         Integration Layer              │
│  ┌──────────┬──────────┬─────────┐│
│  │ PostCSS   │  Atomic   │ Tailwind ││
│  │  Plugin    │   CSS     │ Preset  ││
│  └──────────┴──────────┴─────────┘│
└─────────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│         Domain Layer                │
│  ┌──────────┬──────────┬─────────┐│
│  │ Tokens    │Governance│Resolution││
│  │ Registry   │  Engine  │  Engine  ││
│  └──────────┴──────────┴─────────┘│
└─────────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│      Materialization Layer           │
│  ┌──────────┬──────────┬─────────┐│
│  │   CSS     │   RN     │   PDF   ││
│  │Materializer│Materializer│Materializer││
│  └──────────┴──────────┴─────────┘│
└─────────────────────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│        Runtime Layer                │
│  ┌──────────┬──────────┬─────────┐│
│  │   Web     │   RN     │Adapter  ││
│  │  Adapter  │  Adapter  │Factory  ││
│  └──────────┴──────────┴─────────┘│
└─────────────────────────────────────────┘

🤝 Contributing

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

Development Setup

# Clone the repository
git clone https://github.com/damarkuncoro/meta-architecture-style-engine.git
cd meta-architecture-style-engine

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run CLI
npm run cli

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Inspired by Tailwind CSS's utility-first approach
• Built with TypeScript for type safety
• Designed for modern web development
• Part of the Meta Architecture ecosystem

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email

🔗 Related Projects

• @damarkuncoro/meta-architecture - The core Meta Architecture framework

MASE - Meta Architecture Style Engine

Build beautiful, consistent, and theme-aware user interfaces with ease.

Author: Damar Kuncoro
Version: 0.2.1

⚡️ JIT Mode & Watch

MASE 0.2.0 introduces a powerful Just-In-Time (JIT) compiler with watch mode support.

Using JIT CLI

Generate CSS on-demand by scanning your content files:

npx @damarkuncoro/meta-architecture-style-engine generate-css \
  --format atomic \
  --content "./src/**/*.{html,js,ts,jsx,tsx}" \
  --watch \
  --output dist/utilities.css

• --content: Glob pattern(s) to scan for class names (e.g., p-4, text-center, hover:text-left).
• --watch: Real-time updates. Saves CSS instantly when you modify any content file.
• --output: Destination file for the generated CSS.

Supported Features in JIT

• Arbitrary Values: (Coming soon)
• Variants: hover:, focus:, active:, disabled:, group-hover:, focus-within:.
• Negative Values: -m-4 (negative margin).
• Opacity Modifiers: bg-blue-500/50.
• Importance: !text-center.