emily-css 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,82 +1,140 @@
-# Changelog
-
-All notable changes to `emily-css` are documented here.
-
----
-## v1.2.0-alpha.0 — May 2026
-
-### Added
-- Report-only Tailwind-to-EmilyCSS migration command: `emily-css migrate`.
-- Default semantic migration mode for design-token aligned suggestions.
-- Imported palette mode via `emily-css migrate --import-colours` for visual parity mapping suggestions.
-- Detection and reporting for arbitrary value utilities during migration analysis.
-
-### Notes
-- Migration in this alpha is analysis-only: no source files are modified by `migrate`.
-
----
-## v1.1.0 — May 2026
-
-### Added
-- Added `emily-css doctor`, a manifest-powered project checker that scans configured source files and reports unknown EmilyCSS classes with suggestions.
-- Added variant-aware class validation for responsive, state, ARIA, data-state, motion, dark, and forced-colours variants.
-
+# Changelog
+
+All notable changes to `emily-css` are documented here.
+
 ---
 
-## v1.2.1 — May 2026
-
-**updated the full system to be more efficient**
+## v1.2.2 — May 2026
 
 ### Added
-- updated the full system to be more efficient
+- Added IntelliSense JSON generation via `intellisense` config output (`dist/emily.intellisense.json` by default).
+- Added build profiling via `emily-css build --profile` with coarse timing buckets.
+- Added initial accessibility warnings to `emily-css doctor` (focus removal, same token text/background, and `cursor-pointer` on non-interactive elements).
+- Added documentation stubs in `docs/` for installation, configuration, variants, accessibility, doctor, migrate, manifest, and IntelliSense.
 
 ### Changed
-- updated release logic
-
----
-## v1.1.1 — May 2026
-
-**updated changes and added**
-
-### Added
-- updted changes
-
----
-## v1.1.0 — May 2026
-
-**add utility manifest generation): chore: release v1.1.0**
-
-### Added
-- add utility manifest generation): chore: release v1.1.0
+- Stabilised manifest schema metadata with explicit `schemaVersion`, package name, and package version fields.
+- Improved purge class extraction for complex variant patterns and safer junk filtering.
+- Updated README to reflect current product direction and command surface.
 
----
-## v1.0.29 — May 2026
-
-**added json manifest for future use**
-
-### Added
-- added json manifest for future use
-
----
-## v1.0.28 — May 2026
-
-**added new utilities**
-
-### Changed
-- added new utilties and tests
+### Notes
+- EmilyCSS remains CommonJS-compatible and continues to support Node 16+.
+- ESM-only dependency major upgrades remain intentionally deferred for compatibility.
 
 ---
-## v1.0.27 — May 2026
-
-**colour system redesign — brand/accent tokens + semantic colours (v1.0.23)**
 
-### Added
-- colour system redesign — brand/accent tokens + semantic colours (v1.0.23)
-
-### Changed
-- updated utilties and new showcase
-
----
+## v1.2.1 — May 2026
+
+### Changed
+- Refactored utility generators into smaller internal modules.
+- Kept `src/generators.js` as a compatibility shim so existing imports continue to work.
+- Moved shared defaults into `src/constants.js`.
+- Updated watch mode so configured purge ignore rules are respected consistently.
+- Improved release hardening and package output checks.
+
+### Fixed
+- Kept dependency versions on CommonJS-compatible majors to support Node 16+.
+- Avoided ESM-only dependency upgrades that would break the current CommonJS CLI.
+
+### Dependency compatibility
+EmilyCSS intentionally stays on CommonJS-compatible dependency majors for now:
+
+- `chalk@4`
+- `ora@5`
+- `boxen@5`
+- `chokidar@4`
+
+Newer major versions are ESM-focused and may require newer Node versions. EmilyCSS currently supports Node 16+ and CommonJS.
+
+---
+
+## v1.2.0-alpha.0 — May 2026
+
+### Added
+- Report-only Tailwind-to-EmilyCSS migration command: `emily-css migrate`.
+- Default semantic migration mode for design-token aligned suggestions.
+- Imported palette mode via `emily-css migrate --import-colours` for visual parity mapping suggestions.
+- Detection and reporting for arbitrary value utilities during migration analysis.
+
+### Notes
+- Migration in this alpha is analysis-only. No source files are modified by `migrate`.
+
+---
+
+## v1.1.1 — May 2026
+
+### Added
+- Utility manifest generation for future tooling, doctor checks, migration support, and editor integrations.
+
+---
+
+## v1.1.0 — May 2026
+
+### Added
+- Added `emily-css doctor`, a manifest-powered project checker that scans configured source files and reports unknown EmilyCSS classes with suggestions.
+- Added variant-aware class validation for responsive, state, ARIA, data-state, motion, dark, and forced-colours variants.
+
+---
+
+## v1.2.1 — May 2026
+
+**Refactor utility generators into modules**
+
+---
+## v1.2.1 — May 2026
+
+**updated the full system to be more efficient**
+
+### Added
+- updated the full system to be more efficient
+
+### Changed
+- updated release logic
+
+---
+## v1.1.1 — May 2026
+
+**updated changes and added**
+
+### Added
+- updted changes
+
+---
+## v1.1.0 — May 2026
+
+**add utility manifest generation): chore: release v1.1.0**
+
+### Added
+- add utility manifest generation): chore: release v1.1.0
+
+---
+## v1.0.29 — May 2026
+
+**added json manifest for future use**
+
+### Added
+- added json manifest for future use
+
+---
+## v1.0.28 — May 2026
+
+**added new utilities**
+
+### Changed
+- added new utilties and tests
+
+---
+## v1.0.27 — May 2026
+
+**colour system redesign — brand/accent tokens + semantic colours (v1.0.23)**
+
+### Added
+- colour system redesign — brand/accent tokens + semantic colours (v1.0.23)
+
+### Changed
+- updated utilties and new showcase
+
+---
 # Changelog
 
 All notable changes to `emily-css` are documented here.

