emily-css 1.0.0 → 1.0.2

package/README.md

@@ -1,107 +1,159 @@
-# emily-ui
+# EmilyUI
 
-A config-driven, utility-first CSS framework for developers in constrained environments. Define brand once (colours, fonts, spacing) → generate CSS → browse and copy production-ready components.
+A config-driven utility CSS framework. Define your brand once, generate the CSS.
+
+**EmilyUI** is the ecosystem name. `emily-css` is the utility layer published on npm — it's both the package you install and the CLI you use to generate and purge CSS. More packages coming.
 
 ## Features
 
-- **Config-driven** — Entire framework configured via `emily.config.json`
-- **Utility-first** — 11,844 composable utilities covering layout, spacing, typography, colours, responsive variants, state variants
-- **Responsive ready** — All utilities work with responsive prefixes (sm:, md:, lg:, xl:, 2xl:)
-- **State variants** — hover, focus-visible, active, disabled states built-in
-- **Accessibility first** — WCAG 2.2 AA compliance in core utilities (focus rings, contrast, motion)
-- **Purge system** — Remove unused CSS automatically (97% file size reduction)
-- **Framework-agnostic** — Works with Drupal, static HTML, Power Pages, Vue, Next.js, anything that accepts CSS
-- **No build pipeline required** — Generate CSS, use it directly in your project
+- **Works anywhere** - Generate static CSS and drop it into any project, no build pipeline required.
+- **Config-driven** - Entire framework configured via `emily.config.json`
+- **Utility-first** - Composable utilities for layout, spacing, typography and colour
+- **Responsive ready** - All utilities work with responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
+- **State variants** - `hover:`, `focus-visible:`, `active:`, `disabled:` built-in
+- **Accessibility first** - WCAG 2.2 AA compliance in core utilities (focus rings, contrast, motion)
+- **Purge system** - Remove unused CSS automatically for production
 
 ## Quick Start
 
 ### 1. Install
+
 ```bash
-npm install emily-ui
-emily-ui init
+npm install emily-css
 ```
 
-The `init` command guides you through:
+### 2. Create your config
+
+```bash
+npx emily-css init
+```
+
+This walks you through:
+
 - Project name
 - Brand colours (primary, secondary, success, warning, error, neutral)
 - Font families
 - Base spacing unit
+- Source directory (used by the purge command)
+
+It then generates `emily.config.json` and runs your first build automatically.
+
+### 3. Link the CSS in your project
+
+```html
+<link rel="stylesheet" href="./dist/emily.css">
+```
+
+### 4. Use the utility classes
+
+```html
+<button class="px-4 py-2 rounded-md bg-primary-80 text-white hover:bg-primary-90 focus-visible:ring-2 focus-visible:ring-primary-50">
+  Button
+</button>
+```
+
+Colours, spacing and typography all come from your config.
+
+### 5. Purge unused CSS for production
 
-### 2. Build CSS
 ```bash
-emily-ui build
+npx emily-css purge
 ```
 
+Scans your template files, keeps only the utilities you actually use.
+
 Output:
-- `dist/emily.css` — Full CSS (1.1 MB)
-- `dist/emily.min.css` — Minified (1.04 MB)
+- `dist/emily.purged.css` - Purged CSS
+- `dist/emily.purged.min.css` - Minified version
+
+Use the purged file in production:
+
+```html
+<link rel="stylesheet" href="./dist/emily.purged.min.css">
+```
+
+## Commands
 
-### 2b. Run Tests (Optional)
 ```bash
-npm test
+npx emily-css init     # Create emily.config.json and run first build
+npx emily-css build    # Regenerate CSS after config changes
+npx emily-css purge    # Remove unused utilities for production
+npm test              # Run test suite (if working on EmilyUI itself)
 ```
-*(Run from inside the emily-ui project folder)*
 
-Automated validation of colour generation, utilities, variants, config integrity, and build output (66 tests, all passing). Tests confirm the generator works correctly; manual testing of real-world usage is still recommended before deploying to production.
+## How Purge Works
 
-### 3. Use Components
-Open `showcase.html` in your browser to see 8 production components (button, input, textarea, select, checkbox, radio, card, alert). Copy the HTML, paste into your project.
+EmilyUI scans your template files for class names and removes any utilities you are not using.
 
