Naming

Components

• Use the established industry name: Button, Select, Dialog, DataTable, EmptyState, Toast. Code names are not translated and are written in PascalCase.
• The Turkish page title and description say what the component does (“Tarih seçici”); the code name may stay in English in the title.
• One concept has one name. A second component that does the same job is not created; the difference is a variant.
• Name collision gate (REUSE-01): a name is rejected when, with the affixes Input, Field, Box, Wrapper, Container, letter case and digits removed, it equals the root of an existing component.
• Banned affixes: New, Old, Alt, Custom, Special, Temp, Copy, version suffixes such as V2, trailing digits and brand names. Titles and navigation labels do not use Smart-, Magic-, Ultimate-, Next-gen, Akıllı-, Sihirli-, Süper- (WR-30).
• A specialised field imports the base field and its name says what the base is: AmountInput, PhoneInput, OtpInput (REUSE-02).

Files and folders

Item	Form	Example
Component folder	kebab-case	packages/ui/src/components/icon-button/
Component file	PascalCase	IconButton.tsx, IconButton.stories.tsx
Docs example	kebab-case, in a language folder	apps/docs/src/examples/icon-button/en/sizes.tsx
Docs page	same as the component id	components/icon-button/usage.mdx
Changeset	kebab-case, describing the change	.changeset/icon-button-required-label.md

Props

Rule	Example
Visual weight variant, meaning colour tone, size size	variant="secondary" tone="danger" size="sm"
Size names xs, sm, md, lg, xl; default md	size="md"
States as adjectives, without an is prefix	disabled, invalid, required, loading, readOnly
Controlled value value + onValueChange, uncontrolled defaultValue	onValueChange={(value) => …}
For things that open and close, open + onOpenChange, defaultOpen	open={open}
Accessible name label, also when the name is not visible	label="Close"
A prop that overrides a library string is <state>Label	loadingLabel, successLabel
Icon slots startIcon, endIcon; free content startContent, endContent	startIcon={<Icon name="plus" />}

Direction names use start and end instead of left and right; components mirror in right-to-left text.

Parts and attributes

• The root element carries data-component="<component-id>": data-component="icon-button".
• Inner parts are named with data-part, in kebab-case: data-part="header", data-part="footer".
• States are shown with Base UI’s data-* attributes (data-disabled, data-open); before adding a new state attribute, look for its Base UI counterpart.

Tokens

Layer	Form	Example
Primitive	<family>-<step>	blue-600; source only, not in the build
Semantic	color-<role>-<name>-<state>	--bigbang-color-surface-hovered, --bigbang-color-text-link-hovered
Foundation	<group>-<name>	--bigbang-space-md, --bigbang-radius-sm, --bigbang-duration-fast
Component	<component>-<property>-<variant>	--bigbang-button-height-md, --bigbang-button-padding-inline-sm

Component tokens bind only to semantic tokens. No token name contains a brand name.

Icons

Icon names are BigBang names, not the set’s own names; they are kebab-case and stay the same when the set changes: chevron-down, circle-check, trash. Brand names and affixes such as new-, final-, v2 are not used (ASSET-13). Registered names are listed in the Icon gallery.

Stories and pages

• Story titles are Components/<Name>, or Layout/<Name> for layout components. The story id comes from it and is fixed: components-button--playground. Docs pages embed stories by this id; if the id changes, the docs check stops.
• Page addresses are the same in both languages, in English ASCII: /components/icon-button/, /en/components/icon-button/.
• Titles are in sentence case, at most 60 characters; navigation labels are noun phrases of at most three words.