`@sonic-equipment/ui` is a private, React component library designed with modularity and reusability in mind.
npm install @sonic-equipment/ui@sonic-equipment/ui is a private, React component library designed with modularity and reusability in mind.
- 🔄 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.
Ensure you have React 18 or newer in your project to use @sonic-equipment/ui.
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:
``sh`
npm install @sonic-equipment/ui
#### Import styles
`css`
@import '@sonic-equipment/ui/fonts.css';
@import '@sonic-equipment/ui/styles.css';
Or within your App.tsx
`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:
`css`
import '@sonic-equipment/ui/base.css'
Import and use a component from the library like so:
`jsx
import { Button } from '@sonic-equipment/ui'
const App = () => (
)
`
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 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.
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.
`css
: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);
...
}
`
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:
`css
.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);
}
}
}
`
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:
`css`
: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.
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.
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)
Run the following command in the root directory of the project to install the necessary dependencies:
`bash`
pnpm install
To view and interact with the components in a development environment, this project utilizes Storybook. Run Storybook locally with the following command:
`bash`
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.
The library uses Rollup for bundling, optimized for ESM format. When you're ready to build the library for production:
`bash`
pnpm build
This command triggers the Rollup build process as configured in the project, compiling your components into the dist directory.
To ensure your code follows the project's coding standards and guidelines, run the linter with:
`bash`
pnpm lint
This will check your code for any stylistic or programming errors and help maintain code quality.
Publishing is handled via a private npm registry. Ensure you have the necessary permissions and authentication configured before attempting to publish. When ready, run:
`bash`
pnpm publish
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:
`ts
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:
`ts
type ButtonVariant = 'solid' | 'outline' | 'ghost'
type ButtonColor = 'primary' | 'secondary' | 'tertiary'
type OnClickHandler = (event: MouseEvent) => void
type Key = string | number
``