Style Guide Generator

Automatically generate professional style guide PDFs from any website in seconds

Overview

Style Guide Generator is a web application that analyzes any website's design system and generates a comprehensive, professionally formatted style guide PDF. Simply enter a URL, and within seconds you'll have a detailed document covering colors, typography, components, layout, and accessibility standards.

Live Demo: https://styleguidegenerator-production.up.railway.app

Features

One-Click Analysis - Enter any website URL and get instant design system extraction
Comprehensive Extraction - Automatically identifies:
- Color palettes with semantic classification (primary, secondary, accent, text, backgrounds)
- Typography system (font families, sizes, weights, line heights)
- Spacing values and patterns
- Component inventory
- Layout and responsive breakpoints
- Accessibility compliance (WCAG contrast ratios)
Professional PDF Output - Industry-standard style guide format ready for team distribution
Real-Time Progress - Live status updates during website analysis
Smart Color Classification - Automatically categorizes colors by role and usage
WCAG Compliance Checking - Built-in contrast ratio calculations for accessibility

Tech Stack

Frontend

Next.js 16 - React framework with App Router
React 19 - UI library
TypeScript - Type safety
Tailwind CSS v4 - Utility-first styling
shadcn/ui - Accessible component library
TanStack Query - Async state management
Lucide React - Icon library

Backend & Analysis

Playwright - Headless browser for website analysis
@react-pdf/renderer - PDF generation
Zod - Schema validation

Infrastructure

Railway - Cloud deployment platform
Docker - Containerized deployment
Node.js - Runtime environment

Getting Started

Prerequisites

Node.js 20+
npm or yarn

Installation

Clone the repository:

git clone https://github.com/TomsTools11/styleguidegenerator.git
cd styleguidegenerator

Navigate to the app directory:

cd style-guide-app

Install dependencies:

npm install

Install Playwright browsers:

npx playwright install chromium

Start the development server:

npm run dev

Open http://localhost:3000 in your browser

Building for Production

npm run build
npm start

How It Works

Analysis Pipeline

URL Submission - User enters a website URL
Browser Launch - Playwright spawns a headless Chromium instance
Page Loading - Navigates to the URL with smart popup dismissal and lazy-load handling
Style Extraction - Analyzes computed styles from all page elements:
- Colors from backgrounds, text, borders, and CSS variables
- Font families, sizes, weights, and line heights
- Spacing values (margins, paddings, gaps)
Classification - Intelligently categorizes extracted data:
- Colors grouped by semantic role (primary, secondary, accent, text, backgrounds)
- Typography organized into type scales and hierarchies
- Contrast ratios calculated for accessibility compliance
PDF Generation - Creates a professional style guide using industry-standard template structure
Download - User receives downloadable PDF

PDF Structure

Generated style guides follow professional documentation standards:

Cover Page - Website name, URL, generation date
Color Palette - Primary, secondary, accent, text, and background colors with hex/RGB values
Typography - Font families, type scale, weights, and line heights
Spacing System - Margin and padding patterns
Components - UI elements and patterns identified
Layout & Grid - Breakpoints and container widths
Accessibility - WCAG contrast ratios and compliance notes

Project Structure

styleguidegenerator/
├── Dockerfile                    # Production deployment configuration
├── railway.json                  # Railway deployment settings
├── PROGRESS.md                   # Development progress and notes
└── style-guide-app/              # Main Next.js application
    ├── src/
    │   ├── app/
    │   │   ├── page.tsx          # Landing page with URL input
    │   │   ├── processing/       # Analysis progress page
    │   │   │   └── page.tsx
    │   │   ├── results/          # Results display and PDF download
    │   │   │   └── page.tsx
    │   │   └── api/
    │   │       ├── analyze/      # Start analysis job
    │   │       │   └── route.ts
    │   │       ├── status/       # Check job status
    │   │       │   └── [id]/route.ts
    │   │       ├── results/      # Get analysis results
    │   │       │   └── [id]/route.ts
    │   │       └── generate-pdf/ # Generate PDF from results
    │   │           └── route.ts
    │   ├── components/
    │   │   └── ui/               # shadcn/ui components
    │   ├── lib/
    │   │   ├── analyzer.ts       # Website analysis engine (Playwright)
    │   │   ├── job-store.ts      # In-memory job storage
    │   │   ├── utils.ts          # Utility functions
    │   │   └── pdf/
    │   │       ├── StyleGuideDocument.tsx  # PDF template
    │   │       └── styles.ts               # PDF styling
    │   └── types/
    │       └── style-guide.ts    # TypeScript interfaces
    ├── package.json
    └── tsconfig.json

