UI Customization Architecture

┌─────────────────────────────────────────────────┐
│                   CSS Output                     │
│  Semantic tokens + custom CSS + block styles     │
├─────────────────────────────────────────────────┤
│                  SiteBranding                    │
│  Injects CSS custom properties from context      │
├─────────────────────────────────────────────────┤
│                 SiteContext                       │
│  Resolves: theme preset → site overrides         │
├─────────────────────────────────────────────────┤
│              Payload CMS Data                    │
│  Themes · Sites · Pages · Layout Templates       │
├─────────────────────────────────────────────────┤
│             Block Registry                       │
│  Field definitions + style fields + renderers    │
└─────────────────────────────────────────────────┘

lib/blocks/
├── registry.ts          # Core registry (registerBlock, getPayloadBlocks)
├── block-style-fields.ts # Shared style fields (auto-appended)
├── shared.ts            # Shared options (icons, accents)
├── index.ts             # Barrel import (triggers registration)
├── hero.ts              # Built-in block definitions
├── features.ts
├── stats.ts
├── details-grid.ts
├── timeline.ts
├── testimonials.ts
├── rich-text.ts
├── cta.ts
├── newsletter-form.ts
└── newsletter-cta.ts

interface BlockPlugin {
  /** Unique slug for this block type */
  slug: string;
  /** Labels for the Payload admin UI */
  labels: { singular: string; plural: string };
  /** Payload CMS field definitions */
  fields: PayloadBlock["fields"];
}

// lib/blocks/pricing-table.ts
import { registerBlock } from "./registry";
 
registerBlock({
  slug: "pricingTable",
  labels: { singular: "Pricing Table", plural: "Pricing Tables" },
  fields: [
    { name: "title", type: "text", required: true, localized: true },
    {
      name: "tiers",
      type: "array",
      required: true,
      minRows: 1,
      fields: [
        { name: "name", type: "text", required: true },
        { name: "price", type: "text", required: true },
        { name: "description", type: "textarea" },
        { name: "features", type: "array", fields: [{ name: "text", type: "text", required: true }] },
        { name: "ctaText", type: "text", defaultValue: "Get Started" },
        { name: "ctaLink", type: "text", required: true },
        { name: "highlighted", type: "checkbox", defaultValue: false },
      ],
    },
  ],
});

import "./pricing-table";

pnpm --filter web exec payload generate:types

export type PricingTableBlock = Extract<Block, { blockType: "pricingTable" }>;

case "pricingTable":
  return <PricingTable tiers={block.tiers} title={block.title} />;

import {
  registerBlock, // Register a new block plugin
  getRegisteredBlocks, // Get all registered BlockPlugin[]
  getPayloadBlocks, // Get Payload Block[] with style fields
} from "@/lib/blocks/registry";

BlockRenderer
  └── for each block:
        └── BlockStyleWrapper
              ├── <div> with classes + inline styles (if style configured)
              │     └── rendered block content
              └── separator element (if configured)

// Padding maps to Tailwind classes. Both directions are spelled out as full
// literal class names — Tailwind only emits utilities it can find verbatim
// while scanning the source, so a class built at runtime never reaches the CSS.
const PADDING_TOP_MAP = { none: "pt-0", sm: "pt-4", md: "pt-8", lg: "pt-16", xl: "pt-24" };
const PADDING_BOTTOM_MAP = { none: "pb-0", sm: "pb-4", md: "pb-8", lg: "pb-16", xl: "pb-24" };
 
// Max width maps to Tailwind classes
const MAX_WIDTH_MAP = { sm: "max-w-3xl", md: "max-w-5xl", lg: "max-w-6xl", xl: "max-w-7xl", full: "max-w-full" };

<div data-block-type="hero" data-block-id="abc123">
  <!-- block content -->
</div>

Theme CSS file (cartographic.css or modern.css)
    ↓
globals.css (@import "../themes/cartographic.css")
    ↓
@theme inline (bridges CSS vars → Tailwind utilities)
    ↓
Components (bg-primary, text-foreground, border-border, etc.)

<UIProvider
  resolveTheme={() => theme ?? "light"}
  lightChartTheme={chartTheme}
  darkChartTheme={darkChartTheme}
  mapColors={mapColors}
  onNewsletterSubmit={handleNewsletter}
  labels={labels}
>
  {children}
</UIProvider>

// Maps SiteBrandingColors keys to CSS custom properties
const COLOR_TOKEN_MAP = {
  primary: "--primary",
  primaryForeground: "--primary-foreground",
  secondary: "--secondary",
  background: "--background",
  foreground: "--foreground",
  // ... 15 tokens total
};

interface SiteContextValue {
  site: Site | null;
  hasSite: boolean;
  branding: {
    title?: string;
    logoUrl?: string;
    logoDarkUrl?: string;
    faviconUrl?: string;
    colors?: SiteBrandingColors; // 15 semantic color tokens
    typography?: SiteTypography; // fontPairing
    style?: SiteStyle; // borderRadius, density
  };
  customCode?: SiteCustomCode; // headHtml, customCSS, bodyStartHtml, bodyEndHtml
}

import {
  resolveLayoutTemplate,
  getContentMaxWidthClass,
  shouldShowHeader,
  shouldShowFooter,
  DEFAULT_LAYOUT,
} from "@/components/layout/layout-shell";
 
// Resolution: page override > site default > platform default
const template = resolveLayoutTemplate(pageLayout ?? siteLayout ?? null);
 
// Use in layout
if (shouldShowHeader(template)) {
  /* render header */
}
if (shouldShowFooter(template)) {
  /* render footer */
}
const widthClass = getContentMaxWidthClass(template.contentMaxWidth);

interface LayoutTemplateConfig {
  headerVariant: "marketing" | "app" | "minimal" | "none";
  footerVariant: "full" | "compact" | "none";
  contentMaxWidth: "sm" | "md" | "lg" | "xl" | "full";
  stickyHeader: boolean;
}

const DEFAULT_LAYOUT: LayoutTemplateConfig = {
  headerVariant: "marketing",
  footerVariant: "full",
  contentMaxWidth: "lg",
  stickyHeader: true,
};

[data-site="my-site-slug"] {
  /* admin's custom CSS here */
}

Slug: themes
Group: Configuration
Access: Read (public), Write (editor/admin)
Versioning: Yes (with drafts)

Fields:
  name (text, required)
  description (textarea)
  colors (group) — 15 semantic tokens for light mode
  darkColors (group) — 15 semantic tokens for dark mode
  typography.fontPairing (select)
  style.borderRadius (select)
  style.density (select)
  createdBy (relationship → users)

Slug: layout-templates
Group: Configuration
Access: Read (public), Write (editor/admin)
Versioning: Yes (with drafts)

Fields:
  name (text, required)
  description (textarea)
  headerVariant (select: marketing/app/minimal/none)
  stickyHeader (checkbox)
  footerVariant (select: full/compact/none)
  contentMaxWidth (select: sm/md/lg/xl/full)
  createdBy (relationship → users)

Added to existing Sites collection:

branding.colors — expanded from 3 to 15 semantic tokens
branding.typography.fontPairing (select)
branding.style.borderRadius (select)
branding.style.density (select)
branding.theme (relationship → themes)
customCode.headHtml (textarea)
customCode.customCSS (textarea)
customCode.bodyStartHtml (textarea)
customCode.bodyEndHtml (textarea)
defaultLayout (relationship → layout-templates)

Added to existing Pages collection:

layoutOverride (relationship → layout-templates)
pageBuilder blocks — now loaded from block registry
  each block includes blockStyle group (auto-appended)