@axvn-hoding/ui-toolkit

Blockscout UI Toolkit

A comprehensive collection of reusable Chakra UI components and theme system for Blockscout's projects. This toolkit provides a consistent design system and UI components to maintain visual consistency across Blockscout applications.

Features

• 🎨 Pre-configured Chakra UI theme with Blockscout's design system
• 🧩 Reusable UI components built on Chakra UI
• 🌓 Built-in dark mode support
• 📱 Responsive and accessible components
• 🔍 TypeScript support with proper type definitions

Installation

Package Installation

Install the package using your preferred package manager:

# Using npm
npm install @blockscout/ui-toolkit

# Using pnpm
pnpm add @blockscout/ui-toolkit

Required Dependencies

Ensure you have the following peer dependencies installed:

{
  "dependencies": {
    "@blockscout/ui-toolkit": "latest",
    "@chakra-ui/react": ">=3.36.1",
    "@emotion/react": ">=11.14.0",
    "@uidotdev/usehooks": ">=2.4.1",
    "d3": ">=7.6.1",
    "dayjs": ">=1.11.5",
    "dom-to-image": ">=2.6.0",
    "es-toolkit": ">=1.39.10",
    "next": ">=16.2.4",
    "next-themes": ">=0.4.4",
    "react": ">=18.3.1",
    "react-dom": ">=18.3.1",
    "react-hook-form": ">=7.52.1"
  },
  "devDependencies": {
    "@chakra-ui/cli": ">=3.36.1",
    "@types/node": "^20",
    "@types/react": "18.3.12",
    "@types/react-dom": "18.3.1",
    "typescript": "5.4.2"
  }
}

Quick Start

1. Theme Setup

Create a theme.ts file in your project and configure the Blockscout theme:

// Basic setup
import { theme } from '@blockscout/ui-toolkit';
export default theme;

Or extend the theme with custom overrides:

import { createSystem } from '@chakra-ui/react';
import { themeConfig } from '@blockscout/ui-toolkit';

const customOverrides = {
  // Add your custom theme overrides here
  theme: {
    semanticTokens: {
      colors: {
        brand: {
          primary: { value: '#5353D3' }
        },
      },
    },
  },
};

export default createSystem(themeConfig, customOverrides);

2. Provider Setup

Wrap your application with the ChakraProvider:

import { ChakraProvider } from '@chakra-ui/react';
import { Button } from '@blockscout/ui-toolkit';
import theme from './theme';

function App() {
  return (
    <ChakraProvider theme={theme}>
      <Button>Click me</Button>
    </ChakraProvider>
  );
}

3. TypeScript Support

Add the following script to your package.json to generate Chakra UI type definitions:

{
  "scripts": {
    "chakra:typegen": "chakra typegen ./src/theme.ts"
  }
}

Development

Local Development

• Clone the repository and install dependencies:

pnpm

• Start the development server:

pnpm dev

• Build the package:

pnpm build

Publishing

Manual Publishing

• Update the package version:

npm version <version-tag>

• Build the package:

npm run build

• Publish to NPM:

npm publish --access public

Automated Publishing

Use the toolkit-npm-publisher.yml GitHub Actions workflow for automated publishing.

Contributing

We welcome contributions! Please follow these steps:

• Fork the repository
• Create a feature branch
• Make your changes
• Submit a pull request

Support

For issues, feature requests, or questions, please open an issue in the repository.

License

This project is licensed under the Blockscout Software Licence. See the LICENSE file for full terms.