Skip to content

USER_GUIDE.md

Latest commit

 

History

History
292 lines (211 loc) · 19.9 KB

USER_GUIDE.md

File metadata and controls

292 lines (211 loc) · 19.9 KB
Raw

Design Lib Inspector — руководство пользователя

Figma-плагин для автоматического UX/UI-аудита макетов по 227 правилам лучших практик. Комбинирует детерминированные проверки (контраст, тач-зоны, типографика) с AI-аудитом через Claude Vision (композиция, иерархия, формы, тёмная тема и т.д.).

1. Установка

Быстрый старт для разработчика

git clone https://github.com/avarentcov/design-libs-plugin.git
cd design-libs-plugin
npm install
npm run build

Подключение к Figma

  1. Открыть Figma (desktop или браузер).
  2. Plugins → Development → Import plugin from manifest…
  3. Выбрать manifest.json из корня репозитория.
  4. Плагин появится в меню Plugins → Development → Design Lib Inspector.

Режим разработки с hot-reload

npm run watch

Пересобирает dist/ui.js и dist/ui.html при каждом изменении в src/. В Figma — Plugins → Development → Hot reload plugin (⌥⌘P).

Получение API-ключа Anthropic (нужен для AI-аудита)

  1. Зарегистрироваться на https://console.anthropic.com
  2. Создать ключ: Settings → API Keys → Create key.
  3. Скопировать ключ (начинается на sk-ant-api03-…).
  4. В плагине: Настройки → API-ключ Anthropic → вставить → Сохранить.

Ключ хранится в figma.clientStorage — привязан к вашему Figma-аккаунту, доступен во всех файлах без повторного ввода.

2. Использование

Базовый флоу

  1. Выделить в Figma фрейм (обычно — мобильный или десктопный экран).
  2. Запустить плагин: Plugins → Development → Design Lib Inspector.
  3. Во вкладке Аудит нажать «Запустить аудит» — детерминированные детекторы прогонят 29 правил, покажут нарушения мгновенно.
  4. (Опционально) Во вкладке AI-аудит нажать «AI-анализ» — Claude Vision посмотрит на макет и найдёт композиционные/смысловые проблемы.

Три вкладки

Вкладка Что делает
Аудит 29 auto-детекторов (детерминированные, быстро, бесплатно)
AI-аудит 97 правил через Claude Vision (медленно, платно, глубже)
Настройки API-ключ, выбор модели, источник каталога правил

Работа с результатами

  • Score 0–100: общая оценка. 100 = идеально, 0 = критично. Цветной бейдж (Критично / Плохо / Средне / Хорошо / Отлично).
  • Severity-фильтры: кнопки 228 ошибок, 99 предупреждений, 18 советов — клик фильтрует список.
  • Фильтр по правилу: селект под score — можно сузить до одного правила.
  • Карточка проблемы:
    • Иконка severity + заголовок + P1–P5 priority badge;
    • Кнопка → справа — Перейти к проблемному слою в Figma;
    • Клик по карточке раскрывает детали: Что / Где / Почему / Как исправить + «Скопировать fix» и ссылка на документацию.
  • Группировка: одинаковые правила на разных слоях схлопываются в одну карточку с бейджем × N. В раскрытом виде — список слоёв, у каждого своя кнопка перехода.
  • Отчёт: кнопка «Отчёт» (иконка загрузки) внизу — копирует Markdown-отчёт в буфер обмена.

Выбор AI-модели

В Настройках → Модель доступны:

Модель Скорость Цена за прогон Когда использовать
Haiku 4.5 ~10 с ≈ $0.03 Быстрая проверка, итерации
Sonnet 4.5 ~20 с ≈ $0.10 Баланс
Opus 4.5 ~30 с ≈ $0.80 Глубоко
Opus 4.7 ~30–60 с ≈ $1.20 Deep-thinking (по умолчанию, рекомендуется)

Extended thinking (Claude сначала «размышляет», потом отвечает) включается автоматически для всех моделей — gracefully отключается если модель не поддерживает.

Автоматическое выделение проблемного слоя

Кнопка → на карточке:

  1. В обычном аудите — точно прыгает на конкретную ноду, найденную детектором.
  2. В AI-аудите — фуззи-матчит nodeHint от Claude (имя слоя, которое модель указала) против всех видимых слоёв и прыгает на лучший матч. Если Claude указал общее «Page_mobile» — попадает на корень.

Кросс-страничные прыжки работают: если нода на другой странице, плагин сам переключает figma.currentPage.

3. Критерии аудита

Каталог правил синхронизирован из https://design-libs.vercel.app/api/figma-rules/v1 — 227 правил в снэпшоте. Из них 126 проверяются в плагине: 29 детерминированных + 97 через AI.

Авто-аудит (29 правил)

Бесплатные, мгновенные проверки. Все результаты имеют точный nodeId.

