# Bu UI kit ilə işləmək

İndicə **publish edilə bilən React komponent kitabxanası** scaffold etdin — bu, bir tətbiq deyil. Sən onu öz brendinə uyğunlaşdırırsan, publish edirsən, komanda yoldaşların isə `npm install` edib komponentləri bir-bir import edirlər.

Bu sənəd xəritədir. [`../README.md`](../README.md) isə ərazinin özüdür: burada bir bölmə linklə bitirsə, təfərrüat oradadır.

> `kit-guide` skill-i tərəfindən yazılıb. Kitdə dəyişiklik etdikdən sonra `/kit-guide` işə sal ki, sənəd kodla yenidən üst-üstə düşsün — köhnəlməyə qoyma.

---

## 1. İlk on dəqiqə

```bash
git init          # yalnız təzə scaffold-da — git hook-larının quraşdırılacağı repo lazımdır
pnpm install
pnpm dev          # → http://localhost:5175
```

`pnpm dev` **showcase**-i açır — kitdəki bütün komponentlər bir saytda, CBAR-ın Figma faylındakı düzülüşlə. Overview səhifəsindən başla, sonra istənilən komponenti aç: hər prop üçün bir kontrolu olan canlı playground, variant matrisləri, props cədvəli və Figma paneli səni orada gözləyir.

npm da eyni cür işləyir: `npm install`, `npm run dev`. Bu sənəddəki hər əmrin `npm run <script>` qarşılığı var, publish isə daxildə `npm`-ə müraciət edir — yəni release üçün pnpm quraşdırmaq məcburiyyəti yoxdur.

Davam etməzdən əvvəl dörd şey:

- **`dependencies` boşdur, və məhsul elə budur.** Bu kiti quraşdırmaq komanda yoldaşlarının lock faylına **heç nə** əlavə etmir. Radix `dist`-in içinə kompilyasiya olunur; `tailwind-merge`-in mənbəyi isə `src/lib/tw-merge/` altına vendor edilib. Hər ikisinin lisenziyası `NOTICE` faylında gedir.
- **39 komponent**, hər birinin öz import subpath-i var (`@your-team/ui/button`).
- **Showcase dev alətidir.** `package.json#files` yalnız `dist`-i publish edir — nə showcase, nə də `tools/` sənin release etdiyin paketə düşür. Showcase-in bu qədər zəngin olmasına icazə verən də elə budur.
- **Install skriptləri əvvəlcədən təsdiqlənib.** `esbuild` və `@parcel/watcher` `package.json`-da allowlist-dədir — iki dəfə, hər package manager üçün ayrı. Əgər install skripti olan yeni bir dependency əlavə etsən, onu **hər iki** siyahıya yaz; əks halda install 0 kodu ilə bitir, build isə sonra görünən səbəbsiz sınır.
- **Install həm də üç git hook-u yerinə qoyur** — amma yalnız qovluq artıq git repo-dursa. Təzə scaffold-da deyil, ona görə install `.git can't be found` yazır və heç nə etmir; əvvəlcə `git init` et, ya da sonra `npx husky` işlət. Hook-lar §3-dədir.

---

## 2. Kiti öz brendinə çevir

Komponent kodu yazmazdan əvvəl üç dəyişiklik.

**`package.json` → `name`.** Hazırda `@cbar/uikit` yazılıb və `publishConfig.registry`-də göstərilən Nexus repo-suna publish olunur. Bu kit CBAR-ın deyilsə, hər ikisini dəyiş — scoped ad istifadə et (`@your-team/ui`): scoped olmayan ad public registry-də istənilən şeylə toqquşa bilər. `pnpm release` scaffold defoltu (`uikit-plate`, `cbar-uikit-plate`) qaldıqca publish etməkdən imtina edir.

**`LICENSE` → `__COPYRIGHT_HOLDER__`.** Öz adınla və ya təşkilatının adı ilə əvəz et. İl artıq yazılıb. npm kök `LICENSE` faylını `files` onu saymasa belə hər tarball-a qoyur — yəni consumer-lərin əslində aldığı lisenziya budur; `pnpm release` placeholder qaldıqca dayanır.

**`src/styles/tokens.css` → brend.** Kitdəki hər rəng, radius, boşluq və şrift buradan gəlir. `--ui-color-brand-500`-i dəyiş, bütün kitabxana yenidən brendlənsin — çünki heç bir komponent dəyəri sabit yazmır.