-### 4. Reduce File Size (Recommended for Production)
-```bash
-emily-ui build --purge ./src
+For example:
+
+```html
+<div class="p-4 bg-primary-80 rounded-lg">Content</div>
 ```
 
-Scans your HTML/templates for used classes, removes unused utilities. Typical reduction: 99%+ (1.1 MB → 10–50 KB).
+EmilyUI keeps `.p-4`, `.bg-primary-80`, `.rounded-lg` and removes everything else.
 
-Output:
-- `dist/emily.purged.css` — Only utilities you use
-- `dist/emily.purged.min.css` — Minified version
+Supported file types: `.html`, `.twig`, `.njk`, `.liquid`, `.hbs`, `.jsx`, `.tsx`, `.vue`, `.php`, `.astro`, `.svelte`, `.blade.php` (configurable via `extensions` in `emily.config.json`)
+
+**Note:** Class names must exist as plain text in your files. Dynamically constructed class names will not be detected:
+
+```js
+// This will be missed by purge:
+const colour = 'primary-80'
+const cls = `bg-${colour}`
+
+// This will be detected:
+const cls = 'bg-primary-80'
+```
 
-## File Size Comparison
+If you use dynamic classes, either keep them as plain strings or manually safelist them in your config.
 
-Emily uses a purge-based approach (generate all utilities, then remove unused). Unpurged file size: ~1.1 MB.
+## File Size
 
-For context:
-- **Tailwind v2** (purge-based): 2.4–8MB unpurged → <10KB purged
-- **Emily v1** (purge-based): 1.1MB unpurged → 10–50KB purged
-- **Tailwind v3/v4** (JIT): Generates only what you use, no purge step needed
+EmilyUI uses a purge-based approach (generate all utilities, then remove unused).
 
-Emily's unpurged file is roughly half the size of Tailwind v2. For production, both frameworks achieve similar post-purge sizes. JIT-style on-demand generation is planned for Emily v2.
+| | Unpurged | Purged |
+|---|---|---|
+| Tailwind v2 | 2.4-8MB | under 10KB |
+| EmilyUI v1 | 1.1MB | 10-50KB |
+| Tailwind v3/v4 (JIT) | generates on demand | - |
+
+EmilyUI's unpurged file is roughly half the size of Tailwind v2. Post-purge sizes are comparable. JIT-style generation is planned for v2.
 
 ## File Structure
 
 ```
-emily-ui/
+emily-css/
   ├── src/
-  │   ├── index.js          — Main build script
-  │   ├── generators.js     — Utility generation functions
-  │   ├── purge.js          — CSS purge system
-  │   └── init.js           — Interactive config generator
+  │   ├── index.js          - Main build script
+  │   ├── generators.js     - Utility generation functions
+  │   ├── purge.js          - Purge system
+  │   ├── purge-cmd.js      - Purge CLI command
+  │   └── init.js           - Interactive setup
   ├── dist/
-  │   ├── emily.css         — Generated CSS
-  │   ├── emily.min.css     — Minified CSS
-  │   ├── emily.purged.css  — Purged CSS (with --purge flag)
+  │   ├── emily.css         - Generated CSS
+  │   ├── emily.min.css     - Minified CSS
+  │   ├── emily.purged.css  - Purged CSS
   │   └── emily.purged.min.css
-  ├── showcase.html         — Component browser
-  ├── emily.config.json     — Framework configuration
+  ├── showcase.html         - Example components
+  ├── emily.config.json     - Your config
   ├── package.json
   └── README.md
 ```
 
 ## Configuration
 
-Edit `emily.config.json` to customize:
+Edit `emily.config.json` to customise:
 
 ```json
 {
   "name": "My Brand",
   "description": "Design system",
-  
+
   "baseUnit": "8px",
   "baseFontSize": "16px",
   "fontFamily": "system-ui",
-  
+
   "colours": {
     "primary": "#0077b6",
     "secondary": "#006d9e",
@@ -110,7 +162,7 @@ Edit `emily.config.json` to customize:
     "error": "#b20000",
     "neutral": "#6b7280"
   },
-  
+
   "breakpoints": {
     "sm": "640px",
     "md": "768px",
@@ -118,55 +170,43 @@ Edit `emily.config.json` to customize:
     "xl": "1280px",
     "2xl": "1536px"
   },
-  
-  "spacing": {
-    "scale": { "0": "0px", "1": "0.25rem", ... },
-    "borderRadius": { "sm": "4px", "base": "8px", "lg": "16px", ... }
-  },
-  
-  "typography": {
-    "fontWeights": { "light": 300, "normal": 400, ... },
-    "fontSizes": [ { "name": "sm", "value": "14px" }, ... ]
-  },
-  
-  "shadows": { ... },
-  "transitions": { ... },
-  "zIndex": { ... },
-  "opacity": [ ... ],
-  
+
   "purge": {
-    "extensions": [".html", ".jsx", ".tsx", ".vue", ...]
+    "sourceDir": "./src",
+    "extensions": [".html", ".jsx", ".tsx", ".vue"]
   }
 }
 ```
 
 After editing, rebuild:
+
 ```bash
