AI Integration

Generate PageJSON specs with Claude, ChatGPT, and Cursor AI

Why AI + PageJSON?

PageJSON was designed for AI from the ground up. Unlike traditional HTML/CSS generation which often produces hallucinated code or inconsistent styling, PageJSON's strict schema ensures AI output is:

Reliable - Schema validation prevents invalid JSON
Consistent - Same components render identically every time
Maintainable - JSON is easy to review and modify
Production-ready - No cleanup needed, just build and deploy

Example Prompt 1: Landing Page

Generate a complete landing page for a SaaS product

Create a PageJSON spec for a landing page for "TaskFlow", a project management SaaS tool. Include:

1. Hero section with heading "Manage Projects Effortlessly", subheading about streamlining workflows, 2 CTA buttons ("Start Free Trial" and "Watch Demo"), dark background

2. Feature grid with 6 features: Task tracking, Team collaboration, Time tracking, Reports & analytics, Integrations, Mobile apps. Use icon-cards variant on light background.

3. Stats section showing: 10,000+ Users, 50,000+ Projects, 99.9% Uptime, 4.9/5 Rating. Use stats variant on dark background.

4. Final CTA section centered on primary color asking users to start their free trial.

Ensure proper SEO with title, description, and canonical URL. Use PageJSON schema format.

{
  "seo": {
    "title": "TaskFlow | Project Management Made Simple",
    "description": "Streamline your workflow with TaskFlow. Task tracking, team collaboration, and powerful analytics in one beautiful platform. Start your free trial today.",
    "canonical": "https://taskflow.com"
  },
  "sections": [
    {
      "component": "hero",
      "variant": "simple",
      "data": {
        "heading": "Manage Projects Effortlessly",
        "subheading": "Streamline your workflow with powerful project management tools that your team will actually love to use.",
        "buttons": [
          { "text": "Start Free Trial", "url": "/signup", "style": "brand-secondary" },
          { "text": "Watch Demo", "url": "/demo", "style": "outline-light" }
        ],
        "bg": "dark",
        "align": "center"
      }
    },
    {
      "component": "feature-grid",
      "variant": "icon-cards",
      "data": {
        "heading": "Everything You Need",
        "columns": 3,
        "features": [
          { "icon": "fa-check-square", "heading": "Task Tracking", "body": "Create, assign, and track tasks with ease" },
          { "icon": "fa-users", "heading": "Team Collaboration", "body": "Work together seamlessly in real-time" },
          { "icon": "fa-clock", "heading": "Time Tracking", "body": "Track time spent on every task" },
          { "icon": "fa-chart-bar", "heading": "Reports & Analytics", "body": "Gain insights with powerful reports" },
          { "icon": "fa-plug", "heading": "Integrations", "body": "Connect with your favorite tools" },
          { "icon": "fa-mobile-alt", "heading": "Mobile Apps", "body": "Manage projects on the go" }
        ],
        "bg": "light"
      }
    },
    {
      "component": "feature-grid",
      "variant": "stats",
      "data": {
        "heading": "Trusted by Thousands",
        "columns": 4,
        "features": [
          { "number": "10,000+", "heading": "Users", "body": "Active users" },
          { "number": "50,000+", "heading": "Projects", "body": "Managed daily" },
          { "number": "99.9%", "heading": "Uptime", "body": "Reliability" },
          { "number": "4.9/5", "heading": "Rating", "body": "User satisfaction" }
        ],
        "bg": "dark"
      }
    },
    {
      "component": "cta",
      "variant": "dark-centered",
      "data": {
        "heading": "Start Your Free Trial Today",
        "body": "No credit card required. Full access for 14 days.",
        "buttons": [
          { "text": "Get Started Free", "url": "/signup", "style": "brand-secondary" }
        ],
        "bg": "primary"
      }
    }
  ]
}

Example Prompt 2: Service Page

Generate a service details page with contact form

Create a PageJSON spec for a "Web Development" service page for a digital agency. Include:

1. Simple hero with "Web Development Services" heading, left-aligned on light background

