# AliasCSS
> AliasCSS is a deterministic compiler that turns class names into native CSS. A class name *is* a CSS declaration, written as `[@scope-][selector-]property-value`. There is no design-token vocabulary to learn: if you know CSS, you can write AliasCSS. It works as a browser script (compiles classes on the page at runtime) or as a CLI/build step (writes a .css file). It ships optional theme-aware color tokens and an `x-` component library as examples of building your own design system.
Website: https://aliascss.com
Package: `aliascss` on npm
This file describes version 1.5.0. Every example below was compiled with that release.
## Install
Browser (no build step):
```html
```
Keep `defer` (or put the script at the end of `
`): the runtime watches the page for new elements and needs `` to exist. Classes added later by JavaScript are compiled automatically.
CLI / build:
```bash
npm i -D aliascss
npx aliascss "src/**/*.html" public/css/acss.css # input glob, output file
npx aliascss --config --watch # uses aliascss.config.js (or .mjs)
npx aliascss --help
```
```js
// aliascss.config.js
export default {
input: ['src/**/*.{html,jsx,tsx,vue}'],
output: { location: 'public/css/acss.css' },
minify: false,
// prefix, layers, media, custom, extend, statement, group, ignore … are optional
};
```
## Core rule: a class is one CSS declaration
```
property-value display-flex → display: flex
alias-value d-flex → display: flex
@scope-property-value @md-d-flex → @media (min-width: 768px) { … }
--state-property-value --hover-c-red → :hover { color: red }
@scope--state-property-value @md--hover-c-red
```
- The property-value pair is always last; everything before it is scope and selector.
- Full CSS property names always work (`background-color-red`, `justify-content-space-between`). Short aliases exist for common ones. When unsure, use the full name.
- Values are written as in CSS with `-` between tokens: `b-1px-solid-red` → `border: 1px solid red`, `p-8px-16px` → `padding: 8px 16px`.
### Common aliases
| Alias | Property | Example |
|---|---|---|
| `d` | display | `d-flex`, `d-grid`, `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` | min-width, max-width | `mw-0px`, `xw-680px` |
| `xh` | max-height | `xh-240px` |
| `g` | gap | `g-12px` |
| `aic`, `jcc`, `jcsb` | align-items:center, justify-content:center / space-between | |
| `c`, `bgc` | color, background-color | `c-red`, `bgc-slateTheme1` |
| `fs`, `fw`, `lh`, `ff` | font-size, font-weight, line-height, font-family | `fs-14px`, `fw-600`, `lh-1.5` |
| `les` | letter-spacing | `les--0.02em` |
| `b`, `br` | border, border-radius | `b-1px-solid-red`, `b-0`, `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-scale-0.98`, `tf-translateY--2px` |
| `td` | text-decoration | `td-none` |
| `cont` | `content: ""` (for ::before/::after) | `--before-cont` |
Less common properties: use the full name (`overflow-wrap-break-word`, `scroll-margin-top-24px`).
## Values
| Need | Write | Output |
|---|---|---|
| Negative number | `--` before it | `m--8px` → `margin: -8px`, `tf-translateY--2px` |
| Decimal | `.` | `o-0.5`, `lh-1.5` |
| Percent | `%` | `w-100%` |
| Color with alpha | `/` + decimal 0–1 | `c-red/0.5`, `bgc-ccc/0.7` → `oklch(from … / 0.7)` |
| Hex color | with or without `#` | `c-e3e3e3` and `c-#e3e3e3` are the same |
| `!important` | `--important` or `-i` at the end | `c-red--important` |
| Complex value | property function `prop(value)` | see below |
### Property functions: `property(raw value)`
Use when the value has spaces, commas or functions:
```
padding(8px_16px) → padding: 8px 16px
grid-template-columns(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)
```
- `_` means a space. `\_` is a literal underscore. Commas stay commas.
- Inside `calc()`, `+` and `-` need spaces: write `calc(100%_-_32px)`, never `calc(100%-32px)` (invalid CSS). `*` and `/` don't need them: `calc(var(--x)*-1)`.
- Hex inside a function keeps its `#`: `c(#e3e3e3)`.
## CSS variables
```
--x-gap:16px defines --x-gap: 16px
--x-pad:(8px_16px) defines --x-pad: 8px 16px (raw value in parentheses)
--x-border-color:--x-accent:blue defines --x-border-color: var(--x-accent, blue)
g--x-gap uses gap: var(--x-gap)
g--x-gap:16px uses gap: var(--x-gap, 16px) (with fallback)
m--x-shift:--8px uses margin: var(--x-shift, -8px) (negative fallback: always write --8px)
bgc--x-bg:slateTheme1 uses background-color: var(--x-bg, )
```
Variable names must not start with a digit. The end of a variable name decides how its value is compiled: names ending in `color` or `bg` compile colors (`slateTheme1` → `light-dark(…)`), names ending in `ring` compile a focus ring. Pick neutral names (`--x-gap`, `--x-border-color`) when you want the value as written.
## Selectors and states
```
--hover-c-red :hover --focus-visible-… --active-… --disabled-…
--before-cont ::before --after-… --placeholder-… --marker-…
--first-child-… --last-child-… --checked-… --open-… --popover-open-…
--nth-child(2n+1)-… :nth-child(2n+1) short: --nc(3)-… , --nth-child-3-…
--not(--first-child)-… :not(:first-child) (parentheses for anything longer than one word)
--not--hover-… :not(:hover) (one-word form)
--has(--checked)-… :has(:checked)
--is(…) --where(…) :is(…) :where(…) Capitalised (--Has, --Is, --Where) adds a space: " :has(…)"
--hover--before-c-red :hover::before (state first, then pseudo-element)
```
Never put a state after `::before`/`::after` (`--before--hover` → `::before:hover`, which never matches).
Vendor parts (each browser only applies its own prefix): `--webkit-slider-thumb`, `--webkit-slider-runnable-track`, `--moz-range-thumb`, `--moz-range-track`, `--moz-range-progress`, `--webkit-progress-bar`, `--webkit-progress-value`, `--moz-progress-bar`, `--scrollbar`, `--scrollbar-thumb`, `--file-selector-button`, `--details-content`.
### Attribute selectors
```
[aria-expanded=true]-c-red .x[aria-expanded="true"] { color: red }
[aria-current=page][c-red,fw-600] attribute first, then a group
[class~=active]-bgc-blue
```
### Combinators (target other elements)
| Write | 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` | descendants `*` |
| `__all-m-0` | children `> *` |
| `_.card-c-red` | descendant `.card` |
| `_.(card-title)-c-red` | descendant `.card-title`: **class names containing `-` go in parentheses** |
| `_.(card.is-active)-o-1` | `.card.is-active` |
| `_ul__li--hover-c-red` | `ul > li:hover` |
### Selector before the element: `&`
Everything before `&` becomes an ancestor selector:
```
_.dark&c-white .dark . { color: white }
[data-theme=dark]&c-white [data-theme="dark"] . { … }
```
## Scopes (`@…-`)
| Scope | Meaning |
|---|---|
| `@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 (`xxl`, not `2xl`) |
| `@hover-capable-` | `(hover: hover)` |
| `@motion-reduce-` | `prefers-reduced-motion: reduce` |
| `@container-xs-` … `@container-xxl-` | container queries |
| `@reset- @base- @theme- @components- @utils-` | CSS cascade layers (`@rs`, `@comps`, `@utilities` also work) |
| `@starting-style-` / `@ss-` | `@starting-style` (entry animations) |
| `@[components,starting-style]-…` | several scopes at once |
Layer order: `@layer reset, base, theme, components, utilities;` then the breakpoint layers.
### Responsive rules (important)
1. **Breakpoint classes live in layers, so a plain class always beats them.** Never mix `p-32px @xs-p-16px`; the plain one wins everywhere. Write every size with a prefix: `@xs-p-16px @sm-p-24px @md-p-32px`.
2. **`@xs` is max-width, the others are min-width.** If you start with `@xs`, also set `@sm`, or 576–767px gets nothing: `@xs-x-col-12 @sm-x-col-12 @lg-x-col-8`.
3. Larger breakpoints win over smaller ones (`@md` over `@sm`).
## Groups `[…]`
Apply one prefix to several declarations:
```
@md[d-flex,g-16px,p-24px]
--hover[c-red,bgc-blue]
@components--before[cont,position-absolute,inset-0]
[d-block,--hover-bgc-gray100,[aria-current=true]-fw-600] states and attributes are allowed inside
```
A group styles **one element in all its states**. Element nesting (`[_th[…]]`) is not supported: use statements for that.
## Export a component class: `--as-name`
```html
```
- `--as-[btn,button]` exports several names; `/` is allowed (`--as-card/header`).
- Only property-value classes can be exported; `x-` statements can't be put inside an export.
## Other HTML attributes
```html
```
## Colors and themes
- Theme-aware tokens (switch with light/dark): Radix scales `slateTheme1`…`slateTheme12` (also red, green, amber, blue … `Theme1-12`), fixed dark steps `slateDark1-12`, alpha `blackA1-12`.
- Accent scale (React Aria style), driven by one variable `--accentColor`: `accentRA100`…`accentRA1600` (fixed), `accentRATheme100`…`accentRATheme1600` (light/dark).
- Theme tokens compile to `light-dark()`, which needs `color-scheme`. Put `x-theme` on ``.
- Rebrand everything: ``. Force a subtree: `x-theme-dark` / `x-theme-light`.
## x- components (optional starter library)
All are statements in the `@components` layer, use theme tokens, and can be customised with `--x-*` variables. Utilities override them.
- 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-progress`, `x-field`, `x-label`, `x-hint`, `x-error-text`, `x-choice`, `x-input-group`, `x-input-addon`
- Surfaces: `x-card` (+ `-header -body -footer -title -description -elevated -flat -interactive`), `x-badge`, `x-alert`, `x-table` (+ `-striped -bordered -hover -compact -sticky`), `x-table-card`
- Overlays: `x-dialog` (native `