Components¶

How a storefront component is shared across the Nova-family themes instead of copied into each, and which components are shared so far. The admin has its own component layer and contract: Admin UI components. The token tiers these rules build on are in Foundations.

Why¶

Brock, Atelier, Depot, Pop and Spec each carried their own copy of the pager, sort dropdown, category nav, account status, mini basket and facet rail, mostly the same markup with the class prefix, icon file and message-key prefix renamed (Storefront inventory). A fix had to land five or six times, and the copies drifted (the mini basket's clear-basket confirmation exists only in Brock's). A shared component is one copy of the markup, re-skinned per theme through tokens.

The contract¶

Where it lives¶

• A shared component is a fragment in web-mvc/src/main/resources/templates/nova/ui/<component>.html. Nothing else lives in ui/.
• Themes never ship a ui/ file of the same name. The theme resolver would let one shadow the shared copy for every caller, which is the fork this contract exists to stop.
• The fragment's header comment is the contract: the signature, what each parameter means, what it needs on the model, its public tokens, its message keys and its variants. Keep it current in the same change as the markup.

Naming¶

• Classes are nova-<component> with BEM elements and is- states: nova-pager, nova-pager__summary, nova-pager__page.is-current.
• Styles live in Nova's bdgr.css, in the ui components section near the end, one sub-section per component headed /* --- ui: <component> (ui/<component>.html) --- */. Every Nova-family theme already loads bdgr.css, so nothing new is linked.
• A component built from classes the theme uses elsewhere too (the search bar, listing, product card and page shell: the theme's header form, collection page, product page and layout share them) takes the theme's CSS prefix as a pfx parameter and keeps those class names, styled in the theme's stylesheet, with a nova-<component> hook on its root. Its bdgr.css sub-section stays empty until those classes are tokenised.
• Thymeleaf reads two __ in one attribute as preprocessing, so a BEM class built in an expression must not share an attribute with another one: split it (th:class="${pfx} + '-card__img'" th:classappend="${pfx} + '-card__img--alt'") or resolve the block once in th:with (${now} + '__now').

Tokens¶

• Public tokens are --<component>-<property> (--pager-item-radius, --pager-current-bg). All are optional.
• Every rule in the sub-section reads a public token with a fallback: border-radius: var(--pager-item-radius, var(--radius-md)). The fallback is a semantic token where one fits, otherwise the value of the design the component replaced.
• When one value feeds several rules, resolve it once on the component root into --<component>c-<property> and read that (--pagerc-item-font, used by both page numbers and Previous / Next). This is how commerceTokens.html resolves --nb-* into --nbc-*.
• The rules are written only against the component's own tokens and semantic tokens. They never read a theme's private tokens (--d-ink), which don't exist in other themes.
• A theme re-skins the component by setting its tokens on :root or on the component's root class (every pager theme uses .nova-pager { --pager-…: … }), never by restyling the component's selectors.

Parameters, not forks¶

What genuinely differs between themes is passed in:

• A null prefix means the shared ui.<family>.* keys (ui.pager.summary). Add those to messages.properties with the component.
• Passing the theme's prefix keeps merchants' existing Site Text overrides (of depot.pager.summary, say) working with no data change. Don't rename a theme's keys to share a component.
• Data comes from the same model the theme's fragment used (PaginationParams for the pager). A shared component adds no model attributes and calls no beans, like every storefront template.

Theme delegates¶

Nova's templates call fragment/pagination, so each theme's old fragment file stays as a one-line delegate: same file name, same fragment name and signature, no markup.

<th:block th:fragment="pagination(pagParams)"
          th:insert="~{ui/pager :: pager(${pagParams}, 'fragment/depot-icons', 'depot')}"></th:block>

The delegate is still needed because it shadows Nova's own fragment/pagination.html, which is a different design. Its header comment says which icons and keys it passes and where its tokens are set. A theme layered on a theme with a delegate (Bistro on Brock) inherits it and needs no file.

No visual change¶

Sharing a component must not change how any theme looks. Compare screenshots of every theme that used the old copy, before and after, at phone and desktop widths; once the pattern library (/system/patterns) exists, take them from its fixtures. Any difference is a bug unless the merge request lists it. Behaviour that had drifted between copies (a missing guard, a missing confirmation) is fixed in the same change only when the MR says so.

Adding a shared component¶

The pager is the worked example (ui/pager.html, the "ui: pager" sub-section of bdgr.css).

1. Pick one from the inventory. Take a component whose copies are a rename of each other (a residual of a few lines in Storefront inventory). The pager's five copies differed by one comment line.
2. Write ui/<component>.html from the baseline copy (Brock's, for the Brock family). Rename classes to nova-<component>__*, replace the theme's key prefix with the keys parameter (#{__${k}__.pager.summary(...)}, with k = keys ?: 'ui') and the icon file with the icons parameter (~{__${icons}__ :: chevronLeft(null)}). Write the header comment.
3. Add the shared keys (ui.pager.summary, .label, .previous, .next, .page) to messages.properties with the baseline's English. Keep screen-reader text (aria-label) on keys too (Storefront text).
4. Write the CSS sub-section in bdgr.css, every property through var(--<component>-<property>, fallback), with fallbacks that reproduce the baseline's look.
5. Move each theme's values into tokens. Turn the theme's old rules for the component into one token block (.nova-pager { --pager-item-border: 1.5px solid var(--b-line); … }) and delete the old selectors. Depot's block also switches the layout (--pager-display: flex, --pager-justify: space-between), which is why layout properties are tokens too.
6. Replace each theme's fragment with a delegate that passes its icons and key prefix.
7. Check for no visual change in every affected theme, and update the catalogue below.
8. Update the guard tests' lists: remove the theme files that became delegates from theme-forks.txt, add a pattern fixture if none renders the component, and lower any baseline the ratchet reports.

Guard tests¶

Plain JUnit tests in web-mvc (no Spring context) that keep the contract from eroding. Their lists live in one place each, so a change that shares a component updates them in the same MR.

Renames and custom CSS¶

Sharing a component renames the themes' classes (brock-footer__base became nova-sitefooter__base, the *-btn families became nova-button), and tenants' stored custom CSS ($cssOverride$/global.css, see Site customisation) was written against the old names. Three things keep it working:

• The map. commerce-core/src/main/resources/design/class-renames.json lists every class, id and data attribute the shared components removed from storefront markup, old name to new name, grouped by the theme that used it. It was derived by rendering every pattern fixture with the templates from before and after and pairing each element's lost classes with its gained ones, then checking each pair against the templates. A value that is a list means one old name now reads as several (brock-facet__count is the facet rail's nova-facetrail__count and the category navigation's nova-cat-nav__count); a list that keeps the old name means the class is still used elsewhere (brock-stepper in the full basket). ClassRenamesTest fails when a renamed name comes back into a template or theme script, or a new name disappears.
• The rewrite. CssClassRenamer renames names in selectors only (rule preludes, nested rules, @media/@supports/@layer blocks), never in declarations, strings, url()s, comments or @keyframes, whole identifiers only, and is idempotent. The RenameClassesInCustomCss system update ran it over every site's stylesheet and bumped css-override-version; MCP manageBranding setCustomCss runs it on save and lists what it renamed in customCss.notes. The admin CSS editor saves what it's given.
• Inline styles. JSON components style through nova-jc-* classes now, so a selector on the style attribute (.json-container[style*="shadow"]) can't be rewritten. The site setting json-component-inline-styles makes the resolver write the old inline styles again beside the classes (SemanticTokenResolverInlineStylesTest checks they equal the old output); the update turned it on for sites whose CSS has such selectors.

When a change renames storefront classes, add the pairs to class-renames.json and ship a new dated system update that runs RenameClassesInCustomCss again (it only touches stylesheets that use a mapped name). Hero, scene and email-capture inline styles moved to classes and tokens too; their class names didn't change, but a selector on their old style attribute no longer matches and nothing restores it.

Catalogue¶

Every storefront component family from the Storefront inventory, with its status. This table is updated in the same change that shares a component (or decides a family stays with the themes).

Nova fragments that no theme forks (breadcrumb, responsive-image, search-form, quick-filters, icons and the rest listed in the inventory) are already single copies. They move into ui/ only when a theme needs to re-skin one. The basket and checkout are also single copies, re-skinned through the --nb-* tokens in fragment/commerceTokens.html.