One look, stated once

Theme Contract

Where the Theme comes from

• site.theme (PhiSiteTheme, gateway/site-config.ts) is part of the Site config @phis/server returns from GET /api/v1/site. It is the Site's stored Theme record, read per request.
• site.themeRevision carries publishedRevisionId and workingDraftRevisionId, the Theme scope pointers. They are kept apart from the visual payload.
• A stored record holds only which blocks the Site follows and the values its author changed. Everything else is resolved from the blocks on every read (theme/phi-theme-composition.ts). The author's values always win over the blocks.
• resolvePhiThemeRuntimePayload(...) (theme/phi-theme-runtime.ts) folds the blocks into one ordinary Theme record once, in PhiRootLayout. Every consumer below reads that record; nothing downstream knows which fields a block supplied, and a resolved value is never written back.

Theme blocks

• themes: PhiCmsThemePresetDescriptor[] for palettes -- themeKey, title, optional description, presetVersion, and loadPreset().
• themeBlocks: PhiCmsThemeBlockDescriptor[] for the other four kinds -- blockKind is exactly style, ground, fonts, or set, plus blockKey, title, optional description, presetVersion, and loadBlock().

Selection and resolution

• theme.blocks selects { set?, palette?, style?, ground?, fonts? }, each { key, version? }.
• Each part resolves on its own: an explicit part selection wins, then the Set's part, then (palette only) theme.preset. A part that names nothing or an unavailable block runs on the core block; the selection itself is never rewritten, so re-activating the Module restores the look.
• theme.preset and theme.presetVersion name the palette the runtime payload resolves colour against.
• A resolved composition reports which parts are unavailable, so the Theme workspace can say that a Module is gone instead of presenting the core block as a choice.

• A Theme is a stored record, not a declaration. It carries the author's own values, it is drafted and published like a Page, and it survives its Module: a selection whose block is gone falls back to core and comes back when the Module returns. An automatic selection would overwrite a decision that was made.
• Adoption is one-way. The moment a Theme resolving to a Module's blocks is saved, those blocks become the Site's own and the pictures land in its Media library (see Adoption on save). A look that was never chosen would become permanent the first time anybody saved anything.
• Nothing chosen is visible. The core Set's Logo is the "your logo" placeholder, so a Site that has made no choice says so in its own header. That is the prompt; an automatic Theme would remove it.

Adoption on save

Theme workspace selection

site.theme field reference

Mode

• mode?: "light" | "dark" -- the half of the Theme a record or draft was authored in. The mode a viewer is shown does not come from here: resolvePhiThemeMode(...) (theme/phi-theme-mode.ts) uses the viewer preference (light | dark | system, default system) and, for system, the browser's prefers-color-scheme carried in the phis_color_scheme cookie, falling back to light. A live themeMode or theme signal to the Core Runtime Controller overrides the projection for as long as the page stays open (SIGNALS.md).
• Where that preference lives, and why in two places at once: on the account, as user_accounts.theme_mode (NULL means system, and the endpoint is PATCH /api/v1/auth/profile/theme), and mirrored into the phis_theme_mode cookie, which is what resolvePhiThemeMode actually reads. The mirror is not a convenience -- the static proxy picks a render, and the bootstrap script decides before the first paint, and neither of them can resolve a session. The server writes the cookie on login and on every change, so the account is what follows a person between browsers and the cookie is what this request can see. system is the absence of the cookie rather than a third value in it.
• The account's own answer also travels as runtime.viewer.preferredThemeMode, which is the choice and may say system. runtime.viewer.themeMode beside it is the resolution and always names a half. A Settings panel reads the first: shown the second, it would tell somebody they chose "Light" when they chose to be asked. The pair stands to each other as preferredLocale does to locale.current.
• The Header switch and the Settings panel are the same setting. The switch states two halves and writes the account where there is one (storePhiThemeModePreferenceOnAccount); the panel is where the third answer lives, because no switch can state "System".

Blocks

• blocks?: PhiThemeBlockSelection -- see Selection and resolution.
• preset?: string, presetVersion?: number -- the palette key and version.

Colour

