English | 한국어

Atomic CSS

Auto-generate CSS rules from HTML class names. One naming rule covers every CSS property — no config files, no predefined values, total freedom.

Works with Any Project

Atomic CSS integrates into any existing project without touching your current CSS.

Key principle: load atomic.min.css last.

<!-- Your existing CSS -->
<link rel="stylesheet" href="/css/framework.css" />
<link rel="stylesheet" href="/css/custom.css" />

<!-- Atomic CSS always last → highest priority -->
<link rel="stylesheet" href="/assets/css/common/atomic.min.css" />

Works the same with React, Vue, or any import-based setup — just import it last.

Why Atomic CSS?

• Zero CSS writing — class names ARE the styles. No separate CSS files needed.
• Unlimited freedom — unlike other utility frameworks, no predefined value constraints. gap37px, w847px, fs1-3rem — any value works.
• One rule to learn — combine the first letters of CSS property and value. Once you know the pattern, you can guess any class.
• 14 responsive breakpoints — from QHD (2560px) to Ultra Small (420px).
• 32 pseudo-classes — hover, focus, disabled, valid, and more — all via prefix.
• Zero dependencies — just install the extension and start using it.
• AI-native — built-in MCP server lets AI tools query classes in real-time.

Core Concept

Combine the first letters of CSS property and value:

display: flex           → df
justify-content: center → jcc
align-items: center     → aic
flex-direction: column  → fdc
white-space: nowrap     → wsn
text-overflow: ellipsis → toe
object-fit: cover       → ofc

Know this rule, and you can infer any class — even ones not in the docs.

<div class="df jcc aic gap2rem p2rem bgFFFFFF br8px">Hello Atomic CSS!</div>

Generated CSS:

.df { display: flex; }
.jcc { justify-content: center; }
.aic { align-items: center; }
.gap2rem { gap: 2rem; }
.p2rem { padding: 2rem; }
.bgFFFFFF { background-color: #ffffff; }
.br8px { border-radius: 8px; }

Installation

VS Code Extension

Search "Atomic CSS" in VS Code Marketplace, or install via CLI:

code --install-extension Drangon-Knight.atomicss

CLI (npm)

For non-VSCode workflows, CI/CD pipelines, or build scripts:

# Global install
npm install -g atomic-css-cli

# Or project-local
npm install --save-dev atomic-css-cli

Usage:

# One-time build
atomic-css build ./src

# Watch mode (auto-rebuild on file changes)
atomic-css watch ./src

# With options
atomic-css watch ./src --output ./public/css --extensions .html,.tsx,.vue --debug

MCP Server (AI Integration)

Add to your project root .mcp.json — no local install needed:

{
    "mcpServers": {
        "atomic-css": {
            "type": "sse",
            "url": "https://mcp.atomiccss.dev/sse"
        }
    }
}

Works with Claude Code, Cursor (.cursor/mcp.json), and Windsurf (.windsurf/mcp.json).

Configuration (.atomic.json)

Create .atomic.json at project root for custom behavior. Without it, defaults apply.

| Option | Type | Default | Description | |--------|------|---------|-------------| | cssDirectoryPath | string | "/assets/css/common/" | Output path for generated CSS | | extensions | string[] | [".html"] | File extensions to scan for classes | | selectedLanguages | string[] | ["html"] | VSCode language IDs for auto-update on save | | projects | array | — | Multi-project config for separate CSS outputs |

Examples:

// React / Next.js
{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".tsx", ".jsx"],
    "selectedLanguages": ["html", "typescriptreact", "javascriptreact"]
}

// Vue / Nuxt
{
    "cssDirectoryPath": "/src/assets/css/",
    "extensions": [".html", ".vue"],
    "selectedLanguages": ["html", "vue"]
}

// Multi-project (separate CSS per directory)
{
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html", ".php"],
    "projects": [
        { "name": "korean", "sources": ["/src/ko/"], "output": "/assets/css/ko/" },
        { "name": "english", "sources": ["/src/en/"], "output": "/assets/css/en/" }
    ]
}

IDE Features (VS Code)

Hover Preview

Hover over any class to see the full CSS rule. Hover over class keyword to see all classes combined.

Autocomplete

300+ fixed classes, prefix guides, real-time validation, context-aware suggestions (e.g., flex-related classes after df), duplicate prevention.

Color Preview

Inline color swatches for 13 color prefixes. Click swatch → color picker → class auto-updates.

