Files

T

Тимур Городецкий 7623425d97 feat: initial design system v1.0.0 (tokens, mixins, guide)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-02 10:18:16 +05:00

5.3 KiB

Raw Permalink Blame History

@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).

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

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

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

Нужны, только если читаешь цвет в рантайме (инлайн-стиль, динамическая тема). Подключи 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)

Правишь styles/_tokens.scss (например, $gold-500).

Коммит + новый тег:

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

В проектах поднимаешь тег в package.json (#v1.1.0) → npm install.
Пересобираешь и деплоишь проект (в 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.

5.3 KiB Raw Permalink Blame History Unescape Escape