Skip to content
/ OriginArt Public

Origin art is a melting pot of design systems,2D-3D experiments, and components with configurable themes and design systems.

0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Origin-pod/OriginArt

BranchesTags

Repository files navigation

Origin Art Design System

A multi-design-system monorepo with theming and experimental components built on React, TypeScript, and modern web technologies.

🏗️ Architecture Overview

This project is a monorepo that contains multiple design systems, shared tokens, a theme engine, and UI primitive and core components. It's designed to showcase how different design aesthetics can coexist while sharing a common underlying architecture with proper package separation.

✅ Successfully Restructured Component Library!

The component library has been moved from apps/component-library/ to proper packages:

What was accomplished:

🎯 UI Primitive Package (@origin-art/ui-primitive)

  • Button component with 5 variants (primary, secondary, outline, text, ghost)
  • 3 sizes (sm, md, lg)
  • Full theme integration using CSS custom properties
  • Complete Storybook documentation with all variants and examples

🎯 UI Core Package (@origin-art/ui-core)

  • ThemeSwitcher component re-exported from theme-engine
  • Theme engine re-exports for convenience
  • Complete Storybook documentation with examples

🎯 Updated Playground App

  • Changed imports to use new packages instead of component-library
  • Maintains all functionality with proper theme switching

Benefits Achieved:

✅ Proper Package Architecture - Components follow intended hierarchy (primitives → core → apps) ✅ Clean Separation - UI primitives and core components are in separate packages ✅ Better Reusability - Primitives can now be used independently ✅ Future-Proof - Easy to add new primitives and core components ✅ Theme Integration - All components properly use design token system ✅ TypeScript Support - Full type safety for all components and props

Current Status:

  • Playground app running at http://localhost:3003/
  • All packages build successfully with TypeScript support
  • Theme switching working between Minimal ↔ Rough design systems
  • Button components working in all variants and sizes

Complete Migration from component-library to proper package structure

High-Level Architecture

graph TB
    subgraph "Monorepo Root"
        Root[package.json<br/>pnpm-workspace.yaml<br/>turbo.json]
    end

    subgraph "Token Packages"
        Core[tokens-core<br/>Type definitions<br/>Token utilities]
        Minimal[tokens-minimal<br/>Clean, minimal design]
        Rough[tokens-rough<br/>Hand-drawn aesthetic]
    end

    subgraph "Theme Engine"
        ThemeEngine[theme-engine<br/>ThemeProvider<br/>useTheme hook<br/>ThemeSwitcher]
    end

    subgraph "Component Library"
        ComponentLib[component-library<br/>UI Components<br/>Storybook docs]
    end

    subgraph "Applications"
        Playground[playground<br/>Demo app<br/>Theme showcase]
    end

    Core --> Minimal
    Core --> Rough
    Minimal --> ThemeEngine
    Rough --> ThemeEngine
    ThemeEngine --> ComponentLib
    ComponentLib --> Playground

    Root -.-> Core
    Root -.-> Minimal
    Root -.-> Rough
    Root -.-> ThemeEngine
    Root -.-> ComponentLib
    Root -.-> Playground
Loading

📦 Package Structure

graph LR
    subgraph "packages/"
        CorePkg[tokens-core]
        MinimalPkg[tokens-minimal]
        RoughPkg[tokens-rough]
        ThemePkg[theme-engine]
    end

    subgraph "apps/"
        ComponentPkg[component-library]
        PlaygroundPkg[playground]
    end

    CorePkg --> MinimalPkg
    CorePkg --> RoughPkg
    MinimalPkg --> ThemePkg
    RoughPkg --> ThemePkg
    ThemePkg --> ComponentPkg
    ComponentPkg --> PlaygroundPkg
Loading

🎨 Token System Architecture

Token Hierarchy

