Overview

Base components

An atomic component library by Overdose.

Basic usage

1. Install the base components and dependent packages

yarn add @overdose/components @overdose/theme
yarn add @overdose/design-tokens-transformer -D

• The @overdose/components package contains the base react components
• The @overdose/theme package contains themeable CSS variables the base components depend on
• The @overdose/design-tokens-transformer package contains a script to transform design tokens exported from Figma into theme CSS variables

2. Import the stylesheets

Import the component and theme stylesheets into your App file.

• Nextjs (eg. Carrots): _app.tsx
• Frontastic: app.scss
• Hydrogen: App.server.tsx
• Deity: App.js
• Shogun Frontend: global.css

// JavaScript/TypeScript
import '@overdose/components/build/esm/styles.css'
import '@overdose/theme/styles.css'

3. Import a component

import { Typography } from '@overdose/components';

const MyComponent = () => (
  <Typography tag="p">
    What's up, Doc?
  </Typography>
);

4. Theme

Components are highly themeable both globally and locally.

Global theming

Design tokens can be exported from Overdose-made Figma design files and automatically converted to CSS variables with @overdose/design-tokens-transformer.

1. Export design tokens from Figma using the Design Tokens plugin. Save the exported JSON file in your project (for example as /theme/tokens/design-tokens.tokens.json)
2. Generate tokens with:

yarn transform-design-tokens build -s "<SOURCE_PATH>" -d "<DESTINATION_PATH>"

For example:

yarn transform-design-tokens build -s "./theme/tokens/design-tokens.tokens.json" -d "./theme/__generated__/"

3. Import the generated CSS variables into your App file after @overdose/theme/styles.css.

// JavaScript/TypeScript
import '@overdose/components/build/esm/styles.css'
import '@overdose/theme/styles.css'
import 'theme/__generated__/_tokens.css'

4. Fine-tune the CSS variables as required for the project. Available variables are documented in the Storybook.

:root {
  --btn-border-radius-default: 4px;
}

Local theming

Components expose a type-safe theme prop which allows passing in new class names for the component's root element and child elements.

For example:

import { Accordion, AccordionItem } from '@overdose/components';
import styles from './MyComponent.module.css';

<Accordion
  theme={{
    root: styles.accordion,
  }}>

  <AccordionItem
    name={'That\'s all folks!'}
    theme={{
      active: styles.accordionActive,
      title: styles.accordionTitle,
      content: styles.accordionContent,
    }}>
    {/* ... */}
  </AccordionItem>

</Accordion>

Further reading and contributing

Visit the docs site for more detailed usage and the contributing quick-start guide for a quick overview of how to contribute to the project.