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
    • Schemes/Types
      • StyledGuideProps
      • ThemeType
      • StyleGuide
      • Colors
      • ColorTokens
      • FontSizes
      • FontWeights
      • Sizes
      • UseThemeType
    • Style helpers
      • getStyleGuide()
      • getColor()
      • getColorByTheme()
      • getFontSize()
      • getFontWeight()
      • getSize()
    • Theme hook
      • useTheme()
  • Contributing
    • Cloning repository
    • Installing dependencies
    • Developing
    • Testing
    • Linting
    • Example Application
  • 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