Dokümantasyon

İlk bileşen ekrana gelmeden önce bilmeniz gerekenler: özel bir paket nasıl kurulur, provider neyin sahibidir ve uygulamanızda değil kütüphane katmanında karara bağlanan üç davranış.

Kurulum

Paket özel bir npm kapsamında durur, bu yüzden npm’in onu görebilmesi için salt okunur bir token gerekir. Token’ı ‎.npmrc‎ dosyasına koyun — hem yerelde hem CI’da — sonrası sıradan bir kurulum. React 18 ve 19 desteklenir; ikon seti peer dependency’dir, sürümünü uygulamanız belirler.

# .npmrc — locally and in CI
@nili:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NILI_TOKEN}

npm i @nili/ui @remixicon/react

Provider

NiliProvider yalnızca iki genel kararın sahibidir: hangi tema boyanır ve sayfa hangi yönde okunur. Çeviriyi bilinçli olarak sahiplenmez — bileşenler metinlerini prop olarak alır, böylece kütüphane i18n çalışma zamanı olmadan yayımlanır ve i18next, react-intl, Next.js yönlendirmesi ya da hiçbirini kullanmakta özgür kalırsınız.

import { NiliProvider } from '@nili/ui';
import '@nili/ui/styles.css';

export default function App({ children }) {
  return (
    <NiliProvider locale="fa" defaultTheme="system">
      {children}
    </NiliProvider>
  );
}

Yön

Bir yön prop’u yoktur ve render sırasında hiçbir yerde document.dir okunmaz. Bileşenler mantıksal özelliklerle yazılır, yani yön CSS’ten miras alınır — sağdan sola bir alt ağacın soldan sağa bir sayfa içinde çalışmasının ve sunucu render’ının daha ilk geçişte doğru işaretlemeyi üretmesinin sebebi budur.

// Every component is written this way — logical, not physical.
<div className="ms-4 ps-2 border-s">…</div>

// So a right-to-left island inside a left-to-right page just works,
// with no prop threaded down to make it happen.
<section dir="rtl" lang="fa">
  <Button endIcon={<RiArrowRightLine />}>ادامه</Button>
</section>

Rakamlar

Rakamlar, ASCII kod noktalarının üzerine yerel şekiller bindiren bir fontla değil, değer katmanında Intl üzerinden biçimlendirilir. Sayfa içi arama, kopyala-yapıştır ve ekran okuyucunun ekranla aynı şeyi söylemesini sağlayan da, IBAN veya sipariş numarası gibi Latin kalması gereken değerlere bir çıkış bırakan da bu ayrımdır.

import { formatNumber, parseLocalizedNumber } from '@nili/ui';

formatNumber(1234567, { locale: 'fa-IR' });  // ۱٬۲۳۴٬۵۶۷
formatNumber(1234567, { locale: 'ar-EG' });  // ١٬٢٣٤٬٥٦٧
parseLocalizedNumber('۱٬۲۳۴٬۵۶۷');           // 1234567

// And the escape hatch, for a value that must stay Latin:
<TextInput label="IBAN" latin defaultValue="IR82 0540 …" />

Token ve tema

Bileşenler asla bir dark: varyantı yazmaz. Her biri tek bir anlamsal token çağırır ve değer, bir sınıfa değil data-theme niteliğine bağlı olarak altından değişir. Nitelik açık uçludur; yeni bir tema — yüksek kontrast, bir müşteri markası — yeniden yazım değil, tek bir stil dosyasıdır.

--nili-blue-500: #335CFF;        /* primitive  */
--nili-primary-base: …;          /* semantic   */
--color-primary-base: …;         /* @theme     */
class="bg-primary-base"          /* component  */

/* Dark mode is an attribute, not a class — so a third theme
   is [data-theme='high-contrast'] and nothing else changes. */
<html data-theme="dark">

Erişilebilirlik

Görünür bir etiketi olmayan her şey, isimsiz bir kontrolü kabul etmek yerine tiplerinde bir etiket ister — yalnızca ikondan oluşan bir düğme aria-label, kapatma düğmesi dismissLabel gerektirir. Kural şu: etiketsiz kontrolü bir inceleme yorumu değil, tip sistemi yakalar.

// The type system refuses an unlabelled control.
<Button iconOnly aria-label="Close" startIcon={<RiCloseLine />} />
<Tag onDismiss={remove} dismissLabel="Remove tag">Design</Tag>
<Alert title="Saved" urgency="polite" />

Sonra bileşenlere göz atın — her biri Storybook’un gösterdiği genel görünümle açılır, kaynağı da yanındadır. Bileşenler