graph TD
    subgraph "Token Core Layer"
        Types[TypeScript Interfaces<br/>SemanticTokens, ColorRole, etc.]
        Factory[createSemanticTokens<br/>Token factory function]
        Defaults[Default Values<br/>Fallback tokens]
    end

    subgraph "Design System Implementations"
        MinimalTokens[Minimal Tokens<br/>Clean, modern design]
        RoughTokens[Rough Tokens<br/>Hand-drawn aesthetic]
    end

    subgraph "Theme Resolution"
        LightMode[Light Theme]
        DarkMode[Dark Theme]
    end

    Types --> Factory
    Factory --> MinimalTokens
    Factory --> RoughTokens
    MinimalTokens --> LightMode
    MinimalTokens --> DarkMode
    RoughTokens --> LightMode
    RoughTokens --> DarkMode
Loading

Token Categories

graph LR
    subgraph "Semantic Tokens"
        Colors[🎨 Colors<br/>bg/page, fg/primary, accent/default]
        Spacing[📏 Spacing<br/>xs, sm, md, lg, xl, 2xl, 3xl]
        Radii[⭕ Radii<br/>xs, sm, md, lg, xl, pill]
        Typography[🔤 Typography<br/>families, sizes, weights, lineHeights]
        Shadows[🌑 Shadows<br/>sm, md, lg, xl]
    end

    subgraph "Design Systems"
        MinimalDS[Minimal Design System]
        RoughDS[Rough Design System]
    end

    subgraph "Theme Modes"
        Light[Light Mode]
        Dark[Dark Mode]
    end

    Colors --> MinimalDS
    Spacing --> MinimalDS
    Radii --> MinimalDS
    Typography --> MinimalDS
    Shadows --> MinimalDS

    Colors --> RoughDS
    Spacing --> RoughDS
    Radii --> RoughDS
    Typography --> RoughDS
    Shadows --> RoughDS

    MinimalDS --> Light
    MinimalDS --> Dark
    RoughDS --> Light
    RoughDS --> Dark
Loading

🎯 Theme Engine Flow

Theme Provider Architecture

sequenceDiagram
    participant App as Application
    participant TP as ThemeProvider
    participant TC as ThemeContext
    participant DOM as Document DOM
    participant Tokens as Token Packages

    App->>TP: Initialize with designSystem + mode
    TP->>Tokens: Load tokens based on designSystem
    Tokens-->>TP: Return SemanticTokens
    TP->>TP: Create ResolvedTheme object
    TP->>TC: Update context value
    TP->>DOM: Set CSS custom properties

    loop Token Application
        TP->>DOM: Set --color-* variables
        TP->>DOM: Set --spacing-* variables
        TP->>DOM: Set --radius-* variables
        TP->>DOM: Set --font-family-* variables
        TP->>DOM: Set --font-size-* variables
        TP->>DOM: Set --font-weight-* variables
        TP->>DOM: Set --line-height-* variables
    end

    App->>TP: Theme change request
    TP->>Tokens: Load new tokens
    TP->>DOM: Update CSS variables
    TC-->>App: Notify theme change
Loading

Theme Switching Flow

stateDiagram-v2
    [*] --> Minimal_Light
    Minimal_Light --> Minimal_Dark: Toggle Mode
    Minimal_Dark --> Minimal_Light: Toggle Mode
    Minimal_Light --> Rough_Light: Change Design System
    Minimal_Dark --> Rough_Dark: Change Design System
    Rough_Light --> Rough_Dark: Toggle Mode
    Rough_Dark --> Rough_Light: Toggle Mode
    Rough_Light --> Minimal_Light: Change Design System
    Rough_Dark --> Minimal_Dark: Change Design System
Loading

🧩 Component System

Component Architecture

graph TD
    subgraph "Component Library"
        Button[Button Component]
        StyledButton[Styled Components]
        Stories[Storybook Stories]
        Types[TypeScript Props]
    end

    subgraph "Theme Integration"
        ThemeProvider[ThemeProvider]
        useTheme[useTheme Hook]
        CSSTokens[CSS Custom Properties]
    end

    subgraph "Token Consumption"
        ColorTokens[Color Tokens<br/>accent/default, fg/primary]
        SpacingTokens[Spacing Tokens<br/>xs, sm, md, lg]
        TypographyTokens[Typography Tokens<br/>font-family, font-size]
        RadiusTokens[Radius Tokens<br/>md, sm]
    end

    Button --> StyledButton
    Button --> Types
    Button --> Stories
    StyledButton --> ThemeProvider
    StyledButton --> CSSTokens
    CSSTokens --> ColorTokens
    CSSTokens --> SpacingTokens
    CSSTokens --> TypographyTokens
    CSSTokens --> RadiusTokens
