STYLE.md format reference

This is the canonical structure of a STYLE.md file: the frontmatter, the body, the valid section ids, and the rules the linter enforces. StyleRef emits this format when you compile a style to stylemd.

File location

Write the file as STYLE.md in a project root, alongside AGENTS.md.

Structure

A STYLE.md file has two parts: a YAML frontmatter envelope and a Markdown body.


---
name: "80s-Inspired Poster"
generator: "styleref.io"
sections:
  - colors
  - typography
  - mood-and-personality
signals:
  color_palette: "#6EC6FF, #0B1E3B, #F2F7FF"
  mood_personality: "Calm, precise, futuristic"
---
 
## Colors
Primary #6EC6FF on a deep #0B1E3B ground; near-white #F2F7FF for text.
 
## Typography
Geometric sans for headings; humanist sans for body. Tight leading.
 
## Mood & Personality
Calm, precise, futuristic. Restrained, never decorative.

This example is the minimal valid shape. Files StyleRef generates also include a # Style Name heading, an enforcement preamble telling the reading agent to treat the spec as a hard constraint, and an attribution footer — the linter accepts both.

Frontmatter

Field	Required	Purpose
`name`	Recommended	The style name. Without it, agents show the style as unnamed.
`generator`	Recommended	Marks the file’s origin. StyleRef emits `generator: "styleref.io"`.
`sections`	Required	A YAML list of the section ids present in the body. Agents use it to route the spec.
`signals`	Optional	A small map of machine-readable values, generated from the style’s top-ranked blocks. Keys vary by style.
`description`	Optional	A one-line description.

The signals keys are generated dynamically from whichever blocks a style populates — they are not a fixed set. Different styles produce different signal keys.

Valid section ids

The sections list and body headings use these ids:


output-format             mood-and-personality      colors
typography                light-and-shadow          voice-and-language
spatial-structure         camera-and-motion         shape-language
stroke-system             surface-and-material      post-processing
background-and-environment artistic-mediums         ui-and-web
container-and-boundary    references                inspiration
guardrails                custom

Body

Write one ## heading per section listed in the frontmatter, in the same order.
Put a prose description of the style under each heading.
Every section declared in the frontmatter should have a matching body section.

Colors

Write colors as valid hex: #RGB, #RGBA, #RRGGBB, or #RRGGBBAA. Malformed hex is the one body-level error the linter rejects outright.

What the linter checks

The linter reports errors (which make the file unusable or misleading) and warnings (quality issues):

Check	Level
Frontmatter block present (`--- … ---`)	Error
`sections:` list present and non-empty	Error
Every section id is known	Error
Body is non-empty	Error
Every hex token is valid	Error
`name:` present	Warning
`generator:` present	Warning
Body has `##` headings	Warning
Each declared section has a body section	Warning

Next steps

Add STYLE.md to a project — write one into a repo.
Validate & lint — run the checks above.
The “Styled with STYLE.md” badge — mark a repo that follows one.