React Styled Guide

React Styled Guide is a package that offers you an easy way to configure your own style guide and handle theme state in a React application build with Styled-Components.

React Styled Guide
- Requirements
- Installation
- Usage
  - Configure provider
- Examples
  - Style
  - Theme
  - Application
- API
- Contributing
- LICENSE

Requirements

react: >=18.2
styled-components: >=5.3

Installation

Using npm:

$ npm install react-styled-guide

Using yarn:

$ yarn add react-styled-guide

Usage

Configure provider

Once the package is installed, you can import the library using import or require approach:

Step 1: Import package provider (StyledGuideProvider) according to your JavaScript environment;

CommonJS

// index.jsx
const { StyledGuideProvider } = require('react-styled-guide');

ECMAScript

// index.jsx
import { StyledGuideProvider } from 'react-styled-guide';

TypeScript

// index.tsx
import { StyledGuideProvider, StyledGuideProps } from 'react-styled-guide';

Step 2: Create your own StyleGuide using StyledGuideProps schema/type;

CommonJS/ECMAScript:

// index.jsx
const initialStyleGuide = {
  ...
};

TypeScript:

// index.tsx
const initialStyleGuide: StyledGuideProps = {
  ...
};

Step 3: wrap your components with <StyledGuideProvider /> passing the initial state you have just created in previous step;

 // index.tsx
...

const container = document.getElementById('root');
const root = createRoot(container);
root.render(
  <StyledGuideProvider value={initialStyleGuide}>
    {/* add your components here */}
  </StyledGuideProvider>
);

Examples

Style

Set a color of a text:

// text.styles.jsx
import { styled } from 'styled-components';
import { getColor } from 'react-styled-guide';

export const Text = styled.p`
  color: ${getColor(colors => colors.primary.medium)}; // '#01c4e7'
`;

Theme

Set theme to 'dark':

// my-component.jsx
const MyComponent = () => {
  const { setDarkTheme } = useTheme();

  return <Button onClick={setDarkTheme}>SET DARK THEME</Button>;
};

Application

You can also check an entire application in example/ folder:

$ cd example
$ npm i # or yarn to install dependencies
$ npm start # or yarn start

API

Schemes/Types

StyledGuideProps

key	type	required	default
theme	ThemeType	false	-
styleGuide	StyleGuide	true	-

ThemeType

key	value
dark	`'DARK'`
light	`'LIGHT'`

StyleGuide

key	type	required	default
colors	Colors	true	-
fontSizes	FontSizes	true	-
fontWeights	FontWeights	true	-
sizes	Sizes	true	-

Colors

key	type	required	default
primary	ColorTokens	true	-
secondary	ColorTokens	true	-
neutral	ColorTokens	true	-
success	ColorTokens	true	-
warning	ColorTokens	true	-
error	ColorTokens	true	-

ColorTokens

key	type	required	default
darkest	`string`	true	-
darker	`string`	true	-
dark	`string`	true	-
tinyDark	`string`	true	-
medium	`string`	true	-
tinyLight	`string`	true	-
light	`string`	true	-
lighter	`string`	true	-
lightest	`string`	true	-

FontSizes

key	type	required	default
xxxl	`string`	true	-
xxl	`string`	true	-
xl	`string`	true	-
l	`string`	true	-
m	`string`	true	-
s	`string`	true	-
xs	`string`	true	-
xxs	`string`	true	-
xxxs	`string`	true	-

FontWeights

key	type	required	default
bold	`string`	true	-
medium	`string`	true	-
regular	`string`	true	-
light	`string`	true	-

Sizes

key	type	required	default
giant	`string`	true	-
huge	`string`	true	-
xxxl	`string`	true	-
xxl	`string`	true	-
xl	`string`	true	-
l	`string`	true	-
m	`string`	true	-
s	`string`	true	-
xs	`string`	true	-
xxs	`string`	true	-
xxxs	`string`	true	-
nano	`string`	true	-
quark	`string`	true	-

UseThemeType

