STYLE.md

A file format for portable creative style specifications.

STYLE.md is a Markdown file with YAML front matter that describes a creative style — colors, typography, mood, voice, lighting, composition, materials, motion, and more. Any AI tool that reads Markdown can consume it.

The format is designed for the same use case as DESIGN.md (UI implementation tokens for coding agents), but for a broader creative surface: photography, illustration, copywriting, motion graphics, product design, video, and any discipline where consistent aesthetic output matters.

Drop a STYLE.md file in your project root. Your coding agent, image generator, writing assistant, or diffusion model reads it as context and applies the style to every output.

Quick Start

Create a file called STYLE.md in your project root:

---
name: "Studio Warm"
description: "Warm minimal photography style with soft lighting"
sections:
  - output-format
  - colors
  - light-and-shadow
  - mood-and-personality
signals:
  color_palette: "#F5E6D3 30%, #2C1810 25%, #D4956A 20%"
  mood_personality: "Calm, Minimal, Warm"
  lighting_mood_style: "Golden-hour"
---

# Studio Warm

> This file defines a creative style specification for AI-generated content.
> Apply all rules below to every generated image, text, video, or design.

## Output Format

Photography. Digital. 3:2 aspect ratio.

## Colors

Palette: #F5E6D3 30%, #2C1810 25%, #D4956A 20%, #8B6914 15%, #F0F0E8 10%.
Warm temperature. Muted saturation. Low-medium contrast.

## Light & Shadow

Natural lighting. Soft key light. Single source. Golden-hour mood.
Shadow type: Soft. Exposure: Slightly overexposed.

## Mood & Personality

Calm, Minimal, Warm. Energy: Gentle. Emotional bias: Positive.

That's it. Any AI tool that reads your project files will apply this style.

File Structure

A STYLE.md file has two parts:

YAML Front Matter

Machine-readable metadata for quick discovery. Agents can branch on signals without parsing the full document.

---
name: <string>              # required — human-readable style name
description: <string>       # optional — one-line summary
generator: <string>         # optional — tool that produced this file
sections:                   # required — section IDs present in the body
  - <section-id>
signals:                    # optional — key-value summary of top style attributes
  <key>: <string>
---

Markdown Body

The full style specification, organized into ## sections. The prose body is authoritative — signals are for routing only.

Sections

STYLE.md defines 20 creative domains. Include only the ones relevant to your style.

Section ID	Heading	Covers
output-format	Output Format	Medium, platform, aspect ratio, resolution, discipline
mood-and-personality	Mood & Personality	Energy, emotional bias, humor, narrative, characters
colors	Colors	Palette (hex + weights), temperature, contrast, saturation
typography	Typography	Font family, weights, hierarchy, case, scale
light-and-shadow	Light & Shadow	Lighting mood, key light, direction, shadows, atmosphere
voice-and-language	Voice & Language	Formality, vocabulary, directness, sentence length
spatial-structure	Spatial Structure & Hierarchy	Perspective, focal structure, layout, symmetry
camera-and-motion	Camera & Motion	Shot size, angle, DOF, lens, film stock, animation
shape-language	Shape Language	Shape basis, edges, silhouette, negative space
container-and-boundary	Container & Boundary	Container shape, corners, padding, edge behavior
stroke-system	Line & Stroke System	Stroke usage, weight, consistency, color
surface-and-material	Surface, Material & Detail	Texture, material simulation, patterns, micro-detail
post-processing	Post-processing & Render Style	Tone curve, grain, sharpening, render engine
background-and-environment	Background & Environment	Background type, environment mood, props
artistic-mediums	Artistic Mediums & Techniques	Physical medium, illustrative technique
ui-and-web	UI & Web	Color theme, elevation, buttons, icons, navigation
references	References	Cultural references, temporal era, reference brands
inspiration	Inspiration	Reference image URLs
guardrails	Guardrails	Avoided visuals, colors, words, layouts, legal constraints
custom	Custom Style Items	Free-form key-value pairs

Unknown sections are valid and should be preserved by consumers — the format is extensible.

Signals

The signals block provides a compact, machine-readable summary for agents that need to branch on style attributes without parsing the full document.

• Dynamic. Signal keys are derived from the style's content. Different styles produce different keys.
• For routing, not application. Signals tell an agent what kind of style this is. The prose body is what gets applied.
• Budget: ~150 tokens. Typically 6–10 key-value pairs.

Consumer Behavior

Tools that read STYLE.md files should follow these conventions:

Scenario	Expected behavior
Unknown section heading	Preserve and apply; do not error
Unknown signal key	Accept if value is a string
Missing signals block	Valid; signals are optional
Missing description	Valid
Missing generator	Valid
Duplicate section heading	Error; reject the file
Empty section body	Valid; no rules for this domain

Relationship to DESIGN.md

DESIGN.md specifies UI implementation tokens — CSS-ready values for colors, spacing, typography, border-radius, and components. It's precise, code-level, and scoped to web/app interfaces.

STYLE.md specifies creative intent across any medium. It covers the broader aesthetic surface: mood, voice, lighting, camera, materials, composition, motion — and includes a ui-and-web section that overlaps with DESIGN.md for UI direction.

The two formats are complementary. A project can use both: DESIGN.md for exact design tokens, STYLE.md for the creative direction that informs everything else.

Examples

See examples/ for complete STYLE.md files:

• kokeshi/STYLE.md — Japanese kokeshi doll aesthetic (photography, muted earth tones, geometric shapes)

Specification

The full format specification is in spec.md.

Tools

• StyleRef — Visual builder for STYLE.md files. Define your style with structured blocks, extract from images or documents, and export as STYLE.md. Created and maintained by the authors of this format.

Building a tool that reads or writes STYLE.md? Open an issue or email us to be listed here.

License

MIT