Rebrend səthinin bu qədər kiçik olmasının səbəbi üç qatlı quruluşdur:

```
src/styles/tokens.css     primitivlər (--ui-*)                maşın sahibliyində
      ↓
src/styles/theme.css      semantik rollar + .dark + @theme    əl sahibliyində
      ↓
src/styles/globals.css    giriş: tailwind + tokens + base
```

**Komponentlər yalnız semantik qatı işlədə bilər** — `bg-background`, `text-primary-foreground`, `rounded-md`. Birbaşa `--ui-*` primitivinə müraciət lint xətasıdır, və Figma-dan yenidən sinxronlaşmanın hər şeyi bir anda dəyişməsini (heç nəyi yox) təmin edən elə bu dolayılıqdır.

CBAR bir kontrolu iki müstəqil ox kimi modelləşdirir — treatment və çalar — ona görə əksər komponentlər hər ikisini qəbul edir:

```tsx
<Button variant="outline" colorPalette="tertiary">Ətraflı</Button>
```

Ətraflı: [README §1](../README.md#1-make-it-yours), [§3 Design tokens](../README.md#3-design-tokens).

---

## 3. Bütün skriptlər və hansına nə vaxt əl atmalısan

### Gündəlik

| Əmr | Nə edir | Nə vaxt |
| --- | --- | --- |
| `pnpm dev` | showcase qalereyası :5175-də (`showcase`-in aliası) | işlədiyin müddətdə həmişə açıq |
| `pnpm showcase` | eyni şey, açıq adla | `dev` skriptdə qeyri-müəyyən görünəndə |
| `pnpm showcase:host` | dev server bütün interfeyslərə bağlı | komanda yoldaşına link göndərəndə və ya başqa brauzer profilində açanda |
| `pnpm storybook` | Storybook :6006-da — bir dəfəyə bir story | komponenti təcrid halında yazarkən (yalnız Storybook saxlanılıbsa) |

### Commit-dən əvvəl

| Əmr | Nə edir | Nə vaxt |
| --- | --- | --- |
| `pnpm lint` | ESLint — **və** token/dependency qaydaları | hər dəfə; kitin qaydaları burada tətbiq olunur |
| `pnpm typecheck` | kit üzərində `tsc`, **plus** `showcase/` üçün ikinci keçid | tiplərə və ya showcase-ə toxunandan sonra |
| `pnpm test` | Vitest watch rejimində, jest-axe testləri daxil | komponent davranışını dəyişərkən |
| `pnpm test:run` | eyni şey, bir dəfə, interaktivsiz | CI-da və ya release-dən əvvəl |
| `pnpm check:staged` | `pre-commit` hook-unun işlətdiyini əl ilə | commit-in keçəcəyini commit etməzdən əvvəl bilmək üçün |
| `pnpm check` | `pre-push` hook-unun işlətdiyini əl ilə | sonradan amend etmək istəmədiyin push-dan əvvəl |

`pnpm lint` adətən dörd şeydən birinə görə sınır: `src/` içində `--ui-*` primitivi, sabit rəng dəyəri, kitin əvəz etdiyi paketin import-u, və ya `radix-ui` barrel import-u. Dördü də §8-dədir.

### Git hook-ları

Yuxarıdakı iki cədvəli yadda saxlamaq məcburiyyətin yoxdur, çünki `.husky/` içindəki üç hook onları sənin əvəzinə işlədir. `prepare` skripti onları `pnpm install` zamanı quraşdırır — təzə scaffold-da niyə əvvəlcə `git init` lazım olduğu §1-dədir.

| Hook | Nəyi yoxlayır | Qiyməti |
| --- | --- | --- |
| `pre-commit` | branch adını, sonra **yalnız staged** fayllar üzərində ESLint | ~2–5s |
| `commit-msg` | subyekt sətri `<prefix>[(scope)][!]: <mətn>` formasındadır | ani |
| `pre-push` | tam `lint`, `typecheck` və `test:run` | ~70s |

Bu bölgü qiymət qaydasıdır və onu bilmək lazımdır, çünki sonradan əlavə edəcəyin yoxlamanın yerini elə o həll edir: staged-ə bağlı və ~5s-dən azdırsa `pre-commit`-ə, bütün repo-nu gəzirsə və ya ~10s-dən çoxdursa `pre-push`-a, ~60s-dən çoxdursa isə **heç birinə** getmir. `build`, `verify`, `size` və `audit:shipped` heç bir hook-da olmamasının səbəbi də budur — onlara əvvəlcə `dist/` lazımdır, dəqiqələr çəkən hook isə bir neçə günə bypass edilməyə başlayır və heç nəyi qorumur. Səlahiyyət CI-dadır; hook-lar onun sadəcə daha tez əks-sədasıdır.

Branch adı ilə commit subyekti **eyni** prefiksləri götürür, yəni branch `feat/progress-circle`, onun commit-ləri isə `feat: …` olur:

```
chore feat hotfix bugfix reconcile fix docs refactor test perf ci
```

`main`, `master` və detached `HEAD` (rebase, bisect ortası) branch yoxlamasından azaddır. Git-in özünün yaratdığı subyektlər — `Merge …`, `Revert …`, `fixup!`, `squash!` — mesaj yoxlamasından azaddır, əks halda merge heç kimin yazmadığı bir mesaja görə sınardı.

Keçmək üçün: `HUSKY=0 git commit` və ya `git commit --no-verify` (push üçün də eyni). Nə `lint-staged`, nə də `commitlint` var — hook-lar `.husky/` içində dörd shell skriptidir, oxunmaq və redaktə olunmaq üçün yazılıb. `lib.sh` qalan üçünün source etdiyi ortaq addım və vaxt maşınlığını saxlayır; izlənən (tracked) qalmalıdır, yoxsa hamısı tamamilə sınır.

### Publish-dən əvvəl

| Əmr | Nə edir | Nə vaxt |
| --- | --- | --- |
| `pnpm build` | `exports:gen` → tsup (ESM + CJS + `.d.ts`) → `add-use-client` → Tailwind CLI → `dist/` | verify-dan əvvəl və `prepublishOnly` daxilində |
| `pnpm verify` | export map güncəl, props cədvəlləri güncəl, bütün hədəflər mövcud, `publint` + `attw` təmiz | göndərmək niyyətində olduğun hər build-dən sonra |
| `pnpm size` | hər subpath üçün bayt büdcəsi | komponent əlavə edəndən və ya import-a toxunandan sonra |
| `pnpm audit:shipped` | hansı təhlükəsizlik xəbərdarlıqları **consumer-ə** çatır | hər publish-dən əvvəl və müntəzəm olaraq |
| `pnpm changeset` | changelog yazısı, bump səviyyəsi | dəyişikliklə birlikdə, sonra yox |
| `pnpm release` | idarə olunan publish | ən sonda |

**`audit:shipped` burada adi paketdəkindən daha vacibdir.** `dependencies` boş olduğu üçün consumer-in `npm audit`-i, Dependabot və Snyk — hamısı təmiz göstərir, hətta `dist` içinə kompilyasiya olunmuş Radix-də məlum boşluq olsa belə: onlar quraşdırmadıqları kodu görə bilmirlər. Bu repo həmin problemin hələ də görünən yeganə yeridir.

### Ara-sıra

| Əmr | Nə edir | Nə vaxt |
| --- | --- | --- |
| `pnpm exports:gen` | `package.json#exports`-u `src/components/*/index.ts`-dən yenidən qurur | komponent əlavə/adını dəyişəndən sonra |
| `pnpm props:gen` | showcase-in props cədvəllərini yenidən qurur | komponentin prop-larını dəyişəndən sonra |
| `pnpm figma:spec` | parity səhifəsinin oxuduğu Figma capture-ını yenidən yazır | dizayn faylı dəyişəndə |
| `pnpm showcase:build` | showcase-i `showcase/dist`-ə build edir | doc saytını deploy edərkən (§5) |
| `pnpm showcase:preview` | həmin build-i :5176-da host kimi verir | deploy-dan əvvəl |
| `pnpm build:js` / `build:css` | `build`-in yarıları | build-in özünü debug edərkən |
| `pnpm lint:fix` | ESLint `--fix` ilə | mexaniki təmizləmələr |
| `pnpm kit:local -- --to ../app` | kiti publish etmədən başqa proyektə qurur | komponenti real tətbiqdə sınayarkən (§6b) |

Ətraflı: [README §6 Build](../README.md#6-build).

---

## 4. Komponent əlavə etmək

```bash
/ui-kit-component <ad>     # Claude Code — qovluq, story, test, index.ts, exports
```

Əl ilə dörd addımdır:

```bash
npx shadcn@latest add dialog                       # düz src/components/dialog.tsx yazır
mkdir src/components/dialog
mv src/components/dialog.tsx src/components/dialog/
# index.ts əlavə et ('use client' ilə başlasın), bir .stories.tsx və bir .test.tsx
pnpm exports:gen                                   # package.json#exports-u yenidən qur
```

**Qovluq sərhədi funksionaldır.** `scripts/gen-exports.mjs` `src/components/*/index.ts` fayllarını tarayır və `exports` xəritəsini tapdığından qurur — hər komponentə öz import yolunu verən budur. `shadcn add` düz fayl yazır; onu qovluğa köçürüb generatoru işə salmaq isə bütün fərqdir.

Yeni komponentin daha iki şeyə ehtiyacı var:

- **`'use client'`** — state, effect və ya handler işlədən hər faylın başında, `index.ts` daxil olmaqla. Onsuz komponent Next.js Server Components daxilində sınır.
- **Showcase qeydiyyatı**: `showcase/src/registry/<ad>.tsx` oxları, defoltları, bir `render` və matrisləri elan edir. Komponenti sayta çıxaran həmin tək fayldır.

Ətraflı: [README §5](../README.md#5-adding-a-component).

---

## 5. Showcase-i publish etmək

Showcase statik saytdır. `pnpm showcase:build` `showcase/dist` yazır və onu istənilən yerdən vermək olar — GitHub Pages, Vercel, Netlify, S3, şəbəkə qovluğu.

**Server konfiqurasiyası yoxdur.** Tətbiq URL hash-i üzərindən route edir, ona görə server üçün bütün yollar `index.html`-dir: nə rewrite qaydası, nə `404.html`, nə də `try_files`.

Alt-yol (sub-path) deploy-unun tələb etdiyi yeganə şey `SHOWCASE_BASE`-dir — build-ə asset-lərin harada olacağını deyir:

```bash
# domenin kökündən verilir
pnpm showcase:build

# alt-yoldan verilir, məsələn <sən>.github.io/<repo>/
SHOWCASE_BASE=/my-kit/ pnpm showcase:build
SHOWCASE_BASE=/my-kit/ pnpm showcase:preview      # → http://localhost:5176/my-kit/
```

**`SHOWCASE_BASE`-i preview-ə də ver.** `base` dev serverdə heç nə etmir, yəni alt-yol build-ini yoxlamağın yeganə yolu preview-dur — dəyişən verilməsə isə preview həmin build-i kökdən verir və bütün asset-lər build-ə heç bir aidiyyəti olmayan səbəbdən 404 alır.

Preview-da iki şeyi təsdiqlə: konsolda 404 yoxdur, və Figma paneli canlı bağlantı olmadığını bildirir (canlı sorğular yalnız dev-də işləyir, ona görə host edilmiş showcase heç vaxt ziyarətçinin maşınını yoxlamır).

Nümunə GitHub Pages workflow-u `.github/workflows/showcase-pages.yml`-dədir. Defolt olaraq yalnız `workflow_dispatch`-dir — Pages-i aktivləşdir (Settings → Pages → Source: **GitHub Actions**), Actions tabından bir dəfə işə sal, sonra `push:` triggerini açıqla. Başlıq şərhində Vercel / Netlify / S3 qarşılıqları var. Başqa yerdə host edirsənsə, faylı sil.

Ətraflı: [README §4c](../README.md#4c-publishing-the-showcase).

---

## 6. Kiti publish etmək

```bash
pnpm changeset          # dəyişikliyi təsvir et, major / minor / patch seç
pnpm changeset version  # bump-ı tətbiq edir, CHANGELOG.md yazır
npm pack --dry-run      # fayl siyahısını başqasından əvvəl sən oxu
pnpm release            # idarə olunan publish
```

**Publish edilmiş versiya bir daha istifadə oluna bilməz** — nə npm-də, nə də əksər private registry-lərdə; `npm unpublish` nömrəni azad etmir. Aşağıdakıların hamısı heç nə maşından çıxmamış baş verir.

`pnpm release` paket adını, `LICENSE` placeholder-ini, working tree-nin təmizliyini və həmin versiyanın hədəf registry-də mövcud olub-olmadığını yoxlayır; sonra build edir, verify edir, tarball məzmununu çap edir və publish etməzdən əvvəl səndən versiya nömrəsini yazmağı istəyir. `--dry-run` bütün yoxlamaları keçirir və publish-dən bir addım əvvəl dayanır.

Bump səviyyəsini consumer-in nə hiss edəcəyinə görə seç:

| Bump | Nə vaxt |
| --- | --- |
| **patch** | səhv düzəlişi, stil korreksiyası, API dəyişmir |
| **minor** | yeni komponent, yeni prop, yeni token — yalnız əlavə |
| **major** | silinmiş/adı dəyişmiş export, dəyişmiş prop semantikası, dayandırılmış React versiyası — **və `dist` içinə kompilyasiya olunan kodda breaking change**, çünki Radix dependency olmasa da consumer-ə çatır |

Gözdən qaçan iki major: komponent qovluğunun adını dəyişmək onun import subpath-ini dəyişir, və `--ui-*` tokeni silmək ona istinad edən hər kəsi sındırır.

Private registry (Nexus, GitHub Packages) üçün `.npmrc`-də uyğun bloku açıqla. **Token-i heç vaxt fayla yazma** — `${NPM_TOKEN}` formasını işlət ki, gizli dəyər mühitdən gəlsin.

Consumer-lərin onunla nə etdiyi:

```tsx
import '@your-team/ui/styles.css';        // onların tətbiqində Tailwind lazım deyil
import { Button } from '@your-team/ui/button';
```

Ətraflı: [README §7](../README.md#7-publishing), [§8 Consuming the published kit](../README.md#8-consuming-the-published-kit), və bütün ardıcıllığı səninlə addım-addım keçən `/release-kit` skill-i.

---

## 6b. Publish etməzdən əvvəl istifadə etmək

Publish olunmuş versiya bir daha təkrar istifadə oluna bilmir, ona görə komponentin səhv olduğunu öyrənmək üçün ən pis an məhz `pnpm release`-dən sonrakı andır. `kit:local` bunu öyrənməyin həmin yolunu aradan qaldırır:

```bash
pnpm kit:local -- --to ../my-app     # və ya: npm run kit:local -- --to ../my-app
```

Kiti build edir və **`npm publish`-in göndərəcəyi eyni fayl dəstini** `../my-app/node_modules/` içinə kopyalayır, sonra həmin tətbiqdə nə dəyişməli olduğunu çap edir. İşləyərkən sinxron qalmaq üçün `--watch` əlavə et. Sırf Node-dur — `node scripts/link-local.mjs --to ../my-app` heç bir paket meneceri olmadan işləyir.

Bilməyə dəyən üç şey:

- **Link yox, kopyalayır.** `npm link` symlink qurur və Node `react`-i tətbiqinkindən əvvəl kitin içində tapır — iki React nüsxəsi və ilk hook-dan gələn `Invalid hook call`. Kopyalanmış qovluğun yanında `node_modules` olmur, ona görə həmişə tək React olur.
- **Kopya heç bir lock faylında deyil**, yəni target-də `install` onu silə bilər. Skripti yenidən işlət, ya da `--mode pack` istifadə et — o, əsl tarball qurur və dependency kimi qeyd olunur.
- **TypeScript üçün tətbiqdə `radix-ui` dev dependency lazımdır.** Göndərilən `.d.ts` faylları prop tipləri üçün onu hələ də adlandırır, halbuki JavaScript onu içinə kompilyasiya edib; onsuz on səkkiz komponent heç bir prop qəbul etmirmiş kimi type-check olunur.

Ətraflı: **[`kit-local.az.md`](./kit-local-development/kit-local.az.md)** — tam bələdçi: bütün bayraqlar, Vite və Next üçün tətbiqdə nə dəyişməli olduğu, copy/pack seçimi və problem həlli cədvəli. Qısası: [README §8b](../README.md#8b-using-the-kit-without-publishing-it).

---

## 6c. Kiti tətbiq komandasına təhvil vermək

Paketi quraşdırmaq təhvilin yarısıdır. Digər yarısı budur ki, qarşı tərəfdəki
komandanın qarşısında indi 39 komponent, iki müstəqil stil oxu və yalnız tiplər
üçün lazım olan bir dev dependency dayanır — və onların Claude Code-u bunların
heç birini bilmir.

`consumer-skills/` məhz həmin yarıdır. Bu repo üçün deyil, **tətbiq** üçün
yazılmış üç skill:

| Skill | Nə vaxt işə düşür | Nə edir |
| --- | --- | --- |
| `ui-kit-setup` | təzə quraşdırılıb, ya da nəsə stilsiz görünür | stylesheet marşrutu, dark mode, `radix-ui` dev dependency, kök provayderləri, bundler bayraqları |
| `ui-kit-usage` | həmin tətbiqdə hər hansı UI yazılanda | hansı komponenti götürmək, subpath import, `variant` × `colorPalette`, təhlükəsiz override, ikonlar |
| `ui-kit-review` | UI-ı nəzərdən keçirmək istənəndə | onların kodunu kitə qarşı yoxlayır, əvvəl hesabat, sonra düzəliş |

Hər üç qovluğu onların layihəsinə kopyala:

```bash
cp -r consumer-skills/ui-kit-* ../their-app/.claude/skills/
```

Onlar npm ilə deyil, kopya ilə gedir — `files` qəsdən `dist`-only-dir. Üçünü
birlikdə kopyala: `ui-kit-setup` və `ui-kit-review` hər ikisi
`ui-kit-usage/references/` faylarını oxuyur.

Həmin reference-lər generasiya olunur, ona görə kitdən fərqlənə bilmir:

```bash
pnpm consumer:gen          # yenidən yaz
pnpm consumer:gen --check   # `pnpm verify`-in bir hissəsidir
```

Komponent əlavə etdikdən, rebrand-dan və token qatına hər hansı dəyişiklikdən
sonra işlət. `/consumer-skills` skill-i bütün işi görür — yenidən generasiya
edir, sonra əl ilə yazılmış mətni uzlaşdırır. Təfərrüat:
`consumer-skills/README.md`.

---

## 7. Figma bridge

Showcase-in "canlı" dediyi hər şey — yan-yana render, hesablanmış stil müqayisəsi, `/figma-sync`, `pnpm figma:spec` — `tools/figma-bridge/` içindəki kiçik loopback servisi üzərində işləyir. O, Figma-nı REST API ilə deyil, **plugin** vasitəsilə oxuyur: token yox, rate limit yox, pulsuz planda işləyir. Öz dependency-si yoxdur, yəni quraşdırılası bir şey də yoxdur.

### Bir dəfəlik quraşdırma

1. **Figma desktop → Plugins → Development → Import plugin from manifest…** və `tools/figma-bridge/plugin/manifest.json` faylını seç.
2. **Claude Code-u bir dəfə yenidən başlat** ki, `figma_*` MCP tool-ları görünsün. `.mcp.json` serveri artıq qeydiyyata alıb (`node tools/figma-bridge/mcp.mjs`).

### Hər sessiyada

1. Faylı Figma-da aç.
2. **Plugins → Development → CBAR Figma bridge** işə sal.
3. **Plugin pəncərəsini açıq saxla** — bağlasan bağlantı qırılır.

Yoxlamaq üçün Claude Code-da `figma_health`, və ya `node tools/figma-bridge/cli.mjs health`. Cavab bridge-i, plugini və növbəni adlandırır; əhəmiyyət daşıyan sətir **`plugin: connected`**-dir.

Bridge-i əl ilə başlatmağa ehtiyac yoxdur: MCP serveri onu öz prosesində qaldırır. `node tools/figma-bridge/bridge.mjs` yalnız Claude Code olmadan CLI işlədəndə, və ya showcase-i başqa yerdəki bridge-ə yönləndirəndə lazımdır (`FIGMA_BRIDGE_URL`).

### Nəyi qidalandırır

| | |
| --- | --- |
| `/figma-sync` | Figma **Variables** cədvəlini oxuyur və `tokens.css`-i yenidən yazır, əvvəlcə diff göstərir |
| `pnpm figma:spec` | parity səhifəsinin müqayisə etdiyi `showcase/src/registry/figma-spec.json`-u yenidən qurur |
| Showcase-in Figma paneli | CBAR-ın həmin variantı necə çəkdiyini kitin render-i ilə yan-yana, plus hesablanmış stil müqayisəsi |

**Bridge bağlı olanda da hər şey render olunur** — saxlanmış capture-dan. Canlı hissə əlavədir, məcburi deyil. Showcase-də toolbar göstəricisi həm də açardır (`?figma=live|off`), və canlı rejim yalnız dev-də aktivdir.

**Tapıntılar yazıya alınır, keçərkən "düzəldilmir".** `#/parity?tab=findings` dizayn faylı ilə kitin harada ayrıldığını, sübutları və hansı tərəfin dəyişməli olduğunu göstərən hesabatdır. Məlum tapıntı: CBAR-ın Button set-i `primary`-ni firuzəyi, `secondary`-ni isə tünd mavi çəkir — faylın qalan hissəsinin əksinə. Kit variables cədvəli ilə uyğundur, Button isə istisnadır. Bunu `tokens.css`-də ramp-ları yerdəyişməklə "düzəltmə"; növbəti sinxronizasiya onsuz da üstündən yazacaq.

Ətraflı: [README §4b](../README.md#4b-two-ways-to-look-at-it), gündəlik əmrlər üçün `tools/instructions-mcp.md`, protokol üçün `tools/figma-bridge/README.md`.

---

## 8. Müzakirə olunmayan qaydalar

Bunların hər biri asanlıqla pozulur və bahalı başa gəlir.

**`src/styles/tokens.css` maşın sahibliyindədir.** `figma-sync` onu bütövlükdə yenidən yazır. Əl ilə edilmiş dəyişiklik növbəti sinxronizasiyaya qədər yaşayır.

**`src/icons/generated/` də maşın sahibliyindədir** — doqquz modulda 250 ikon, Figma faylından generasiya olunub. Onlara data kimi yanaş; bütövlükdə əvəz et. Əl sahibliyində olan hissə `src/icons/icons.tsx`-dir: aliaslar və üç Lucide ikonu.

**`radix-ui` barrel-ini heç vaxt import etmə.** Həmişə primitiv üzrə subpath:

```ts
import * as Slot from 'radix-ui/slot';   // düzgün
import { Slot } from 'radix-ui';         // yox — lint xətası
```

Barrel Radix işlədən 21 komponentin hamısından əlçatan tək moduldur, ona görə bundler onu bir ortaq chunk-a yığır və yalnız `Slot` istəyən komponent bütün kitabxananı özü ilə dartır. Ölçülüb: Button 10 kB-dan 434 kB-a qalxır.

**`src/lib/tw-merge/` vendor edilmiş upstream mənbədir.** Orada yalnız bir bilərəkdən edilmiş dəyişiklik var (`import` → `import type`, `verbatimModuleSyntax` üçün) və bir test qovluğu quraşdırılmış paketlə fayl-fayl müqayisə edir. Onu "səliqəyə salmaq" testi sındırır.

**`dependencies` boş qalır.** Ora yazdığın hər şey hər consumer-in lock faylına həmişəlik düşür. Paketə uzanmazdan əvvəl komponentə uzan; `pnpm lint` bu kitin əvəz etdiklərini artıq bloklayır — `clsx`, `class-variance-authority`, `lucide-react`, `cmdk`, `sonner`, `vaul`, `rc-*` və bütün tarix kitabxanaları.

**`src/` içində nə `--ui-*` primitivi, nə də sabit rəng.** `#hex`, `rgb()`, `hsl()`, `oklch()` — hamısı lint xətasıdır. İstisnalar `--ui-duration-*`, `--ui-ease-*` və `--ui-z-*`-dir: onların üstündə semantik qat yoxdur, çünki heç nə onları mövzuya görə yenidən xəritələmir.

**Install skripti olan yeni dependency hər iki allowlist-ə yazılır** — npm üçün `allowScripts`, pnpm üçün `pnpm.onlyBuiltDependencies`. Hər menecer o birinin sahəsini görməzdən gəlir.

**Showcase-in Tailwind `@source` təyinatı `showcase/src/showcase.css`-dədir, `src/styles/globals.css`-də yox.** globals.css Tailwind CLI tərəfindən publish olunan `dist/styles.css`-ə çevrilir — yəni ora əlavə edilmiş glob yalnız showcase-ə aid class-ları hər consumer-ə göndərir.

---

## 9. Nəsə sınanda

**Storybook başlamır — `ERR_DLOPEN_FAILED`.** Storybook `oxc-resolver`-dan asılıdır; onun native binding-inin Microsoft reputasiyası yoxdur və Smart App Control / WDAC onu bloklayır. Bu, maşın siyasətidir, kitin qüsuru deyil — yenidən quraşdırmaq kömək etmir. Showcase normal işləyir, CI da.

**Kopyalanmış `localhost:5175` linki başqa pəncərədə açılmır.** `pnpm showcase` `localhost`-a bağlanır, bu isə Windows-da yalnız IPv6 loopback deməkdir — `localhost`-u IPv4-ə çevirən brauzer profili (incognito pəncərə, telefon) sənin kopyaladığın yerdə işləyən linkdə bağlantı xətası alır. `pnpm showcase:host` hər iki ailəyə və LAN-a bağlanır. Bu, dev serveri və kitin mənbəyini həmin şəbəkəyə açır; çiyin üstündən baxışdan artıq hər şey üçün build edilmiş saytı deploy et.

**Figma paneli boşdur.** Plugin pəncərəsi bağlıdır və ya bridge işləmir. `figma_health` ilə yoxla. Başqa heç nəyə təsir etmir — panelin capture-a əsaslanan hissəsi işləməyə davam edir.

**Git Bash-dən verilən `SHOWCASE_BASE` Windows yoluna çevrilir.** MSYS başlanğıc slash-ı yenidən yazır, yəni `/my-kit/` `C:/Program Files/Git/my-kit/` kimi gəlir. PowerShell və ya `cmd` işlət — ya da əmrin əvvəlinə `MSYS_NO_PATHCONV=1` qoy.

**`CJS ⚡️ Build success`-dən dərhal sonra `ERR_WORKER_OUT_OF_MEMORY`.** `.d.ts` bundle-ı bütün tip qrafını eyni anda saxlayan worker-də qurulur. `scripts/run-tsup.mjs` məhz bunun üçün heap limitini qaldırır; yenə baş verirsə, `NODE_OPTIONS`-da özün daha böyük `--max-old-space-size` təyin et — skript sənin dəyərinə toxunmur.

**`pnpm verify` export map-də sınır.** Komponent əlavə etmisən və ya adını dəyişmisən, amma `pnpm exports:gen` işə salmamısan. Props cədvəlləri və `pnpm props:gen` üçün də eyni.

**Install `.git can't be found` yazır.** Husky git repo-su olmayan qovluqda hook quraşdırmaqdan imtina edir, təzə scaffold isə hələ repo deyil. Başqa heç nəyə təsiri yoxdur — install özü uğurla bitib. `git init`, sonra `npx husky` işlət; `git config --get core.hooksPath` cavabı `.husky/_` olmalıdır.

**Hook ilk sətrində shell sintaksis xətası ilə sınır.** Checkout onu CRLF-ə çevirib. `.gitattributes` `.husky/**`-i məhz buna görə LF-ə bağlayır; artıq klonlanmış ağacda `git add --renormalize .` düzəldir.

---

## Daha dərinə

| Mövzu | Harada |
| --- | --- |
| Arxitektura, üç qayda | [README §2](../README.md#2-architecture) |
| Token qatları, palitralar | [README §3](../README.md#3-design-tokens) |
| Komponent siyahısı və kənar halları | [README §4](../README.md#4-what-ships) |
| 250 ikonluq dəst | [README §4a](../README.md#4a-the-icon-set) |
| Showcase vs Storybook, parity səhifəsi | [README §4b](../README.md#4b-two-ways-to-look-at-it) |
| Mövcud consumer-lər üçün migration qeydləri | [README §9](../README.md#9-migrating) |
| Kiti publish etmədən işlətmək, tam bələdçi | [`kit-local.az.md`](./kit-local-development/kit-local.az.md) |
| Skill-ləri tətbiq komandasına təhvil vermək | [`consumer-skills/README.md`](../consumer-skills/README.md) |
| Gündəlik Figma əmrləri | `tools/instructions-mcp.md` |

| Skill | Nə edir |
| --- | --- |
| `/kit-guide` | bu sənədi mövcud koddan yenidən yazır |
| `/ui-kit-component` | build-in gözlədiyi formada komponent əlavə edir |
| `/figma-sync` | Figma-dan tokenləri çəkib `tokens.css`-ə yazır |
| `/design-audit` | kiti Figma ilə tutuşdurur, report və fix planı yazır |
| `/professional-review` | kodun özünü review edir — arxitektura, təmiz kod, adlandırma — və `professional_review.md`-ə refactor planı yazır |
| `/brand-kit` | kiti komandanın öz kitinə çevirir — ad, rəng, lisenziya, loqotip |
| `/kit-doctor` | bütün gate-i işlədir və sınanları təsnif edir |
| `/release-kit` | publish prosesini başdan-sona keçir |
| `/update-deps` | consumer-ləri sındırmadan dependency-ləri yeniləyir |
| `/consumer-skills` | tətbiqin aldığı skill-ləri yeniləyir |