build-core-ui-components — Разработка компонентов core-ui

Источник: ds-skills/core-ui-development-skills/src/skills/build-core-ui-components/SKILL.md Справочники скилла — вложенные страницы. В вики не выложен, лежит в папке скилла: agents/openai.yaml (подпись скилла для агента OpenAI).

Шапка скилла:

name: build-core-ui-components
description: Создание и изменение React-компонентов библиотеки core-ui, включая публичный TypeScript API, локальные компоненты и утилиты, SCSS-модули, Storybook-документацию и Vitest/RTL-тесты. Использовать при реализации компонента по макету, по контракту дизайна (`components/<slug>.yaml`) или по описанию, расширении существующего компонента и подготовке связанных историй, документации, тестов и экспортов в репозитории core-ui.

Создавать код, согласованный с текущей архитектурой репозитория. Считать актуальный код и конфигурацию источником истины; не переносить абстрактный шаблон механически.

Проверка репозитория

Перед применением убедиться, что текущий workspace является библиотекой core-ui:

1. Прочитать корневой package.json и проверить имя пакета, React, Storybook и команды проверки проекта.
2. Проверить наличие src/, src/index.ts, src/.storybook/, CONTRIBUTING.md и характерных компонентов библиотеки.
3. Не полагаться только на имя директории: оно может отличаться в другой копии репозитория.
4. Если признаки не совпадают или репозиторий определить нельзя, не применять эти конвенции автоматически и сообщить пользователю.

Рабочий процесс

1. Определить источник задачи. Если на компонент есть контракт дизайна — components/<slug>.yaml в базе ds-docs/component-contracts, — читать его вместо разбора макета глазами: состав, свойства, токены и правила там уже сняты и проверены. Контракта нет — работать по макету обычным порядком.
2. Определить публичный API, состояния, варианты, интерактивность и требования доступности.
3. Прочитать границы изменений и зафиксировать допустимые пути.
4. Найти 2–3 ближайших актуальных компонента вне src/deprecated/ и изучить их реализацию, стили, Storybook и тесты.
5. Прочитать структуру и React/TypeScript-конвенции.
6. Загрузить только относящиеся к задаче инструкции:
   • при добавлении utils/ — локальные утилиты;
   • при добавлении components/ — вложенные компоненты;
   • при выносе свойств вложенного компонента в публичный API — проброшенные свойства;
   • при работе со SCSS — стили и токены;
   • при работе со Storybook — истории и документация;
   • при сборке историй по контракту — истории из контракта;
   • при добавлении служебных story-пропсов — исключаемые аргументы Storybook;
   • при работе с тестами — тестирование;
   • при добавлении skeleton или состояния загрузки — пропсы загрузочных состояний.
7. Проверить существующие токены, миксины, хуки, текстовые компоненты и иконки поиском по репозиторию. Не придумывать отсутствующие API и CSS-переменные. Имя токена из контракта — тоже кандидат на проверку, а не готовая переменная.
8. Реализовать минимально необходимый API и переиспользовать подходящие примитивы core-ui.
9. Выполнить проверку результата.

Основные правила

• Использовать kebab-case для директорий и файлов, PascalCase для компонентов и типов, lowerCamelCase для переменных и функций, SNAKE_CASE для констант.
• Писать JSDoc и новую документацию на русском языке.
• Не создавать файлы, варианты, состояния и абстракции, которые не нужны текущей задаче.
• Не изменять сестринские компоненты и общую инфраструктуру без явного согласования.
• Не экспортировать локальные components/ и utils/ через публичный index.ts компонента.
• Покрывать основной компонент тестами. Не создавать отдельные component-тесты внутри components/.
• Покрывать каждую утилиту из utils/ отдельными unit-тестами.
• Не менять версию, CHANGELOG.md, ветку и историю Git без явного запроса или релизной задачи.

Работа с контрактом

• Контракт — источник фактов, а не пожеланий: что в нём записано, то и снято с макета.
• Раздел gaps — дыры и подозрительные места. Их не чинить молча: дыра означает вопрос к дизайну, а не свободу выбрать значение.
• Чего в контракте нет — того не додумывать. Формат не описывает тени, размытия и параметры анимации; их отсутствие означает «не снято», а не «нет в макете».
• Контракт лежит в чужом репозитории и правится дизайн-стороной. Замечания возвращать текстом, файл не трогать.
• Подробности — контракт компонента как источник задачи.

Работа с макетом

• Отделять подтверждённые требования от предположений.
• Сопоставлять элементы макета с существующими токенами и компонентами библиотеки.
• Сверять публичный API со списком проброшенных вложенных компонентов: не проброшенное наружу не выносить.
• При недоступной или неоднозначной части макета явно описывать допущение.
• Если дизайн требует отсутствующего общего API, применять процедуру BLOCKER / LIMITATION / IMPROVEMENT из правил границ.