Loading

Button Component Flow

flowchart TD
    Start([Button Render]) --> CheckProps{Check Props}
    CheckProps -->|variant='primary'| PrimaryStyle[Primary Styles]
    CheckProps -->|variant='secondary'| SecondaryStyle[Secondary Styles]
    CheckProps -->|variant='outline'| OutlineStyle[Outline Styles]
    CheckProps -->|variant='text'| TextStyle[Text Styles]
    CheckProps -->|variant='ghost'| GhostStyle[Ghost Styles]

    PrimaryStyle --> SizeCheck{Check Size}
    SecondaryStyle --> SizeCheck
    OutlineStyle --> SizeCheck
    TextStyle --> SizeCheck
    GhostStyle --> SizeCheck

    SizeCheck -->|size='sm'| SmallSize[Small Padding + Font]
    SizeCheck -->|size='md'| MediumSize[Medium Padding + Font]
    SizeCheck -->|size='lg'| LargeSize[Large Padding + Font]

    SmallSize --> TokenResolution[Resolve CSS Custom Properties]
    MediumSize --> TokenResolution
    LargeSize --> TokenResolution

    TokenResolution --> RenderButton[Render Styled Button]
    RenderButton --> End([Complete])
Loading

🔨 Build System

Turbo Build Pipeline

graph TD
    subgraph "Root Commands"
        Build[pnpm build]
        Dev[pnpm dev]
        Lint[pnpm lint]
        Clean[pnpm clean]
        TypeCheck[pnpm type-check]
    end

    subgraph "Package Dependencies"
        CoreBuild[tokens-core build]
        MinimalBuild[tokens-minimal build]
        RoughBuild[tokens-rough build]
        ThemeBuild[theme-engine build]
        ComponentBuild[component-library build]
        PlaygroundBuild[playground build]
    end

    subgraph "Build Tools"
        TSUP[TSUP - TypeScript bundler]
        Vite[Vite - Build tool]
        TSC[TypeScript Compiler]
        Storybook[Storybook Build]
    end

    Build --> CoreBuild
    Build --> MinimalBuild
    Build --> RoughBuild
    Build --> ThemeBuild
    Build --> ComponentBuild
    Build --> PlaygroundBuild

    CoreBuild --> TSUP
    MinimalBuild --> TSUP
    RoughBuild --> TSUP
    ThemeBuild --> TSUP
    ComponentBuild --> Vite
    ComponentBuild --> Storybook
    PlaygroundBuild --> Vite

    CoreBuild -.-> MinimalBuild
    CoreBuild -.-> RoughBuild
    MinimalBuild -.-> ThemeBuild
    RoughBuild -.-> ThemeBuild
    ThemeBuild -.-> ComponentBuild
    ComponentBuild -.-> PlaygroundBuild
Loading

Development Workflow

sequenceDiagram
    participant Dev as Developer
    participant Root as Root Package
    participant Turbo as Turbo
    participant Component as component-library
    participant Playground as playground
    participant Storybook as Storybook

    Dev->>Root: pnpm dev
    Root->>Turbo: Run dev pipeline
    turbo->>Component: Start dev mode
    turbo->>Playground: Start dev mode
    turbo->>Storybook: Start Storybook

    Component-->>Turbo: Dev server ready
    Playground-->>Turbo: Dev server ready
    Storybook-->>Turbo: Storybook ready

    Turbo-->>Dev: All services running

    Note over Dev,Storybook: Developer can now:
    Dev->>Component: Modify components
    Dev->>Playground: Test in playground
    Dev->>Storybook: View component docs
Loading

🚀 Getting Started

Prerequisites

  • Node.js 18+
  • pnpm 9+

Installation

# Clone the repository
git clone <repository-url>
cd origin-art

# Install dependencies
pnpm install

Available Commands

# Development - starts all apps in watch mode
pnpm dev

# Build all packages
pnpm build

# Type checking
pnpm type-check

# Linting
pnpm lint

# Clean all build outputs
pnpm clean

Package-Specific Commands

