commit 7623425d9785bb09e68f2a80d86535b75d75b933 Author: Тимур Городецкий Date: Thu Jul 2 10:18:16 2026 +0500 feat: initial design system v1.0.0 (tokens, mixins, guide) Co-Authored-By: Claude Opus 4.8 (1M context) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fc5c6be --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +node_modules/ +*.log +.DS_Store +Thumbs.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..e85fd5a --- /dev/null +++ b/README.md @@ -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 +... +``` + +Для обычной вёрстки это не нужно — хватает `_tokens.scss`. + +--- + +## Шрифты + +Подключи Inter + Lora один раз в `onInit()` веб-части: + +```ts +import { SPComponentLoader } from '@microsoft/sp-loader'; + +protected onInit(): Promise { + 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-компоненты** (`