docs!: polish 7.x release and Starterkit messaging

Clarify Drupal 11.3+ support and Drupal 12 forward compatibility.

Document known breaking changes and favicon deployment ownership.

Use child theme and parent theme language consistently.

Author: Callin Mullaney

README.md

@@ -4,11 +4,11 @@
 
 ## Emulsify is an open-source toolset for creating and implementing design systems on your website
 
-### Storybook development, Vite build, and Drupal 11.3 / Drupal 12.x theme
+### Storybook, Emulsify Core 4, and a Vite-based build workflow for Drupal 11.3+
 
-**Emulsify Drupal** provides a [Storybook](https://storybook.js.org/) component library, a [Vite](https://vite.dev/) development environment, and a starter kit theme that supports Drupal 11.3.x and Drupal 12.x.
+**Emulsify Drupal** provides a [Storybook](https://storybook.js.org/) component library, Emulsify Core 4 tooling, and a [Vite](https://vite.dev/)-based build workflow for Drupal 11.3+ with Drupal 12 forward compatibility. Until Drupal 12 beta or stable recommended-project releases are available, Drupal core development branch coverage is experimental.
 
-The current 7.x series no longer depends on `stable9`; Emulsify now ships its own complete template layer instead of inheriting one from a Drupal base theme.
+The current 7.x series no longer depends on `stable9`; Emulsify now ships its own complete template layer instead of inheriting one from a Drupal parent theme.
 
 ## Documentation
 
@@ -20,6 +20,7 @@ The current 7.x series no longer depends on `stable9`; Emulsify now ships its ow
 2. [Usage](https://www.emulsify.info/docs/emulsify-drupal/basic-usage/commands)
 3. [Upgrade guide](./UPGRADE.md)
 4. [Template override map](./docs/template-map.md)
+5. [Favicon generation lifecycle](./docs/favicon-generation.md)
 
 ## Demo
 
@@ -29,7 +30,7 @@ The current 7.x series no longer depends on `stable9`; Emulsify now ships its ow
 
 ### Generate a child theme
 
-If `emulsify_tools` is installed, you can generate a subtheme with the helper-module Drush command:
+If `emulsify_tools` is installed, you can generate a child theme with the helper-module Drush command:
 
 ```bash
 drush emulsify my_theme
@@ -41,7 +42,7 @@ The helper module also exposes the fully qualified command name:
 drush emulsify_tools:bake my_theme
 ```
 
-You can also generate the same subtheme with Drupal core's standard Starterkit command from the root of your Drupal site:
+You can also generate the same child theme with Drupal core's standard Starterkit command from the root of your Drupal site:
 
 ```bash
 php web/core/scripts/drupal generate-theme my_theme --starterkit whisk --path themes/custom
@@ -82,17 +83,26 @@ Do not enable `whisk` directly. It is a generation-only starter source.
 
 The generated favicon workflow is built around one portable SVG source stored in theme settings.
 
-1. Save the theme settings form to generate or update the package during normal admin changes.
-2. After configuration import or deploy, regenerate missing package files with `drush emulsify_tools:favicon-generate [theme_name]` before public traffic reaches the environment.
-3. Use `drush emulsify_tools:favicon-status [theme_name]` to inspect dependency, package, and portable-source status, or use the theme settings UI for package and source diagnostics.
-4. Use `drush emulsify_tools:favicon-reset [theme_name]` if you need to remove generated assets and restore the theme default favicon behavior.
+Emulsify Drupal owns the theme-facing parts of that workflow: the theme settings form, config defaults and schema, admin previews, frontend head tags, generated asset references in `<theme>.settings`, and sanitized SVG storage for config portability.
 
-Runtime generation remains a lock-protected fallback if a request reaches an environment before deployment tasks regenerate the package. Fallback failures are logged and do not break page rendering.
+1. Configure the package in the theme settings form for `emulsify` or an Emulsify child theme.
+2. Save the theme settings form to generate or update the package during normal admin changes.
+3. Review package and portable-source diagnostics in the theme settings UI.
+
+Emulsify Tools owns deployment-oriented Drush operations for those same
+settings. After configuration import or deploy, use the Emulsify Tools favicon
+commands to generate, inspect, or reset environment-local package files before
+public traffic reaches the environment. See the Emulsify Tools README for the
+full command documentation.
+
+Runtime page requests never generate favicon files. If the configured package is missing, Emulsify skips favicon head tags until the theme settings form or the Emulsify Tools generate command creates the package.
 
 Generated favicon packages require the PHP `gd` extension and the `Imagick` extension for SVG rasterization. If either extension is unavailable, the uploaded SVG can still be stored in configuration, but PNG and ICO package generation will fail until those extensions are installed.
 
 The theme settings UI surfaces the current portable-source and package status. Portable SVG copies larger than 256 KB are flagged because very large config payloads are awkward to review and deploy.
 
+See [docs/favicon-generation.md](./docs/favicon-generation.md) for generated files, package location, generator limits, and deployment expectations.
+
 ## Contributing
 
 ### [Code of Conduct](https://github.com/emulsify-ds/emulsify-drupal/blob/main/CODE_OF_CONDUCT.md)
@@ -117,13 +127,13 @@ To facilitate automatic semantic release versioning, we utilize the [Conventiona
 
 ### Release Readiness
 
-Run the release guard before merging packaging or starterkit changes:
+Run the release guard before merging packaging, starterkit, favicon settings, or release metadata changes, and before preparing a 7.x release:
 
 ```bash
 npm run release:check
 ```
 
-Use `npm run release:check -- --skip-smoke` when you only want the static metadata, README, duplicate-script, and schema checks.
+Use `npm run release:check -- --skip-smoke` when you only want the static metadata, README, duplicate-script, and schema checks. The static checks verify that favicon settings stay aligned across `FaviconSettings::DEFAULTS`, `config/install/emulsify.settings.yml`, and `config/schema/emulsify.schema.yml`.
 
 ## Author
 

UPGRADE.md

@@ -2,38 +2,60 @@
 
 Emulsify 7.x is a breaking release. Plan the upgrade as a theme-platform change, not a patch-level update.
 
+## Known Breaking Changes
+
+- Drupal 10 support is removed.
+- Drupal 11.3+ is required.
+- Drupal 12 compatibility is forward-looking until Drupal 12 beta or stable releases are available.
+- The Stable9 parent theme is removed.
+- Emulsify now uses `base theme: false`.
+- The `drupal/components` dependency is removed.
+- `drupal/emulsify_tools:^2.0` is required.
+- Generated child theme frontend workflow moved from Webpack to Vite.
+- Generated child themes use Emulsify Core 4.
+- Whisk is now a Starterkit source and should not be enabled directly.
+- Favicon handling now uses a generated package workflow.
+- Favicon generation happens on theme settings save or through Emulsify Tools Drush commands, not on normal page requests.
+- Hook implementations moved to Drupal 11.3+ `#[Hook]` attributes.
+- Legacy 6.x procedural hook include behavior is removed.
+
 ## Requirements
 
-- Drupal 11.3 through Drupal 12.x is supported.
-- Drupal 10 is no longer supported.
+- Drupal 11.3+ is supported.
+- Drupal 12 forward compatibility is included through the `^11.3 || ^12` core constraint.
+- Drupal core development branch coverage is experimental until Drupal 12 beta or stable releases are available.
+- Drupal 10 is no longer supported in 7.x.
 - `drupal/emulsify_tools:^2.0` is required by both `composer.json` and `emulsify.info.yml`.
 
 ## Package Changes
 
 - The old `drupal/components` dependency is gone.
-- Frontend workflow references should move from Webpack-era commands and docs to the Vite-based workflow shipped in 7.x.
-- `whisk` remains a starter source only. Do not enable it as a runtime base theme.
+- Frontend workflow references should move from Webpack-based build workflow commands and docs to the Vite-based build workflow shipped in 7.x.
+- `whisk` remains a starter source only. Do not enable it as a runtime parent theme.
 
 ## Theme Architecture Changes
 
-- `stable9` is no longer the base theme. Emulsify now ships its own full template layer.
+- `stable9` is no longer the parent theme. Emulsify now ships its own full template layer.
 - Generated child themes should keep `emulsify` as their parent theme.
 - If you generated a child theme in the 6.x era, review any copied Twig overrides against the 7.x template surface before carrying them forward.
 - The current template parity inventory is documented in [docs/template-map.md](docs/template-map.md).
 
 ## Recommended Upgrade Path
 
-1. Update the site to Drupal 11.3 or any Drupal 12 release.
+1. Update the site to Drupal 11.3 or a newer Drupal 11 release before moving to Emulsify 7.x.
 2. Require `drupal/emulsify_tools:^2.0`.
-3. Update the Emulsify base theme to 7.x.
+3. Update the Emulsify parent theme to 7.x.
 4. Regenerate or review custom child themes so they inherit from `emulsify`, not `stable9` or `whisk`.
-5. Move frontend build and local-development docs, scripts, and team habits from Webpack terminology to Vite.
-6. Run the release-readiness checks before merge: `npm run release:check`.
+5. Move frontend build and local-development docs, scripts, and team habits from Webpack-based build workflow terminology to the Vite-based build workflow.
+6. Run the release-readiness checks before merge or release: `npm run release:check`. The static release gate verifies that favicon defaults, install config, and schema keys stay in sync.
 
 ## Favicon Migration Notes
 
 - Favicon settings now store a portable sanitized SVG source in theme config.
-- Generated favicon packages are environment-local build artifacts. After config import or deploy, regenerate them with `drush emulsify_tools:favicon-generate [theme_name]`.
-- Use `drush emulsify_tools:favicon-status [theme_name]` to inspect the current package and source state.
-- Use `drush emulsify_tools:favicon-reset [theme_name]` to remove generated assets and return to the default theme favicon behavior.
+- Emulsify Drupal owns the theme settings UI, config defaults and schema, admin previews, frontend head tags, generated asset references, and portable source storage.
+- Configure or update favicons in the theme settings form for `emulsify` or an Emulsify child theme.
+- Generated favicon packages are environment-local build artifacts. After config import or deploy, use Emulsify Tools to regenerate them with `drush emulsify_tools:favicon-generate [theme_name]`.
+- Emulsify Tools owns the full favicon Drush command documentation for `emulsify_tools:favicon-generate`, `emulsify_tools:favicon-status`, and `emulsify_tools:favicon-reset`.
+- Runtime page requests do not generate missing favicon package files.
 - PNG and ICO generation require the PHP `gd` extension and the `Imagick` extension.
+- Generated files, package location, source limits, and deployment expectations are documented in [docs/favicon-generation.md](docs/favicon-generation.md).

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "emulsify-ds/emulsify-drupal",
-    "description": "The official Drupal base theme for Emulsify that generates custom themes with Storybook development + Vite Build",
+    "description": "The official Drupal theme for Emulsify, with Storybook and a Vite-based build workflow for generated child themes",
     "type": "drupal-theme",
     "homepage": "http://emulsify.info",
     "license": "GPL-2.0-only",

emulsify.info.yml

@@ -1,6 +1,6 @@
 name: Emulsify
 type: theme
-description: The official base theme for Emulsify and its flexible component-driven development.
+description: The official Drupal parent theme for Emulsify component-driven development.
 base theme: false
 core_version_requirement: '^11.3 || ^12'
 package: emulsify

package.json

@@ -1,7 +1,7 @@
 {
   "name": "emulsify-drupal",
   "version": "7.0.0",
-  "description": "Storybook development + Vite Build + Drupal 11.3-12.x theme",
+  "description": "Storybook, Emulsify Core 4, and a Vite-based build workflow for Drupal 11.3+ with Drupal 12 forward compatibility",
   "keywords": [
     "component library",
     "design system",

templates/layout/page.html.twig

@@ -4,7 +4,7 @@
  * Theme override to display a single page.
  *
  * This keeps Emulsify's page-level wrapper owned by the parent theme so
- * generated subthemes do not need to rely on stable9 for the default page
+ * generated child themes do not need to rely on stable9 for the default page
  * structure.
  *
  * @see template_preprocess_page()

whisk/package.json

@@ -1,7 +1,7 @@
 {
   "name": "whisk",
   "version": "1.0.0",
-  "description": "Storybook development + Vite Build",
+  "description": "Storybook and a Vite-based build workflow powered by Emulsify Core 4",
   "keywords": [
     "component library",
     "design system",

whisk/whisk.info.emulsify.yml

@@ -3,7 +3,7 @@ base theme: emulsify
 core_version_requirement: '^11.3 || ^12'
 
 name: whisk
-description: A subtheme build upon the Emulsify Design System.
+description: A child theme built upon the Emulsify Design System.
 package: 'Emulsify'
 screenshot: screenshot.png
 version: VERSION

whisk/whisk.info.yml

@@ -3,7 +3,7 @@ base theme: emulsify
 core_version_requirement: '^11.3 || ^12'
 
 name: Whisk Starter
-description: Generation-only starter source for Emulsify subthemes.
+description: Generation-only starter source for Emulsify child themes.
 package: 'Emulsify'
 screenshot: screenshot.png
 hidden: true

whisk/whisk.starterkit.yml

@@ -1,4 +1,8 @@
+# Drupal validates starterkit path patterns against files that exist in the
+# source theme. Keep optional files out of these rules until they are committed.
 ignore:
+  # Starter-only files are used by Emulsify Drupal or Drupal core generation and
+  # should not be copied into generated child themes.
   - '/.DS_Store'
   - '/assets/.DS_Store'
   - '/config/.DS_Store'
@@ -7,5 +11,17 @@ ignore:
   - '/whisk.info.emulsify.yml'
   - '/whisk.starterkit.yml'
 
+no_edit:
+  # These files are copied as build/tooling inputs. Automatic starterkit content
+  # replacement can corrupt package-managed config or binary data.
+  - '/config/emulsify-core/**'
+  - '/screenshot.png'
+
+no_rename:
+  # Emulsify Core config paths are tool conventions, not theme machine-name
+  # conventions, and should remain stable in generated themes.
+  - '/config/emulsify-core/**'
+
 info:
+  core_version_requirement: '^11.3 || ^12'
   hidden: null