🎋 Stone-UI

Stone-UI is a component library built with TypeScript, React, CSS modules, and Feather icons.
Inspired by: Bamboo-UI
Practices from: Good npm library practices

Table of Contents

• Quick start
• Usage
  • CSS module loader
  • Import base styles
  • Import components
• Contributing
  • Installing dependencies
  • Running Storybook
  • Linting and formatting
  • Testing

Quick start

To add Stone UI to your project, run the following command:

npm add @lifeondesk/stone-ui
# or using npm
npm install @lifeondesk/stone-ui

Stone UI is built using React, so react and react-dom are required peer dependencies. If you don't have them installed yet, run the following command in your project:

npm add react react-dom
# or using npm
npm install react react-dom

Usage

CSS module loader

Stone UI uses CSS modules for styling which are imported into the JavaScript files. A custom loader is needed to make this work.

Popular React frameworks such as Next.js and Create React App support CSS modules out of the box, though you might need additional configuration to enable this for node modules (e.g. next-transpile-modules).

If you are not using a framework or starter kit with CSS module support, you need to add and configure the css-loader for Webpack or find a similar loader for your bundler of choice.

Import base styles

Stone UI's components rely on a two global stylesheet to work properly.

• theme.css contains the default CSS variables for both light and dark mode. You can override individual variables or create a custom theme.
• base.css contains a small CSS reset and a handful of other global styles such as font-face declarations and custom ::selection styles.

Import the stylesheets in your application globally and before any other imports from Stone UI. For example, in Next.js you should import the stylesheets in the _app.js file:

// ./pages/_app.js
import '@lifeondesk/stone-ui/base.css';
import '@lifeondesk/stone-ui/components.css';
import '@lifeondesk/stone-ui/theme.css';

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Import components

Once the initial setup is done, importing and using the components is straightforward:

import { Button } from '@lifeondesk/stone-ui';

function App() {
  return (
    <Button variant="primary" onClick={() => alert('Hello')}>
      Say hello
    </Button>
  );
}

You can add custom styles to a component by passing in a className prop:

import { Button } from '@lifeondesk/stone-ui';

function App() {
  return (
    <Button className="spacing-bottom" onClick={() => alert('Hello')}>
      Say hello
    </Button>
  );
}

Contributing

If you have ideas for how I could improve this README or the project in general, let me know. Below are some tips how to make changes to the project:

Installing dependencies

This project uses npm to manage its dependencies. Once you've cloned the repository, navigate to the project folder in your terminal and run the following command to install all dependencies:

npm

Running Storybook

I use Storybook as a development workbench and to document the components. To start Storybook and open it in your browser, run the following command:

npm start

Linting and formatting

I use stone-toolkit, SumUp's toolkit for building JavaScript & TypeScript applications, to manage the linting and formatting configs. The linter and TypeScript run on every commit to ensure high code quality. You can also lint manually by running the following commands:

# Lint and report issues
npm lint
# Same as above, but also tries to fix issues automatically
npm lint:fix

Testing

The majority of the components are purely visual and TypeScript gives me a high level of confidence in the code. For these reasons and since this is only a personal project, I've opted to keep the number of tests to a minimum. You can run the tests using the following command:

npm test