Theme Engine and Tailwind v4
Relevant source files
The following files were used as context for generating this wiki page:
The Theme Engine is a multi-tenant styling system designed to provide a consistent yet customizable visual experience across different shops. It leverages Tailwind CSS 4's native support for CSS variables to bridge the gap between hardcoded platform defaults and per-tenant branding. By utilizing Theme Tokens, the engine allows operators to customize colors, radii, and spacing without requiring a code redeploy.
The system is architected around a "semantic token layer" (P3-3) which maps technical platform tokens to descriptive aliases. This allows the storefront to remain "tenant-themeable" while maintaining accessibility standards like WCAG AA contrast ratios by default.
Sources: CONTEXT.md:143-155, apps/storefront/src/design-tokens.gate.test.ts:13-20
Architecture and Data Flow
The theme engine operates on a cascading resolution logic that ensures every shop has a valid visual configuration, even if they have not provided custom branding.
The Setting Cascade
Theme resolution follows a specific hierarchy known as the Setting Cascade. This last-write-wins approach starts with platform defaults and applies overrides as they are defined in the Shop record.
The diagram above shows how theme tokens and component settings are resolved through various tiers of the platform.
Sources: CONTEXT.md:173-182, CONTEXT.md:162-171
CSS Variable Injection
The system injects theme data into the browser using CSS custom properties (variables). This integration is particularly deep with Tailwind v4, where standard Tailwind theme variables are pinned to specific defaults to ensure the redeclaration remains inert until a shop provides an override.
| Variable Category | Description | Example Tokens |
|---|---|---|
| Typography Scale | Pinned to Tailwind v4 defaults (xs, sm, base, lg, xl). | --text-xs: 0.75rem |
| Font Weights | Pinned to standard weights (normal: 400, bold: 700). | --font-weight-bold: 700 |
| Semantic Aliases | Maps platform tokens to functional UI roles. | --surface-1: var(--color-block) |
| Accent Colors | Shop-specific brand colors with fallback values. | --accent-primary: #073b4c |
Sources: apps/storefront/src/app/globals.test.ts:11-30, apps/storefront/src/app/globals.test.ts:44-59
Design Tokens and Semantic Layer
The platform utilizes a "P3-3" semantic token layer to decouple component styling from raw color values. This prevents "unmigrated oversights" where hardcoded Tailwind classes (e.g., bg-white) might bypass the theme engine.
Semantic Mapping
The storefront defines several core semantic tokens that components consume. These tokens are wired to platform color or shadow tokens.
- Surface Tokens:
--surface-1(base),--surface-2(raised),--surface-3(sunken). - State Tokens:
--state-sale,--state-danger,--state-success,--state-info. - Elevation Tokens:
--elevation-1(card shadow),--elevation-2(hover),--elevation-3(panel).
Sources: apps/storefront/src/app/globals.test.ts:44-59, apps/storefront/src/design-tokens.gate.test.ts:13-20
Accessibility and Contrast (WCAG AA)
The theme engine enforces a strict "lint gate" to ensure that the platform-default values for semantic tokens meet WCAG 2.1 AA contrast requirements. This includes specific remedies for challenging color combinations, such as using a darker success color (--color-block-success-dark) for normal-weight text on a success background.
| Token Pair | Contrast Ratio | WCAG Status |
|---|---|---|
--text-muted on --surface-1 | ≥ 4.5:1 | Pass (Normal AA) |
--state-sale on white | ≥ 4.5:1 | Pass (Normal AA) |
White on --state-success | ~3.43:1 | Pass (Large/Bold only) |
--text-success-strong on --surface-success | ≥ 4.5:1 | Pass (Normal AA) |
Sources: apps/storefront/src/design-tokens.gate.test.ts:135-175, apps/storefront/src/design-tokens.gate.test.ts:187-200
Implementation Details
Tailwind v4 Integration
Tailwind CSS 4 is used as the primary styling framework across the storefront and admin apps. The integration relies on SCSS modules and CSS variables defined in globals.css.
/* Example of pinning Tailwind v4 defaults in globals.css */
:root {
--text-xs: 0.75rem;
--text-sm: 0.875rem;
--text-base: 1rem;
--font-weight-normal: 400;
--font-weight-bold: 700;
}
Sources: apps/storefront/src/app/globals.test.ts:11-25, apps/storefront/README.md:14-25
Shared Design Primitives
Marketing surfaces (Landing and Admin apps) share design primitives through the @nordcom/commerce-marketing-common package. This package provides a shared Nordstar Theme to ensure visual consistency.
// Shared Theme structure in marketing-common
{
accents: {
primary: '#ed1e79',
secondary: '#ed1e79',
},
fonts: {
heading: 'var(--font-primary)',
body: 'var(--font-primary)',
},
}
Sources: packages/marketing-common/README.md:1-25
The Customization Hub
Operators manage theme settings through the Customization Hub in the Admin app. This interface allows for editing:
- Theme Tokens: Scalar styling values like colors, sizes, and radii.
- Component Settings: Behavioral choices such as product-card variants.
- Section Visibility: Toggling regions like the header or footer.
Changes are stored in the Shop extension manifest. Modifications follow a "Save Draft → Publish" flow, ensuring that theme updates are staged and previewed before reaching the live Storefront.
Sources: CONTEXT.md:188-197, CONTEXT.md:143-155