Docs / Format spec

Complete example

A full, linter-valid DESIGN.md covering all eight standard sections and every token category. Use this as a template — replace the values with your own design system.

This file passes all seven lint rules, including WCAG AA contrast checks on all component color pairs. Copy it, swap the values, and run the linter to confirm your file is valid:

npx @google/design.md lint DESIGN.md

The complete file:

---
name: "Pebble Banking"
version: "1.2.0"

colors:
  primary:     "#1A1C1E"
  accent:      "#B8422E"
  neutral:     "#F7F5F2"
  surface:     "#FFFFFF"
  surface-alt: "#F4F2EF"
  border:      "#E5E1DC"
  on-primary:  "#FFFFFF"
  on-accent:   "#FFFFFF"
  error:       "#C0392B"
  success:     "#27AE60"
  text-1:      "#1A1C1E"
  text-2:      "#555250"
  text-3:      "#8C8884"

typography:
  h1:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 3rem
    fontWeight: 800
    lineHeight: 1.05
    letterSpacing: -0.03em
  h2:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 2rem
    fontWeight: 700
    lineHeight: 1.15
    letterSpacing: -0.02em
  h3:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 1.25rem
    fontWeight: 600
    lineHeight: 1.3
  body:
    fontFamily: "Inter"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.65
  body-sm:
    fontFamily: "Inter"
    fontSize: 0.875rem
    fontWeight: 400
    lineHeight: 1.6
  label:
    fontFamily: "Manrope"
    fontSize: 0.75rem
    fontWeight: 500
    letterSpacing: 0.06em
  mono:
    fontFamily: "JetBrains Mono"
    fontSize: 0.8125rem
    fontWeight: 400
    lineHeight: 1.7

spacing:
  xs:  4px
  sm:  8px
  md:  16px
  lg:  32px
  xl:  64px
  2xl: 128px

rounded:
  sm:   4px
  md:   8px
  lg:   16px
  xl:   24px
  full: 9999px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.full}"
    padding: "12px 24px"
    fontWeight: 600
    fontSize: "14px"

  button-accent:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.on-accent}"
    rounded: "{rounded.full}"
    padding: "12px 24px"
    fontWeight: 600
    fontSize: "14px"

  button-ghost:
    backgroundColor: "transparent"
    textColor: "{colors.primary}"
    borderColor: "{colors.border}"
    borderWidth: "1px"
    rounded: "{rounded.full}"
    padding: "12px 24px"
    fontWeight: 500
    fontSize: "14px"

  card:
    backgroundColor: "{colors.surface}"
    borderColor: "{colors.border}"
    borderWidth: "1px"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"

  card-elevated:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.xl}"
    padding: "{spacing.lg}"
    boxShadow: "0 4px 20px rgba(26, 28, 30, 0.08)"

  input:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text-1}"
    borderColor: "{colors.border}"
    borderWidth: "1px"
    rounded: "{rounded.md}"
    padding: "10px 14px"
    fontSize: "14px"

  input-error:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text-1}"
    borderColor: "{colors.error}"
    borderWidth: "1px"
    rounded: "{rounded.md}"
    padding: "10px 14px"
    fontSize: "14px"

  badge:
    backgroundColor: "{colors.surface-alt}"
    textColor: "{colors.text-2}"
    rounded: "{rounded.full}"
    padding: "3px 10px"
    fontSize: "12px"
    fontWeight: 500

  badge-accent:
    backgroundColor: "rgba(184, 66, 46, 0.08)"
    textColor: "{colors.accent}"
    rounded: "{rounded.full}"
    padding: "3px 10px"
    fontSize: "12px"
    fontWeight: 500
---

## Overview
Pebble Banking is a mobile-first fintech product for everyday users aged 25–50.
Visual language: clean, trusted, approachable. Emotional response: secure,
calm, and competent. Never flashy — never cold. Every design decision should
reinforce trust and reduce cognitive load.

## Colors
primary (#1A1C1E) is the single highest-emphasis color. Use it for the primary
CTA per screen, active nav items, and text on light surfaces.

accent (#B8422E) is reserved exclusively for alerts, errors, and destructive
states. Never use it as a primary action color — it signals caution.

neutral (#F7F5F2) is the default page background. surface (#FFFFFF) is for
elevated elements like cards and modals.

text-2 (#555250) and text-3 (#8C8884) are for secondary and tertiary text.
Never use text-3 for interactive elements.

## Typography
Headlines use Plus Jakarta Sans at tight leading. Body copy uses Inter.
Monospace code uses JetBrains Mono. All-caps labels use Manrope — never
use uppercase on body copy.

Never mix more than two typefaces in a single component. Default to
fontWeight 600 for h3 and below to maintain visual hierarchy without relying
on size alone.

## Spacing
Base unit is 4px. Use sm (8px) for inline gaps between icons and labels.
Use md (16px) for card internal padding at mobile breakpoints and form
field spacing. Use lg (32px) for card internal padding at desktop and
between content sections.

## Components
All buttons are pill-shaped (rounded-full). Use button-primary for the
single highest-emphasis action per screen. Use button-ghost for secondary
actions in the same viewport — never stack two button-primary elements.

Cards use a 1px border on the light surface. Use card-elevated (with
box-shadow, no border) only for floating elements like modals and dropdowns.

Input fields have a 1px neutral border at rest; this becomes borderColor error
on validation failure.

Badges are non-interactive indicators. badge-accent is for status tags
that need attention (overdue, expired) — not for positive states.

## Do's and Don'ts
Do: use surface (#FFFFFF) for elevated card backgrounds on the neutral base.
Do: pair every action badge with a text label — never communicate state
through colour alone.
Do: use card-elevated (shadow, no border) for modals and drawers.

Don't: use accent (#B8422E) for primary CTAs — it signals caution or danger.
Don't: mix font families within a single component.
Don't: use text-3 (#8C8884) for any interactive element — it fails WCAG AA
on the neutral background.

## Accessibility
WCAG AA compliance minimum on all text and interactive elements. Focus
indicator: 2px solid primary with 2px offset. Minimum tap target 44×44px.
Never communicate state through colour alone — pair with an icon or label.
error states require both borderColor change and an error message below
the field.

## Motion
Transitions: 150ms ease-out on interactive element state changes (hover,
focus, active). Expansion/collapse: 200ms ease-in-out. Page transitions:
250ms ease-in-out on opacity and translateY. Always respect
prefers-reduced-motion — disable transitions when set.