docs: refine documentation tone

Callin Mullaney · Callin Mullaney · commit 09540bbd3786 · 2026-05-25T01:26:05.000-05:00
diff --git a/README.md b/README.md
@@ -4,19 +4,32 @@
 
 An open-source toolset for creating and implementing design systems.
 
-**Emulsify Core** provides shared [Vite](https://vite.dev/) build configuration and a [Storybook](https://storybook.js.org/) component library setup for component-driven development. In 4.x, Twig-based components and React components are both supported authoring models. A project can be Twig-first, React-first, or intentionally mixed.
+**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.
 
-## 4.x At A Glance
+## How Emulsify Core Works
 
-- Webpack has been replaced with Vite.
-- Storybook uses `@storybook/react-vite`.
+- 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.
 
+## Project Evolution
+
+Emulsify Core has grown through each major release while keeping the same practical goal: make component-library tooling easier to share across real projects.
+
+- `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`.
+
+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.
+
+See [Version Evolution](docs/version-evolution.md) for more release history.
+
 ## Authoring Models
 
 Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:
@@ -56,21 +69,22 @@ Common project scripts call the shared Emulsify Core Vite and Storybook config:
 
 ## Documentation
 
-The full 4.x documentation is split by task:
+The documentation is split by task:
 
 | 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.                          |
 | [Native Twig Extensions](docs/native-twig-extensions.md)  | Using `bem()`, `add_attributes()`, and `switch/case/default/endswitch` in Twig.js.                                    |
-| [Migration To 4.x](docs/migration-4x.md)                  | Upgrading from 3.x, preserving existing structures, and adopting Vite/React Storybook.                                |
+| [Migration](docs/migration-4x.md)                         | Upgrading from earlier versions while preserving existing structures.                                                 |
 
 ## Supported Project Shapes
 
-Current release-readiness coverage validates:
+Release-readiness coverage validates:
 
 - Drupal SDC projects using `src/components`.
 - Generic Twig projects using `src/components`.
@@ -82,7 +96,7 @@ Craft CMS and WordPress + Timber are documented as Twig-based project use cases
 
 ## Public Imports
 
-Emulsify Core 4.x exposes stable public package paths:
+Emulsify Core exposes stable public package paths:
 
 ```js
 import { renderTwig } from '@emulsify/core/storybook';
diff --git a/docs/README.md b/docs/README.md
@@ -4,10 +4,11 @@ These docs expand on the short project README and are organized by the task a pr
 
 | Topic                                                | Use This When                                                                                                         |
 | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [Version Evolution](version-evolution.md)            | Understanding how Emulsify Core has evolved across major releases.                                                    |
 | [Component Authoring](component-authoring.md)        | Choosing Twig, React, or mixed Storybook authoring and comparing component examples.                                  |
 | [Storybook](storybook.md)                            | Rendering Twig stories, using `renderTwig()`, understanding Twig runtime helpers, and mixing Twig with React stories. |
 | [Project Structure And Output](project-structure.md) | Configuring `src/components`, root `./components`, `variant.structureImplementations`, and expected output paths.     |
 | [Platform Adapters](platform-adapters.md)            | Understanding `generic`, `drupal`, platform resolution order, and Drupal SDC behavior.                                |
 | [Extension Points](extension-points.md)              | Adding Vite plugins, Tailwind CSS, Storybook preview overrides, and other framework tooling.                          |
 | [Native Twig Extensions](native-twig-extensions.md)  | Using `bem()`, `add_attributes()`, and `switch/case/default/endswitch` in Twig.js.                                    |
-| [Migration To 4.x](migration-4x.md)                  | Upgrading from 3.x, preserving existing structures, and adopting Vite/React Storybook.                                |
+| [Migration](migration-4x.md)                         | Upgrading from earlier versions while preserving existing structures.                                                 |
diff --git a/docs/component-authoring.md b/docs/component-authoring.md
@@ -34,7 +34,7 @@ Storybook's Twig runtime supports Emulsify's native Twig helpers plus `include()
 
 ## React Component Libraries
 
-React components render through Storybook's React/Vite support. Storybook discovers React stories from the same normalized story roots as Twig stories. The shared Storybook globs include `*.stories.js`, `*.stories.jsx`, `*.stories.ts`, and `*.stories.tsx`; current release fixture coverage validates JavaScript/JSX stories.
+React components render through Storybook's React/Vite support. Storybook discovers React stories from the same normalized story roots as Twig stories. The shared Storybook globs include `*.stories.js`, `*.stories.jsx`, `*.stories.ts`, and `*.stories.tsx`; fixture coverage validates JavaScript/JSX stories.
 
 ```jsx
 import { Button } from './Button';
diff --git a/docs/extension-points.md b/docs/extension-points.md
@@ -122,7 +122,7 @@ Use preview head for markup needed inside the story iframe, such as fonts, meta
 
 ## Public Imports
 
-Emulsify Core 4.x exposes stable public package paths:
+Emulsify Core exposes stable public package paths:
 
 ```js
 import { renderTwig } from '@emulsify/core/storybook';
diff --git a/docs/migration-4x.md b/docs/migration-4x.md
@@ -1,15 +1,15 @@
-# Migration To 4.x
+# Migration To The Current Release
 
-Emulsify Core 4.x moves the build and component library stack from Webpack-era assumptions to Vite and React/Vite Storybook while preserving existing component structures.
+Emulsify Core now runs on Vite and React/Vite Storybook while preserving existing component structures. This guide is for projects upgrading from earlier Webpack-based versions.
 
 ## Requirements
 
 Use Node.js 24 or later. All maintained scripts run `scripts/check-node-version.js` before doing work.
 
-## What Changed
+## What Changed From Earlier Versions
 
 - Webpack has been replaced with Vite.
-- Storybook now uses `@storybook/react-vite`.
+- Storybook uses `@storybook/react-vite`.
 - Twig rendering remains supported through Emulsify's Twig integration.
 - React components are supported directly through Storybook's React/Vite setup.
 - Twig and React stories can coexist in the same Storybook instance.
@@ -30,7 +30,7 @@ Projects with `variant.structureImplementations` should keep that configuration
 
 ## Storybook Migration
 
-Storybook now runs on React/Vite. Twig stories still work, but imported Twig templates should be rendered with `renderTwig()` from `@emulsify/core/storybook`.
+Storybook runs on React/Vite. Twig stories still work, but imported Twig templates should be rendered with `renderTwig()` from `@emulsify/core/storybook`.
 
 ```js
 import template from './button.twig';
@@ -63,7 +63,7 @@ Drupal-specific Twig filters are only loaded when the Drupal adapter enables the
 
 ## Drupal Behavior
 
-Drupal-specific Storybook behavior now comes from the Drupal platform adapter. Generic and unknown platforms do not create or require a Drupal global by default.
+Drupal-specific Storybook behavior comes from the Drupal platform adapter. Generic and unknown platforms do not create or require a Drupal global by default.
 
 Drupal SDC mirroring remains supported for Drupal projects that enable `singleDirectoryComponents`.
 
diff --git a/docs/project-structure.md b/docs/project-structure.md
@@ -31,7 +31,7 @@ components/
     button.scss
 ```
 
-Projects using this structure do not need to create `src/` just to upgrade to 4.x. Generic builds emit into `dist/`; Drupal SDC mirroring happens only when the Drupal adapter enables it.
+Projects using this structure do not need to create `src/` just to use the current build system. Generic builds emit into `dist/`; Drupal SDC mirroring happens only when the Drupal adapter enables it.
 
 ### `variant.structureImplementations`
 
diff --git a/docs/storybook.md b/docs/storybook.md
@@ -1,6 +1,6 @@
 # Storybook
 
-Emulsify Core 4.x uses `@storybook/react-vite`. React components render directly through Storybook's React framework, and Twig templates render through Emulsify's Twig story helper.
+Emulsify Core uses `@storybook/react-vite`. React components render directly through Storybook's React framework, and Twig templates render through Emulsify's Twig story helper.
 
 ## Twig Stories
 
diff --git a/docs/version-evolution.md b/docs/version-evolution.md
@@ -0,0 +1,31 @@
+# Version Evolution
+
+Emulsify Core has always focused on one job: package the build, Storybook, linting, and component-library conventions that Emulsify projects need, while still giving individual projects room to extend those conventions.
+
+The current release keeps that goal and moves the implementation forward. It replaces the older Webpack-centered stack with Vite, uses React/Vite Storybook, supports Twig and React stories in the same library, and uses `project.emulsify.json` as the source of truth for platform and structure decisions.
+
+## 1.x: Shared Tooling Foundation
+
+The first major version established Emulsify Core as a reusable package instead of a set of copied project files. It bundled Storybook, Webpack, linting, a11y checks, Sass processing, Twig-related build support, asset handling, and project override hooks.
+
+That release made it practical for themes and standalone projects to consume shared Emulsify tooling from npm while still keeping project-specific configuration in the consuming project.
+
+## 2.x: Project Structure And Drupal SDC Support
+
+The second major version expanded how Emulsify Core handled project structure. It added better support for older component layouts, multi-level component directories, global and foundational asset processing, Storybook static directories, and Drupal-oriented SDC workflows.
+
+This version also continued dependency and Storybook upgrades while making more behavior configurable through project-level files. The important compatibility lesson from this era remains true: projects should not have to move working component directories just to keep using Emulsify Core.
+
+## 3.x: Runtime Modernization
+
+The third major version moved the package into a more modern JavaScript runtime model. It adopted ESM, raised the runtime floor to Node 24, kept dependencies current, refined PostCSS and Sass handling, improved component asset copying, and continued to preserve existing Drupal SDC behavior.
+
+It also set up the architectural runway for the current build model by cleaning up module scope, Storybook behavior, asset resolution, and package compatibility work.
+
+## Current Release: Vite, React/Vite Storybook, And Platform Adapters
+
+The current release is the next evolution of Emulsify Core. Vite replaces Webpack as the build engine. Storybook runs on the React/Vite framework. Twig templates render through Emulsify's Storybook helper, and React components render through normal Storybook React patterns.
+
+The project model is also more explicit. `project.emulsify.json` drives platform and structure configuration. The normalized structure model supports `src/components`, root `./components`, and custom `variant.structureImplementations`. Platform adapters own platform-specific behavior such as Drupal behavior attachment, Drupal Twig filters, and Drupal SDC output mirroring.
+
+That combination keeps existing Drupal and Twig-heavy projects viable while making Emulsify Core a better fit for generic Twig libraries, standalone React libraries, and mixed design systems. It is not a break from the project history; it is the same shared-tooling idea updated for the way modern component libraries are built.
