STYLES.md

A simple, open format for defining how your project writes, designs, and communicates — readable by humans and AI coding agents alike.

Think of STYLES.md as a README for style: a predictable, single place for your writing standards, design tokens, and AI agent constraints.

Explore the framework View on GitHub

⚠️ Experimental — Validate before use

This project is still experimental. Most content was generated with AI assistance and has not yet been fully validated in real-world conditions.

A STYLES.md file will not automatically make your project consistent or accessible. What it can do is make your standards explicit, machine-readable, and easier for both humans and AI agents to follow.

Please share your experience — positive or negative — in the issue queue.

Why STYLES.md?

Style guides used to be PDFs, Figma boards, or wiki pages that nobody could find. In an era of AI-assisted development, a style guide must be a machine-readable logic gate.

STYLES.md puts your writing conventions, design tokens, and AI agent constraints in one predictable file at your repo root — where humans, automation, and AI agents can all find and use it.

It is part of a broader ecosystem of open standards: ACCESSIBILITY.md and SUSTAINABILITY.md provide the foundational guardrails that STYLES.md builds on.

The framework

STYLES.md is one part of a three-pillar ecosystem. Together, these standards define not just what you build, but how you build it:

ACCESSIBILITY.md

The foundational requirement. Style is a subset of accessibility. Defines inclusion guardrails and contributor requirements.

SUSTAINABILITY.md

The environmental constraint. Good style is lightweight and efficient. Defines compute and content efficiency rules.

STYLES.md

The expression layer. Voice, tone, design tokens, and AI agent constraints for your specific project.

Two surfaces, one standard

STYLES.md distinguishes between two surfaces that share the same project:

GitHub Pages site

Public-facing pages built with Jekyll. Governed by design tokens, layout patterns, typography, and responsive breakpoints.

Repository documentation

README, AGENTS.md, STYLES.md, examples, and templates. Governed by writing standards, heading hierarchy, and link conventions.

Voice, tone, and accessibility requirements apply to both surfaces. Design tokens and layout patterns apply to the site surface only. See STYLES.md for the full scope table.

How to get started

  1. Fork this repository or copy STYLES-template.md into your project root.
  2. Choose a flavor from the examples folder that matches your context.
  3. Customize the voice, tokens, and rules for your project. Replace all [PLACEHOLDER] values.
  4. Reference it in your AGENTS.md and LLM prompts so AI agents stay on-brand.
  5. Add the companion standards — ACCESSIBILITY.md and SUSTAINABILITY.md — for a complete governance baseline.

Resources in this repository

STYLES.md

This project's own style implementation. Two-surface structure, design tokens, and AI agent rules.

STYLES-template.md

A minimal skeleton to copy into your own project and customize.

Examples

Worked examples for formal-gov, tech-minimal, and low-bandwidth contexts, plus a discovery prompt to generate a STYLES.md for any existing project.

AGENTS.md

Operational instructions for AI coding agents working in this repository.

ACCESSIBILITY.md

Foundational accessibility commitment and contributor guardrails.

SUSTAINABILITY.md

Environmental and compute-efficiency constraints for this project.