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

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.example.json
    │   └── 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/**"
}

The Design Token

The design token file is the source of truth for the generated SCSS token map:

src/resources/design/tokens.json

The token script converts that JSON file into:

src/resources/styles/tokens/_tokens.scss

The generated _tokens.scss file exports a $tokens map. src/resources/styles/tokens/_config.scss reads that map and exposes typed SCSS variables such as $colors, $fonts, $headings, $spacing, $border-radius, $box-shadow, $semantic-colors, $z-index, $opacity, and $forms.

Token File Shape

The token file is plain JSON. Keys use the names that the bundled SCSS expects, so keep the top-level names stable unless you also update the SCSS modules that read them.

{
  "unit": "rem",
  "page": {},
  "colors": [],
  "fonts": [],
  "headings": {},
  "spacing": {},
  "borderRadius": {},
  "boxShadow": {},
  "semanticColors": {},
  "zIndex": {},
  "opacity": {},
  "forms": {}
}

Top-level token groups:

• unit: the base unit label used by the design system. The bundled file uses rem.
• page: page-level defaults. backgroundColor, margin, and padding are used by the root/page styles.
• colors: an array of named color entries. Each entry has a type, a CSS color value in color, and an optional shades array.
• fonts: an array of named font entries. Each entry has a type, a font file uri, and supported sizes.
• headings: heading font metadata. It contains a shared type, a font uri, and a variant array with h1 through h6 size values.
• spacing: named spacing scale values.
• borderRadius: named radius values. The generated SCSS exposes this group as $border-radius.
• boxShadow: named CSS shadow values.
• semanticColors: named intent colors for UI states such as success, warning, danger, and info.
• zIndex: named stacking values for layers such as dropdowns, sticky elements, modals, and toasts.
• opacity: named opacity values for disabled, muted, and overlay states.
• forms: form-control tokens split into input, focus, disabled, and error groups.

Colors

Color tokens are an array so the SCSS can generate utility classes from each entry:

{
  "type": "bright-green-100",
  "color": "rgb(146, 191, 48)",
  "shades": [20, 30]
}

For every color entry, src/resources/styles/tokens/_config.scss generates:

.bg-{type}
.fg-{type}

For example, a color with "type": "bright-green-100" creates .bg-bright-green-100 and .fg-bright-green-100.

Fonts

Font tokens describe available text families and sizes:

{
  "type": "main-text-regular",
  "uri": "'../fonts/freesans'",
  "sizes": ["0.75rem", "0.875rem", "1rem", "1.125rem", "1.25rem"]
}

The uri points to the generated resources font path from the compiled CSS. Keep the quotes inside the JSON string when the value should be emitted as a Sass string.

Headings

Heading tokens define the heading font and the size for each heading level:

{
  "type": "heading",
  "uri": "'../fonts/freesansbold'",
  "variant": [
    { "h1": "2.625rem" },
    { "h2": "2rem" },
    { "h3": "1.75rem" },
    { "h4": "1.625rem" },
    { "h5": "1.5rem" },
    { "h6": "1.375rem" }
  ]
}

Forms

Form tokens keep the default, focus, disabled, and error styles together:

{
  "forms": {
    "input": {
      "height": "2.5rem",
      "padding-x": "0.75rem",
      "padding-y": "0.5rem",
      "border": "1px solid #d0d0d0",
      "border-radius": "0.5rem",
      "background-color": "#fff",
      "text-color": "#161616",
      "placeholder-color": "rgba(0, 0, 0, 0.45)"
    },
    "focus": {
      "border": "1px solid #0288d1",
      "outline-color": "rgba(2, 136, 209, 0.32)",
      "outline-width": "0.1875rem"
    },
    "disabled": {},
    "error": {}
  }
}

Use the same hyphenated keys that appear in the bundled example when a CSS property name needs to be represented directly.

Example Token File

A complete example token file is included at:

src/resources/design/tokens.example.json

Use it as a reference when changing tokens.json, or copy it over tokens.json in a generated project before running the token build.

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|ts]:

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.

Flex Mixins

The utility module exposes flex positioning mixins for common layout alignment:

@use './src/resources/styles/utility' as utility;

.toolbar {
  @include utility.flex-center-center;
}

.actions {
  @include utility.flex-top-right;
}

Available named mixins:

flex-top-left
flex-top-center
flex-top-right
flex-center-left
flex-center-center
flex-center-right
flex-bottom-left
flex-bottom-center
flex-bottom-right

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:

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.