Token Packages

# Build specific token package
pnpm --filter @origin-art/tokens-core build
pnpm --filter @origin-art/tokens-minimal build
pnpm --filter @origin-art/tokens-rough build

Theme Engine

# Build theme engine
pnpm --filter @origin-art/theme-engine build

Component Library

# Development mode with Storybook
pnpm --filter @origin-art/component-library dev

# Build component library
pnpm --filter @origin-art/component-library build

# Run Storybook
pnpm --filter @origin-art/component-library storybook

Playground App

# Development mode
pnpm --filter @origin-art/playground dev

# Build playground
pnpm --filter @origin-art/playground build

🏃‍♂️ Development Workflow

1. Making Changes to Tokens

flowchart LR
    EditTokens[Edit Token Files] --> BuildCore[Build tokens-core]
    BuildCore --> BuildPackages[Build token packages]
    BuildPackages --> TestTheme[Test in theme engine]
    TestTheme --> TestComponents[Test in components]
    TestComponents --> TestPlayground[Verify in playground]
Loading

2. Adding New Components

flowchart TD
    CreateComponent[Create Component TSX] --> CreateProps[Define Props Interface]
    CreateProps --> CreateStyled[Create Styled Component]
    CreateStyled --> CreateStories[Write Storybook Stories]
    CreateStories --> UpdateExports[Update index.ts exports]
    UpdateExports --> TestStorybook[Test in Storybook]
    TestStorybook --> TestPlayground[Test in Playground]
    TestPlayground --> Build[Build Library]
Loading

3. Adding New Design Systems

flowchart TD
    DefineTokens[Define Token Values] --> CreatePackage[Create tokens package]
    CreatePackage --> ExportTokens[Export tokens object]
    ExportTokens --> UpdateThemeEngine[Update theme engine imports]
    UpdateThemeEngine --> TestSwitcher[Test theme switcher]
    TestSwitcher --> TestComponents[Test with components]
    TestComponents --> UpdateDocs[Update documentation]
Loading

📁 File Structure

origin-art/
├── package.json                 # Root package config
├── pnpm-workspace.yaml         # PNPM workspace config
├── turbo.json                   # Turbo build config
├── tsconfig.base.json          # Base TypeScript config
├── README.md                   # This file
│
├── packages/                   # Shared packages
│   ├── tokens-core/           # Core token types & utilities
│   │   ├── src/
│   │   │   └── index.ts       # Type definitions & factory
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── tokens-minimal/        # Minimal design system tokens
│   │   ├── src/
│   │   │   └── index.ts       # Minimal token definitions
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── tokens-rough/          # Rough design system tokens
│   │   ├── src/
│   │   │   └── index.ts       # Rough token definitions
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── theme-engine/          # Theme management system
│   │   ├── src/
│   │   │   ├── ThemeProvider.tsx    # Main theme provider
│   │   │   ├── ThemeSwitcher.tsx   # Theme switcher component
│   │   │   ├── types.ts           # TypeScript types
│   │   │   └── index.ts           # Public exports
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   ├── ui-primitive/         # ✅ LOW-LEVEL UI BUILDING BLOCKS
│   │   ├── src/
│   │   │   ├── Button.tsx      # ✅ 5 variants, 3 sizes, full theme integration
│   │   │   ├── Button.stories.tsx  # ✅ Complete Storybook docs
│   │   │   └── index.ts      # ✅ Public exports
│   │   ├── package.json        # ✅ Proper exports & dependencies
│   │   └── tsconfig.json      # ✅ TypeScript configuration
│   │
│   └── ui-core/              # ✅ HIGH-LEVEL COMPOSED COMPONENTS
│       ├── src/
│       │   ├── ThemeSwitcher.tsx   # ✅ Re-export from theme-engine
│       │   ├── ThemeSwitcher.stories.tsx  # ✅ Complete Storybook docs
│       │   └── index.ts      # ✅ Re-exports theme engine
│       ├── package.json        # ✅ Proper exports & dependencies
│       └── tsconfig.json      # ✅ TypeScript configuration
│
├── apps/                      # Applications
│   ├── experiment-2d/          # 2D Canvas components (not yet implemented)
│   ├── experiment-3d/          # 3D Graphics components (Not yet implemented)
│   └── playground/           # ✅ Demo application
│       ├── src/
│       │   ├── App.tsx       # ✅ Uses new packages instead of component-library
│       │   └── main.tsx      # Entry point
│       ├── index.html
│       ├── package.json
│       ├── vite.config.ts
│       └── tsconfig.json

