Spaces:
Running
Running
| title: UICopilot | |
| emoji: 🎨 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| license: mit | |
| # UICopilot | |
| **AI UI/UX Engineering Platform** — analyze, score, and improve the visual quality of your application. | |
| UICopilot reviews screenshots, HTML, and CSS, scores interface quality across the dimensions that actually make software look professional, and turns every issue it finds into a prioritized, explainable fix — not just a grade. | |
| > Built for developers who say *"I can build software, but I can't make it look good."* | |
| --- | |
| ## Why UICopilot | |
| Most UI checkers stop at "here's your score." UICopilot is built on a different premise: **the score is not the product — the prioritized action plan is.** | |
| ``` | |
| UI Score: 82/100 | |
| Increase card padding from 12px to 20px (+4 points) | |
| Make table headers 13px uppercase (+3 points) | |
| Standardize primary button styling (+2 points) | |
| ``` | |
| Every issue UICopilot surfaces includes the problem, the evidence, why it matters, the recommended fix, and the expected score impact. No vague suggestions. | |
| ## What It Does | |
| - **Scores your UI** across visual hierarchy, typography, spacing, consistency, accessibility, contrast, and component quality. | |
| - **Detects issues** with severity, confidence, and an estimated point gain for fixing each one. | |
| - **Finds inconsistency** — e.g. six different button styles where there should be one — and tells you how to consolidate. | |
| - **Teaches as it goes**: every recommendation explains *why* it matters, with reference points from products like Stripe, Linear, and Notion. | |
| - **Generates fixes**: CSS variables, design tokens, semantic HTML/ARIA improvements, and a ready-to-paste prompt for Claude Code. | |
| - **Tracks progress over time**, so you can see whether today's changes actually improved your UI. | |
| ## Architecture | |
| ``` | |
| Frontend | |
| ↓ | |
| FastAPI Backend | |
| ↓ | |
| Analysis Engine | |
| ├── Screenshot Analyzer ├── Color Analyzer | |
| ├── HTML Analyzer ├── Dashboard Analyzer | |
| ├── CSS Analyzer ├── Table Analyzer | |
| ├── Component Analyzer ├── Mobile Analyzer | |
| ├── Accessibility Analyzer └── Design System Analyzer | |
| ├── Typography Analyzer | |
| └── Spacing Analyzer | |
| ↓ | |
| Recommendation Engine → Score Engine → Learning Engine → Claude Prompt Generator | |
| ↓ | |
| SQLite (DuckDB planned for analytics & trend history) | |
| ``` | |
| Layered design throughout: API → Services → Analyzers → Rules → Repositories. Analyzers have no UI logic and no direct database access; scoring weights and thresholds are configuration-driven, not hard-coded. | |
| ## Project Structure | |
| ``` | |
| ui-copilot/ | |
| ├── backend/ | |
| │ ├── api/ # FastAPI routes — no business logic here | |
| │ ├── services/ # Orchestration layer | |
| │ ├── analyzers/ # Screenshot / HTML / CSS / component analyzers | |
| │ ├── rules/ # spacing_rules.py, typography_rules.py, contrast_rules.py, ... | |
| │ ├── models/ | |
| │ ├── repositories/ | |
| │ └── utils/ | |
| ├── frontend/ | |
| │ ├── components/ | |
| │ ├── pages/ | |
| │ └── assets/ | |
| ├── tests/ | |
| ├── docs/ # REQUIREMENTS.md, specs/, ADRs | |
| ├── samples/ | |
| ├── reports/ | |
| ├── data/ | |
| ├── config/ # scoring weights, thresholds — not in code | |
| ├── scripts/ | |
| └── requirements.txt | |
| ``` | |
| ## Getting Started | |
| ```bash | |
| # Clone | |
| git clone https://github.com/<your-org>/ui-copilot.git | |
| cd ui-copilot | |
| # Create and activate a virtual environment | |
| python -m venv venv | |
| source venv/bin/activate # Windows: venv\Scripts\activate | |
| # Install dependencies (Python 3.9+) | |
| pip install -r requirements.txt | |
| # Start the server | |
| uvicorn backend.api.main:app --reload | |
| ``` | |
| Then open **http://localhost:8000** — the Developer Dashboard loads automatically. | |
| The API docs are at **http://localhost:8000/docs** (Swagger UI). | |
| ### Running tests | |
| ```bash | |
| python -m pytest tests/ -v | |
| ``` | |
| ### Linting | |
| ```bash | |
| ruff check backend/ tests/ | |
| ``` | |
| ## V1 Modules — Status | |
| | Module | Description | Status | | |
| |--------|-------------|--------| | |
| | 1 | Project Management (SQLite + CRUD) | ✅ Done | | |
| | 2 | Page Analyzer (HTML + CSS parser) | ✅ Done | | |
| | 3 | Screenshot Analysis (CV, no API calls) | ✅ Done | | |
| | 4 | Design System Detection (6 rules) | ✅ Done | | |
| | 5 | Scoring Engine (7 categories, config-driven) | ✅ Done | | |
| | 6 | Issue Detection (severity, confidence, evidence) | ✅ Done | | |
| | 7 | Improvement Roadmap (7 buckets) | ✅ Done | | |
| | 8 | Learning Mode (why + references on every issue) | ✅ Done | | |
| | 9 | Claude Prompt Generator | ✅ Done | | |
| | 10 | CSS Generator | ✅ Done | | |
| | 11 | HTML Improvements (ARIA, semantic, responsive) | ✅ Done | | |
| | 12 | Design Token Generator (colors, spacing, elevation, animation, dark mode) | ✅ Done | | |
| | 13 | Accessibility Review (WCAG A/AA, keyboard/ARIA hints) | ✅ Done | | |
| | 14 | Dashboard Analyzer | ✅ Done | | |
| | 15 | Mobile Analyzer | ✅ Done | | |
| | 16 | Consistency Checker (cross-page divergence) | ✅ Done | | |
| | 17 | UI Trend Analysis (score over time) | ✅ Done | | |
| | 18 | Achievements / Gamification (14 badges) | ✅ Done | | |
| | 22 | Developer Dashboard (workspace UI at `/`) | ✅ Done | | |
| ## API Endpoints | |
| ``` | |
| POST /api/v1/analyze — analyze HTML (+ optional CSS) | |
| POST /api/v1/analyze/screenshot — analyze a screenshot | |
| GET /api/v1/projects — list projects | |
| POST /api/v1/projects — create project | |
| GET /api/v1/projects/{id} — get project | |
| DELETE /api/v1/projects/{id} — delete project | |
| GET /api/v1/projects/{id}/pages — list pages | |
| POST /api/v1/projects/{id}/pages — add page | |
| GET /api/v1/projects/{id}/trend — score-over-time (all pages) | |
| GET /api/v1/projects/{id}/consistency — cross-page consistency report | |
| GET /api/v1/projects/{id}/achievements — badges & gamification | |
| GET /api/v1/pages/{id} — get page | |
| GET /api/v1/pages/{id}/analyses — list analyses | |
| GET /api/v1/pages/{id}/trend — score-over-time (one page) | |
| GET /health — health check | |
| GET /docs — Swagger UI | |
| ``` | |
| ## Roadmap | |
| UICopilot Version 1 covers screenshot, HTML, and CSS analysis with scoring, issue detection, the improvement roadmap, learning mode, and the Claude prompt generator. See [`ROADMAP.md`](./ROADMAP.md) for the full path: GitHub PR integration → browser extension → Figma plugin → VS Code extension → CI/CD quality gates. | |
| Full module breakdown and detailed scope live in [`docs/REQUIREMENTS.md`](./docs/REQUIREMENTS.md), the project's living requirements document. | |
| ## Scoring Model | |
| | Category | Weight | | |
| |---|---| | |
| | Visual Hierarchy | 20% | | |
| | Typography | 15% | | |
| | Spacing | 15% | | |
| | Consistency | 15% | | |
| | Accessibility | 15% | | |
| | Contrast | 10% | | |
| | Component Quality | 10% | | |
| Scores are 0–100, per page, with category-level breakdowns and a trend view across reviews over time. | |
| ## Contributing | |
| See [`CONTRIBUTING.md`](./CONTRIBUTING.md). New analyzers and rules should follow the single-responsibility pattern already used in `backend/rules/` — each rule returns an issue, severity, confidence score, and fix recommendation, and reads its thresholds from `config/`, not from hard-coded values. | |
| ## License | |
| MIT — see [`LICENSE`](./LICENSE). | |