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