package/README.md

@@ -1,158 +1,107 @@
 # emilyCSS
 
-**A config-driven design system generator for developers working in constrained or legacy environments.**
+Token-first, framework-agnostic CSS generation for teams that want predictable utilities without adopting a full app framework.
 
-Define your brand in one JSON file and generate a production-ready, accessibility-first stylesheet in seconds.
+## What emilyCSS is
 
-## The Mental Model
+emilyCSS lets you define design tokens in `emily.config.json` and generate static CSS you can use anywhere: HTML, Drupal, WordPress, Power Pages, React, Vue, and other environments.
 
-emilyCSS is built for real-world systems like **Drupal, Power Pages, WordPress, static HTML**, and other environments where modern build pipelines often don't exist.
+## Why teams use it
 
-1. **Configure** — Define your brand colours, fonts, and spacing in `emily.config.json`
-2. **Generate** — Run one command to produce a clean, optimized CSS file
-3. **Deploy** — Link the stylesheet and copy production-ready components from the showcase
+- Token-first utility generation from your own colours, spacing, typography, and motion settings
+- Framework-agnostic output (`dist/emily.css` and `dist/emily.min.css`)
+- Accessibility-focused utility coverage (focus rings, visually-hidden helpers, motion-aware variants)
+- Tooling support with manifest and IntelliSense JSON generation
+- CommonJS package with Node 16+ compatibility
 
-## Quick Start
-
-### 1. Initialize
+## Install and basic workflow
 
 ```bash
+npm install emily-css
 npx emily-css init
+npx emily-css build
+npx emily-css watch
 ```
 
-This creates your `emily.config.json`, walks you through your brand settings (colours, fonts, spacing, etc.), and runs your first build.
-
-### 2. Link the CSS
+Link production CSS in your project:
 
 ```html
 <link rel="stylesheet" href="./dist/emily.min.css">
 ```
 
-### 3. Start Building
-
-Use the generated utilities and browse the showcase for ready-to-copy components.
-
-```bash
-npx emily-css build     # Rebuild after config changes
-npx emily-css watch     # Watch mode for development
-```
-
-## Core Features
-
-- **Token-Driven Colours** — One hex per colour → balanced 10-shade scale using OKLCH
-- **Predictable Spacing** — Everything scales from your baseUnit
-- **Accessibility First** — Focus-visible rings, motion utilities, WCAG 2.2 AA colours
-- **No Build Pipeline Required** — Just a static CSS file
-- **Smart Purge** — Remove unused utilities for tiny production files
-- **UI Starter Kit** — Copy-paste accessible components from showcase.html
-
-## Commands
+## Core commands
 
 ```bash
-npx emily-css init     # Setup config + first build
-npx emily-css build    # Regenerate CSS
-npx emily-css watch    # Development watch mode
-npx emily-css purge    # Remove unused styles for production
-npx emily-css migrate  # Report-only Tailwind-to-EmilyCSS migration analysis
-  --import-colours     # Imported palette mode (visual parity class suggestions)
+npx emily-css init
+npx emily-css build
+npx emily-css build --profile
+npx emily-css watch
+npx emily-css doctor
+npx emily-css migrate
+npx emily-css migrate --import-colours
+npx emily-css showcase
+npx emily-css help
+npx emily-css version
 ```
 