-emily-ui build
+npx emily-css build
 ```
 
 ## Utilities
 
-Emily generates utilities across these categories:
-
-- **Display** — block, inline, flex, grid, hidden
-- **Spacing** — margin (m-), padding (p-), gap (gap-)
-- **Sizing** — width (w-), height (h-), max-width, min-height
-- **Positioning** — absolute, relative, fixed, sticky, top, right, bottom, left
-- **Flexbox** — flex, flex-direction, justify-content, align-items, flex-wrap
-- **Grid** — grid, grid-cols, grid-rows, grid-gap
-- **Colours** — background (bg-), text, borders, accent for form controls
-- **Typography** — font-size, font-weight, line-height, text-align
-- **Borders** — border-width, border-style, border-colour, border-radius
-- **Shadows** — box-shadow, text-shadow
-- **Opacity** — opacity levels
-- **Accessibility** — sr-only, focus-visible, motion-safe, forced-colors
-- **State variants** — hover:, focus-visible:, active:, disabled:
-- **Responsive variants** — sm:, md:, lg:, xl:, 2xl:
+EmilyUI generates utilities across these categories:
+
+- **Display** - block, inline, flex, grid, hidden
+- **Spacing** - margin (`m-`), padding (`p-`), gap (`gap-`)
+- **Sizing** - width (`w-`), height (`h-`), max-width, min-height
+- **Positioning** - absolute, relative, fixed, sticky, top, right, bottom, left
+- **Flexbox** - flex, flex-direction, justify-content, align-items, flex-wrap
+- **Grid** - grid, grid-cols, grid-rows, grid-gap
+- **Colours** - background (`bg-`), text, borders, accent for form controls
+- **Typography** - font-size, font-weight, line-height, text-align
+- **Borders** - border-width, border-style, border-colour, border-radius
+- **Shadows** - box-shadow, text-shadow
+- **Opacity** - opacity levels
+- **Accessibility** - sr-only, focus-visible, motion-safe, forced-colors
+- **State variants** - `hover:`, `focus-visible:`, `active:`, `disabled:`
+- **Responsive variants** - `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
 
 ## Examples
 
 ### Button
+
 ```html
 <button class="px-4 py-2 rounded-md bg-primary-80 text-white hover:bg-primary-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-50">
   Click me
@@ -174,6 +214,7 @@ Emily generates utilities across these categories:
 ```
 
 ### Responsive Card
+
 ```html
 <div class="w-full md:w-96 p-4 md:p-6 rounded-lg bg-neutral-10 border-1 border-neutral-30 shadow-md">
   <h2 class="text-lg font-semibold text-neutral-90">Title</h2>
@@ -182,11 +223,12 @@ Emily generates utilities across these categories:
 ```
 
 ### Accessible Form Input
