Контрибьютинг

AtlantumUI разрабатывается по внутреннему набору правил, описывающих архитектуру токенов, чек-лист готовности компонента, матрицу пропсов, стратегию типизации, доступность и процесс релиза. Эти правила — источник истины для контрибьюторов (в том числе для AI-агентов, участвующих в разработке) и находятся в директории RULES/ репозитория.

Публичная документация не дублирует эти файлы: сюда постепенно переносится и адаптируется только то, что полезно внешнему потребителю компонентов (например, архитектура дизайн-токенов уже отражена в разделе Основы).

Если вы контрибьютите в репозиторий — начните с RULES/atlantum-ui-project-structure.md (структура монорепозитория) и RULES/atlantum-ui-component-checklist.md.md (чек-лист готовности компонента).

Документация компонентов

Страницы в разделе Компоненты генерируются скриптом docs:sync из исходников @atlantum/react. Ручные правки в page.mdx перезаписываются при следующей синхронизации.

Локальный запуск сайта


pnpm --filter @atlantum/docs dev

Сайт доступен на http://localhost:3100 . Перед dev автоматически обновляется только docgen (таблицы пропсов), без перегенерации MDX.

Добавление или обновление компонента

Опишите компонент в JSDoc

Над export const {Name} (или export function {Name}) в {Name}.tsx добавьте краткое описание и при необходимости тег @a11y:


/**
 * Кнопка для первичных и вторичных действий.
 *
 * @a11y Рендерит нативный button — фокус и клавиатура наследуются от браузера.
 */
export const Button = forwardRef(...)

Экспортируйте компонент из `packages/react/src/index.ts`

Скрипт обнаруживает публичные компоненты по строкам export { Name } from "./components/Name".

Запустите синхронизацию


pnpm docs:sync

Команда создаёт или обновляет страницу apps/docs/app/components/{slug}/page.mdx, запись в sidebar, карточку в индексе и re-export в atlantum-react-client.tsx.

Проверьте, что CI пройдёт


pnpm --filter @atlantum/docs docs:check

Если команда завершилась с ошибкой — закоммитьте файлы, которые изменил docs:sync.

Что генерируется автоматически

Артефакт	Назначение
`app/components/{slug}/page.mdx`	Описание, превью, варианты, API
`app/components/_meta.ts`	Порядок пунктов в sidebar
`app/components/page.mdx`	Карточки на странице «Компоненты»
`components/atlantum-react-client.tsx`	Client-компоненты для live-превью в MDX
`.docgen/{Name}.json`	JSON для `PropsTable` (в `.gitignore`)

Превью «Использование» берёт meta.args из {Name}.stories.tsx. Секции вариантов строятся по enum/boolean-пропсам из docgen. Нестандартные случаи (Tooltip, Accordion, Divider, Link) настраиваются в apps/docs/scripts/lib/component-overrides.mjs.

CI и релиз

В каждом PR CI запускает docs:check — убедитесь, что pnpm docs:sync выполнен до push.
После публикации пакетов в npm workflow релиза дополнительно запускает docs:sync и коммитит обновлённые страницы в master.