Component Structure

Naming

The component must be named using the PascalCase convention.


Structure

Component folder structure

Each component should adhere to the following folder file structure:

Copy

Notes:

  1. Components can be generated using the pnpm generate-component script (see page Creating Component for more details).
  2. Each public component should be housed in its own folder in the src directory.
  3. The component folder must include:
    • A main component file (Button.tsx)
    • A types file (Button.types.ts)
    • A meta file (Button.meta.tsx) for automatic TestKit, SSR, and accessibility testing
    • An index.ts file
    • A docs folder with the component's Storybook examples
  4. Test files should be organized in a test folder inside the component directory. Private UniDrivers, if required, should also be placed in this folder.
  5. If a component contains subcomponents, they should be nested in a components folder in the main component directory.
    • Each subcomponent should have its own folder without an index.ts file.
    • If subcomponents require testing, a test folder should be created in their respective subcomponent folders.
  6. Component folders can include additional files and folders if needed:
    • A utils folder for housing utility functions, with one function per file. The file name should match the name of the function.
    • A hooks folder for custom hooks.
    • A constants file (Button.constants.tsx) for component-specific constants.
    • A context file (Button.context.ts) for managing component context.

TestKits

  1. When component uses other components under the hood, DON'T re-expose those components testkits directly. It creates unnecessary coupling with that component.

By following these guidelines, we ensure a structured and organized approach to component development, facilitating scalability, maintainability, and ease of collaboration.

Main files explained

ComponentName.tsx

Component implementation. It can either be an atom or a composition of other components.

ComponentName.st.css

Component stylesheets powered by Stylable. See documentation to learn how to use it: Stylable.

ComponentName.uni.driver.ts

Every component exposes a public driver (testkit) to interact with it in tests (ComponentName.spec.tsx).

ComponentName.visual.ts

Visual tests for component styles and variations.

ComponentName.meta.tsx

An internal metadata file for automatic visual, SSR, a11y and testkit testing.

test/ComponentName.spec.tsx

Unit tests of component behavior and methods.

test/ComponentName.visual.tsx

Visual tests of component styles and variations after interactions.

docs/index.story.ts

Entry file for documentation. It uses the .story convention to apply the automated documentation tool.






Last updated: 26 October 2026

Did this help?