+
 ```html
 <label for="email" class="block text-sm font-medium text-neutral-80">
   Email
 </label>
-<input 
+<input
   id="email"
   type="email"
   class="mt-1 w-full px-3 py-2 border-1 border-neutral-40 rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-50"
@@ -197,52 +239,50 @@ Emily generates utilities across these categories:
 
 All utilities are built with WCAG 2.2 AA in mind:
 
-- **Focus rings** — Focus-visible states include proper colour contrast
-- **Colour contrast** — All colour scales meet AA contrast ratios
-- **Motion** — `motion-safe` and `motion-reduce` utilities for users with vestibular disorders
-- **Semantic HTML** — Components use proper heading hierarchy and form labels
-- **Screen reader support** — `.sr-only` utility for screen-reader-only content
-- **Forced colours** — Utilities respect Windows High Contrast mode
+- **Focus rings** - Focus-visible states include proper colour contrast
+- **Colour contrast** - All colour scales meet AA contrast ratios
+- **Motion** - `motion-safe` and `motion-reduce` utilities for users with vestibular disorders
+- **Screen reader support** - `.sr-only` utility for screen-reader-only content
+- **Forced colours** - Utilities respect Windows High Contrast mode
 
-## Known Limitations
+## Testing
 
-These are post-v1 priorities:
-- Arbitrary values (`w-[123px]`) — deferred to v2
-- Extend system for custom utilities — deferred to v2
-- Pattern utilities (Wrapper, Flow, Stack) — deferred to v2
-- Watch mode / HMR — deferred to v2
-- Pre-built component tier — deferred to v2
+```bash
+npm test
+```
+
+66 automated tests covering colour generation, utilities, variants, config integrity, and build output. All passing.
 
 ## Troubleshooting
 
 ### Styles not applying?
-1. Check that responsive prefix is correct: `.md\:flex` not `.md:flex`
-2. Verify class name spelling in HTML
-3. Clear browser cache and rebuild CSS
+
+1. Check the responsive prefix: `.md\:flex` not `.md:flex`
+2. Verify class name spelling
+3. Clear browser cache and rebuild: `npx emily-css build`
 
 ### File size too large?
-Use the purge system:
+
 ```bash
-emily-ui build --purge ./src
+npx emily-css purge
 ```
 
 ### Config not applying?
+
 1. Edit `emily.config.json`
-2. Run `npm run build` to regenerate CSS
-3. No cache invalidation needed (CSS is regenerated from scratch)
+2. Run `npx emily-css build`
+3. No cache invalidation needed
 
 ## CDN
 
-Use emily-ui directly without npm via jsDelivr:
-
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/emily-ui/dist/emily.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/emily-css/dist/emily.css">
 ```
 
 ## Support
 
-Open an issue or start a discussion on GitHub:
-https://github.com/andyjterry/emily-ui
+- Website: https://www.emilyui.com
+- GitHub: https://github.com/andyjterry/emily-ui
 
 ## License
 

package/bin/emilyui.js