• palette?: PhiThemePalette (theme/phi-theme-presets.ts), the same shape a palette block ships:

  • seed -- seeds shared by both modes (colorPrimary, colorInfo, colorSuccess, colorWarning, colorError, colorLink).
  • modes.light / modes.dark, each with

    • seed -- the per-mode base seeds colorTextBase and colorBgBase;
    • overrides -- explicit colour tokens that are not seeds, such as colorLinkHover or colorBgLayout;
    • customColors -- the ten Phi custom colours custom1 through custom10;
    • gradients -- the three gradient slots gradient1 through gradient3, each a direction and two or more colour stops (theme/phi-theme-gradients.ts). They are per mode for the reason a mode seed is: the run that reads as the brand on a light page can be a hole in a dark one. A slot the palette leaves out is derived from the mode's own resolved colours (primary, warning, info), so every Theme offers all three without anybody drawing them. A palette block's slots and theme.palette's are merged per slot (phi-theme-presets.ts). They reach the page as the tokens phiGradient1-phiGradient3 (with a matching …Text colour), which Ant Design writes as --ant-phi-gradient-1 and so on; a Control or a Background reads the property and is in the right mode wherever it stands.

Style

• style?: { token?: Record<string, unknown> } -- mode-free structural Ant Design tokens: radii, control heights, spacing, typography sizes.
• shape?: { controls?: PhiControlShapeCorners } -- see Control shape.
• buttons?: { shadow?: { default?, primary?, danger? } } -- one step per Button kind, each none | soft | strong (theme/phi-button-shadow.ts). A step becomes the Button component token (defaultShadow, primaryShadow, dangerShadow) per mode, because a shadow that reads on a light ground disappears on a dark one. A kind left unset keeps Ant Design's tinted line.
• buttons.primaryGradient?: "gradient1" | "gradient2" | "gradient3" | null -- the Theme gradient every primary Button is filled with (theme/phi-button-shadow.ts, resolved in phi-theme-gradients.ts). Absent, primary Buttons keep their one colour. Hover and press lay a filter over the run instead of swapping it for a second picture, because Ant Design transitions every Button property and a swapped picture crossfades badly. A single Button can still choose a gradient of its own with the gradient variant.
• typography?: { headings?: "body" | "serif" | "display" } -- the font slot h1 to h3 take (theme/phi-theme-typography.ts). Absent means body. A non-body choice sets --phi-font-heading on the root; a slot without a family falls back to the body font.
• components?: Record<string, Record<string, unknown>> -- Ant Design component overrides, merged per component over the shared component defaults, never replacing the whole object.

Ground

• root?: PhiSiteThemeRoot (types/site-theme.ts):

  • root.background.light / root.background.dark -- the Root Background per mode, on the canonical structured Background contract (PhiCmsBackgroundWidgetConfig). A mode without one uses the resolved Ant Design colorBgLayout.
  • root.chrome.light / root.chrome.dark -- the Chrome Overlay the Header, Sider, and Footer Regions share. Any Surface may show it as its ground with the Background Base theme, in the mode of its tone (LAYOUTING.md).
  • root.chrome.shadow.header | sider | footer -- the Shadow each Chrome family casts at its outer edge (PhiShadow), independent of mode.

  What each layer may contain, which Regions paint it, and how a Region overrides it are owned by SHELL.md. The ground is site-wide; there is no Area override.

Fonts

• fonts?: { body?, mono?, serif?, accent?, display? } -- five slots (PhiSiteFontSlots). A slot holds a family name or a phis:asset/<id> reference to a Site-owned font Asset.
• There is no rem setting. One rem is 16px everywhere (PHI_REM_ROOT_PX in theme/phi-css-vars.ts): the document's font size, every length this package converts, and Ant Design's generated structure. A Theme that wants everything larger moves fontSize and the size tokens.

Brand