Контраст и цвет (6) — error/warning severity

  • WCAG-контраст — текст < 4.5:1 к фону (error)
  • Контрастные соотношения WCAG — расширенная проверка (error)
  • Контраст текста — крупный текст < 3:1 (error)
  • Дизайн для дальтоников — цвет как единственный сигнал (error)
  • Правило 60-30-10 · Акцент через дефицит · Консистентность цветовой палитры

Типографика (8)

  • Контраст текста (error)
  • Типографическая шкала · Сочетание шрифтов · Интерлиньяж по размеру шрифта · Минимальный размер шрифта (warning)
  • Длина строки · Оптимальная ширина строки · Трекинг для заглавных (info)

Пространство и тач-зоны (3)

  • Размер тач-зон — < 44×44 iOS / 48×48 Android (error)
  • Размер зоны касания (error)
  • Оптическое выравнивание (warning)

Тёмная тема (4)

  • Контраст в тёмной теме (error)
  • Elevation через светлость · Не использовать чистый чёрный · Границы в тёмной теме (warning)

Компоненты и состояния (5)

  • Иерархия кнопок · Анатомия карточки · Focus-состояния · Disabled-состояние (warning)
  • Глубина и слои (warning)

Формы и когнитивная нагрузка (3)

  • Метка над полем (error)
  • Закон Хикса — > 7 пунктов выбора (warning)
  • Цвет — не единственный сигнал (info)

AI-аудит (97 правил)

Claude Vision смотрит на PNG-скриншот и оценивает:

Иерархия и восприятие (~15) Визуальный вес · Одна точка фокуса · F-паттерн чтения · Иерархия размером · Выравнивание и поток · Иерархия через пространство · Визуальная группировка · Визуальная иерархия · Контраст (восприятие) · Эффект эстетики · Цветовая иерархия · Приоритизация контента · Баланс иконок и текста и др.

Пространство и ритм (~8) 8pt-сетка · Последовательные отступы · Единая шкала отступов · Плотность padding · Ритм секций · Адаптивные отступы · Принцип близости · Воздух вокруг контента · Негативное пространство · Воздух в интерфейсе

Типографика (6) Висячие строки · Контраст жирности · Уровни цвета текста · Табличные цифры · Выравнивание текста · Стратегия обрезки текста

Цвет и тёмная тема (9) Семантический цвет · Правила градиентов · Прозрачность вместо нового цвета · Уровни поверхностей в тёмной теме · Затемнение изображений · Семантические цвета в dark · Десатурация · Изображения в тёмной теме

Формы (~17) Ширина поля · Размер поля · Плейсхолдер-не-label · UX паролей · Select vs Radio · Одноколоночная форма · Опциональные поля · Выбор даты · Позиция кнопки отправки · Подтверждение деструктивных действий · Автоформатирование · Автозаполнение · Клавиатурная навигация · Счётчик символов · Toggle vs Checkbox · Группировка полей · Валидация в реальном времени · Сообщение об ошибке · Прогресс многошаговой формы

Компоненты (~10) Модалки · Таблицы · Toast-уведомления · Хлебные крошки · Паттерны поиска · Выпадающие меню · Вкладки · Аватары · Иконка+подпись · Skeleton-загрузка · Дизайн пустых состояний

Когнитивная и гештальт (~7) Прогрессивное раскрытие · Бритва Оккама · Закон Миллера · Чанкинг · Когнитивная нагрузка · Закон подобия · Закон прегнантности · Принцип общей области

Состояния и восприятие (~8) Пустое состояние · Отображение ошибок · Состояние выбора · Подтверждение успеха · Сопоставление · Скевоморфизм · Сенсорная привлекательность · Эффект тёмного режима · Эффект благородного края · Аффективная эвристика · Превосходство изображений

Внимание и взаимодействие (~5) Баннерная слепота · Визуальные якоря · Сигнификаторы · Обнаруживаемость · Эффект автодополнения · Эффект фон Ресторфа

Что НЕ проверяется автоматически

180 правил в каталоге остаются справочными — их нельзя проверить по статическому скриншоту:

  • Decision biases (якорь, приманка, фрейминг) — про поведение при выборе
  • Behavioral loops (переменное вознаграждение, градиент цели) — нужно видеть путь пользователя
  • Persuasion (социальное доказательство, дефицит) — нужен контекст
  • Temporal/interactive (тайминг анимаций, hover/active, undo) — нужна интерактивность
  • Memory laws (прайминг, интервальное повторение) — нужен временной контекст

Эти правила смотри в каталоге на https://design-libs.vercel.app/ для ручного ревью.

4. Score — как читать

Формула: 100 / (1 + penalty/50), где penalty = errors × 5 + warnings × 2 + infos × 0.5. Плавная кривая — всегда ≥ 1, при отсутствии проблем = 100.

Вердикты по порогам:

Score Вердикт Цвет
86–100 Отлично Зелёный (success)
61–85 Хорошо Нейтральный
41–60 Средне Жёлтый (warning)
21–40 Плохо Красный (destructive)
0–20 Критично Красный (destructive)