@@ -6,12 +6,15 @@ if (command === "init") {
   require("../src/init.js");
 } else if (command === "build") {
   require("../src/index.js");
+} else if (command === "purge") {
+  require("../src/purge-cmd.js");
 } else {
   console.log(`
-emily-ui — Config-driven CSS framework generator
+emily-css - Config-driven CSS framework generator
 
 Usage:
-  emily-ui init     Set up a new project
-  emily-ui build    Generate emily.css from your existing config
+  emily-css init     Set up a new project
+  emily-css build    Generate emily.css from your config
+  emily-css purge    Remove unused utilities for production
 `);
-}
+}

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "emily-css",
-  "version": "1.0.0",
-  "description": "Config-driven, utility-first CSS framework. Define brand colours once, generate 11,000+ utilities, browse and copy production-ready components.",
+  "version": "1.0.2",
+  "description": "A config-driven utility CSS framework. Define your brand once, generate the CSS.",
   "main": "src/index.js",
   "bin": {
-    "emily-ui": "./bin/emilyui.js"
+    "emily-css": "./bin/emilyui.js"
   },
   "files": [
     "bin/",
     "src/",
-    "dist/",
+    "dist/emily.css",
+    "dist/emily.min.css",
+    "dist/emily.demo.css",
+    "dist/emily.demo.min.css",
     "fonts/",
     "README.md",
     "LICENSE"

package/src/index.js

@@ -777,7 +777,7 @@ function addStateVariants(css) {
 function build(options = {}) {
   const configPath = path.join(process.cwd(), 'emily.config.json');
   if (!fs.existsSync(configPath)) {
-    console.error(`\n  emily-ui: No config found.\n  Expected: ${configPath}\n  Run "emily-ui init" to create one.\n`);
+    console.error(`\n  emily-css: No config found.\n  Expected: ${configPath}\n  Run "emily-css init" to create one.\n`);
     process.exit(1);
   }
   const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -786,7 +786,7 @@ function build(options = {}) {
     const { purgeCSS } = require('./purge.js');
     const cssPath = path.join(process.cwd(), 'dist/emily.css');
     if (!fs.existsSync(cssPath)) {
-      console.error('  emily-ui: Run emily-ui build first before purging.');
+      console.error('  emily-css: Run "emily-css build" first.');
       process.exit(1);
     }
     console.log(`Purging unused utilities from ${options.purge}...`);

package/src/init.js

@@ -23,16 +23,16 @@ function isValidHex(hex) {
 
 // Default colours
 const defaultColours = {
-  primary: '#0077b6',
-  secondary: '#006d9e',
+  primary: '#DB2777',
+  secondary: '#2563EB',
   success: '#017F65',
   warning: '#ffc107',
   error: '#b20000',
-  neutral: '#6b7280'
+  neutral: '#57534E'
 };
 
 // Default config template - matches emily.config.json structure
-function createDefaultConfig(name, colours, fonts, baseUnit) {
+function createDefaultConfig(name, colours, fonts, baseUnit, sourceDir) {
   return {
     name,
     description: `${name} design system`,
@@ -206,10 +206,15 @@ async function init() {
       }
     }
 
-    // 5. Create config
-    const config = createDefaultConfig(name, colours, fonts, baseUnit);
+    // 5. Source directory for purge
+    console.log('\nSource directory for purge (where your templates/HTML live):');
+    let sourceDir = await prompt('  Source directory [./src]: ');
+    sourceDir = sourceDir.trim() || './src';
 
-    // 6. Write config file to the user's project directory
+    // 6. Create config
+    const config = createDefaultConfig(name, colours, fonts, baseUnit, sourceDir);
+
+    // 7. Write config file to the user's project directory
     const configPath = path.join(process.cwd(), 'emily.config.json');
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 
@@ -219,13 +224,13 @@ async function init() {
     console.log(`   Base unit: ${baseUnit}px`);
     console.log(`\n📝 Config saved: ${configPath}`);
 
-    // 7. Run build
+    // 8. Run build
     console.log('\n🔨 Building CSS...\n');
     rl.close();
 
     // Spawn build process
     const { spawn } = require('child_process');
-    const build = spawn('npx', ['emily-ui', 'build'], {
+    const build = spawn('npx', ['emily-css', 'build'], {
       cwd: process.cwd(),
       stdio: 'inherit'
     });
@@ -237,7 +242,7 @@ async function init() {
         console.log('   1. Open showcase.html in your browser to see components');
         console.log('   2. Copy component code into your project');
         console.log('   3. Update emily.config.json to customize colours/fonts');
-        console.log('   4. Run: npm run build -- --purge ./src (to reduce CSS size)');
+        console.log('   4. Run: emily-css purge (to remove unused CSS for production)');
       } else {
         console.log('\n❌ Build failed');
       }

package/src/purge-cmd.js

@@ -0,0 +1,55 @@
+const fs = require('fs');
+const path = require('path');
+
+function runPurge() {
+  const configPath = path.join(process.cwd(), 'emily.config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error('\n  emily-css: No config found. Run "emily-css init" first.\n');
+    process.exit(1);
+  }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const sourceDir = config.purge && config.purge.sourceDir;
+
+  if (!sourceDir) {
+    console.error('\n  emily-css: No purge sourceDir in emily.config.json.');
+    console.error('  Add: "purge": { "sourceDir": "./src" }\n');
+    process.exit(1);
+  }
+
+  const cssPath = path.join(process.cwd(), 'dist/emily.css');
+
+  if (!fs.existsSync(cssPath)) {
+    console.error('\n  emily-css: No CSS found. Run "emily-css build" first.\n');
+    process.exit(1);
+  }
+
+  const { purgeCSS } = require('./purge.js');
+
+  console.log('\nPurging unused utilities from ' + sourceDir + '...');
+
+  const css = fs.readFileSync(cssPath, 'utf8');
+  const purged = purgeCSS(css, sourceDir);
+  const minified = purged
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s?\{/g, '{')
+    .replace(/\s?\}/g, '}')
+    .replace(/;\s/g, ';')
+    .trim();
+
+  fs.writeFileSync(path.join(process.cwd(), 'dist/emily.purged.css'), purged);
+  fs.writeFileSync(path.join(process.cwd(), 'dist/emily.purged.min.css'), minified);
+
+  const original = Buffer.byteLength(css, 'utf8');
+  const purgedSize = Buffer.byteLength(purged, 'utf8');
+  const reduction = Math.round((1 - purgedSize / original) * 100);
+
+  console.log('\n\u2713 Purged CSS written:');
+  console.log('  dist/emily.purged.css');
+  console.log('  dist/emily.purged.min.css');
+  console.log('\n  ' + Math.round(original / 1024) + 'KB -> ' + Math.round(purgedSize / 1024) + 'KB (' + reduction + '% reduction)\n');
+}
+
+runPurge();