A single source of truth for content blocks

BlockSpec is an open standard for defining a content block as structured, machine-readable JSON. The HTML contract, content fields, layout variants, design tokens, and authoring guidance — all in one canonical file.

A BlockSpec file is a single .json document describing one block. A library is a collection of BlockSpec files — one per block — composable into pages by StructureSpec.

1. Define the block

   Create a blockspec.json file using the open schema. Specify the HTML contract — data-block slug, allowed surfaces and layouts, structural pattern — alongside content fields, variants, token roles consumed, and authoring guidance.

2. Compose pages with StructureSpec

   StructureSpec references BlockSpec items by slug to compose page archetypes. A "Marketing landing page" type might list Hero, Feature grid, Testimonial, and CTA in sequence — each one a separate BlockSpec file in the library.

3. Render with brand tokens

   A consumer reads the block's HTML contract from BlockSpec and the visual styling from a parent BrandSpec. The same block renders consistently across projects, themed by token swap rather than restyled by hand.

4. Author with guidance

   Field-level prompts, character limits, and voice guidance turn a blank CMS form into a guided framework. The block tells the author what's expected, in what order, with what tone — and AI tools can use the same guidance to draft content directly.

A BlockSpec document is a JSON object with a root block key and seven top-level sections. All sections are optional at the object level but recommended for complete block definition. Identity and contract are the minimum viable spec.

Field definition fields

Contract fields

The contract object defines the HTML/DOM shape every instance of this block must conform to. It is the public interface that consuming tools render against.

A complete BlockSpec document for a Hero block. All fields shown are part of the v0.1.0 schema.

{
  "_export": {
    "blockName":        "Hero",
    "blockSpecVersion": "0.1.0",
    "exportedAt":       "2026-05-02T10:00:00.000Z"
  },

  "block": {

    /* ── Identity ────────────────────────────── */
    "identity": {
      "name":        "Hero",
      "slug":        "hero",
      "category":    "lead",
      "description": "Page-opening section with headline, supporting copy, and CTAs.",
      "version":     "1.0.0"
    },

    /* ── Contract ────────────────────────────── */
    "contract": {
      "dataBlock":        "hero",
      "structure":        "section[data-block=hero][data-surface][data-layout] > .container > .inner",
      "surfaces":         ["default", "muted", "inverse", "accent"],
      "layouts":          ["centered", "split", "media-right", "media-left"],
      "scopedCss":        true,
      "breakpointPolicy": "fluid"
    },

    /* ── Fields ──────────────────────────────── */
    "fields": [
      {
        "name":           "headline",
        "label":          "Headline",
        "type":           "text",
        "required":       true,
        "characterLimit": 80,
        "help":           "The single sentence that earns attention."
      },
      {
        "name":           "subhead",
        "label":          "Supporting copy",
        "type":           "rich-text",
        "required":       false,
        "characterLimit": 240,
        "help":           "One or two sentences expanding on the headline."
      },
      {
        "name":     "primaryCta",
        "label":    "Primary CTA",
        "type":     "link",
        "required": false,
        "help":     "The primary action you want people to take."
      },
      {
        "name":     "media",
        "label":    "Hero image or video",
        "type":     "media",
        "required": false,
        "help":     "Used in split, media-right, and media-left layouts."
      }
    ],

    /* ── Variants ────────────────────────────── */
    "variants": [
      {
        "name":        "centered",
        "layout":     "centered",
        "description": "Headline and copy centered above CTAs. No media.",
        "fieldsUsed":  ["headline", "subhead", "primaryCta"]
      },
      {
        "name":        "split",
        "layout":     "split",
        "description": "Headline left, media right, 50/50 split.",
        "fieldsUsed":  ["headline", "subhead", "primaryCta", "media"]
      }
    ],

    /* ── Tokens consumed ─────────────────────── */
    "tokens": {
      "colors":     ["primary", "neutral", "accent"],
      "typography": ["heading", "body"],
      "spacing":    ["section", "stack-md"]
    },

    /* ── Guidance ────────────────────────────── */
    "guidance": {
      "voice": "Clear and direct. Earn attention with specificity.",
      "fieldPrompts": {
        "headline":   "The single sentence that captures what this page is about. Choose clear over clever.",
        "subhead":    "One or two sentences expanding on the headline with the why or the how.",
        "primaryCta": "The verb is more important than the adjective. 'Start now' beats 'Get amazing access'."
      }
    },

    /* ── Metadata ────────────────────────────── */
    "metadata": {
      "name":        "Hero",
      "version":     "1.0.0",
      "lastUpdated": "2026-05-02T00:00:00.000Z"
    }

  },

  "$schema":  "https://blockspec.org/schema/v0.1/blockspec.json",
  "version":  "0.1.0"
}

BlockSpec is designed to be consumed by any tool that needs a structured block definition — page renderers, CMS field generators, AI authoring tools, design-system documentation. Below are reference patterns for the most common outputs.

Render the HTML contract

Read the contract from BlockSpec and emit the canonical DOM structure. Surface and layout are passed in as attributes; field content fills the inner template.

/* Generated from blockspec.json → block.contract */
<section data-block="hero" data-surface="default" data-layout="centered">
  <div class="container">
    <div class="inner">
      <h1>{{ headline }}</h1>
      <p>{{ subhead }}</p>
      <a href="{{ primaryCta.href }}">{{ primaryCta.label }}</a>
    </div>
  </div>
</section>

Generate a CMS field schema

Map BlockSpec fields directly to ACF field groups, Gutenberg block attributes, or any other CMS field schema. The block becomes a guided form, not a blank page.

// Generate ACF field group from BlockSpec
const spec = await fetch('/blocks/hero/blockspec.json').then(r => r.json());

const acfFields = spec.block.fields.map(field => ({
  key:          `field_${field.name}`,
  label:        field.label,
  name:         field.name,
  type:         mapType(field.type),     // 'text' → 'text'; 'rich-text' → 'wysiwyg'
  required:     field.required,
  maxlength:    field.characterLimit,
  instructions: field.help
}));

AI-assisted authoring

Combine BlockSpec field guidance with PersonSpec or BrandSpec voice to generate calibrated draft content. The block defines what's needed; the brand or person defines how it should sound.

// Draft Hero content from BlockSpec + BrandSpec voice
const block = await fetch('/blocks/hero/blockspec.json').then(r => r.json());
const brand = await fetch('/brandspec.json').then(r => r.json());

const draftPrompt = `
  Block: ${block.block.identity.name}
  Voice guidance: ${block.block.guidance.voice}
  Brand tone: ${brand.brand.voice.tone.join(', ')}

  Generate content for these fields:
  ${block.block.fields.map(f =>
    `- ${f.label} (max ${f.characterLimit} chars): ${block.block.guidance.fieldPrompts[f.name]}`
  ).join('\n')}
`;

BlockSpec is designed to be standards-aware. It builds on, references, and is interoperable with several established frameworks. It is not a replacement for any of them — it is a structured layer that makes them composable in a single, machine-readable file.