Тимур Городецкий
148 lines
5.3 KiB
Markdown
148 lines
5.3 KiB
Markdown
# @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`.
|