🎯 Key Features

Multi-Design System Support

  • Minimal Design System: Clean, modern aesthetic with professional spacing and typography
  • Rough Design System: Hand-drawn, organic aesthetic with playful typography and rough shadows

Theme Switching

  • Light/Dark Modes: Each design system supports both light and dark themes
  • Runtime Switching: Change themes without page reload using CSS custom properties
  • Persistent State: Theme choices are maintained in React context

Component Library

  • Styled Components: Uses styled-components for dynamic theming
  • Token-Driven: All components use design tokens for consistent styling
  • Storybook Documentation: Comprehensive component documentation and examples
  • TypeScript Support: Full type safety for all components and props

Build System

  • Turborepo: Fast, incremental builds with intelligent caching
  • TypeScript: Strict type checking across all packages
  • Modern Tooling: Vite for fast development and optimized builds
  • Package Management: PNPM workspaces for efficient dependency management

🔧 Technical Implementation Details

CSS Custom Properties Strategy

The theme engine uses CSS custom properties (CSS variables) to dynamically apply theme values:

/* Generated by ThemeProvider */
:root {
  /* Colors */
  --color-bg-page: #ffffff;
  --color-fg-primary: #111827;
  --color-accent-default: #3b82f6;

  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;

  /* Typography */
  --font-family-body: "Inter", sans-serif;
  --font-size-base: 16px;
  --font-weight-medium: 500;

  /* Radii */
  --radius-md: 6px;
  --radius-sm: 4px;
}

Token Resolution Pattern

Components access tokens through the theme context:

const StyledButton = styled.button<{ variant: string; size: string }>`
  background: ${(props) => props.theme.tokens.colors["bg/surface"]};
  padding: ${(props) => props.theme.tokens.spacing.md};
  border-radius: ${(props) => props.theme.tokens.radii.md};
  font-family: ${(props) => props.theme.tokens.typography.family.body};
`;

This approach ensures:

  • Runtime Theming: Components automatically adapt to theme changes
  • Type Safety: TypeScript ensures correct token usage
  • Performance: CSS variables are updated efficiently
  • Developer Experience: Autocomplete and error checking for tokens

🚀 Deployment & Usage

Using the Component Library

import {
  ThemeProvider,
  Button,
  ThemeSwitcher,
} from "@origin-art/component-library";

function App() {
  return (
    <ThemeProvider initialDesignSystem="minimal" initialMode="light">
      <div>
        <ThemeSwitcher />
        <Button variant="primary">Click me</Button>
        <Button variant="secondary">Cancel</Button>
      </div>
    </ThemeProvider>
  );
}

Custom Theme Integration

import { useTheme } from "@origin-art/component-library";

function ThemedComponent() {
  const { theme } = useTheme();

  return (
    <div
      style={{
        backgroundColor: `var(--color-bg-surface)`,
        color: `var(--color-fg-primary)`,
        padding: `var(--spacing-md)`,
        borderRadius: `var(--radius-md)`,
      }}
    >
      Themed content
    </div>
  );
}

🤝 Contributing

Development Guidelines

  1. Token First: Always start with token definitions before components
  2. Type Safety: Ensure all new code is fully typed
  3. Storybook Stories: Document all component variations
  4. Theme Testing: Verify components work in all themes
  5. Build Verification: Ensure all builds pass before committing

Adding New Features

  1. New Design System: Create new tokens package and update theme engine
  2. New Component: Follow established patterns with stories and types
  3. New Token Categories: Update core types and all token packages
  4. Enhanced Theming: Extend ThemeProvider with new capabilities

This architecture provides a solid foundation for building scalable, themeable design systems that can adapt to different brand identities while maintaining consistent code patterns and developer experience.

About

Origin art is a melting pot of design systems,2D-3D experiments, and components with configurable themes and design systems.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages