Skip to content

Latest commit

 

History

History
75 lines (52 loc) · 3.1 KB

component-design.md

File metadata and controls

75 lines (52 loc) · 3.1 KB

Component design

Component directory structure

Structure of the directory where the necessary files for a Component are located.

├─ __tests__
  └── index.test.tsx ........... Component's tests
├─ Component.ct.tsx............. Component's visual tests
├─ Component.ct-story.tsx....... Component's story to be used in visual tests
├─ index.tsx ................... Component's logic and rendering
├─ index.d.ts .................. Component's types
├─ Component.stories.tsx ....... Component's Storybook
├─ consts.ts ................... Component's constants
└─ README.md ................... Component's documentation

Styling

We use Tailwind CSS for styling. Custom Tailwind classes can be used but should be avoided. All design tokens from orbit-design-tokens have classes that apply their value to the different possible CSS properties.

Component types

For component typing we use Typescript. Always create index.d.ts file, where the declaration of types is stored. We use readonly types to be more strict in setting up values of the props. When the purpose of the prop is really optional, its type should me marked as optional (?).

Every component should accept dataTest and id props. For this, we extend the Globals type.

import type * as Common from "../common/types";

export interface Props extends Common.Globals {
  readonly size?: "small" | "medium" | "large";
  readonly children: React.ReactNode;
}

Component constants

We use constants for props that have options. In this way, we can easily maintain consistency. Just export your options as objects with uppercase.

export const SIZE_OPTIONS = {
  SMALL: "small",
  MEDIUM: "medium",
  LARGE: "large",
};

Storybook

All components should have stories that display their different variations and behaviors. Stories should be written in the file Component.stories.tsx. For more information about using Storybook check the official documentation.

Testing

All components should have unit tests and visual tests. We use Jest for unit testing and their tests should be written in the file __tests__/index.test.tsx.

Visual tests are performed using Playwright. They should be written in the file Component.ct.tsx and should be used to test the component in different states and with different props.

For more information about component testing check the dedicated page.

Component documentation

Documentation is one of the most important elements of Orbit components. It’s necessary to add README.md to the main directory of the Component.

Readme should contain:

  • Basic import
  • Example of usage in default state
  • Table of all props
  • Options of enum proptypes
  • Functional specs
    • Explains all special behaviors of the Component