Веб-тул
ds-health
Вставляешь URL и получаешь отчёт о здоровье дизайн-системы. Инструмент считает цвета, типографику, отступы и радиусы на живом сайте в настоящем браузере.
Что измеряет
- ЦветаСколько цветов текста и фона на странице. Чем меньше уникальных значений и чем больше CSS-переменных, тем выше счёт.
- ТипографикаСемейства, размеры и начертания видимого текста. Чем их меньше, тем собраннее система.
- ОтступыСколько разных значений padding и gap. Хорошо, когда они сходятся к шкале.
- РадиусСколько ненулевых радиусов. Меньше — ровнее углы.
Запуск
git clone https://github.com/AndrewAntoshkin/ds-health.git
cd ds-health
npm install
npm startОткрой http://localhost:3000. Если порт занят:
PORT=3002 npm startЕсли Playwright не находит браузер:
npx playwright install chromiumКак устроено
Инструмент открывает страницу в настоящем Chromium через Playwright, снимает видимые элементы, читает computed styles и собирает отчёт: счёт, сигналы и рекомендации.
URL → Playwright (Chromium) → getComputedStyle() on sampled elements
→ Count unique colors, fonts, spacing, radii
→ Score each category (0–100)
→ Generate executive summary + priorities + recommendationsAPI
POST /api/analyze
curl -X POST http://localhost:3000/api/analyze \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Запрос
| Поле | Тип | Описание |
|---|---|---|
| url | строка | Публичный HTTP/HTTPS-адрес страницы |
Ответ
| Поле | Тип | Описание |
|---|---|---|
| health.overall | число | Средний балл от 0 до 100 |
| health.color | число | Оценка цельности цвета |
| health.typography | число | Оценка цельности типографики |
| health.spacing | число | Оценка цельности отступов |
| health.radius | число | Оценка цельности скруглений |
| health.label | строка | «Здоровый», «В целом цельный» и другие |
| executiveSummary | строка | Короткий вывод обычным языком |
| priorities | массив | Что чинить первым |
| recommendations | массив | Конкретные следующие шаги |
| signals | массив | Отдельные наблюдения |
| topValues | объект | Самые частые значения по категориям |
GET /health
Возвращает { "ok": true } — удобно для проверки, что сервис жив.
Пример здорового сайта
Результат разбора barvian.me — собранный минималистичный сайт:
| Значение | Что значит |
|---|---|
| 100 | Цвет |
| 100 | Типографика |
| 100 | Отступы |
| 100 | Скругление |
{
"elementsSampled": 69,
"textNodesSampled": 41,
"cssVariables": 4,
"textColors": 3,
"backgroundColors": 3,
"fontFamilies": 1,
"fontSizes": 1,
"fontWeights": 2,
"spacingValues": 4,
"radiusValues": 1
}
Executive summary:
"This page looks healthy. 4 CSS variables were
detected, and no major consistency issues stood
out in the sampled page."Пример раздробленного сайта
Страница с кучей конкурирующих значений — обычная история легаси и быстрых прототипов:
| Значение | Что значит |
|---|---|
| 65 | Цвет |
| 45 | Типографика |
| 70 | Отступы |
| 90 | Скругление |
Priority issues:
⚠ 14 text colors detected — consider consolidating
⚠ 4 font families in use — reduce to 1–2
⚠ 8 font sizes found — align to a type scale
⚠ No CSS variables detected — consider tokenizing
Recommendations:
→ Audit text colors and create a semantic palette
→ Standardize on 1–2 font families
→ Define a spacing scale (4, 8, 12, 16, 24, 32)
→ Introduce CSS custom properties for tokensКак читать отчёт
Удобный порядок чтения: сначала счёт, потом резюме, потом приоритеты, потом сырые значения.
| Раздел | Что показывает |
|---|---|
| Общее здоровье | Среднее четырёх оценок — быстрый сигнал «прошло / не прошло» |
| Короткий вывод | Вывод для тех, кто не читает сырые цифры |
| Приоритеты | Что чинить первым — с наибольшим эффектом |
| Рекомендации | Практичные шаги, которые можно поставить в спринт |
| Сигналы | Отдельные наблюдения — сырые доказательства за оценкой |
| Частые значения | Самые частые цвета, размеры и отступы — где сведение в токены даст больше всего |
| Сведённые группы | Почти одинаковые значения собраны в более чистые группы |
Шкала
| Диапазон | Метка | Что значит |
|---|---|---|
| 90–100 | Здоровый | Жёстко собрано: мало цветов, сдержанная типографика, небольшой набор отступов |
| 70–89 | В целом цельный | Есть разрозненность или несколько разовых значений |
| 50–69 | Нужно внимание | Визуальная система расползается — стоит посмотреть ближе |
| 0–49 | Раздробленный | Слишком много конкурирующих значений — слоя токенов, скорее всего, нет |
Цепочка
ds-health проверяет живую страницу после контура модели, когда интерфейс уже на проде:
ds-context prepares the pack
ds-eval scores generated UI
ds-health reads the live page ← you are here