Definition

The xtyle definition is the core artifact. It declares a portable, structured brand identity that compilers translate into platform-specific output.

Required Fields

Field	Type	Description
xtyle	string	Spec version (e.g. "1.0"). Major.minor only.
name	string	Machine-readable identifier. Lowercase, hyphens allowed.

Everything else is optional. A valid definition can contain a single color, just a tagline, or just a voice spec.

The Three Pillars

Visual (hard)

Tokens that compile to visual output. Deterministic — a hex code is a hex code.

• Colors — palette definitions, semantic mappings, contrast rules
• Typography — font families, type scale, weights, line heights
• Spacing — rhythm scale, grid definitions
• Iconography — icon set references, sizing, style
• Imagery — logo variants, aspect ratios, usage constraints
• Layout — border radii, shadows, elevation, breakpoints

Verbal (hard)

Tokens that compile to text output. Deterministic — a tagline is a tagline.

• Identity — product names, slogans, taglines, descriptions
• Jargon — domain-specific terminology with definitions
• Copy — approved fragments keyed by purpose, versioned
• Boilerplate — legal, disclaimers, standard footers

Voice (soft)

Structured guidance for humans and LLMs. Not mechanically reproducible, but structured enough that an LLM doesn’t have to guess and a new hire doesn’t have to absorb vibes.

• Tone — mood, intensity, formality, humor
• Values — principles, decision-making heuristics
• History — origin, milestones, pivots
• Positioning — what it is, what it isn’t
• Audience — who it serves, who it doesn’t
• Art direction — visual energy, mood references, anti-references
• Register — how the voice modulates across contexts
• Vocabulary — reach, blacklist, profanity stance
• Anti-patterns — what this voice is explicitly not

Component Anatomy

The visual.components section describes UI elements as framework-agnostic anatomy definitions. Each component declares its structural parts, interactive states, size variants, and visual variants — all using token references that resolve through the definition’s palette, semantic, typography, spacing, and layout tokens.

Structure

{
  "visual": {
    "components": {
      "button": {
        "anatomy": { ... },
        "states": { ... },
        "sizes": { ... },
        "variants": { ... }
      }
    }
  }
}

Anatomy

The anatomy object maps component parts to their token properties. The first key is always the root element. Subsequent keys are child parts.

{
  "anatomy": {
    "container": {
      "background": "amber",
      "border-radius": "md",
      "padding-x": "md",
      "padding-y": "sm",
      "font-family": "heading",
      "font-weight": 700
    },
    "label": {
      "color": "coal",
      "font-size": "1rem"
    }
  }
}

Token references resolve through the definition: "amber" matches a palette color, "md" matches a spacing or radius value, "heading" matches a font family. Values that don’t match any token pass through as-is (e.g. "1rem", 700).

States

State overrides apply on top of the base anatomy. Keys are state names (hover, focus, disabled, etc.), values are objects keyed by anatomy part name.

{
  "states": {
    "hover": {
      "container": { "background": "#D4900F", "box-shadow": "mid" }
    },
    "disabled": {
      "container": { "background": "char", "opacity": "0.5" },
      "label": { "color": "steam" }
    }
  }
}

Sizes

Size variants override root-level properties. Each size key maps to a flat object of property overrides.

{
  "sizes": {
    "sm": { "padding-x": "sm", "padding-y": "xs", "font-size": "0.875rem" },
    "md": { "padding-x": "md", "padding-y": "sm", "font-size": "1rem" },
    "lg": { "padding-x": "lg", "padding-y": "md", "font-size": "1.125rem" }
  }
}

Variants

Variants override anatomy at the part level. Each variant is keyed by part name, then by property.

{
  "variants": {
    "secondary": {
      "container": { "background": "transparent", "border": "1px solid amber" },
      "label": { "color": "amber" }
    }
  }
}

Compilers consume this structure and translate it to platform-specific output — CSS classes, Svelte components, or whatever the target requires. The definition stays framework-agnostic.

File Naming

brand.xtyle.json           single-file definition
brand.xtyle.yaml           single-file YAML variant
brand.xtyle/               directory definition
  xtyle.json               root manifest
  visual.json
  verbal.json
  voice.json
  variants/

Schema

The definition schema is available at definition.schema.json. Point your $schema field at it for editor autocomplete:

{
  "$schema": "https://xtyle.dev/schema/definition/v1.0.json",
  "xtyle": "1.0",
  "name": "my-brand"
}