# AliasCSS

**Write CSS in your class names.** AliasCSS is a compiler that turns class names into native CSS. Each class is one CSS declaration, so if you know CSS, you already know AliasCSS.

```html
<button class="d-flex aic g-8px p-8px-16px br-8px bgc-blue c-white --hover-bgc-navy @md-p-12px-20px">
  Save
</button>
```

```css
.d-flex { display: flex }
.aic { align-items: center }
.g-8px { gap: 8px }
.p-8px-16px { padding: 8px 16px }
.br-8px { border-radius: 8px }
.bgc-blue { background-color: blue }
.c-white { color: white }
.--hover-bgc-navy:hover { background-color: navy }
@media (min-width: 768px) { .\@md-p-12px-20px { padding: 12px 20px } }
```

- **Any CSS property, any value.** There's no fixed list of utilities to learn. Full property names always work (`justify-content-space-between`), and short aliases exist for the common ones (`jcsb`).
- **States, selectors and media queries live in the class:** `--hover-…`, `[aria-expanded=true]-…`, `[data-open]&…`, `@md-…`, `@motion-reduce-…`.
- **Light and dark themes built in.** Radix-style colour tokens (`slateTheme1`–`12`) and an accent scale driven by one variable (`--accentColor`).
- **No config needed to start.** Add a config file when you want custom values, your own components or a build step.

