Skip to content

Commit 674c81a

Browse files
tenphitenphi
committed
chore: update documentation
1 parent bd45882 commit 674c81a

2 files changed

Lines changed: 226 additions & 84 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,67 @@
1-
# Contribution guide
2-
3-
## Development Information
4-
5-
### Requirements
6-
7-
- [Node LTS](https://nodejs.org/en/)
8-
- [YARN v1](https://classic.yarnpkg.com/lang/en/)
9-
10-
### Commit Convention
11-
12-
Before you create a Pull Request, please check whether your commits comply with
13-
the commit conventions used in this repository.
14-
15-
When you create a commit, we kindly ask you to follow the convention
16-
`category: message` in your commit message while using one of
17-
the following categories:
18-
19-
- `feat/feature`: all changes that introduce completely new code or new
20-
features
21-
- `fix`: changes that fix a bug (ideally, you will additionally reference an
22-
issue if present)
23-
- `refactor`: any code-related change that is not a fix nor a feature
24-
- `docs`: changing existing or creating new documentation (i.e. README, docs for
25-
usage of lib or CLI usage)
26-
- `build`: all changes regarding the build of the software, changes to
27-
dependencies or the addition of new dependencies
28-
- `test`: all changes regarding tests (adding new tests or changing existing
29-
ones)
30-
- `ci`: all changes regarding the configuration of continuous integration (i.e.
31-
GitHub actions, ci system)
32-
- `chore`: all changes to the repository that do not fit into any of the above
33-
categories
34-
35-
If you are interested in the detailed specification, you can visit
36-
https://www.conventionalcommits.org/ or check out the
37-
[Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).
38-
39-
### Steps to PR
40-
41-
1. Create a new branch out of the `main` branch. We follow the convention
42-
`[type/(task-name | scope)]`. For example `fix/CUK-1` or `docs/menu-typo`. `type`
43-
can be either `docs`, `fix`, `feat`, `build`, or any other conventional
44-
commit type. `scope` is just a short id that describes the scope of work.
45-
2. Make and commit your changes following the
46-
[commit convention](https://github.com/cube-js/cube-ui-kit/blob/main/CONTRIBUTING.md#commit-convention).
47-
As you develop, you can run `pnpm build` and
48-
`pnpm test` to make sure everything works as expected.
49-
3. Run `pnpm changeset` to create a detailed description of your changes. This
50-
will be used to generate a changelog when we publish an update.
51-
[Learn more about Changeset](https://github.com/atlassian/changesets/tree/master/packages/cli).
52-
> You can make it earlier after you have created a PR.
53-
> Click on a link in the Changeset's bot message
54-
> and write the changes you want to make. Then commit these changes.
55-
56-
4. Also, if you provide `jsx` snippets to the changeset, please turn off the
57-
live preview by doing the following at the beginning of the snippet:
58-
` ```jsx live=false`
59-
60-
> If you made minor changes like CI config, prettier, etc, you can run
61-
> `pnpm changeset add --empty` to generate an empty changeset file to document
62-
> your changes.
63-
64-
### Tests
65-
66-
All commits that fix bugs or add features need a test.
67-
We use jest to write unit tests and storybook to make visual regression tests.
1+
# Contributing
2+
3+
## Requirements
4+
5+
- [Node.js](https://nodejs.org/) >= 22.14.0
6+
- [pnpm](https://pnpm.io/) >= 10
7+
8+
## Getting Started
9+
10+
```bash
11+
pnpm install
12+
pnpm storybook # starts Storybook on http://localhost:6060
13+
```
14+
15+
## Commit Convention
16+
17+
Follow the `category: message` format:
18+
19+
| Category | Use for |
20+
|----------|---------|
21+
| `feat` | New features or components |
22+
| `fix` | Bug fixes (reference an issue when possible) |
23+
| `refactor` | Code changes that are neither a fix nor a feature |
24+
| `docs` | Documentation updates |
25+
| `build` | Build config or dependency changes |
26+
| `test` | Adding or updating tests |
27+
| `ci` | CI/CD configuration |
28+
| `chore` | Everything else (formatting, tooling, etc.) |
29+
30+
See the [Conventional Commits](https://www.conventionalcommits.org/) spec for details.
31+
32+
## Steps to PR
33+
34+
1. **Branch** off `main` using the convention `type/scope` — e.g. `fix/select-overflow`, `feat/date-range-picker`, `docs/menu-typo`.
35+
36+
2. **Develop** your changes. Verify as you go:
37+
38+
```bash
39+
pnpm build # check the build
40+
pnpm test # run unit tests (Vitest)
41+
pnpm fix # lint + format
42+
```
43+
44+
3. **Create a changeset** to describe your changes for the changelog:
45+
46+
```bash
47+
pnpm changeset
48+
```
49+
50+
[Learn more about Changesets.](https://github.com/atlassian/changesets/tree/master/packages/cli)
51+
52+
> For trivial changes (CI config, formatting, etc.) use `pnpm changeset add --empty`.
53+
>
54+
> If your changeset includes JSX snippets, disable live preview: `` ```jsx live=false ``
55+
56+
4. **Push** and open a Pull Request against `main`.
57+
58+
## Tests
59+
60+
All bug fixes and new features should include tests. The project uses [Vitest](https://vitest.dev/) with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) and [Chromatic](https://www.chromatic.com/) for visual regression.
61+
62+
```bash
63+
pnpm test # run all tests
64+
pnpm test -- Button # run tests matching "Button"
65+
pnpm test -u # update snapshots
66+
pnpm chromatic # visual regression (requires token)
67+
```

‎README.md‎

Lines changed: 159 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,174 @@
1-
# UI Kit for Cube Dev Projects
1+
# Cube UI Kit
22

3-
Based on React Aria and `tasty` styling library.
3+
[![npm version](https://img.shields.io/npm/v/@cube-dev/ui-kit.svg)](https://www.npmjs.com/package/@cube-dev/ui-kit)
4+
[![license](https://img.shields.io/npm/l/@cube-dev/ui-kit.svg)](https://github.com/cube-js/cube-ui-kit/blob/main/LICENSE)
45

5-
## Available Scripts
6+
An open-source React component library that powers [Cube Cloud](https://cubecloud.dev) and other [Cube Dev](https://cube.dev) products. While built for Cube's own interfaces, it is a general-purpose kit you can use freely in any application where it fits your needs.
67

7-
### pnpm start
8+
**[Live Storybook](https://cube-ui-kit.vercel.app/)** · **[Tasty Docs](https://github.com/tenphi/tasty)**
89

9-
Runs the test page in the development mode.
10-
Open http://localhost:8080 to view it in the browser.
10+
## Highlights
1111

12-
The page will reload if you make edits.
13-
You will also see any lint errors in the console.
12+
- **100+ production-ready components** — primitives (Button, Input), layout (Grid, Flex, Space), fields (Select, ComboBox, DatePicker), overlays (Dialog, Toast), and complex organisms (CommandMenu, FilterPicker, FileTabs).
13+
- **Accessible by default** — built on [React Aria](https://react-spectrum.adobe.com/react-aria/) with keyboard navigation, focus management, and screen reader support out of the box.
14+
- **Tasty styling engine** — declarative, token-aware styles with state-driven values, design tokens, responsive breakpoints, and zero specificity conflicts. See the [Tasty documentation](https://github.com/tenphi/tasty).
15+
- **Integrated form system** — async rule-based validation with field-level and form-level state management; fields plug in directly without extra wrapper components.
16+
- **TypeScript-first** — complete type definitions with autocomplete for tokens and style props.
17+
- **Tree-shakeable** — unbundled ESM output; import only what you use.
1418

15-
### pnpm storybook
19+
## Installation
1620

17-
Run storybook with all the components of UI Kit.
21+
```bash
22+
pnpm add @cube-dev/ui-kit
23+
```
1824

19-
Deployed version of the Storybook from the `main` branch is here: https://cube-uikit-storybook.netlify.app/
25+
Peer dependencies:
2026

21-
### pnpm build
27+
```bash
28+
pnpm add react react-dom
29+
```
2230

23-
Builds a static copy of UIKit to the `dist/` folder.
24-
Your app is ready to be deployed!
31+
React 18 and 19 are both supported.
2532

26-
### pnpm test
33+
## Quick Start
2734

28-
Not yet implemented
35+
Wrap your application with `Root` to initialize the design system:
36+
37+
```tsx
38+
import { Root, Button, TextInput, Space } from '@cube-dev/ui-kit';
39+
40+
function App() {
41+
return (
42+
<Root>
43+
<Space flow="column" gap="2x" padding="4x">
44+
<TextInput label="Name" placeholder="Enter your name" />
45+
<Button type="primary" onPress={() => console.log('clicked')}>
46+
Submit
47+
</Button>
48+
</Space>
49+
</Root>
50+
);
51+
}
52+
```
53+
54+
## Components
55+
56+
| Category | Components |
57+
|----------|------------|
58+
| **Layout** | Flex, Grid, Space, Flow, Panel, ResizablePanel, Prefix, Suffix |
59+
| **Actions** | Button, Button.Group, Button.Split, Link, Menu, CommandMenu |
60+
| **Content** | Text, Title, Paragraph, Card, Badge, Tag, Avatar, Alert, Skeleton, Placeholder, Disclosure, Divider, CopySnippet, PrismCode |
61+
| **Fields** | TextInput, NumberInput, PasswordInput, SearchInput, TextArea, Select, ComboBox, Checkbox, RadioGroup, Switch, Slider, DatePicker, FileInput, ListBox, FilterListBox, FilterPicker, Picker |
62+
| **Form** | Form, FieldWrapper, SubmitButton, ResetButton |
63+
| **Overlays** | Dialog, AlertDialog, Modal, Tooltip, Toast, Notifications |
64+
| **Navigation** | Tabs, FileTabs |
65+
| **Status** | Spin, LoadingAnimation |
66+
67+
Browse all components with live examples in the [Storybook](https://cube-ui-kit.vercel.app/).
68+
69+
## Styling with Tasty
70+
71+
Cube UI Kit uses [Tasty](https://github.com/tenphi/tasty) — a styling engine that generates conflict-free CSS using mutually exclusive selectors. Tasty documentation is included in this package under [`docs/tasty/`](./docs/tasty) and covers:
72+
73+
- [Usage](./docs/tasty/usage.md) — component creation, state mappings, sub-elements, variants
74+
- [Configuration](./docs/tasty/configuration.md) — tokens, recipes, custom units, TypeScript extensions
75+
- [Style Properties](./docs/tasty/styles.md) — complete reference for all enhanced style properties
76+
77+
Create custom styled components:
78+
79+
```tsx
80+
import { tasty } from '@cube-dev/ui-kit';
81+
82+
const Card = tasty({
83+
styles: {
84+
display: 'flex',
85+
flow: 'column',
86+
padding: '4x',
87+
gap: '2x',
88+
fill: '#surface',
89+
border: '#border',
90+
radius: '1r',
91+
92+
Title: { preset: 'h3', color: '#primary' },
93+
Content: { preset: 't2', color: '#text' },
94+
},
95+
elements: { Title: 'h2', Content: 'div' },
96+
});
97+
```
98+
99+
Style properties support state-driven values:
100+
101+
```tsx
102+
const StatusBadge = tasty({
103+
styles: {
104+
padding: '1x 2x',
105+
radius: 'round',
106+
fill: {
107+
'': '#surface',
108+
'type=success': '#success-bg',
109+
'type=error': '#danger-bg',
110+
},
111+
},
112+
});
113+
```
114+
115+
## Development
116+
117+
### Prerequisites
118+
119+
- Node.js >= 22.14.0
120+
- pnpm >= 10
121+
122+
### Scripts
123+
124+
```bash
125+
pnpm storybook # Start Storybook dev server on port 6060
126+
pnpm build # Build the library (tsdown, unbundled ESM)
127+
pnpm test # Run all tests (Vitest)
128+
pnpm test -- Button # Run tests matching "Button"
129+
pnpm fix # Lint and format (ESLint + Prettier)
130+
pnpm size # Check bundle size limits
131+
pnpm chromatic # Run visual regression tests
132+
```
133+
134+
### Project Structure
135+
136+
```
137+
src/
138+
├── components/
139+
│ ├── actions/ # Button, Link, Menu, CommandMenu, ...
140+
│ ├── content/ # Card, Badge, Tag, Alert, Skeleton, ...
141+
│ ├── fields/ # TextInput, Select, ComboBox, ...
142+
│ ├── form/ # Form, FieldWrapper, SubmitButton, ...
143+
│ ├── layout/ # Flex, Grid, Space, Flow, Panel, ...
144+
│ ├── navigation/ # Tabs
145+
│ ├── organisms/ # FileTabs, StatsCard
146+
│ ├── overlays/ # Dialog, Tooltip, Toast, ...
147+
│ └── status/ # Spin, LoadingAnimation
148+
├── icons/ # 130+ icon components (Tabler-based + custom)
149+
├── stories/ # Storybook guides and documentation
150+
├── tasty/ # Tasty integration utilities
151+
├── tokens/ # Design tokens
152+
└── index.ts # Public API barrel export
153+
docs/
154+
└── tasty/ # Tasty styling engine documentation
155+
```
156+
157+
Each component follows a standard file layout:
158+
159+
```
160+
ComponentName/
161+
├── ComponentName.tsx # Implementation
162+
├── ComponentName.stories.tsx # Storybook stories
163+
├── ComponentName.docs.mdx # Documentation
164+
├── ComponentName.test.tsx # Tests
165+
└── index.tsx # Re-exports
166+
```
167+
168+
## Contributing
169+
170+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for commit conventions, branch naming, PR workflow, and changeset instructions.
29171

30172
## License
31173

32-
This project is licensed under the MIT License - see the LICENSE file for details.
174+
[MIT](./LICENSE) — Cube Dev, Inc.

0 commit comments

Comments
 (0)