Diagnostics & Quick Fix

Invalid classes get yellow underlines with Levenshtein-based suggestions. Ctrl+. for auto-correction.

Design Token System

Define tokens in .atomic.json (colors, spacing, fontSize, etc.). strict: true enforces team design system.

Commands & Shortcuts

| Command | Shortcut | Description | |---------|----------|-------------| | Search Class | Ctrl+Shift+A | Search classes by CSS property, insert on select | | Update All | Ctrl+Alt+A | Scan all project files and regenerate CSS | | CSS → Class | Ctrl+Shift+C | Convert CSS declarations to Atomic classes | | Sort Classes | Ctrl+Alt+S | Auto-sort classes by semantic order | | Detect Unused | Command Palette | Find CSS selectors not used in HTML |

Naming Rules

Units

| Unit | Notation | Example | |------|----------|---------| | px | px | w100px, gap8px | | % | p | w50p → width: 50% | | rem | rem | fs1-5rem → font-size: 1.5rem | | em | em | p1em | | vh / vw | vh, vw | h100vh, w100vw | | vmin / vmax | vmin, vmax | w50vmin | | fr | fr | gtc1fr-2fr |

Based on html { font-size: 10px }: 1rem = 10px → 2rem = 20px, 10rem = 100px

Hyphens (-)

| Use | Example | Result | |-----|---------|--------| | Decimal | gap1-5rem | 1.5rem | | Value separator | gtc1fr-2fr-1fr | 1fr 2fr 1fr | | Media prefix | sm-dn | @media(max-width:768px) | | Pseudo-class | hover-bg000000 | :hover |

Special Notation

| Notation | Meaning | Example | Result | |----------|---------|---------|--------| | i suffix | !important | w100pxi | width: 100px !important | | neg- prefix | Negative value | neg-mt10px | margin-top: -10px |

Display

| Class | CSS | |-------|-----| | df | display: flex | | dif | display: inline-flex | | dg | display: grid | | db | display: block | | dib | display: inline-block | | di | display: inline | | dn | display: none | | dt | display: table | | dtc | display: table-cell |

Flexbox

| Class | CSS | |-------|-----| | fdr / fdrr | flex-direction: row / row-reverse | | fdc / fdcr | flex-direction: column / column-reverse | | fwn / fww / fwr | flex-wrap: nowrap / wrap / wrap-reverse | | jcfs / jcfe / jcc | justify-content: flex-start / flex-end / center | | jcsb / jcsa / jcse | justify-content: space-between / around / evenly | | ais / aifs / aife / aic | align-items: stretch / flex-start / flex-end / center | | fs0 / fs1 | flex-shrink: 0 / 1 | | fg1 / fg2 | flex-grow: 1 / 2 | | flex1-1-auto | flex: 1 1 auto |

Grid

| Pattern | Example | CSS | |---------|---------|-----| | Direct | gtc1fr-2fr-1fr | grid-template-columns: 1fr 2fr 1fr | | repeat | gtcr3-1fr | repeat(3, 1fr) | | auto-fit | gtcrfit-minmax28rem-1fr | repeat(auto-fit, minmax(28rem, 1fr)) | | auto-fill | gtcrfill-minmax250px-1fr | repeat(auto-fill, minmax(250px, 1fr)) | | Rows | gtrauto-1fr-auto | grid-template-rows: auto 1fr auto | | minmax | gtcminmax100px-1fr | minmax(100px, 1fr) | | calc | gtccalc100p-200px-1fr | calc(100% - 200px) 1fr |

calc (Arithmetic)

Works with any unit property (width, height, margin, padding, top, etc.):

| Pattern | Example | CSS | |---------|---------|-----| | Subtract (default) | wcalc100p-200px | width: calc(100% - 200px) | | Add | wcalc-add50p-100px | width: calc(50% + 100px) | | Multiply | wcalc-mul2rem-3 | width: calc(2rem * 3) | | Divide | wcalc-div100p-3 | width: calc(100% / 3) |

Spacing

| Pattern | Property | |---------|----------| | m, mt, mr, mb, ml | margin (directional) | | p, pt, pr, pb, pl | padding (directional) | | gap, rg, cg | gap, row-gap, column-gap | | mta, mra, mba, mla | margin-direction: auto |

Spacing values in multiples of 4 recommended: 4px, 8px, 12px, 16px, 2rem...

