Skip to content

Commit 287cbc4

Browse files
buffosbuffos
committed
docs: finalize v0.1.0 release and detailed architecture
- Expand README.md with project goals, tech stack, and modular architecture - Add Mermaid diagrams for Global Architecture and Plugin Reactivity Flow - Document the mount-time subscription pattern and inner workings of the state-compile loop - Add step-by-step guide for creating new plugins - Bump version to 0.1.0 in package.json - Finalize roadmap status in task modules
1 parent bf5ce26 commit 287cbc4

2 files changed

Lines changed: 139 additions & 30 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,138 @@
1-
# UI Theme Generator (WIP)
2-
3-
Single-page, framework-free Vite + TypeScript app that lets users build a theme configuration JSON, live-preview it in an iframe, and generate/download CSS bundles in-browser.
4-
5-
## Status
6-
- Tooling set up (ESLint + Prettier).
7-
- App implementation not started; Vite scaffold still present.
8-
9-
## Tech Stack
10-
- Vite + TypeScript (no UI framework)
11-
- ESLint with `@typescript-eslint`, `eslint-plugin-import`
12-
- Prettier for formatting
13-
14-
## Scripts
15-
- `npm run dev` – start dev server
16-
- `npm run build` – type-check then build
17-
- `npm run preview` – preview production build
18-
- `npm run lint` / `npm run lint:fix` – lint (optionally fix)
19-
- `npm run format` – format with Prettier
20-
21-
## Goals (MVP)
22-
- Theme controls (colors, typography, spacing, radius, shadow)
23-
- Live preview in iframe
24-
- Compile `theme.config.json` → CSS (`tokens`, `utilities`, `components`, `index`)
25-
- Export JSON and zipped CSS bundle
26-
27-
## Contributing Notes
28-
- One-file-at-a-time steps for clarity.
29-
- Track every change in `CHANGELOG.md`.
1+
# CSS Theme Builder v0.1.0
2+
3+
A high-performance, plugin-based engine for generating modern design systems. This tool allows designers and developers to build, audit, and export CSS design tokens and utility classes through a visual interface.
4+
5+
## 🎯 Goal
6+
7+
The goal of this project is to bridge the gap between design variables and production CSS. It provides a "live" environment where design foundations (colors, typography, spacing, etc.) can be tailored per theme persona and instantly exported as a clean, standardized CSS system.
8+
9+
## 🚀 Tech Stack
10+
11+
- **Engine**: Pure TypeScript (zero-framework core)
12+
- **Bundler**: [Vite](https://vitejs.dev/)
13+
- **Styling**: Modern Vanilla CSS with CSS Variables (Custom Properties)
14+
- **Diagrams**: Mermaid.js
15+
16+
### Available Scripts
17+
18+
- `npm install`: Install dependencies.
19+
- `npm run dev`: Start the interactive design environment.
20+
- `npm run build`: Compile the application for production.
21+
- `npm run preview`: Preview the production build locally.
22+
23+
---
24+
25+
## 🏗️ Global Architecture
26+
27+
The application follows a reactive "Single Source of Truth" architecture. When the central `ThemeConfig` changes, the system orchestrates an immediate re-compilation and UI update.
28+
29+
```mermaid
30+
graph TD
31+
subgraph "Core State (state.ts)"
32+
Config[ThemeConfig State]
33+
Listeners[Listeners Set]
34+
end
35+
36+
subgraph "Plugin System"
37+
P_Entry[Compiler Entry]
38+
P_UI[Control Module]
39+
P_Prev[Preview Module]
40+
end
41+
42+
subgraph "Application Entry (main.ts)"
43+
Compiler[Compiler Engine]
44+
UI_Host[UI Sidebar Host]
45+
Preview_Host[Preview Canvas Host]
46+
end
47+
48+
%% Initialization Phase
49+
Preview_Host -.->|subscribe| Config
50+
UI_Host -->|loop mount| P_UI
51+
P_UI -.->|subscribe| Config
52+
53+
%% Update Phase
54+
P_UI -->|updateConfig| Config
55+
Config -->|notify| Listeners
56+
Listeners -->|trigger| Compiler
57+
Listeners -->|trigger| P_UI
58+
Listeners -->|trigger| Preview_Host
59+
60+
Compiler -->|Inject| DOM[Live CSS Variables]
61+
```
62+
63+
---
64+
65+
## 🔌 Plugin Architecture
66+
67+
The system is entirely modular. Every feature is a self-contained plugin.
68+
69+
### Plugin Contracts
70+
71+
- **Compiler Entry**: Transforms the configuration segment into CSS tokens (`--var`), utilities (`.u-name`), and components.
72+
- **Control Module**: Mounts standard HTML controls into the sidebar for interactive editing.
73+
- **Preview Module**: Renders a dedicated "Spec" or "Gallery" in the main canvas to demonstrate the tokens in action.
74+
75+
### The Reactive Loop (Inner Workings)
76+
77+
1. **Mounting**: During `main.ts` initialization, every plugin's `mount(container, api)` is called.
78+
2. **Subscription**: Inside `mount`, most plugins call `api.subscribe(sync)`. This registers a local `sync` function in the global State.
79+
3. **Interaction**: When a user moves a slider, the plugin calls `api.updateConfig()`.
80+
4. **Notification**: The State updates the shared object and immediately iterates through all registered listeners.
81+
5. **Synchronization**:
82+
- The **Compiler** (via the Preview Engine) re-runs, generating new CSS.
83+
- All **Control Modules** run their `sync` functions to ensure their inputs match the new global state (crucial for Undo/Redo/Presets).
84+
85+
```mermaid
86+
sequenceDiagram
87+
participant User
88+
participant PluginUI as Control Module
89+
participant State as state.ts
90+
participant Compiler as compile.ts
91+
participant DOM as Document
92+
93+
Note over PluginUI, State: Initialization
94+
PluginUI->>State: api.subscribe(syncFn)
95+
96+
Note over User, DOM: The Reactive Cycle
97+
User->>PluginUI: Interaction (Slider/Input)
98+
PluginUI->>State: api.updateConfig(mutator)
99+
State->>State: Update central Object
100+
State-->>PluginUI: notify (calls syncFn)
101+
State-->>Compiler: notify (triggers compile)
102+
Compiler->>DOM: Inject Fresh <style>
103+
DOM-->>User: Visual Update
104+
```
105+
106+
---
107+
108+
## 🛠️ How to Create a Plugin
109+
110+
1. **Define the Data**: Extend the `ThemeModules` interface in `src/compiler/types.ts` using TypeScript module augmentation to add your plugin's configuration shape.
111+
2. **Create Plugin Logic**: Create a new folder in `src/plugins/basic-[your-feature]`.
112+
3. **Implement Compiler Entry**: Create an object with `emitTokens` and `emitUtilities` functions.
113+
4. **Build UI Controls**: Implement the `ControlModule` interface, creating a `mount` function that generates the necessary inputs and syncs them with `api.updateConfig`.
114+
5. **Develop Preview**: Implement the `PreviewModule` to show a visual specification or interactive demo of your feature.
115+
6. **Register**:
116+
- Add to `src/compiler/registry.ts`
117+
- Add to `src/app/ui.ts`
118+
- Add to `src/app/preview-registry.ts`
119+
120+
---
121+
122+
## ✨ Current Functionality
123+
124+
### Foundations
125+
126+
- **🎨 Color System**: High-precision scale generation (50-950) with Analogous, Complementary, and Manual palette modes.
127+
- **✍️ Typography**: Standardized font scales with fluid line-height foundations.
128+
- **📏 Spacing & Radius**: Unit-based spacing system and semantic rounding tokens.
129+
- **🌑 Shadows**: Multi-layered elevation shadows with granular opacity and blur controls.
130+
- **🥞 Z-Index**: Global stacking order management (`--z-index-*`) for layer-perfect layouts.
131+
- **📐 Iconography**: Standardized icon sizing and stroke-weight foundations.
132+
133+
### Auditing & Handoff
134+
135+
- **♿ Accessibility Audit**: Scans all semantic color pairs for WCAG contrast compliance with one-click "Nudge Fix" capabilities.
136+
- **📋 Style Guide**: A consolidated technical specification of every token in the system.
137+
- **🖱️ Click-to-Copy**: Every token in the Style Guide can be copied as a CSS variable with a single click.
138+
- **📁 Presets**: Pre-configured theme personas (Aurora, Midnight, Cyberpunk, etc.) for instant starting points.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "css-theme-builder",
33
"private": true,
4-
"version": "0.0.0",
4+
"version": "0.1.0",
55
"type": "module",
66
"scripts": {
77
"dev": "vite",

0 commit comments

Comments
 (0)