Headless

Overview

Headless supports two project types: standard CMS projects for general content management, and component library projects for managing reusable UI components with built-in brand identity.

Component libraries store components as structured content entries with code templates, design token placeholders, and metadata. When consumed, the token placeholders are replaced with your brand's actual values — colors, fonts, spacing, and more.

Creating a Component Library

From your organization, click Create Project
Select Component Library as the project type
Choose a starter pack:
- SaaS Landing Page Kit — 8 components (hero, pricing table, features grid, CTA banner, navbar, footer, testimonials, FAQ)
- Portfolio Kit — 6 components (project card, about section, contact form, skill grid, timeline, image gallery)
- Empty Library — Just the brand profile with no seed components
Enter a project name, slug, and optional description
Click Create

The system automatically provisions three content types and (if selected) seed components with a default brand profile.

Content Types

Every component library project is provisioned with three content types:

Brand Profile (Singleton)

Stores your brand identity as design tokens. Contains 21 fields organized into categories:

Colors (12 fields):

Primary, secondary, accent
Background, surface
Text primary, text secondary, text muted
Border
Error, success

Typography (3 fields):

Heading font, body font, monospace font

Design System (3 fields):

Border radius (none, sm, md, lg, full)
Spacing scale (compact, default, relaxed)
Shadow style (none, soft, medium, bold)

Additional (3 fields):

Design mood (multi-select: modern, clean, playful, corporate, minimal, bold, elegant)
Custom tokens (JSON for brand-specific extensions)
Brand guidelines notes (rich text)

Component

Stores individual UI components with code and metadata. Key fields:

name, description, category, framework, complexity, tags
code_template — Source code with {{token}} placeholders
token_map — JSON mapping placeholder names to brand profile fields
usage_notes, dependencies, version_label, component_status
preview_image — Optional screenshot

Component Collection

Groups related components together. Fields: name, description, components (JSON array of slugs), cover image, sort order.

Brand Configurator

Access the brand configurator from the Brand tab in the library navigation.

The configurator provides a visual editing interface for all 21 brand profile fields:

Color pickers with hex input and preview swatches
Font selectors for heading, body, and monospace families
Dropdown selectors for border radius, spacing, and shadow presets
Multi-select for design mood tags
JSON editor for custom tokens
Rich text editor for brand guidelines

A live preview panel on the right side shows your brand tokens applied to a sample interface in real-time as you make changes.

Changes are saved with optimistic locking to prevent conflicts.

Component Gallery

Access the gallery from the Gallery tab (the default view for component library projects).

The gallery displays all components in a searchable, filterable grid:

Search by component name or description
Filter by category: Navigation, Sections, Cards, Forms, Layout, Data Display, Feedback, Overlays
Filter by framework: React, Vue, Svelte, HTML

Each component card shows the name, description, category, framework, complexity level, and tags.

Component Detail & Live Preview

Click a component to view its full detail page with four tabs:

Preview

A sandboxed iframe renders the component in real-time using React, Babel, and Tailwind CSS. Features:

Theme toggle: Switch between light and dark modes
Brand Applied toggle: View the component with or without brand tokens resolved
Dynamic sizing: The preview iframe adjusts height to fit content

Code

View the component's source code:

Raw template: Shows {{token}} placeholders as-is
Brand-resolved: Shows code with placeholders replaced by actual brand values
Copy to clipboard button

Token Map

A visual table showing each {{token}} placeholder in the code template and which brand profile field it maps to.

Usage

Displays usage notes, dependencies, and version information for the component.

Token System

Components use {{token_name}} placeholders in their code templates. For example:

JSX

<div style={{ backgroundColor: '{{color_primary}}' }}>
  <h1 style={{ fontFamily: '{{font_heading}}' }}>Hello</h1>
</div>

Each component has a token map (JSON) that maps placeholder names to brand profile field names:

JSON

{
  "color_primary": "color_primary",
  "font_heading": "font_heading",
  "color_bg": "color_background"
}

The token resolver replaces each {{placeholder}} with the corresponding value from the brand profile. Custom tokens stored in the custom_tokens JSON field can also be referenced using dot notation (e.g., custom_tokens.gradient_primary).

Consuming Components

Component library data is accessible through all standard Headless APIs.

Via MCP (AI Assistants)

Components are standard content entries, so all existing MCP tools work:

list_entries with contentTypeApiId: "component" to browse components
get_entry to fetch a specific component's code and metadata
semantic_search to find components by description or purpose
find_similar to discover related components

Via REST API

Text

GET /api/v1/{projectSlug}/entries?contentType=component
GET /api/v1/{projectSlug}/entries/{entryId}

Via GraphQL

Query the auto-generated component type with any fields you need.

Connect Page

The Connect tab in the library navigation provides ready-to-use configuration for MCP endpoints, REST API examples, and AI assistant integration instructions.

Documentation

Component Library