Skip to Content

Welcome to AliasCSS

AliasCSS is a programmable, deterministic CSS compiler and styling metalanguage. It maps CSS concepts directly into a strict class grammar parsed right to left.

The core model is:

[Block-Level @-Scopes] + [Selectors / States / Combinators] + [Property-Value Anchor]

The rightmost property-value anchor is the foundation. Everything to its left modifies where or when that declaration applies.

1.Load AliasCSS

For a browser/CDN setup:

<script defer src="https://cdn.jsdelivr.net/npm/aliascss@latest/dist/aliascss.js"></script>

Then write normal CSS knowledge directly as AliasCSS class tokens.

<div class="display-flex padding-24px background-color-18181b color-ffffff">
  Hello AliasCSS
</div>

The basic translation is deterministic:

display: flex;                  → display-flex
padding: 24px;                  → padding-24px
background-color: #18181b;      → background-color-18181b
color: #ffffff;                 → color-ffffff

Think in CSS

AliasCSS does not require replacing CSS concepts with an unrelated vocabulary.

CSS                                      AliasCSS

display: flex;                           display-flex
justify-content: center;                 justify-content-center
align-items: center;                     align-items-center
padding: 16px 24px;                      padding-16px-24px
border-radius: 8px;                       border-radius-8px
background-color: #6366f1;               background-color-6366f1
margin-top: -16px;                       margin-top--16px

Shorthands are available for common properties:

display-flex              → df / d-flex
justify-content-center    → jcc
align-items-center        → aic
padding-16px-24px         → p-16px-24px
background-color-ffffff   → bgc-ffffff
color-333333              → c-333333

2. Core Grammar

Right-to-left evaluation

Every valid AliasCSS class terminates at a CSS property-value anchor.

Tier 1                         Tier 2                         Tier 3

Block-Level @-Scope            Selectors / States             Property-Value
@media                         --hover                        background-color-6366f1
@container                     _tag                            opacity-0
@layer                         __tag                           cursor-pointer
@starting-style                &                               padding-16px

                         ← READ & PARSE RIGHT TO LEFT

Universal invariant

No property-value pair = no valid AliasCSS class.

The rightmost segment is always the primary CSS declaration. Tokens to its left modify its selector, state, scope, or context.

Delimiters

TokenRoleExample
-Property/value and value token delimiterbackground-color-red
--Negative value / variable / state prefixmargin-top--16px
/Decimal alpha modifierbackground-color-ffffff/0.08
. or dDecimal pointfont-size-1.5rem, line-height-1d4
__Chaining / multi-rule delimitertn-opacity-0.2s__transform-0.2s
[...]Declaration grouping[padding-16px,color-white]
_ suffixLiteral comma preservationgrid-template-columns(...)_

Alpha invariant

Alpha values use decimal notation:

background-color-ffffff/0.08
color-000000/0.5
border-color-ffffff/0.1

Whole integer alpha values such as /80 are not valid AliasCSS alpha notation.

3. Properties & Values

AliasCSS supports three declaration modes.

Semantic mode

Semantic property names are the recommended default.

<div class="
  display-flex
  flex-direction-column
  justify-content-space-between
  align-items-center
  border-radius-12px
  background-color-ffffff
">
</div>

Shorthand mode

Common layout properties have canonical shorthand aliases.

PropertyShorthandExample
widthww-100%
heighthh-100vh
max-widthxwxw-1200px
min-widthmwmw-320px
marginmm-0px-auto
paddingpp-16px-24px
displayd, df, dgd-flex, df
borderbb-1px-s-e2e8f0
border-radiusbrbr-8px
colorcc-333333
background-colorbgcbgc-ffffff
transformtftf-tx-10px

fs is not a generic free-form value vocabulary. Use the documented font-size-* grammar or a supported shorthand/value mapping.

Property functions

When normal token grammar cannot represent a value, use:

property(raw_value)

This is the last resort for CSS raw values.

Examples:

<div class="background(linear-gradient(135deg,red_30%,blue_60%))_"></div>
<div class="grid-template-columns(repeat(3,minmax(280px,1fr)))_"></div>

