emily-css 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `emily-css` are documented here.
 
 ---
 
+## v1.2.6 — May 2026
+
+**Fix migration scanner false positives by ignoring prose tokens, JS property access, and dynamic placeholders while keeping valid utility classes and arbitrary value support.**
+
+### Fixed
+- fix: tighten migration class filtering
+
+---
+## v1.2.5 — May 2026
+
+**Node 18+ Compatibility and Docs/CLI Alignment**
+
+### Fixed
+- fix(release): align Node support, CLI scripts, and README with current behavior
+
+---
+## v1.3.0 -- May 2026
+
+### Added
+- **ARIA state variants**: Added `aria-checked:` variant prefix, generating CSS rules targeting `[aria-checked="true"]`. Completes the ARIA variant set alongside `aria-expanded`, `aria-selected`, `aria-current`, and `aria-disabled`.
+- **Data-state variants**: Added `data-checked:`, `data-unchecked:`, `data-active:`, and `data-inactive:` variant prefixes targeting `[data-state="*"]` selectors. Used by Radix UI, Headless UI, and similar headless component libraries. Completes the data-state set alongside `data-open:` and `data-closed:`.
+- **`emily-css info` command**: New CLI command. Shows a project overview without triggering a build -- version, framework detection, output paths, CSS file sizes, source globs, file count, colour/spacing/font summary.
+- **Doctor contrast warnings**: `emily-css doctor` now checks configured brand colour shades against standard light and dark backgrounds using the WCAG relative luminance formula. Flags shade/background pairings below 4.5:1 contrast. Non-blocking (warning, not error).
+
+### Changed
+- `BASE_VARIANTS` in `src/constants.js` updated to include the five new variant names so `doctor` and `manifest` recognise them.
+
+---
+
 ## v1.2.4 — May 2026
 
 **chore: release v1.2.4**
@@ -426,9 +455,4 @@ All notable changes to `emily-css` are documented here.
 - 11,844 utility classes generated from `emily.config.json`
 - OKLCH colour scale generation — one hex in, 10-shade scale out
 - Responsive variants (`sm:` `md:` `lg:` `xl:` `2xl:`)
