emilyCSS

Token-first, framework-agnostic CSS generation for teams that want predictable utilities without adopting a full app framework.

What emilyCSS is

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.

Why teams use it

• Token-first utility generation from your own colours, spacing, typography, and motion settings
• Framework-agnostic output (single project-specific emily.css path by default)
• Accessibility-focused utility coverage (focus rings, visually-hidden helpers, motion-aware variants)
• Broader Tailwind-style compatibility coverage for everyday migration classes
• Tooling support with manifest and IntelliSense JSON generation
• CommonJS package with Node 18+ compatibility

Install and basic workflow

npm install emily-css
npx emily-css init
npx emily-css build
npx emily-css watch

During init, if you choose non-system fonts, EmilyCSS can optionally install matching @fontsource/* packages for you. Supported non-system keys include inter, lexend, figtree, dm-sans, nunito, and atkinson.

Dev: link full CSS for fastest feedback.

<link rel="stylesheet" href="./dist/emily.css">

Production: run a build. By default it overwrites the same emily.css path with purged/minified CSS:

<link rel="stylesheet" href="./dist/emily.css">

Core commands

npx emily-css init
npx emily-css init --fresh
npx emily-css init --skip-font-install
npx emily-css init --yes
npx emily-css build
npx emily-css build --profile
npx emily-css watch
npx emily-css watch --prod
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):

npm run emily:build
npm run emily:watch
npm run emily:watch -- --prod
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

• watch (default) is development mode and regenerates full CSS at your configured output.fullCss path.

• build generates production CSS (purged + minified) at your configured output.css path.

• New init projects default to a single stable filename by setting both paths to the same project-specific emily.css location.

• watch --prod is available when you explicitly want purge + minify on every source-file change.

• init now detects existing emily.config.json and lets you choose between reusing existing values or starting from fresh defaults.

• init supports --fresh, --use-existing, --skip-font-install, and --yes for faster setup and automation.

• 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).

Tailwind compatibility additions

Recent utility coverage additions include:

• Negative margin utilities: -m-*, -mx-*, -my-*, -mt-*, -mr-*, -mb-*, -ml-*
• Positioning full values: top-full, right-full, bottom-full, left-full, inset-full, inset-x-full, inset-y-full
• Box sizing: box-border, box-content
• Grid alignment: justify-items-*, justify-self-*
• Sizing completion: max-h-none
• Typography completion: font-thin, font-extralight, font-extrabold, font-black
• Background origin and gradient directions: bg-origin-*, bg-gradient-to-*
• Transition completion: transition-all, transition-shadow
• Transform axis utilities: scale-x-*, scale-y-*, extended skew-x-*, skew-y-*, and negative skew variants
• Overscroll behavior: overscroll-*, overscroll-x-*, overscroll-y-*

Migration scanner utility-prefix detection was also expanded for classes like box-*, overscroll-*, transition-*, color-scheme-*, field-sizing-*, and scrollbar-*.

Manifest and IntelliSense JSON

Enable machine-readable outputs when needed:

{
  "manifest": true,
  "intellisense": {
    "enabled": true,
    "output": "dist/emily.intellisense.json"
  }
}

Generated files:

• dist/emily.manifest.json
• dist/emily.intellisense.json

These files are intended for tooling, audits, and editor integrations. A VSCode extension is not required for generation.

Minimal configuration example

{
  "name": "My Brand",
  "fontFamily": {
    "heading": "atkinson",
    "body": "inter"
  },
  "colours": {
    "brand": "#0077B6",
    "accent": "#0EA5E9",
    "neutral": "#57534E",
    "success": "#0F766E",
    "error": "#B91C1C"
  },
  "manifest": true,
  "intellisense": true
}

Notes on compatibility

• Package format: CommonJS
• Runtime support: Node 18+
• ESM-only major upgrades are intentionally avoided where they would break compatibility

License

MIT