Function spacing

Underscores inside a property function represent spaces.

margin(10px_20px)

becomes:

margin: 10px 20px;

Literal commas

A trailing _ preserves literal commas:

background(linear-gradient(135deg,red_30%,blue_60%))_

becomes:

background: linear-gradient(135deg, red 30%, blue 60%);

4. Selectors, States & Attributes

AliasCSS embeds selector logic directly in the class grammar.

Combinator ladder

_       descendant
__      direct child
___     adjacent sibling
____    general sibling

Examples:

<article class="
  display-flex
  __h3-font-size-20px
  __h3-font-weight-700
  __p-color-64748b
">
  <h3>Scoped heading</h3>
  <p>Scoped paragraph.</p>
</article>

Compiled conceptually as:

.parent > h3 {
  font-size: 20px;
  font-weight: 700;
}
 
.parent > p {
  color: #64748b;
}

Descendant grouping

<div class="_h3[font-size-18px,font-weight-700,color-ffffff]">
  <h3>Grouped heading</h3>
</div>

Attribute selectors

Attribute values are unquoted inside AliasCSS class names.

[data-state=open]-display-none
[type=button][data-state=open]-background-color-6366f1
_[data-state=open]-color-red
__[data-state=open]-color-red

Do not write:

[data-state="open"]

inside the AliasCSS class token. The compiler inserts the CSS quotes in the emitted selector.

Pseudo-classes

All pseudo states use the -- prefix.

--hover-color-6366f1
--focus-visible-outline-none
--active-transform-scale-0.98
--disabled-opacity-0.5
--checked-background-color-6366f1

Grouped states:

<button class="
  background-color-ffffff
  color-000000
  --hover[background-color-000000,color-ffffff,border-color-000000]
">
  Submit
</button>

Pseudo-elements

Use the pseudo-element flag without quoted strings inside the class name.

--before-content-empty
--after-content-empty
--placeholder-color-64748b
--selection[background-color-6366f1,color-ffffff]

A quoted value such as:

--before-content("→")

is not valid AliasCSS class syntax.

5. Magic & Selector Anchor

The Magic & identifier changes the placement of the generated class selector.

Normal combinators target descendants:

_div-display-none

The & anchor inverts the relationship so the generated class appears after the contextual selector:

_div&-display-none

Anchor matrix

PatternResult
_tag&-utilitytag .class
__tag&-utilitytag > .class
___tag&-utilitytag + .class
____tag&-utilitytag ~ .class

Parent hover

<div class="card">
  <button class="__.card--hover&-opacity-1 opacity-0">
    Quick Action
  </button>
</div>

Conceptual output:

.card:hover > .generated-class {
  opacity: 1;
}

Checkbox state

<input type="checkbox" checked>
 
<label class="___input--checked&-color-6366f1">
  Active
</label>

Conceptual output:

input:checked + .generated-class {
  color: #6366f1;
}

Ancestor class

Ancestor class selectors use an escaped dot:

_.sidebar&-display-none

Root theme context

<div class="
  background-color-ffffff
  color-0f172a
  _html[class~=dark]&-[background-color-0b0f19,color-f8fafc]
">
  Theme-aware surface
</div>

6. Scope Wrappers

Scope wrappers represent block-level CSS rules such as media queries, layers, container queries, starting styles, supports rules, and custom rules.

They are evaluated before selectors and declarations.

Responsive scopes

Common scopes include:

@xs
@sm
@md
@lg
@xl
@xxl

They can be written with the @ prefix or configured as bare media aliases.

Example:

<div class="
  width-100%
  @sm-width-50%
  @lg-width-33.333%
">
  Responsive column
</div>

Grouped scope

<div class="@md[padding-24px,gap-20px,display-flex]"></div>

Compound scopes

Bare keys inside @[...] do not repeat the @.

Valid:

@[md,base]-display-flex

Invalid:

@[@md,@base]-display-flex

The order is significant:

@[xs,base]