-## Migration (1.2.0-alpha)
-
-- `emily-css migrate` is report-only and does not modify files.
-- Default migration mode is semantic (`gray/slate/zinc/stone` remap toward `neutral` naming).
-- `emily-css migrate --import-colours` enables imported palette mode for parity-oriented palette suggestions.
-- Arbitrary value utilities (for example `w-[37px]`, `bg-[#0f172a]`) are detected and reported as unsupported.
+## Doctor and migrate
 
-## How Purge Works
+- `doctor` checks for unknown EmilyCSS classes and variants.
+- `doctor` now also reports non-failing accessibility warnings (for example obvious focus-removal or same-token text/background patterns).
+- `migrate` is report-only and helps plan Tailwind-to-Emily migrations without modifying files.
 
-emilyCSS scans your templates for used class names and removes everything else.
+## Manifest and IntelliSense JSON
 
-Supported files: `.html`, `.php`, `.twig`, `.liquid`, `.jsx`, `.vue`, `.astro`, etc. (configurable).
+Enable machine-readable outputs when needed:
 
-**Important:** Dynamically constructed classes like `bg-${colour}` are not detected. Use static strings or add them to the safelist.
+```json
+{
+  "manifest": true,
+  "intellisense": {
+    "enabled": true,
+    "output": "dist/emily.intellisense.json"
+  }
+}
+```
 
-## File Size (Typical)
+Generated files:
 
-| State | Size |
-|-------|------|
-| Full build | ~1.1 MB |
-| After purge | 10–50 KB |
+- `dist/emily.manifest.json`
+- `dist/emily.intellisense.json`
 
-## Configuration
+These files are intended for tooling, audits, and editor integrations. A VSCode extension is not required for generation.
 
-Edit `emily.config.json`:
+## Minimal configuration example
 
 ```json
 {
   "name": "My Brand",
-  "baseUnit": "8px",
   "fontFamily": {
-    "heading": "lexend",
+    "heading": "atkinson",
     "body": "inter"
   },
   "colours": {
-    "brand": "#2563EB",
-    "accent": "#2563EB",
-    "btn-primary": "#2563EB",
-    "btn-secondary": "#2563EB",
-    "neutral": "#57534E"
+    "brand": "#0077B6",
+    "accent": "#0EA5E9",
+    "neutral": "#57534E",
+    "success": "#0F766E",
+    "error": "#B91C1C"
   },
-  "semanticColours": {
-    "dark": "#1A1A1A",
-    "light": "#FAFAFA"
-  },
-  "purge": {
-    "content": ["./**/*.{html,php,jsx,tsx,vue}"]
-  }
+  "manifest": true,
+  "intellisense": true
 }
 ```
 
-After changes: `npx emily-css build`
-
-## Component Showcase
-
-After your first build, open `showcase.html` in your browser. It contains production-ready, accessible components (buttons, forms, alerts, cards, etc.) built with your brand.
-
-## EmilyUI vs emilyCSS
-
-- **EmilyUI** — The broader brand / ecosystem
-- **emilyCSS** — The current product (the emily-css npm package + CLI)
-
-## Example Components
-
-### Button
-
-```html
-<button class="px-6 py-3 rounded-lg bg-brand-80 text-white hover:bg-brand-90 focus-visible:ring-2 focus-visible:ring-brand-50 font-medium">
-  Submit
-</button>
-```
-
-### Responsive Card
-
-```html
-<div class="w-full md:w-96 p-6 rounded-xl bg-white border border-neutral-20 shadow-sm">
-  <h2 class="text-2xl font-semibold text-neutral-90">Card Title</h2>
-  <p class="mt-3 text-neutral-70">Content goes here.</p>
-</div>
-```
-
-## Fonts
-
-emilyCSS applies font stacks but does not include font files. Recommended approach:
-
-```bash
-npm install @fontsource/inter @fontsource/lexend
-```
+## Notes on compatibility
 
-Then import the weights you need.
+- Package format: CommonJS
+- Runtime support: Node 16+
+- ESM-only major upgrades are intentionally avoided where they would break compatibility
 
-## Support
+## Documentation stubs
 
-- **Website:** https://www.emilyui.com
-- **GitHub:** https://github.com/andyjterry/emily-ui
+Starter docs are available in [`docs/`](./docs) for installation, configuration, variants, accessibility, doctor, migrate, manifest, and IntelliSense.
 
 ## License
 
-MIT
+MIT

package/bin/emilyui.js

