Preset JSON Schema

A preset config is a plain TypeScript object (or JSON file) that declares design tokens and layout preferences. VeloCMS reads it, injects the tokens as CSS custom properties, and applies layout class overrides to the blog templates. No React code required for a preset — it's pure data.

Full schema example

import type { PresetConfig } from "@velocms/plugin-types";

export const myPreset: PresetConfig = {
  name: "Coastal Light",
  version: "1.0.0",
  category: "blog", // "blog" | "magazine" | "portfolio" | "documentation"

  design_tokens: {
    colors: {
      background: "oklch(99% 0.01 210)",  // required
      foreground: "oklch(15% 0.02 210)",  // required
      primary: "oklch(55% 0.20 210)",     // optional
      secondary: "oklch(65% 0.10 210)",
      accent: "oklch(70% 0.25 180)",
      muted: "oklch(94% 0.01 210)",
      muted_foreground: "oklch(50% 0.03 210)",
      border: "oklch(88% 0.01 210)",
    },
    typography: {
      heading_font: "Playfair Display", // required — Google Fonts name
      body_font: "Inter",               // required
      mono_font: "Fira Code",           // optional
      base_size: "18px",
      line_height: 1.75,
      heading_weight: 700,
      body_weight: 400,
    },
    spacing: {
      container_max: "720px",
      section_gap: "gap-16",   // Tailwind class
      card_padding: "p-6",
    },
    borders: {
      radius: "rounded-xl",    // Tailwind class
    },
  },

  layout: {
    header: { variant: "centered", sticky: false },
    posts_grid: { variant: "single-column" },
    sidebar: { show: false },
    footer: { variant: "minimal" },
  },

  components: {
    post_card: {
      variant: "minimal",
      show_image: false,
      show_excerpt: true,
    },
  },
};

Colors

Use OKLCH values for perceptual uniformity. All eight color fields are supported; only background and foreground are required. The theme engine injects these as CSS custom properties (--background, --foreground, etc.) that map directly to Tailwind semantic classes like bg-background and text-foreground.

Typography

heading_font and body_font are Google Fonts display names. The theme engine generates the @import for you — no manual URL construction needed. Set base_size as a CSS length string ("16px", "1.125rem").

Layout variants

Category field

The category field drives how the preset appears in the VeloCMS themes gallery. "blog" is for content-heavy long-form sites, "magazine" for multi-author publications, "portfolio" for visual work, and "documentation" for technical reference sites.