design-spec-md
Write precise Markdown design specs: requirements, tokens, states, a11y, responsive. Use to make agents understand design exactly.
Design Spec in Markdown
Precise Markdown specs that make agents understand design exactly.
Quick Start
# Feature: Checkout form
## Goal
Let users pay in under 60 seconds with zero confusion.
## Audience
Mobile-first shoppers, low patience, possible screen readers.
## Tokens
- colors: bg/surface/foreground/primary/border/ring
- spacing: 4/8/16/24 scale only
- radii: sm 6px, md 12px, lg 20px
## Out of scope
- No new brand colors, no custom fonts.# validate the spec before building with your own repo's checker,
# e.g.: python scripts/check_spec.py docs/specs/checkout.mdWhen to Use
- Any UI task given to an AI agent
- Landing pages, dashboards, forms, mobile screens
- Retheme or redesign of existing apps
- Handoff between human and agent
- Design reviews and pre-delivery checks
Best Practices
Goal
- One sentence, one measurable outcome
- State the user job, not the component list
- Add a time or quality bar when possible
- No marketing fluff in the goal
Audience
- Device, context, constraints (one-handed, sunlight, keyboard-only)
- Accessibility needs up front
- What the user already knows (skip re-explaining)
- Edge users: zoom 200%, slow network, old phones
Tokens
- Reuse existing semantic tokens, never hard-code hex
- Map roles: background, surface, foreground, primary, border, ring
- Typography: font, sizes, line-height, weights
- Spacing and radii from the scale, no magic numbers
Components and States
- List components with props and variants
- Every interactive element needs default/hover/focus/disabled/error/empty/loading
- Focus visible for keyboard, 44px+ touch targets
- Reduced motion respected, no bounce easing
Responsive and A11y
- Breakpoints 375/768/1024/1440 with behavior per breakpoint
- Contrast 4.5:1 minimum for text
- Meaning never by color alone
- Chips and badges reflow, long tokens wrap safely
Dependencies
# no runtime required, spec is plain Markdown
# optional local checks
python3 --versionExamples
# Spec: SaaS pricing section
## Goal
Visitors compare 3 plans and click CTA without scrolling confusion.
## Tokens
- primary: indigo-600, hover indigo-700
- surface: white, border slate-200
- font: Inter/ system fallback, h2 32/40 bold
## Components
- PricingCard x3: title, price, features[5 max], CTA
- States: default, highlighted (middle), focus-visible ring
## A11y
- h2 hierarchy, list semantics for features
- CTA contrast 5.1:1, keyboard reachable# Spec: Ops dashboard table
## Goal
Operators scan 500 rows and spot failures in seconds.
## Tokens
- danger: red-600 with icon + text (never color alone)
- density: comfortable/compact toggle
- font: tabular numbers for metrics
## States
- loading skeleton, empty with action, error with retry
- row hover subtle, selected with checkbox + aria-selected# Spec: Mobile onboarding (3 steps)
## Goal
80% completion, under 90 seconds.
## Constraints
- One primary action per screen
- Back + skip always visible
- No keyboard traps, safe-area respected
## Validation
- Test on 360px wide, 200% text scaling
- Screen reader order matches visual order## Anti-patterns to forbid in the spec
- "Make it beautiful" without tokens or constraints
- Emojis as icons (use SVG: Lucide/Heroicons)
- Cards nested in cards, gray text on colored bg
- Pure black (#000) or pure gray fillsStep-by-Step
1. Write Goal in one measurable sentence.
2. Describe Audience, devices, and constraints.
3. Lock Tokens: colors, typography, spacing, radii.
4. List Components with all interaction states.
5. Define Responsive behavior per breakpoint.
6. Add A11y requirements: contrast, focus, semantics.
7. Declare Out of scope explicitly.
8. Run the Validation checklist before building.
Validation
1. Goal is measurable and single-sentence
2. Tokens cover all colors and fonts used, no hard-coded hex
3. Every button and input has hover, focus, disabled, error states
4. Contrast 4.5:1 minimum, focus visible, touch targets 44px+
5. Layout works at 375/768/102vpx without clipping
Troubleshooting
- Agent ignores spec: shorten to one page, move details to appendix.
- Vague output: replace adjectives with tokens and numbers.
- Clipped chips: require wrap or +n disclosure in the spec.
- Color-only meaning: add icon + text rule to A11y section.
- Scope creep: enforce Out of scope, new asks go to v2.
Design Spec в Markdown (Спецификация дизайна)
Точные Markdown-спеки, чтобы агенты понимали дизайн без догадок.
Быстрый старт
# Фича: Форма оплаты
## Цель
Пользователь платит за 60 секунд без путаницы.
## Аудитория
Мобильные покупатели, низкая терпимость, возможны скринридеры.
## Токены
- цвета: bg/surface/foreground/primary/border/ring
- отступы: только шкала 4/8/16/24
- радиусы: sm 6px, md 12px, lg 20px
## Вне скоупа
- Без новых фирменных цветов и шрифтов.# проверка спеки перед разработкой
python scripts/check_spec.py docs/specs/checkout.mdКогда использовать
- Любая UI-задача для ИИ-агента
- Лендинги, дашборды, формы, мобильные экраны
- Ретеминг или редизайн существующего приложения
- Передача между человеком и агентом
- Ревью дизайна и предрелизные проверки
Лучшие практики
Цель
- Одно предложение, один измеримый результат
- Формулируйте задачу пользователя, а не список компонентов
- Добавьте время или планку качества, если можно
- Без маркетинговой воды в цели
Аудитория
- Устройство, контекст, ограничения (одна рука, солнце, только клавиатура)
- Потребности доступности — сразу
- Что пользователь уже знает (не переобъяснять)
- Крайние кейсы: зум 200%, медленная сеть, старые телефоны
Токены
- Переиспользуйте семантические токены, не хардкодьте hex
- Роли: background, surface, foreground, primary, border, ring
- Типографика: шрифт, размеры, интерлиньяж, насыщенность
- Отступы и радиусы только из шкалы, без магических чисел
Компоненты и состояния
- Список компонентов с пропсами и вариантами
- Каждому интерактиву нужны default/hover/focus/disabled/error/empty/loading
- Фокус видим с клавиатуры, тач-цели 44px+
- Уважайте reduced motion, без bounce-easing
Адаптив и доступность
- Брейкпоинты 375/768/1024/1440 с поведением на каждом
- Контраст текста минимум 4.5:1
- Смысл никогда только цветом
- Чипы и бейджи переносятся, длинные токены врапятся
Зависимости
# рантайм не нужен, спека — обычный Markdown
# опциональные локальные проверки
python3 --versionПримеры
# Спека: Тарифная секция SaaS
## Цель
Посетитель сравнивает 3 тарифа и жмет CTA без путаницы.
## Токены
- primary: indigo-600, hover indigo-700
- surface: white, border slate-200
- шрифт: Inter/системный, h2 32/40 bold
## Компоненты
- PricingCard x3: заголовок, цена, фичи[макс 5], CTA
- Состояния: default, выделенная (средняя), focus-visible ring
## Доступность
- иерархия h2, списки для фич
- контраст CTA 5.1:1, доступ с клавиатуры# Спека: Таблица опс-дашборда
## Цель
Оператор сканирует 500 строк и видит сбои за секунды.
## Токены
- danger: red-600 с иконкой + текстом (не только цветом)
- плотность: переключатель comfortable/compact
- шрифт: табличные цифры для метрик
## Состояния
- скелетон загрузки, пустое с действием, ошибка с ретраем
- hover строки subtle, выбранное с чекбоксом + aria-selected# Спека: Мобильный онбординг (3 шага)
## Цель
80% прохождения за 90 секунд.
## Ограничения
- Одно главное действие на экран
- Назад + пропустить всегда видны
- Без клавиатурных ловушек, safe-area учтена
## Проверка
- Тест на 360px и масштабе текста 200%
- Порядок скринридера совпадает с визуальным## Запрещенные антипаттерны в спеке
- "Сделай красиво" без токенов и ограничений
- Эмодзи вместо иконок (только SVG: Lucide/Heroicons)
- Карточки в карточках, серый текст на цветном фоне
- Чистый черный (#000) и плоские серые заливкиПошаговое руководство
1. Напишите Цель одним измеримым предложением.
2. Опишите Аудиторию, устройства и ограничения.
3. Зафиксируйте Токены: цвета, шрифты, отступы, радиусы.
4. Перечислите Компоненты со всеми состояниями.
5. Определите Адаптив под каждый брейкпоинт.
6. Добавьте Доступность: контраст, фокус, семантика.
7. Явно укажите Вне скоупа.
8. Прогоните чек-лист Валидации до разработки.
Валидация
1. Цель измерима и в одном предложении
2. Токены покрывают все цвета и шрифты, нет хардкода hex
3. У каждой кнопки и инпута есть hover, focus, disabled, error
4. Контраст 4.5:1, фокус виден, тач-цели 44px+
5. Раскладка работает на 375/768/1024/1440 без клиппинга
Устранение неполадок
- Агент игнорирует спеку: сократите до страницы, детали в приложение.
- Размытый выхлоп: замените прилагательные токенами и числами.
- Клиппинг чипов: требуйте wrap или +n раскрытие.
- Смысл только цветом: добавьте правило иконка + текст.
- Расползание скоупа: держите Вне скоупа, новое — в v2.