LedgerHQ/lumen / .claude/skills/component-anatomy
component-anatomy
VerifiedUse when creating, naming, or placing a file or folder in libs/*, or when modifying or adding a file to an existing component (even when the barrel isn't touched) — component vs utility naming, the one-responsibility-per-file layout, when a folder needs an `index.ts` barrel (public API only), and the required set of files a component needs per lib. Load this before scaffolding or restructuring a component so the layout matches the codebase.
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
Componentsbarrel 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.
| Lib | impl .tsx | types.ts | .test.tsx | stories | .mdx | .figma.tsx |
|---|---|---|---|---|---|---|
ui-react | required | required | required | co-located .stories.tsx | required | if in Figma |
ui-rnative | required | required | required | co-located .stories.tsx (id prefix rnative-*) | required | if in Figma |
design-core | n/a (tokens, no components) | — | — | — | — | — |
utils-shared | camelCase util files | co-located or inline | required | — | — | — |
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(notDefault/Primary),{Property}Showcase,With{Feature}; seecomponent-stories. Inui-rnativetheBaserender is usually explicit (render: (args) => <Component {...args} />). - Docs — the two-tab Overview / Implementation structure lives in
component-mdx. - Disabled state — any component with a
disabledstate must consume the shared disabled context; seedisabled-context.
Review checks
Rules verifiable from a diff. Everything above is authoring guidance.
| Check | Applies to | Detect | Skip |
|---|---|---|---|
| Component folder/file not PascalCase, or utility not camelCase | all libs | folder/file casing vs kind | — |
Missing index.ts on a public component / package / layer folder | all libs | new public component folder with no barrel | internal helper folder (single impl + tests) |
| Barrel on a single-file internal folder | all libs | new index.ts that only re-exports one sibling file | public component folders; folders that re-export several modules |
| Import from a deep path instead of a public component barrel | all libs | from '.../Button/Button' when Button/index.ts exists | internal helpers that have no barrel |
New component not re-exported from the parent Components barrel | ui-react, ui-rnative | parent index.ts unchanged | — |
| More than one responsibility in a file (impl + types + stories in one file) | all libs | stories/types/tests inlined in the impl file | — |
| Required file missing for the lib (see table) | per lib | absent .test.tsx / .mdx / .figma.tsx where required | files a lib does not use (e.g. .figma.tsx under Components/visualization/) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |