Sigil Preset

Sigil Preset

Create and modify complete token presets that define the visual identity of a Sigil-powered project.

The #1 Rule: Full Token Coverage

Every custom preset MUST populate ALL 33 token categories and ALL fields.

The canonical template is packages/presets/src/_template.ts. It contains every field from SigilTokens with sensible defaults. When creating a custom preset:

1. Start from the template — copy _template.ts, rename, change values.
2. Never delete fields — change values, don't remove keys.
3. No partial presets — if a field exists in _template.ts, it must exist in your preset.

The 33 required categories (all must be present):

When to Use

• User asks to create a custom preset
• User asks to modify an existing preset in packages/presets/
• User says "create a preset", "new theme", "custom preset"
• User wants to adjust colors, typography, or spacing for a preset
• User asks which preset to use for a specific aesthetic

How to Use

1. Start from the template

Always start from packages/presets/src/_template.ts. Read it first:

cat packages/presets/src/_template.ts

Then copy and customize:

import type { SigilPreset } from "@sigil-ui/tokens";

export const myPreset: SigilPreset = {
  name: "my-preset",
  metadata: {
    description: "Short description of this preset's aesthetic",
    author: "author-name",
    version: "0.1.0",
    tags: ["category", "mood"],
    mood: "the vibe in 2-3 words",
  },
  tokens: {
    // ALL 33 categories from _template.ts — change values, never delete fields
    colors: { /* all 35 fields */ },
    typography: { /* all 31 fields */ },
    spacing: { /* all 25 fields */ },
    layout: { /* all 22 fields */ },
    sigil: { /* all 10 fields */ },
    radius: { /* all 16 fields */ },
    shadows: { /* all 14 fields */ },
    motion: { /* all 18 fields */ },
    borders: { /* all 11 fields */ },
    buttons: { /* all 9 fields */ },
    cards: { /* all 18 fields */ },
    headings: { /* all 15 fields */ },
    navigation: { /* all 24 fields */ },
    backgrounds: { /* all 9 fields */ },
    code: { /* all 14 fields */ },
    inputs: { /* all 13 fields */ },
    cursor: { /* all 15 fields */ },
    scrollbar: { /* all 13 fields */ },
    alignment: { /* all 13 fields */ },
    sections: { /* all 25 fields */ },
    dividers: { /* all 15 fields */ },
    gridVisuals: { /* all 10 fields */ },
    focus: { /* all 5 fields */ },
    overlays: { /* all 8 fields */ },
    dataViz: { /* all 13 fields */ },
    media: { /* all 6 fields */ },
    controls: { /* all 11 fields */ },
    componentSurfaces: { /* all 12 fields */ },
    hero: { /* all 25 fields */ },
    cta: { /* all 15 fields */ },
    footer: { /* all 15 fields */ },
    banner: { /* all 12 fields */ },
    pageRhythm: { /* all 14 fields */ },
  },
};

2. Built-in presets

3. Creating a new preset (in-repo)

1. Copy packages/presets/src/_template.ts → packages/presets/src/<name>.ts.
2. Rename the export and name field.
3. Change token values — never delete fields.
4. Add to barrel: packages/presets/src/index.ts.
5. Add entry to packages/presets/tsup.config.ts.
6. Add export map entry to packages/presets/package.json.
7. Register in packages/cli/src/commands/init.ts and packages/cli/src/commands/preset.ts.

4. User-created presets (via CLI)

Users can run sigil preset create to scaffold a sigil.preset.<name>.ts file in their project root. The CLI generates from the template with all 33 categories.

Rules

1. All 33 token categories required — a preset must define every field from _template.ts. No partial presets. No missing categories. This is the most important rule.
2. All colors in OKLCH — use oklch(L C H) format exclusively. No hex, rgb, or hsl.
3. Themed colors — background, surface, surface-elevated, all text-*, and all border-* tokens must provide both light and dark values.
4. Unthemed colors — primary, secondary, success, warning, error, info are single values shared across themes.
5. Font stacks — always include system fallbacks (e.g., "Satoshi", system-ui, sans-serif).
6. Spacing scale — must be a 10-element array of ascending numbers, unit is always "px".
7. Radius consistency — values should form a smooth progression (sm < md < lg < xl < 2xl). Exception: brutalist may use 0px for all.
8. Shadow layering — use multi-layer shadows for md/lg/xl to create realistic depth. sm can be a single layer.
9. Motion coherence — faster presets (brutalist) should have shorter durations, softer presets should be slower.
10. Metadata required — description, author, and version must be set.

Validation Checklist

Before considering a custom preset complete, verify:

• All 33 token categories present
• No fields from _template.ts are missing
• All authored colors use OKLCH
• Themed colors have both light and dark
• Spacing scale has exactly 10 ascending values
• Radius values form a smooth progression
• Font stacks include system fallbacks
• Metadata has description, author, version

Examples

Deriving a preset from the template

Copy the template, then change the values that define your aesthetic:

import { _templatePreset } from "./_template.js";
import type { SigilPreset } from "@sigil-ui/tokens";

export const warmPreset: SigilPreset = {
  name: "warm",
  tokens: {
    ..._templatePreset.tokens,
    colors: {
      ..._templatePreset.tokens.colors,
      primary: "oklch(0.65 0.16 35)",
      "primary-hover": "oklch(0.60 0.19 35)",
      secondary: "oklch(0.70 0.14 150)",
    },
    typography: {
      ..._templatePreset.tokens.typography,
      "font-display": '"Fraunces", Georgia, serif',
      "font-body": '"Source Serif 4", Georgia, serif',
      "font-mono": '"Fira Code", ui-monospace, monospace',
    },
    // All other categories inherited from _templatePreset.tokens
  },
  metadata: {
    description: "Warm variant — terracotta primary, serif typography",
    author: "you",
    version: "0.1.0",
  },
};

Choosing OKLCH values

Use this mental model:

• L (lightness): 0 = black, 1 = white. Primary colors: 0.50–0.70. Backgrounds: 0.95–0.99 (light), 0.05–0.12 (dark).
• C (chroma): 0 = gray, 0.20+ = vivid. Body text: 0. Accent colors: 0.12–0.20.
• H (hue): 0 = red, 60 = yellow, 150 = green, 250 = blue, 310 = pink.