2. Content block (text-only variant) describing the service: what they offer, their approach, and why clients choose them. Include a bulleted list of deliverables.

3. Feature grid with 4 key benefits (icon-cards variant): Custom Design, Responsive & Fast, SEO Optimized, Ongoing Support

4. Contact form (simple variant) with fields for name, email, company, and project details

Include proper SEO optimization.

{
  "seo": {
    "title": "Web Development Services | Premium Digital Solutions",
    "description": "Professional web development services. Custom websites built with modern technologies. Responsive design, SEO optimization, and ongoing support included.",
    "canonical": "https://agency.com/services/web-development"
  },
  "sections": [
    {
      "component": "hero",
      "variant": "simple",
      "data": {
        "heading": "Web Development Services",
        "subheading": "Custom websites that drive results",
        "bg": "light",
        "align": "left"
      }
    },
    {
      "component": "content-block",
      "variant": "text-only",
      "data": {
        "heading": "Build Your Digital Presence",
        "body": "<p>We specialize in creating custom web solutions that help businesses thrive online. Our experienced team combines technical expertise with creative design to deliver websites that not only look great but perform exceptionally.</p><p>Our approach focuses on understanding your business goals and translating them into a digital experience that resonates with your target audience.</p><h3>What's Included:</h3><ul><li>Custom website design and development</li><li>Responsive layouts for all devices</li><li>Search engine optimization (SEO)</li><li>Content management system (CMS)</li><li>Analytics and tracking setup</li><li>Training and documentation</li><li>6 months of post-launch support</li></ul>",
        "bg": "white"
      }
    },
    {
      "component": "feature-grid",
      "variant": "icon-cards",
      "data": {
        "heading": "Why Choose Us",
        "columns": 4,
        "features": [
          { "icon": "fa-paint-brush", "heading": "Custom Design", "body": "Unique designs tailored to your brand" },
          { "icon": "fa-bolt", "heading": "Responsive & Fast", "body": "Optimized for all devices and lightning fast" },
          { "icon": "fa-search", "heading": "SEO Optimized", "body": "Built for search engine visibility" },
          { "icon": "fa-headset", "heading": "Ongoing Support", "body": "Dedicated support after launch" }
        ],
        "bg": "light"
      }
    },
    {
      "component": "contact-form",
      "variant": "simple",
      "data": {
        "heading": "Let's Discuss Your Project",
        "subheading": "Tell us about your needs and we'll get back to you within 24 hours",
        "fields": [
          { "name": "name", "type": "text", "label": "Full Name", "required": true },
          { "name": "email", "type": "email", "label": "Email Address", "required": true },
          { "name": "company", "type": "text", "label": "Company Name" },
          { "name": "details", "type": "textarea", "label": "Project Details", "rows": 5, "required": true }
        ],
        "submitText": "Send Inquiry",
        "bg": "white"
      }
    }
  ]
}

Example Prompt 3: Multi-Page Site

Generate multiple pages for a complete website

Generate PageJSON specs for a 3-page website for "GreenClean", an eco-friendly cleaning service:

**Homepage:**
- Hero with "Eco-Friendly Cleaning Services" heading, green theme
- Feature grid showing 3 services (Residential, Commercial, Deep Cleaning)
- Stats showing experience and satisfied customers
- CTA to book a service

**About Page:**
- Simple hero "About GreenClean"
- Content blocks describing company mission, eco-friendly approach, and team
- Team grid with 4 team members (photos, names, roles)

**Contact Page:**
- Simple hero "Get In Touch"
- Two-column layout: contact form on left, address block on right
- Include phone, email, address, and business hours

All pages should have consistent SEO and branding.

AI generates 3 separate JSON files:

1. index.json (Homepage)
2. about.json (About page)
3. contact.json (Contact page)

Each file includes:
- Proper SEO configuration
- Consistent component usage
- Appropriate variants
- Full data structures
- Properly formatted JSON

→ Ready to place in src/data/pages/
→ Run npm run build
→ Deploy complete website

AI Workflows

Workflow 1: Cursor AI (Recommended)

