Skip to Content
DocumentationIntroduction

Introduction to AliasCSS

AliasCSS is an open, programmable, deterministic CSS compiler and styling metalanguage. Instead of relying on closed, arbitrary utility vocabularies, AliasCSS maps directly to native CSS rules through a mathematical grammar evaluated strictly from Right to Left (R-to-L).

It unifies native property declarations, DOM combinator traversal, contextual styling via the Magic & anchor, in-line @keyframes authoring, multi-layer effect chaining (__), and markup-driven semantic component extraction (--as-).

Core Architecture: The Three-Tier Pipeline

AliasCSS parses class strings through a deterministic three-tier pipeline evaluated from right to left:

┌──────────────────────────────┬──────────────────────────────┬──────────────────────────────┐
│           Tier 1             │            Tier 2            │            Tier 3            │
│     Block-Level Scopes       │      Selectors & States      │    Property-Value Anchor     │
│   (@media, @container, etc.) │     (--hover, _, __, &)      │     (Core CSS Declaration)   │
├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ @media (min-width: 768px)    │ :hover                       │ background-color: #6366f1    │
│ @container (min-width: 400px)│ > button                     │ opacity: 0                   │
│ @starting-style              │ [disabled]                   │ cursor: not-allowed          │
└──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘
◄─────────────────────────────────────────────────────────────────────────────────────────────
                                 READ & PARSE: RIGHT TO LEFT

  1. Tier 3 — Property-Value Anchor: The core CSS declaration (e.g., padding-16px, display-flex, c-ffffff).

  2. Tier 2 — Selectors & States: Combinators (_, __), pseudo-classes (--hover, --focus), and context anchors (&).

  3. Tier 1 — Block-Level Scopes: Enclosing CSS block constructs such as media queries (@md-), cascade layers (@base-), or container queries (@container-md-).

Key Features

1. Dual Declaration Modes and property function for raw css value

Choose between full, self-documenting CSS property names or high-frequency shorthand aliases:

<!-- Full Semantic Form -->
<div class="display-flex justify-content-center align-items-center background-color-0b0f19 padding-24px"></div>
 
<!-- Canonical Shorthand Form -->
<div class="df jcc aic bgc-0b0f19 p-24px"></div>

Both compile into identical, deduplicated CSS rules.

1.2 Property Function for Raw CSS Values

Use proprty(value) : when standard utilities fall short because native CSS expects parentheses, mathematical expressions, or literal commas.

Above code can be written as:

<!-- Full Semantic Form -->
<div class="display(flex) justify-content(center) align-items(center) background-color(#0b0f19) padding(24px)"></div>
 
<!-- Canonical Shorthand Form -->
<div class="d(flex) jc(center) ai(center) bgc(#0b0f19) p(24px)"></div>

Property(value) function is a universal utility that allows you to write any valid CSS value, including those that require parentheses, mathematical expressions, or literal commas. This is particularly useful for complex CSS properties like transform, filter, and clip-path, where the value may not be easily represented by standard utilities.

<!-- Multi-stop directional linear gradient -->
<div class="background(linear-gradient(135deg,#0f172a,rgba(99,102,241,0.2),transparent))_ min-height-300px border-radius-16px"></div>
 
<!-- Radial spotlight gradient -->
<div class="background(radial-gradient(circle_at_top,#6366f1/0.25,transparent_70%))_ position-absolute top-0 width-100% height-500px"></div>
ℹ️

property(value)_ will preserve the ’,’ inside the value otherwise it will replaced by space. For example, margin(auto,0,-12px,0) will be compiled to margin: auto 0 -12px 0; and margin(auto,0,-12px,0)_ will be compiled to margin: auto, 0, -12px, 0;. `

2. Native DOM Combinator Ladder

Target child and sibling nodes directly from a container without writing bespoke stylesheets:

  • _tag → Descendant space combinator (.parent tag)

  • __tag → Direct child combinator (.parent > tag)

  • ___tag → Adjacent sibling combinator (.parent + tag)

  • ____tag → General sibling combinator (.parent ~ tag)

<article class="_h2-font-size-24px __p-color-64748b">
  <h2>Scoped Heading</h2>
  <p>Direct child styled from parent</p>
</article>

3. Context Inversion via the Magic &

By default, combinators place generated targets after the parent class. Placing & after a selector prefix inverts placement, outputting the selector before the class (tag .class) for parent- or ancestor-aware conditional styling:

<!-- Inverts styling when an ancestor has the .dark class -->
<div class="background-color-ffffff color-000000 _.dark&-[background-color-0b0f19,color-f8fafc]">
  Adaptive Theme Surface
</div>

4. Component Export Engine (--as-)

Bundle atomic utilities and export them into reusable, semantic CSS classes right from your markup—no CSS extraction plugins or separate stylesheets required:

<!-- Define and export reusable .btn class -->
<button class="[border-0,padding-8px-16px,border-radius-6px,font-weight-600,cursor-pointer]--as-btn btn">
  Submit
</button>
 
<!-- Consume anywhere downstream -->
<button class="btn">Cancel</button>

5. Dynamic Transitions, 3D Transforms & Keyframes

  • Chaining with __: The double underscore serves as a delimiter to chain transitions, 3D transforms, and filters into a single declaration:
<div class="tf-rotateX-20deg__rotateY-45deg__translateZ-60px"></div>
<button class="tn-transform-0.2s-ease__box-shadow-0.2s-ease"></button>
  • In-Line Keyframe Timelines: Define multi-step animations directly in HTML attributes:
<div
  keyframes-pulse="@0-[transform-scale-1] @50-[transform-scale-1.05] @100-[transform-scale-1]"
  class="an-pulse adu-2s atf-linear aici @motion-reduce-an-none"
>
  Pulsing Container
</div>

Quick Start & Configuration

Install the AliasCSS CLI and initialize your configuration:

npx aliascss --config

Customize media breakpoints, register design tokens, or extend property compilers in aliascss.config.js:

// aliascss.config.js
export default {
  input: ['src/**/*.{html,jsx,tsx,mdx}'],
  output: {
    location: './public/css/acss.css',
  },
  custom: {
    // Custom colors must use strict CamelCase (no hyphens/underscores)
    colors: {
      brandPrimary: '#6366f1',
      brandHover: '#4f46e5',
      surfaceDark: '#0b0f19',
    },
  },
};
Last updated on
Getting Started