Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/theme-and-design

theme-and-design

Verified

Customize the visual appearance of a Liferay site using themeCSS client extensions, master pages, and style books. Use when the user asks to change colors or fonts, create a theme, set up a style book, define a master page header/footer, or apply WCAG accessibility guidelines.

Theme and Design

Three layers control a site's look and feel. Apply them in this order: themeCSS (base variables and overrides), style book (token values per site), master page (header/footer layout).

When iterating on a site built from a site initializer, theme changes apply live via blade gw deploy of the themeCSS CET — no site reprovision needed (see rules/site-initializer-format.md).

When to Invoke

  • "Change the site colors", "apply a brand theme", "create a custom theme"
  • "Set up a style book with our design tokens"
  • "Define a header and footer for all pages"
  • "Create a dark variant of the site"
  • Called by build-site when the user specifies visual design requirements

Workflow

Layer 1: themeCSS Client Extension

A themeCSS CET injects custom CSS that overrides Clay Design System variables. This replaces the legacy Liferay theme WAR.

Prefer it for a site's look. Ship the brand, its colors, typography, and CSS across the site, in a themeCSS CET bound in the master page's settings, rather than only in style book values, fragment CSS, or edits on the running site. The CET is reviewable, versioned, and survives reprovision, and it keeps the brand in one place. Bind a style book alongside it for the values editors should be able to tune (see Layer 2).

