https://github.com/divriots/starter-react-sui
https://github.com/divriots/starter-react-sui
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/divriots/starter-react-sui
- Owner: divriots
- License: mit
- Created: 2021-03-12T14:12:30.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-03-02T10:52:45.000Z (over 4 years ago)
- Last Synced: 2025-09-17T00:13:46.193Z (9 months ago)
- Language: TypeScript
- Size: 180 KB
- Stars: 1
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://backlight.dev/preview/z99ptYZyvMOGDivUlP9u)
[](https://github.com/divriots/starter-react-sui)
# System UI Tech Sample _by_ ‹div›RIOTS
This is a _Technology Sample_ you can rely on to build your own Design System, based on React and a [System UI theme](https://system-ui.com/theme).
**Disclaimer**: _Technology Samples_ aren't comprehensive _Design Systems_ but showcases a given technology so you free to build you own solution upon it.
## Architecture
This _tech sample_ uses [React](https://reactjs.org/) and [JSX](https://reactjs.org/docs/introducing-jsx.html) to implement its components with [TypeScript](https://www.typescriptlang.org/). The Tokens are following the [System UI theme specification](https://system-ui.com/theme), and are consumed in two flavors: [Theme UI](https://theme-ui.com/) and [styled-components](https://styled-components.com/).
### Tokens
The Tokens are separated in different components:
- `typography`: fonts definitions
- `colors`: colors and variants
- `space`: relative and absolute spaces
- `sizes`: screensize breakpoints
- `shadows`: inset and outset shadows
- `radii`: border radius
- `border`: borders definitions
- `z-index`: z-axe indices
The [System UI tokens specification](https://system-ui.com/theme) allows you to define scales (like `font-sizes`, `radius`, _etc_) in arrays. You can also refer to previously declared values as _aliases_.
Your `tokens` should be organized by following the _key reference_ in the specification:
| Theme Key | CSS Properties |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| space | margin, margin-top, margin-right, margin-bottom, margin-left, padding, padding-top, padding-right, padding-bottom, padding-left, grid-gap, grid-column-gap, grid-row-gap |
| fontSizes | font-size |
| colors | color, background-color, border-color |
| fonts | font-family |
| fontWeights | font-weight |
| lineHeights | line-height |
| letterSpacings | letter-spacing |
| sizes | width, height, min-width, max-width, min-height, max-height |
| borders | border, border-top, border-right, border-bottom, border-left |
| borderWidths | border-width |
| borderStyles | border-style |
| radii | border-radius |
| shadows | box-shadow, text-shadow |
| zIndices | z-index |
| transitions | transition |
All tokens are declared in dedicated `*.ts` files in each tokens' components. They're then all exposed by the `all/index.ts` component file in a `theme` constant.
Your theme tokens can be imported anywhere with
```ts
import { theme } from '~/all';
```
## Components
This _tech sample_ exposes components in two flavor. They all use the same theme tokens imported as above, so your React components and your theme are not hard-linked together, and you can rely on the theme abstraction you're the most comfortable with.
Both [Theme UI](https://theme-ui.com/#style-your-ui) and [styled-components](https://styled-components.com/docs/api#themeprovider) exposes a `` JSX wrapper that take as theme argument a system-ui theme tokens definition:
```jsx
```
To avoid the need of loading the `` decorator in each components, we have overridden the _stories_ and _doc_ layouts in the `tui-utils` component.
```jsx
export const Layout = (props) => (
);
```
### Theme-UI
In the `tui-utils` component, the global theme as well as **all components variations** are loaded and merged in a common theme definition in the `variants.ts` file. This definition is then used by the `` that decorates the different layouts.
### Creating theme-ui components
To add new theme-ui based components, you have to create a component with two files: your component itself, and a `variants.ts` file that declares the [theme-ui compatible components definitions](https://theme-ui.com/components).
Your component's `variants.ts` file have to be loaded in the `tui-utils/variants.ts` file to be used by the wrapped theme.
### styled-components
On the contrary of _Theme UI_, _styled-component_ doesn't declares variations at theme level, but let you customize your components' styles directly by using the theme definitions:
```jsx
import styled from 'styled-components';
const StyledButton = styled.button(
({ theme, primary = true, secondary, disabled = false, loading = false }) => {
return {
'font-size': theme.fontSizes[2],
padding: `${theme.space[2]} ${theme.space[3]}`,
};
}
);
export const Button = () => ;
```
### Creating a _styled-components_ component
To add new _styled-components_ component, create a component that import the _styled-components_ core utils:
```jsx
import * as React from 'react';
import styled from 'styled-components';
import { ThemeContext } from 'styled-components';
export const MyComponent = () => {
const theme = React.useContext(ThemeContext);
return (
// Your component here
);
};
```
## Stories
Stories are written in Storybook's [Component Story Format](https://backlight.dev/docs/component-story-format).
You can defined multiple stories for your components to visualize their variations:
```jsx
import { Button } from '../index';
import { layout } from '~/tui-utils';
export default layout;
export const primary = () => Primary;
export const secondary = () => Secondary;
export const disabled = () => Disabled;
export const secondary_disabled = () => (
Disabled
);
```
Stories for the components are located in their `stories/` folder.
## Documentation
Documentation pages are decorated by a React layout using the [@divriots/dockit-react](https://github.com/divriots/dockit-react) helpers. See the `layout` component.
### Pages
Each component embed its own documentation in its `doc/` folder. You can use any web format for your documentation but we recommend you to write it with the [mdx](https://backlight.dev/docs/mdx) format, allowing you to embed your components live in the documentation.
---
## Links
- [System UI](https://system-ui.com/)
- [Theme UI](https://theme-ui.com/)
- [styled-components](https://styled-components.com/)