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"];
  /** Optional React render function */
  render?: (block: Record<string, unknown>, key: string) => React.ReactElement;
}

// lib/blocks/pricing-table.ts
import type { Field } from "payload";
 
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";

import type { Block } from "@/lib/types/cms-blocks";
 
// Add to the blockRenderers map
const blockRenderers: Record<string, (block: Block, key: string) => React.ReactElement> = {
  // ... existing renderers
  pricingTable: (block, key) => {
    const b = block as Record<string, unknown>;
    return <PricingTable key={key} tiers={b.tiers as Tier[]} title={b.title as string} />;
  },
};

export interface PricingTableBlock {
  blockType: "pricingTable";
  title: string;
  tiers: Array<{
    name: string;
    price: string;
    description?: string | null;
    features?: Array<{ text: string; id?: string | null }> | null;
    ctaText?: string | null;
    ctaLink: string;
    highlighted?: boolean | null;
    id?: string | null;
  }>;
  blockStyle?: BlockStyle | null;
  id?: string | null;
  blockName?: string | null;
}

export type Block =
  | HeroBlock
  | FeaturesBlock
  // ...existing types
  | PricingTableBlock;

import {
  registerBlock, // Register a new block plugin
  getRegisteredBlocks, // Get all registered BlockPlugin[]
  getBlock, // Get a single plugin by slug
  getPayloadBlocks, // Get Payload Block[] with style fields
  getBlockRenderers, // Get render map from plugins with renderers
} 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
const PADDING_MAP = {
  none: "py-0", // → pt-0 or pb-0
  sm: "py-4",
  md: "py-8",
  lg: "py-16",
  xl: "py-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>

Layer 1: Base Colors (Cartographic Palette)
  --cartographic-parchment, --cartographic-navy, etc.
      ↓
Layer 2: Semantic Tokens
  --background, --foreground, --primary, --accent, etc.
      ↓
Layer 3: Component Usage
  bg-background, text-foreground, border-border, etc.

// 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)