Two constraints to settle before writing any CSS.

  1. It needs its own project. themeCSS is classified frontend; a siteInitializer is batch, and the workspace plugin forbids that combination. The theme is always a sibling project — see rules/client-extension-types.md → "Which Types May Share a Project".

  2. It is applied from the initializer tree through the master page, not metadata.json. layout-set/*/metadata.json has no key for a client extension, but the master page's page-definition.json carries a top level settings.themeCSSClientExtension block whose externalReferenceCode is "LXC:" + <config-erc> (the same settings block also binds a style book and globalCSSClientExtensions). The resolver at render time walks layout → master layout → layout set, so one bind on the master cascades to every page using it and survives reprovision. See rules/site-initializer-format.md → "Binding Design to the Master via settings". Once the master binds the CET, switch Classic's own header and footer off in the same settings, as themeSettings beside "themeName": "Classic": the layout set's show-header and show-footer no longer apply to its pages. Creating or changing the binding is a master composition change (applied the next time the initializer fires, after a clean redeploy); redeploying the CET updates the served CSS live once bound. The order of deploys matters: if the CET is not yet registered when the initializer imports the master, the bind is silently skipped (No CET found for LXC:...) — retrigger the initializer after the CET is up.

So decide up front where each part of the look lives: the themeCSS CET bound to the master first, for the brand and every Clay level override, including those with no style book token (Classic exposes no headings* tokens); a style book bound alongside it for the values editors tune; fragment CSS only for one fragment's own look.

Scaffold

client-extensions/<name>/
  client-extension.yaml
  package.json         # drives the theme build
  src/
    css/
      _custom.scss     # Clay variable overrides

package.json is what compiles the SCSS — without it there is no build/buildTheme output for the URLs below to point at:

{
	"liferayDesignPack": {
		"baseTheme": "styled"
	},
	"main": "package.json",
	"name": "@liferay/<name>",
	"version": "0.0.0"
}

client-extension.yaml:

<workspace-id>-theme-css:
  clayRTLURL: css/clay_rtl.css
  clayURL: css/clay.css
  mainRTLURL: css/main_rtl.css
  mainURL: css/main.css
  name: <WorkspaceId> Theme CSS
  type: themeCSS

The keys are mainURL and clayURL — capital URL. All four paths are outputs of the theme build (the build/buildTheme/css directory), not files you author.

src/css/_custom.scss — Clay variable overrides:

// Brand colors

$primary: #0B5FFF;
$secondary: #6B7280;
$success: #287D3C;
$danger: #DA1414;

// Typography

$font-size-base: 1rem;
$font-family-base: "Inter", sans-serif;
$headings-font-weight: 700;

// Border radius

$border-radius: 0.5rem;
$border-radius-lg: 1rem;

// Shadows

$box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12);

src/css/main.scss:

@import "custom";

Build the SCSS to CSS: blade gw buildClientExtension or configure the Sass build in build.gradle. Then run deploy-and-verify.

The Stock Theme Build Compiles Clay STATIC — Style Book Tokens Apply to Nothing

The scaffold above produces a theme whose Style Book typography (and color at the Clay level) tokens silently do nothing. The liferayDesignPack build compiles Clay with plain Sass values: the resulting clay.css/main.css contain zero var(--…) references (verified on 2026.Q3.1 — grep --count 'var(--' clay.css → 0), so a style book token like fontFamilyBase sets a CSS variable that no rule reads. The failure is perfectly silent: the page's inline :root shows the token value (e.g. --font-family-base: YourFont, …), the style book editor looks right, and the rendered font never changes — it reads as a problem loading the font, not a compilation one. Classic does not have this problem because its Clay is compiled against the variable set built on CSS custom properties (body { font-family: var(--body-font-family) } → :root chain → var(--font-family-base)).

The fix is one file, src/css/_clay_variables.scss — the hook clay/base.scss imports before Clay's own variables (this is the mechanism Classic's own _clay_variables.scss comment documents):

@import 'clay/atlas-custom-properties/_variables';

That variable set defines every Clay Sass variable as var(--token, fallback) ($font-family-base: var(--font-family-base) !default; in clay/atlas-custom-properties/variables/_globals.scss), so the whole compiled output consumes the style book's variables — verified: ~2,300 distinct var(--…) names after the switch, and getComputedStyle(document.body).fontFamily returns the token value. Diagnose with grep --count 'var(--font-family-base' <served clay.css>: 0 means static build, tokens dead.

Or start from Classic's own sources (verified on 2026.Q3.5). Classic is itself baseTheme: styled plus its own src/css (modules/apps/frontend-theme/frontend-theme-classic/src/css, identical byte for byte to the .scss files inside the deployed classic-theme.war). Copy that directory into the CX's src/css and add your rules at the end of _custom.scss. The build then matches Classic: its clay.css and main.css had exactly Classic's 2,021 and 67 var(--…) references, and style book tokens apply. Leave out Classic's two *-atlas-custom-properties.scss entry files: Classic's pages load clay.css and main.css, not those variants, and against the workspace build's styled base their @import 'clay/atlas-custom-properties' fails with Dart Sass "It's not clear which file to import" (the base ships both the partial and the file). To add tokens of your own (values Classic has no token for), copy Classic's frontend-token-definition.json from the WAR, append a token set, declare the same custom properties with defaults in :root in _custom.scss, and point the style book's themeId at LXC:<config-erc>.

On 2026.Q2.7 the copied sources compile Clay static, like stock Classic. There, Classic's own _clay_variables.scss still imports _deprecated_clay_variables (fixed values), so Classic itself serves a clay.css with only 94 distinct var(--…) names and a copy of its src/css matches that (94 and 27 in main.css). Switch that one import to @import 'clay/atlas-custom-properties/_variables'; (Classic's comment in the same file says so): the build then had 2,462 distinct names in clay.css and 90 in main.css, and a style book's primaryColor recolored Clay's buttons and links. That drops the deprecated file's few fixed overrides (sticker radii, flat label colors). The 2026.Q2.7 source has no *-atlas-custom-properties.scss entry files to leave out. On both releases the plugin's RTL step fails on this Clay ("Unable to generate RTL version … cascadingStyleSheet is null") and the *_rtl.css files are plain copies; fine for a site that reads left to right. Verified with workspace plugin 17.1.5.

Corollary: without this import, a :root { --primary: … !important } block only affects rules that explicitly write var(--primary) (your own custom SCSS, fragment CSS) — Clay buttons, alerts, and body text keep the defaults compiled into Clay regardless of what the style book or :root says.

Webfonts: Register in the themeCSS, Apply via the Style Book

A brand webfont splits across the two layers: @font-face (registration) lives in the themeCSS CET — font binaries under assets/fonts, shipped by an assemble block {from: assets, include: fonts/**, into: static} (do not hashify them; the CSS references them by stable relative URL ../fonts/<file> from css/main.css) — and the family is applied only by the style book's fontFamilyBase token (YourFont, <fallbacks>). Do not add a font-family rule to the CSS. Both halves are dead without the _clay_variables.scss import above. @font-face matches family names regardless of case. Ship woff2 + woff; skip .eot.

A themeCSS project serves any static file this way, not only fonts (verified on 2026.Q2.7): with assemble: [{from: assets, into: static}] at the top level, assets/<dir>/<file> is served at /o/<project directory>/<dir>/<file> on every virtual host, typed by its extension, beside css/main.css. So one theme project can hold what every site's chrome needs (fonts, icons, logos), referenced from its CSS as ../<dir>/<file> and from fragments by the path relative to the root. Name a file by its real type: the static server types by extension, and a file fetched from another site under a .png name can hold WebP bytes. Webfonts hosted locally can come from the @fontsource/<family> npm packages (SIL OFL 1.1, files/<family>-<subset>-<weight>-normal.woff2, with each subset's unicode-range in its CSS files).

Tokens of your own (verified on 2026.Q2.7): a category appended to the CET's frontend-token-definition.json after Classic's own, tokens shaped like Classic's (name, label, defaultValue, mappings: [{type: cssVariable, value: <variable>}], optional editorType ColorPicker/Length), is accepted from a site initializer's style book and declared in each page's :root like Classic's tokens. A mapping may name a variable Clay already reads but Classic has no token for (line-height-base). Declare the same variables with their defaults in _custom.scss too, for a site whose book sets none. The definition is the deployed CET's: redeploy the CET before an initializer imports a book that sets a new token, or the token is dropped.

Apply to Site

The portable path is the master page binding: set settings.themeCSSClientExtension.externalReferenceCode to "LXC:" + <config-erc> in the master's page-definition.json and fire the initializer again with a clean redeploy (see the constraint note at the top of this skill). For a quick manual check on a live site, Site Administration → Design → Theme → Configure also selects it — but that selection is lost on reprovision, so never treat it as the durable copy.

Layer 2: Style Book

A style book maps Clay token names to site specific values. Unlike a themeCSS CET's compiled output, a style book can be applied from the initializer tree, which makes it the reproducible half of the theme layer.

A themeCSS CET built with the stock theme build bypasses the style book — unless it compiles Clay against the variables built on CSS custom properties. By default the SCSS build emits literal values, not var(--token) references, so style book tokens never reach any rule the CET's compiled CSS sets — a token edit "succeeds" (and a reprovision succeeds) with zero visible change. The src/css/_clay_variables.scss import above ("The Stock Theme Build Compiles Clay STATIC") removes the bypass: with it, the compiled Clay consumes var(--token) throughout and the style book drives typography and Clay colors as designed. Either way, the brand ships in the themeCSS CET; put only the values that marketers should be able to tune in a style book bound alongside it. To make a style book drive tokens on a site bound to a themeCSS CET, the CET must also ship its own frontend-token-definition.json declaring the tokens and the style book must be bound alongside the CET (same master settings block, style book by key, CET by full LXC: ERC). Two related facts: a themeCSS CET selected as the site theme without a token definition makes the page editor NPE, and the CET's getThemeId() is its ERC — so a style-book.json targeting a site themed by a themeCSS CET sets themeId to that ERC, not classic_WAR_classictheme. Also note a style book's themeId is fixed at creation: it is set only when the book is created, and the initializer upsert (updateStyleBookEntry) takes no themeId, so a book first created against the wrong theme keeps it on every redeploy. Bind it again by deleting the book, then firing the initializer again — plan the theme before first provision.

Author It in the Tree

site-initializer/style-books/<name>/style-book.json — defaultStyleBookEntry is what applies it to the site with no manual step:

{
	"defaultStyleBookEntry": true,
	"frontendTokensValuesPath": "frontend-tokens-values.json",
	"name": "<Style Book Name>",
	"themeId": "classic_WAR_classictheme"
}

classic_WAR_classictheme is right only when no themeCSS CET is bound. When the master binds one, themeId must be that CET's full ERC, "LXC:<config-erc>"; a book bound to Classic is then silently orphaned, so the tokens never emit and the Style Books list shows it against the wrong theme (verified on 2026.Q2, _isStyleBookEntryApplicable).

frontend-tokens-values.json beside it, one entry per token. The key the Style Book editor reads depends on the release: on 2026.Q3.1 it is namespaced with the token definition ID (the book's themeId, so LXC:<config-erc>:primaryColor on a site bound to a themeCSS CET); on 2026.Q2.7 it is the plain token name (primaryColor). The wrong form still renders, but the editor shows the theme defaults for every token:

{
	"classic_WAR_classictheme:primaryColor": {
		"cssVariableMapping": "primary",
		"value": "#14284b"
	}
}

The initializer upsert leaves the book in a "Draft" state — benign. The style book handler writes through Liferay's versioned entity service, which updates the published head AND an identical draft row together; the editor shows a "Draft" badge whenever a draft row exists. Verified on 2026.Q3.1: head and draft identical byte for byte after an upsert, live pages serve the head. Publish (it changes no content and clears the badge) or ignore it; it reappears after every reprovision that touches the book.

Why the namespace (verified on 2026.Q3.1, root cause found in style-book-web source): the runtime provider of CSS variables (StyleBookScopedCSSVariablesProvider) iterates all entries reading only cssVariableMapping/value — regardless of key, so a plain key like "primaryColor" renders fine. But the editor's sidebar (Sidebar.js → FrontendTokenCategories) rewrites every token's name to `${definitionId}:${token.name}` and looks values up by that namespaced key — a plain key is simply not found, so the editor shows the theme default while the page renders your value. The failure is doubly deceptive: everything looks right on the site, wrong in the admin UI, and if an admin then edits and publishes from that editor state, the UI saves namespaced keys alongside your plain ones and the defaults it displayed overwrite your values wherever they touched a field. Use namespaced keys from the start on 2026.Q3.1 — that is the format the UI itself saves.

On 2026.Q2.7 it is the reverse: plain keys (read from the bundle's style-book-web JS). FrontendTokenSet.js looks a value up as frontendTokensValues[frontendToken.name], and nothing in 2026.Q2.7's editor prefixes the name, so a book written with LXC:<config-erc>: keys showed the theme default for all 66 of its tokens (Font Family Base read system-ui, … while every page rendered the book's 'Open Sans'). The same book imported again with plain keys showed its own values. Check the release before choosing the form: in the bundle's com.liferay.style.book.web.jar, META-INF/resources/js/style-book-editor/Sidebar.js builds ${definitionId}:${…} names only on the releases that namespace.

Token Names Must Exist in the Theme — Unknown Ones Are Dropped Silently

A token only takes effect if its name is declared in the active theme's frontend-token-definition.json. An invented name is discarded with no error: the initializer logs addStyleBookEntries took N ms, nothing warns, and the page keeps the default value. Do not guess — enumerate first:

Each entry needs two things — the token name (the JSON key) and its cssVariableMapping. The mapping is not derivable from the name (primaryD1Color → primary-d1, btnPrimaryBackgroundColor → btn-primary-background-color, fontFamilyBase → font-family-base), so dump both at once rather than guessing the form in kebab case:

Read it from the deployed theme in the bundle, not from portal source. A Liferay Workspace is not a portal checkout — modules/apps/frontend-theme/... does not exist there, and reaching for it sends you looking for a repository you may not have. The definition ships inside the theme WAR:

unzip -p bundles/osgi/portal-war/classic-theme.war WEB-INF/frontend-token-definition.json > /tmp/tokens.json

python3 -c "
import json
d = json.load(open('/tmp/tokens.json'))
for c in d['frontendTokenCategories']:
    for s in c.get('frontendTokenSets', []):
        for ft in s.get('frontendTokens', []):
            for m in ft.get('mappings', []):
                print(f\"{ft['name']:36s} -> {m.get('value')}\")" | sort -u

This has the added benefit of describing the theme actually running, so the list matches the release under test rather than whatever branch is checked out. Verified on a 2026.Q2 bundle: 252 tokens, and no headings* among them.

Filter that list to what you need (grep --extended-regexp '^(primary|btnPrimary|body|font|h[1-6])') rather than reading all 252. For a non Classic theme, substitute its WAR under bundles/osgi/portal-war (or bundles/osgi/war for a deployed custom theme).

Classic declares 252 tokens. Useful ones: bodyBgColor, bodyColor, primaryColor, primaryD1Color, primaryD2Color, primaryL1Color…primaryL3Color, secondaryColor, warningColor, warningD1Color, fontFamilyBase, fontSizeBase, fontWeightBold, fontWeightBolder, h1FontSize…h6FontSize, and the full btnPrimary* / btnSecondary* sets (BackgroundColor, BorderColor, Color, and their Hover variants).

Recoloring buttons takes the whole btnPrimary* set, not just the background — leaving btnPrimaryColor alone gives white label text on a light accent.

A page element's style value naming an unknown token is written out raw. fragmentStyle values such as "textColor": "whiteColor" are token names; when the active theme's definition has no such token, the layout's style sheet (/o/layout-common-styles/main.css?plid=…) carries color: whiteColor !important, invalid CSS the browser ignores, with no error. Seen on 2025.Q3.2 under Dialect, whose definition has no Classic whiteColor or gray500Color; the same values resolved once the site moved to Classic, so the two renders differed. Check every style value against the definition of the theme that will render it.

Moving a Site to Another Theme: Fragment JS Reads Variables by Name

Rewriting a fragment's var(--old-token) references is not the whole move. JavaScript that reads a theme variable by name, getComputedStyle(document.documentElement).getPropertyValue('--color-chart-1'), gets an empty string once the new theme does not define that name, with no error. Chart.js then fills every segment with its default black, while the legend, drawn from CSS, keeps its colors. Seen on 2026.Q3.5 after a Dialect → Classic move: two doughnut fragments read --color-brand-primary-lighten-2, --color-chart-*, and --color-accent-* this way. A converter that maps var(--…) and a scan for leftover var(--color-…) both miss these strings, so search fragment JS for getPropertyValue('-- too, and map those names like the CSS ones.

Moving a Site to Another Theme: The Old Theme's Defaults Do Not Come With It

A style book holds only the tokens someone set. Everything else the site looked like came from the old theme's own defaults, and mapping the style book again carries none of them. Measured on a Dialect (2025.Q3.2) → Classic plus themeCSS CX (2026.Q3.5) move whose style book had been mapped again token by token:

WhatDialectClassic
--font-size-base, body text1rem, 16px0.875rem, 14px
--h1-font-size … --h4-font-size2.3125 / 2 / 1.75 / 1.5rem1.625 / 1.375 / 1.1875 / 1rem
--border-radius, -sm, -lg0.5 / 0.375 / 0.75rem0.25 / 0.1875 / 0.375rem
.btn, .btn-sm, .btn-lg height48 / 36 / 56px40 / 30 / 48px
.form-control height48px40px
.cardbody padded 16/24/24/24px, no border, radius 8px16px, 1px border, radius 16px
.label20px (11px text)18px (12px text)

So every page's text was 12.5% smaller and its headings 25–33% smaller, and a hero whose height followed its text cropped differently. Nothing errors.

Find them by comparing renders, not stylesheets. Read the old site's :root custom properties live (getComputedStyle(document.documentElement).getPropertyValue(…)); Dialect names its own in the WAR, css/dialect/variables/*.scss ($btn-padding-y: var(--btn-padding-y), $card-body-padding-top: var(--card-body-padding-top), …). Then inject the same Clay markup (.btn in every size, .card, .form-control, .label, .modal-content, the .rounded* utilities, …) into a page of each site and compare computed height, padding, radius, and font size.

Where each goes:

  • What the new theme has a token for → the style book: fontSizeBase, fontSizeLg, fontSizeSm, h1FontSize…h6FontSize, borderRadius, borderRadiusSm, borderRadiusLg on Classic. These reach .rounded*, .modal-content, and the -lg input radius, which read the variables.
  • What Classic compiles as a fixed value → Clay's Sass variables, at the end of the CX's src/css/_clay_variables.scss (Clay's hook, imported before its own !defaults): $btn-padding-y, $btn-padding-x-sm, $btn-padding-y-lg, $btn-line-height-sm/-lg, $btn-monospaced-size/-sm/-lg, $btn-border-radius/-sm/-lg, $card-body-padding-*, $card-border-width, $card-border-radius, $input-height, $input-padding-y, $label-font-size, $label-line-height, $label-padding-y. A size set in a map takes a partial map, which Clay merges into its own: $btn-sizes: (btn-xs: (border-radius: 0.375rem)), $label-lg: (font-size: …, line-height: …). Not in _custom.scss: it comes after Clay, too late for a variable, and a plain .btn { padding … } rule there also pads .btn-unstyled and the monospaced buttons, whose padding is 0.
  • Dialect's button padding is its variable less the border: --btn-padding-y: 0.75rem renders 11px, so $btn-padding-y: 0.6875rem with Classic's 1px border.

With both, 31 injected Clay components matched the old site in radius, height, padding, and font size, and the hero's height to the pixel. That is not all of it. A wider comparison the next day (about 80 Clay elements, every variant of buttons, alerts, labels, badges, text and backgrounds, form inputs focused and disabled, tables, four navs, dropdown, pagination, card, list group, modal, toast, and the shadow utilities, read at rest, on hover, and on focus) found 526 visible differences left: Dialect's colors (body text #484848 against Classic's #1c1c24, links, white inputs with a #a3a3a3 border against Classic's gray ones, table and label grays, alerts), its shadows (the purple elevated .card shadow, --box-shadow*), and component type (.card-title 20px against 14px). The sizes above were only the start: compare colors, borders, shadows, and type the same way, at rest, on hover, and on focus, and port each difference onto the new theme with the same split (a token where the new theme has one, a Clay Sass variable where it compiles a fixed value).

Never Trust a var() Fallback for Contrast

var(--some-token, #safe-color) in fragment CSS is a WCAG trap: the fallback only applies when the variable is unset, and a Clay/theme default counts as set. Example: var(--text-muted, #6b7280) — no style book defines text-muted, so Clay's default #a7a9bc (~2.3:1 on white, an AA fail) wins and the compliant fallback is dead code. Reference a token the style book actually defines (a --gray-* ramp value), or measure the resolved color in the browser (getComputedStyle) — never assume the fallback is what renders.

Classic has no headings* tokens at all — headingsColor, headingsFontFamily, and headingsFontWeight are all plausible and all ignored. Only the sizes are tokenized (h1FontSize…h6FontSize); heading family and weight have no token.

CSS Across the Site With No Token — Prefer the themeCSS CET

Put a rule that applies across the site, and that no style book token expresses, in the themeCSS CET's src/css/_custom.scss, which every page bound to the master loads. Only when the site ships no themeCSS CET is the master page's header fragment the reproducible fallback, as described below.

A fragment's index.css is a stylesheet on the page, so its rules can target anything — they are not confined to the fragment's markup. A fragment placed in the master page loads on every page using that master, which makes it the one place CSS across the site can live and still survive delete and redeploy:

/* site-header/index.css — deliberately NOT scoped to the fragment wrapper */