Shorthand expansion: p, m, gap, bw are internally expanded to longhand. So p20px pl10px correctly overrides only padding-left, regardless of order.

Color

| Pattern | Example | CSS | |---------|---------|-----| | c + HEX | cFFFFFF | color: #FFFFFF | | bg + HEX | bg000000 | background-color: #000000 | | bc + HEX | bcDDDDDD | border-color: #DDDDDD | | RGBA | c255-0-0-50 | color: rgba(255,0,0,0.5) | | RGBA bg | bg0-0-0-80 | background-color: rgba(0,0,0,0.8) | | Opacity | o50, o80 | opacity: 0.5, opacity: 0.8 |

CSS Variables (Custom Properties)

Use prefix--variable-name pattern for var():

<div class="bg--box-color gap--spacing br--radius">

Supports all prefixes: colors (c--, bg--, bc--), sizing (w--, h--), spacing (gap--, p--, m--), typography (fs--, fw--), and more. Works with media queries, pseudo-classes, !important, ::before/::after, and relationship selectors.

Border

| Pattern | Example | CSS | |---------|---------|-----| | Shorthand | b1pxsolidDDDDDD | border: 1px solid #DDDDDD | | Directional | bt2pxdashed000000 | border-top: 2px dashed #000000 | | Radius | br8px, br50p | border-radius | | None | bn | border: none |

Shadow

| Pattern | Example | CSS | |---------|---------|-----| | Box Shadow (HEX) | bs2px4px10px0pxFF0000 | box-shadow: 2px 4px 10px 0px #FF0000 | | Box Shadow (RGBA) | bs0px4px12px0px0-0-0-10 | box-shadow: 0px 4px 12px 0px rgba(0,0,0,0.1) | | Inset | bsi0px2px4px0px000000 | box-shadow: inset 0px 2px 4px 0px #000000 | | Text Shadow | ts2px-2px-4px-DDDDDD | text-shadow: 2px 2px 4px #DDDDDD | | None | bsn | box-shadow: none |

Transform

| Class | CSS | |-------|-----| | ttx10px | transform: translateX(10px) | | tty2-5rem | transform: translateY(2.5rem) | | neg-ttx50p | transform: translateX(-50%) | | tr45deg | transform: rotate(45deg) | | ts1-5 | transform: scale(1.5) |

Transition

| Class | CSS | |-------|-----| | tall200msease | transition: all 200ms ease | | topacity500ms | transition: opacity 500ms | | tnone | transition: none |

Filter / Backdrop Filter

| Class | CSS | |-------|-----| | filterb5px | filter: blur(5px) | | filterbr120p | filter: brightness(120%) | | filterc80p | filter: contrast(80%) | | filtern | filter: none | | bfb10px | backdrop-filter: blur(10px) |

Media Queries (14 Breakpoints)

Prefix any class for responsive behavior:

| Prefix | Breakpoint | | Prefix | Breakpoint | |--------|------------|---|--------|------------| | qh- | 2560px | | rg- | 1080px | | uh- | 2160px | | md- | 1024px | | kk- | 2048px | | sm- | 768px | | fh- | 1920px | | es- | 640px | | hl- | 1800px | | us- | 420px | | sl- | 1700px | | | | | ul- | 1600px | | | | | el- | 1440px | | | | | lg- | 1280px | | | |

<!-- 3 columns → 2 → 1 -->
<div class="dg gtcr3-1fr md-gtcr2-1fr sm-gtc1fr gap2rem">
    <div class="db sm-dn">Desktop only</div>
    <div class="dn sm-db">Mobile only</div>
</div>

Pseudo-Classes (32)

| Category | Prefixes | |----------|----------| | Interaction | hover-, focus-, active-, focus-within-, focus-visible- | | Input state | disabled-, enabled-, checked-, indeterminate- | | Form validation | valid-, invalid-, required-, optional-, in-range-, out-of-range- | | Link | link-, visited-, any-link-, target- | | Other | placeholder-shown-, empty-, read-only-, fullscreen-, autofill-, modal-, etc. |

Pseudo-Elements & Relationship Selectors

Pseudo-elements: before-, after-

Relationship selectors:

| Combinator | Keyword | CSS | |------------|---------|-----| | > direct child | child | .parent:hover > target | | descendant | children | .parent:hover target | | + adjacent | next | .trigger:hover + target | | ~ general sibling | siblings | .trigger:hover ~ target |