@@ -10,6 +10,7 @@ const usageText = `
   Usage:
     emily-css init        Set up a new project
     emily-css build       Generate production CSS to the configured output path
+      --profile           Print coarse build timing information
     emily-css watch       Dev mode: rebuild on changes
     emily-css doctor      Scan project files for unknown EmilyCSS classes
     emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report
@@ -24,7 +25,10 @@ if (command === "init") {
   require("../src/init.js");
 } else if (command === "build") {
   const { build } = require("../src/index.js");
-  build({ keepFull: process.argv.includes("--keep-full") });
+  build({
+    keepFull: process.argv.includes("--keep-full"),
+    profile: process.argv.includes("--profile"),
+  });
 } else if (command === "watch") {
   require("../src/watch.js");
 } else if (command === "showcase") {
@@ -48,6 +52,7 @@ if (command === "init") {
   Commands:
     emily-css init        Set up a new project (interactive wizard)
     emily-css build       Generate production CSS to the configured output path
+      --profile           Print coarse build timing information
     emily-css watch       Dev mode: watch for changes and rebuild
     emily-css doctor      Scan project files for unknown EmilyCSS classes
     emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emily-css",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A config-driven utility CSS framework. Define your brand once, generate the CSS.",
   "main": "src/index.js",
   "bin": {
@@ -45,12 +45,12 @@
     "node": ">=16.0.0"
   },
   "devDependencies": {
-    "nodemon": "^3.0.0"
+    "nodemon": "^3.1.14"
   },
   "dependencies": {
     "boxen": "^5.1.2",
     "chalk": "^4.1.2",
-    "chokidar": "^5.0.0",
+    "chokidar": "^4.0.3",
     "cross-spawn": "^7.0.6",
     "enquirer": "^2.4.1",
     "fast-glob": "^3.3.3",

package/src/doctor.js

@@ -185,6 +185,102 @@ function loadManifest(config, css) {
   return generateManifest(css, config);
 }
 
+const INTERACTIVE_TAGS = new Set([
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "option",
+]);
+
+const VISIBLE_FOCUS_CLASSES = new Set([
+  "focus-ring",
+  "focus-visible:ring-2",
+  "outline",
+  "outline-2",
+]);
+const KNOWN_CLASS_SHIMS = new Set(["focus-ring-none"]);
+
+function parseElementClassLists(content) {
+  const entries = [];
+  const classAttrRegex =
+    /<([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*?\b(?:class|className)\s*=\s*(["'])([\s\S]*?)\2[^>]*?>/g;
+  let match;
+
+  while ((match = classAttrRegex.exec(content)) !== null) {
+    const tagName = match[1].toLowerCase();
+    const classes = match[3]
+      .split(/\s+/)
+      .map((cls) => cls.trim())
+      .filter(Boolean);
+
+    entries.push({ tagName, classes });
+  }
+
+  return entries;
+}
+
+function hasVisibleFocusReplacement(classes) {
+  return classes.some((className) => VISIBLE_FOCUS_CLASSES.has(className));
+}
+
+function extractColourToken(className, prefix) {
+  const match = className.match(new RegExp(`^${prefix}([a-z][a-z0-9-]*-\\d{1,3})$`));
+  return match ? match[1] : null;
+}
+
+function createAccessibilityWarnings(filePath, content) {
+  const warnings = [];
+  const classEntries = parseElementClassLists(content);
+
+  classEntries.forEach(({ tagName, classes }) => {
+    if (classes.includes("focus-ring-none") && !hasVisibleFocusReplacement(classes)) {
+      warnings.push({
+        file: filePath,
+        reason: "focus-removal",
+        className: "focus-ring-none",
+        message:
+          'focus-ring-none removes visible focus styles without a replacement focus class.',
+      });
+    }
+
+    const bgTokens = new Set();
+    const textTokens = new Set();
+
+    classes.forEach((className) => {
+      const bgToken = extractColourToken(className, "bg-");
+      const textToken = extractColourToken(className, "text-");
+
+      if (bgToken) bgTokens.add(bgToken);
+      if (textToken) textTokens.add(textToken);
+    });
+
+    bgTokens.forEach((token) => {
+      if (textTokens.has(token)) {
+        warnings.push({
+          file: filePath,
+          reason: "same-text-background-colour",
+          className: `bg-${token} text-${token}`,
+          message: `Text and background both use token "${token}", which is likely unreadable.`,
+        });
+      }
+    });
+
+    if (classes.includes("cursor-pointer") && !INTERACTIVE_TAGS.has(tagName)) {
+      warnings.push({
+        file: filePath,
+        reason: "cursor-pointer-non-interactive",
+        className: "cursor-pointer",
+        message: `cursor-pointer is applied to non-interactive <${tagName}>.`,
+      });
+    }
+  });
+
+  return warnings;
+}
+
 function doctor() {
   const config = getConfig();
 
@@ -208,6 +304,7 @@ function doctor() {
 
   const files = getFilesToScan(config);
   const issues = [];
+  const warnings = [];
   const suggestionCache = new Map();
 
   files.forEach((filePath) => {
@@ -218,7 +315,8 @@ function doctor() {
       classes.forEach((className) => {
         const parsed = normaliseClassForManifest(className);
         const unknownVariants = parsed.variants.filter((variant) => !variantSet.has(variant));
-        const knownBase = utilitySet.has(parsed.baseClass);
+        const knownBase =
+          utilitySet.has(parsed.baseClass) || KNOWN_CLASS_SHIMS.has(parsed.baseClass);
 
         if (unknownVariants.length === 0 && knownBase) {
           return;
@@ -236,14 +334,31 @@ function doctor() {
           suggestion: suggestionCache.get(className),
         });
       });
+
+      warnings.push(...createAccessibilityWarnings(filePath, content));
     } catch (error) {
       // Keep parity with purge behaviour: unreadable files are skipped.
     }
   });
 
-  if (issues.length === 0) {
+  if (issues.length === 0 && warnings.length === 0) {
     console.log("✓ EmilyCSS doctor found no class issues");
-    return { ok: true, issues: [], exitCode: 0 };
+    return { ok: true, issues: [], warnings: [], exitCode: 0 };
+  }
+
+  if (warnings.length > 0) {
+    console.log(
+      `EmilyCSS doctor warning${warnings.length === 1 ? "" : "s"} (${warnings.length})\n`,
+    );
+    warnings.forEach((warning) => {
+      console.log(path.relative(process.cwd(), warning.file));
+      console.log(`  Warning: ${warning.message}`);
+      console.log("");
+    });
+  }
+
+  if (issues.length === 0) {
+    return { ok: true, issues: [], warnings, exitCode: 0 };
   }
 
   console.log(`EmilyCSS doctor found ${issues.length} issue${issues.length === 1 ? "" : "s"}\n`);
@@ -262,7 +377,7 @@ function doctor() {
   });
 
   console.log("Run `emily-css build` after fixing classes.");
-  return { ok: false, issues, exitCode: 1 };
+  return { ok: false, issues, warnings, exitCode: 1 };
 }
 
 module.exports = {

package/src/generators/accessibility.js

@@ -0,0 +1,40 @@
+'use strict'
+
+function accessibilityUtilities() {
+  return `/* Accessibility */
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border-width: 0; }
+.not-sr-only { position: static; width: auto; height: auto; padding: 0; margin: 0; overflow: visible; clip: auto; white-space: normal; }
+.sr-only-focusable:not(:focus):not(:focus-within) { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border-width: 0; }
+.focus-ring:focus-visible { outline: 2px solid var(--color-brand-80); outline-offset: 2px; }
+.focus-ring-inset:focus-visible { outline: 2px solid var(--color-brand-80); outline-offset: -2px; }
+.focus-ring-none:focus-visible { outline: none; }
+.focus-visible:focus { outline: 2px solid currentColor; outline-offset: 2px; }
+.focus\\:outline-none:focus { outline: 2px solid transparent; outline-offset: 2px; }
+
+/* Touch target — WCAG 2.2 SC 2.5.8 minimum 24x24px hit area */
+.touch-target { position: relative; }
+.touch-target::before { content: ''; position: absolute; top: 50%; left: 50%; width: max(100%, 24px); height: max(100%, 24px); transform: translate(-50%, -50%); }
+
+/* Skip link — reveals on focus for keyboard/AT users */
+.skip-link { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border-width: 0; }
+.skip-link:focus { position: fixed; top: 1rem; left: 1rem; z-index: 1070; width: auto; height: auto; padding: 0.75rem 1.25rem; background-color: #ffffff; color: #000000; font-weight: 700; text-decoration: underline; border: 2px solid currentColor; border-radius: 4px; clip: auto; white-space: normal; }
+
+@media (prefers-reduced-motion: reduce) {
+  .motion-reduce\\:transition-none { transition-property: none; }
+  .motion-reduce\\:animate-none { animation: none; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  .motion-safe\\:transition { transition-property: color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter; transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); transition-duration: 150ms; }
+}
+@media (forced-colors: active) {
+  .forced-colors\\:outline { outline: 1px solid CanvasText; }
+  .forced-colors\\:outline-1 { outline: 1px solid CanvasText; }
+  .forced-colors\\:forced-color-adjust-none { forced-color-adjust: none; }
+}
+
+`;
+}
+
+module.exports = {
+  accessibilityUtilities,
+};