#wrapper h1,
#wrapper h2,
#wrapper h3 {
	font-family: 'Your Face', -apple-system, 'Segoe UI', Roboto, Arial, sans-serif;
	font-weight: 800;
	letter-spacing: -0.022em;
}

This is a deliberate exception to "Fragment Scoping" in scaffold-fragment — that rule exists to stop accidental cascade leakage between sibling fragments on one page. Keep the exception narrow (headings and brand chrome), keep it in the master's fragment rather than a content fragment, and comment why, or the next reader will "fix" it back into scope.

Tag Selectors Alone Miss Every Overridden Heading

A fragmentFields literal in page-definition.json replaces the editable region's inner markup, so a title authored as <div class="…__title"><h2>…</h2></div> renders as that div with bare text — no <h2> survives (see skills/manage-pages/SKILL.md → "A Literal Override Replaces the Editable's Inner Markup").

The rule above therefore matches the fragment's default heading and skips every placement that sets its own text — which, on a real site, is most of them. Name the title wrapper classes alongside the tags:

#wrapper h1,
#wrapper h2,
#wrapper h3,
#wrapper .conference-hero__title,
#wrapper .section-heading__title {
	/* family, weight, tracking */
}

Verified on 2026.Q2: with tags only, getComputedStyle on an overridden hero title returned the body font at weight 700, while the untouched default beside it rendered correctly — so the page looked mostly branded and the failure read as a font loading problem rather than a selector one.

