Styles Architecture

A robust architectural foundation built upon ITCSS, OOCSS, and modern SCSS practices.

The Inverted Triangle

Atomix follows the ITCSS (Inverted Triangle CSS) methodology to maintain a predictable cascade and minimize specificity conflicts.

Core Principles

By organizing CSS from far-reaching, low-specificity styles to specific, high-specificity utilities, we eliminate the need for `!important` and reduce regression risks.

Increasing Specificity
Styles become more targeted as you move down the layers.
Decreasing Reach
Base styles affect many elements; utilities affect only one.
Explicit Control
Logic moves from abstract patterns to concrete implementations.

Settings

Tools

Generic

Elements

Objects

Components

Utilities

Tokens-to-Styles Workflow

How design decisions flow from abstract tokens into concrete component styles.

1. Define

Design Tokens in Figma

2. Export

Standardized JSON Data

3. Transform

SCSS & CSS Variables

4. Apply

Premium UI Components

Layer Breakdown

Every line of CSS in Atomix belongs to one of these seven layers, ensuring a lean and maintainable codebase.

Settings

Global variables, colors, and configuration. Foundation for the entire system.

Output: NoneSpecificity: N/A

Examples:

$primary: #7c3aed;$spacing-4: 1rem;$breakpoint-md: 768px;

Tools

Mixins, functions, and utilities for generating CSS dynamically.

Output: NoneSpecificity: N/A

Examples:

@mixin media-up($bp) {...}@function spacing($size) {...}

Generic

Far-reaching, low-specificity styles like resets and normalize.

Output: CSSSpecificity: Very Low

Examples:

* { box-sizing: border-box; }:root { --atomix-primary: ... }

Elements

Base styling for bare HTML elements without classes.

Output: CSSSpecificity: Low

Examples:

body { font-family: ... }h1 { font-size: 2rem; }

Objects

Layout patterns and structural components (OOCSS).

Output: CSSSpecificity: Medium

Examples:

.o-container { ... }.o-grid { display: grid; }

Components

Specific UI components with modifiers and variants.

Output: CSSSpecificity: High

Examples:

.c-btn { ... }.c-card__header { ... }

Utilities

Single-purpose helper classes with highest specificity.

Output: CSSSpecificity: Highest

Examples:

.u-m-4 { margin: 1rem !important; }.u-text-center { ... }

Atomic Design Integration

How we map UI components to Atomic Design principles for better modularity.

Atoms

Basic building blocks: Buttons, Inputs, Badges, and Icons. They cannot be broken down further without losing functionality.

Molecules

Groups of atoms bonded together: Form groups, Search bars, and Card headers. They perform simple, specific tasks.

Organisms

Complex UI components: Navigation bars, Data tables, and Modals. They represent distinct sections of an interface.

Technical Benefits

Cascade PredictabilityStyles are applied in a logical order, reducing unexpected overrides.
Zero Specificity WarsEliminates the need for deep nesting and `!important` flags.
Performance OptimizedSmaller CSS payloads and faster browser rendering times.

Modern Capabilities

SCSS Module SystemUsing `@use` and `@forward` for encapsulated styling.
Dynamic ThemingLeveraging CSS Custom Properties for runtime theme switching.
Native Dark ModeBuilt-in support for light and dark color schemes.

Theming & Customization

Atomix is designed to be fully rebranded without touching the core library styles.

SCSS Customization

Override system variables at compile-time to change colors, typography, or spacing globally.

// main.scss
@use 'atomix/styles' with (
  $primary: #6366f1,
  $border-radius-base: 0.5rem,
  $font-family-base: ('Inter', sans-serif)
);

Runtime Overrides

Use CSS variables for dynamic changes like branding or dashboard colors.

:root {
  --atomix-primary: #f59e0b;
  --atomix-surface: #ffffff;
}

[data-theme='dark'] {
  --atomix-surface: #0f172a;
}

File Organization

Following a strict directory structure for maximum scalability.

Directory Structure

01-settings/ (Vars, Maps)

02-tools/ (Mixins, Functions)

03-generic/ (Reset, Normalize)

04-elements/ (Base tags)

05-objects/ (Grid, Layout)