key	type	description
theme	ThemeType	-
setDarkTheme	`function`	dispatch action to change theme state to `dark`.
setLightTheme	`function`	dispatch action to change theme state to `light`.

Style helpers

getStyleGuide()

Description: Used to access StyleGuide object to get one of its children's value.
Arguments:
- function(StyleGuide) => string | number
Returns: string | number
Example:

import { styled } from 'styled-components';
import { getStyleGuide } from 'react-styled-guide';

export const Text = styled.p`
  color: ${getStyleGuide(
    styleGuide => styleGuide.colors.primary.medium // e.g.: '#01c4e7'
  )};
`;

getColor()

Description: Used to access Colors object to get one of its value.
Arguments:
- function(Colors) => string
Returns: string
Example:

import { styled } from 'styled-components';
import { getColor } from 'react-styled-guide';

export const Text = styled.p`
  color: ${getColor(colors => colors.primary.medium)}; // e.g.: '#01c4e7'
`;

getColorByTheme()

Description: Used to access Colors object to get one of its value according to Theme state.
- The first callback function argument will be called if theme is DARK.
- The second callback function argument will be called if theme is LIGHT.
Arguments:
- function(Colors) => string
- function(Colors) => string
Returns: string
Example:

import { styled } from 'styled-components';
import { getColorByTheme } from 'react-styled-guide';

export const Text = styled.p`
  color: ${getColorByTheme(
    colors => colors.primary.darker, // e.g.: '#3F3F3F'
    colors => colors.primary.lighter // e.g.: '#DADADA'
  )};
`;

getFontSize()

Description: Used to access FontSizes object to get one of its value.
Arguments:
- function(FontSizes) => string
Returns: string
Example:

import { styled } from 'styled-components';
import { getFontSize } from 'react-styled-guide';

export const Text = styled.p`
  front-size: ${getFontSize(fontSizes => fontSizes.xs)}; // e.g.: '14px'
`;

getFontWeight()

Description: Used to access FontWeights object to get one of its value.
Arguments:
- function(FontWeights) => number
Returns: number
Example:

import { styled } from 'styled-components';
import { getFontWeight } from 'react-styled-guide';

export const Text = styled.p`
  front-weight: ${getFontWeight(fontWeights => fontWeights.bold)}; // e.g.: 600
`;

getSize()

Description: Used to access Sizes object to get one of its value.
Arguments:
- function(Sizes) => number
Returns: number
Example:

import { styled } from 'styled-components';
import { getSize } from 'react-styled-guide';

export const Card = styled.div`
  height: ${getSize(sizes => sizes.giant)}; // e.g.: '200px'
  padding: ${getSize(sizes => sizes.xxxs)}; // e.g.: '16px'
`;

Theme hook

useTheme()

Description: Used to get UseThemeType object to access and manipulate theme state.
Arguments: -
Returns: UseThemeType
Example:

import { ThemeTypes, useTheme } from 'react-styled-guide';

export const App = () => {
  const { theme, setDarkTheme, setLightTheme } = useTheme();

  const changeTheme = () => {
    if (theme === ThemeTypes.light) setDarkTheme();
    else setLightTheme();
  };

  return (
    <div>
      <p>
        Current Theme: <span>{theme}</span>
      </p>
      <button onClick={changeTheme}>CHANGE THEME</button>
    </div>
  );
};

Contributing

This package welcomes all constructive contributions. Feel free to add contributions from the following items (but not only) :

bug fixes and enhancements
new features
additions and fixes to documentation
additional tests
triaging incoming pull requests and issues

Cloning repository

$ git clone https://github.com/luizclr/react-styled-guide.git
$ cd react-styled-guide

Installing dependencies

$ yarn install

Developing

Start development server on watch mode:

$ yarn start

Testing

Run test suite:

$ yarn test

Building

Run build script:

$ yarn build

Check dist/ folder to see parsing resulte.

Linting

Run lint script:

$ yarn lint

Example Application

Enter in example/ foder and start development server on watch mode:

$ cd example
$ yarn start

Open a browser and access localhost:1234.

LICENSE

MIT