add(docs): contributor naming conventions doc (#1931)

Author: kotAPI

docs/app/docs/contributing/before-you-start/content.mdx

@@ -17,4 +17,5 @@ Before submitting your first contribution, we recommend:
 
 - Exploring our components in the [Playground](https://radui.dev/playground)
 - Reading through our component documentation
+- Reading the [naming conventions](/docs/contributing/naming-conventions) before adding new files or folders
 - Setting up a local development environment

docs/app/docs/contributing/naming-conventions/content.mdx

@@ -0,0 +1,97 @@
+# Naming conventions
+
+This page documents the naming patterns already used across the Rad UI repo.
+
+Use these conventions for new work unless you are extending an older area that already has a different local pattern. In that case, prefer consistency inside that component or package over doing a partial rename in an unrelated PR.
+
+## General rules
+
+- Prefer descriptive names over short names.
+- Use `PascalCase` for component folders, component files, context files, providers, and exported React types.
+- Use `camelCase` for hooks, helper functions, and utility folders that are not React components.
+- Use `kebab-case` for docs route folders under `docs/app/docs`.
+- Keep related files together inside the component or primitive folder instead of scattering them across the repo.
+
+## UI component folders
+
+Most components under `src/components/ui` follow this shape:
+
+```text
+src/components/ui/Accordion/
+  Accordion.tsx
+  contexts/
+  fragments/
+  stories/
+  tests/
+```
+
+Follow these naming rules for new UI components:
+
+- Name the folder after the exported component: `Accordion`, `Combobox`, `NumberField`.
+- Name the top-level entry file after the component: `Accordion.tsx`, `Combobox.tsx`, `NumberField.tsx`.
+- Put compound parts in `fragments/` with names like `AccordionRoot.tsx`, `AccordionItem.tsx`, `AccordionTrigger.tsx`.
+- Put tests in `tests/` and stories in `stories/`.
+- Use lowercase stylesheet filenames when they represent style packages, for example `accordion.clarity.scss` and `accordion.baremetal.scss`.
+
+## Contexts, providers, and hooks
+
+Context-related files should make their role obvious from the filename.
+
+- Use `*Context.tsx` for React context modules, for example `AccordionContext.tsx` or `NumberFieldContext.tsx`.
+- Use more specific names when there is more than one context, for example `AccordionItemContext.tsx` or `ComboboxRootContext.tsx`.
+- Use `*Provider` in the symbol name when a standalone provider component exists.
+- Use `use*` for hooks, for example `useComponentClass.ts` or `useControllableState/index.tsx`.
+
+For new work, prefer a `contexts/` directory name. The repo still has older `context/` folders, so do not rename those as drive-by cleanup in an unrelated issue.
+
+## Primitives vs UI components
+
+The repo distinguishes between headless primitives in `src/core/primitives` and composed components in `src/components/ui`.
+
+- Primitive folders still use `PascalCase`: `Button`, `Dialog`, `Combobox`.
+- Primitive implementation files may be explicit, such as `ComboboxPrimitive.tsx`, or use `index.tsx` in older folders.
+- UI component entry files should stay explicit: `Button.tsx`, `Dialog.tsx`, `Theme.tsx`.
+- When naming primitive parts, keep the `Primitive` suffix in the symbol or file when it clarifies the layer, such as `ButtonPrimitive`, `ComboboxPrimitiveRoot`, or `MenuPrimitive.tsx`.
+
+For new files, prefer explicit filenames when the file represents a concrete exported component or context. Keep `index.ts` or `index.tsx` for small entrypoints and for folders that already use that pattern.
+
+## Tests and stories
+
+Use the component or primitive name as the base filename.
+
+- Stories: `Accordion.stories.tsx`, `Badge.stories.tsx`
+- Visual-story variants: `AccordionItemVisualTests.stories.tsx`
+- Main test file: `Accordion.test.tsx`
+- Focused test files: `Accordion.a11y.test.tsx`, `Accordion.focus.test.tsx`, `Combobox.full.test.tsx`, `Combobox.simple.test.tsx`
+
+When adding a specialized test, keep the qualifier before `.test.tsx`. That keeps related files grouped together in editors and search.
+
+## Docs and examples
+
+Docs pages under `docs/app/docs` use route-oriented naming.
+
+- Route folders use `kebab-case`, for example `before-you-start`, `setting-up-dev-environment`, `radio-group`.
+- A docs page folder usually contains `page.tsx`, `seo.ts`, and `content.mdx`.
+- Supporting docs assets usually live in a local `docs/` folder with descriptive names such as `anatomy.tsx`, `component_api/root.tsx`, `codeUsage.js`, or `example_1.tsx`.
+- Standalone example components use `PascalCase`, for example `AvatarExample.tsx` or `SwitchExample.tsx`.
+
+## When to keep the local pattern
+
+Some areas are not perfectly uniform yet. Follow these rules when the repo already differs:
+
+- Match the surrounding folder if you are making a small change inside an existing component.
+- Prefer the newer convention only when creating a new area or when a full rename is already in scope.
+- Do not mix `context/` and `contexts/` inside the same component folder.
+- Do not introduce a second naming style for the same kind of file in the same directory.
+
+## Quick reference
+
+- UI component folder: `PascalCase`
+- UI component entry file: `PascalCase.tsx`
+- Fragment file: `PascalCasePart.tsx`
+- Context file: `PascalCaseContext.tsx`
+- Hook file: `useSomething.ts`
+- Stories file: `PascalCase.stories.tsx`
+- Test file: `PascalCase.test.tsx`
+- Docs route folder: `kebab-case`
+- Docs page support files: descriptive names, usually `page.tsx`, `seo.ts`, `content.mdx`

docs/app/docs/contributing/naming-conventions/page.tsx

@@ -0,0 +1,7 @@
+import { createDocsPage } from '@/components/docsPage/createDocsPage'
+import metadata from './seo'
+import Content from './content.mdx'
+
+export { metadata }
+
+export default createDocsPage(Content)

docs/app/docs/contributing/naming-conventions/seo.ts

@@ -0,0 +1,8 @@
+import generateSeoMetadata from '@/utils/seo/generateSeoMetadata'
+
+const namingConventionsMetadata = generateSeoMetadata({
+  title: 'Naming conventions | Rad UI',
+  description: 'Contributor naming rules for folders, files, contexts, hooks, tests, stories, and docs routes.'
+})
+
+export default namingConventionsMetadata

docs/app/docs/docsNavigationSections.tsx

@@ -131,6 +131,10 @@ export const docsNavigationSections = [
                 title:"Contributing to Rad UI",
                 path:"/docs/contributing/contributing-to-rad-ui"
             },
+            {
+                title:"Naming Conventions",
+                path:"/docs/contributing/naming-conventions"
+            },
             {
                 title:"Security & Dependency SLA",
                 path:"/docs/contributing/security-dependency-sla"