06-components/ (Component UI)

99-utilities/ (Helper classes)

Naming Conventions

We use strict prefixes to distinguish between architectural layers:

.o-*Objects (e.g., .o-container)

.c-*Components (e.g., .c-button)

.u-*Utilities (e.g., .u-m-4)

.is-*, .has-*States (e.g., .is-active)

BEM Naming Convention

We use the Block Element Modifier convention to maintain modularity and avoid side effects.

The Syntax

.c-block

The standalone entity (e.g., .c-card, .c-btn).

.c-block__element

Parts of a block (e.g., .c-card__title, .c-btn__icon).

.c-block--modifier

Variations (e.g., .c-card--glass, .c-btn--primary).

Code Example

<div className="c-card c-card--glass">
  <div className="c-card__header">
    <h3 className="c-card__title">Title</h3>
  </div>
  <div className="c-card__body">
    <button className="c-btn c-btn--primary">
      Action
    </button>
  </div>
</div>

Governance & Best Practices

Guidelines for contributing to the Atomix styling ecosystem.

The "Do" List

Always use CSS variables for colors and spacing.
Prefer utility classes for one-off layouts.
Follow BEM naming convention for components.
Keep component files under 200 lines.

The "Avoid" List

Never use IDs for styling.
Avoid deep nesting (max 3 levels).
Do not use `!important` unless in utilities.
No hard-coded magic numbers for spacing.

Styles Architecture

A robust architectural foundation built upon ITCSS, OOCSS, and modern SCSS practices.

The Inverted Triangle

Atomix follows the ITCSS (Inverted Triangle CSS) methodology to maintain a predictable cascade and minimize specificity conflicts.

Core Principles

By organizing CSS from far-reaching, low-specificity styles to specific, high-specificity utilities, we eliminate the need for `!important` and reduce regression risks.

Increasing Specificity
Styles become more targeted as you move down the layers.
Decreasing Reach
Base styles affect many elements; utilities affect only one.
Explicit Control
Logic moves from abstract patterns to concrete implementations.

Settings

Tools

Generic

Elements

Objects

Components

Utilities

Tokens-to-Styles Workflow

How design decisions flow from abstract tokens into concrete component styles.

1. Define

Design Tokens in Figma

2. Export

Standardized JSON Data

3. Transform

SCSS & CSS Variables

4. Apply

Premium UI Components

Layer Breakdown

Every line of CSS in Atomix belongs to one of these seven layers, ensuring a lean and maintainable codebase.

Settings

Global variables, colors, and configuration. Foundation for the entire system.

Output: NoneSpecificity: N/A

Examples:

$primary: #7c3aed;$spacing-4: 1rem;$breakpoint-md: 768px;

Tools

Mixins, functions, and utilities for generating CSS dynamically.

Output: NoneSpecificity: N/A

Examples:

@mixin media-up($bp) {...}@function spacing($size) {...}

Generic

Far-reaching, low-specificity styles like resets and normalize.

Output: CSSSpecificity: Very Low

Examples:

* { box-sizing: border-box; }:root { --atomix-primary: ... }

Elements

Base styling for bare HTML elements without classes.

Output: CSSSpecificity: Low

Examples:

body { font-family: ... }h1 { font-size: 2rem; }

Objects

Layout patterns and structural components (OOCSS).

Output: CSSSpecificity: Medium

Examples:

.o-container { ... }.o-grid { display: grid; }

Components

Specific UI components with modifiers and variants.

Output: CSSSpecificity: High

Examples:

.c-btn { ... }.c-card__header { ... }

Utilities

Single-purpose helper classes with highest specificity.

Output: CSSSpecificity: Highest

Examples:

.u-m-4 { margin: 1rem !important; }.u-text-center { ... }

Atomic Design Integration

How we map UI components to Atomic Design principles for better modularity.

Atoms

Basic building blocks: Buttons, Inputs, Badges, and Icons. They cannot be broken down further without losing functionality.

Molecules

Groups of atoms bonded together: Form groups, Search bars, and Card headers. They perform simple, specific tasks.

Organisms

Complex UI components: Navigation bars, Data tables, and Modals. They represent distinct sections of an interface.

