# @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`.