AAtomic CSS

Installation & Usage Guide

Atomic CSS can be used in two ways. VS Code Extension provides autocomplete and real-time CSS generation in the editor, NPM CLI generates CSS from the terminal regardless of editor.

VS Code Extension

Use directly in editor. Autocomplete, hover preview, and real-time CSS file generation all in one.

  • ✓ Class name autocomplete + CSS preview
  • ✓ Hover to see CSS output
  • ✓ Auto CSS generation on file save
  • ✓ Invalid class warnings

NPM CLI

Run from terminal. CSS generation without VS Code. Suitable for CI/CD pipelines.

  • ✓ Editor-independent — run anywhere
  • ✓ build / watch mode support
  • ✓ CI/CD build pipeline integration
  • ✓ Managed via config file (.atomic.json)

VS Code Extension

Install from the Visual Studio Code Marketplace and start using immediately. No build process or additional configuration needed.

Marketplace: https://marketplace.visualstudio.com/items?itemName=Drangon-Knight.atomicss

1. Installation

Install from Marketplace

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "Atomic CSS" (publisher: Drangon-Knight)
  4. Click Install

Install from Terminal

code --install-extension Drangon-Knight.atomicss

Verify Installation

After installation, open any HTML file and type inside the class="" attribute. If the autocomplete list and CSS preview appear, it is working correctly.

2. Key Features

Autocomplete

Type in the class="" attribute to receive real-time class suggestions along with CSS output.

Hover Preview

Hover over a class name to see the generated CSS in a tooltip.

Real-time CSS Generation

When you save or edit a file, atomic.css and atomic.min.css are automatically generated/updated.

Validation

Underlines invalid classes, suggests similar classes, detects property conflicts (distinguishes media/pseudo-class context)

Color Preview

Inline color swatches for 13 color prefixes. HEX/RGBA + hover/media combos, border shorthand colors. Color picker integration.

Quick Fix

Auto-correct typos to similar classes, delete invalid classes, suggest closest token values on violations.

CSS → Class

Input CSS declarations to convert to Atomic classes. Supports colors, font-weight, z-index, opacity, and more.

Sort Classes

Auto-sort classes semantically: display→flex→size→spacing→typography→color. Selection or whole file.

Design Tokens

Define tokens in .atomic.json — they appear first with ★ in autocomplete. Use strict mode for team design systems.

CSS Variable Autocomplete

Scans project CSS/SCSS for :root variables. When typing bg--, actual variable names from your project are suggested.

Unused Class Detection

Detects classes in atomic.css that are not used in any HTML file.

Inline CSS Hints

justify-content

See IDE Features Guide for detailed usage of each feature.

Supported File Formats

HTML, Vue (.vue), React/JSX (.jsx / .tsx), Svelte (.svelte), PHP, JSP, Twig etc. All files that use the class attribute.

3. How It Works

The VS Code extension scans class attributes in HTML whenever you save or edit a file, automatically generating CSS files.

1Write class="df jcc aic" in an HTML file
2Extension parses class names and generates CSS rules
3Auto-saves atomic.css + atomic.min.css to the specified path
✓Link in HTML with <link rel="stylesheet" href="atomic.min.css">

4. Configuration

VS Code Settings

Press Ctrl+, to open Settings and search for "atomic" to find two settings:

SettingDefaultDescription
atomic.cssDirectoryPath/assets/css/commonDirectory path where CSS files are saved
atomic.selectedLanguages["html"]File languages that trigger CSS generation
settings.json (VS Code)
{
    "atomic.cssDirectoryPath": "/assets/css/common",
    "atomic.selectedLanguages": ["html", "vue", "php", "jsp"]
}

Project Config File (.atomic.json)

Create .atomic.json at the project root to override VS Code settings. Useful for sharing settings across team projects.

