Adlandırma

Bileşenler

• Sektörde yerleşmiş adı kullanın: Button, Select, Dialog, DataTable, EmptyState, Toast. Kod adları çevrilmez ve PascalCase yazılır.
• Türkçe sayfa başlığı ve açıklama, adın ne yaptığını anlatır (“Tarih seçici”); kod adı başlıkta İngilizce kalabilir.
• Bir kavramın tek bir adı vardır. Aynı işi gören ikinci bir bileşen açılmaz; fark bir varyanttır.
• Ad çakışma kapısı (REUSE-01): Ad Input, Field, Box, Wrapper, Container ekleri, büyük-küçük harf ve rakamlar atıldığında var olan bir bileşenin köküyle aynıysa reddedilir.
• Yasak ekler: New, Old, Alt, Custom, Special, Temp, Copy, V2 gibi sürüm ekleri, sonda rakam ve marka adları. Başlık ve gezinme etiketlerinde Smart-, Magic-, Ultimate-, Next-gen, Akıllı-, Sihirli-, Süper- kullanılmaz (WR-30).
• Özel bir alan temel alanı içe aktarır ve adı temeli anlatır: AmountInput, PhoneInput, OtpInput (REUSE-02).

Dosya ve klasörler

Öğe	Biçim	Örnek
Bileşen klasörü	kebab-case	packages/ui/src/components/icon-button/
Bileşen dosyası	PascalCase	IconButton.tsx, IconButton.stories.tsx
Doküman örneği	kebab-case, dil klasöründe	apps/docs/src/examples/icon-button/tr/sizes.tsx
Doküman sayfası	bileşen kimliğiyle aynı	components/icon-button/usage.mdx
Değişiklik kaydı	kebab-case, değişikliği anlatır	.changeset/icon-button-required-label.md

Özellikler

Kural	Örnek
Görsel ağırlık variant, anlam rengi tone, ölçü size	variant="secondary" tone="danger" size="sm"
Boyut adları xs, sm, md, lg, xl; varsayılan md	size="md"
Durumlar is öneki olmadan sıfatla	disabled, invalid, required, loading, readOnly
Denetimli değer value + onValueChange, denetimsiz defaultValue	onValueChange={(value) => …}
Açılıp kapanan için open + onOpenChange, defaultOpen	open={open}
Erişilebilir ad label; görünmesi gerekmeyen ad için de aynı ad	label="Kapat"
Kütüphane metnini ezen özellik <durum>Label	loadingLabel, successLabel
İkon yuvaları startIcon, endIcon; serbest içerik startContent, endContent	startIcon={<Icon name="plus" />}

Yön bildiren adlar left ve right yerine start ve end kullanır; bileşenler sağdan sola metinde aynalanır.

Parçalar ve öznitelikler

• Kök öğe data-component="<bileşen-kimliği>" taşır: data-component="icon-button".
• İç parçalar data-part ile adlanır, kebab-case: data-part="header", data-part="footer".
• Durumlar Base UI’nin data-* öznitelikleriyle (data-disabled, data-open) gösterilir; yeni bir durum özniteliği eklenmeden önce Base UI’de karşılığı aranır.

Token’lar

Katman	Biçim	Örnek
Ham değer	<aile>-<basamak>	blue-600; yalnızca kaynakta, derlemeye girmez
Anlam	color-<rol>-<ad>-<durum>	--bigbang-color-surface-hovered, --bigbang-color-text-link-hovered
Temel	<grup>-<ad>	--bigbang-space-md, --bigbang-radius-sm, --bigbang-duration-fast
Bileşen	<bileşen>-<özellik>-<varyant>	--bigbang-button-height-md, --bigbang-button-padding-inline-sm

Bileşen token’ları yalnızca anlam token’larına bağlanır. Marka adı hiçbir token adında geçmez.

İkonlar

İkon adları BigBang adlarıdır, setin kendi adı değildir; kebab-case yazılır ve set değişse de aynı kalır: chevron-down, circle-check, trash. Marka adları ve new-, final-, v2 gibi ekler kullanılmaz (ASSET-13). Kayıttaki adlar İkon galerisinde listelenir.

Hikâyeler ve sayfalar

• Hikâye başlığı Components/<Ad> ya da düzen bileşenleri için Layout/<Ad> biçimindedir. Hikâye kimliği bundan üretilir ve sabittir: components-button--playground. Doküman sayfaları bu kimlikle hikâye gömer; kimlik değişirse doküman denetimi durur.
• Sayfa adresleri iki dilde aynı, İngilizce ve ASCII’dir: /components/icon-button/, /en/components/icon-button/.
• Başlıklar cümle düzeninde yazılır, en fazla 60 karakterdir; gezinme etiketleri en fazla üç kelimelik ad öbeğidir.