Deployment

Railway Deployment

The app is configured for one-click deployment to Railway:

Fork this repository
Connect to Railway
Select "Deploy from GitHub repo"
Railway will automatically:
- Detect the Dockerfile
- Build the Docker image with Playwright dependencies
- Deploy to a production URL

Docker Deployment

Build and run locally with Docker:

# Build the image
docker build -t style-guide-generator .

# Run the container
docker run -p 3000:3000 style-guide-generator

Environment Variables

Currently, no environment variables are required for basic operation. Future features may require:

REDIS_URL - For persistent job storage
DATABASE_URL - For user accounts and history
ANTHROPIC_API_KEY - For planned creative brief feature

Known Limitations

Current Constraints

In-Memory Job Storage - Jobs are lost on server restart. Recommended to implement Redis or PostgreSQL for production.
No Concurrency Control - Unlimited browser instances can spawn under high load. Implement job queue with concurrency limits.
No Browser Pooling - Each analysis spawns a new Chromium instance (~150-300MB). Consider browser reuse or connection pooling.
Fixed Timeouts - 30-second page load timeout may be too short for slow sites. Make configurable via environment variables.
Limited Error Handling - No retry logic for flaky websites or handling of auth-protected sites.

Recommended Improvements

Add Redis for persistent job storage
Implement job queue with max 2-3 concurrent browser instances
Add browser connection pooling
Implement job cleanup/TTL (prevent memory leaks)
Add environment variable configuration
Enhance error handling with retry logic

See PROGRESS.md for detailed technical notes and improvement roadmap.

Roadmap

Planned Features

User Accounts - Save analysis history and re-download past guides
Creative Brief Generator - Upload screenshots to generate marketing content briefs using Claude Vision AI
Multiple URL Analysis - Analyze multiple pages for comprehensive design system extraction
Custom Templates - Choose from different PDF templates and styles
Export Formats - JSON, Figma tokens, CSS variables
API Access - Programmatic style guide generation for developers
Team Workspaces - Collaborate on style guides
Custom Branding - Add company logo to generated PDFs

Development

Running Tests

npm run lint

Building

npm run build

Local Development Tips

The analyzer uses Playwright's domcontentloaded strategy for faster, more reliable loading
Auto-scrolling triggers lazy-loaded content
Popup dismissal automatically handles cookie banners and modals
Colors are deduplicated and classified by luminance and usage patterns

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the MIT License.

Acknowledgments

Built with Next.js
Website analysis powered by Playwright
PDF generation using @react-pdf/renderer
UI components from shadcn/ui

Support

For issues, questions, or suggestions:

Open an issue on GitHub
Check PROGRESS.md for technical details and development notes

Made with ❤️ by TomsTools11

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
style-guide-app		style-guide-app
.dockerignore		.dockerignore
Dockerfile		Dockerfile
PROGRESS.md		PROGRESS.md
README.md		README.md
docbuildr-logo.svg		docbuildr-logo.svg
example-styleguide.pdf		example-styleguide.pdf
railway.json		railway.json
style-guide-generator-web-app-plan.md		style-guide-generator-web-app-plan.md

TomsTools11/styleguidegenerator

Folders and files

Latest commit

History

Repository files navigation