.atomic.json
{
    "selectedLanguages": ["html"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html"],
    "projects": []
}
PropertyTypeDescription
selectedLanguagesstring[]File languages that trigger CSS generation (e.g., html, vue, php)
cssDirectoryPathstringDirectory path where CSS files are saved (relative to project root)
extensionsstring[]File extensions to scan (e.g., .html, .vue, .jsx)
projectsobject[]Multi-project setup (different output paths per folder)

Multi-project Configuration

When managing multiple projects in one workspace, use the projects array to specify different CSS output paths per folder.

.atomic.json
{
    "selectedLanguages": ["html", "vue", "jsp"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html", ".vue", ".jsp"],
    "projects": [
        {
            "name": "admin",
            "sources": ["/admin/"],
            "output": "/admin/assets/css/"
        },
        {
            "name": "front",
            "sources": ["/front/"],
            "output": "/front/assets/css/"
        }
    ]
}

Behavior: When you edit /admin/pages/login.html, CSS is generated in /admin/assets/css/, and files under /front/ generate CSS independently in /front/assets/css/.

5. Commands & Shortcuts

Press Ctrl+Shift+P to run from the command palette, or use keyboard shortcuts directly:

CommandShortcutDescription
Atomic CSS: Search ClassCtrl+Shift+A
Mac: Cmd+Shift+A		Search Atomic CSS classes by CSS property name. e.g., searching "justify-content" shows related classes like jcc, jcsb, etc.
Atomic CSS: Update AllCtrl+Alt+A
Mac: Cmd+Alt+A		Scans all project files and batch-generates CSS. Useful for initial setup or processing many files.
Atomic CSS: CSS → ClassCtrl+Shift+C
Mac: Cmd+Shift+C		Input CSS declarations to convert them to Atomic classes.
Atomic CSS: Sort ClassesCtrl+Alt+S
Mac: Cmd+Alt+S		Auto-sort classes in class attributes by semantic order.
Atomic CSS: Detect UnusedCommand PaletteDetect classes in CSS files that are not used in HTML.

Note: You generally do not need to run commands manually. CSS updates automatically when you save a file. Ctrl+Shift+A is often used for quick class name lookup when you cannot remember a name.

NPM CLI (atomic-css-cli)

A CLI tool that generates Atomic CSS from the terminal without VS Code. Used when working with build servers, CI/CD pipelines, or editors other than VS Code (WebStorm, Vim, etc.).

NPM: https://www.npmjs.com/package/atomic-css-cli

1. Installation

Global Install (recommended)

Use the atomic-css command anywhere:

npm install -g atomic-css-cli

Project Local Install

Install as a project dependency to use in package.json scripts:

npm install --save-dev atomic-css-cli

Verify Installation

atomic-css --version

2. build -- One-time CSS Generation

Recursively scans the specified directory, extracts Atomic CSS classes from all HTML/Vue/JSX files, and generates CSS files once.

# Scan current directory and generate CSS
atomic-css build .

Options

OptionsAbbreviationDescription
--output <path>-oCSS output directory path. Uses .atomic.json cssDirectoryPath if not specified
--extensions <exts>-eFile extensions to scan, comma-separated (e.g., html,vue,jsx)
--debug-dAlso generates atomic.css (formatted version)
--config <path>-cProject root path containing the .atomic.json file

Usage Examples

# Default: scan current directory, generate CSS at default path
atomic-css build .

# Scan src folder and output to ./css folder
atomic-css build ./src -o ./css

# Scan only html, vue, jsx files
atomic-css build . -e html,vue,jsx

# Debug mode: also generate atomic.css (formatted version)
atomic-css build . --debug

# Build using .atomic.json config from project root
atomic-css build ./src -c ./

# All options combined
atomic-css build ./src -o ./assets/css -e html,vue,jsx -d -c ./

Output

Two files are generated upon build completion:

FileDescription
atomic.cssFormatted CSS (for debugging, generated only with --debug option)
atomic.min.cssMinified CSS (for production, always generated)

3. watch -- Real-time Watch Mode

Detects file changes in real-time and automatically regenerates CSS. Running a terminal during development provides the same experience as the VS Code extension.

# Watch current directory and auto-generate CSS on changes
atomic-css watch .

Exit: Press Ctrl+C to exit watch mode.

Usage Examples

# Default: watch current directory
atomic-css watch .

# Watch src folder and output to ./css folder
atomic-css watch ./src -o ./css

# Watch only specific extensions
atomic-css watch . -e html,vue,jsx

# Debug mode + custom output path
atomic-css watch . -o ./assets/css --debug

build vs watch: build runs once and exits, watch continuously watches for file changes. During development use watch, and in build pipelines use build.

4. init -- Generate Config File

Creates a default .atomic.json config file at the project root.

# Run in project root
atomic-css init

# → .atomic.json file created

Default config generated:

.atomic.json
{
    "selectedLanguages": ["html"],
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html"],
    "projects": []
}

5. package.json Script Integration

If installed locally in the project, registering in package.json scripts is convenient:

package.json
{
    "scripts": {
        "css": "atomic-css watch ./src -o ./assets/css",
        "css:build": "atomic-css build ./src -o ./assets/css",
        "dev": "npm run css & your-dev-server",
        "build": "npm run css:build && your-build-command"
    }
}

Then run as follows:

# Development: run watch mode
npm run css

# Build: one-time CSS generation
npm run css:build

6. CI/CD Pipeline Integration

To auto-generate CSS on the build server, add atomic-css build to the build step:

GitHub Actions Example
# .github/workflows/build.yml
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18

      - run: npm install
      - run: npx atomic-css build ./src -o ./assets/css
      - run: npm run build  # then build the project

Basic HTML Setup

Whichever method you choose, for accurate rem calculations in HTML, set the root font size to 10px:

index.html
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Project</title>
    <style>html { font-size: 10px; }</style>
    <link rel="stylesheet" href="./assets/css/common/atomic.min.css">
</head>
<body>
    <div class="df jcc aic h100vh">
        <h1 class="fs4-8rem fw900 c333333">Hello Atomic CSS</h1>
    </div>
</body>
</html>

CSS generated by the above classes:

ClassGenerated CSS
dfdisplay: flex
jccjustify-content: center
aicalign-items: center
h100vhheight: 100vh
fs4-8remfont-size: 4.8rem
fw900font-weight: 900
c333333color: #333333

rem rule: With html { font-size: 10px } setting, 1rem = 10px. Therefore 4.8rem = 48px, 2rem = 20px.

Framework Integration

Atomic CSS works with any framework — it's just CSS class names.

Vue / Nuxt

<template>
    <div class="df fdc gap2rem p2-4rem maxw80rem mxa">
        <h1 class="fs3-2rem fw800">{{ title }}</h1>
        <p class="fs16px c71717A">{{ description }}</p>
    </div>
</template>

React / Next.js

export default function App() {
    return (
        <div className="df fdc gap2rem p2-4rem maxw80rem mxa">
            <h1 className="fs3-2rem fw800">{title}</h1>
            <p className="fs16px c71717A">{description}</p>
        </div>
    );
}

Svelte

<div class="df fdc gap2rem p2-4rem maxw80rem mxa">
    <h1 class="fs3-2rem fw800">{title}</h1>
    <p class="fs16px c71717A">{description}</p>
</div>

PHP / JSP

<div class="df fdc gap2rem p2-4rem maxw80rem mxa">
    <h1 class="fs3-2rem fw800">{title}</h1>
    <p class="fs16px c71717A">{description}</p>
</div>

Next Steps

Installation is complete. See the documentation below for more detailed usage.

Quick StartNaming ConventionUnit SystemResponsive DesignDisplayFlexbox