-- State variants (`hover:` `focus-visible:` `active:` `disabled:` `dark:`)
-- Purge system — strips unused classes, ~97% file size reduction
-- Interactive setup wizard (`npx emily-css init`)
-- 72 tests, all passing
-
----
+- State variants (`hover:` `focus-visible:` `active:` `disab

package/README.md

@@ -12,7 +12,7 @@ emilyCSS lets you define design tokens in `emily.config.json` and generate stati
 - 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 22+ compatibility
+- CommonJS package with Node 18+ compatibility
 
 ## Install and basic workflow
 
@@ -36,19 +36,36 @@ npx emily-css init
 npx emily-css build
 npx emily-css build --profile
 npx emily-css watch
+npx emily-css info
 npx emily-css doctor
 npx emily-css migrate
 npx emily-css migrate --import-colours
+npx emily-css manifest
 npx emily-css showcase
 npx emily-css help
 npx emily-css version
 ```
 
+Equivalent npm scripts (when added by `emily-css init`):
+
+```bash
+npm run emily:build
+npm run emily:watch
+npm run emily:doctor
+npm run emily:migrate
+npm run emily:info
+npm run emily:manifest
+npm run emily:showcase
+npm run emily:version
+npm run emily:help
+```
+
 ## Doctor and migrate
 
 - `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.
+- For best migrate accuracy, generate the full framework/manifest first (`emily-css build --keep-full` or enable `manifest: true`).
 
 ## Manifest and IntelliSense JSON
 
@@ -95,13 +112,9 @@ These files are intended for tooling, audits, and editor integrations. A VSCode
 ## Notes on compatibility
 
 - Package format: CommonJS
-- Runtime support: Node 22+
+- Runtime support: Node 18+
 - ESM-only major upgrades are intentionally avoided where they would break compatibility
 
-## Documentation stubs
-
-Starter docs are available in [`docs/`](./docs) for installation, configuration, variants, accessibility, doctor, migrate, manifest, and IntelliSense.
-
 ## License
 
 MIT

package/bin/emilyui.js

@@ -13,6 +13,7 @@ const usageText = `
     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 info        Show project config and CSS stats
     emily-css doctor      Scan project files for unknown EmilyCSS classes
     emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report
       --import-colours    Detect Tailwind colour palettes and suggest importedPalettes config
@@ -35,6 +36,9 @@ if (command === "init") {
   require("../src/watch.js");
 } else if (command === "showcase") {
   require("../src/showcase.js");
+} else if (command === "info") {
+  const { info } = require("../src/info.js");
+  info();
 } else if (command === "doctor") {
   const { doctor } = require("../src/doctor.js");
   const result = doctor();
@@ -69,6 +73,7 @@ if (command === "init") {
     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 info        Show project config, output paths, and CSS stats
     emily-css doctor      Scan project files for unknown EmilyCSS classes
     emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report
       --import-colours    Detect Tailwind colour palettes and suggest importedPalettes config
@@ -80,7 +85,12 @@ if (command === "init") {
   npm scripts (added by init):
     npm run emily:build      Same as emily-css build
     npm run emily:watch      Same as emily-css watch
+    npm run emily:doctor     Same as emily-css doctor
+    npm run emily:migrate    Same as emily-css migrate
+    npm run emily:info       Same as emily-css info
+    npm run emily:manifest   Same as emily-css manifest
     npm run emily:showcase   Same as emily-css showcase
+    npm run emily:version    Same as emily-css version
     npm run emily:help       Same as emily-css help
   
   Docs: https://emilyui.dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emily-css",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "A config-driven utility CSS framework. Define your brand once, generate the CSS.",
   "main": "src/index.js",
   "bin": {
@@ -26,6 +26,11 @@
     "ship": "node scripts/ship.js",
     "emily:build": "emily-css build",
     "emily:watch": "emily-css watch",
+    "emily:doctor": "emily-css doctor",
+    "emily:migrate": "emily-css migrate",
+    "emily:info": "emily-css info",
+    "emily:manifest": "emily-css manifest",
+    "emily:version": "emily-css version",
     "emily:help": "emily-css help"
   },
   "keywords": [
@@ -42,7 +47,7 @@
   "author": "Andy Terry",
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=18.0.0"
   },
   "devDependencies": {
     "nodemon": "^3.1.14"

package/src/constants.js

@@ -46,10 +46,15 @@ const BASE_VARIANTS = [
   'motion-safe',
   'aria-expanded',
   'aria-selected',
+  'aria-checked',
   'aria-current',
   'aria-disabled',
   'data-open',
   'data-closed',
+  'data-checked',
+  'data-unchecked',
+  'data-active',
+  'data-inactive',
   'dark',
   'forced-colors',
 ];

package/src/doctor.js

@@ -4,8 +4,9 @@ const fs = require("fs");
 const path = require("path");
 const fg = require("fast-glob");
 const { extractClassNames } = require("./purge.js");
-const { ensureFullFramework, generateManifest } = require("./index.js");
+const { ensureFullFramework, generateManifest, generateColourScale } = require("./index.js");
 const { DEFAULT_EXTENSIONS } = require("./constants.js");
+const { resolvePurgeConfig } = require("./purgeConfig.js");
 const {
   getConfig,
   getFullCssPath,
@@ -111,18 +112,20 @@ function suggestClassName(className, utilitySet, variantSet) {
 }
 
 function getFilesToScan(config) {
-  const extensions = config?.purge?.extensions || DEFAULT_EXTENSIONS;
-  const ignore = config?.purge?.ignore || [];
+  const resolvedPurgeConfig = resolvePurgeConfig(config);
+  const extensions = resolvedPurgeConfig.extensions || DEFAULT_EXTENSIONS;
+  const ignore = resolvedPurgeConfig.ignore || [];
+  const sourceGlobs = resolvedPurgeConfig.sourceGlobs || [];
 
-  if (config?.purge?.sourceGlobs && config.purge.sourceGlobs.length > 0) {
-    return fg.sync(config.purge.sourceGlobs, {
+  if (sourceGlobs.length > 0) {
+    return fg.sync(sourceGlobs, {
       ignore,
       onlyFiles: true,
       unique: true,
     });
   }
 
-  const sourceDir = config?.purge?.sourceDir || ".";
+  const sourceDir = resolvedPurgeConfig.sourceDir || ".";
   const scanDir = path.isAbsolute(sourceDir)
     ? sourceDir
     : path.join(process.cwd(), sourceDir);
@@ -244,6 +247,79 @@ function createAccessibilityWarnings(filePath, content) {
   return warnings;
 }
 
+// ─── Colour contrast helpers ──────────────────────────────────────────────────
+
+function hexToRelativeLuminance(hex) {
+  const toLinear = (c) => {
+    const v = parseInt(c, 16) / 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  const r = toLinear(hex.slice(1, 3));
+  const g = toLinear(hex.slice(3, 5));
+  const b = toLinear(hex.slice(5, 7));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrastRatio(hexA, hexB) {
+  const lA = hexToRelativeLuminance(hexA);
+  const lB = hexToRelativeLuminance(hexB);
+  const lighter = Math.max(lA, lB);
+  const darker  = Math.min(lA, lB);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// Check configured brand colours against standard light/dark backgrounds.
+// Shades 60–80 are the most common text-on-light use case.
+// Shades 20–40 are the most common text-on-dark use case.
+function createContrastWarnings(config) {
+  const warnings = [];
+  const colours = config.colours || {};
+  const LIGHT_BG = '#FAFAFA';
+  const DARK_BG  = '#1A1A1A';
+  const THRESHOLD_NORMAL = 4.5;
+
+  Object.entries(colours).forEach(([name, baseHex]) => {
+    let scale;
+    try {
+      scale = generateColourScale(baseHex);
+    } catch {
+      return;
+    }
+
+    // Shades typically used as text on light backgrounds
+    [60, 70, 80].forEach((shade) => {
+      const hex = scale[shade];
+      if (!hex) return;
+      const ratio = contrastRatio(hex, LIGHT_BG);
+      if (ratio < THRESHOLD_NORMAL) {
+        warnings.push({
+          file: 'emily.config.json',
+          reason: 'low-contrast-token',
+          className: `text-${name}-${shade}`,
+          message: `text-${name}-${shade} on a light background has ~${ratio.toFixed(1)}:1 contrast (WCAG AA needs 4.5:1 for normal text). Consider using a darker shade.`,
+        });
+      }
+    });
+
+    // Shades typically used as text on dark backgrounds
+    [20, 30, 40].forEach((shade) => {
+      const hex = scale[shade];
+      if (!hex) return;
+      const ratio = contrastRatio(hex, DARK_BG);
+      if (ratio < THRESHOLD_NORMAL) {
+        warnings.push({
+          file: 'emily.config.json',
+          reason: 'low-contrast-token',
+          className: `text-${name}-${shade}`,
+          message: `text-${name}-${shade} on a dark background has ~${ratio.toFixed(1)}:1 contrast (WCAG AA needs 4.5:1 for normal text). Consider using a lighter shade.`,
+        });
+      }
+    });
+  });
+
+  return warnings;
+}
+
 function doctor() {
   const config = getConfig();
 
@@ -304,8 +380,10 @@ function doctor() {
     }
   });
 
+  warnings.push(...createContrastWarnings(config));
+
   if (issues.length === 0 && warnings.length === 0) {
-    console.log("✓ EmilyCSS doctor found no class issues");
+    console.log("\u2713 EmilyCSS doctor found no class issues");
     return { ok: true, issues: [], warnings: [], exitCode: 0 };
   }
 
@@ -347,4 +425,7 @@ module.exports = {
   doctor,
   normaliseClassForManifest,
   suggestClassName,
+  hexToRelativeLuminance,
+  contrastRatio,
+  createContrastWarnings,
 };

package/src/index.js

@@ -849,12 +849,17 @@ function generateSemanticColourUtilities(semanticColours) {
 
 function addAriaDataVariants(css) {
   const variants = [
-    { name: 'aria-expanded', selector: '[aria-expanded="true"]' },
-    { name: 'aria-selected', selector: '[aria-selected="true"]' },
-    { name: 'aria-current',  selector: '[aria-current="page"]' },
-    { name: 'aria-disabled', selector: '[aria-disabled="true"]' },
-    { name: 'data-open',     selector: '[data-state="open"]' },
-    { name: 'data-closed',   selector: '[data-state="closed"]' },
+    { name: 'aria-expanded',  selector: '[aria-expanded="true"]' },
+    { name: 'aria-selected',  selector: '[aria-selected="true"]' },
+    { name: 'aria-checked',   selector: '[aria-checked="true"]' },
+    { name: 'aria-current',   selector: '[aria-current="page"]' },
+    { name: 'aria-disabled',  selector: '[aria-disabled="true"]' },
+    { name: 'data-open',      selector: '[data-state="open"]' },
+    { name: 'data-closed',    selector: '[data-state="closed"]' },
+    { name: 'data-checked',   selector: '[data-state="checked"]' },
+    { name: 'data-unchecked', selector: '[data-state="unchecked"]' },
+    { name: 'data-active',    selector: '[data-state="active"]' },
+    { name: 'data-inactive',  selector: '[data-state="inactive"]' },
   ];
 
   let variantCss = css;
@@ -1828,6 +1833,7 @@ module.exports = {
   oklchToHex,
   generateColourScale,
   generateAllColours,
+  generateFontCSS,
   generateSpacing,
   generateBorderUtilities,
   generateColourUtilities,
@@ -1840,6 +1846,4 @@ module.exports = {
   addAriaDataVariants,
   addResponsiveVariants,
   generateManifest,
-  generateFontCSS,
-  codeUtilities,
 };

package/src/info.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const fg = require('fast-glob');
+const {
+  getConfig,
+  getFullCssPath,
+  getProductionCssPath,
+} = require('./config.js');
+const { resolvePurgeConfig } = require('./purgeConfig.js');
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+function detectFramework(config) {
+  if (config.framework) return config.framework;
+  // fall back to output path heuristic
+  const outputPath = typeof config.output === 'string' ? config.output : (config.output && config.output.path) || '';
+  const out = outputPath.toLowerCase();
+  if (out.includes('public')) return 'Nuxt / Vue / Next.js';
+  return 'Static / Generic';
+}
+
+function getSourceGlobs(config) {
+  return resolvePurgeConfig(config).sourceGlobs;
+}
+
+function countSourceFiles(globs) {
+  try {
+    return fg.sync(globs, { onlyFiles: true, unique: true }).length;
+  } catch {
+    return null;
+  }
+}
+
+function info() {
+  let config;
+  try {
+    config = getConfig();
+  } catch (err) {
+    console.error('emily-css info: could not load emily.config.json');
+    console.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const packageJson = require(path.join(__dirname, '..', 'package.json'));
+  const fullCssPath = getFullCssPath(config);
+  const productionCssPath = getProductionCssPath(config);
+  const globs = getSourceGlobs(config);
+  const fileCount = countSourceFiles(globs);
+
+  const fullSizeStr = fs.existsSync(fullCssPath)
+    ? formatBytes(fs.statSync(fullCssPath).size)
+    : 'not built';
+
+  const prodSizeStr = fs.existsSync(productionCssPath)
+    ? formatBytes(fs.statSync(productionCssPath).size)
+    : 'not built';
+
+  const colourNames = config.colours ? Object.keys(config.colours) : [];
+  const semanticNames = config.semanticColours ? Object.keys(config.semanticColours) : [];
+  const colourSummary = colourNames.length
+    ? colourNames.join(', ') + (semanticNames.length ? ` + ${semanticNames.length} semantic` : '')
+    : 'none';
+
+  const fontConfig = config.fontFamily || {};
+  const headingFont = typeof fontConfig === 'object' ? (fontConfig.heading || 'system') : fontConfig;
+  const bodyFont   = typeof fontConfig === 'object' ? (fontConfig.body    || 'system') : fontConfig;
+
+  const lines = [
+    `emily-css v${packageJson.version}`,
+    '',
+    `  Project:      ${detectFramework(config)}`,
+    `  Config:       emily.config.json`,
+    `  Output:       ${path.relative(process.cwd(), fullCssPath)} (full)`,
+    `                ${path.relative(process.cwd(), productionCssPath)} (production)`,
+    `  CSS size:     ${fullSizeStr} (full)  /  ${prodSizeStr} (production)`,
+    `  Source globs: ${globs.join(', ')}`,
+    `  Files found:  ${fileCount !== null ? fileCount : 'unknown'}`,
+    '',
+    `  Colours:      ${colourSummary}`,
+    `  Spacing:      ${config.spacing && config.spacing.scale ? Object.keys(config.spacing.scale).length : 0} steps`,
+    `  Fonts:        ${headingFont} (heading), ${bodyFont} (body)`,
+    '',
+  ];
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { info };

package/src/init.js

@@ -154,6 +154,11 @@ function addEmilyScriptsToPackageJson() {
     const scripts = {
       "emily:build": "emily-css build",
       "emily:watch": "emily-css watch",
+      "emily:doctor": "emily-css doctor",
+      "emily:migrate": "emily-css migrate",
+      "emily:info": "emily-css info",
+      "emily:manifest": "emily-css manifest",
+      "emily:version": "emily-css version",
       "emily:help": "emily-css help",
       "emily:showcase": "emily-css showcase",
     };
@@ -288,7 +293,7 @@ function detectProject() {
     sourceDir: ".",
     outputPath: "dist/emily.min.css",
     sourceGlobs: [
-      "./**/*.{html,htm,twig,njk,liquid,hbs,php,astro,svelte,vue,js,ts}",
+      "./**/*.{html,htm,twig,njk,liquid,hbs,php,astro,svelte,vue,blade.php,jinja,jinja2,j2}",
     ],
     linkHint: '<link rel="stylesheet" href="./dist/emily.min.css">',
   };
@@ -325,6 +330,8 @@ function createDefaultConfig({
       fullCss: "dist/emily.css",
     },
 
+    manifest: true,
+
     colours,
 
     semanticColours: {
@@ -721,6 +728,11 @@ async function init() {
                   ? "\n\nScripts added:\n" +
                     chalk.cyan("  npm run emily:build\n") +
                     chalk.cyan("  npm run emily:watch\n") +
+                    chalk.cyan("  npm run emily:doctor\n") +
+                    chalk.cyan("  npm run emily:migrate\n") +
+                    chalk.cyan("  npm run emily:info\n") +
+                    chalk.cyan("  npm run emily:manifest\n") +
+                    chalk.cyan("  npm run emily:version\n") +
                     chalk.cyan("  npm run emily:showcase\n") +
                     chalk.cyan("  npm run emily:help")
                   : ""),

package/src/migrate.js

@@ -6,6 +6,7 @@ const { extractClassNames, getAllFiles } = require('./purge.js');
 const { generateManifest } = require('./manifest.js');
 const { normaliseClassForManifest, suggestClassName } = require('./doctor.js');
 const { DEFAULT_EXTENSIONS } = require('./constants.js');
+const { resolvePurgeConfig } = require('./purgeConfig.js');
 const MIGRATION_DEFAULT_EXTENSIONS = [...DEFAULT_EXTENSIONS, '.mdx'];
 
 const TAILWIND_MAPPINGS = {
@@ -573,6 +574,13 @@ function isLikelyUtilityClass(className) {
   if (/[;()={},`]/.test(className)) return false;
   if (!/[a-zA-Z]/.test(className)) return false;
   if (!/^[a-zA-Z0-9:#_./\-[\]]+$/.test(className)) return false;
+
+/*
+ * Ignore obvious prose / JS expressions
+ */
+if (/[.]+$/.test(className)) return false;
+if (/^[[][^:\]]+[]]$/.test(className)) return false;
+if (/^[a-zA-Z]+\.[a-zA-Z0-9_$]+$/.test(className)) return false;
   if (/^[a-z]+$/.test(className) && !SINGLE_WORD_UTILITY_ALLOWLIST.has(className)) return false;
   if (!hasUtilityLikeSyntax(className) && !SINGLE_WORD_UTILITY_ALLOWLIST.has(className)) return false;
 
@@ -740,8 +748,11 @@ function migrateClasses(input, options = {}) {
 }
 
 function getFilesToScan(config, options = {}) {
-  const extensions = (config && config.purge && config.purge.extensions) || MIGRATION_DEFAULT_EXTENSIONS;
-  const ignore = (config && config.purge && config.purge.ignore) || [];
+  const resolvedPurgeConfig = resolvePurgeConfig(config || {});
+  const extensions = Array.from(
+    new Set([...(resolvedPurgeConfig.extensions || MIGRATION_DEFAULT_EXTENSIONS), '.mdx']),
+  );
+  const ignore = resolvedPurgeConfig.ignore || [];
 
   if (options.sourceGlobs && options.sourceGlobs.length > 0) {
     return fg.sync(options.sourceGlobs, {
@@ -752,8 +763,8 @@ function getFilesToScan(config, options = {}) {
     });
   }
 
-  if (config && config.purge && config.purge.sourceGlobs && config.purge.sourceGlobs.length > 0) {
-    return fg.sync(config.purge.sourceGlobs, {
+  if (resolvedPurgeConfig.sourceGlobs && resolvedPurgeConfig.sourceGlobs.length > 0) {
+    return fg.sync(resolvedPurgeConfig.sourceGlobs, {
       ignore,
       onlyFiles: true,
       unique: true,
@@ -763,7 +774,7 @@ function getFilesToScan(config, options = {}) {
 
   const sourceDir =
     options.sourceDir ||
-    (config && config.purge && config.purge.sourceDir) ||
+    resolvedPurgeConfig.sourceDir ||
     '.';
 
   const scanDir = path.isAbsolute(sourceDir)
@@ -879,4 +890,4 @@ module.exports = {
   migrateClasses,
   loadManifest,
   generateMigrationReport,
-};
+};

package/src/purge.js

@@ -4,6 +4,7 @@ const fs = require("fs");
 const path = require("path");
 const fg = require("fast-glob");
 const { DEFAULT_EXTENSIONS, DEFAULT_PURGE_IGNORE } = require("./constants.js");
+const { resolvePurgeConfig } = require("./purgeConfig.js");
 
 function getAllFiles(dir, extensions = DEFAULT_EXTENSIONS) {
   const absoluteDir = path.isAbsolute(dir) ? dir : path.resolve(dir);
@@ -175,22 +176,27 @@ function purgeBlock(block, usedClasses) {
 }
 
 function getFilesForPurge(scanDir, config, extensions) {
-  if (config?.purge?.sourceGlobs && config.purge.sourceGlobs.length) {
+  const resolvedPurgeConfig = resolvePurgeConfig(config);
+  const sourceGlobs = resolvedPurgeConfig.sourceGlobs || [];
+
+  if (sourceGlobs.length) {
     console.log(`\n🔍 Scanning using sourceGlobs`);
-    config.purge.sourceGlobs.forEach((glob) => console.log(`   - ${glob}`));
+    sourceGlobs.forEach((glob) => console.log(`   - ${glob}`));
     console.log(`   Extensions: ${extensions.join(", ")}`);
 
-    return fg.sync(config.purge.sourceGlobs, {
-      ignore: config.purge.ignore || [],
+    return fg.sync(sourceGlobs, {
+      ignore: resolvedPurgeConfig.ignore || [],
       onlyFiles: true,
       unique: true,
     });
   }
 
-  console.log(`\n🔍 Scanning fallback directory: ${scanDir}`);
+  const fallbackScanDir = resolvedPurgeConfig.sourceDir || scanDir;
+
+  console.log(`\n🔍 Scanning fallback directory: ${fallbackScanDir}`);
   console.log(`   Extensions: ${extensions.join(", ")}`);
 
-  return getAllFiles(scanDir, extensions);
+  return getAllFiles(fallbackScanDir, extensions);
 }
 
 function printFileSummary(files, extensions) {
@@ -214,7 +220,8 @@ function printFileSummary(files, extensions) {
 }
 
 function purgeCSS(css, scanDir, config) {
-  const extensions = config?.purge?.extensions || DEFAULT_EXTENSIONS;
+  const resolvedPurgeConfig = resolvePurgeConfig(config);
+  const extensions = resolvedPurgeConfig.extensions || DEFAULT_EXTENSIONS;
   const files = getFilesForPurge(scanDir, config, extensions);
 
   printFileSummary(files, extensions);

package/src/purgeConfig.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { DEFAULT_EXTENSIONS, DEFAULT_PURGE_IGNORE } = require('./constants.js');
+
+const LEGACY_STATIC_GENERIC_GLOB = './**/*.{html,htm,twig,njk,liquid,hbs,php,astro,svelte,vue,js,ts}';
+
+const PROJECT_PURGE_PRESETS = {
+  Nuxt: {
+    sourceDir: '.',
+    sourceGlobs: [
+      './components/**/*.{vue,js,ts}',
+      './pages/**/*.vue',
+      './layouts/**/*.vue',
+      './app.vue',
+    ],
+  },
+  'Next.js': {
+    sourceDir: '.',
+    sourceGlobs: [
+      './app/**/*.{js,jsx,ts,tsx}',
+      './pages/**/*.{js,jsx,ts,tsx}',
+      './components/**/*.{js,jsx,ts,tsx}',
+      './src/**/*.{js,jsx,ts,tsx}',
+    ],
+  },
+  React: {
+    sourceDir: './src',
+    sourceGlobs: [
+      './src/**/*.{js,jsx,ts,tsx,html}',
+      './components/**/*.{js,jsx,ts,tsx}',
+      './public/**/*.html',
+    ],
+  },
+  'Vue/Vite': {
+    sourceDir: './src',
+    sourceGlobs: [
+      './src/**/*.{vue,js,jsx,ts,tsx,html}',
+      './index.html',
+    ],
+  },
+  Astro: {
+    sourceDir: './src',
+    sourceGlobs: [
+      './src/**/*.{astro,html,md,mdx,js,jsx,ts,tsx,vue,svelte}',
+    ],
+  },
+  Drupal: {
+    sourceDir: '.',
+    sourceGlobs: [
+      './web/themes/custom/**/*.{twig,js,ts}',
+      './templates/**/*.html.twig',
+      './components/**/*.twig',
+      './**/*.theme',
+    ],
+  },
+  'Static/Generic': {
+    sourceDir: '.',
+    sourceGlobs: [
+      './**/*.{html,htm,twig,njk,liquid,hbs,php,astro,svelte,vue,blade.php,jinja,jinja2,j2}',
+    ],
+  },
+};
+
+function unique(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
+function readPackageJson(cwd) {
+  const packagePath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(packagePath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function hasDependency(packageJson, dependencyName) {
+  if (!packageJson) return false;
+
+  return Boolean(
+    packageJson.dependencies?.[dependencyName] ||
+    packageJson.devDependencies?.[dependencyName],
+  );
+}
+
+function detectProjectType(cwd = process.cwd()) {
+  const packageJson = readPackageJson(cwd);
+
+  if (
+    fs.existsSync(path.join(cwd, 'nuxt.config.ts')) ||
+    fs.existsSync(path.join(cwd, 'nuxt.config.js')) ||
+    hasDependency(packageJson, 'nuxt')
+  ) {
+    return 'Nuxt';
+  }
+
+  if (hasDependency(packageJson, 'next')) {
+    return 'Next.js';
+  }
+
+  if (hasDependency(packageJson, 'react')) {
+    return 'React';
+  }
+
+  if (
+    hasDependency(packageJson, 'vue') ||
+    fs.existsSync(path.join(cwd, 'vite.config.ts')) ||
+    fs.existsSync(path.join(cwd, 'vite.config.js'))
+  ) {
+    return 'Vue/Vite';
+  }
+
+  if (
+    hasDependency(packageJson, 'astro') ||
+    fs.existsSync(path.join(cwd, 'astro.config.mjs'))
+  ) {
+    return 'Astro';
+  }
+
+  let rootFiles = [];
+  try {
+    rootFiles = fs.readdirSync(cwd);
+  } catch {
+    return 'Static/Generic';
+  }
+
+  const hasDrupalInfoFile = rootFiles.some((file) => file.endsWith('.info.yml'));
+
+  if (
+    hasDrupalInfoFile ||
+    fs.existsSync(path.join(cwd, 'web/core'))
+  ) {
+    return 'Drupal';
+  }
+
+  return 'Static/Generic';
+}
+
+function normaliseGlob(glob) {
+  return String(glob || '').replace(/\\/g, '/').trim();
+}
+
+function isLegacyStaticGenericGlob(sourceGlobs) {
+  if (!Array.isArray(sourceGlobs) || sourceGlobs.length !== 1) return false;
+  const [onlyGlob] = sourceGlobs.map(normaliseGlob);
+  return onlyGlob === LEGACY_STATIC_GENERIC_GLOB;
+}
+
+function resolvePurgeConfig(config = {}, options = {}) {
+  const purge = config.purge || {};
+  const cwd = options.cwd || process.cwd();
+  const detectedProjectType = detectProjectType(cwd);
+  const projectType = purge.projectType || detectedProjectType;
+  const preset = PROJECT_PURGE_PRESETS[projectType] || PROJECT_PURGE_PRESETS['Static/Generic'];
+
+  const configuredSourceGlobs = Array.isArray(purge.sourceGlobs)
+    ? purge.sourceGlobs.filter(Boolean)
+    : [];
+
+  let sourceGlobs = configuredSourceGlobs.length > 0
+    ? configuredSourceGlobs
+    : preset.sourceGlobs;
+
+  if (projectType === 'Static/Generic' && isLegacyStaticGenericGlob(sourceGlobs)) {
+    sourceGlobs = preset.sourceGlobs;
+  }
+
+  const sourceDir = purge.sourceDir || preset.sourceDir || '.';
+
+  return {
+    projectType,
+    sourceDir,
+    sourceGlobs,
+    ignore: unique([...DEFAULT_PURGE_IGNORE, ...(purge.ignore || [])]),
+    extensions: Array.isArray(purge.extensions) && purge.extensions.length > 0
+      ? purge.extensions
+      : DEFAULT_EXTENSIONS,
+  };
+}
+
+module.exports = {
+  PROJECT_PURGE_PRESETS,
+  LEGACY_STATIC_GENERIC_GLOB,
+  detectProjectType,
+  resolvePurgeConfig,
+};
+