• homeLinkTarget?: PhiLinkTarget -- where the Brand leads: a Page by reference or an external address, the same target every link stores (REFERENCES.md). The Page target names the public Area, since the Brand leads there wherever it is drawn. It is resolved on the Server in the render's one batch of link targets, and the Brand Widget is handed the address. Absent, or a Page that no longer resolves, is the Site root in the language being read. The server's reference index reads CMS trees and not the Theme record, so this target is not among the affected references a path change counts.
• eyebrow?: string -- the small line above the Wordmark.
• logo?: { light?, dark? } -- one Logo per mode, each one of

  • { sourceKind: "asset", assetId: number, url?: string } (url is resolved on read and written by the picker alongside the id),
  • { sourceKind: "url", sourceUrl: string } (a Set's inline Logo until a save uploads it),
  • { sourceKind: "none" } (explicitly no Logo, so a Set's Logo does not show through).

  A mode the record leaves unset shows the followed Set's Logo; where that Set is a Module's, the first save takes it into the Media library. The core Set's is followed and never copied, like every other core block -- its Logo is the "your logo" placeholder, and a Site must not come to own a blank.
• logoAlt?: string -- falls back to the Asset's own alt text.
• logoYOffset?: number -- pixels the Logo is nudged against the Wordmark, to correct the artwork's own whitespace. Applied only where the Logo is drawn. Absent means none.
• slogan?: { label?, icon? }, location?: { label?, icon? } -- the two frame lines. A line with no label draws nothing at all, icon included; only the icon has a default (antd:star, antd:location, PHI_BRAND_LINE_FALLBACK_ICONS), and an icon in front of an empty line would report something missing rather than something not asked for.
• wordmark?: { fontFamily?, fontWeight?, fontStyle?: "normal" | "italic", letterSpacing?, parts? } with parts[] of { text, color?, fontWeight? }. What a part states wins over the Wordmark.

Contact

Widget defaults

• widgets.locale?: { mode?: "label-list" | "compact-pill", showText?: boolean } -- read by the Locale Widget; defaults compact-pill and true.
• widgets.account?: { variant?: "full" | "compact" | "icon-only", showLabel?: boolean, showChevron?: boolean } -- read by the Account Widget; its own instance config wins.

Shell

• contentMax?: number
• light / dark: { background?, color? } -- global Shell surface per mode.
• header, sider, footer: each with family-level light / dark and metrics, and per-Region entries header.top | main | bottom, sider.left | right, footer.top | main | bottom. Each entry has light / dark { background?, color? } plus height, width, collapsedWidth, sticky, offsetTop, and zIndex.

Resolution into Ant Design

1. 1.
   structural defaults (buildPhiThemeStructuralTokens, derived from the Phi scale),
2. 2.
   colour tokens from the palette block with theme.palette merged over it,
3. 3.
   theme.style.token,
4. 4.
   fontFamily / fontFamilyCode from the resolved body / mono slots.

• Ant Design's structure is not rendered. The root theme sets zeroRuntime (and hashed: false), and the structure of every component comes from @phis/ui/antd-static.css. That specifier names no file of this package: withPhiNextConfig from @phis/ui/next/config, which wraps the Site's next.config, generates the structure from the Ant Design the Site installed -- once per version, into node_modules/.cache/phis-ui/ -- and points the specifier at it. A Site updates Ant Design within the peer range without a release of this package. Generating fails, and with it the Site's build, when a style hook Ant Design declares is not reached; pnpm antd-css:check and the package build run the same generation against this package's own Ant Design. The structure reads every Theme value through var(--ant-...), so one file serves every Theme, mode and nested scope. It is imported before this package's sheets, so a rule of ours that ties on specificity wins.
• AntdRegistry in PhiRootLayout extracts what is still rendered during SSR: the --ant-* variables Server Component markup and plain CSS use, per theme scope.
• resolvePhiPublishedRootTheme(...) (server-only) emits only Phi-owned structural variables that have no Ant Design token.
• PhiConfigProvider is the single Client boundary for Ant Design locale and theme configuration. Its usePhiConfig() value carries token, customColors, fonts, layout, mode, and presets. The Server Root passes only serializable data across it; Client theme modules never import server resolvers or server-only modules, and pnpm audit:graph must report no Client-to-server-only reachability.
• The root resolves on the Server, for both modes: resolvePhiRootThemeState(...) in PhiRootLayout hands PhiRootLiveThemeProvider the antd theme per mode plus the Shell Chrome Overlay's custom properties, and the provider only picks the mode on screen, so the mode switch needs no round trip. The provider fetches the resolver with import() only when a Theme draft arrives live from the Builder's Theme editor (the theme signal); until it has resolved, the frame keeps the Theme it has. The resolver, the Shell region styles and the Overlay are not on any first load, and scripts/validate-area-client-reach.mjs holds the root to that (ROOT_SERVER_RESOLVED_THEME_FILES).
• The Server resolves a Theme once per process: resolvePhiRootThemeState(...) keeps the resolved state by the content it was resolved from and hands it out frozen (gateway/CACHES.md).

The stated vocabulary

• PHI_THEME_TOKEN_KEYS -- every name a render may read or write. PhiThemeTokens is cut from Ant Design's GlobalToken by that list, and it is what usePhiConfig().token hands a Client Component; PhiServerThemeTokens is cut from the same list, so the two projections cannot drift apart.
• PHI_THEME_OWN_TOKEN_KEYS -- the names this house adds to Ant Design's set. paddingXXL is one: buildPhiThemeStructuralTokens hands it over with the rest of the scale and the cssVar pass emits a variable for every token it is given, so --ant-padding-xxl is on the page although AliasToken has no such field. Ant Design's type does not know the name; its output does. Such a name is read as a CSS variable, never through the hook, because it cannot be cut from a type that lacks it.
• PHI_THEME_PALETTE_SEED_KEYS and PHI_THEME_STYLE_SEED_KEYS -- what a palette may seed and what a style token may say beyond the vocabulary (wireframe, which is not a value on the page but the switch the derivation runs under).

• theme.components is Ant Design's component tree (Layout.*, Menu.*, some hundreds of names) and stays an open record. Holding it to a list would take that whole tree in as a contract for the sake of the handful of overrides a Site writes.
• The Theme workspace (plugins/runtime-modules/theme/widgets/brand-controls/client.tsx) edits these tokens rather than reading them -- it walks them by name and writes them back -- so it lives below the bridge with Ant Design's own types. That is a decision, not a leak.

Control shape

• square removes rounding; pill is a full capsule on rectangular Controls and a circle on square icon-only Controls. Both apply at every Control size.
• rounded is the numeric radius scale unchanged; subtle is that scale shifted one step smaller.
• pill is derived centrally from the rendered Control height, never persisted as border-radius: 50%.
• A Control that grows with its content -- a Textarea, a multiple Select whose tags wrap, a Mentions box -- keeps the capsule of ONE Control line at every height. Half of a box four rows tall is an arc across its side, not a capsule, so pill there is half the Control height rounded up rather than the full radius. The other three shapes state a number and are unaffected.

• Table -- headerBorderRadius, which Ant Design's internal tableRadius and therefore the container's top corners and a footer's bottom come from. The bottom corners are not drawn by Ant Design at all; styles/controls.css clips them from the variable when a footer or a summary row closes the Table.
• Collapse -- its panels, through collapsePanelBorderRadius, the token Ant Design derives from borderRadiusLG and draws a panel's container, first header and last body from. It is what the Collapsible Layout renders with.
• Tree -- the node grounds through a component-level override of the global borderRadius, which is what Ant Design's Tree reads and what it declares no token of its own for; the frame of a bordered Tree from the variable.
• The eight boxes drawn from the global borderRadiusLG, each through a component-level override of that global: a Card's container, header, cover and actions bar; a Modal's content, which is what an Overlay renders as; and the panels a Dropdown, a Select, a DatePicker, a Cascader, a Popover and a collapsed Sider's Menu submenu open over the page. An overlay and a dropdown are surfaces like any other -- what stays off them is the Control shape, not the scale. A Drawer (flush to the viewport edge) is not a surface this answers for, and the icon tile a Card draws beside its title is an element inside one, so it keeps the numeric scale.
• Tooltip -- the same step through its own borderRadius, except under pill, where it takes half the Control height (resolvePhiTooltipShapeRadius). The full-radius abbreviation cannot be used here: Ant Design computes the Tooltip's minimum width from this number, so 9999 would ask for a tooltip twenty thousand pixels wide. Half the Control height is the same capsule, because a Tooltip's minimum height is the Control height, and a Tooltip that wraps holds that corner instead of growing an arc.
• Layout -- the box of a Layout with a Surface, wherever the author configured no corner. A corner in a custom border always wins: the step answers silence, it is not a ceiling. Outside the Provider the variable is absent and a Layout falls back to no radius. A Layout without a Surface states no corner, because there is no box there to round. The step is applied as longhands, so it never stands beside the corners a configured border writes. For Phi Controls the shape wins over conflicting component radius overrides. The Split Card is one card split in two, so its corner is simply its Surface's.
• A Phi Control that draws its own surface -- the frame of a bordered Tree, and a media tile together with the skeleton standing in for it. There is no component token to carry the step to a box phis draws itself, so it reads the variable, bare. The Config Provider declares it on its element in the server render and mirrors it onto the document for portals, and nothing of phis renders outside it (usePhiConfig throws there), so an --ant-* fallback beside it would only hide a missing Provider. Intrinsic geometry stays authoritative: Switch stays a capsule, Checkbox and Radio keep their shapes, joined groups round only their outer boundary.

Fonts and typography

• The five slots are body, mono, serif, accent, and display. The core fonts block names Fira Sans, Fira Mono, and Lora for the first three.
• A family name is mapped through the font catalogue (theme/phi-font-catalogue.ts) to its CSS variable: --phi-font-source-body, --phi-font-source-mono, --phi-font-source-serif for the core families, plus the variables Modules declare. A name not in the catalogue reaches the browser as written. A phis:asset/<id> slot is resolved to @font-face rules for the Site-owned Asset (theme/phi-theme-fonts.server.ts).
• accent and display have no core family. Widget font keys resolve them to body when unset.
• Widget typography keys (types/site-theme.ts, components/widgets/helpers/):

  • fontFamily = inherit | system | body | mono | serif | accent | display, resolved from usePhiConfig().fonts and the Ant Design token; system is the token fontFamily.
  • fontSize = inherit | xs | sm | base | lg | xl | xxl, resolved to PHI_FONT_SIZES.xs, fontSizeSM, fontSize, fontSizeLG, fontSizeXL, PHI_FONT_SIZES.xxl. display is not offered there.
• Sizes use Ant Design tokens and --ant-font-size* variables; there is no --phi-font-size-* or --phi-font-family-* contract.
• Declaration, preloading, Module font contributions, and Site-owned font files: NEXT_INTEGRATION.md.

Tokens and CSS rules

• theme.palette and theme.style.token, resolved over the followed blocks, are the only source of Ant Design design tokens. cssVar output and SSR --ant-* variables derive from that source. The px2rem pass over the generated structure is a rem bridge, not a token source.
• Client Components read Ant Design semantics from usePhiConfig().token (or theme.useToken() inside a nested Ant Design provider). Plain CSS and Server Components use var(--ant-...). Server Components never depend on ConfigProvider or client theme hooks.
• --phi-* is reserved for Phi-owned structural or technical values that Ant Design does not model -- Shell geometry, Builder scaffold geometry, effects, font sources, Control shape radii. Do not mirror Ant Design colours, spacing, radii, typography, shadows, control sizes, or motion into --phi-*.
• Custom colours are data in usePhiConfig().customColors, never global CSS variables; consumers do not reconstruct them from CSS or substitute semantic tokens. The Theme workspace is the only place that supplies an unpublished draft palette explicitly.
• A component-scoped custom property may bridge a live token into a selector or pseudo-element; it is an implementation detail, not a second theme API.
• Use inline styles for geometry and per-instance layout values. Do not hydrate token-derived visual end values (color, background, border*, boxShadow) through inline styles in Client Components when a class or CSS variable expresses them; browsers normalize them and cause hydration mismatches.
• PHI_* constants (theme/phi-tokens.ts) are seed and default values, not an active runtime theme source. Stable Shell dimensions come from theme.shell, with PHI_* only as defaults.
• Server components may read runtime.site.theme only for Site-owned contracts Ant Design does not model, such as Shell, Brand, and Contact.
• Prefer Ant Design theme and component tokens and component variants over CSS overrides. Hardcoded colours, radii, typography values, or bespoke tuning are added only on explicit operator request.
• ConfigProvider carries Ant Design configuration only, never Phi Site or runtime config. Provider-level component styles are never hardcoded in the root layout; visual defaults flow through the shared token helpers and stay overridable by site.theme.
• Feature code persists semantic Phi values (for example theme.shape.controls); adapter token names and CSS values are resolved centrally and never appear in Module or Widget config.

Phi scale

CSS files

• PhiRootLayout imports antd/dist/reset.css directly and hosts the providers; it does not own Shell topology.
• styles/root.css holds the base html / body rules, root-level effect rules, and small utilities.
• styles/control-shape.css applies the Control shape to small and large Control sizes.
• styles/shell.css and Region chrome: SHELL.md.
• styles/layout.css, layout-authoring-scaffold.css, layout-affordances.css, and builder-scaffold.css: LAYOUTING.md. Builder scaffold styles are imported only by Builder authoring, never by the Root or a Public runtime entry.

Rules

• site.theme holds Site-wide presentation defaults. It is not the page-metadata owner; page title and description come from the Page record.
• Widget instance config lives on CMS nodes; Area presets own Region, Layout, and Widget structure.
• A Widget or Layout is a shell around Ant Design: inside one, Ant Design is free, and a Widget may arrange its own Controls with Flex, Space, Row, or Col. Composing several Widgets belongs to Layouts and their slots only, never to an Ant Design layout primitive or hand-written CSS. A Widget never contains another Widget.