<!-- On card hover, scale child img -->
<div class="card-hover-child-img-ts1-1"></div>

More Classes

| Class | CSS | |-------|-----| | ar16-9 | aspect-ratio: 16/9 | | lc3-1-5rem | Line clamp (3 lines) | | fw100~fw900 | font-weight | | zi10, zi999 | z-index | | w100p, h100vh | width: 100%, height: 100vh | | wa, ha | width: auto, height: auto | | mxa | margin-left: auto; margin-right: auto | | cp | cursor: pointer | | usn | user-select: none | | pen | pointer-events: none | | oh | overflow: hidden | | wsn | white-space: nowrap | | toe | text-overflow: ellipsis |

Examples

Flexbox Center

<div class="df jcc aic gap2rem p2rem">
    <span>Centered content</span>
</div>

Responsive Grid Cards

<div class="dg gtcrfit-minmax28rem-1fr gap2rem p2rem">
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">Card 1</div>
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">Card 2</div>
    <div class="bgFFFFFF br8px p2rem bs0px4px12px0px0-0-0-10">Card 3</div>
</div>

Glassmorphism

<div class="bfb10px bg255-255-255-20 br16px p2-4rem">
    <h2 class="fs2-4rem fw700 mb16px cFFFFFF">Title</h2>
    <p class="fs1-6rem lh1-6 c255-255-255-80">Content</p>
</div>

Hover Button

<button class="p12px-2-4rem bg007BFF cFFFFFF br8px fs1-6rem fw600
    cp tall200msease hover-bg0056B3 active-ts0_98
    md-p8px-2rem md-fs1-4rem">
    Click me
</button>

Full-Screen Layout

<div class="dg gtrauto-1fr-auto h100vh">
    <header class="p16px bg000000 cFFFFFF">Header</header>
    <main class="p2rem oa">Content</main>
    <footer class="p16px bgF0F0F0">Footer</footer>
</div>

Sidebar Layout

<div class="dg gtc25rem-1fr gap2rem md-gtc1fr">
    <aside class="p2rem bgF5F5F5 md-order2">Sidebar</aside>
    <main class="p2rem md-order1">Content</main>
</div>

MCP Server — AI Integration

AI tools can query Atomic CSS classes in real-time via MCP (Model Context Protocol).

No guessing, no stale docs — AI queries the server directly for accurate, up-to-date results.

6 Tools

| Tool | Description | |------|-------------| | get_guide | Full rules guide (call once for AI onboarding) | | css_to_classes | Convert CSS declarations → Atomic classes | | validate_classes | Validate classes + suggest fixes for invalid ones | | lookup_class | Class name → generated CSS | | search_by_css | Search by CSS property/value | | list_classes | Browse classes by category |

Setup

// .mcp.json (project root)
{
    "mcpServers": {
        "atomic-css": {
            "type": "sse",
            "url": "https://mcp.atomiccss.dev/sse"
        }
    }
}

| AI Tool | Config File | |---------|-------------| | Claude Code | .mcp.json | | Cursor | .cursor/mcp.json | | Windsurf | .windsurf/mcp.json |

CLI Reference

Commands

# One-time build
atomic-css build <directory>

# Watch mode
atomic-css watch <directory>

Options

| Option | Default | Description | |--------|---------|-------------| | --output, -o | .atomic.json config | CSS output directory | | --extensions, -e | .html | File extensions to scan (comma-separated) | | --debug, -d | false | Generate both atomic.css and atomic.min.css |

Config (.atomic.json)

CLI respects the same .atomic.json as the VS Code extension. Place it at project root:

{
    "cssDirectoryPath": "/assets/css/common/",
    "extensions": [".html", ".tsx", ".vue"]
}

Programmatic API

const { build, watch } = require('atomic-css-cli');

// One-time build
const result = await build('./src', {
    output: './public/css',
    extensions: ['.html', '.tsx']
});

// Watch mode
watch('./src', { extensions: ['.html', '.vue'], debug: true });

Links

| | Link | Description | |---|------|-------------| | Web | atomiccss.dev | Official docs — full class reference, live preview | | MCP | mcp.atomiccss.dev | AI MCP server — instant integration | | Marketplace | VS Code Marketplace | VS Code extension | | npm | atomic-css-cli | CLI tool | | Registry | io.github.Yoodaekyung/atomic-css | Official MCP Registry |

Support

[email protected]