Skip to content

Latest commit

 

History

History
195 lines (137 loc) · 5.55 KB

README.md

File metadata and controls

195 lines (137 loc) · 5.55 KB

Kleros

Kleros UI Components Library

Conventional Commits Commitizen Friendly Styled with Prettier

Introduction

The Kleros UI Components Library is a comprehensive collection of React components that implement the Kleros design system. This library provides a consistent and accessible user interface for Kleros applications, making it easier to build cohesive user experiences across the Kleros ecosystem.

Built with React, TypeScript, and Tailwind CSS, this library offers a wide range of components from basic UI elements to complex interactive widgets. Each component is designed with accessibility, customization, and ease of use in mind.

Features

  • React-based components: Built with React 18 and TypeScript for type safety
  • Tailwind CSS integration: Leverages Tailwind for styling with consistent design tokens
  • Accessibility: Components follow WAI-ARIA guidelines for maximum accessibility
  • Responsive design: Components adapt to different screen sizes
  • Customizable: Easily theme and extend components to match your application's design
  • Storybook documentation: Interactive documentation with usage examples

Components

The library includes a wide variety of components, including but not limited to:

  • Layout: Box, Card, Modal
  • Navigation: Breadcrumb, Pagination, Tabs
  • Form Elements: TextField, TextArea, NumberField, Checkbox, RadioGroup, Switch, DatePicker, FileUploader
  • Data Display: DisplaySmall, DisplayLarge, DisplayIcon, Tag, Tooltip
  • Feedback: Alert, Push Notifications
  • Progress: LinearProgress, CircularProgress, Steps, Timeline
  • Interactive Elements: Button, Accordion, Dropdown, Cascader

Usage

Installation

Install the package using your preferred package manager:

# Using yarn
yarn add @kleros/ui-components-library

# Using npm
npm install @kleros/ui-components-library

Setup

  1. Import the CSS at the top level of your application:
import "@kleros/ui-components-library/style.css";
  1. Import and use components in your application:
import { Button, TextField, Alert } from "@kleros/ui-components-library";

function MyComponent() {
  return (
    <div>
      <TextField label="Username" placeholder="Enter your username" />
      <Button>Submit</Button>
      <Alert type="success">Operation completed successfully!</Alert>
    </div>
  );
}

Theme usage

If you wish the use the library's tailwind theme variables in your tailwind app. You can utilize it by importing the theme file in your global.css file.

@import tailwindcss @import
  "../../../node_modules/@kleros/ui-components-library/dist/theme/theme.css";

You can find the available theme variables here. If want to override or edit the defined theme variables, you can do so like this:

:root {
  --klerosUIComponentsWhiteBackground: #832323;
}
:root[class="dark"] {
  --klerosUIComponentsWhiteBackground: #832323;
}

Peer Dependencies

This library requires the following peer dependencies:

  • React 18+
  • React DOM 18+
  • Tailwind CSS 4+

Make sure these are installed in your project.

Development

Local Setup

  1. Clone the repository:

    git clone https://github.com/kleros/ui-components-library.git
cd ui-components-library

  2. Install dependencies:

    yarn install

  3. Start the Storybook development server:

    yarn start

  4. Build the library:

    yarn build

Code Quality

This project uses:

  • TypeScript for type checking
  • ESLint for code linting
  • Prettier for code formatting
  • Husky for Git hooks
  • Conventional Commits for commit messages

Run checks with:

yarn check-types    # Type checking
yarn check-style    # Linting

Package Publication

Tagging

  1. Bump the version in package.json
  2. Run a clean build: yarn clean && yarn build
  3. Commit the change to git: git add -u ; git commit -m "chore: release"
  4. Tag this version: version=v$(cat package.json | jq -r .version) && git tag -m $version $version
  5. Push both commit and tag: git push && git push --tags

Publish to NPM

  1. Export your NPM token: export YARN_NPM_AUTH_TOKEN=<npm_xxxxxxxxxxxx>
  2. Publish: yarn publish

Publish to GitHub

  1. Login:

    npm login --registry https://npm.pkg.github.com --auth-type legacy
> Username: YOUR_GITHUB_USERNAME
> Password: YOUR_GITHUB_PERSONAL_ACCESS_TOKEN

  2. Publish: npm publish --registry https://npm.pkg.github.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes using conventional commits (git commit -m 'feat: add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.