HomeOverviewFoundationsComponentsGuidelinesPatterns

Architecture

Understanding MUZISYSTEM's structure, layers, and design decisions

System Architecture

MUZISYSTEM follows a layered architecture that separates concerns and enables scalability across multiple brands and products. The system is built on three core layers: Design Tokens, Components, and Patterns.

Core Layers

1. Design Layer

@avnir/design

Design tokens, CSS variables, and base styles. The foundation of the visual language.

  • Colors & themes
  • Typography scale
  • Spacing system
  • Border radius
  • Shadows & effects

2. Component Layer

@avnir/ui

React components built with TypeScript. Reusable, accessible, and performant.

  • Primitives (Button, Input)
  • Layout components
  • Data display
  • Navigation
  • Feedback & overlays

3. Pattern Layer

Apps & Templates

Common UI patterns and page templates for rapid development.

  • Authentication flows
  • Upload workflows
  • Data tables
  • Form patterns
  • Page templates

Package Structure

MUZISYSTEM is organized as a monorepo with clear separation of concerns:

Core Packages

  • @avnir/design - Design tokens and CSS foundation
  • @avnir/ui - React component library
  • @avnir/brandkit - Brand assets and logos
  • @avnir/icons - Icon library

Applications

  • apps/muzisystem - This documentation site
  • apps/ladle - Component playground and stories

Design Principles

🎯 Separation of Concerns

Clear boundaries between design tokens, components, and applications. Each layer has a single responsibility.

🔄 Unidirectional Flow

Apps depend on UI, UI depends on Design. No circular dependencies. Clean dependency graph.

📦 Tree-Shakeable

Import only what you need. Unused components are automatically removed from your bundle.

🎨 Theme-Agnostic

Components work with any brand theme. Switch themes without changing component code.

Multi-Brand Strategy

MUZISYSTEM supports multiple brands through a token-based theming system. Each brand defines its primary color, and the system automatically generates all necessary variants and states.

How It Works

  1. Brand Selection - Set data-brand attribute on HTML element
  2. Token Override - Brand-specific tokens override base tokens
  3. Component Rendering - Components use tokens, automatically styled
  4. Theme Switching - Change data-theme for light/dark mode

Performance Considerations

  • CSS Variables - Runtime theme switching without JavaScript
  • Code Splitting - Load only what's needed per page
  • Minimal Bundle - Optimized component size and dependencies
  • Server Components - Next.js RSC support for optimal performance

Accessibility Architecture

Accessibility is built into the architecture, not added as an afterthought:

  • Semantic HTML - Proper heading hierarchy and landmarks
  • ARIA Attributes - Automatically added where needed
  • Keyboard Navigation - Focus management and keyboard shortcuts
  • Screen Reader - Tested with NVDA, JAWS, and VoiceOver
  • Color Contrast - WCAG 2.2 AA compliant by default