Skip to main content

Contributing

Folder structure#

The two most important folders in this project are:

  • /src - The source code for all the components
  • /website - The code that powers this documentation website

The documentation website is powered by docusaurus.

Commands#

The repo consists of two projects – the UI library (located in the root) and the documentation website (located in ./website). Both have their own package.json file and their own commands.

Root folder#

  • yarn build - Builds the UI library
  • yarn watch - Builds the UI library whenever a file changes
  • yarn lint - Lints the code

In ./website#

  • yarn dev - Starts docusaurus
  • yarn build - Creates a production build of docusaurus
  • yarn serve - Serves the production build of docusaurus

If you want to bring up this documentation page simply run yarn dev in ./website. This will allow you to browse, but also develop components.

Guidelines#

  1. Always use our internal forwardRef from ./src/lib/forward-ref.ts when exporting components. This will ensure that the as prop works.
  2. Use the SizeProp and ColorProp for sizes and colors.
  3. Make your component accessible.
  4. Put the component in ./src/components/your-component/index.tsx and export it from ./src/index.ts.
  5. Follow the documentation guidelines.

forwardRef#

To make sure that the user of this library can pass refs to our components you need to export your new component using forwardRef. You can read more on forwarding refs in the react docs.

Ideally your component should support the as prop, so that the user can change the element of your component. This is really useful when you want a button to be a link or an avatar to be a button.

// href prop will be typed because we pass as="a"
<Button as="a" href="https://pixby.se">
Imma link
</Button>

To support this you need to use our internal forwardRef function from ./src/lib/forward-ref.ts:

interface AvatarOptions {
size?: SizeProp;
}
export interface AvatarProps extends HTMLPixbyProps<'div'>, AvatarOptions {}
export const Avatar = forwardRef<AvatarProps, 'div'>(({ as = 'div' }, ref) => {
return <pixby.div as={as} ref={ref} className="w-8 h-8 bg-primary" />;
});

The pixby components#

These are internal components found in ./src/lib/pixby.ts that just creates the basic HTML element you choose. This is used to support the as prop without having to use Reacts createElement function:

// with createElement
return createElement(as, { size, ref }, children);
// with a pixby component
return (
<pixby.div as={as} ref={ref}>
{children}
</pixby.div>
);

Example#

Result
SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
Live Editor

Use the pixby component that matches the default component you export. So if your main wrapper is a button, use <pixby.button>, and always pass ref and as to it.

Documenting a component#

Once you have your component ready to be documented, add a file in docs/components/[your-component].mdx, and then put it the sidebar by adding it to ./sidebars.js.

If you want to use the React Live plugin (highly recommended), you also need to add your component to its scope in src/theme/ReactLiveScope/index.js.

Document structure#

To make it easy for the reader to know where things are, we try to follow a strict structure.

---
title: MyComponent
slug: /components/my-component
---
Short description of the component.
## Import
```jsx
import { MyComponent } from '@pixby/ui';
```
- `MyComponent`: description of this component.
## Usage
```jsx live
<MyComponent>Some Toy Story reference</MyComponent>
```
## Props
### `propName`
You can change X by using the `propName` prop.
```jsx live
<MyComponent propName="someValue">Some Toy Story reference</MyComponent>
```
## Some other topic
Feel free to add more sections after **Props**.
## Accessability
End the document by adding some information about accessability.
`MyComponent` follows the practices for X found at [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#X).
- `MyComponent` has the role of `component`.
- `Esc` disables `MyComponent`.

Use local version of @pixby/ui in another project#

Sometimes you want to make changes to the components and see how they work in another project. To work with a local version of @pixby/ui in another project do the following:

cd ~/projects/pixby-ui
yarn link
cd ~/projects/your-awesome-project
yarn link @pixby/ui
cd ~/projects/pixby-ui
yarn watch

If you do the above, any change you do to @pixby/ui will now be built and reflected in your project. You can of course use npm link / yalc or whatever is your preference for linking.

caution

If you get errors related to React hooks when linking, it might be that you have multiple version of React (one for the local @pixby/ui package and one for your own project).

In that scenario, please use yalc, or make sure you are running the same version of React as your local @pixby/ui.

Edit this page