Every Content Fragment Outranks This Rule — Strip Their Heading Weights

The selector above is one ID plus a type, so any fragment styling its own heading through a class beats it. scaffold-fragment requires exactly that form (#wrapper .<wrapper-class>), so the collision is the default outcome, not an edge case:

#wrapper h1                        /* master rule   — 1 id, 0 classes, 1 type */
#wrapper .conference-hero__title   /* fragment rule — 1 id, 1 class          */

The fragment wins. The failure is quiet because it is partial: family and tracking still apply (the fragment did not set those), so headings look almost right while font-weight silently stays at whatever the fragment declared. Verified on 2026.Q2 — a rule across the site asking for 800 computed to 700 on every heading whose fragment set font-weight: 700, and reads as "the heavy font did not take".

Fix it at the fragments, not by escalating the master selector. Delete font-weight from every heading rule in every content fragment so the master rule is the single source of truth:

grep --before-context=3 --line-number 'font-weight' */index.css | grep --extended-regexp '__title|__heading'

Then confirm the computed value in the browser rather than trusting the stylesheet, because the cascade is the whole question:

getComputedStyle(document.querySelector('.my-fragment__title')).fontWeight;

Leave explicit weights on non headings (<p> date stamps, buttons, uppercase micro labels) — those are not governed by the rule and often want a different weight on purpose.

Set family, weight, and tracking here — never color. Headings must inherit color from their section, or the same rule that styles dark text on the light content areas also paints the hero h1 and footer h2 in that color, on their own dark background. The snippet above omits color for this reason; adding it is invisible on a light only site and renders headings unreadable the moment a navy hero or footer exists.

Weigh it against the alternatives before reaching for it:

NeedPut it in
Brand across the site, Clay variable overrides, no tokenthemeCSS CET bound in the master's settings.themeCSSClientExtension — preferred (survives reprovision)
Across the site, no token, plain CSSThe themeCSS CET's src/css/_custom.scss; master page fragment CSS (above) only when the site has no themeCSS CET
Value has a style book token, and editors should tune itStyle book bound alongside the themeCSS CET (Layer 2)
Truly across the instance, every siteglobalCSS CET (no per site scoping available)
One section's lookThat fragment's own scoped CSS

A webfont still needs a file served from a CET; a system font stack at weight 800/900 gets a heavy sans with no external dependency.

Verify the book landed by fetching a page and checking the override lands after the theme default — two declarations, e.g. --primary: #0b5fff; from Classic then --primary: #14284b; from the book. One declaration means the tokens were dropped.

The style book REST API is behind a flag. headless-admin-content has no style book resource. The one in headless-admin-site (/sites/{siteERC}/style-books) answers every call with 400 UnsupportedOperationException unless its flag is on: LPD-57283 (release, off by default) on 2026.Q3 and later, the hidden LPD-56718 on 2026.Q1 and 2026.Q2 (StyleBookResourceImpl; see rules/headless-apis.md). Without the flag, author style books in the site initializer tree as above, or in Site Administration → Design → Style Books.

Consult learn.liferay.com for the full style book token reference (search style book tokens).

Layer 3: Master Page

Master pages define the persistent header and footer that surround all Content Pages assigned to that master.

Author the master in the site initializer tree, under layout-page-templates/master-pages/<name> (see rules/site-initializer-format.md → "Master Pages"), and bind the theme, favicon, and style book from its settings. The API call below is for a change made once to a running instance. See liferay-rules.md → "Deliver Through Client Extensions".

Create via API

curl \
	--data '{
		"name": "<Master Page Name>",
		"pageDefinition": {
			"pageElement": {
				"pageElements": [
					{
						"definition": {
							"fragment": {
								"key": "<header-fragment-name>",
								"siteKey": "[$GROUP_KEY$]"
							}
						},
						"type": "Fragment"
					},
					{
						"definition": {
							"fragmentSettings": {
								"unallowedFragments": []
							}
						},
						"type": "DropZone"
					}
				],
				"type": "Root"
			},
			"version": 1.1
		}
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/master-pages" \
	--user "test@liferay.com:test"

The DropZone element must carry a definition.fragmentSettings block — a bare {"type": "DropZone"} does not render, and the master shows an empty body. Use {"definition": {"fragmentSettings": {"unallowedFragments": []}}, "type": "DropZone"} so page specific content can be placed inside the master. Note version is the number 1.1 (not the string "1.0") for a master with a working drop zone. Custom header/footer fragments are referenced by key (the fragment's directory name) + siteKey ([$GROUP_KEY$]), exactly as in a page page-definition.json (see manage-pages); the content area is a DropZone element, not a LAYOUT_DROP_ZONE fragment. Master pages are typically authored in the initializer tree under layout-page-templates/master-pages/<name>/page-definition.json (where pageDefinition/page-definition.json is the correct importer format). Note: the live headless-admin-site MasterPage DTO uses pageSpecifications, not pageDefinition — prefer the initializer path, or verify the live write shape against the OpenAPI spec (get-openapi MCP tool, or GET /o/headless-admin-site/v1.0/openapi.json).

Mark It as the Site Default

settings.masterPage.key in each page-definition.json applies the master to the pages in the tree. Pages created later, in the UI or over REST, get the site's default master instead, so mark yours as the default, or new pages render without the header and footer.

The tree cannot do this. master-page.json accepts only key and name, and an extra key such as "defaultTemplate": true makes the importer drop the master page: the site provisions with no master and every page loses its header and footer. This is one of the settings no client extension can carry, so it stays a step after deployment: script it next to the initializer and run it after each provision. Mark it over REST by sending the master page back with markedAsDefault set:

SITE="http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>"

ERC=$(curl \
	--silent \
	--url "${SITE}/master-pages" \
	--user "test@liferay.com:test" \
	| jq --raw-output '.items[] | select(.key == "<master-name>") | .externalReferenceCode')

curl \
	--silent \
	--url "${SITE}/master-pages/${ERC}" \
	--user "test@liferay.com:test" \
	| jq '.markedAsDefault = true' \
	| curl \
		--data @- \
		--header "Content-Type: application/json" \
		--request PUT \
		--silent \
		--url "${SITE}/master-pages/${ERC}" \
		--user "test@liferay.com:test"

Verified on 2026.Q2: the response and a fresh GET .../master-pages both show "markedAsDefault": true. A reprovision deletes the site and the flag with it, so repeat the call after every reprovision.

Consult learn.liferay.com for the full master page template reference (search master page templates).

Accessibility

Follow WCAG 2.1 AA as the baseline:

  • Color contrast: minimum 4.5:1 for normal text, 3:1 for large text (18pt+). Use a contrast checker before finalizing the $primary color.
  • Measure what renders, not the token values. In headless Chrome, for each visible element with its own text, take its computed color and the first opaque background-color walking up its ancestors (compose semitransparent layers, and an ancestor's absolutely positioned ::before overlay from getComputedStyle(node, '::before') at its opacity, taking a gradient's worst stop; an ancestor with a background-image makes the pair unmeasurable unless an overlay of about 0.8 or more hides it), and compute the WCAG ratio; open each menu panel and measure again. On a migrated site this finds what a token audit cannot: colors a page definition carries as raw hex, a text color the migration dropped, a fragment's own CSS.
  • Focus indicators: ensure Clay's default focus ring is not overridden to outline: none without a replacement.
  • Skip link: include a <a href="#main-content" class="skip-link">Skip to main content</a> in the master page header.
  • Image alt text: enforce via data-lfr-editable-type="image" regions, which prompt editors to provide alt text.

Favicon and Spritemap

To replace the Liferay favicon or icon spritemap, use the companion CET types:

<workspace-id>-favicon:
  url: "images/favicon.ico"
  type: themeFavicon

<workspace-id>-spritemap:
  url: "images/icons.svg"
  type: themeSpritemap

Ship these in the same frontend project as the themeCSS CET, with the icon files actually present. A url that points at nothing deploys cleanly and delivers no icon.

themeFavicon is the only route to a browser tab icon. There is no style book token for a favicon, and no initializer handler writes the site record's own favicon column either, so a site with no favicon project keeps the product default no matter how thoroughly it is otherwise rebranded. Bind it in the master's page-definition.json beside the theme, as settings.favIcon with {"externalReferenceCode": "LXC:<config-erc>", "name": "<CET Name>"}. Every page using the master then serves the CET's icon, and the binding survives reprovision. Do not add favIconType there: that is the REST shape, and in the tree it makes the importer drop the whole master without a log line. Verified on 2026.Q3.8.

globalCSS Versus themeCSS

A themeCSS CET overrides Clay Design System variables and is applied per site — durably via the master's settings.themeCSSClientExtension binding, or manually under Design → Theme. A globalCSS CET is different: it injects a plain CSS file on every page automatically as soon as it is deployed — there is no per site selection and no Instance Settings or manual enablement step. Scope is controlled on the CET itself (scope: company injects across the instance; omitting scope uses the default):

assemble:
  - from: assets
    hashify: global.css
    into: static

<workspace-id>-global-css:
  name: <WorkspaceId> Global CSS
  scope: company
  type: globalCSS
  url: global.*.css

assemble is a key at the top level of client-extension.yaml, a sibling of the entries, never a key inside one. Inside an entry, createClientExtensionConfig fails with class java.util.LinkedHashMap cannot be cast to class java.lang.String, after the build tasks before it reported success (verified on 2026.Q2.7 with workspace plugin 17.1.5).

Use globalCSS for site agnostic CSS that must always load; use themeCSS for brand tokens applied per site through the master binding or theme picker.

Success Signal

After deploying and assigning:

  1. Open the site home page in the browser.

  2. Confirm the CET is actually taking effect by its rendered result, not by a URL string. A themeCSS CET replaces the theme's compiled CSS (its main.css carries the Clay variable overrides and any custom rules) — it does not add a <link> whose href contains the config ERC. So verify the effect: getComputedStyle(document.documentElement).getPropertyValue('--some-token') returns the CET's value, or a rule the CET sets is measurably in force (e.g. a brand color on a primary button). The master's settings.themeCSSClientExtension binding (or Design → Theme showing the CET) is itself ground truth that the bind exists.

    Do not verify by grepping stylesheet hrefs for the CET name. Because the CET replaces the theme CSS rather than adding a separately named file, its config ERC never appears in a <link> href — and the base classic-theme clay.css/main.css URLs can still be present. Concluding "the theme CSS is not applied" from the absence of a <CET-name>-named stylesheet is a false negative. Trust the computed style or the master binding, not the href.

  3. Confirm brand colors appear in primary buttons and headings.

  4. Run a browser contrast audit (DevTools → Accessibility) to validate WCAG compliance.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall