@emulsify/core 3.4.1 → 4.0.0

package/.storybook/preview.js

@@ -1,31 +1,60 @@
-// .storybook/preview.js
-import { useEffect } from '@storybook/preview-api';
-import Twig from 'twig';
-import { setupTwig, fetchCSSFiles } from './utils.js';
+/**
+ * @file Storybook preview configuration shared by Emulsify projects.
+ */
+
 import { getRules } from 'axe-core';
+import React from 'react';
+import { defaultDecorateStory, useEffect } from 'storybook/preview-api';
+import Twig from 'twig';
+import { twigExtensionInstallers } from 'virtual:emulsify-twig-extension-installers';
+import {
+  mergePreviewParameters,
+  normalizePreviewOverrideModule,
+} from '../src/storybook/preview-parameters.js';
+import {
+  renderHtmlStoryResult,
+  withLegacyStoryToString,
+} from '../src/storybook/render-twig.js';
+import {
+  attachStorybookBehaviors,
+  fetchCSSFiles,
+  getStorybookPlatformAdapter,
+  setupTwig,
+} from './utils.js';
+
+const previewOverrideModules = import.meta.glob(
+  [
+    // Installed package path: node_modules/@emulsify/core/.storybook -> project root.
+    '../../../../config/emulsify-core/storybook/preview.js',
+    // Local development path: repo .storybook -> repo root.
+    '../config/emulsify-core/storybook/preview.js',
+  ],
+  { eager: true },
+);
+const [previewOverrideModule] = Object.values(previewOverrideModules);
+const externalOverrides = normalizePreviewOverrideModule(previewOverrideModule);
 
 /**
- * External override parameters loaded from project config file, if present.
- * @type {object}
+ * Active platform behavior used by the shared preview decorators.
+ *
+ * @type {ReturnType<typeof getStorybookPlatformAdapter>}
  */
-let externalOverrides = {};
+const platformAdapter = getStorybookPlatformAdapter();
 
-// Load the preview.js from the project config overrides.
-try {
-  /**
-   * Dynamically require external preview overrides.
-   * @module '../../../../config/emulsify-core/storybook/preview.js'
-   */
-  externalOverrides = require(
-    '../../../../config/emulsify-core/storybook/preview.js'
-  ).default;
-} catch (err) {
-  // no override file? swallow the error and use {}
-  externalOverrides = {};
-}
+/**
+ * Deferred Drupal behavior shim import.
+ *
+ * The decorator awaits this promise when Drupal behaviors are enabled so that
+ * `attachBehaviors()` is available before a story asks for it.
+ *
+ * @type {Promise<*>}
+ */
+const platformBehaviorShimReady = platformAdapter.loadDrupalBehaviorShim
+  ? import('./_drupal.js')
+  : Promise.resolve();
 
-// Import Drupal behaviors for rich JavaScript integration.
-import './_drupal.js';
+/** @type {Array<Function>} Configured Twig.js extension installers. */
+const configuredTwigExtensions = twigExtensionInstallers;
 
 /**
  * Filters accessibility rules by matching tags.
@@ -34,10 +63,10 @@ import './_drupal.js';
  */
 function enableRulesByTag(tags = []) {
   const allRules = getRules();
-  return allRules.map(rule =>
-    tags.some(t => rule.tags.includes(t))
+  return allRules.map((rule) =>
+    tags.some((t) => rule.tags.includes(t))
       ? { id: rule.ruleId, enabled: true }
-      : { id: rule.ruleId, enabled: false }
+      : { id: rule.ruleId, enabled: false },
   );
 }
 
@@ -54,26 +83,49 @@ const AxeRules = enableRulesByTag([
   'best-practice',
 ]);
 
-// Initialize Twig and load any CSS that your stories need.
-setupTwig(Twig);
-fetchCSSFiles();
+/**
+ * Storybook React wraps story functions in React elements before decorators run.
+ * Preserve that React-safe behavior while giving old stringifying decorators a
+ * useful string result for legacy Twig stories.
+ *
+ * @param {Function} storyFn Storybook story function.
+ * @param {Function[]} decorators Storybook decorators.
+ * @returns {Function} Decorated story function.
+ */
+export const applyDecorators = (storyFn, decorators) =>
+  defaultDecorateStory(
+    (context) =>
+      withLegacyStoryToString(React.createElement(storyFn, context), () =>
+        storyFn(context),
+      ),
+    decorators,
+  );
 
 /**
- * Storybook decorators to apply Drupal behaviors before rendering each story.
+ * Storybook decorators to apply platform-specific behavior after each story render.
  * @type {Array<import('@storybook/react').Decorator>}
  */
 export const decorators = [
   /**
-   * Decorator that attaches Drupal behaviors on story mount.
+   * Decorator that attaches platform behavior on story mount and args updates.
+   * Legacy Twig stories that return HTML strings are wrapped so React
+   * Storybook renders them as markup while projects migrate to renderTwig().
+   *
    * @param {Function} Story The story component to render.
    * @param {object} context Story context including args.
-   * @returns {Function} Rendered story.
+   * @returns {*} Rendered story.
    */
   (Story, { args }) => {
     useEffect(() => {
-      Drupal.attachBehaviors();
+      void attachStorybookBehaviors({
+        adapter: platformAdapter,
+        behaviorShimReady: platformBehaviorShimReady,
+      });
     }, [args]);
-    return Story();
+
+    return renderHtmlStoryResult(Story({ args }), {
+      platformAdapter,
+    });
   },
 ];
 
@@ -97,7 +149,11 @@ const defaultParams = {
  * Merged Storybook parameters including external overrides.
  * @type {object}
  */
-export const parameters = {
-  ...defaultParams,
-  ...externalOverrides,
-};
+export const parameters = mergePreviewParameters(
+  defaultParams,
+  externalOverrides,
+);
+
+// Initialize platform-agnostic Twig helpers and eager-load story CSS.
+setupTwig(Twig, { extensions: configuredTwigExtensions });
+await fetchCSSFiles(parameters);

package/.storybook/utils.js

@@ -1,58 +1,77 @@
-import { resolve, dirname } from 'path';
-import twigDrupal from 'twig-drupal-filters';
-import twigBEM from 'bem-twig-extension';
-import twigAddAttributes from 'add-attributes-twig-extension';
-import emulsifyConfig from '../../../../project.emulsify.json' with { type: 'json' };
-import twigInclude from './polyfills/twig-include';
-import twigSource from './polyfills/twig-source';
+/**
+ * @file Shared Storybook runtime helpers.
+ */
 
-// Create __filename from import.meta.url without fileURLToPath
-let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
+import {
+  attachStorybookBehaviors,
+  genericStorybookAdapter,
+  normalizeStorybookPlatformAdapter,
+} from '../src/storybook/platform-behaviors.js';
+import { setupTwig } from '../src/storybook/twig/setup.js';
 
-// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
-if (process.platform === 'win32' && _filename.startsWith('/')) {
-  _filename = _filename.slice(1);
+const emulsifyEnv =
+  (typeof __EMULSIFY_ENV__ !== 'undefined' && __EMULSIFY_ENV__) || {};
+
+/**
+ * Get the normalized Emulsify environment injected by Storybook's Vite config.
+ *
+ * @returns {object} Normalized Emulsify environment.
+ */
+export function getEmulsifyEnvironment() {
+  return emulsifyEnv;
 }
 
-const _dirname = dirname(_filename);
+/**
+ * Get Storybook platform behavior flags from the active adapter.
+ *
+ * @returns {object} Storybook adapter flags.
+ */
+export function getStorybookPlatformAdapter() {
+  return normalizeStorybookPlatformAdapter(
+    emulsifyEnv.platformAdapter?.storybook,
+  );
+}
 
 /**
- * Fetches project-based variant configuration. If no such configuration
- * exists, returns default values as a flat component structure.
+ * Determine whether Storybook should eagerly load all compiled CSS.
  *
- * @returns {Array} project-based variant configuration, or default config.
+ * @param {object} [parameters={}] - Storybook parameters.
+ * @returns {boolean} TRUE unless `parameters.emulsify.loadAllCSS` is false.
  */
-const fetchVariantConfig = () => {
-  try {
-    return emulsifyConfig.variant.structureImplementations;
-  } catch (e) {
-    return [
-      {
-        name: 'components',
-        directory: '../../../../components',
-      },
-    ];
-  }
-};
+export function getLoadAllCSS(parameters = {}) {
+  return parameters?.emulsify?.loadAllCSS !== false;
+}
 
 /**
- * Fetches and loads all CSS files from the specified directories based on the project's configuration.
- * If the platform is 'drupal', it also includes CSS files from additional component directories.
+ * Eagerly load CSS from the active Storybook render path.
+ *
+ * Drupal-style mirrored component CSS uses the root `components` CSS tree for
+ * component styles and keeps shared compiled CSS from `dist` excluding
+ * `dist/components`; all other projects use the compiled `dist` CSS tree. The
+ * eager globs live in separate dynamically imported modules so Vite cannot
+ * hoist both render paths into the same preview bundle. Projects with very
+ * large CSS libraries can set `parameters.emulsify.loadAllCSS = false` and
+ * import their own CSS from a preview override.
  *
- * @returns {undefined} If an error occurs, the function will return undefined.
+ * @param {object} [parameters={}] - Storybook parameters.
+ * @returns {Promise<undefined>} Resolves when the selected CSS path is loaded.
  */
-const fetchCSSFiles = () => {
+const fetchCSSFiles = async (parameters = {}) => {
   try {
-    // Load all CSS files from 'dist'.
-    const cssFiles = require.context('../../../../dist', true, /\.css$/);
-    cssFiles.keys().forEach((file) => cssFiles(file));
+    if (!getLoadAllCSS(parameters)) {
+      return undefined;
+    }
+
+    const adapter = getStorybookPlatformAdapter();
 
-    // Load all CSS files from 'components' for 'drupal' platform.
-    if (emulsifyConfig.project.platform === 'drupal') {
-      const drupalCSSFiles = require.context('../../../../components', true, /\.css$/);
-      drupalCSSFiles.keys().forEach((file) => drupalCSSFiles(file));
+    if (adapter.loadMirroredComponentCss) {
+      await import('./css-components.js');
+      return undefined;
     }
-  } catch (e) {
+
+    await import('./css-dist.js');
+    return undefined;
+  } catch {
     return undefined;
   }
 };
@@ -64,34 +83,16 @@ const fetchCSSFiles = () => {
  * @returns {string|undefined} Project machine name string, or undefined if not available
  */
 export function getProjectMachineName() {
-  try {
-    return emulsifyConfig.project.machineName;
-  } catch (e) {
-    return undefined;
-  }
-};
-
-// Build namespaces mapping.
-export const namespaces = {};
-for (const { name, directory } of fetchVariantConfig()) {
-  namespaces[name] = resolve(_dirname, '../../../../', directory);
+  return typeof emulsifyEnv.machineName === 'string'
+    ? emulsifyEnv.machineName
+    : undefined;
 }
 
-/**
- * Configures and extends a standard Twig object.
- *
- * @param {Object} twig - Twig object that should be configured and extended.
- * @returns {Object} Configured Twig object.
- */
-export function setupTwig(twig) {
-  twig.cache();
-  twigDrupal(twig);
-  twigBEM(twig);
-  twigAddAttributes(twig);
-  twigInclude(twig);
-  twigSource(twig);
-  return twig;
-}
-
-// Export the fetchCSSFiles function.
-export { fetchCSSFiles };
+// Keep these named exports stable for preview.js and downstream overrides.
+export {
+  attachStorybookBehaviors,
+  fetchCSSFiles,
+  genericStorybookAdapter,
+  normalizeStorybookPlatformAdapter,
+  setupTwig,
+};

package/README.md

@@ -4,93 +4,144 @@
 
 An open-source toolset for creating and implementing design systems.
 
-**Emulsify Core** provides a [Storybook](https://storybook.js.org/) component library and a [Webpack](https://webpack.js.org/) development environment. It is meant to make project setup and ongoing development easier by bundling all necessary configuration and providing it as an extendable package for your theme or standalone project.
+**Emulsify Core** provides shared [Vite](https://vite.dev/) build configuration and a [Storybook](https://storybook.js.org/) component library setup for component-driven development. Twig-based components and React components are both supported authoring models. A project can be Twig-first, React-first, or intentionally mixed.
 
-## Installation and usage
-Installation and configuration is setup by the provided base theme project(s). As of this writing, Emulsify Drupal is the only base theme project [with this integration](https://github.com/emulsify-ds/emulsify-drupal/blob/main/whisk/package.json#L36).
+## How Emulsify Core Works
 
-### Manual installation
-- `npm install @emulsify/core` within your repository or project theme.
-- Copy the provided `npm run` scripts from [Emulsify Drupal's package.json](https://github.com/emulsify-ds/emulsify-drupal/blob/main/whisk/package.json#L15)
-- Copy the contents of `whisk/config/emulsify-core/` from [Emulsify Drupal](https://github.com/emulsify-ds/emulsify-drupal/tree/main/whisk/config/emulsify-core) into your project so `config/` exists at the root of your repository or project theme. The files within `config/` allow you to extend or overwrite configuration provided by Emulsify Core.
+- Vite builds project JavaScript, Sass/CSS, Twig templates, component metadata, and static component assets.
+- Storybook uses the React/Vite framework.
+- Twig files can render in React-based Storybook through `renderTwig()`.
+- React components render through Storybook's React/Vite support.
+- Twig and React stories can coexist in the same Storybook instance.
+- `project.emulsify.json` is the source of truth for platform and structure configuration.
+- Platform-specific behavior is controlled by adapters instead of being assumed globally.
+- Node.js 24 or later is required.
 
-### Common Scripts
+## Project Evolution
 
-Run `nvm use` prior to running any of the following commands to verify you are using Node 20.
-(Each is prefixed with `npm run `)
+Emulsify Core has grown through each major release while keeping the same practical goal: make component-library tooling easier to share across real projects.
 
-**develop**
-Starts and instance of storybook, watches for any files changes, recompiles CSS/JS, and live reloads storybook assets.
+- `1.x` established Emulsify Core as a reusable package for Storybook, Webpack, linting, a11y checks, project overrides, and asset handling.
+- `2.x` expanded component structure support, improved Drupal SDC compatibility, upgraded Storybook, and made more project files configurable from consuming projects.
+- `3.x` modernized the runtime around ESM and Node 24, continued Storybook and dependency upgrades, improved component asset copying, and strengthened compatibility for existing Drupal-oriented builds.
+- The current release moves the build system to Vite, runs Storybook on React/Vite, supports Twig and React stories side by side, and normalizes platform and project-structure behavior through `project.emulsify.json`.
 
-**lint**
-Lints all JS/SCSS within your components and reports any violations.
+The latest version is the next evolution of that work: faster builds, clearer public APIs, less global Drupal assumption, and a broader foundation for CMS themes, standalone UI libraries, and mixed component systems.
 
-**lint-fix**
-Automatically fixes any simple violations.
+See [Version Evolution](docs/version-evolution.md) for more release history.
 
-**prettier**
-Outputs any code formatting violations.
+## Authoring Models
 
-**prettier-fix**
-Automatically fixes any simple code formatting violations.
+Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:
 
-**storybook-build**
-Builds a static output of the storybook instance.
+- Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today; Craft CMS and WordPress + Timber can use the generic adapter unless a project adds platform-specific behavior.
+- Use React for standalone UI libraries, application components, or projects that already use React.
+- Use mixed Twig and React when a design system needs to document both CMS-rendered and JavaScript-rendered components in the same Storybook instance.
 
+See [Component Authoring](docs/component-authoring.md) for Twig, React, mixed Storybook, and shared Sass examples.
 
-### Quick Links
+## Basic Usage
 
-- [Emulsify Homepage](https://www.emulsify.info/)
+Installation and project scripts are usually provided by a starter or platform integration. Manual setup starts with:
 
-## Demo
+```sh
+npm install @emulsify/core
+```
 
-1. [Storybook](http://storybook.emulsify.info/)
+Every project should provide a `project.emulsify.json` file at the project root:
 
-## Contributing
+```json
+{
+  "project": {
+    "platform": "generic",
+    "name": "example",
+    "machineName": "example"
+  }
+}
+```
 
-### [Code of Conduct](https://github.com/emulsify-ds/emulsify-drupal/blob/master/CODE_OF_CONDUCT.md)
+Common project scripts call the shared Emulsify Core Vite and Storybook config:
 
-The project maintainers have adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
+- `storybook`: starts Storybook development.
+- `storybook-build`: builds static Storybook output.
+- `build`: runs the Vite build for JS, CSS, copied Twig templates, component metadata, and static component assets.
+- `lint`: lints maintained project source.
 
-### Contribution Guide
+## Documentation
 
-Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:
+The documentation is split by task:
 
-1. [Emulsify Drupal](https://github.com/emulsify-ds/emulsify-drupal/issues)
-2. [Emulsify Twig Extensions](https://github.com/emulsify-ds/emulsify-twig-extensions/issues)
-3. [Emulsify Tools (Drupal module)](https://www.drupal.org/project/issues/emulsify_tools)
+| Topic                                                     | Use This When                                                                                                         |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [Version Evolution](docs/version-evolution.md)            | Understanding how Emulsify Core has evolved across major releases.                                                    |
+| [Component Authoring](docs/component-authoring.md)        | Choosing Twig, React, or mixed Storybook authoring and comparing component examples.                                  |
+| [Storybook](docs/storybook.md)                            | Rendering Twig stories, using `renderTwig()`, understanding Twig runtime helpers, and mixing Twig with React stories. |
+| [Project Structure And Output](docs/project-structure.md) | Configuring `src/components`, root `./components`, `variant.structureImplementations`, and expected output paths.     |
+| [Platform Adapters](docs/platform-adapters.md)            | Understanding `generic`, `drupal`, platform resolution order, and Drupal SDC behavior.                                |
+| [Extension Points](docs/extension-points.md)              | Adding Vite plugins, Tailwind CSS, Storybook preview overrides, and other framework tooling.                          |
+| [Performance](docs/performance.md)                        | Understanding sourcemaps, eager Twig imports, Tailwind scanning, copied files, and fixture validation.                |
+| [Native Twig Extensions](docs/native-twig-extensions.md)  | Using `bem()`, `add_attributes()`, and `switch/case/default/endswitch` in Twig.js.                                    |
+| [Release Verification](docs/release.md)                   | Running 4.x release checks, tarball smoke tests, and semantic-release dry runs before publishing.                     |
+| [Migration](docs/migration-4x.md)                         | Upgrading from earlier versions while preserving existing structures.                                                 |
 
-### Committing Changes
+## Known Limitations
 
-To facilitate automatic semantic release versioning, we utilize the [Conventional Changelog](https://github.com/conventional-changelog/conventional-changelog) standard through Commitizen. Follow these steps when commiting your work to ensure semantic release can version correctly.
+- Implemented platform adapters are currently `generic` and `drupal`. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the generic adapter today; dedicated adapters are future opportunities. See [Platform Adapters](docs/platform-adapters.md).
+- Storybook's Twig resolver eagerly imports Twig modules and raw Twig source. This is reliable for `include()` and `source()`, but large Twig libraries should keep Storybook source roots intentional. See [Performance](docs/performance.md).
+- Production sourcemaps are enabled by default unless a project overrides Vite config through `config/emulsify-core/vite/plugins.*`. See [Performance](docs/performance.md).
+- Project extensions use the public `config/emulsify-core` directory: `config/emulsify-core/vite/plugins.*` for Vite, `config/emulsify-core/storybook/...` for Storybook, and `config/emulsify-core/a11y.config.js` for a11y. See [Extension Points](docs/extension-points.md).
+- Webpack-specific customizations must be migrated manually to Vite plugins or `extendConfig()`. See [Migration](docs/migration-4x.md).
+- Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. Generic projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
 
-1. Stage your changes, ensuring they encompass exactly what you wish to change, no more.
-2. Run the `commit` script via `yarn commit` or `npm run commit` and follow the prompts to craft the perfect commit message.
-3. Your commit message will be used to create the changelog for the next version that includes that commit.
+## Supported Project Shapes
 
-## Author
+Release-readiness coverage validates:
 
-Emulsify® is a product of [Four Kitchens](https://fourkitchens.com).
+- Drupal SDC projects using `src/components`.
+- Generic Twig projects using `src/components`.
+- Root `./components` projects.
+- Projects using multiple `variant.structureImplementations`.
+- Mixed Twig + React Storybook projects.
 
-## Contributors
+WordPress + Timber and Craft CMS are Twig-based project use cases that can use the `generic` adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently `generic` and `drupal`.
 
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-<table>
-  <tbody>
-    <tr>
-      <td align="center" valign="top" width="16.66%"><a href="https://github.com/callinmullaney"><img src="https://avatars.githubusercontent.com/u/369018?v=4?s=100" width="100px;" alt="Callin Mullaney"/><br /><sub><b>Callin Mullaney</b></sub></a><br /><a href="https://github.com/fourkitchens/emulsify-core/commits?author=callinmullaney" title="Code">💻</a> <a href="https://github.com/fourkitchens/emulsify-core/commits?author=callinmullaney" title="Documentation">📖</a></td>
-      <td align="center" valign="top" width="16.66%"><a href="https://github.com/amazingrando"><img src="https://avatars.githubusercontent.com/u/409903?v=4?s=100" width="100px;" alt="Randy Oest"/><br /><sub><b>Randy Oest</b></sub></a><br /><a href="https://github.com/fourkitchens/emulsify-core/commits?author=amazingrando" title="Code">💻</a> <a href="https://github.com/fourkitchens/emulsify-core/commits?author=amazingrando" title="Documentation">📖</a></td>
-      <td align="center" valign="top" width="16.66%"><a href="https://github.com/robherba"><img src="https://avatars.githubusercontent.com/u/9342274?v=4?s=100" width="100px;" alt="Roberto Hernandez"/><br /><sub><b>Roberto Hernandez</b></sub></a><br /><a href="https://github.com/fourkitchens/emulsify-core/commits?author=robherba" title="Code">💻</a></td>
-      <td align="center" valign="top" width="16.66%"><a href="https://github.com/dependabot"><img src="https://avatars.githubusercontent.com/u/49699333?v=4?s=100" width="100px;" alt="Dependabot"/><br /><sub><b>Dependabot</b></sub></a><br /><a href="#maintenance-dependabot" title="Maintenance">🚧</a></td>
-    </tr>
-  </tbody>
-</table>
+## Public Imports
+
+Emulsify Core exposes stable public package paths:
+
+```js
+import { renderTwig } from '@emulsify/core/storybook';
+import { registerTwigExtensions } from '@emulsify/core/extensions/twig';
+import { defineReactExtension } from '@emulsify/core/extensions/react';
+```
+
+`defineReactExtension` is reserved for future React extension support. It currently returns the input unchanged. Adopting the import path is safe; the runtime is intentionally a no-op until the registry lands. See [Extension Points](docs/extension-points.md#public-imports).
+
+Vite consumers can import the shared config from `@emulsify/core/vite` and public Vite plugin helpers from `@emulsify/core/vite/plugins`.
+
+## Contributing
 
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
+Maintained JavaScript source, config, scripts, and tests should use consistent comments:
 
-<!-- ALL-CONTRIBUTORS-LIST:END -->
+- Start each maintained JS file with a short JSDoc file block that explains the file's responsibility.
+- Use JSDoc blocks for exported functions, complex helpers, and public contracts.
+- Use `//` comments for local intent, compatibility behavior, and non-obvious edge cases.
+- Keep comments concise and factual. Prefer explaining why behavior exists instead of restating the code.
+- Use YAML or shell comments in workflow, hook, and fixture files where the format supports comments.
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+Do not add comments to JSON files, lockfiles, binary assets, generated output, legal documents, or dependency files. Those formats either do not support comments or should remain exact artifacts.
+
+Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:
+
+1. [Emulsify Drupal](https://github.com/emulsify-ds/emulsify-drupal/issues)
+2. [Emulsify Tools (Drupal module)](https://www.drupal.org/project/issues/emulsify_tools)
+
+## Links
+
+- [Emulsify Homepage](https://www.emulsify.info/)
+- [Storybook Demo](http://storybook.emulsify.info/)
+- [Code of Conduct](https://github.com/emulsify-ds/emulsify-drupal/blob/master/CODE_OF_CONDUCT.md)
+
+## Author
+
+Emulsify&reg; is a product of [Four Kitchens](https://fourkitchens.com).

package/config/.stylelintrc.json

@@ -1,10 +1,6 @@
 {
-  "extends": [
-    "stylelint-config-standard-scss"
-  ],
-  "plugins": [
-    "stylelint-prettier"
-  ],
+  "extends": ["stylelint-config-standard-scss"],
+  "plugins": ["stylelint-prettier"],
   "customSyntax": "postcss-scss",
   "rules": {
     "at-rule-empty-line-before": [

package/config/a11y.config.js

@@ -1,14 +1,18 @@
-module.exports = {
+/**
+ * @file Shared accessibility linting configuration.
+ *
+ * These defaults are consumed by the pa11y script and can be extended by
+ * consuming projects through their local Emulsify config.
+ */
+
+export default {
   storybookBuildDir: '../../../../.out',
   pa11y: {
     includeNotices: false,
     includeWarnings: false,
     runners: ['axe'],
   },
-  // A11y linting is done on a component-by-component
-  // basis, which results in the linter reporting some errors that
-  // should be ignored. These codes and descriptions allow for those
-  // errors to be targeted specifically.
+  // Ignore rules that are noisy for isolated component pages.
   ignore: {
     codes: ['landmark-one-main', 'page-has-heading-one'],
     descriptions: ['Ensures all page content is contained by landmarks'],

package/config/babel.config.js

@@ -1,6 +1,11 @@
+/**
+ * @file Babel configuration for test and legacy transpilation paths.
+ */
+
 export default (api) => {
   api.cache(true);
 
+  // Disable Babel's generated comments so minified output stays compact.
   const presets = [['minify', { builtIns: false }]];
   const comments = false;
 

package/config/eslint.config.js

@@ -1,4 +1,7 @@
-// Import ESLint Flat Config and required plugins
+/**
+ * @file ESLint flat configuration for Emulsify Core.
+ */
+
 import js from '@eslint/js';
 import babelParser from '@babel/eslint-parser';
 import importPlugin from 'eslint-plugin-import';
@@ -6,10 +9,9 @@ import pluginSecurity from 'eslint-plugin-security';
 import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
 
 export default [
-  // Base ESLint recommended rules
+  // Start with core and plugin recommendations before project overrides.
   js.configs.recommended,
 
-  // Plugin configurations
   importPlugin.flatConfigs.recommended,
   pluginSecurity.configs.recommended,
   eslintPluginPrettierRecommended,
@@ -39,6 +41,7 @@ export default [
     ignores: ['**/*.min.js', '**/node_modules/**/*'],
 
     rules: {
+      // Keep historical project conventions while warning on risky patterns.
       strict: 0,
       'consistent-return': 'off',
       'no-underscore-dangle': 'off',

package/config/postcss.config.js

@@ -1,5 +1,10 @@
+/**
+ * @file PostCSS plugin configuration.
+ */
+
 import autoPrefixer from 'autoprefixer';
 
 export default {
+  // Autoprefixer keeps compiled CSS compatible with supported browsers.
   plugins: [autoPrefixer()],
 };