@sonic-equipment/ui

@sonic-equipment/ui is a private, React component library designed with modularity and reusability in mind.

Features

• 🔄 Universally Compatible: Our components seamlessly integrate across any meta framework, including Next.js, Remix, or Vite React with React Router, ensuring effortless adaptability.
• 🎨 Styled with PostCSS: Leveraging PostCSS modules for scoped and manageable styles and compatibility with React Server Components.
• 📚 Documented with Storybook: Components are documented and showcased using Storybook, with stories co-located alongside components for easy reference.
• 📦 Bundled with Rollup: Efficiently compiled for production with Rollup and published as a private NPM package.

Getting Started

Prerequisites

Ensure you have React 18 or newer in your project to use @sonic-equipment/ui.

Installation

Since @sonic-equipment/ui is a private package, ensure you have access to the private npm registry configured in your project. Then, install the library using npm:

npm install @sonic-equipment/ui

Import styles

@import '@sonic-equipment/ui/fonts.css';
@import '@sonic-equipment/ui/styles.css';

Or within your App.tsx

import '@sonic-equipment/ui/fonts.css'
import '@sonic-equipment/ui/styles.css'

Apply base styles

Use the following import to apply the base styles to your project or copy the content of base.css into your project's global styles:

import '@sonic-equipment/ui/base.css'

Usage

Import and use a component from the library like so:

import { Button } from '@sonic-equipment/ui'

const App = () => (
  <Button variant="solid" color="primary">
    Click Me
  </Button>
)

Styling

This library uses PostCSS with modules CSS, allowing you to import styles directly into your React components for scoped styling. The PostCSS configuration includes the following plugins:

• postcss-import: Allows you to use the @import statement inside your CSS files, enabling you to split your CSS into smaller, more maintainable pieces. This plugin processes each import, inlining content directly into the CSS file, making it easier to organize and share styles across different files.

• postcss-nested: Enables you to write your CSS in a nested manner, similar to what you might be used to in preprocessors like SCSS or Less. This makes managing complex CSS structures simpler by keeping related rules nested within one another.

• postcss-custom-media: Provides the ability to define custom media query aliases inside your CSS, allowing for more readable and maintainable responsive design. By defining a custom name for media queries, you can reuse them throughout your stylesheets without repeating the conditions.

• autoprefixer: Automatically adds vendor prefixes to CSS rules using values from Can I Use. It ensures your CSS will work with as many browsers as possible by adding necessary prefixes for you, saving time and helping avoid potential errors in manual prefixing.

Design Tokens

Design tokens in @sonic-equipment/ui serve as the foundational building blocks of our component library's visual design. They encapsulate and centralize the core stylistic attributes such as typography, colors, spacing, and borders, ensuring consistency across the library. Our tokens are organized and imported through index.css.

Example: Color Tokens

Our color tokens, defined in colors.css, offer a wide palette ranging from grayscale to brand-specific hues. These tokens are used to maintain visual harmony and can be applied throughout your project for consistency and easy themeability.

:root {
  /* Global color tokens */
  --color-white: #ffffff;
  --color-black: #000000;
  ...

  /* Brand-specific aliases */
  --color-brand-red: var(--color-red-700);
  --color-brand-dark-red: var(--color-red-800);
  ...
}

Utilizing Tokens in Components

Design tokens are applied directly in our component styles, ensuring consistent look and feel. Here's how a token is used in the styling of our Button component:

.solid {
  &:where(.primary) {
    background-color: var(--color-brand-red);
    color: var(--color-white);

    &:where([data-hovered]),
    &:where([data-pressed]) {
      background-color: var(--color-brand-dark-red);
    }
  }
}

Customizing Tokens

To customize these tokens for your project, override the default values in a global CSS file after importing the library's styles. This allows you to tailor the appearance of @sonic-equipment/ui components to fit your brand's identity:

:root {
  --color-brand-red: #ff0000; /* Your brand red */
  --color-brand-dark-red: #cc0000; /* A darker shade of your brand red */
}

This approach ensures that any component from the @sonic-equipment/ui library not only adheres to your design system but is also flexible enough to accommodate brand-specific styling.

Getting Started with Development

This section provides a step-by-step guide to setting up your development environment for @sonic-equipment/ui. Whether you're looking to contribute or simply want to run the library locally for development, follow the instructions below.

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js (version 14 or newer)
• pnpm (as this project uses pnpm for dependency management)

Installation

Run the following command in the root directory of the project to install the necessary dependencies:

pnpm install

Running Storybook

To view and interact with the components in a development environment, this project utilizes Storybook. Run Storybook locally with the following command:

pnpm dev

This will start the Storybook server, typically available at http://localhost:6006. You can browse through the component stories and work on components in real-time.

Building the Library

The library uses Rollup for bundling, optimized for ESM format. When you're ready to build the library for production:

pnpm build

This command triggers the Rollup build process as configured in the project, compiling your components into the dist directory.

Linting

To ensure your code follows the project's coding standards and guidelines, run the linter with:

pnpm lint

This will check your code for any stylistic or programming errors and help maintain code quality.

Publishing

Publishing is handled via a private npm registry. Ensure you have the necessary permissions and authentication configured before attempting to publish. When ready, run:

pnpm publish

Best practices

TypeScript - Types vs Interfaces

When defining types for prefer interfaces to describe data types / object structures and use types for union types, tuples, and other types.

Examples for interfaces:

interface ButtonProps {
  variant: 'solid' | 'outline' | 'ghost'
  color: 'primary' | 'secondary' | 'tertiary'
}

interface CheckboxProps extends ExternalLibraryCheckboxProps {
  checked: boolean
  onChange: (checked: boolean) => void
}

interface Product {
  id: string
  name: string
  price: number
}

Examples for types:

type ButtonVariant = 'solid' | 'outline' | 'ghost'
type ButtonColor = 'primary' | 'secondary' | 'tertiary'

type OnClickHandler = (event: MouseEvent) => void

type Key = string | number