Customization Guide

Make PageJSON match your brand with colors, fonts, and design tokens

Configuration Overview

All customization happens in src/data/site.json. This single file controls:

Brand Colors - Primary, secondary, accent colors and gradients
Typography - Font families for headings, body, and code
Spacing - Global spacing scale
Navigation & Footer - Header and footer configuration
UX Features - Separators, shadows, animations

Brand Colors Configuration

Define your brand's color palette

{
  "brand": {
    "colors": {
      "primary": {
        "hex": "#0F0F0F",
        "name": "Deep Black",
        "contrast": "light"
      },
      "secondary": {
        "hex": "#8B5CF6",
        "name": "Electric Purple",
        "contrast": "light"
      },
      "dark": {
        "hex": "#171717",
        "name": "Charcoal",
        "contrast": "light"
      },
      "light": {
        "hex": "#FAFAFA",
        "name": "Off-White",
        "contrast": "dark"
      },
      "accent": {
        "hex": "#A78BFA",
        "name": "Soft Purple",
        "contrast": "light"
      }
    },
    "gradients": {
      "primary": "linear-gradient(135deg, #0F0F0F 0%, #171717 100%)",
      "secondary": "linear-gradient(135deg, #8B5CF6 0%, #7C3AED 100%)",
      "hero": "linear-gradient(135deg, #0F0F0F 0%, #8B5CF6 50%, #A78BFA 100%)"
    }
  }
}

// Use in components:
{
  "component": "hero",
  "data": {
    "bg": "primary",     // Uses your primary color
    "bg": "dark",        // Uses your dark color
    "bg": "light"        // Uses your light color
  }
}

// Use gradients:
{
  "component": "hero",
  "data": {
    "bgColor": "linear-gradient(135deg, #your-color 0%, #your-color-2 100%)",
    "bgMode": "dark"     // Set text color mode
  }
}

:root {
  --brand-primary: #0F0F0F;
  --brand-primary-rgb: 15, 15, 15;
  --brand-secondary: #8B5CF6;
  --brand-secondary-rgb: 139, 92, 246;
  --brand-dark: #171717;
  --brand-light: #FAFAFA;
  --brand-accent: #A78BFA;
}

/* Auto-generated utility classes */
.bg-brand-primary { background-color: var(--brand-primary); }
.text-brand-secondary { color: var(--brand-secondary); }
.btn-brand-secondary { background: var(--brand-secondary); color: white; }
/* Plus 30+ more utility classes... */

Typography Configuration

Choose from 8 professionally-paired font combinations

{
  "brand": {
    "typography": {
      "preset": "startup",
      "presets": {
        "startup": {
          "name": "Startup",
          "description": "Bold, modern - Space Grotesk + Inter",
          "googleFonts": "https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@400;500;600&display=swap",
          "headingFont": "'Space Grotesk', sans-serif",
          "bodyFont": "'Inter', sans-serif"
        },
        "modern": {
          "name": "Modern Tech",
          "description": "Clean SaaS - Manrope + Inter",
          "headingFont": "'Manrope', sans-serif",
          "bodyFont": "'Inter', sans-serif"
        },
        "editorial": {
          "name": "Editorial",
          "description": "Blog/magazine - Fraunces + Source Sans 3",
          "headingFont": "'Fraunces', serif",
          "bodyFont": "'Source Sans 3', sans-serif"
        }
      }
    }
  }
}

// 8 Typography Presets:

"startup"     // Space Grotesk + Inter (Bold, modern)
"modern"      // Manrope + Inter (Clean SaaS)
"editorial"   // Fraunces + Source Sans 3 (Blog/magazine)
"corporate"   // Outfit + Inter (Professional)
"elegant"     // Cormorant + Lato (Luxury/premium)
"technical"   // JetBrains Mono + IBM Plex Sans (Dev/tech)
"friendly"    // Quicksand + Open Sans (Approachable)
"classic"     // Playfair Display + Lato (Timeless)

// Change by setting:
"preset": "editorial"  // In site.json

Spacing System

Control global spacing between sections

{
  "spacing": {
    "default": "xl",
    "options": ["xs", "sm", "md", "lg", "xl"],
    "description": "xs=tight, sm=compact, md=normal, lg=open, xl=spacious"
  }
}

/* Spacing values: */
xs:  py-3    (1.5rem / 24px)
sm:  py-4    (2rem   / 32px)
md:  py-5    (3rem   / 48px)
lg:  py-6    (4rem   / 64px)
xl:  py-7    (5rem   / 80px)