Open PageJSON project in Cursor
Create new file: src/data/pages/my-page.json
Use Cursor Chat with prompt: "Generate a PageJSON spec for..."
AI writes directly into the file
Run npm run build to test
Iterate with AI if needed

Workflow 2: Claude / ChatGPT

Copy schema reference from /docs/creating-pages
Paste into conversation with your requirements
AI generates complete JSON
Copy output to src/data/pages/my-page.json
Validate JSON syntax
Run npm run build

Workflow 3: Hybrid (AI + Manual)

Use AI to generate initial structure
Manually refine specific components
Ask AI to add missing sections
Fine-tune styling and content

Validation Tips

Ensure AI-generated JSON is valid

// Error 1: Invalid component names
"component": "header"  // ❌ Wrong
"component": "hero"    // ✅ Correct

// Error 2: Missing required fields
"data": {               // ❌ Missing heading
  "subheading": "..."
}
"data": {               // ✅ Has heading
  "heading": "...",
  "subheading": "..."
}

// Error 3: Invalid variant
"variant": "centered"  // ❌ Not a valid variant
"variant": "simple"    // ✅ Valid variant

// Error 4: Trailing commas
{
  "heading": "Title",  // ❌ Trailing comma
}
{
  "heading": "Title"   // ✅ No trailing comma
}

// Error 5: Unescaped quotes in strings
"body": "He said "hello""  // ❌ Breaks JSON
"body": "He said \"hello\"" // ✅ Escaped quotes

Before building, check:

☐ Valid JSON syntax (no trailing commas)
☐ All component names exist (hero, cta, feature-grid, etc.)
☐ All variants are valid for each component
☐ Required data fields present (heading, etc.)
☐ SEO section complete (title, description, canonical)
☐ Button styles are valid (primary, outline-primary, etc.)
☐ Background values are valid (light, dark, white, primary)
☐ Icon classes use Font Awesome format (fa-icon-name)
☐ URLs start with / or https://
☐ No undefined variables or placeholders

Validate JSON at: https://jsonlint.com

Example Prompt 4: Updating Existing Pages

Use AI to modify or enhance existing pages

Here's my current homepage JSON:

[paste existing JSON]

Modify it to:
1. Change hero heading to "Transform Your Business"
2. Add a new feature to the feature grid: "24/7 Support" with fa-headset icon
3. Change the final CTA background to dark
4. Update SEO title to include "2026"

Return only the updated JSON.

AI returns the complete updated JSON with:
- Modified hero heading
- New feature added to features array
- Updated CTA bg property
- New SEO title

All other content preserved exactly.

Simply replace the old file with AI output.

Example Prompt 5: Batch Generation

Generate multiple similar pages at once

Generate PageJSON specs for 5 service pages for a digital marketing agency. Services:

1. SEO Services
2. Social Media Marketing
3. Content Marketing
4. Email Marketing
5. PPC Advertising

Each page should have:
- Simple hero with service name
- Text content block describing the service
- Feature grid with 3 benefits
- Contact form

Use consistent structure across all pages. Return as 5 separate JSON objects labeled with filenames.

AI generates 5 complete JSON specs:

=== seo-services.json ===
{ /* Full JSON */ }

=== social-media-marketing.json ===
{ /* Full JSON */ }

=== content-marketing.json ===
{ /* Full JSON */ }

=== email-marketing.json ===
{ /* Full JSON */ }

=== ppc-advertising.json ===
{ /* Full JSON */ }

Save each to src/data/pages/services/
Build once, get 5 pages.

Best Practices

1. Be Specific

Instead of "create a homepage", say "create a homepage for a SaaS project management tool with hero, 6 features, stats, and CTA"

2. Reference Components

Mention specific component names and variants: "Use hero variant 'simple', feature-grid variant 'icon-cards'"

3. Provide Context

Give AI business context: industry, target audience, key messaging, brand personality

4. Iterate

Start simple, then ask AI to enhance: "Add a testimonials section" or "Make the hero more compelling"

5. Validate First

Always validate JSON before building. Catch syntax errors early.

6. Keep Schema Docs Handy

Reference Creating Pages for component properties and valid values

Documentation