Manara Design System

A comprehensive design system built with React, TypeScript, Vite, and Tailwind CSS, featuring a scalable primitive → plugin → implementation architecture with semantic utilities.

Quick Links

• Getting Started
• Storybook
• Documentation
• Project Structure
• Architecture
• Design System Features
• Development
• Contributing
• License

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd manara

# Install dependencies
npm install

# Start the development server
npm run dev

🧪 Storybook

This project uses Storybook for component development and documentation:

• Interactive Examples: Test components in isolation
• Foundations Documentation: Colors, Typography, Spacing, Borders, and Icons in src/stories/foundations/
• Welcome/Onboarding Page: src/stories/Welcome.mdx
• Accessibility Testing: Built-in a11y addon for compliance checking
• Documentation: Auto-generated docs from component props
• Visual Testing: Stories for different component states

npm run storybook  # Start Storybook on http://localhost:6006

📖 Documentation

Use these links as the starting point for the project:

• Storybook Welcome: src/stories/Welcome.mdx
• Storybook Foundations:
  • src/stories/foundations/Colors.stories.tsx
  • src/stories/foundations/Typography.stories.tsx
  • src/stories/foundations/Spacing.stories.tsx
  • src/stories/foundations/Borders.stories.tsx
  • src/stories/foundations/Icons.stories.tsx
• Design System Docs: docs/manara-design-system-docs.md
• Code Style Guide: docs/code-style-guide.md
• Component Stories: src/components/*/*.stories.tsx

📁 Project Structure

src/
├── components/           # React components
│   ├── Button/
│   └── Checkbox/
├── stories/              # Storybook MDX + foundations stories
│   ├── Welcome.mdx
│   └── foundations/
├── styles/
│   ├── primitives/      # CSS variables (design tokens)
│   │   ├── colors.css
│   │   ├── fonts.css
│   │   ├── spacing.css
│   │   └── typography.css
│   └── plugins/         # Tailwind plugins for semantic utilities
│       ├── colors-plugin.ts
│       ├── typography-plugin.ts
│       ├── spacing-plugin.ts
│       ├── borders-plugin.ts
│       └── index.ts     # Main plugin hub
├── assets/              # Icons, logos, payment method assets, fonts
└── lib/
    └── utils/           # Utility functions (cn)

🏗️ Architecture

The Manara Design System follows a plugin-based architecture that ensures consistency, maintainability, and scalability:

├── Primitives (CSS Variables) → Raw design tokens
├── Plugins (Tailwind Plugins) → Semantic utilities with manara- prefix
├── Main Plugin Hub → Central aggregation
└── Implementation → Standard Tailwind + Manara utilities

🎨 Design System Features

Plugin-Based Architecture

• Semantic Utilities: All design system utilities use the manara- prefix
• Coexistence: Standard Tailwind utilities work alongside Manara utilities
• Modular: Individual plugins can be used separately if needed

Component Foundation

• Headless UI: All interactive components (modals, dropdowns, drawers) built on Headless UI
• Accessibility: WCAG-compliant components out of the box
• Variant System: Using class-variance-authority for component variants
• Type Safety: Full TypeScript support with autocomplete

Responsive Typography System

• Automatic mobile/desktop typography scaling
• CSS variable-based implementation with manara- prefixed utilities
• No manual breakpoint classes needed for typography

Color System

• Semantic color tokens with manara- prefix (text-manara-primary, bg-manara-brand)
• Consistent palette across all components
• CSS custom properties for dynamic theming

🧩 Using the Design System

• Use manara- semantic utilities for typography, spacing, color, borders, and surfaces.
• Build interactive components with Headless UI primitives for accessibility.
• Use CVA (class-variance-authority) for variant-driven components.
• Reference Storybook (src/stories/Welcome.mdx and src/stories/foundations/) for usage patterns and states.
• Keep implementation details concise in components and centralize reusable logic in typed variants/utilities.

🛠️ Development

Standards and Enforcement

All contributions must strictly adhere to the code style guide:

• docs/code-style-guide.md

Available Scripts

npm run dev              # Start development server
npm run build            # Build for production
npm run preview          # Preview production build
npm run lint             # Run ESLint
npm run format           # Format code with Prettier
npm run storybook        # Start Storybook
npm run build-storybook  # Build Storybook

Code Formatting

This project uses Prettier for consistent code formatting:

• Auto-formatting: Run npm run format to format all files
• ESLint Integration: Prettier rules are integrated with ESLint
• Editor Integration: Configure your editor to format on save

# Format all files
npm run format

# Check formatting without fixing
npx prettier --check .

Workflow Summary

1. Follow docs/code-style-guide.md strictly.
2. Add/update stories for any component changes.
3. Run npm run format and npm run lint before commit.
4. Keep docs aligned with behavior and API changes.

🔧 Tech Stack

Core Technologies

• React 19 - Latest UI library with improved performance
• TypeScript - Type safety and enhanced developer experience
• Vite - Fast build tool and development server
• Tailwind CSS - Utility-first CSS framework with custom plugins

Component & Styling

• Headless UI - Unstyled, accessible components for modals, dropdowns, etc.
• Class Variance Authority (CVA) - Type-safe variant system for components
• clsx + tailwind-merge - Smart class name combining and conflict resolution

Development Tools

• Storybook - Component development and documentation
• ESLint + Prettier - Code linting, formatting, and quality
• Vitest - Fast unit testing framework
• Playwright - End-to-end testing for Storybook

🎯 Key Benefits

• Semantic System: Clear manara- prefixed utilities alongside standard Tailwind
• Accessibility First: Headless UI ensures WCAG compliance out of the box
• Type Safety: Full TypeScript support with autocomplete and validation
• Automatic Responsiveness: Typography adapts without manual breakpoint classes
• Maintainable Architecture: Plugin-based system scales efficiently
• Flexible Implementation: Mix and match Manara utilities with standard Tailwind
• Consistent Patterns: Enforced design decisions across all components

🤝 Contributing

1. Follow docs/code-style-guide.md strictly.
2. Keep changes aligned with architecture and semantic manara- utility usage.
3. Add or update Storybook stories for component changes.
4. Run formatting/linting before commit.
5. Keep README/docs synchronized with functional changes.

📄 License

[Add license information here]