Click UI

Click UI is the ClickHouse design system and component library. Our aim with Click UI is to provide an accessible, theme-able, modern, and attractive interface with which to experience the speed and power of ClickHouse.

You can find the official docs for the Click UI design system and component library at clickhouse.design/click-ui.

Overview

• Requirements
• Development
  • Generating design tokens
  • Local development server
• Tests
• Storybook
  • Stories development server
  • Public static site
• Releases and Versions

Requirements

• Nodejs (>= 22.12.x) as runtime
• Yarn (>= 4.5.3) for development, any other package manager in a host project

Development

The project uses yarn package manager for development.

After cloning the repository change to the work directory and install the dependencies:

yarn

Generating design tokens

Tokens are provided by a style directionary sourced from tokens-studio.

It's expected to have theme tokens provided externally, e.g. Figma tokens-studio output is stored in the repository and a PR's opened. The assets are stored in the directory [./tokens/themes].

Once [./tokens/themes] files are updated, we must regenerate the tokens:

yarn generate-tokens

Learn more about tokens-studio here.

Local development server

To run the Click UI development execute the command:

yarn dev

It'll default to the location http://localhost:5173, if port available.

Tests

The package uses vitest and react testing library for tests, e.g. functional tests.

yarn test

Storybook

The component library provides a collection of ready-to-use components. We use Storybook to showcase and document our components.

Stories development server

Start the storybook development server:

yarn storybook

It'll default to the location http://localhost:6006, if port available.

Build static site

To build a static version:

yarn storybook:build

Once built, you can serve the static files by:

yarn storybook:serve

Public static version

The latest static version's built and deployed automatically when contributing to main of Click UI.

Once deployed it's available publicly at clickhouse.design/click-ui.

Using Click UI in an external app

Click UI has been tested in NextJS, Gatsby, and Vite. If you run into problems using it in your app, please create an issue and our team will try to answer.

1. Navigate to your app's route and run npm i @clickhouse/click-ui or yarn add @clickhouse/click-ui
2. Make sure to wrap your application in the Click UI ClickUIProvider, without doing this, you may run into issues with styled-components. Once that's done, you'll be able to import the individual components that you want to use on each page. Here's an example of an App.tsx in NextJS.

import { ClickUIProvider, Text, ThemeName, Title, Switch } from '@clickhouse/click-ui'
import { useState } from 'react'

function App() {
  const [theme, setTheme] = useState<ThemeName>('dark')

  const toggleTheme = () => {
    theme === 'dark' ? setTheme('light') : setTheme('dark')
  }

  return (
    <ClickUIProvider theme={theme} config={{tooltip:{ delayDuration: 0 }}}>
      <Switch 
        checked={theme === 'dark'} 
        onCheckedChange={() => toggleTheme()} 
        label="Dark mode"
      />

      <Title type='h1'>Click UI Example</Title>
      <Text>Welcome to Click UI. Get started here.</Text>
    </ClickUIProvider>
  )
}

export default App

Changeset

Learn to manage the versioning of changelog entries.

The following is a brief description of available commands to allow a person making a contribution make key decisions about their changes.

It'll generate a changeset, which is effectively two key bits of information:

• A version type which follows semver
• Change information placed in a changelog

Make good use of this simple workflow to help us release new package versions more confidently.

Add a new changeset

When contributing, declare an intent or describe the changes you're making or adding to a release by executing the changeset:add command.

The wizard will ask a few questions and generate a changelog entry for you:

yarn changeset:add

The changesets tool keeps track of all declared changes in the .changeset directory.

Once completed, you must commit the changeset!

Checking the changeset status

To check if your branch contains a changeset:

yarn changeset:status

Create a new version and changelogs

To consume all changesets, and update to the most appropriate semver version and write a friendly changelog based on those changesets, the following command is available:

Important

Consuming changesets is done automatically in the CI/CD environment. For this reason, you don't have to execute the command, as a contributor your single concern should be adding changesets to any relevant changes.

yarn changeset:version

Releases and Versions

New versions and release notes are available at GitHub Releases.

To create a new release and publish a new version, follow the instructions in publish.md.

Conventional commits

We prefer to commit our work following Conventional Commits conventions. Conventional Commits are a simple way to write commit messages that both people and computers can understand. It help us keep track fo changes in a consistent manner, making it easier to see what was added, changed, or fixed in each commit or update.

The commit messages are formatted as [type]/[scope] The type is a short descriptor indicating the nature of the work (e.g., feat, fix, docs, style, refactor, test, chore). This follows the conventional commit types.

The scope is a more detailed description of the feature or fix. This could be the component or part of the codebase affected by the change.

Here's an example of different conventional commits messages that you must follow:

test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: 📝 Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...