Примеры:

  • 0 ошибок + 0 warning + 5 info → penalty 2.5 → score 95 (Отлично)
  • 1 error + 3 warning + 5 info → penalty 13.5 → score 79 (Хорошо)
  • 5 error + 10 warning + 20 info → penalty 55 → score 48 (Средне)
  • 77 error + 38 warning + 24 info → penalty 473 → score 10 (Критично)

5. Особенности поведения

Скрытые слои не аудируются

Слои с visible === false, opacity === 0 или размером 0×0 пропускаются вместе со всем поддеревом. На рендер не влияют → и в аудит не попадают.

Дедупликация

Одна и та же проблема на одной ноде — одна запись в списке. В каталоге бывает, что один детектор привязан к нескольким правилам (например, contrast-wcag → 4 правила). Плагин исполняет каждый детектор ровно один раз и атрибутирует результаты первому совпавшему правилу.

Группировка

Одно правило, сработавшее на N слоях → одна карточка с бейджем × N, раскрывающаяся в список слоёв с индивидуальными кнопками перехода.

Кросс-страничный переход

Кнопка «Перейти» умеет переключать текущую страницу Figma, если нода находится на другой странице.

Повторный аудит при смене выделения

Выбор нового фрейма сбрасывает состояние issues + флаги autoRan/aiRan → снова показывается empty-state «Запустите аудит». Исключение — клик «Перейти» не считается сменой выделения (его делает сам плагин).

6. Диагностика

Проблема Решение
Белый экран плагина Собрать npm run build заново
Anthropic API: invalid x-api-key Проверить ключ в Настройках — сверить с console.anthropic.com
AI-аудит не нашёл ничего Попробовать Sonnet/Opus, выделить более сложный фрейм
«Перейти» прыгает на фрейм, не на слой (AI) Claude не указал конкретный nodeHint — переформулируйте или сложнее фрейм
«не ISO-8859-1 code point» В ключ попал невидимый юникод-символ — очистится автоматически при следующем прогоне, можно пересохранить
Плагин в меню с суффиксом «(Developer VM)» Это метка Figma для dev-плагинов. Уйдёт после публикации в Community / приватно в команду

7. Архитектура (для разработчиков)

manifest.json            Figma plugin manifest
src/
  sandbox/code.ts        Figma sandbox (main): экспорт PNG, jump-to-node, clientStorage
  ui/                    UI React + Tailwind + shadcn
    App.tsx              Главный компонент: табы, state, runAudit/runAi
    theme.ts, icons.tsx, logo.ts, globals.css
    i18n/ru.ts           Все строки UI
  screens/
    IssuesScreen.tsx     Вкладка Аудит/AI-аудит (общая, mode='auto'|'ai')
    SettingsScreen.tsx   Настройки
    summary.ts           computeScore, scoreVerdict, renderMarkdownReport
  detectors/
    contrast.ts, typography.ts, layout.ts, colorTheme.ts,
    forms.ts, targets.ts, cognitive.ts
    index.ts             runAutoAudit с дедупом по detectorId
    types.ts
  shared/
    rules-types.ts       Sync из v0-design-libs
    rules-snapshot.json  Закешированный каталог
    rules-bundle.ts      GENERATED embed в бандл
    ai-rule-overrides.ts Promote manual→ai (77 ruleId)
    recommendation.ts    buildRecommendation, Recommendation type
    serialize.ts         SceneNode → SerializedNode
    messages.ts          Тип-safe протокол UI↔sandbox
  vision/
    claude.ts            Anthropic API client, runVisionAuditBatched, thinking
    tool-schema.ts       report_issues tool для tool-use
  components/ui/         shadcn primitives (Button/Badge/Card/Input/Select/Progress)
  lib/utils.ts           cn() helper

scripts/
  sync-types.mjs         Копирует типы из v0-design-libs
  embed-rules.mjs        Тянет каталог и эмбедит в bundle

esbuild.config.mjs       Сборка sandbox (ES2017) + UI (ES2020) + Tailwind CSS inline

Команды

npm run typecheck    # tsc --noEmit
npm test             # vitest (34 теста)
npm run build        # полная сборка
npm run watch        # hot reload в dev-режиме

Как добавить детектор

  1. В v0-design-libs (upstream-каталог) создать правило с checkType: 'auto' и detector: { id: 'my-detector', params: {...} }.
  2. В плагине создать функцию в src/detectors/<group>.ts типа DetectorFn.
  3. Зарегистрировать в src/detectors/index.ts в DETECTORS map.
  4. Добавить тест в src/detectors/__tests__/detectors.test.ts.

Как добавить правило в AI-аудит

  • Если правило уже есть в каталоге с checkType: 'manual' → добавить его id в PROMOTE_TO_AI в src/shared/ai-rule-overrides.ts.
  • Если нужно новое правило → оформить в upstream-каталоге с checkType: 'ai', обязательно заполнить summary и antiPattern — Claude использует их для поиска нарушений.