CSS Refiner

A browser-based CSS analysis and optimization tool. Paste (or drag-and-drop) a CSS file and run one or more analyzers to detect redundancies, normalize colors, merge duplicates, and more.

Try it online — no install needed.

Features

• Empty Rules — Detects and removes selectors with no declarations
• Color Normalization — Converts colors to a consistent format (hex, rgb, hsl)
• Duplicate Detection — Finds identical declaration blocks across selectors
• Media Query Merging — Consolidates duplicate @media blocks
• Fuzzy Value Matching — Spots near-identical numeric values (e.g. 14px vs 15px)
• Near-Duplicate Analysis — Detects selectors that share most declarations
• Design Tokens — Extracts repeated values as CSS custom property candidates

Workflow

• Single textarea — edits are applied in-place via the Apply button
• Auto-Refine loops the safe analyzers (empty rules, color normalize, duplicates, media queries) until the CSS stabilizes
• Drag-and-drop .css files directly onto the textarea
• Download or copy the result at any point
• Light / dark theme toggle
• English / French interface (i18n via PHP + JSON)

Requirements

• PHP 7.4+ (used only for i18n bootstrapping)
• A web server (Apache, Nginx, Caddy…) with PHP support
• No database, no Composer dependencies, no build step

Installation

1. Clone the repository

git clone https://github.com/Sangiovanni/CSS-refiner.git

2. (Optional) Run the setup script

If you want to rename folders or nest the app under a URL prefix, run the interactive setup script:

# Linux / macOS
chmod +x setup.sh
./setup.sh

# Windows
setup.bat

The setup script lets you:

1. Rename public/ to match your vhost (e.g. www, public_html)
2. Rename secure/ for obscurity (e.g. backend, engine)
3. Set a URL space to serve the app from a subdirectory (e.g. tools/css → http://domain/tools/css/)

All three constants in init.php are updated automatically. You can re-run the script at any time.

If you don't need any of this, skip straight to step 3.

3. Configure a virtual host

The web server's document root must point to the public folder (or whatever you renamed it to). The secure folder sits outside the document root and is never accessible via HTTP — this is intentional.

css-refiner/
  public/               ← document root points HERE
    index.php
    init.php
    assets/
  secure/               ← outside document root (not web-accessible)
    cssrafiner/
      src/
      translate/

Apache example (vhost)

<VirtualHost *:80>
    ServerName cssrefiner.local
    DocumentRoot "/path/to/css-refiner/public"

    <Directory "/path/to/css-refiner/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx example

server {
    listen 80;
    server_name cssrefiner.local;
    root /path/to/css-refiner/public;
    index index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

4. Add a hosts entry (local development)

127.0.0.1  cssrefiner.local

5. Open in browser

http://cssrefiner.local/

That's it — no build step, no dependencies to install.

Hosting on an existing website

Use the setup script (step 2) or manually set the PUBLIC_FOLDER_SPACE constant in public/init.php. This nests the app under a subdirectory so it doesn't conflict with your existing site:

your-existing-site/
  public/               ← your existing document root
    index.html          ← your homepage
    tools/              ← CSS Refiner lives here, isolated
      index.php
      assets/

For example, set PUBLIC_FOLDER_SPACE to 'tools' and move the app files into public/tools/. The setup script handles this automatically.

Project structure

public/
  index.php                  — Entry point, HTML template
  init.php                   — Path constants, bootstrap
  assets/
    css/style.css            — All styles (light + dark theme)
    js/
      app.js                 — Main orchestration (events, pipeline, apply)
      constants.js           — Tool identifiers, config values
      css-parser.js          — Character-by-character CSS parser
      i18n.js                — Client-side translation helper
      utils.js               — Shared utilities
      analyzers/
        color-normalize.js   — Color format normalization
        design-tokens.js     — Repeated value extraction
        duplicates.js        — Identical block detection
        empty-rules.js       — Empty selector removal
        fuzzy-values.js      — Near-identical value matching
        media-queries.js     — @media block consolidation
        near-duplicates.js   — Similar selector detection
      ui/
        components.js        — Reusable UI components
        diff-view.js         — Before/after diff rendering
        results-panel.js     — Suggestion list and controls

secure/cssrafiner/
  src/Translator.php         — PHP i18n class
  translate/
    en.json                  — English translations
    fr.json                  — French translations

How this project was built

This project was built entirely through AI-assisted development using GitHub Copilot (Claude). The human provided architecture rules, feature direction, code review, and bug reports. The AI generated all implementation code.

See DEVELOPMENT.md for the full narrative of the development process.

Support

If you find this useful:

License

MIT — see LICENSE for details.