@handijit/ui 1.0.0 → 2.0.0

package/README.md

@@ -1,32 +1,46 @@
 # @handijit/ui
 
-Erişilebilir, tema güdümlü React bileşen kütüphanesi. SCSS Modules üzerine
-kurulu; tek çalışma zamanı bağımlılığı ikon seti (`react-bootstrap-icons`).
-
-- **Tek CSS dosyası, iki tema.** Açık ve koyu hazır gelir, her token dışarıdan
-  ezilebilir.
-- **Yönlendirici enjekte edilir.** `next/link`, `react-router`, ham `<a>` —
-  karar tüketicinin.
-- **Metin dışarıdan, ama BİR KEZ.** Kütüphane hiçbir dilde metin uydurmaz;
-  kullanıcıya görünen dizeler sağlayıcıda tek yerde tanımlanır.
-- **Yerel öğeler korunur.** `<dialog>`, `<input type="range">`,
-  `<input type="radio">` — odak tuzağı, klavye gezinmesi ve ekran okuyucu
-  duyurusu tarayıcıdan gelir.
-- **Üç alt giriş, ana pakete sıfır bayt.** `@handijit/ui/chat` (sohbet ve
-  araç arayüzleri), `@handijit/ui/charts` (bağımlılıksız SVG grafikleri),
-  `@handijit/ui/scss` (token değişkenleri ve mixin'ler). Kullanmayan uygulama
-  onları indirmez.
+Accessible React components for Han Dijit applications: the site, the staff
+panel and the desktop programs. Built on SCSS Modules and drawn with the tokens
+of [`@handijit/design`](https://www.npmjs.com/package/@handijit/design).
+
+- **One design source.** Colours, type, radii, spacing, motion and layers come
+  from `@handijit/design` (`--hd-*`). This package holds no palette of its own.
+- **Light and dark.** Both themes ship; the choice rides on `data-theme`, the
+  contract `@handijit/design` defines.
+- **The router is injected.** `next/link`, `react-router`, a plain `<a>`: the
+  application decides.
+- **Text comes from outside, once.** The library invents no string in any
+  language; user-visible strings are defined in one place, on the provider.
+- **Native elements are kept.** `<dialog>`, `<input type="range">`,
+  `<input type="radio">`: focus trapping, keyboard handling and screen reader
+  announcements come from the browser.
+- **Three sub-entries, zero bytes in the main bundle.** `@handijit/ui/chat`
+  (chat and tool interfaces), `@handijit/ui/charts` (dependency-free SVG
+  charts), `@handijit/ui/scss` (token variables and mixins).
 
 ```bash
-npm install @handijit/ui @handijit/utils react-bootstrap-icons
+npm install @handijit/ui @handijit/design @handijit/utils react-bootstrap-icons
 ```
 
-`react`, `react-dom`, `@handijit/utils` ve `react-bootstrap-icons`
-**peer** bağımlılıktır.
+`react`, `react-dom`, `@handijit/design` (`^1.0.0`), `@handijit/utils`
+(`^2.0.0`) and `react-bootstrap-icons` are **peer** dependencies. The design
+package is a peer on purpose: an application has exactly one copy of the tokens,
+and the site, the panel and the components all read the same custom properties.
+
+Coming from 1.x? The migration is in [`CHANGELOG.md`](./CHANGELOG.md) under
+2.0.0, old name → new name for every token, variable, prop, variant and export.
 
 ---
 
-## Hızlı başlangıç
+## Quick start
+
+```tsx
+// Once, at the root of the application. The order matters.
+import '@handijit/design/tokens.css'; // the --hd-* custom properties, both themes
+import '@handijit/design/fonts.css'; // optional: Archivo, Inter, IBM Plex Mono
+import '@handijit/ui/styles.css';
+```
 
 ```tsx
 import { Button, Field, Input, UIVariant } from '@handijit/ui';
@@ -40,210 +54,208 @@ import { Button, Field, Input, UIVariant } from '@handijit/ui';
 </Button>;
 ```
 
-Sağlayıcı **zorunlu değil**: paket kurulup hiçbir yapılandırma yapılmadan
-çalışır. Bağlantılar ham `<a>` olur, tema varsayılanlarda kalır.
+The provider is **optional**: the package works with no configuration. Links
+are plain `<a>` elements and labels are whatever each call passes.
 
-**CSS tek dosya olarak alınır.** Uygulamanın kökünde bir kez:
+`@handijit/ui/styles.css` carries **no tokens**. Without
+`@handijit/design/tokens.css` every colour resolves to nothing. `fonts.css` is
+optional: load the three families your own way (`next/font`, self-hosted
+`@font-face`) if you prefer, the tokens only name them.
 
-```tsx
-import '@handijit/ui/styles.css';
-```
+### A subset of the CSS
 
-Alt küme isteyen tüketici `base.css` (token'lar, kutu modeli, `@keyframes`) ile
-kullandığı bileşenlerin `components/<Ad>/style.css` dosyalarını **kendi
-derlemesinde tek dosyaya** birleştirir:
+An application that wants less imports `base.css` (box model, `@keyframes`,
+helpers) and the `components/<Name>/style.css` files of the components it uses,
+and lets its own build join them:
 
 ```scss
-// styles/ui.scss — Sass düz CSS dosyalarını içine alır.
+// styles/ui.scss: Sass inlines plain CSS files.
 @use '@handijit/ui/base.css';
 @use '@handijit/ui/components/Button/style.css';
 @use '@handijit/ui/components/Chip/style.css';
 ```
 
-JS modülleri CSS içe aktarmaz; bu bilinçli: Turbopack'te her istemci sınırının
-CSS'i ayrı dosyaya düşüyor ve render-blocking dosya sayısı LCP'yi bayttan çok
-etkiliyordu (`CHANGELOG.md` → 1.0.0).
+The JavaScript modules do not import CSS. That is deliberate: under Turbopack
+every client boundary's CSS landed in its own file, and the number of
+render-blocking files hurt LCP more than the bytes did.
 
-Her bileşenin alt yolu var — `@handijit/ui/button`, `/chip-group`,
-`/combobox`… — ama cephe (`@handijit/ui`) saf yeniden dışa aktarım olduğu
-için paketleyici ikisinden de aynı dosyaya iner.
+Every component also has a subpath (`@handijit/ui/button`, `/chip-group`,
+`/combobox`, …). The main entry is a pure re-export, so a bundler reaches the
+same file either way.
+
+The sub-entries have their own stylesheets, imported **after** `styles.css`:
+`@handijit/ui/chat.css`, `@handijit/ui/charts.css`.
 
 ---
 
-## Tema
+## Theme
 
-### Tema seçimi `<html>` üzerinde taşınır
+### The choice rides on `<html data-theme>`
 
 ```html
-<html data-ui-theme="dark">
+<html data-theme="dark"></html>
 ```
 
-Öznitelik yoksa `prefers-color-scheme` yedeği devreye girer — ama kullanıcının
-**açık bir seçimi** varsa sistem tercihi onu ezmez.
+This is the contract of `@handijit/design`, not a setting of this package:
+`data-theme="light"` or `"dark"` on the root element picks the theme, and
+without the attribute `prefers-color-scheme` decides. An explicit choice is
+never overridden by the system setting. The attribute also works on any
+element, to draw one region in the other theme.
 
-### İlk boyamadan önce yazın — `UiThemeScript`
+### Write it before the first paint: `UiThemeScript`
 
 ```tsx
-// app/layout.tsx — sunucu düzeni, <head> içine.
+// app/layout.tsx, a server layout, inside <head>.
 import { UiThemeScript } from '@handijit/ui';
 
 <head>
-  <UiThemeScript storageKey="theme" />
+  <UiThemeScript nonce={nonce} />
 </head>;
 ```
 
-Kayıtlı açık seçimi (`light` / `dark`) `<html data-ui-theme>`e yazar; kayıt
-yoksa sistem tercihi izlenir. Satır içi betik HTML ayrıştırılırken çalışır.
+It renders the boot script of `@handijit/design` (`THEME_BOOT_SCRIPT`) as an
+inline `<script>`. The script reads `localStorage["hd-theme"]` (`light` or
+`dark`; anything else means "follow the system"), writes `data-theme` while the
+HTML is still being parsed, and follows the system setting when it changes.
+Without it a user who chose dark sees one light frame.
 
-Bu iş sağlayıcıya bırakılamaz: sağlayıcı ağaç monte olduktan sonra çalışıyor ve
-koyu tema seçmiş kullanıcı o ana kadar **bir kare beyaz ekran** görüyor.
-⚠ Bir **bileşen**, fonksiyon değil: paket `'use client'` taşıdığı için dışa
-verilen düz bir fonksiyon Next'in sunucu düzeninde çağrılamıyor.
+It is a component and not a function because a plain function exported from a
+package with `'use client'` files cannot be called from a Next.js server layout.
 
-### Token'ları ezmek
+### Content Security Policy
 
-Yalnızca değiştirdiğiniz token'ı verin; gerisi varsayılanında kalır.
+The boot script is the **only** element this library injects. It injects no
+`<style>` element at all.
 
-```tsx
-import { UiProvider } from '@handijit/ui';
-
-const THEME = {
-  light: { link: '#0a58ca', 'ring-color': '#0d6efd' },
-  dark: { link: '#6ea8fe' },
-  fonts: { heading: 'Archivo, sans-serif', body: 'Inter, sans-serif' },
-  // Ölçüler tema başına DEĞİL: bir markanın yuvarlaklığı açık temada
-  // 12 px, koyu temada 8 px olmaz.
-  metrics: { 'radius-md': '2px', 'radius-lg': '4px', 'duration-normal': '120ms' },
-};
+| Policy style      | What to do                                                                  |
+| ----------------- | --------------------------------------------------------------------------- |
+| Nonce per request | `<UiThemeScript nonce={nonce} />`                                           |
+| Static hash       | add `'${THEME_BOOT_SCRIPT_HASH}'` to `script-src`; the page stays cacheable |
+
+```ts
+import { THEME_BOOT_SCRIPT_HASH } from '@handijit/ui'; // re-exported from @handijit/design
 
-<UiProvider theme={THEME} linkComponent={NextLink}>
-  <App />
-</UiProvider>;
+const policy = `script-src 'self' '${THEME_BOOT_SCRIPT_HASH}'`;
 ```
 
-Sağlayıcı ezmeyi çocuklarından önce bir `<style>` olarak **çizer**: sunucu
-çıktısında da vardır, ilk boyamada uygulanır; hidrasyondan sonra hiçbir renk
-değişmez. Bu yüzden sağlayıcı `<body>` içinde durur, `<html>`i saramaz.
+`THEME_ATTRIBUTE`, `THEME_STORAGE_KEY`, `THEME_BOOT_SCRIPT` and
+`THEME_BOOT_SCRIPT_HASH` are re-exports, not copies: the digest always matches
+the script the installed design package ships.
 
-Ezme `@layer ui` içindedir: aynı token'ı kendi CSS'inizde ezerseniz
-(`html:has(.panel) { --ui-danger-solid: #dc2626 }`) sizinki özgüllüğe ve
-sıraya bakılmaksızın kazanır. Açık temaya verilen değer koyu temaya sızmaz;
-koyu temada da istiyorsanız `dark`a da yazın.
+Some components position or size themselves with inline `style` attributes
+(popover coordinates, progress width, virtual list offsets). A nonce cannot
+cover an attribute; a policy that restricts inline styles needs
+`style-src-attr 'unsafe-inline'`.
 
-React'in dışından (Storybook'tan, stil sayfalarından sonra çalışan bir
-betikten) aynı işi `initUi({ theme })` yapar; ezmeyi `<head>`in sonuna
-yazar. ⚠ Stil sayfalarınızdan **önce** çağırmayın: `@layer ui` belgede ilk
-kez orada görülürse katman sırası oradan kurulur ve sonra gelen
-`@layer reset, @handijit/ui;` bildiriminiz `reset`i kütüphanenin üstüne koyar.
+### Changing the theme
 
-**Kütüphane font YÜKLEMEZ.** `fonts` yalnızca `font-family` dizesi; yüklemeyi
-(`next/font`, `@font-face`, CDN) siz yaparsınız. Bir UI paketinin ağdan font
-çekmesi, sizin ölçemediğiniz bir istek demek.
+```tsx
+const { scheme, preference, setScheme, toggle, isReady } = useUiTheme();
+```
 
-#### Ezilebilen ölçüler
+| Field        |                                                                        |
+| ------------ | ---------------------------------------------------------------------- |
+| `scheme`     | the **resolved** theme, the one on screen (`light` \| `dark`)          |
+| `preference` | the user's **choice** (`light` \| `dark` \| `system`)                  |
+| `setScheme`  | stores the choice and applies it; `'system'` removes the stored choice |
+| `toggle`     | flips between light and dark                                           |
+| `isReady`    | `false` on the server and on the first client frame                    |
 
-`radius-*` · `space-0…9` · `font-size-2xs…4xl` · `leading-*` · `icon-xs…xl` ·
-`duration-*` · `ease-*` — tam liste `METRIC_TOKENS` içinde ve dışa veriliyor.
+A three-state switch (Light / Dark / System) reads `preference`; if it read
+`scheme`, "System" would show "Dark" as selected.
 
-Ezilemeyenler ve nedenleri: **kırılma noktaları** (`@media (max-width: var(--x))`
-geçersiz CSS), **katman (`z-*`)** (yığılma sırası, marka kararı değil) ve
-**dokunma hedefi** (44 px; yoğun kipte de küçülmemeli — WCAG 2.5.8).
+`setScheme` writes where the boot script reads: `localStorage["hd-theme"]`
+holds `light` or `dark`, "system" removes the key, and the attribute always
+carries the resolved theme. A choice made through the hook therefore survives a
+reload without a flash. Wait for `isReady` before drawing the switch: the
+server does not know the choice, and a guessed switch mismatched on hydration
+even when the guess was right.
 
-### Bilgi yoğunluğu
+### Brand and product overrides
 
-```html
-<html data-ui-density="compact"></html>
-```
+There is no theme prop. A value is changed where it is defined, as a custom
+property, in the application's own stylesheet:
+
+```css
+:root {
+  --hd-radius-md: 10px;
+}
 
-Satır yüksekliği, dolgu ve punto bir kademe iner. Vitrin bir ekranda 8 satır,
-operasyon paneli 80 satır gösteriyor; ikisini tek ölçekle karşılamanın yolu yok.
-Kararı `initUi({ density: 'compact' })` da verebilir.
+/* The same selector the design package uses, or the override loses on <html>. */
+:root[data-theme='dark'] {
+  --hd-bg-page: #0b0d12;
+}
+```
 
-**Yarıçap değişmez** (yuvarlaklık yoğunluğun değil markanın işi) ve **dokunma
-hedefi küçülmez**: görsel kutu daralır, `tap-target` örtüsü 44 px kalır.
+Change the tokens of `@handijit/design` sparingly: the contrast of every text
+and focus pair is measured against the published values.
 
-### CSS'imizi ezmek — `@layer ui`
+### Overriding our CSS: `@layer ui`
 
-Kütüphane CSS'inin tamamı `@layer ui` içinde — tema ezmeleri
-(`UiProvider theme`, `initUi`) dahil. Katmanlı bir kural, katmansız
-bir kurala **her zaman yenilir** — özgüllüğe ve sıraya bakılmaksızın:
+All of the library's CSS is inside `@layer ui`. A layered rule **always loses**
+to an unlayered one, whatever the specificity or source order:
 
 ```css
-/* Bu kadarı yeter; `!important` ya da `.app .card .card` gerekmez. */
+/* This is enough; no `!important`, no `.app .card .card`. */
 .my-card {
   padding: 0;
 }
 ```
 
-Katman olmadan sizin sınıfınız ile bizimki aynı özgüllükte (0,1,0) yarışıyordu
-ve kazananı **kaynak sırası** belirliyordu; o sıra da bundler'ınızın elinde —
-geliştirme ile üretim aynı olmak zorunda değil.
+Without the layer your class and ours competed at the same specificity and the
+winner was decided by source order, which is in your bundler's hands and need
+not be the same in development and production.
+
+### Component variables
+
+Besides the design tokens, a few components read custom properties of their own
+(`var(--ui-…, default)`) so an application can restyle one component from
+`:root` without a class selector:
+
+| Component    | Variables                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| focus ring   | `--ui-ring-width` (2px) · `--ui-ring-offset` (2px; `-2px` pulls it inside)                                                            |
+| inputs       | `--ui-placeholder` (`text-3`)                                                                                                         |
+| modal scrim  | `--ui-scrim-blur`                                                                                                                     |
+| `Button`     | `--ui-button-radius` · `-weight` · `-tracking` · `-wrap` (`nowrap`)                                                                   |
+| `Chip`       | `--ui-chip-bg` · `-line` · `-fg` · `-radius` · `-weight` · `-selected-bg` · `-selected-line` · `-selected-fg` · `-selected-weight`    |
+| `Badge`      | `--ui-badge-font` · `-weight` · `-tracking` · `-transform` · `-radius` · `-bg` · `-line` · `-fg`                                      |
+| `Stat`       | `--ui-stat-label-font/-size/-weight/-tracking/-transform` · `-value-font/-weight/-tracking` · `-unit-font/-size/-tracking/-transform` |
+| `Tabs`       | `--ui-tab-weight`                                                                                                                     |
+| `RadioCard`  | `--ui-radio-card-line` · `-radius`                                                                                                    |
+| sticky parts | `--ui-header-height` (see below)                                                                                                      |
 
-### Temayı değiştirmek
-
-```tsx
-const { scheme, preference, setScheme, toggle, isReady } = useUiTheme();
-
-useEffect(() => {
-  if (isReady) localStorage.setItem('theme', preference);
-}, [preference, isReady]);
+```css
+:root {
+  --ui-ring-offset: -2px;
+  --ui-button-weight: 500;
+  --ui-chip-radius: var(--hd-radius-pill);
+  --ui-badge-font: var(--hd-font-mono);
+  --ui-badge-transform: uppercase;
+}
 ```
 
-| Alan | |
-| --- | --- |
-| `scheme` | **ÇÖZÜLMÜŞ** tema — ekranda çizili olan (`light` \| `dark`) |
-| `preference` | kullanıcının **SEÇİMİ** (`light` \| `dark` \| `system`) |
-| `setScheme` | `'system'` verildiğinde açık seçim SİLİNİR |
-
-Üç durumlu bir anahtar (Açık / Koyu / Sistem) `preference` okur; `scheme`
-okusaydı "Sistem" seçiliyken düğme "Koyu"yu işaretli gösterirdi. `system` bir
-değer değil **değerin yokluğu**: öznitelik silinir ve
-`:not([data-ui-theme])` sorgusu devreye girer.
+`--ui-*` is the prefix of component-private variables only. Every global value
+(colour, size, radius, duration, layer) is `--hd-*`.
 
-Kalıcılık **kancanın işi değil**: seçimi `localStorage`a mı, sunucuda
-okunabilsin diye bir çereze mi, kullanıcı profiline mi yazacağınız sizin
-kararınız. Kütüphane `localStorage`a yazsaydı sunucu tarafı onu okuyamayacağı
-için ilk boyama yine yanlış temada olurdu.
+### Reading tokens in JavaScript
 
-`isReady`: sunucu çıktısında ve hidrasyondan önceki ilk karede `false`. Tema
-anahtarını çizmeden önce bekleyin — sunucu hangi temanın seçili olduğunu
-bilmiyor ve bir tahminle çizilen anahtar, doğru tahmin edilse bile hidrasyonda
-uyuşmazlık üretiyordu.
-
-### Token katmanları
-
-```
-theme/palette.ts   → ham hex (TEK hex kaynağı)
-theme/tokens.ts    → anlamsal token → değer
-                     LIGHT_THEME / DARK_THEME  (renk, temaya bağlı)
-                     METRIC_TOKENS             (ölçü, temadan bağımsız)
-                     COMPACT_DENSITY           (yoğun kipin ezdikleri)
-styles/*.generated → yukarıdakinden ÜRETİLİR (npm run tokens)
+```tsx
+const colors = useUiTokens(['border', 'chart-1']); // { border: '#…', 'chart-1': '#…' }
 ```
 
-SCSS ve TypeScript tarafı elle tutulsaydı bir tarafta var olup diğerinde
-olmayan bir token çıkardı — ve ayrışma sessiz: bileşen `var(--ui-yok)`
-okuyup rengini kaybediyor, derleme yeşil dönüyor. Nöbetçi
-`theme/__tests__/tokens.contract.test.ts`.
-
-**Ölçüler CSS değişkeni olduğu için SCSS aritmetiği çalışmaz.**
-`$space-8 - $space-2` derlenmez — ve Sass hata da vermez: ifadeyi olduğu gibi
-geçirip tarayıcıya `var(--a)-var(--b)` yazar, tarayıcı bütün bildirimi atar.
-Hesap `calc()` içinde yazılır, negatif değer dahil:
-
-```scss
-padding-inline-start: calc(#{$space-8} - #{$space-2});
-margin-inline: calc(-1 * #{$space-2});
-```
+`useUiTokens` returns the resolved values of design tokens and follows theme
+changes; it is for canvas and third-party charts that cannot read `var()`. On
+the server and the first frame it returns `currentColor`. The names are
+`TokenName` of `@handijit/design`.
 
 ---
 
-## Metinler
+## Labels
 
-Kütüphane "Kapat" yazamaz: hangi dilde, hangi üslupta, hangi terimle
-yazacağını bilmez. Ama aynı dizeyi yüz çağrı yerine dağıtmak da doğru değil —
-biri değiştiğinde doksan dokuzu eski kalıyor. Metinler **bir kez**, sağlayıcıda
-verilir:
+The library cannot write "Close": it does not know the language, the tone or
+the term. Spreading the same string over a hundred call sites is not right
+either. Labels are given **once**, on the provider:
 
 ```tsx
 <UiProvider
@@ -283,37 +295,28 @@ verilir:
 >
 ```
 
-**Çözümleme sırası: prop → config → geliştirme uyarısı.** Bir prop verilmişse o
-kazanır; bağlama göre farklı olması gereken yerlerde (`closeLabel="Daha sonra"`)
-hâlâ prop geçilir.
+**Resolution order: prop → provider → development warning.** A prop wins when
+given; pass one where the wording depends on the context
+(`closeLabel="Daha sonra"`).
 
-### Config'e girmeyenler
+Text that belongs to **one element** never goes on the provider, because it
+differs at every call site: `Modal.title`, `ConfirmDialog.confirmLabel` ("Sil":
+it must repeat the action; "OK" does not say what is being confirmed),
+`IconButton.label`, `Select.label`, `Combobox.labels.placeholder`,
+`TableCheckbox.label`, `ChipGroup.label`, `RatingInput.label`.
 
-Öğeye **özgü** hiçbir metin config'e girmez — her çağrı yerinde farklı olduğu
-için bir uygulama düzeyinde varsayılanı olamaz:
-
-`Modal.title` · `ConfirmDialog.confirmLabel` ("Sil" — eylemi tekrarlamak
-zorunda; "Tamam" kullanıcıya neyi onayladığını söylemez) · `IconButton.label` ·
-`Select.label` · `Combobox.labels.placeholder` · `TableCheckbox.label` ·
-`ChipGroup.label` · `RatingInput.label`
-
-### Eksik metin nasıl görünür
-
-TypeScript sağlayıcının çalışma zamanında ne taşıdığını göremiyor, o yüzden
-prop'lar isteğe bağlı. Ne prop ne config varsa öğe adsız kalır ve bu geliştirme
-kipinde konsola düşer:
+TypeScript cannot see what the provider carries at run time, so the props are
+optional. With neither a prop nor a provider value the element stays unnamed
+and, in development, the console says so once per key:
 
 ```
 [@handijit/ui] Eksik metin: Modal.closeLabel. Prop olarak geçin ya da
 <UiProvider labels={…}> içinde bir kez tanımlayın.
 ```
 
-Uyarı anahtar başına bir kez verilir; yirmi satırlık bir liste konsolu
-doldurmaz.
-
 ---
 
-## Yönlendirici
+## Router
 
 ```tsx
 import NextLink from 'next/link';
@@ -321,41 +324,31 @@ import NextLink from 'next/link';
 <UiProvider linkComponent={NextLink}>…</UiProvider>;
 ```
 
-Bir bileşen kütüphanesi kendi yönlendiricisini **seçemez**: `next/link` import
-etmek paketi Next'e bağlar, `react-router` import etmek başka bir uygulamayı
-kırar.
-
-Yönlendiriciye özgü props `linkProps` ile geçer:
+A component library cannot choose the router: importing `next/link` ties the
+package to Next.js, importing `react-router` breaks another application.
+Router-specific props travel through `linkProps`:
 
 ```tsx
 <Pagination buildHref={page => `?sayfa=${page}`} linkProps={{ scroll: false }} … />
 ```
 
----
-
-## Sayfalamada başa dönme
-
-Sayfa değiştiren tıklamadan sonra pencereyi başa almak bir **prop**tur; çağıran
-tarafta kaydırma kodu yazılmaz:
+### Back to the top after a page change
 
 ```tsx
 <Pagination page={page} totalPages={totalPages} scrollTo="top" … />
 ```
 
-İki kipte de çalışır (`buildHref` ve `onPageChange`). Kaydırma anidir ve üç
-durumda **yapılmaz**: etkin sayfaya basıldığında, yeni sekmede açan tıklamada
-(Ctrl/Cmd/orta tuş) ve prop verilmediğinde.
+It works in both modes (`buildHref` and `onPageChange`). The scroll is instant
+and does **not** happen when the active page is pressed, when the click opens a
+new tab (Ctrl/Cmd/middle button), or when the prop is absent. Do not pass it
+for a list inside a page (reviews in a tab): it throws the reader to the top.
 
-⚠ Sayfa içindeki bir listenin sayfalamasında (sekme içi değerlendirme listesi
-gibi) **verilmez** — kullanıcıyı okuduğu bölümden sayfanın tepesine atar.
+### Sticky header
 
----
-
-## Yapışkan başlık
-
-Sayfa kaydırmasına yapışan bileşenler (`DirectoryGroup`, `DirectoryJump`,
-kapaklı `DataTable`) offset'i `--ui-header-height`ten okur ve **varsayılanı
-0**. Kendi yapışkan bandınız varsa gerçek ölçüyü yazın:
+Components that stick while the page scrolls (`DirectoryGroup`,
+`DirectoryJump`, a `DataTable` with a caption) read their offset from
+`--ui-header-height`, **0 by default**. If the application has a sticky band,
+write its real height:
 
 ```tsx
 useEffect(() => {
@@ -370,126 +363,141 @@ useEffect(() => {
 }, []);
 ```
 
-Sabit bir sayı yazmayın: bant mobilde arama kutusu kendi satırına düştüğünde
-büyür, bir duyuru şeridi çıkıp kaybolduğunda değişir.
+Do not write a constant: the band grows when the search box wraps on a phone
+and changes when an announcement strip appears.
 
 ---
 
-## Bileşen kataloğu
-
-| Grup | Bileşenler |
-| --- | --- |
-| Eylem | `Button` · `IconButton` · `TextLink` · `Tooltip` · `Menu` · `ContextMenu` · `Popover` |
-| Seçim | `Chip` · `ChipGroup` · `SegmentedControl` · `Select` · `Combobox` · `Checkbox` · `Switch` · `Radio` · `RadioCard` · `RangeSlider` · `RatingInput` · `QuantityStepper` · `TableCheckbox` |
-| Girdi | `Input` · `PasswordInput` · `Textarea` · `TagInput` · `DateField` · `FileUpload` · `Field` |
-| Yüzey | `Card` (+ `CardMedia`, `CardOverlay`, `CardBody`, `CardFooter`) · `SummaryCard` · `Panel` (+ `PanelForm`, `PanelRow`) · `PageHeader` · `SectionHeader` · `Tile` · `Directory` (+ `DirectoryGroup`, `DirectoryRow`, `DirectoryJump`) · `Carousel` · `ScrollArea` · `Disclosure` · `Accordion` · `Tabs` |
-| Geri bild. | `Alert` · `Badge` · `StatusDot` · `CodeBadge` · `Kbd` · `EmptyState` · `Skeleton` (+ `SkeletonCard`, `SkeletonRows`, `SkeletonTable`) · `Spinner` · `Progress` · `Steps` · `Divider` · `Avatar` · `Rating` · `Price` · `Stat` · `CopyField` · `Breadcrumb` · `ToastHub` (+ `ToastPortal`) |
-| Kipsel | `Modal` · `Drawer` · `BottomSheet` · `ConfirmDialog` · `PromptDialog` · `CommandPalette` |
-| Veri | `Table` (+ `TableScroller`) · `DataTable` (+ `DataTableRow`) · `FilterBar` (+ `FilterBarField`) · `Pagination` · `Timeline` |
-| Tema ve kancalar | `UiProvider` · `UiThemeScript` · `initUi` · `useUi` · `useUiTheme` · `useUiTokens` · `useAnnounce` · `useStickToBottom` · `usePositioning` · `useVirtualList` · `useListboxNavigation` · `hasOpenSurface` |
-| Sohbet — `/chat` | `ChatThread` · `ChatMessage` · `PromptInput` · `PromptSuggestions` · `Prose` · `CodeBlock` · `ReasoningBlock` (+ `ReasoningText`) · `ToolCall` (+ `ToolCallSection`) · `TerminalOutput` · `SourceList` · `Citation` · `MessageActions` · `AppBar` · `ActionList` (+ `ActionListItem`) · `SegmentBar` · `Legend` · `DescriptionList` |
-| Grafik — `/charts` | `LineChart` · `AreaChart` · `BarChart` · `ComposedChart` · `PieChart` · `ScatterPlot` · `Heatmap` · `BoxPlot` · `Histogram` · `RadarChart` |
-
-Alt girişlerin stilleri ayrı dosyada ve `styles.css`ten **sonra** içe aktarılır:
-`@handijit/ui/chat.css`, `@handijit/ui/charts.css`.
+## Component catalogue
+
+| Group             | Components                                                                                                                                                                                                                                                                                                                          |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Action            | `Button` · `IconButton` · `TextLink` · `Tooltip` · `Menu` · `ContextMenu` · `Popover`                                                                                                                                                                                                                                               |
+| Choice            | `Chip` · `ChipGroup` · `SegmentedControl` · `Select` · `Combobox` · `Checkbox` · `Switch` · `Radio` · `RadioCard` · `RangeSlider` · `RatingInput` · `QuantityStepper` · `TableCheckbox`                                                                                                                                             |
+| Input             | `Input` · `PasswordInput` · `Textarea` · `TagInput` · `DateField` · `FileUpload` · `Field`                                                                                                                                                                                                                                          |
+| Surface           | `Card` (+ `CardMedia`, `CardOverlay`, `CardBody`, `CardFooter`) · `SummaryCard` · `Panel` (+ `PanelForm`, `PanelRow`) · `PageHeader` · `SectionHeader` · `Tile` · `Directory` (+ `DirectoryGroup`, `DirectoryRow`, `DirectoryJump`) · `Carousel` · `ScrollArea` · `Disclosure` · `Accordion` · `Tabs`                               |
+| Feedback          | `Alert` · `Badge` · `StatusDot` · `CodeBadge` · `Kbd` · `EmptyState` · `Skeleton` (+ `SkeletonCard`, `SkeletonRows`, `SkeletonTable`) · `Spinner` · `Progress` · `Steps` · `Divider` · `Avatar` · `Rating` · `Price` · `Stat` · `CopyField` · `Breadcrumb` · `ToastHub` (+ `ToastPortal`)                                           |
+| Modal             | `Modal` · `Drawer` · `BottomSheet` · `ConfirmDialog` · `PromptDialog` · `CommandPalette`                                                                                                                                                                                                                                            |
+| Data              | `Table` (+ `TableScroller`) · `DataTable` (+ `DataTableRow`) · `FilterBar` (+ `FilterBarField`) · `Pagination` · `Timeline`                                                                                                                                                                                                         |
+| Theme and hooks   | `UiProvider` · `UiThemeScript` · `useUi` · `useUiTheme` · `useUiTokens` · `useAnnounce` · `useStickToBottom` · `usePositioning` · `useVirtualList` · `useListboxNavigation` · `hasOpenSurface`                                                                                                                                      |
+| Chat, `/chat`     | `ChatThread` · `ChatMessage` · `PromptInput` · `PromptSuggestions` · `Prose` · `CodeBlock` · `ReasoningBlock` (+ `ReasoningText`) · `ToolCall` (+ `ToolCallSection`) · `TerminalOutput` · `SourceList` · `Citation` · `MessageActions` · `AppBar` · `ActionList` (+ `ActionListItem`) · `SegmentBar` · `Legend` · `DescriptionList` |
+| Charts, `/charts` | `LineChart` · `AreaChart` · `BarChart` · `ComposedChart` · `PieChart` · `ScatterPlot` · `Heatmap` · `BoxPlot` · `Histogram` · `RadarChart`                                                                                                                                                                                          |
+
+### Variants and sizes
+
+| `UIVariant` | Use                                                                     |
+| ----------- | ----------------------------------------------------------------------- |
+| `PRIMARY`   | the one expected action of the screen: cobalt fill                      |
+| `ACCENT`    | the conversion action (download, try, subscribe): coral fill, only that |
+| `SECONDARY` | a neutral second action: grey border, body text                         |
+| `OUTLINE`   | a cobalt frame: an encouraged navigation that is not the primary action |
+| `SOFT`      | a neutral fill: a secondary action inside a card                        |
+| `GHOST`     | no surface: toolbar and inline secondary actions, in the link colour    |
+| `DANGER`    | a destructive action                                                    |
+| `ON_BAND`   | an action on the brand band (deep cobalt in both themes)                |
+
+`UISize`: `XSMALL` 28px · `SMALL` 32px · `MEDIUM` 40px · `LARGE` 48px. Fields
+are 40px with 15px text on desktop and 44px with 16px text on a narrow or touch
+screen (no iOS zoom, a full touch target).
+
+`IconButton variant`: `ghost` · `outline` · `solid` · `accent` · `danger`.
+`Badge tone`: `neutral` · `success` · `danger` · `warning` · `info` ·
+`highlight`, each as `soft`, `solid` or `outline`.
+
+### The number of options picks the element
+
+| Options       | Element                                              |
+| ------------- | ---------------------------------------------------- |
+| ≤7            | `ChipGroup`: all on screen, one tap                  |
+| 5–20          | `Select`: a list without search                      |
+| 20+           | `Combobox`: type to search                           |
+| A range       | `RangeSlider` (+ a number input for the exact value) |
+| A single flag | `Checkbox`                                           |
+
+### Dropdown or bottom sheet
+
+`Select` and `Combobox` open a **dropdown anchored to the trigger** on every
+screen except a narrow touch one, where they open a **bottom sheet**. The rule
+is one media query, exported as `SHEET_MEDIA_QUERY`:
+`(max-width: 640px) and (pointer: coarse)`. A narrow desktop window, an
+Electron window included, keeps the dropdown.
 
-### Seçenek sayısı öğeyi belirler
+---
 
-| Seçenek sayısı | Öğe                                             |
-| -------------- | ----------------------------------------------- |
-| ≤7             | `ChipGroup` — hepsi ekranda, tek dokunuş        |
-| 5–20           | `Select` — aramasız liste; mobilde alt sayfa    |
-| 20+            | `Combobox` — yazarak ara                        |
-| Aralık         | `RangeSlider` (+ kesin değer için sayı girdisi) |
-| Tekil aç/kapa  | `Checkbox`                                      |
+## Decisions the system carries
 
-Hepsini onay kutusu listesi yapmak tek tip ama kötü bir arayüzdür: 1121 markayı
-da 3 seçeneği de aynı biçimde göstermek, ikisini de yanlış gösterir.
+**Cobalt acts, coral converts, turquoise highlights.** Cobalt is the primary
+action, the link, the selection and the focus ring. Coral is the conversion
+button (`UIVariant.ACCENT` on `Button`, `variant="accent"` on `IconButton`) and
+appears nowhere else. Turquoise marks a highlight or a live state
+(`Badge tone="highlight"`, `Avatar tone="highlight"`); it is a fill, never body
+text.
+`colour-footprint.test.ts` turns a coral or turquoise token in any other
+component's stylesheet into a failing test.
 
----
+**One `PRIMARY` per screen.** `UIVariant` is a hierarchy of emphasis: two
+filled buttons side by side and neither stands out.
+
+**Status is a tint, an action is a fill or a border.** `Alert` and the soft
+`Badge` sit on tinted grounds; when that distinction blurs, users try to click
+status labels.
+
+**Colour never carries meaning alone** (WCAG 1.4.1). Every state is also told
+by a text, an icon or a mark: each `Alert` tone has its own icon, the required
+star of `Field` has a readable text next to it.
+
+**Icons come from `react-bootstrap-icons`, in the filled version.** A thin
+outline disappears on a tint at small sizes. Where no filled twin exists (`X`,
+`Check`, `Plus`, `Dash`) the heavy `*Lg` version is used, and `Caret*Fill`
+instead of a chevron. Content icons (a category mark, a logo) always come from
+outside as a `ReactNode` prop.
+
+**Icon size is separate from text size.** The scale is its own set of values
+(`$icon-xs` … `$icon-xl`: 14/16/18/20/24px); every box that carries an icon
+takes its size from there.
+
+**"Could not load" and "empty" are different states.** `DataTable` never draws
+the empty message while `error` is set.
+
+**A native element beats an imitation.** `<dialog>`, `<input type="range">`,
+`<input type="radio">` are kept. The one exception is `<select>`: its list
+cannot be styled and its mobile wheel looks like nothing else in the
+application.
 
-## Sistemin taşıdığı kararlar
-
-**Zemin mürekkep ve kâğıt, yeşil eylemdir.** Nötrler sıcak mürekkep ekseninde
-(açık sayfa `#faf9f5`, koyu sayfa `#141413`); markanın yeşili yalnızca birincil
-eylemde, bağlantıda, odak halkasında ve marka işaretinde. Seçim — etkin sayfa,
-seçili çip, sekme çizgisi, ilerleme, onay kutusu, anahtar — mürekkeptir.
-Yeşilin yayılmasını `green-footprint.test.ts` derleme hatasına çevirir.
-
-**Doygun dolgu = tıklanabilir.** Durum etiketleri **her zaman** tint zeminli
-(`Badge`, `Alert`), eylemler **her zaman** dolgulu veya çerçeveli. Bu ayrım
-bozulduğunda kullanıcı durum etiketine tıklamayı deniyor. `Badge`in `solid`
-varyantı durum tonlarında bilinçli olarak `soft` ile aynı şeyi verir.
-
-**Bir ekranda tek `PRIMARY`.** `UIVariant` bir vurgu hiyerarşisi: iki dolu düğme
-yan yana durduğunda hiçbiri öne çıkmaz. `UIVariant.CART` ekrandaki en parlak
-yeşil — dönüşüm eylemi; birincil eylemden (koyu çam) aydınlıkla ayrışır.
-
-**Renk tek başına anlam taşımaz** (WCAG 1.4.1). Her durum bir metin, ikon veya
-işaretle de bildirilir: `Alert`in her tonunun kendi ikonu var, `Field`in zorunlu
-yıldızının yanında okunabilir bir metin, `RatingInput`in yıldızlarının altında
-açıklama duruyor.
-
-**İkonlar `react-bootstrap-icons`ten, DOLU sürümüyle.** Kabuk simgeleri
-(`Modal`ın kapatma çarpısı, `Select`in oku, `Alert`in durum ikonu) bir zamanlar
-kütüphanenin içinde elle çizilmiş yollardı; bir ikon setinin bakımını üstlenmek
-hiçbir şey kazandırmıyordu — tüketici uygulamalar kendi içerik ikonlarını zaten
-aynı setten alıyor ve paket `external`, yani ikinci bir kopya inmiyor. Dolu
-(`*Fill`) sürüm kural: ince konturlu bir simge, tint zeminde ve küçük ölçüde
-tek piksele inip kayboluyor. Fill eşi olmayan simgelerde (`X`, `Check`, `Plus`,
-`Dash`) kalın `*Lg` sürümü kullanılır, chevron yerine dolu `Caret*Fill` —
-böylece bütün kabuk aynı çizgi ağırlığında kalır. İçerik ikonları (kategori
-simgesi, marka logosu) her zaman `ReactNode` prop'u olarak DIŞARIDAN gelir.
-
-**İkon ölçüsü metin puntosundan ayrıdır.** İkonlar `1em` ile ölçeklenir ama
-taşındıkları kutunun `font-size` değeri metin için seçilmiştir ve simge için
-küçük kalır: 40 px'lik bir `IconButton`ın ortasındaki 16 px'lik simge tıklanabilir
-görünmüyordu. Ölçek ayrı bir token dizisidir (`$icon-xs` … `$icon-xl`,
-14/16/18/20/24 px) ve ikon taşıyan her kutu puntosunu oradan alır.
-
-**"Yüklenemedi" ile "boş" ayrı durumlardır.** `DataTable`da `error` verilmişken
-boş mesajı **asla** çizilmez; bir ağ hatasını "kayıt kalmamış" diye okutmak
-kullanıcıya yanlış karar verdirir.
-
-**Yerel öğe, taklit öğeden iyidir.** `<dialog>`, `<input type="range">`,
-`<input type="radio">` korunur. Tek istisna `<select>`: açılır listesinin içine
-hiçbir biçimde girilemiyor ve mobil tekerleği uygulamanın geri kalanına hiç
-benzemiyor. Bedeli (odak yönetimi, ok tuşları, `aria-activedescendant`) bir kez
-ödenip tek bileşene kapatıldı.
-
-**Dokunma hedefi en az 44×44 px** (WCAG 2.5.8). Görsel kutu daha küçük olabilir;
-tıklanabilir alan görünmez bir örtüyle korunur.
-
-**Geçişler 200 ms'yi geçmez** — tek istisna dipten açılan panel
-(`duration-slow`, 320 ms) — ve `prefers-reduced-motion` her animasyonda
-karşılanır.
-
-**Odak halkası `:focus-visible` ile.** `:focus` fareyle tıklandığında da halka
-gösterip görsel gürültü yaratıyor ve kullanıcılar bunu hata sanıyordu.
+**A touch target is at least 44×44px** (WCAG 2.5.8). The visual box may be
+smaller; an invisible overlay keeps the area.
+
+**Motion uses the design durations** (`fast` 120ms, `base` 200ms, `slow`
+320ms for a sheet) and every animation honours `prefers-reduced-motion`.
+
+**The focus ring is `:focus-visible`**, 2px of cobalt with a 2px offset.
 
 ---
 
 ## Next.js App Router
 
-Paket `'use client'` sınırını **kendi içinde ve dosya başına** çizer (6.0):
-kanca kullanmayan bileşenler (`Button`, `Chip`, `Badge`, `Card`, `Panel`,
-`Tile`, `TextLink`, `Kbd`, `Alert`, `EmptyState`, `IconButton`, `Progress`,
-`Skeleton`, `StatusDot`, `SummaryCard`, `SectionHeader`, `PageHeader`,
-`Divider`) sunucu bileşeni olarak çizilir ve istemciye JS indirmez; etkileşimli
-olanlar kendi yönergesini taşır, `children` sunucuda çizilip aktarılır. İnce
-`Client*` sarmalayıcıları gerekmez; `UIVariant`/`UISize` sunucuda da içe
-aktarılır.
+The package draws the `'use client'` boundary **inside itself, per file**:
+components without hooks (`Alert`, `Badge`, `Button`, `Card`, `Chip`,
+`Divider`, `EmptyState`, `IconButton`, `Kbd`, `PageHeader`, `Panel`,
+`Progress`, `SectionHeader`, `Skeleton`, `StatusDot`, `SummaryCard`,
+`TextLink`, `Tile`) render as server components and send no JavaScript; the
+interactive ones carry their own directive. No thin `Client*` wrappers are
+needed, and `UIVariant` / `UISize` can be imported on the server.
 
 ```ts
-// next.config.ts — cephe saf olduğu için içe aktarım bileşen dosyasına kısa devre yapılır.
-experimental: { optimizePackageImports: ['@handijit/ui'] }
+// next.config.ts: the main entry is pure, so imports short-circuit to the component file.
+const nextConfig = {
+  experimental: { optimizePackageImports: ['@handijit/ui'] },
+};
 ```
 
 ```tsx
-// app/layout.tsx — sunucu bileşeni
+// app/layout.tsx, a server component
+import '@handijit/design/tokens.css';
+import '@handijit/design/fonts.css';
 import '@handijit/ui/styles.css';
-import '@handijit/ui/chat.css'; // yalnızca /chat kullanılıyorsa
-import '@handijit/ui/charts.css'; // yalnızca /charts kullanılıyorsa
+import '@handijit/ui/chat.css'; // only if /chat is used
+import '@handijit/ui/charts.css'; // only if /charts is used
 import { UiProvider, UiThemeScript } from '@handijit/ui';
 import NextLink from 'next/link';
 
@@ -497,7 +505,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="tr" suppressHydrationWarning>
       <head>
-        <UiThemeScript storageKey="theme" />
+        <UiThemeScript />
       </head>
       <body>
         <UiProvider linkComponent={NextLink}>{children}</UiProvider>
@@ -507,141 +515,28 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-`suppressHydrationWarning`: tema betiği `<html>`e sunucunun yazmadığı bir
-öznitelik ekliyor; uyarı yalnızca o öğe için susturulur.
-
----
+`suppressHydrationWarning`: the boot script adds an attribute to `<html>` that
+the server did not write; the warning is silenced for that element only.
 
-## Geliştirme
+## Electron
 
-```bash
-nvm use            # .nvmrc → 24
-npm install
-npm run verify     # tokens → kontrast → typecheck → lint → kapsam → build → API → animasyon → boyut
-npm run playground # bileşen galerisi → http://localhost:5273
-```
+The same three stylesheet imports in the renderer entry, and the boot script in
+the HTML shell. With the usual strict policy of a packaged program, allow the
+script by hash (`THEME_BOOT_SCRIPT_HASH`), and keep `style-src-attr
+'unsafe-inline'` for the positioned components. With a mouse or a trackpad
+`Select` and `Combobox` open dropdowns whatever the window width.
 
-| Komut                     |                                                                 |
-| ------------------------- | --------------------------------------------------------------- |
-| `npm run tokens`          | SCSS token dosyalarını `theme/tokens.ts`ten üretir              |
-| `npm run build`           | `build/` — ana giriş + `chat` + `charts` (ESM + CJS + `.d.ts` + CSS) ve `build/scss/` |
-| `npm run test`            | Jest + Testing Library + `jest-axe`                              |
-| `npm run test:coverage`   | kapsam kapısı — tüm `src/`: satır 89 · ifade 86 · fonksiyon 80 · dal 75 |
-| `npm run test:visual`     | görsel regresyon (Playwright); `verify` İÇİNDE DEĞİL, aşağı bkz. |
-| `npm run test:device`     | iOS (WebKit) + Android (Chromium) davranış nöbetçileri, aşağı bkz. |
-| `npm run check:contrast`  | WCAG kontrast ölçümü, iki temada 210 çift                        |
-| `npm run check:palette`   | palet tarifinin çıktısı mı + nötr chroma tavanı + tint ve kategori ayrışması |
-| `npm run check:api`       | genel API nöbetçisi — dört giriş, dört taban çizgisi (ana 176 · sohbet 30 · grafik 22 · SCSS 252 ad) |
-| `npm run size`            | paket boyutu bütçesi (`size-limit`)                              |
-| `npm run exports`         | `package.json` `exports` haritasını üretir (`check:exports` doğrular, `build`in son adımı) |
-| `npm run playground`      | bileşen galerisi (tema · RTL · yoğunluk anahtarı)                |
-| `npm run lint`            | ESLint (TS) + stylelint (SCSS)                                    |
-| `npm run typecheck`       | `tsc --noEmit`                                                   |
-
-### Nöbetçiler ne koruyor
-
-- **Eksen taraması** — dışa verilen her bileşen, her anlamlı durumunda
-  (`components/__tests__/a11y.test.tsx`). Deftere girmeyen yeni bir bileşen
-  testi kırar.
-- **Klavye sözleşmesi** — tuş matrisleri her bileşenin JSDoc'unda, nöbetçisi
-  `components/__tests__/keyboard.test.tsx`.
-- **Kontrast** — metin ≥ 4,5:1, ikon ve odak halkası ≥ 3:1. Eşiği tutmayan bir
-  token derlemeyi kırar; düzeltme daima `palette.ts` düzeyinde yapılır.
-- **Token sözleşmesi** — açık/koyu anahtar kümeleri ve üretilmiş SCSS kaynakla
-  eşleşir. Ayrışma bugüne kadar sessizdi.
-- **Paket boyutu** — tek bileşen import eden bir uygulamanın ne indirdiği
-  ölçülür. Ölçülen (2026-10-10, `size-limit`): `Badge` **4,33 kB** · `Button`
-  **5,12 kB** · `styles.css` **23,07 kB** · tüm paket **42,05 kB** gzip. Alt
-  girişler ana pakette SAYILMAZ: sohbet **6,32 kB**, grafikler **14,02 kB**
-  (yalnızca `LineChart` **7,19 kB**).
-  ⚠ **Bütçeler `.size-limit.js`te** (paket 43 kB, `styles.css` 24 kB) ve
-  başlıkta kalan pay dar. Bu satır bir dönem
-  `Badge 2,7 / Button 3,4 / paket 22,2` diyordu — ölçüm değil, bayat bir
-  kopyaydı ve okuyana **%70 boş alan** olduğunu düşündürüyordu. Yeni bir
-  bileşen eklerken bütçenin fiilen dolu olduğu bilinerek girilir; `size-limit`
-  kırmızıya döndüğünde doğru tepki limiti yükseltmek değil, ne eklendiğini
-  ölçmektir (`npm run size`).
-- **Genel API** — her girişin dışa aktarım kümesi kendi taban çizgisiyle
-  karşılaştırılır (`npm run check:api`): ana giriş `scripts/api-baseline.txt`
-  (176), `chat` (30), `charts` (22), `scss` (252 `$değişken` + `@mixin`). Düşen
-  bir ad **kırıcı**dır ve tüketiciler caret ile aldığı için bir sonraki
-  `npm install`da derleme hatası olarak çıkar. Bilinçli değişiklikte
-  `node scripts/check-api.mjs --update` + CLAUDE.md'ye gerekçe.
-- **Alt giriş sınırı** — `chat` ve `charts` ana girişi yalnızca PAKET ADIYLA
-  alır (`subentry-boundary.test.ts`); göreli bir yol `UiProvider` bağlamının
-  ve kipsel yüzey yığınının ikinci bir kopyasını paketlerdi.
-- **Yeşil ayak izi** — bileşen SCSS'inde yeşil token ailesine uzanan her
-  bileşen gerekçeli bir izin listesinde (`green-footprint.test.ts`).
-- **Opacity ile soluklaştırma yasak** — `0`/`1` dışındaki her `opacity`
-  derlemeyi kırar (`passive-opacity.test.ts`); pasiflik token'larla çizilir.
-- **iOS yakınlaştırması** — galerideki her metin girdisi dar ekranda ≥16px
-  (`e2e/mobile.spec.ts`, hesaplanmış stil).
-- **Odak halkası ve hareket ölçeği** — stylelint, `focus-ring` mixin'i dışında
-  `outline` ve bileşen SCSS'inde ham süre değeri (`0.7s`) yazılmasını
-  engelliyor. Üç bileşen kendi halkasını, iki bileşen kendi süresini
-  yazıyordu.
-
-### Cihaz nöbetçileri — `npm run test:device`
+---
 
-```bash
-npm run test:device:install   # WebKit + Chromium ikilileri (bir kez)
-npm run test:device           # ios (iPhone 14 · WebKit) + android (Pixel 7 · Chromium)
-```
+## Chat components: `@handijit/ui/chat`
 
-Bu depodaki en pahalı hatalar masaüstünde **görünmüyordu**: alt sayfanın gövdesi
-çöküyor, dip şerit klavyenin altında kalıyor, filtre seçenekleri maskenin
-altında siliniyordu. Üçü de yerleşim/boyama hatası ve üçü de yalnızca gerçek bir
-yerleşim motorunda ölçülebiliyor — jsdom bunları hiç hesaplamıyor.
-
-**İki motor, çünkü bir motor yetmiyor.** iOS'taki her tarayıcı (Chrome dahil)
-WebKit; Chromium'da doğru olan orada doğru olmak zorunda değil.
-
-**Ekran görüntüsü değil sayı.** Bu koşu piksel karşılaştırmaz — yükseklik,
-taşma, odak ve hesaplanmış CSS değeri ölçer. Yani platformdan bağımsız,
-referans dosyası yok, `--update-snapshots` gerektirmiyor ve `test:visual`in
-aksine **CI'da olduğu gibi koşabilir**.
-
-**Emülasyonun dürüst sınırı.** Playwright'ın WebKit'i iOS Safari değil; çentik
-payı (`env(safe-area-inset-*)` burada hep 0), ekran klavyesinin görünen alanı
-daraltması, adres çubuğunun kaybolup gelmesi ve momentum kaydırma
-yakalanmıyor. O sınırın altında kalanlar için savunma CSS'te taban değerlerde
-(bkz. `bottom-sheet` mixin'i) ve onların nöbetçisi `e2e/bottom-sheet.spec.ts`.
-
-**Görsel regresyon `verify` içinde değil**: ekran görüntüsü platforma bağlı
-(yazı tipi tarama, alt piksel yumuşatma) ve macOS'te üretilmiş bir referans
-ubuntu üzerinde koşan CI'da her dosyada kırmızı döner. Referanslar platform
-başına saklanıyor (`e2e/__screenshots__/{platform}/`); CI'da açılacağı gün doğru
-yol, Playwright'ın resmi konteynerinde koşup `linux` referanslarını orada
-üretmek.
-
-> ⚠ **Referansları yenilerken `--update-snapshots=all` yazın, çıplak
-> `--update-snapshots` DEĞİL.** Ölçüldü (palet değişikliği turunda): çıplak
-> bayrak yalnızca **eksik** referansı yazıyor; eşleşmeyeni ne yeniden üretiyor
-> ne de kırıyor — koşu `40 passed` diyor, dosyalar eski renkte kalıyor ve
-> ardından gelen doğrulama koşusu **eski referansı eski referansla**
-> karşılaştırdığı için yeşil dönüyor. Yani sessizce yanlış bir "temiz" alınıyor.
-> `=all` mod, pikseli değişen her dosyayı yazar (bayt bayt aynı olanlara
-> dokunmaz, o yüzden dosya sayısı toplamdan az çıkabilir). Doğrulama:
-> yenilemeden sonra bir referansın baskın renklerini örnekleyin.
-> ⚠ `=changed` de yetmez: yalnızca eşiği (`maxDiffPixelRatio: 0.002`) aşan
-> farkı yazar — iki küçük yazının kalktığı bir değişiklik eşiğin altında kalıp
-> eski referans dosyada durur. Küçük bir değişiklikte bölümün referansını silip
-> `=missing` ile yazdırın.
-
-`master`a her push `npm publish` çalıştırır — **`package.json` sürümünü
-yükseltmeyi unutmayın**, aynı sürüm ikinci kez yayımlanamaz ve iş akışı kırmızı
-döner.
-
-## Sohbet bileşenleri — `@handijit/ui/chat`
-
-Sohbet ve araç arayüzleri için ayrı bir giriş; ana paketi ve `styles.css`i
-büyütmez.
+A separate entry for chat and tool interfaces; it adds nothing to the main
+bundle or to `styles.css`.
 
 ```tsx
 import '@handijit/ui/styles.css';
-import '@handijit/ui/chat.css'; // styles.css'TEN SONRA
+import '@handijit/ui/chat.css'; // AFTER styles.css
 
-import { UiProvider } from '@handijit/ui';
 import { ChatMessage, ChatThread, PromptInput } from '@handijit/ui/chat';
 
 <ChatThread
@@ -665,7 +560,7 @@ import { ChatMessage, ChatThread, PromptInput } from '@handijit/ui/chat';
 </ChatThread>;
 ```
 
-Metinler aynı sağlayıcıdan, `labels.chat` altında:
+Labels come from the same provider, under `labels.chat`:
 
 ```tsx
 <UiProvider
@@ -688,58 +583,31 @@ Metinler aynı sağlayıcıdan, `labels.chat` altında:
 >
 ```
 
-`CodeBlock` kodu kendisi vurgular ve biçimlendirir — bağımlılık yok, renkler
-temayla döner:
+`CodeBlock` highlights and formats the code itself, with no dependency:
 
 ```tsx
 <CodeBlock language="json" code={JSON.stringify(payload)} />
 ```
 
-JSON iki boşlukla yeniden girintilenir (değerler metin olarak korunur: büyük
-sayılar yuvarlanmaz), kenardaki boş satırlar atılır; başka dilde girintiye
-dokunulmaz. 30'dan fazla dil tanınır (ts/tsx, json, bash, python, yaml, css,
-html, sql, diff, go, rust…), tanınmayan dil düz çizilir. Kopyala düğmesi ekranda
-görüneni kopyalar. Renkler `chat.css`teki `--ui-syntax-keyword`, `-string`,
-`-number`, `-name`, `-type` değişkenleridir; CSS'te ezilir. Shiki düzeyinde
-doğruluk isterseniz önceden vurgulanmış HTML'i `html` olarak verin (güvenliği
-sizin) — yerleşik vurgulayıcının yerine geçer.
-
-Markdown ayrıştırması tüketicide kalır: `Prose` yalnızca tipografi kabıdır.
-Bileşen listesi ve kararlar: `CLAUDE.md` → "`@handijit/ui/chat`".
-
-## SCSS API — `@handijit/ui/scss`
+JSON is re-indented with two spaces (values are kept as text: large numbers are
+not rounded) and blank lines at the edges are dropped; other languages keep
+their indentation. More than 30 languages are recognised; an unknown one is
+drawn plain. The token colours are design tokens (keyword `primary-text`,
+string `success-fg`, number `warning-fg`, type `highlight-text`), so they
+follow the theme and stay inside the measured text pairs. For Shiki-grade
+accuracy pass pre-highlighted HTML as `html` (its safety is yours).
 
-Token değişkenleri ve mixin'ler kopyalanmadan alınır. Değişkenler
-`var(--ui-…)` dizeleridir; tema çalışma zamanında döner. Modül kural basmaz;
-`:root` token kuralları `base.css`tedir (bileşen modülleri onu kendileri getirir).
+Markdown parsing stays in the application: `Prose` is a typography container
+only.
 
-```scss
-@use '@handijit/ui/scss' as ui;
-
-.panel {
-  padding: ui.$space-4;
-  border: 1px solid ui.$border;
-
-  @include ui.focus-ring;
+## Charts: `@handijit/ui/charts`
 
-  @media (max-width: ui.$breakpoint-tablet-portrait) {
-    padding: ui.$space-3;
-  }
-}
-```
-
-Next.js (Turbopack ve webpack) paket `exports`'unu çözer. Başka bir derleyici
-çözemezse yol `node_modules/@handijit/ui/build/scss` ile `loadPaths`e verilip
-`@use 'index' as @handijit/ui` yazılabilir.
-
-## Grafikler — `@handijit/ui/charts`
-
-On SVG grafiği, sıfır bağımlılık (çizim, ölçek ve istatistik kütüphanenin
-kendisinde). Ana paketi ve `styles.css`i büyütmez.
+Ten SVG charts with no dependency (drawing, scales and statistics live in the
+library).
 
 ```tsx
 import '@handijit/ui/styles.css';
-import '@handijit/ui/charts.css'; // styles.css'TEN SONRA
+import '@handijit/ui/charts.css'; // AFTER styles.css
 
 import { BarChart, LineChart, PieChart } from '@handijit/ui/charts';
 
@@ -749,7 +617,7 @@ import { BarChart, LineChart, PieChart } from '@handijit/ui/charts';
   xKey="month"
   data={[
     { month: 'Oca', revenue: 120, cost: 90 },
-    { month: 'Şub', revenue: 180, cost: null }, // null = veri yok: çizgi KESİLİR
+    { month: 'Şub', revenue: 180, cost: null }, // null = no data: the line BREAKS
   ]}
   series={[
     { key: 'revenue', label: 'Gelir' },
@@ -758,116 +626,162 @@ import { BarChart, LineChart, PieChart } from '@handijit/ui/charts';
 />;
 ```
 
-| Grafik | Ne zaman |
-|---|---|
-| `LineChart` · `AreaChart` | Zaman içinde eğilim; `AreaChart isStacked` toplamın parçaları |
-| `BarChart` | Kategorileri karşılaştırma; `orientation="horizontal"` uzun adlar için |
-| `ComposedChart` | Çubuk + çizgi; farklı birim `axis: 'right'` |
-| `PieChart` | Bir bütünün ≤6 parçası (`variant="donut"` varsayılan) |
-| `ScatterPlot` | İki değişkenin ilişkisi; `size` ile balon |
-| `Heatmap` | İki kategorik eksende yoğunluk (gün × saat) |
-| `BoxPlot` · `Histogram` | Dağılım: grupları karşılaştırma · tek değişkenin şekli |
-| `RadarChart` | Birkaç seriyi aynı eksen takımında; eksenler AYNI ölçekte |
-
-Her grafik tek bir sekme durağıdır: oklar öğeleri gezer (gelinen öğe
-duyurulur), `Home`/`End` uçlara gider, `Escape` vurguyu kaldırır. Ekran okuyucu
-grafiği gizli bir **veri tablosu** olarak da okur. Genişlik kapsayıcıdan ölçülür
-(`width` ile sabitlenebilir), yükseklik `height`. Sayılar `labels.locale`
-yereliyle biçimlenir; ipucu, duyuru ve tablo `formatValue` / `format` ile
-ezilir. Eksen bölmeleri bunu KULLANMAZ: kısa gösterimde ("12 B", "0,005") ve
-birimsiz kalır, basamak sayısı bölme adımından gelir. Renkler kategorik paletten
-(`tone`: `cat-1`…`cat-5`, `series-1`, `series-2`, `muted`).
-
-## 1.0'a geçiş — `@ahmetilhn/hanui` 5.x'ten
-
-1.0 iki şeyi birden getirir: **yeni ad** (`@ahmetilhn/hanui` → `@handijit/ui`; CSS öneki `hanui-` →
-`ui-`, token'lar `--hanui-*` → `--ui-*`, `@layer ui`, `data-ui-theme`, `UiProvider`/`useUi`/`initUi`;
-peer `@ahmetilhn/handy-utils` → `@handijit/utils`) ve 6.0 olarak hazırlanmış **paketleme** değişiklikleri.
-6.0 bir **paketleme** sürümü: bileşen API'si değişmedi, kırılan şey paketin
-dosya düzeni, `'use client'` sınırı ve CSS'in inişi. Tam liste `CHANGELOG.md`.
-
-| 5.x | 6.0 |
-|---|---|
-| `import '@handijit/ui/styles.css'` | ESM'de **silinir** — bileşen modülleri `base.css` + kendi `style.css`ini getirir; CJS/paketleyicisiz kullanımda kalır |
-| tek `build/index.js`, tamamı `'use client'` | `build/components/<Ad>/index.js`; 18 bileşen yönergesiz (sunucuda çizilir), alt yol `@handijit/ui/<kebab-ad>` |
-| `build/index.d.ts` toplanmış | dosya başına `.d.ts`; `import type` aynı |
-| `Combobox` tetikleyicisi `role="button"`, arama kutusu `role="combobox"` | tetikleyici `role="combobox"` (`aria-expanded`, `aria-controls`, `aria-invalid`, `aria-required`), arama kutusu metin kutusu |
-| bağlantı `Button` pasifken `preventDefault` işleyicisi | `aria-disabled` + `tabIndex=-1` + `pointer-events: none`; işlev prop'u yok (sunucudan çizilebilir) |
-| site ezmesi sınıf seçicisiyle | **bileşen değişkenleri** (aşağıda) |
-
-### Bileşen değişkenleri
-
-Token sözleşmesinin (`--ui-page`, `--ui-text`… 110 ad) dışında, tek bir
-bileşenin görünümünü tüketicinin `:root`ta ezdiği CSS özel özellikleri. Bileşen
-`var(--ui-…, varsayılan)` ile okur; yazılmazsa varsayılan geçerlidir.
-
-| Bileşen | Değişkenler |
-|---|---|
-| odak halkası | `--ui-ring-width` (2px) · `--ui-ring-offset` (2px; öğenin içine çekmek için `-2px`) |
-| girdiler | `--ui-placeholder` (`text-3`) |
-| kipsel perde | `--ui-scrim-blur` (3px) |
-| `Button` | `--ui-button-radius` · `-weight` · `-tracking` · `-wrap` (`nowrap`) |
-| `Chip` | `--ui-chip-bg` · `-line` · `-fg` · `-radius` · `-weight` · `-selected-bg` · `-selected-line` · `-selected-fg` · `-selected-weight` |
-| `Badge` | `--ui-badge-font` · `-weight` · `-tracking` · `-transform` · `-radius` (+ `-bg` · `-line` · `-fg`, 5.x) |
-| `Stat` | `--ui-stat-label-font/-size/-weight/-tracking/-transform` · `-value-font/-weight/-tracking` · `-unit-font/-size/-tracking/-transform` |
-| `Tabs` | `--ui-tab-weight` |
-| `RadioCard` | `--ui-radio-card-line` · `-radius` |
+| Chart                     | When                                                            |
+| ------------------------- | --------------------------------------------------------------- |
+| `LineChart` · `AreaChart` | a trend over time; `AreaChart isStacked` for parts of a total   |
+| `BarChart`                | comparing categories; `orientation="horizontal"` for long names |
+| `ComposedChart`           | bars and a line; a different unit on `axis: 'right'`            |
+| `PieChart`                | at most six parts of a whole (`variant="donut"` by default)     |
+| `ScatterPlot`             | the relation of two variables; a bubble with `size`             |
+| `Heatmap`                 | density on two categorical axes (day × hour)                    |
+| `BoxPlot` · `Histogram`   | distribution: comparing groups · the shape of one variable      |
+| `RadarChart`              | a few series on one set of axes, all on the SAME scale          |
+
+Every chart is a single tab stop: arrows walk the items (each is announced),
+`Home` / `End` go to the ends, `Escape` clears the highlight. A screen reader
+also reads the chart as a hidden **data table**. Width is measured from the
+container (or fixed with `width`); numbers are formatted with `labels.locale`.
+Colours come from the data series of the design (`tone`: `chart-1` … `chart-6`,
+`muted`).
+
+## SCSS API: `@handijit/ui/scss`
+
+Variables and mixins for the application's own stylesheets. The variables are
+`var(--hd-…)` references, so the theme turns at run time; the module emits no
+rules.
+
+```scss
+@use '@handijit/ui/scss' as ui;
 
-```css
-:root {
-  --ui-ring-offset: -2px;
-  --ui-button-weight: 500;
-  --ui-chip-radius: var(--ui-radius-pill);
-  --ui-badge-font: var(--ui-font-mono);
-  --ui-badge-transform: uppercase;
+.panel {
+  padding: ui.$space-4;
+  border: 1px solid ui.$border;
+  border-radius: ui.$radius-md;
+
+  @include ui.type(small);
+  @include ui.focus-ring;
+
+  @media (max-width: ui.$breakpoint-md) {
+    padding: ui.$space-3;
+  }
 }
 ```
 
-## 5.0'a geçiş
+**The values are custom properties, so SCSS arithmetic does not work.**
+`$space-8 - $space-2` compiles to `var(--a)-var(--b)` without an error and the
+browser drops the declaration. Write the calculation in `calc()`:
 
-5.0 bir **renk** sürümü: nötr eksen yeşilden sıcak mürekkebe geçti, yeşil
-yalnızca eylem, bağlantı ve odakta kaldı. Bileşen API'si değişmedi; kırılan şey
-token adları ve görünüm.
+```scss
+padding-inline-start: calc(#{ui.$space-8} - #{ui.$space-2});
+margin-inline: calc(-1 * #{ui.$space-2});
+```
+
+Sass colour functions do not work either; mix in CSS:
+`color-mix(in srgb, #{ui.$primary} 20%, transparent)`.
+
+Next.js (Turbopack and webpack) resolves the package `exports`. For a compiler
+that cannot, add `node_modules/@handijit/ui/build/scss` to `loadPaths` and
+write `@use 'index' as ui`. An application that needs only the tokens can use
+`@handijit/design/tokens.scss` directly.
+
+---
+
+## Development
+
+```bash
+nvm use            # .nvmrc → 24
+npm install
+npm run verify     # contrast → typecheck → lint → coverage → build → API → animations → size
+npm run playground # component gallery → http://localhost:5273
+```
 
-| 4.x token | 5.0 |
-|---|---|
-| `role`, `role-hover`, `role-active` | `selected`, `selected-hover`, `selected-active` (mürekkep) |
-| `on-role` | `on-selected` |
-| `role-tint` / `role-line` | `selected-tint` / `selected-line` |
-| `role-text` | `link` (+ `link-hover`) |
-| `shell*` | aynı ad, değer çamdan mürekkebe; yeni `on-shell`, `on-shell-2`, `on-shell-danger`, `shell-line` |
-| — | `cat-1…5`, `series-1/2` (kategorik palet) |
+| Command                  |                                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| `npm run build`          | `build/`: main entry, `chat`, `charts` (ESM + CJS + `.d.ts` + CSS) and `build/scss/`        |
+| `npm run test`           | Jest + Testing Library + `jest-axe`                                                         |
+| `npm run test:coverage`  | coverage gate over all of `src/`: lines 89 · statements 86 · functions 80 · branches 75     |
+| `npm run check:contrast` | WCAG contrast of the pairs the components draw, both themes (240 pairs)                     |
+| `npm run check:api`      | public API guard: four entries, four baselines (main 163 · chat 30 · charts 22 · SCSS 225)  |
+| `npm run size`           | bundle budget (`size-limit`)                                                                |
+| `npm run exports`        | writes the `exports` map of `package.json` (`check:exports` verifies; last step of `build`) |
+| `npm run lint`           | ESLint (TypeScript) + stylelint (SCSS)                                                      |
+| `npm run format:check`   | Prettier over `src`, `playground`, `__tests__`                                              |
+| `npm run typecheck`      | `tsc --noEmit`                                                                              |
+| `npm run test:visual`    | visual regression (Playwright); NOT part of `verify`, see below                             |
+| `npm run test:device`    | iOS (WebKit) and Android (Chromium) behaviour guards                                        |
+
+### What the guards protect
+
+- **Design contract** (`__tests__/styles/design-contract.test.ts`): every
+  `--hd-*` name in the compiled stylesheets, the SCSS aliases and the
+  TypeScript sources exists in the installed `@handijit/design`; breakpoints
+  and layers match it; no stylesheet declares an `--hd-*` property or carries
+  a literal colour.
+- **Colour footprint** (`colour-footprint.test.ts`): coral and turquoise tokens
+  are used only by the components on a justified allow-list.
+- **Contrast**: text ≥ 4.5:1, icons and the focus ring ≥ 3:1, measured on the
+  values of the installed design package for every pair a component draws.
+- **Accessibility scan** (`__tests__/components/a11y.test.tsx`): every exported
+  component in each meaningful state. A new component missing from the ledger
+  fails the test.
+- **Keyboard contract**: the key matrix is in each component's JSDoc; its guard
+  is `keyboard.test.tsx`.
+- **Control sizes** (`control-size.test.tsx`): `Input`, `DateField`,
+  `DateRange` and `Select` take their size from one mixin, and a text field
+  never drops below 16px on a narrow or touch screen.
+- **Public API**: the exports of each entry are compared with a baseline. A
+  dropped name is **breaking** and surfaces as a build error at the consumer's
+  next install. For a deliberate change: `npm run build`, then
+  `node scripts/check-api.mjs --update`, and a line in the CHANGELOG.
+- **Bundle size**: budgets in `.size-limit.js` (main entry 44 kB, `styles.css`
+  25 kB gzip). When `size-limit` turns red, measure what was added before
+  raising a limit.
+- **Sub-entry boundary**: `chat` and `charts` import the main entry by PACKAGE
+  NAME only (`subentry-boundary.test.ts`); a relative path would bundle a
+  second copy of the provider context and the modal stack.
+- **No fading with opacity**: any `opacity` other than `0` / `1` fails
+  (`passive-opacity.test.ts`); a disabled state is drawn with tokens.
+- **Focus ring and motion scale**: stylelint rejects `outline` outside the
+  `focus-ring` mixin and raw durations in component SCSS.
+
+### Device guards: `npm run test:device`
+
+```bash
+npm run test:device:install   # WebKit and Chromium binaries (once)
+npm run test:device           # ios (iPhone 14 · WebKit) + android (Pixel 7 · Chromium)
+```
 
-Eski adlara takma ad **yok**. Kendi CSS'inizde `--ui-role*` okuyan ya da
-`theme={{ light: { role: … } }}` ezmesi yazan yerler yeni adlara geçer.
-Görünüm değişiklikleri: açık sayfa krem (`#faf9f5`), koyu sayfa sıcak siyah
-(`#141413`), kart ve panel durgunken gölgesiz, `info` tonu nötr, `CodeBadge`
-mürekkep. Ayrıntı ve ölçümler: `CLAUDE.md` → "Renk kararları (5.0)".
+The most expensive bugs of this repository were invisible on a desktop: a
+collapsed sheet body, a bottom bar under the keyboard. They are layout and
+paint bugs and can only be measured in a real layout engine. This run compares
+numbers (height, overflow, focus, computed style), not pixels, so it needs no
+reference files.
 
-## 5.1 – 5.6'da eklenenler
+**Visual regression is not part of `verify`**: screenshots depend on the
+platform (font rasterisation), and a reference made on macOS fails on the
+ubuntu CI runner. References are stored per platform under
+`__tests__/e2e/__screenshots__/{platform}/`.
 
-Hepsi ekleme; 5.0'ın token sözleşmesi dışında kırıcı değişiklik yok.
+> When refreshing references write `--update-snapshots=all`, not the bare
+> flag: the bare flag writes only **missing** files and leaves mismatching ones
+> in place while the run reports success.
 
-| Sürüm | Ne |
-|---|---|
-| 5.1 | `Disclosure`, `StatusDot`, `Kbd`; `useUiTokens`, `useStickToBottom`, `hasOpenSurface`; `Modal size="xl"`, `Button size={UISize.XSMALL}` + `shape="pill"`, `IconButton shape="round"`, `Textarea variant="bare"`, `Progress size="xs"`, etkileşimli `CodeBadge`, `Avatar` (`icon`, `shape="rounded"`, `tone="brand"`), `Stat variant="inline"`, `ScrollArea isFollowingEnd`; `CommandPalette` `hotkey` + komut kapanıştan SONRA çalışır |
-| 5.2 | `UiThemeScript`; `@handijit/ui/chat` — 20 sohbet bileşeni |
-| 5.3 | `@handijit/ui/charts` — 10 SVG grafiği; `@handijit/ui/scss`; `Input --technical` dar ekranda ≥16px; `QuantityStepper` ve `DataTable` pasif/dinlenme hâli opacity yerine token |
-| 5.3.2 | Düzeltme: kaydırma kapları kapsayıcı blok (`ChatThread`, `ScrollArea`, `TerminalOutput`, `ActionList` ve 12 kab daha) — görsel olarak gizli metin kabın dışına taşıp atalarını kaydırılabilir yapmıyor; grafik ekseni 0,1'in altındaki adımda sıfıra çökmüyor |
-| 5.4 | `CodeBlock` yerleşik vurgulayıcı ve biçimlendirici (bağımlılıksız, 30+ dil); sözdizimi renkleri `--ui-syntax-*` (yalnızca `chat.css`) |
-| 5.5 | `Input`, `DateField`, `DateRange` `size="sm"` (36px — `Select sm` ve `Button` SMALL ile tek hiza); SCSS `input-sm` mixin'i; yerel sayısal `size` niteliği bu üç girdinin tipinden çıktı |
-| 5.6 | `ContextMenu` — imleç noktasında açılan menü (sağ tık), `role="menu"` dışında başlık; `Menu` ile ortak yüzey; `usePositioning` öğesiz (nokta) çapayı da ölçer; düzeltme: `Menu` açılışta odağı gerçekten ilk öğeye taşır (gerçek tarayıcıda `<body>`de kalıyordu) |
+### Releasing
 
-Ayrıntı ve ölçülmüş gerekçeler: `CLAUDE.md` → "Göç ve `@deprecated` yollar",
-"`@handijit/ui/chat`", "`@handijit/ui/charts`".
+Every push to `master` runs `.github/workflows/publish.yml`: it checks the formatting,
+runs `npm run verify`, and publishes with the `NPM_ACCESS_TOKEN` repository
+secret and npm provenance **when `package.json` carries a version that is not
+on npm yet**; otherwise it skips. A published version gets a `vX.Y.Z` tag and a
+GitHub Release whose notes are that version's section of `CHANGELOG.md`, so the
+section must exist before the push.
 
-## Tasarım sözleşmesi
+## Design contract
 
-Öğe seçimi (hangi durumda hangi bileşen), yüzey/yükseklik merdiveni, renk
-kararları, durum tintleri, tipografi rolleri, erişilebilirlik eşikleri, hareket
-ölçeği ve `@deprecated` göç yolları **`CLAUDE.md`** içindedir. O dosya
-kütüphaneyi kullanan uygulamalar için de normatiftir.
+Which element to use when, the surface ladder, colour roles, typography roles,
+accessibility thresholds and the motion scale are in **`CLAUDE.md`**. That file
+is normative for applications that use the library too. The visual language
+itself (palette, type, logo) belongs to `@handijit/design`.
 
-## Lisans
+## License
 
 MIT