How paumen/css-promptify works
Project type and purpose
• This is an open-source, browser-based CSS review tool (“CSS Promptify”) with an accompanying LLM context/spec pack.
• It ships as a single-page application (SPA) built with React + TypeScript + Vite, and implements a CSS parser + rule-engine entirely in the client.
• The repo also contains a comprehensive “spec” directory (source of truth for rules and product documentation), CI workflows, example generators, and test artifacts.
File structure
• Top-level directories:
• app/ → the SPA implementation
• spec/ → product requirement docs & rulebook
• scripts/ → codegen scripts (e.g. generate examples)
• tests/ → validation reports + sample CSS
• .github/ → CI: linting and type-checking workflows
• Inside app/:
• src/parser → CSS parser module (AST generation)
• src/engine → rule engine runner & orchestrator
• src/rules → individual rule definitions (format, style, safety, tokens, modern, education, consolidation)
• src/state → session-only settings and data store
• src/ui → React components & panels (Input, Issues, Output, Settings, primitives)
• Build/config: Vite (vite.config.ts), tsconfig, ESLint, package.json.
README for additional insights
• The spec (in spec/PRD_BUILD_SPEC.md) is the source of truth for feature requirements and the rulebook.
• No backend or external service calls are implemented: all rule evaluation happens client-side.
• LLM integration consists of a “prompt export” feature—not an API call—from within the UI.
a. Main components
• Browser SPA Container
• UI Layer
– InputPanel (user pastes CSS)
– SettingsPanel (rule toggles)
– IssuesPanel (error/warning/info display)
– OutputPanel (cleaned CSS & fix comments, prompt export)
• Application Core
– State Manager (holds CSS text, settings, engine results)
– Parser Module (CSS → AST)
– Rule Engine
· Rule Dispatcher
· Rule Modules (format, style, safety, modern, tokens, education, consolidation)
• Spec & Context Pack (non-runtime docs)
• CI Pipeline (GitHub Actions for lint/typecheck)
b. Relationships / Data Flow
1. User CSS input → State
2. State triggers Parser → AST
3. AST + Settings → Rule Engine → Diagnostics & Fix Suggestions
4. Engine Output → State → UI Panels render issues & output
5. Prompt Export reads Engine Output + Spec Rules → text for LLM
c. Architectural patterns / principles
– Modular rule plugins: each rule is self-contained and registered via an index.
– Unidirectional data flow: input → parser → engine → UI render.
– Client-only architecture: no server, session-only state.
– Separation of concerns: parser, engine, rules, UI, and docs each in their own directory.
d. Key technologies
• React + TypeScript + Vite
• CSS Modules for styling components
• ESLint + Prettier for code quality
• GitHub Actions (super-linter, typecheck)
• Node.js scripts for codegen (scripts/generate-examples-md.js)
Essential elements
• In-browser state store as the single source of truth for UI and engine.
• Local codegen script and spec directory to illustrate documentation is part of system health.
• Document the CI workflows as a separate “DevOps” lane to show how quality gates are applied.