# @argent/x-ui
This package provides a theme and components for use with [Chakra UI](https://chakra-ui.com/)
## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Set up the global theme](#set-up-the-global-theme)
- [Theme and utilities](#theme-and-utilities)
- [Components](#components)
- [Tailwind theme](#tailwind-theme)
- [Design System tokens](#design-system-tokens)
- [Icons and Logos](#icons-and-logos)
- [Storybook](#storybook)
- [Testing](#testing)
- [Development](#development)
- [Development as a local dependency](#development-as-a-local-dependency)
- [Recommended](#recommended)
- [Experimental](#experimental)
- [Versioning](#versioning)
- [Hotfix workflow](#hotfix-workflow)
## Installation
To install the package, use the following command:
```sh
pnpm add @argent/x-ui
```
## Usage
### Set up the global theme
```tsx
import { Button, H1, theme } from "@argent/x-ui"
import { ChakraProvider } from "@chakra-ui/react"
import { FC } from "react"
export const App: FC = () => {
return (
Hello world
)
}
```
### Theme and utilities
The theme contains standard set of attributes which are accessed using a name or key as decribed by chakra-ui. This allows the system to change the underlying values and units without changing the component markup.
See [chakra style props](https://chakra-ui.com/docs/styled-system/style-props) for examples
### Components
You can use primitives and components from chakra - see [chakra components](https://chakra-ui.com/docs/components) for examples
Some components like `BottomSheet` require you to import styles in your project. You can do it like this:
```typescript
import "@argent/x-ui/styles/style.css"
```
## Design System tokens
The tokens in `*.generated.ts[x]` are generated from data in Supernova. To regenerate these (requires an access key - see `.env`):
You can get that access token from: https://cloud.supernova.io/user-profile/authentication
```sh
pnpm gen:tokens
```
## Icons and Logos
The icons and logos in `/src/components/icons` and `/src/components/logos` are generated from master artwork in Figma. To regenerate these (requires an access key - see `.env`):
You can get that access token from: https://www.figma.com/developers/api#access-tokens
```sh
pnpm gen:icons
```
## Tailwind theme
You will need to add the css varaibles that are reference by the tailwind config to your global styles `global.css`. Thes are set to use `.dark` class for dark mode by default:
```css
/* global.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
@import "@argent/x-ui/styles/tailwind.css";
/* any additional styles here */
```
And them colors and fontSize to your tailwind config `tailwind.config.ts`:
```tsx
// tailwind.config.ts
import type { Config } from "tailwindcss"
import { tailwindThemeConfig } from "@argent/x-ui"
const config: Config = {
darkMode: "class",
theme: {
extend: {
colors: {
...tailwindThemeConfig.colors
// add any additional colors here
},
fontSize: {
...tailwindThemeConfig.fontSize
// add any additional font sizes here
}
}
}
// add any additional config here
}
export default config
```
## Storybook
Custom components and examples unique to this package are in Storybook
```sh
pnpm storybook
```
Storybook will be published to Chromatic for each PR - see the GitHub Actions output for a link
The permalink for `@argent/x-ui` on `develop` is https://develop--65d8cb036305ac44c7a097eb.chromatic.com/
## Testing
Tests include shapshot testing that requires Playwright browsers to be installed
```sh
pnpm exec playwright install
```
To run the tests, use the following command:
```sh
pnpm test
```
To run tests in watch mode:
```sh
pnpm test:watch
```
To update test snapshots:
```sh
pnpm test:update
```
## Development
To start development, clone the repository and install the dependencies:
```sh
git clone https://github.com/argentlabs/x-ui.git
cd x-ui
pnpm install
# generate TypeScript types for autocomplete
pnpm gen:theme-typings
```
You can start the development server with:
```sh
pnpm dev
```
This builds for development, in watch mode with sourcemaps enabled.
## Development as a local dependency
### Recommended
The recommended way to develop as a local dependency is to use the `file:` protocol, see [What's the difference between pnpm link and using the file: protocol?](https://pnpm.io/cli/link#whats-the-difference-between-pnpm-link-and-using-the-file-protocol)
```json
/** in the project package.json, use a relative path to the local x-ui folder */
"@argent/x-ui": "file:../../../x-ui",
```
The workflow is then;
- Make changes in `x-ui` package
- Run `pnpm build` in the `x-ui` package
- Run `pnpm install` in the project that references the local `x-ui` folder
- Repeat every time you want to install the latest changes
Once you are happy with the changes
- Create and merge a PR into `develop` branch
- Wait for package to publish to npm with [updated `next` version](https://www.npmjs.com/package/@argent/x-ui?activeTab=versions)
- Update the version in the relevant projects
### Experimental
Please also try an experimental way of developing local packages with live reloading and source maps. This is a new feature, please use and share any feedback or issues.
1. In each of the packages you are wroking on, start dev in watch mode with reloading;
```sh
# e.g. in `x-ui` or `x-shared` package
$ pnpm dev
```
2. In `argent-x-private`, modify the root `package.json` to override the packages you want to work on:
```json
/** in the project package.json, use a relative path to the local folder */
"pnpm": {
"overrides": {
"@argent/x-shared": "link:../x-shared",
"@argent/x-ui": "link:../x-ui"
}
}
```
3. Install the changes and start the dev server with hot reloading
```sh
$ pnpm install
$ pnpm dev
# or just for the extension package
$ pnpm dev:extension
```
4. Make a change in the linked package. This will trigger a series of updates;
- trigger a re-build in the linked package
- trigger a re-build in the extension package
- trigger a reload of the running extension with your changes
## Versioning
The package version will be inferred automatically from each commit message using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) - see the summary there for how to achieve patch, minor and major version changes.
## Hotfix workflow
- Checkout the tag of the version you want to hotfix
- Create a new branch using the format `hotfix/vx.y.z` and increment the patch version
- Add your changes
- Commit your changes using the format `fix: `