@mrktg-common/internal-ui

Общий интерфейс внутренних инструментов маркетинга: Landings Admin и LP Constructor. Здесь живут и пакет, и дизайн-система Internal ui: токены, классы компонентов, карточки с правилами и превью. Артефакт системы в claude.ai собирается из этого репозитория, версия у пакета и системы одна.

Посмотреть систему: страница в S3 (обновляется с каждым пушем в master), артефакт в claude.ai.

Что внутри

• tokens.css — переменные обеих тем, генерируется из tokens/tokens.json.
• components.css — styles/components.css: глобальные классы компонентов (в системе это bundle.css).
• React-компоненты — тонкие обёртки над этими классами: разметка как в карточках системы, поведение по их README (таймеры тостов, фокус в модалке, клавиатура в списках, выключенное с причиной).

design/canvas.css (вспомогательные классы холстов дизайна, .is-still) в пакет не входит.

Дизайн-система

• design/README.md — бренд-бук, design/sections/*.md — разделы (контраст, паттерны, переход продуктов);
• design/components/<Comp>/ — карточка компонента: README.md с правилами и preview.html с превью в обеих темах;
• design/cover.html — обложка, design/canvas.css — классы для холстов;
• design/assets/ — фавиконка библиотеки для страницы системы; в пакет npm не входит;
• CHANGELOG.md — общий changelog пакета и системы.

npm run design собирает артефакт в design-dist/project/ (в гит не попадает): токены с версией из package.json и ссылкой на коммит, tokens.css тем же генератором, что и пакет, классы, карточки, разделы и CHANGELOG.md разделом. Тест проверяет, что пакет и артефакт получают одинаковые tokens.css и классы.

Там же собирается design-dist/site/: статическая страница системы для тех, у кого нет доступа к артефакту. CI выкладывает её во внутренний S3-бакет int-components: internal-ui/master/ с master, internal-ui/vX.Y.Z/ с тегов, internal-ui/<ветка>/ для MR. Переменные CI те же, что у int-components.

Подключение

npm i @mrktg-common/internal-ui

Пакет ставится из публичного npm собранным (dist/). Peer-зависимости: react и react-dom 19, lucide-react 1.

Стили импортируются один раз в корне приложения, до стилей продукта:

import '@mrktg-common/internal-ui/tokens.css';
import '@mrktg-common/internal-ui/components.css';

Базовые правила системы (box-sizing, цвет ссылок, шрифт) заданы внутри .app, поэтому корневой элемент приложения получает класс app. Шрифт Inter 400–700 подключается продуктом (Google Fonts).

Тема — атрибут data-theme на <html>. ThemeProvider в корне ставит его, помнит выбор (по умолчанию в localStorage, можно передать своё хранилище) и в режиме System следит за системной темой. Чтобы не мигало при загрузке, в <head> вставляется themeScript().

import { ThemeProvider, ToastProvider, Header, HeaderNav, UserMenu } from '@mrktg-common/internal-ui';
import { Blocks } from 'lucide-react';

<ThemeProvider>
  <ToastProvider>
    <div className="app">
      <Header productName="LP Constructor" productIcon={Blocks} homeHref="/" link={RouterLink} end={<UserMenu email={user.email} />}>
        <HeaderNav link={RouterLink} items={[{ href: '/', label: 'Projects', current: true }]} />
      </Header>
    </div>
  </ToastProvider>
</ThemeProvider>

link — компонент ссылки роутера продукта (react-router, next/link), по умолчанию обычный <a>.

Компоненты

Header, HeaderNav, Breadcrumbs, UserMenu, Button, Field, TextField, Input, Textarea, Checkbox, Search, Switch, Segmented, Popover, Menu, SelectMenu, MultiSelectMenu, Badge, StatusBadge, EnvPill, EnvChip, BrandName, Alert, Banner, ToastProvider и useToast, Tooltip, Skeleton, EmptyState, Spinner, Loading, CenteredCard, Card, Facts, Tabs, CopyField, Modal, ChangeBlock, Table, TableCell; для файлов и долгих операций — Dropzone, FileRow, Progress, ProgressLabel, Countdown, ResultReport, ReportRow, Steps, Step.

Правила, которые компоненты держат сами:

• выключенное с причиной — aria-disabled плюс причина (подсказка, menu-hint, aria-describedby): фокус остаётся, нажатие не проходит; нативный disabled — только где причина очевидна;
• оверлеи и стопка тостов рендерятся в портал в body с классом .is-fixed;
• тосты: 6 с с паузой при наведении и фокусе, с Undo 10 с, ошибки висят до закрытия, не больше трёх;
• зелёный только для «живёт на продакшене»: StatusBadge status="live" production={false} нейтральный, пройденная проверка в отчёте и готовый шаг — тоже нейтральные;
• Dropzone проверяет тип и размер файла до отправки, ошибка — строкой под зоной.

Продуктовые экраны держат свои CSS-модули и не переопределяют классы системы. То, чего в системе нет (например, экран результата в окне публикации конструктора), остаётся в продукте, пока не появится здесь.

Разработка

npm run lint
npm run typecheck
npm test
npm run build   # dist/: index.js, *.d.ts, tokens.css, components.css

Изменения

Одно изменение — один MR: CSS в styles/components.css (или токен в tokens/tokens.json), компонент в src/ с тестом, карточка в design/components/ и запись в CHANGELOG.md. Версия — в package.json, meta.release в tokens.json и верхнем разделе CHANGELOG.md одновременно (тест сверяет): patch — правка без изменения разметки, minor — добавление, major — изменение класса, токена или разметки.

Примеры в карточках, тестах и токенах — только вымышленные: example.com, бренды Aurora / Borealis / Cirrus, люди [email protected]. Тест test/no-brands.test.ts падает на брендах компании, её доменах и именах.

Публикация

Тег vX.Y.Z на коммит с этой версией, затем npm publish (prepublishOnly прогоняет lint, typecheck, тесты и сборку) и публикация design-dist/project/ в артефакт системы в claude.ai — это делает сессия Claude (npm run design, затем публикация файлов в артефакт с сохранением createdOnFiles из его текущего индекса).