Cautions

Important cautions when using Atomic CSS. Understanding these helps prevent unexpected issues.

Dynamic Class Binding

Cause

The Atomic CSS extension analyzes source code text at save time to find used class names and generates only the corresponding CSS. Since JavaScript is not executed, strings inside variables cannot be tracked.

<!-- ❌ Class in variable — CSS not generated -->
<script setup>
const boxStyle = "w100px h100px bg6366F1 br8px"
</script>

<div :class="boxStyle"></div>

<!-- ✅ Literal class — CSS generated normally -->
<div class="w100px h100px bg6366F1 br8px"></div>

Dynamic Binding in Frameworks

The same issue occurs when dynamically binding classes in Vue, React, Svelte, etc.

<!-- ❌ v-for + dynamic binding -->
<script setup>
const items = [
  { cls: "bg6366F1 br8px" },
  { cls: "bg34D399 br12px" },
]
</script>

<div v-for="item in items"
     :class="item.cls">
</div>

<!-- ✅ Conditionals also as full strings -->
<div :class="active
  ? 'bg6366F1 cFFFFFF'
  : 'bg27272A c71717A'">
</div>

<!-- ✅ This way both class sets are
     present as literals in source and detected -->

String Concatenation Also Fails

Template literals or string concatenation to build class names are also not detected.

// ❌ Class generated by string concatenation
const size = 16
const cls = `fs${size}px`  // "fs16px"
// → No "fs16px" literal in source

// ❌ Class generated by function
function getBg(color) {
  return `bg${color}`
}
getBg("FF0000")  // "bgFF0000"
// → No "bgFF0000" literal in source

// ✅ Use full class names as literals
const cls = isLarge ? 'fs2rem' : 'fs1-4rem'
// → Both 'fs2rem' and 'fs1-4rem' are detected

// ✅ List as literals in map object
const sizeMap = {
  sm: 'fs1-2rem p8px',
  md: 'fs1-4rem p12px',
  lg: 'fs1-6rem p16px',
}
// → All values exist as literals and are detected

Class Name Conflicts

Atomic CSS creates class names from the initials of CSS properties, so different properties may share the same abbreviation. They are differentiated by presence of units.

Missing Units

Properties that use numeric values must include units. Without units, they may be interpreted as different properties or not work at all.

CSS Cascade Order (Specificity)

All Atomic CSS classes have the same selector specificity (single class). When multiple classes target the same property, the one declared later in the CSS file takes effect. This is not determined by order in the HTML class attribute.

<!-- ⚠️ Which applies, w100px or w200px? -->
<div class="w100px w200px bg18181B p16px">
  Determined by declaration order in CSS file
  (Not by order in HTML class attribute)
</div>

<!-- ✅ Use only one class per property -->
<div class="w200px bg18181B p16px">
  Specify only one clearly
</div>

When you intentionally need to raise priority, use the i suffix which adds !important.

<!-- Add !important with i suffix -->
<div class="w100pxi bg6366F1 p16px">
  width: 100px !important
</div>

<!-- Override external library styles -->
<div class="external-component df jcc aici">
  Force layout with display: flex !important
</div>

rem Base Value

Atomic CSS rem units are designed based on html { font-size: 10px }, meaning 1rem = 10px. Without this setting, rem values will not match their intended sizes.

Add the following to your project's global CSS:

html {
  font-size: 10px;
}

/* Now rem calculations are intuitive */
/* 1.6rem = 16px */
/* 2rem = 20px */
/* 2.4rem = 24px */
/* 10rem = 100px */

Hyphen (-) Interpretation

Hyphens are interpreted differently depending on context. Understanding hyphen roles is essential to prevent unintended results.

Do Not Edit Generated CSS Files

Do not directly edit CSS files auto-generated by the Atomic CSS extension (such as atomic.css). The extension re-scans and overwrites the content on every file save.

Checklist

Check the following when using Atomic CSS.

Related Pages