means the media wrapper contains the layer.

@[base,xs]

means the layer contains the media wrapper.

Raw scope rules

Complex CSS at-rules can be passed directly:

<div class="@[media(768px<=width<=1024px)]-display-none"></div>

Feature query:

<div class="@[supports(display:grid),base]-display-grid"></div>

Named container:

<div class="@[container_sidebar(min-width:400px)]-display-none"></div>

Container queries

Supported semantic container scopes include:

@container-xs
@container-sm
@container-md
@container-lg
@container-xl
@container-2xl

The ancestor must establish container context, for example:

<div class="container-type-inline-size">
  ...
</div>

Cascade layers

@reset
@base
@theme
@components
@utilities
@starting-style

Aliases such as @rs, @comps, and @utils are supported where defined.

7. Grouping & --as- Component Export

Grouping bundles declarations under one selector, state, attribute, scope, or combinator.

Basic grouping

<div class="[display-flex,gap-16px,padding-20px]"></div>

State grouping

<button class="
  border-0
  color-ffffff
  --hover-[color-000000,background-color-ffffff]
">
  Action
</button>

Attribute grouping

<div class="[data-state=open][display-flex,position-absolute,left-0,top-100%]">
  Dropdown
</div>

Combinator grouping

<div class="
  _h3[font-size-20px,font-weight-700]
  __button[padding-8px-16px,background-color-6366f1]
">
</div>

Component export

The --as- engine converts an inline group into a reusable semantic class.

<button class="
  [border-0,padding-8px-16px,border-radius-6px,font-weight-600,cursor-pointer]--as-btn
  btn
">
  Submit
</button>

The generated component can then be reused:

<button class="btn">Save</button>
<button class="btn">Update</button>
<button class="btn">Cancel</button>

Multiple exports

<div class="
  [border-0,padding-16px,display-flex,align-items-center,justify-content-center]--as-[btn,badge]
"></div>

Scoped export

Scopes wrap the export from outside:

<div class="@md[padding-24px,background-color-6366f1]--as-card card"></div>

Do not put a block-level scope inside the grouping brackets:

Correct:
@md[padding-20px,background-color-6366f1]--as-card

Incorrect:
[padding-10px,@md-padding-20px]--as-card

Specificity bump

<div class="
  [class][background-color-ffffff,border-radius-12px,padding-16px]--as-card
  card
">
</div>

This produces the equivalent of:

.card[class] {
  background-color: #ffffff;
  border-radius: 12px;
  padding: 16px;
}

8. Motion: Transitions, Transforms & Keyframes

AliasCSS keeps motion in the same grammar.

Transitions

Single transition:

tn-transform-0.2s-ease
transition-opacity-200ms

Multiple transitions use __:

tn-transform-0.2s-ease__color-0.5s

Conceptual output:

transition: transform 0.2s ease, color 0.5s;

Transform chaining

The same __ operator chains transform functions:

tf-rotateX-20deg__rotateY-360deg
tf-scale-1.1__translateY--10px__rotate-5deg

Negative angles and distances use --:

tf-rotateY--90deg
tf-translateY--10px

Inline keyframes

Define a timeline through the keyframes-* attribute:

<div
  keyframes-fadeIn="
    @0-opacity-0
    @100-opacity-1
  "
  class="an-fadeIn adu-1s atf-linear"
>
  Fade in
</div>

Grouped steps:

<div
  keyframes-pop="
    @0-[transform-scale-0.8,opacity-0]
    @100-[transform-scale-1,opacity-1]
  "
  class="an-pop adu-0.6s atf-ease-out"
>
  Pop
</div>

Multiple timeline percentages:

@[0,50,100]-display-flex
@[25,75]-[display-none,transform-scale-0.5]

Animation controls

an-[name]
adu-[duration]
adl-[delay]
atf-[timing-function]
atf-linear
atf-eio
aici
ada
afmbo
afm-forwards
aps-paused
aps-running

Reduced motion

<div class="an-spin adu-1s aici @motion-reduce-an-none"></div>

