Rename component -title/-subtitle classes to -heading/-subheading (#668) - #1136
Open
stephaniehobson wants to merge 2 commits into
Open
stephaniehobson wants to merge 2 commits into
stephaniehobson wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
A few updated files still contain inconsistencies with established repo conventions (e.g., Sass declaration ordering and outdated “title” terminology in nearby comments/identifiers) that should be corrected before merging.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR completes the “component class” portion of the -title → -heading rename across Protocol’s component templates, component Sass, and the menu JS behavior, plus adds migration guidance for consumers.
Changes:
- Renamed component CSS classes from
*-title/*-subtitleto*-heading/*-subheadingacross relevant Nunjucks templates and Sass component styles. - Updated
assets/js/protocol/menu.jsand its unit tests to use the new.mzp-c-menu-headingselector. - Added migration doc “find/replace” recipes and updated Sass base imports to use
headingsinstead oftitles.
File summaries
| File | Description |
|---|---|
| tests/unit/menu.js | Updates fixture markup and selectors to .mzp-c-menu-heading for menu behavior tests. |
| docs/02-usage/migration.md | Adds consumer-facing find/replace recipes for component class renames. |
| components/sticky-promo/sticky-promo.html | Renames sticky promo title class to heading in template markup. |
| components/sidebar-menu/sidebar-menu.html | Renames sidemenu title class to heading in template markup. |
| components/newsletter/newsletter.html | Renames newsletter title class to heading in template markup. |
| components/newsletter/newsletter--success.html | Renames newsletter title class to heading in success variant markup. |
| components/newsletter/newsletter--errors.html | Renames newsletter title class to heading in error variant markup. |
| components/navigation/03-menu-item/menu-item.html | Renames menu-item title class to heading in component markup. |
| components/navigation/02-menu/menu.html | Renames menu title class to heading in menu markup examples. |
| components/menu-list/menu-list.html | Renames menu-list title class to heading and updates MzpDetails.init() selector. |
| components/forms/example-form/example-form.html | Updates form header and legend classes to heading/subheading. |
| components/forms/12-form-header/form-header.html | Updates form header title class to heading. |
| components/forms/07-titles/titles.html | Removes the old “titles” example markup. |
| components/forms/07-titles/readme.md | Removes the old “titles” documentation. |
| components/forms/07-headings/readme.md | Adds replacement documentation for form headings/subheadings. |
| components/forms/07-headings/headings.html | Adds replacement example markup for form headings/subheadings. |
| components/card/card.html | Renames card title class to heading in template markup. |
| components/callout/callout.html | Renames callout title class to heading in template markup. |
| components/callout/callout--example.html | Renames callout title class to heading in example markup. |
| components/billboard/billboard.html | Renames billboard title class to heading in template markup. |
| components/article/article.html | Renames article title class to heading in template markup. |
| assets/sass/protocol/protocol.scss | Switches base utilities import from titles to headings. |
| assets/sass/protocol/components/forms/_form.scss | Renames form title/subtitle selectors to heading/subheading. |
| assets/sass/protocol/components/_sticky-promo.scss | Renames sticky promo title selectors to heading in component styles. |
| assets/sass/protocol/components/_sidebar-menu.scss | Renames sidemenu title selector to heading in component styles. |
| assets/sass/protocol/components/_newsletter-form.scss | Renames newsletter title selector to heading in component styles. |
| assets/sass/protocol/components/_menu.scss | Renames menu title selectors to heading in component styles. |
| assets/sass/protocol/components/_menu-list.scss | Renames menu-list title selectors to heading in component styles. |
| assets/sass/protocol/components/_menu-item.scss | Renames menu-item title selectors to heading in component styles. |
| assets/sass/protocol/components/_card.scss | Renames card title selectors to heading in component styles. |
| assets/sass/protocol/components/_callout.scss | Renames callout title selectors to heading in component styles. |
| assets/sass/protocol/components/_billboard.scss | Renames billboard title selectors to heading in component styles. |
| assets/sass/protocol/components/_article.scss | Renames article title selector to heading in component styles. |
| assets/sass/protocol/base/utilities/_headings.scss | Updates base utility file naming/commenting for heading utilities. |
| assets/sass/protocol/base/elements/_headings.scss | Adds/renames base element styling for h1–h6 under headings. |
| assets/sass/protocol/base/_elements.scss | Switches base element import from titles to headings. |
| assets/js/protocol/menu.js | Updates menu behavior selectors from .mzp-c-menu-title to .mzp-c-menu-heading. |
Review details
- Files reviewed: 36/37 changed files
- Comments generated: 6
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
stephaniehobson
added this pull request to stack #1151
September 11, 2026 21:44
stephaniehobson
marked this pull request as ready for review
September 16, 2026 20:53
There was a problem hiding this comment.
🔵 Needs a closer look
Migration documentation and changelog follow-ups remain unresolved.
Review details
Suppressed comments (5)
Previously missed (3) — in code that hasn't changed since the last review.
docs/02-usage/migration.md:51
- This is a breaking public class rename, but
CHANGELOG.mdstill says the component HTML/CSS renames will happen in a separate PR and has no entry for these changes. Please add the v23 release note and update/remove that stale statement so consumers are warned about the migration.
docs/02-usage/migration.md:257 - These new migration commands use
sed -i '', which is BSD/macOS syntax; GNUsedon Linux rejects it even though this section is labeled “macOS/Linux” (line 225). Use a portable form such assed -i.bakor provide separate platform-specific commands, and apply the same correction to the class-rename commands below.
docs/02-usage/migration.md:262 - The rename also changes JavaScript selectors (
assets/js/protocol/menu.js), but this terminal recipe only rewrites HTML/Nunjucks/SCSS. Consumers with custom JavaScript (or a vendored Protocol tree) will retain the old selector and can break menu behavior; include JavaScript files so the migration covers every affected source type.
docs/02-usage/migration.md:51
- The PR also removes the
base/elements/_titles.scssandbase/utilities/_titles.scssSass partial paths, but this migration section only replaces class strings. Consumers who import either old partial directly will get a missing-module error after upgrading; document the file/import renames and include them in the migration instructions.
docs/02-usage/migration.md:257 - The form subheading rename has the same gap as the title recipe: JavaScript files are not included, even though this migration changes a public class name that consumer scripts may query. Add the script-file replacement here as well so the terminal instructions are consistent for both renamed form classes.
- Files reviewed: 36/37 changed files
- Comments generated: 0 new
- Review effort level: Lite
Finishes the component-class half of the title -> heading rename that PR") -- the branch that originally held this work no longer exists, so this redoes it against current main. Mixins, utility classes, and CSS vars were already renamed in #1107; this covers the remaining 12 component-level BEM classes across Article, Billboard, Callout, Card, Form, Menu, Menu Item, Menu List, Newsletter, Sidebar Menu, and Sticky Promo: mzp-c-menu-title -> mzp-c-menu-heading mzp-c-form-title -> mzp-c-form-heading mzp-c-form-subtitle -> mzp-c-form-subheading mzp-c-card-title -> mzp-c-card-heading mzp-c-menu-item-title -> mzp-c-menu-item-heading mzp-c-callout-title -> mzp-c-callout-heading mzp-c-sticky-promo-title -> mzp-c-sticky-promo-heading mzp-c-newsletter-title -> mzp-c-newsletter-heading mzp-c-menu-list-title -> mzp-c-menu-list-heading mzp-c-sidemenu-title -> mzp-c-sidemenu-heading mzp-c-billboard-title -> mzp-c-billboard-heading mzp-c-article-title -> mzp-c-article-heading Clean break, no aliases, per the naming issue's own note that this is a breaking rename (#668). Also: - Renamed the two already-heading-only-content files that still had the stale filename: base/elements/_titles.scss and base/utilities/_titles.scss -> _headings.scss (updated their @use sites and kept the alphabetical @use ordering in _elements.scss and protocol.scss) - Renamed the forms/07-titles component directory and titles.html to 07-headings/headings.html; reworded its readme, which still said "titles (aka headings)" - Updated the 8 .mzp-c-menu-title selectors in assets/js/protocol/menu.js - Fixed tests/unit/menu.js's fixture markup, which still built a .mzp-c-menu-title element -- missed by a first pass that only searched assets/ and components/ - Extended docs/02-usage/migration.md with find/replace recipes for this rename, matching the existing style docs/03-contributing/02-naming.md's example already used -heading/-desc and needed no change here. Verified: npm run lint, npm test (47 specs, Firefox + Chrome), npm run build-docs (523 items, no errors -- confirmed the renamed forms/headings component renders with the new classes), and npm run build-package all pass.
stephaniehobson
force-pushed
the
v23/heading-classes
branch
from
September 16, 2026 23:05
46299c1 to
b401207
Compare
stephaniehobson
added a commit
that referenced
this pull request
Sep 16, 2026
#668) Documentation-site only -- these are Fractal demo templates in components/*.html, not shipped in the npm package (AGENTS.md: 'docs/ exist for the documentation site, not the shipped package'). Consumers hand-write their own markup using the compiled classes; they don't call these render() functions, so this has zero impact on downstream projects. That's also why it needs no migration.md entry, unlike C1's actual CSS class renames. title -> heading title_el -> heading_el title_class -> heading_class Affects: Billboard, Callout, Card, Card Layout, Menu, Picto, Section Heading, Sticky Promo, Zap. Found and fixed a real, pre-existing bug as a side effect: Picto's config.yml already used `heading:` as its context key (has for a long time -- confirmed via git log), but picto.html's template still consumed `title`/`title_el`, so the config's example heading text was silently ignored and the Fractal preview rendered an empty heading. Renaming the template to match fixes it -- verified in the built docs output. Also updated prose in two component readmes (menu-item, sticky-promo) and one demo (form-header.html's 'Form Title' -> 'Form Heading') that directly described their own just-renamed heading elements by the old name. Left generic English usage of "title" alone elsewhere (e.g. the heading/heading-sizes readmes' 'a heading acts as a title for...', sidebar-menu's placeholder link text) -- that's not describing a renamed API surface. Explicitly out of scope, left for a separate follow-up (user decision): MzpModal.createModal() and MzpNotification.init() both take a real, shipped JS API option called `title` (assets/js/protocol/modal.js, notification-bar.js) that renders as heading text. That's a breaking public JS API change with real consumer impact, not a docs-only rename, so it doesn't belong bundled into this low-risk commit -- left modal.html, notification-bar--scripted.html, and their readmes untouched. Stacked on #1136 (v23/heading-classes). Part of #1084. Verified: npm run lint, npm test (47 specs, Firefox + Chrome), and npm run build-docs (523 items, no errors) -- confirmed in the built output that Picto, Card, Callout, Billboard, Section Heading, Zap, Menu, and Card Layout all render their heading content correctly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Finishes the component-class half of the title -> heading rename that #1107 deferred.
Issue
#668
Testing
CHANGELOG.md.