Technical Benefits

Cascade PredictabilityStyles are applied in a logical order, reducing unexpected overrides.
Zero Specificity WarsEliminates the need for deep nesting and `!important` flags.
Performance OptimizedSmaller CSS payloads and faster browser rendering times.

Modern Capabilities

SCSS Module SystemUsing `@use` and `@forward` for encapsulated styling.
Dynamic ThemingLeveraging CSS Custom Properties for runtime theme switching.
Native Dark ModeBuilt-in support for light and dark color schemes.

Theming & Customization

Atomix is designed to be fully rebranded without touching the core library styles.

SCSS Customization

Override system variables at compile-time to change colors, typography, or spacing globally.

// main.scss
@use 'atomix/styles' with (
  $primary: #6366f1,
  $border-radius-base: 0.5rem,
  $font-family-base: ('Inter', sans-serif)
);

Runtime Overrides

Use CSS variables for dynamic changes like branding or dashboard colors.

:root {
  --atomix-primary: #f59e0b;
  --atomix-surface: #ffffff;
}

[data-theme='dark'] {
  --atomix-surface: #0f172a;
}

File Organization

Following a strict directory structure for maximum scalability.

Directory Structure

01-settings/ (Vars, Maps)

02-tools/ (Mixins, Functions)

03-generic/ (Reset, Normalize)

04-elements/ (Base tags)

05-objects/ (Grid, Layout)

06-components/ (Component UI)

99-utilities/ (Helper classes)

Naming Conventions

We use strict prefixes to distinguish between architectural layers:

.o-*Objects (e.g., .o-container)

.c-*Components (e.g., .c-button)

.u-*Utilities (e.g., .u-m-4)

.is-*, .has-*States (e.g., .is-active)

BEM Naming Convention

We use the Block Element Modifier convention to maintain modularity and avoid side effects.

The Syntax

.c-block

The standalone entity (e.g., .c-card, .c-btn).

.c-block__element

Parts of a block (e.g., .c-card__title, .c-btn__icon).

.c-block--modifier

Variations (e.g., .c-card--glass, .c-btn--primary).

Code Example

<div className="c-card c-card--glass">
  <div className="c-card__header">
    <h3 className="c-card__title">Title</h3>
  </div>
  <div className="c-card__body">
    <button className="c-btn c-btn--primary">
      Action
    </button>
  </div>
</div>

Governance & Best Practices

Guidelines for contributing to the Atomix styling ecosystem.

The "Do" List

Always use CSS variables for colors and spacing.
Prefer utility classes for one-off layouts.
Follow BEM naming convention for components.
Keep component files under 200 lines.

The "Avoid" List

Never use IDs for styling.
Avoid deep nesting (max 3 levels).
Do not use `!important` unless in utilities.
No hard-coded magic numbers for spacing.

Getting Started

Documentation

Resources

Community

Styles Architecture

The Inverted Triangle

Core Principles

Increasing Specificity

Decreasing Reach

Explicit Control

Tokens-to-Styles Workflow

1. Define

2. Export

3. Transform

4. Apply

Layer Breakdown

Settings

Tools

Generic

Elements

Objects

Components

Utilities

Atomic Design Integration

Atoms

Molecules

Organisms

Technical Benefits

Modern Capabilities

Theming & Customization

SCSS Customization

Runtime Overrides

File Organization

Directory Structure

Naming Conventions

BEM Naming Convention

The Syntax

Code Example

Governance & Best Practices

The "Do" List

The "Avoid" List

Styles Architecture

The Inverted Triangle

Core Principles

Increasing Specificity

Decreasing Reach

Explicit Control

Tokens-to-Styles Workflow

1. Define

2. Export

3. Transform

4. Apply

Layer Breakdown

Settings

Tools

Generic

Elements

Objects

Components

Utilities

Atomic Design Integration

Atoms

Molecules

Organisms

Technical Benefits

Modern Capabilities

Theming & Customization

SCSS Customization

Runtime Overrides

File Organization

Directory Structure

Naming Conventions

BEM Naming Convention

The Syntax

Code Example

Governance & Best Practices

The "Do" List

The "Avoid" List