Component Anatomy

Component & file anatomy

Naming and layout conventions for everything under libs/*. Each responsibility gets its own file. Barrels (index.ts) exist to expose a public API and to re-export several modules from one entry — not on every folder. Which files a component needs depends on the lib — see the table below and the Libraries map in AGENTS.md.

Naming

• Components live in a PascalCase folder, one file per responsibility.
• Utilities & hooks live in a camelCase folder, split by responsibility.
• Everything that is not a component is camelCase.

One responsibility per file

Split implementation, types, tests, stories, docs and Code Connect into separate files rather than one large module. This keeps diffs small and lets each skill (component-styling, component-testing, component-stories, component-mdx, code-connect) attach to the file it owns.

Barrel & re-export

A barrel is an index.ts that export * / export type * a folder's public API. Use one when consumers should import the folder, not a specific file:

• Package / layer barrels (Components/index.ts, core/index.ts) — the published surface.
• Component folders (Button/, TextInput/, BaseInput/) — several files (impl, types, sub-parts); the barrel is the import target. Import from that barrel, never from .../Button/Button.
• A new public component must also be re-exported from its parent Components barrel so it ships from the package root.

Do not add a barrel for every folder. Skip index.ts when the folder is an internal helper with a single implementation file (plus tests). Import the file directly (useMyHook/useMyHook is the pattern; useMyHook/index.ts is the anti-pattern to avoid repeating). A one-file folder does not need a barrel just to re-export that file.

Component folder layout

ComponentName/
├── ComponentName.tsx          # implementation
├── types.ts                   # prop types with JSDoc
├── ComponentName.test.tsx     # tests
├── ComponentName.stories.tsx  # Storybook stories
├── ComponentName.mdx          # Storybook docs
├── ComponentName.figma.tsx    # Figma Code Connect
└── index.ts                   # barrel exposing the public API

Utility / hook folder layout

useControllableState/             # public util — barrel so consumers import the folder
├── useControllableState.ts
├── useControllableState.test.ts
└── index.ts

useBaseInputValue/                # internal helper, one impl file — no barrel
├── useBaseInputValue.ts
└── useBaseInputValue.test.ts

Required files per lib

Not every lib ships the full set. A component addition is complete when it has the files marked required for its lib — do not add (or flag as missing) files a lib does not use.

Charts live at Components/visualization/ inside ui-react and ui-rnative, exposed only at the /visualization subpath. They follow their lib's row above, with two exceptions: some web stories sit in __stories__/ rather than co-located, and there is no .figma.tsx or .mdx coverage on the React Native side.

Notes:

• Stories naming — Base (not Default/Primary), {Property}Showcase, With{Feature}; see component-stories. In ui-rnative the Base render is usually explicit (render: (args) => <Component {...args} />).
• Docs — the two-tab Overview / Implementation structure lives in component-mdx.
• Disabled state — any component with a disabled state must consume the shared disabled context; see disabled-context.

Review checks

Rules verifiable from a diff. Everything above is authoring guidance.