@tansu/design-system

Общая дизайн-система для всех SPFx-проектов Tansu (V5 Executive Premium). Один источник правды для цветов, шрифтов, теней и паттернов. Меняешь здесь — обновляется во всех проектах.

---

Что внутри

Файл	Что	Когда подключать
styles/_tokens.scss	$переменные + @mixin (компайл-тайм, без CSS-вывода)	в каждом .module.scss
styles/global.scss	рантайм CSS-переменные :root{--navy-900…}	один раз на веб-часть (по необходимости)
prompt-template.md	промпт для генерации/переверстки веб-части по дизайну	при работе с Claude

---

Установка в проекте

В package.json проекта добавь зависимость (пин по тегу — стабильность):

"dependencies": {
  "@tansu/design-system": "git+https://git.tnsu.kz/timur.gorodetskiy/design-system.git#v1.0.0"
}

Затем:

npm install

Авторизация. Репозиторий приватный. Чтобы npm install смог его скачать, на машине должен быть доступ к Gitea — проще всего настроить SSH-ключ (Gitea → Settings → SSH Keys) и использовать ssh-URL: git+ssh://git@git.tnsu.kz/timur.gorodetskiy/design-system.git#v1.0.0.

---

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

В любом .module.scss:

@import '~@tansu/design-system/styles/tokens';

.card {
  background: $navy-900;
  border-radius: $r-md;
  box-shadow: $sh-1;
  @include card-hover-gold;
}

.publishButton {
  @include btn-accent;
  border-radius: $r-sm;
}

~ — это ссылка на node_modules (так работает sass-загрузчик SPFx).

Правила (важно для поддерживаемости)

1. Только переменные и миксины. Сырой hex (#D4A01E, #0F2440) в компонентах — запрещён.
2. Заголовки — $font-serif (Lora), остальной текст — $font-sans (Inter).
3. Отступы — из шкалы $sp-1…$sp-8, не произвольные числа.
4. Повторяющийся паттерн (шапка, карточка, кнопка) — бери миксин, не копируй правила.

---

Рантайм-переменные (опционально)

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

// PortalMainPage.module.scss (корневой)
@import '~@tansu/design-system/styles/global';

<span style={{ color: 'var(--gold-500)' }}>...</span>

Для обычной вёрстки это не нужно — хватает _tokens.scss.

---

Шрифты

Подключи Inter + Lora один раз в onInit() веб-части:

import { SPComponentLoader } from '@microsoft/sp-loader';

protected onInit(): Promise<void> {
  SPComponentLoader.loadCss(
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Lora:wght@500;600;700&display=swap'
  );
  return super.onInit();
}

Для корпоративной сети лучше самохостить шрифты (офлайн, скорость, без внешней зависимости). Это план на будущее.

---

Как менять дизайн (workflow)

1. Правишь styles/_tokens.scss (например, $gold-500).
2. Коммит + новый тег:

   git commit -am "feat: deeper gold accent"
   git tag v1.1.0 && git push --tags
   

3. В проектах поднимаешь тег в package.json (#v1.1.0) → npm install.
4. Пересобираешь и деплоишь проект (в SPFx стили впекаются в бандл — это неизбежно).

SemVer: правка цвета/значения — minor (v1.1.0); удаление/переименование переменной (ломает проекты) — major (v2.0.0).

---

Дальше: слои дизайн-системы

• Слой 1 — токены (этот пакет) ✅
• Слой 2 — миксины (этот пакет) ✅
• Слой 3 — React-компоненты (<Button>, <Badge>, <PageHeader>) — следующий шаг. Потребует сборки пакета (TS→JS) и перехода на npm-реестр Gitea (см. ниже).

Переход на npm-реестр Gitea (когда появится слой 3)

publishConfig в package.json уже указывает на реестр Gitea. Тогда:

# .npmrc в проекте
@tansu:registry=https://git.tnsu.kz/api/packages/timur.gorodetskiy/npm/

"@tansu/design-system": "^1.0.0"

Публикация: npm publish. Обновление в проектах: npm update @tansu/design-system.