/* Applied to all sections automatically */
<section class="py-5">  <!-- md spacing -->
<section class="py-7">  <!-- xl spacing -->

Branding Configuration

Logo, tagline, and brand identity

{
  "siteName": "PageJSON",
  "siteUrl": "https://pagejson.com",
  "description": "PageJSON is the first schema-driven page language...",
  "tagline": "Schema-Driven Pages. Built for AI. Powered by JSON.",
  
  "branding": {
    "logoType": "icon",
    "logoIcon": "fa-code",
    "logoText": "PageJSON",
    "logo": "/assets/img/logo/logo.svg",
    "logoLight": "/assets/img/logo/logo-light.svg",
    "favicon": "/assets/img/logo/favicon.png",
    "tagline": "Prompt → PageJSON → Themes"
  }
}

// Option 1: Font Awesome Icon + Text
"logoType": "icon",
"logoIcon": "fa-rocket",      // Any Font Awesome icon
"logoText": "YourBrand"

// Option 2: Image Logo
"logoType": "image",
"logo": "/assets/img/logo.svg",           // Dark navbar
"logoLight": "/assets/img/logo-light.svg"  // Light navbar

// Automatically switches based on header theme

UX Features

Fine-tune user experience settings

{
  "ux": {
    "separators": {
      "enabled": true,
      "style": "light"
    },
    "shadows": {
      "enabled": true
    },
    "animations": {
      "enabled": true,
      "style": "subtle"
    },
    "header": {
      "autoHide": false
    },
    "enhancement": "standard"
  }
}

// Section Separators
separators.enabled: true  // Adds faint borders between sections
separators.style: "light" // or "strong" for darker borders

// Shadows
shadows.enabled: true     // Adds shadows to cards, nav, sidebar

// Animations
animations.enabled: true  // Enable scroll animations
animations.style: "subtle" // or "bold" for more dramatic

// Auto-hide Header
header.autoHide: true     // Header hides on scroll down

// Enhancement Level
enhancement: "minimal"    // Minimal UX features
enhancement: "standard"   // Balanced
enhancement: "rich"       // All features enabled

Header & Footer Configuration

Customize navigation and footer layout

{
  "header": {
    "style": "sticky",
    "theme": "dark",
    "utilityBar": {
      "enabled": true,
      "bgClass": "bg-dark",
      "leftItems": [
        { "type": "phone", "icon": "fa-phone", "text": "020 1234 5678" }
      ],
      "rightItems": [
        { "type": "link", "text": "Get Started", "url": "/contact" }
      ]
    },
    "announcement": {
      "enabled": false,
      "text": "🎉 New feature launched!",
      "link": "/blog/announcement"
    }
  },
  "footer": {
    "main": {
      "variant": "contact-left",
      "theme": "dark",
      "showCompanyName": false,
      "showAddress": false,
      "brandBlock": {
        "tagline": "Your tagline here",
        "description": "Brief elevator pitch"
      }
    },
    "sub": {
      "variant": "minimal",
      "theme": "dark",
      "companyName": "Your Company LLC"
    }
  }
}

Before & After Examples

See how customization transforms your site:

Example 1: Tech Startup

Colors: Deep black (#0F0F0F) + Electric purple (#8B5CF6)
Fonts: Space Grotesk + Inter (preset: "startup")
Spacing: xl (spacious)
Result: Bold, modern, developer-focused aesthetic

Example 2: Professional Services

Colors: Navy (#1E3A5F) + Gold (#D4AF37)
Fonts: Outfit + Inter (preset: "corporate")
Spacing: lg (open)
Result: Trustworthy, professional, corporate feel

Example 3: Creative Agency

Colors: Coral (#FF6B6B) + Teal (#4ECDC4)
Fonts: Fraunces + Source Sans 3 (preset: "editorial")
Spacing: md (normal)
Result: Vibrant, creative, magazine-style layout

Testing Your Customization

After editing site.json:

Run npm run build to regenerate CSS variables
Check dist/assets/css/style.css for your custom CSS variables
Test on different screen sizes (mobile, tablet, desktop)
Verify text contrast with WebAIM Contrast Checker
Check all components still render correctly

Contrast Requirements

For WCAG AA compliance:

Normal text: 4.5:1 contrast ratio minimum
Large text (18px+): 3:1 contrast ratio minimum
UI components: 3:1 contrast ratio minimum

Documentation