DESIGN.md: Спецификация формата для описания визуальной идентификации для кодирующих агентов

Лаборатория Google выпустила DESIGN.md — спецификацию формата для описания визуальной идентичности кодовым агентам. Файл объединяет машиночитаемые токены дизайна (YAML front matter) с человекочитаемым обоснованием дизайна (разметка Markdown). Токены дают агентам точные значения; текст объясняет, почему эти значения существуют и как их применять.

Обзор формата

Файл DESIGN.md имеет два слоя, разделенные верхними ограничителями ---: YAML front matter для токенов и тело Markdown с разделами ##. Пример отрывка:

---
name: "Heritage"
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: "Public Sans"
    fontSize: "3rem"
  body-md:
    fontFamily: "Public Sans"
    fontSize: "1rem"
  label-caps:
    fontFamily: "Space Grotesk"
    fontSize: "0.75rem"
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"

Токены являются нормативными значениями. Текст предоставляет контекст для применения.

Ключевые возможности

• Типы токенов: Цвета (hex sRGB), объекты типографики (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation), размеры (число+единица), ссылки на токены ({path.to.token}).
• Компоненты: Сопоставляют имя с подсвойствами токенов, например components.button-primary.backgroundColor: "{colors.tertiary}".
• Порядок разделов (необязательно, но соблюдается): Обзор, Цвета, Типографика, Макет и интервалы, Высота и глубина, Формы, Компоненты, Правила и запреты.

Инструменты командной строки

Валидация DESIGN.md с помощью линтера:

npx @google/design.md lint DESIGN.md
{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Обнаружение регрессий между версиями:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
  "tokens": {
    "colors": {
      "added": ["accent"],
      "removed": [],
      "modified": ["tertiary"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Пример использования

Агент, читающий пример Heritage, создаст интерфейс с глубокими черными заголовками шрифтом Public Sans, теплым известняковым фоном (#F7F5F2) и кнопками действия цвета Boston Clay (#B8422E) — и всё это из одного файла.