⚡ Design System Generator (desygen)

desygen is a standardized front-end component and logic context generator designed to dramatically accelerate the development of MVPs, prototypes, and modular design systems.

It automates the creation of visual UI components and establishes a clean logical architecture (light Clean Architecture pattern) that connects your UI with React Contexts, services (API/database layer), and strict TypeScript DTO interfaces.

🚀 Key Features

• Automated UI Generation: A CLI command that parses design.system.json to generate functional React components (such as Button and Input) and their corresponding style sheets.
• Ready-to-Use Logical Architecture: Instantly scaffold React Client Context Providers, service contracts, and typed DTOs (blank or pre-integrated with Firebase) in seconds.
• Integrated Test Suite: Out-of-the-box support for fast automated unit and integration tests powered by Vitest to ensure component and generator health.

📂 Repository Structure

The package is structured cleanly to separate UI generation (visual components and styling) from the logical architecture generation (contexts, services, interfaces):

• generator/:
  • ui/: Generator scripts for visual components (button-generator.js, input-generator.js).
  • logical/: Generator scripts for data layer files (context-generator.js, service-generator.js, interface-generator.js, abstract-generator.js).
• templates/:
  • ui/: Component and style code templates (TSX and Vanilla CSS).
  • logical/: Context, Firebase services, and interface TS templates.

🛠️ Step-by-Step Integration & Usage Guide

Follow these steps to integrate desygen into your target project and generate UI components:

Step 1: Link the Package Locally

Since desygen is currently in local development, you need to use npm link to make the CLI globally available and accessible in your target project:

1. In your terminal, navigate to this package's root directory (dsg-package/) and run:

   npm link

2. Navigate to your target web application's directory (e.g., my-react-app/) and link the package:

   npm link desygen

Step 2: Initialize Configuration

Before generating components, you need a configuration file in your target project root:

1. In your target project directory, run:

   npx desygen create

2. This creates a default design.system.json file containing multi-layout configuration settings for both the Button and Input components (specifying sizes and variants). You can customize these colors, margins, and sizes in the file according to your design system requirements.

Step 3: Run the Generator

To generate components based on the config file:

1. In your target project directory, execute:

   npx desygen generate

2. This parses design.system.json and creates a ./components/ui/ folder inside your project containing:
   • Button.tsx and button.css
   • Input.tsx and input.css

Step 4: Import and Use the Components

You can now import the generated components directly into your application code. They are pre-typed and ready to receive configured sizes and variants:

import Button from "./components/ui/Button";
import Input from "./components/ui/Input";

export default function Home() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "10px", padding: "20px" }}>
      <Input 
        label="Username" 
        placeholder="Enter your username..." 
        size="md" 
      />
      
      <Button variant="primary" size="lg">
        Register
      </Button>
    </div>
  );
}

📖 Available CLI Commands

After linking the package, you can run the following commands in the root of your project:

1. Generating Business Logic & CRUD Contexts

# Generates a blank Context, Service, and DTO interface for a custom entity (e.g., Stock)
npx desygen full-context Stock

# Generates with integrated support for Firebase Firestore
npx desygen full-context User --service=firebase

• What it does: Scaffolds the following architecture inside your ./src/ directory:
  • src/contexts/stock.context.tsx $\rightarrow$ Complete React Client Context Provider with state and loading handling.
  • src/lib/services/stock.service.ts $\rightarrow$ Service class representing backend CRUD operations.
  • src/lib/interfaces/stock.interface.ts $\rightarrow$ Interface definitions (extends AbstractDto).
  • src/lib/utils/abstract.dto.ts $\rightarrow$ Base abstract DTO interface.

📄 Configuration Structure (design.system.json)

The design system configuration dictates the visual and structural properties of the generated components:

{
  "components": {
    "button": {
      "library": "react",
      "style": "vanilla",
      "sizes": {
        "sm": {
          "padding": "0.375rem 0.75rem",
          "fontSize": "0.875rem",
          "borderRadius": "6px"
        },
        "md": {
          "padding": "0.625rem 1.25rem",
          "fontSize": "1rem",
          "borderRadius": "8px"
        },
        "lg": {
          "padding": "0.875rem 1.75rem",
          "fontSize": "1.125rem",
          "borderRadius": "10px"
        }
      },
      "variants": {
        "primary": {
          "backgroundColor": "#10b981",
          "color": "#ffffff"
        },
        "secondary": {
          "backgroundColor": "transparent",
          "color": "#10b981",
          "borderColor": "#10b981"
        },
        "ghost": {
          "backgroundColor": "transparent",
          "color": "#6b7280"
        }
      }
    },
    "input": {
      "library": "react",
      "style": "vanilla",
      "sizes": {
        "sm": {
          "padding": "0.375rem 0.75rem",
          "fontSize": "0.875rem",
          "borderRadius": "6px"
        },
        "md": {
          "padding": "0.625rem 1rem",
          "fontSize": "1rem",
          "borderRadius": "8px"
        },
        "lg": {
          "padding": "0.875rem 1.25rem",
          "fontSize": "1.125rem",
          "borderRadius": "10px"
        }
      }
    }
  }
}

🧪 Running Automated Tests

The package includes unit and integration tests using Vitest (leveraging mock filesystem and string helpers). To run the test suite:

npm run test

🗺️ Roadmap & Next Steps

We have mapped the implementation priorities for 39 components (including modals, accordions, navigations, form fields, and chart modules). Refer to the full roadmap at ROADMAP.md for more details.

🎨 Design References & Guidelines

For the visual design foundations and accessibility guidelines of our generated components, we recommend referring to:

• Design System Guideline: Material Design 3 (M3)
• Base Components: M3 Components
• Icon Design: M3 Designing Icons
• Color Contrast Accessibility: Who Can Use
• Typography & Font Scaling: M3 Text Resizing Guide