DOCSEARCHbyAlgolia
Submit Docs

DESIGN.md Format Specification

repository·main·Indexed 10 days ago

https://github.com/google-labs-code/design.md

A format specification for describing visual identities to coding agents. It combines structured YAML design tokens with Markdown prose to provide exact values and design rationale. The specification supports exporting tokens to Tailwind CSS v3, Tailwind CSS v4, and the W3C Design Tokens Community Group (DTCG) JSON format. Currently in alpha, it defines schemas for colors, typography, spacing, and component-level tokens.

Tokens
31.7K
Snippets
99
Records
142
Agent score
97%

What's inside DESIGN.md

  1. Overview of the Totality Festival design system

    main

    Totality Festival is a dark, immersive design system designed for a solar eclipse music festival. It utilizes a "Cosmic Premium" aesthetic characterized by:

    • Color Palette: Deep-space obsidian, explosive corona gold, and atmospheric cyan.
    • Visual Styles: Glassmorphism and ambient glow effects.

    The system is distributed via three primary files to support different workflows: a specification file (DESIGN.md), a Tailwind CSS configuration (tailwind.config.js), and a standardized JSON token file (design_tokens.json).

  2. Overview of the Atmospheric Glass design system

    main
    Atmospheric Glass is a glassmorphism-driven design system specifically tailored for weather applications. It utilizes frosted crystalline panels layered over vibrant gradient backgrounds to present meteorological data. The visual language relies on a monochromatic white palette with varying alpha channels to create luminosity and depth.

  5. Totality Festival Design System Specification

    main

    The Totality Festival Design System is a 'Cosmic Premium' aesthetic designed to capture the tension of a solar eclipse. It utilizes Glassmorphism and High-Contrast movements, featuring translucent obsidian surfaces and high-energy accents.

    Core Design Principles

    • Glassmorphism: Use semi-transparent surfaces (10-20% opacity) with a 20px backdrop blur and a 1px inner stroke of white at 10% opacity to simulate glass refraction.
    • Elevation: Depth is achieved through light-based layering rather than drop shadows. Level 3 (Interactive) elements should emit an 'Ambient Glow'—a soft, diffused shadow tinted with Secondary or Primary colors.
    • Color Usage: Mandatory use of radial gradients for backgrounds to simulate the circular nature of an eclipse, transitioning from Neutral at the edges to Tertiary or Secondary at the focal centers.
    • Typography: Use Space Grotesk for headers and labels (geometric/technical) and Inter for long-form content (legibility).
    --- 
name: Totality Festival Design System
colors:
  surface: "#121318"
  primary: "#fff6df"
  secondary: "#bdf4ff"
  tertiary: "#fcf3ff"
  # ... (full token set available in source)
---

  6. Atmospheric Glass Design System Overview

    main
    Atmospheric Glass is a high-fidelity Glassmorphism design system designed for meteorological data visualization. It uses a 'vibrant-minimalist' approach where a multi-colored abstract gradient background provides energy, while UI elements act as frosted crystalline lenses (glass containers) that focus attention. The aesthetic is ethereal, calm, and premium, utilizing transparency, blur, and light refraction to simulate physical layers of glass floating in a digital space.

  7. What is the DESIGN.md format?

    main

    DESIGN.md is a self-contained, plain-text representation of a design system. It serves as a living source of truth for both humans and AI agents to ensure stylistic consistency.

    A file consists of two parts:

    1. YAML Frontmatter (Optional): Contains machine-readable design tokens (colors, typography, spacing, etc.).
    2. Markdown Body: Provides human-readable design rationale, guidance, and prose.

    Prose can use descriptive names (e.g., "Midnight Forest Green") that correspond to systematic token names (e.g., primary). The tokens are the normative values, while the prose provides the context for their application.

  8. Apply Paws & Paths layout and elevation principles

    main

    To maintain the 'Modern Corporate' aesthetic of Paws & Paths, follow these layout and depth rules:

    Layout & Spacing

    • Grid: Use a Fixed Grid model. For mobile, use a 4-column system.
    • Whitespace: Apply a 'generous' philosophy. Use lg and xl spacing for vertical separation between major sections to prevent crowding.
    • Rhythm: All spacing must strictly follow the 8px scale.

    Elevation & Depth

    • Surfaces: Use the lightest neutral tint for main backgrounds. Place interactive cards on a pure white surface (surface-container-lowest) to create a sense of hierarchy.
    • Shadows: Use Ambient Shadows. Shadows should be highly diffused and soft:
      • Blur: 20px-40px
      • Opacity: 4-8%
      • Color: Mix a subtle hint of the primary orange or secondary blue into the shadow color to avoid a 'dirty' gray appearance.
    • Interactions: Elements should subtly lift on hover or tap by increasing the shadow spread, providing tactile feedback.

  9. How to write a DESIGN.md specification

    main

    A DESIGN.md specification consists of two primary components: tokens and prose.

    • Tokens: Defined in YAML, these serve as a reference for the design system (e.g., colors, typography, spacing). They are treated as context rather than strict rendering instructions.
    • Prose: This is the most vital part of the specification. It describes the intent, narrative, and philosophy of the design.

    To achieve high-quality design generation, focus on describing intent through prose rather than just providing precise metric values. Use specific references (e.g., "A 1970s graduate lecture handout") instead of generic adjectives (e.g., "modern, clean") to provide a clear point of reference for models.

  10. How the DESIGN.md format works

    main

    A DESIGN.md file is a hybrid format designed to provide both machine-readable tokens and human-readable rationale to coding agents. It consists of two layers:

    1. YAML front matter: Located at the top of the file, delimited by --- fences. This contains the normative design tokens (colors, typography, spacing, etc.).
    2. Markdown body: Contains design rationale organized into ## sections (e.g., ## Overview, ## Colors).

    The tokens in the YAML section provide the exact values, while the prose in the Markdown section explains the why and the intended application of those values.

    ---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
---

## Overview
Architectural Minimalism meets Journalistic Gravitas.

## Colors
The palette is rooted in high-contrast neutrals.

  11. Configure Component Tokens

    main

    Components in DESIGN.md map a component name to a group of sub-token properties. You can use direct values or Token References (e.g., {colors.primary}) to ensure consistency.

    Valid component properties include:

    • backgroundColor
    • textColor
    • typography
    • rounded
    • padding
    • size
    • height
    • width

    Variants like hover, active, or pressed should be expressed as separate component entries with related key names (e.g., button-primary and button-primary-hover).

    components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

  12. Extend the DESIGN.md format with custom categories

    main

    The DESIGN.md specification defines a structural minimum (name and standard categories like colors, typography, spacing, rounded, and components), but it is extensible.

    You can define any additional keys, sections, or structures required by your specific design system. The format is designed to be flexible so that different teams can implement different types of tokens (e.g., CSS animation curves for motion or audio-domain constants).

    Example of a custom motion section:

    motion:
  feedback: 120ms
  content: 250ms
  easing: 'cubic-bezier(0.2, 0, 0, 1)'