9. Escape Hatches

AliasCSS should be written using normal grammar whenever possible.

When the grammar genuinely cannot express a value or rule, use an escape hatch.

1. property(value) — last resort

Use a known CSS property with a raw CSS value:

background(linear-gradient(135deg,red_30%,blue_60%))_

This is the preferred raw-value escape hatch.

2. Custom property bridging

CSS variables can be consumed through AliasCSS property functions:

padding(10px,--gutter-x)

which resolves to:

padding: 10px var(--gutter-x);

3. data-raw-css

For CSS that is outside the normal selector/compiler grammar:

<div
  class="display-flex align-items-center"
  data-raw-css="..."
>
</div>

Use this only when the normal AliasCSS grammar is insufficient.

10. Modern CSS Capabilities

AliasCSS supports modern CSS constructs through its scope and property grammar.

Starting styles

<dialog class="
  opacity-1
  transform-scale-1
  transition-all-200ms
  @starting-style[opacity-0,tf-scale-0.9]
">
  Animated dialog
</dialog>

CSS Anchor Positioning

<button class="anchor-name-popover-anchor">
  Target
</button>
 
<div class="
  position-anchor-popover-anchor
  position-fixed
  top-anchor-bottom
">
  Floating surface
</div>

Scroll-driven animations

<div class="
  animation-timeline-scroll-root
  animation-range-entry-0%-exit-100%
"></div>

11. Configuration

aliascss.config.js is the compiler orchestration layer.

A configuration can define input files, output, media prefixes, CSS Modules integration, extractors, custom colors, compiler extensions, groups, prebuild bundles, ignored classes, and global statements.

import { getCompiler } from 'aliascss';
 
const config = {
  input: [
    'app/**/*.(tsx|jsx)',
    'components/**/*.(tsx|jsx)',
    'public/*.html',
  ],
 
  output: {
    location: './public/css/acss.css',
    '--file': true,
  },
 
  media: {
    prefix: {
      '@xs': '@media (max-width : 600px)',
      'xs': '@media (max-width : 600px)',
      '@sm': '@media (min-width : 600px)',
      'sm': '@media (min-width : 600px)',
    },
  },
 
  '--module': false,
  importModuleAs: 'x',
  extractorFunction: 'x',
 
  custom: {
    colors: {
      themeTextColor: 'var(--theme-text-color, #c3c3c3)',
      themeBgColor: 'var(--theme-bg-color, #0e0e0e)',
      primary: 'rgba(124, 143, 234, 1)',
    },
  },
 
  extend: {},
  prebuild: {},
  group: {},
 
  ignore: [
    'color-primary',
    'fs-xl',
  ],
 
  statement: `
    :root {
      --font-sans: system-ui, -apple-system, sans-serif;
    }
  `,
};
 
export default config;

Configuration invariants

Custom colors

Custom color keys must use CamelCase:

themeTextColor
surfacePrimary
accent600

Avoid:

theme-text-color
surface_primary

Media prefixes

Define both forms when overriding a breakpoint:

media: {
  prefix: {
    '@md': '@media (min-width: 768px)',
    'md': '@media (min-width: 768px)',
  },
}

group

Global group entries accept space-separated atomic utility strings. Selector prefixes and combinators do not belong in global groups.

For selector-aware abstractions, use:

[...]
--as-

instead.

12. Extending the Compiler

The extend configuration allows custom property compilers and multi-property design-system primitives.

Single-property compiler

extend: {
  shadow: {
    property: 'box-shadow',
 
    compiler: (value) => {
      const token = value.replace(/^-/, '');
 
      const elevationScale = {
        xs: '0px 1px 2px var(--shadow-color, rgba(16, 24, 40, 0.05))',
        sm: '0px 1px 3px var(--shadow-color, rgba(16, 24, 40, 0.1))',
        md: '0px 4px 8px -2px var(--shadow-color, rgba(16, 24, 40, 0.1))',
        lg: '0px 12px 16px -4px var(--shadow-color, rgba(16, 24, 40, 0.1))',
        xl: '0px 20px 24px -4px var(--shadow-color, rgba(16, 24, 40, 0.1))',
      };
 
      return elevationScale[token] || value;
    },
  },
}

