Design Foundation

Generate and manage tokens, Sass resources, themes, assets, and configuration files that define the visual foundation of your Atomic Design system.

Explore Resources

View on GitHub

Atomic Resources - A SASS/SCSS framework for your design system

only for react, react native doesn't support sass/scss (yet).

All components have their own scss file attached. So you need to install SASS in your project.

Atomic Resources sets up an entire SCSS framework you can control with a single Design Token

install the atomic resources package

In the root of project execute the following command to install the package:

npx create-atomic-resources@latest ./src

This will create a new folder called

./src/resources

with all the necessary files and folders for your design system.

File structure

The package will install several files and folders in the

./src/resources

folder. These include:

/src/resources/design/tokens.json

this is the

Design Token

file. It contains all the design tokens for your design system. You can edit this file to change the values of your design tokens.

/src/resources/fonts/*.[woff,woff2,ttf]

This folder contains all the font files for your design system. You can add or remove font files as needed.

/src/resources/styles/**.[scss]

This folder contains all the SCSS files for your design system. These files are generated based on the values in the

Design Token

file. It's not recommended to edit these files directly, as they will be overwritten when you change the design tokens. Instead, you can edit the

main.scss

file to change the structure of your styles.

/src/resources/styles/main.scss

This is the main SCSS file for your design system. It imports all the other SCSS files and generates the final CSS output. You can edit this file to change the structure of your styles.

Packages

The following packages will be installed as dependencies in your project:

json-to-scss, prettier, sass

These packages are installed into your

package.json

file as dev dependencies. They are used to generate the SCSS files from the design tokens and to format the generated SCSS files.

package.json scripts

The installer will add the following to your scripts in

package.json

"token": "json-to-scss ./src/resources/design/tokens.json ./src/resources/styles/tokens.scss",

"scss": "sass ./src/resources/styles/main.scss ./src/resources/styles/main.css"

This script is used to generate the

tokens.scss

file from the

tokens.json

file. You can run this script whenever you make changes to your design tokens to update the generated SCSS file.

"scss": "sass ./src/resources/styles/main.scss ./src/resources/styles/main.css"

This script is used to compile the SCSS files into a single CSS file. You can run this script whenever you make changes to your SCSS files to update the generated CSS file.

Requirements

A design token is usually a JSON file that contains all the design specs for your project. It's generally used as a developer hand-off from a designer to a developer

You can check Atlassian's design token for more information.

Atomic Resources

Creates a reusable SCSS resources setup for projects that use atomic design, Storybook, and optionally atomic-bomb.

Important This tool is for educational purposes only.

Usage

Run the package from the root of the project that should receive the resources:

npx create-atomic-resources ./src

The command expects one argument:

npx create-atomic-resources <destination-dir>

Example:

npx create-atomic-resources ./src

This creates or updates:

src/

└── resources/

├── design/

│ └── tokens.json

├── fonts/

└── styles/

├── fonts/

├── functions/

├── headings/

├── page/

├── reset/

├── root/

├── tokens/

├── utility/

├── vars/

└── main.scss

What It Does

The installer:

copies the bundled
resources
directory into the destination directory
installs
json-to-scss
,
sass
, and
prettier
as dev dependencies
detects
pnpm-lock.yaml
,
yarn.lock
, or
package-lock.json
to choose the package manager
defaults to
npm
when no lockfile exists
retries npm installs with
--legacy-peer-deps
when npm reports an
ERESOLVE
peer dependency conflict
adds resource scripts to the project
package.json

The generated scripts are:

{

"token": "json-to-scss ./src/resources/design/tokens.json ./src/resources/styles/tokens/_tokens.scss",

"scss": "sass --quiet ./src/resources/styles/main.scss ./src/resources/styles/main.css",

"nice": "prettier -w ./src/**"

}

Requirements

Node.js
npm, pnpm, or Yarn
a
package.json
in the directory where the command is run

The command should be run from the application root, not from inside the destination folder.

Storybook

Import the generated stylesheet in

.storybook/preview.js

import "../src/resources/styles/main.css"

If you install into a different destination directory, adjust the import path to match that directory.

Design Tokens

The design token file should live in:

src/resources/design/tokens.json

After changing

tokens.json

, rebuild the SCSS token file:

npm run token

Then rebuild the compiled stylesheet:

npm run scss

SCSS

The main SCSS entrypoint is:

src/resources/styles/main.scss

The compiled CSS output is:

src/resources/styles/main.css

The bundled SCSS uses Dart Sass modules with

@use

and avoids deprecated global Sass APIs.

With atomic-bomb

When using the generated resources together with

atomic-bomb

, uncomment the component imports in

src/resources/styles/main.scss

/* Uncomment when using atomic-bomb */

//@use '../../components/atoms';

//@use '../../components/molecules';

//@use '../../components/organisms';

//@use '../../components/templates';

//@use '../../components/pages';

Those imports point at the Sass barrel files that

atomic-bomb

creates in each component folder:

src/components/atoms/_index.scss

src/components/molecules/_index.scss

src/components/organisms/_index.scss

src/components/templates/_index.scss

src/components/pages/_index.scss

When

atomic-bomb

creates a component, it appends that component to the matching

_index.scss

barrel. When a generated component is removed with

atomic-bomb --remove [NAME]

, the matching Sass barrel entry is removed as well, so the resource imports in

main.scss

can stay stable.

Manual Installation

You can also clone the repository with [degit](https://www.npmjs.com/package/degit):

degit https://github.com/ReneKrewinkel/create-atomic-resources.git <destination-dir>

The

npx

workflow is preferred because it also installs dependencies and updates

package.json

scripts.

Troubleshooting

npm peer dependency conflicts

If npm reports an

ERESOLVE

peer dependency conflict while installing the helper packages, the installer retries automatically with:

npm install --save-dev --legacy-peer-deps json-to-scss sass prettier

This is useful in projects with strict or outdated peer dependency ranges.

No lockfile detected

When no

pnpm-lock.yaml

yarn.lock

, or

package-lock.json

is found, the installer uses npm.

Custom destination directories

The copied resources follow the destination directory you pass to the CLI. The generated package scripts currently target

./src/resources

, so if you install into another directory, update the generated

token

scss

, and

nice

scripts in your project

package.json

Development

Check the CLI syntax:

npm test

Format the CLI:

npm run nice

Publish workflow:

npm run deploy

deploy

runs

predeploy

, which checks the CLI and bumps the package patch version before pushing commits and tags.