📖 Documentation: [aliascss.com](https://aliascss.com)

---

## Contents

- [Install](#install)
- [The rule: one class, one declaration](#the-rule-one-class-one-declaration)
- [Values](#values)
- [States and pseudo-elements](#states-and-pseudo-elements)
- [Attributes and other elements](#attributes-and-other-elements)
- [Responsive and other scopes](#responsive-and-other-scopes)
- [Groups and exports](#groups-and-exports)
- [CSS variables](#css-variables)
- [Colours and themes](#colours-and-themes)
- [Keyframes](#keyframes)
- [x- components](#x--components)
- [React, Vue and other frameworks](#react-vue-and-other-frameworks)
- [CLI and aliascss.config.js](#cli-and-aliascssconfigjs)
- [Using AliasCSS with AI coding agents](#using-aliascss-with-ai-coding-agents)
- [Upgrading from older versions](#upgrading-from-older-versions)
- [Changelog](#changelog)

---

## Install

### CLI (production)

```bash
npm install --save-dev aliascss
npx aliascss "src/**/*.html" public/css/acss.css          # input glob → output file
npx aliascss "src/**/*.html" public/css/acss.css --watch
```

The CLI scans your files and writes one CSS file. Link that file in your app.

### CDN (development and experiments only)

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

The browser script compiles classes on the page at runtime, including elements added later by JavaScript. It's large and does its work in the browser, so **don't ship it to production**: use the CLI output instead. Keep `defer`, because the script needs `<body>` to exist.

---

## The rule: one class, one declaration

```
[@scope-][selector-]property-value
```

Read it right to left: the property and value are always last, and everything before them says *when* and *where* the declaration applies.

| Class | CSS |
|---|---|
| `display-flex` or `d-flex` | `display: flex` |
| `margin-left-20px` or `ml-20px` | `margin-left: 20px` |
| `border-1px-solid-ccc` or `b-1px-solid-ccc` | `border: 1px solid #ccc` |
| `--hover-c-red` | `:hover { color: red }` |
| `@md-d-grid` | `@media (min-width: 768px) { display: grid }` |
| `@md--hover-c-red` | both |

### Common aliases

| Alias | Property | Example |
|---|---|---|
| `d` | display | `d-flex`, `d-none`, `d-inline-flex` |
| `p`, `m` | padding, margin | `p-16px`, `m-0`, `p-8px-16px` |
| `w`, `h` | width, height | `w-100%`, `h-40px` |
| `mw`, `xw`, `xh` | min-width, max-width, max-height | `xw-680px` |
| `g` | gap | `g-12px` |
| `aic`, `jcc`, `jcsb` | align-items: center, justify-content: center / space-between | |
| `c`, `bgc` | color, background-color | `c-red`, `bgc-slateTheme2` |
| `fs`, `fw`, `lh`, `ff` | font-size, font-weight, line-height, font-family | `fs-14px`, `fw-600`, `lh-1.5` |
| `b`, `br` | border, border-radius | `b-1px-solid-ccc`, `br-8px` |
| `t`, `r`, `btm`, `l` | top, right, bottom, left | `t-0` |
| `o`, `zi` | opacity, z-index | `o-0.5`, `zi-10` |
| `tf` | transform | `tf-rotate-45deg`, `tf-translateY--2px` |
| `cont` | `content: ""` | `--before-cont` |

Not sure of an alias? Use the full CSS property name; it always works.

---

## Values

| Need | Write | CSS |
|---|---|---|
| Several values | `-` between them | `p-8px-16px` → `padding: 8px 16px` |
| Negative | `--` before the number | `m--8px` → `margin: -8px` |
| Decimal | `0.5` (recommended) | `o-0.5`, `lh-1.5`, `m-0.25rem` |
| Percent | `%` | `w-100%` |
| Hex colour | with or without `#` | `c-e3e3e3`, `c-#e3e3e3` |
| Colour with alpha | `/` + decimal | `c-red/0.5` |
| `!important` | `--important` at the end | `c-red--important` |
| Anything complex | `property(raw value)` | see below |

`.5` also works and compiles to `0.5`, but write `0.5`. The older `d` and `p` notation (`o-0d5`, `w-50p`) still compiles.

### Property functions: `property(raw value)`

Use this when the value has spaces, commas or functions. Inside the parentheses, `_` is a space:

```
padding(8px_16px)                        → padding: 8px 16px
gtc(repeat(3,1fr))                       → grid-template-columns: repeat(3, 1fr)
box-shadow(0_1px_3px_rgb(0_0_0_/_0.1))   → box-shadow: 0 1px 3px rgb(0 0 0 / 0.1)
w(calc(100%_-_32px))                     → width: calc(100% - 32px)
ff(Times_New_Roman,Times,serif)          → font-family: "Times New Roman", Times, serif
background(linear-gradient(45deg,red,blue))
```

In `calc()`, `+` and `-` need spaces around them: `calc(100%_-_32px)`.

For properties that take several layers (shadows, transforms, transitions, filters), `__` separates the layers: `tf-scale-2__rotate-25deg` → `transform: scale(2) rotate(25deg)`.

---

## States and pseudo-elements

Start the class with `--` and the state or pseudo-element:

```
--hover-c-red               :hover
--focus-visible-…           :focus-visible
--active-…   --disabled-…   --checked-…   --placeholder-…
--before-cont               ::before { content: "" }
--first-child-…   --last-child-…   --popover-open-…
--nth-child(2n+1)-…         :nth-child(2n+1)
--not(--first-child)-…      :not(:first-child)
--has(--checked)-…          :has(:checked)
--hover--before-c-red       :hover::before      (state first, then pseudo-element)
```

Short forms exist for most of them (`--h-` for `:hover`, `--fv-` for `:focus-visible`, and so on).

---

## Attributes and other elements

### Attribute states

```
[aria-expanded=true]-c-red        .x[aria-expanded="true"]  { color: red }
[aria-current=page][c-red,fw-600] attribute + several declarations
[data-open]-d-block               attribute present
```

Never put quotes in a class name: write `[data-state=open]`, not `[data-state='open']`.

### A parent's state: `&`

Everything before `&` becomes an ancestor selector. This is the main tool for component state: put one `data-*` or `aria-*` attribute on the root, and let every child react to it.

```html
<div data-open class="…">
  <div class="o-0 [data-open]&o-1">…</div>       <!-- [data-open] .x { opacity: 1 } -->
</div>
```

### Other elements

| Class | Selector |
|---|---|
| `_li-c-red` | descendant `li` |
| `__li-c-red` | child `> li` |
| `___p-c-red` | next sibling `+ p` |
| `____p-c-red` | later siblings `~ p` |
| `_all-m-0` | all descendants `*` |
| `_.(card-title)-c-red` | descendant `.card-title` (class names with `-` go in parentheses) |

---

## Responsive and other scopes

Scopes start with `@`:

| Scope | Media / rule |
|---|---|
| `@xs-` | max-width: 575.99px |
| `@sm-` | min-width: 576px |
| `@md-` | min-width: 768px |
| `@lg-` | min-width: 992px |
| `@xl-` | min-width: 1200px |
| `@xxl-` | min-width: 1408px |
| `@hover-capable-` | `(hover: hover)` |
| `@motion-reduce-` | `prefers-reduced-motion: reduce` |
| `@container-xs-` … `@container-xxl-` | container queries |
| `@starting-style-` | `@starting-style` (entry animations) |
| `@reset-` `@base-` `@theme-` `@components-` `@utils-` | cascade layers |

**Two rules to remember:**

1. **A class without a scope beats a scoped class**, because breakpoints live in cascade layers. Don't mix `p-32px @md-p-16px`. Give every size a prefix: `@xs-p-16px @sm-p-24px @md-p-32px`.
2. **`@xs` is max-width; the others are min-width.** If you use `@xs`, also set `@sm`, or screens from 576px to 767px get nothing.

---

## Groups and exports

### Groups `[…]`

Apply one prefix to several declarations:

```
@md[d-flex,g-16px,p-24px]
--hover[c-red,bgc-blue]
--before[cont,position-absolute,inset-0]
```

### Exports `--as-name`

Define a class once and reuse it by name. This keeps long class lists out of repeated markup:

```html
<div hidden class="[d-flex,aic,g-8px,p-8px-16px,br-8px,c-slateTheme11,--hover-bgc-slateTheme3,[aria-current=page]-fw-600]--as-nav-item"></div>

<a href="/" class="nav-item" aria-current="page">Home</a>
<a href="/billing" class="nav-item">Billing</a>
```

Groups and exports take plain property-value classes only. `x-` components and `@scope-` classes go on the element itself.

---

## CSS variables

```
--x-gap:16px          defines  --x-gap: 16px
g--x-gap              uses     gap: var(--x-gap)
g--x-gap:16px         uses     gap: var(--x-gap, 16px)
w-var(--x-w)          uses     width: var(--x-w)
w(var(--x-w))         uses     width: var(--x-w)
```

Start your own variables with `--x-`. Short selector aliases claim other prefixes (`--h-` is `:hover`, `--s-` is `::selection`, `--sb-` is the scrollbar), so `--sb-bg:red` won't do what you expect. Variables whose names end in `-color` or `-bg` compile colour tokens: `--x-ring-color:accentRA1000`.

---

## Colours and themes

Put `x-theme` on `<html>`, then use the theme tokens. They switch between light and dark automatically:

```html
<html class="x-theme">
  <div class="bgc-slateTheme2 c-slateTheme12 b-1px-solid-slateTheme6">…</div>
  <button class="bgc-accentRA1000 c-white">Save</button>
  <span class="bgc-accentRATheme100 c-accentRATheme1100">Soft badge</span>
</html>
```

- **Neutral and colour scales:** `slateTheme1`–`12`, plus `red`, `green`, `amber`, `blue`, `violet`, `mauve`… `Theme1`–`12`, and alpha versions (`violetThemeA4`, `blackA6`). These follow the Radix Colors steps: 1–2 backgrounds, 3–5 component states, 6–8 borders, 9–10 solid fills, 11–12 text.
- **Accent scale:** `accentRA100`–`1600` (fixed) and `accentRATheme100`–`1600` (light/dark), all derived from one colour.
- **Rebrand:** `<html class="x-theme --accentColor:0d74ce">`.
- **Force one part of the page:** `x-theme-dark` / `x-theme-light`.

---

## Keyframes

Declare keyframes on any element with a `keyframes-name` attribute:

```html
<i class="d-none" keyframes-pop-in="@0-[o-0,tf-scale-0.9] @100-[o-1,tf-none]"></i>
<i class="d-none" keyframes-shake="@[0,100][tf-none] @[20,60][tf-translateX--6px] @[40,80][tf-translateX-6px]"></i>

<div class="animation(pop-in_.3s_ease-out_both) @motion-reduce-animation-none">Hi</div>
```

- One stop: `@0-[…]` or `@0[…]`. Several stops with the same style: `@[0,25,50][…]`.
- Use lower-case kebab-case names. HTML lower-cases attribute names, so `keyframes-fadeIn` becomes `fadein`.
- Give the element a class (`class="d-none"`) so the browser script picks it up.

---

## x- components

An optional starter library, built with AliasCSS itself. Every component uses theme tokens, can be customised with `--x-*` variables, and sits in the `@components` layer, so any utility overrides it.

- **Forms:** `x-button` (+ `-secondary -ghost -danger -sm -lg -icon`), `x-input`, `x-textarea`, `x-select`, `x-checkbox`, `x-radio`, `x-switch`, `x-range`, `x-file`, `x-field`, `x-label`
- **Surfaces:** `x-card`, `x-badge`, `x-alert`, `x-table`
- **Overlays:** `x-dialog` (native `<dialog>`), `x-dropdown` (native `popover`), `x-accordion` (`<details>`)
- **Navigation:** `x-tab-list`, `x-tab`, `x-breadcrumb`, `x-pagination`, `x-menu`
- **Feedback:** `x-spinner`, `x-skeleton`, `x-avatar`
- **Layout:** `x-stack`, `x-cluster`, `x-center`, `x-grid`, `x-sidebar`, `x-cover`, `x-row` + `x-col-1`…`12`
- **Content:** `x-prose`, `x-kbd`, `x-code`, `x-divider`

```html
<button class="x-button --x-button-bg:pinkTheme9">Launch</button>
```

The `x-` library is an example of a design system built with AliasCSS. You can define your own with `extend` in the config.

---

## React, Vue and other frameworks

The CLI reads your source files as text and finds classes in two places:

1. `class="…"` and `className="…"` string literals
2. calls to the extractor function, `String('…')` by default

Wrap any class that lives in a variable, object, ternary or template literal, and never build class names at runtime:

```tsx
const TONE = {
  paid: String('bgc-greenTheme3 c-greenTheme11'),
  due: String('bgc-redTheme3 c-redTheme11'),
};

<span className={TONE[status]}>…</span>
<li className={String('d-flex g-8px ') + (active ? String('bgc-accentRATheme100') : '')} />

// never: 'bgc-' + color   or   `p-${n}px`
```

For component state, set a `data-*` or `aria-*` attribute and style it with `[data-open]&…` or `[aria-pressed=true]-…`, which keeps the class names static.

---

## CLI and aliascss.config.js

```bash
npx aliascss --config            # build from aliascss.config.js
npx aliascss --config --watch    # rebuild on change
npx aliascss --help
```

`package.json`:

```json
"scripts": {
  "aliascss-build": "aliascss --config",
  "aliascss-watch": "aliascss --config --watch"
}
```

`aliascss.config.js`: everything except `input` and `output` is optional.

```js
const config = {
  // glob pattern, or an array of them
  input: ['app/**/*.{tsx,jsx}', 'components/**/*.{tsx,jsx}', 'public/*.html'],

  output: {
    location: './public/css/acss.css',   // one CSS file with everything
    '--file': true,                      // also one CSS file per input file
  },

  // name of the wrapper the CLI scans in JS/TS (default: String)
  extractorFunction: 'String',

  // minify the main CSS file with cssnano
  // minify: true,

  // prefix every class: ac-bgc-red, ac--hover-c-red
  // prefix: 'ac',

  // CSS module support
  '--module': true,
  importModuleAs: 'x',                   // import x from 'page.module.css'

  // rewrite the output file on each build (leave this on unless you know why not)
  truncate: true,

  // change a media prefix
  media: {
    prefix: { xs: '@media (max-width: 600px)' },
  },

  // custom colour names (no "-" or "_" in the name): bgc-main, c-brand
  custom: {
    colors: {
      main: 'rgb(12,23,45)',
      brand: '#c6c6c6',
    },
  },

  // your own properties and components
  extend: {
    'txt-color': { property: 'color', extend: 'color' },   // txt-color-red
    shadow: {                                              // shadow-sm, shadow-lg
      property: 'box-shadow',
      compiler: (value) => ({
        sm: '0 1px 3px var(--x-shadow-color)',
        md: '0 4px 8px -2px var(--x-shadow-color)',
        lg: '0 12px 16px -4px var(--x-shadow-color)',
      })[value.slice(1)],
    },
    'ui-btn': {                                            // a component made of AliasCSS classes
      type: 'statement',
      statement: `
        @components[d-inline-flex,aic,g-8px,p-8px-16px,br-8px,bgc-accentRA1000,c-white]
        @components--hover-bgc-accentRA1100
      `,
    },
  },

  // fixed class names
  prebuild: {
    'text-sm': 'font-size:14px;line-height:20px',
    'flex-center': 'display:flex;align-items:center;justify-content:center',
  },

  // plain CSS added to every compiled file
  statement: `
    body { font-family: system-ui, sans-serif; }
  `,

  // one class name for a set of AliasCSS classes
  group: {
    container: 'd-flex flex-direction-column aic',
  },

  // class names to leave alone (for example, ones another framework owns)
  ignore: ['fs12px', 'c-red'],
};

export default config;
```

---

## Using AliasCSS with AI coding agents

- **[aliascss.com/llms.txt](https://aliascss.com/llms.txt):** the whole language on one page, written for language models.
- **AliasCSS AI kit:** a skill folder plus `AGENTS.md`, `CLAUDE.md`, Cursor and Copilot instructions. Copy it into your project, and Claude Code, Codex, Cursor, Copilot and Gemini CLI will write correct AliasCSS.

---

## Upgrading from older versions

| Old | Now | Why |
|---|---|---|
| `xs-dn`, `md-w-500px` | `@xs-d-none`, `@md-w-500px` | Breakpoints need `@`. Without it, the class compiles **with no media query** and applies at every width. |
| `ff-Times_New_Roman--Times--serif` | `ff(Times_New_Roman,Times,serif)` | Use the function form for font lists. |
| `o-0d5`, `w-50p` | `o-0.5`, `w-50%` | Both still work; `.` and `%` are easier to read. |
| `c--var--name` | `c--x-name` | Both work; use `--x-` names for your own variables. |

---

## Changelog

### 1.5.3

- **Fixed:** in the browser script, a page with a `keyframes-…` element threw "Cannot read properties of undefined (reading 'has')" and stopped styling every element after it (regression in 1.5.2).
- **Fixed:** decimals with a leading dot (`o-.5`, `m-.5rem`, `scale-.98`, `--x-o:.5`) compile to `0.5` instead of a negative value or an empty rule. `0.5` remains the recommended form.
- **Fixed:** `w-var(--x-w)` and other `-var(…)` values compile, fallbacks included.
- **Added:** `display-webkit-box` / `d-webkit-box`.

### 1.5.2

- **Fixed:** `grid-column` and `grid-row` keep a negative number after `/` (`gc-1/-1` → `1 / -1`).
- **Fixed:** keyframes are written once instead of on every re-render, and single-stop keyframes accept `@0[…]`, `@0-[…]` and `@50%[…]`.
- **Added:** `cursor-grab` and other cursor keywords.

---

## License

See [LICENSE](LICENSE).