Multi-property compiler

Use type: 'group' when one token should emit a synchronized set of declarations.

extend: {
  text: {
    type: 'group',
 
    groups: {
      sm: 'font-size: 14px; line-height: 20px; letter-spacing: 0em;',
      md: 'font-size: 16px; line-height: 24px; letter-spacing: 0em;',
      lg: 'font-size: 18px; line-height: 26px; letter-spacing: -0.0025em;',
      xl: 'font-size: 20px; line-height: 28px; letter-spacing: -0.005em;',
    },
  },
}

13. Extraction & CSS Modules

Dynamic class extraction

When class names are assembled dynamically, use the configured extraction helper.

const x = (classes) => classes;
<button
  className={
    active
      ? x('background-color-primary color-ffffff padding-8px-16px')
      : x('background-color-gray200 color-gray800 padding-8px-16px')
  }
>
  Dynamic Action
</button>

Configuration:

export default {
  extractorFunction: 'x',
};

CSS Modules

export default {
  '--module': true,
  importModuleAs: 'styles',
};

Then:

import styles from './Card.module.css';
 
export default function Card() {
  return (
    <div className={styles['padding-24px background-color-ffffff border-radius-12px']}>
      Scoped Module Container
    </div>
  );
}

14. Migration & Collision Control

Use ignore when migrating from another CSS system or when third-party classes must remain untouched.

export default {
  ignore: [
    'container',
    'btn',
    'card',
  ],
};

This is useful when AliasCSS is introduced alongside Bootstrap, Tailwind, legacy stylesheets, or vendor CSS.

15. CLI

Build using the configuration:

npx aliascss --config

The configuration controls the compiler input, output, extensions, groups, and other build behavior.

16. Recommended Authoring Order

When creating a new AliasCSS class, think from the CSS declaration outward.

Step 1 — Write the CSS

padding: 16px;

Step 2 — Convert the declaration

padding-16px

Step 3 — Add a state if needed

--hover-padding-20px

Step 4 — Add a selector relationship if needed

__button--hover-background-color-6366f1

Step 5 — Add a scope if needed

@md-padding-24px

Step 6 — Combine them

@md__button--hover-background-color-6366f1

The principle remains:

SCOPE → SELECTOR / STATE → PROPERTY-VALUE

while the compiler resolves the final expression from the rightmost property-value anchor backward.

17. Architecture at a Glance

                    AliasCSS
                       │
             ┌─────────┴─────────┐
             │                   │
        Block Scopes        Selector Engine
             │                   │
     @media / @layer       _ __ ___ ____ &
     @container             --state
     @supports              [attribute]
     @starting-style        :is / :has / :not
             │                   │
             └─────────┬─────────┘
                       │
                Property Anchor
                       │
             ┌─────────┴─────────┐
             │                   │
        Semantic Mode       Shorthand Mode
             │                   │
       display-flex              df
       padding-16px               p-16px
       color-ffffff               c-ffffff
             │
             └─────────┬─────────┘
                       │
                Escape Hatches
                       │
               property(value)
                 data-raw-css
                       │
                 Compiler Config
                       │
                 aliascss.config.js

18. The AliasCSS Mental Model

AliasCSS is intended to be readable by developers who already understand CSS.

Do not memorize a replacement vocabulary for CSS.

Instead:

  1. Know CSS.
  2. Write the property and value.
  3. Use the documented shorthand when useful.
  4. Add states with --.
  5. Add structural relationships with _, __, ___, or ____.
  6. Use & when the selector needs contextual inversion.
  7. Add scopes with @.
  8. Group repeated declarations with [...].
  9. Export reusable patterns with --as-.
  10. Use property(value) only as the last resort.

The goal is deterministic translation:

CSS knowledge
     ↓
AliasCSS grammar
     ↓
Deterministic compiler
     ↓
Native CSS
Last updated on