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
commit 7623425d97
6 changed files with 467 additions and 0 deletions
@@ -0,0 +1,147 @@
+# @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` проекта добавь зависимость (пин по тегу — стабильность):
+
+```json
+"dependencies": {
+  "@tansu/design-system": "git+https://git.tnsu.kz/timur.gorodetskiy/design-system.git#v1.0.0"
+}
+```
+
+Затем:
+
+```bash
+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`:
+
+```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` **один раз** — в корневом компоненте веб-части:
+
+```scss
+// PortalMainPage.module.scss (корневой)
+@import '~@tansu/design-system/styles/global';
+```
+
+```tsx
+<span style={{ color: 'var(--gold-500)' }}>...</span>
+```
+
+Для обычной вёрстки это не нужно — хватает `_tokens.scss`.
+
+---
+
+## Шрифты
+
+Подключи Inter + Lora один раз в `onInit()` веб-части:
+
+```ts
+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. Коммит + новый тег:
+   ```bash
+   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/
+```
+
+```json
+"@tansu/design-system": "^1.0.0"
+```
+
+Публикация: `npm publish`. Обновление в проектах: `npm update @tansu/design-system`.