# 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 ``), `x-dropdown` (native `popover`), `x-accordion` (`
`) - Navigation: `x-tab-list`, `x-tab`, `x-tab-panel`, `x-breadcrumb`, `x-pagination`, `x-menu` (hamburger → X, uses `aria-expanded`) - Feedback: `x-spinner`, `x-skeleton`, `x-avatar`, `x-avatar-group` - Layout: `x-stack`, `x-cluster`, `x-center`, `x-grid`, `x-switcher`, `x-sidebar`, `x-cover`, `x-frame`, `x-reel` - 12-column grid: `x-row` (gap 16px; `x-row-xs/sm/md/lg/xl` = 4/8/16/24/32px; `x-row-20px` any gap), `x-col-1`…`x-col-12`, `x-col` (fill), `x-col-auto` (fit content), `x-col-240px` (fixed), `x-col-offset-1`…`11`. Uses flex + gap, no negative margins, so a card can be the column itself. - Slide-in panels: `x-absolute-top/-bottom/-left/-right` (hide with `data-absolute-hide` or class `x-absolute-hide`), `x-absolute-0` (fill parent) - Content: `x-prose`, `x-kbd`, `x-code`, `x-code-block`, `x-divider`, `x-divider-vertical`, `x-divider-text` (+ `-start -end`), `x-arrow` (+ `-up -down -left -right`) - Theme: `x-theme`, `x-theme-light`, `x-theme-dark` Example: ```html
…
``` ## Build your own design system The `x-` library is an example, not a fixed API. Define your own in the config: ```js export default { extend: { 'ui-btn': { type: 'statement', statement: ` @base-all-unset @components[d-inline-flex,aic,g-8px,p-8px-16px,br-8px,bgc--ui-btn-bg:accentRA1000,c-white,cursor-pointer] @components--hover-bgc--ui-btn-hover:accentRA1100 @components--focus-visible[outline-2px-solid-currentColor,outline-offset-2px] ` }, 'ui-reset': { type: 'raw', statement: `*{box-sizing:border-box}` }, }, }; ``` - `type: 'statement'`: a class made of AliasCSS classes (multi-line, scopes allowed). - `type: 'raw'`: plain CSS output as is. - `type: 'group'`: a function compiler that takes a value (`x-col-6`, `x-row-24px`). - Convention: custom function compilers are capitalised (`Theme(…)`), custom classes get a prefix (`x-`, `ui-`). ## Console messages The compiler still outputs the CSS but warns about likely mistakes: ``` AliasCSS: "w(calc(100%-32px))": "+" and "-" need spaces in calc(), write _-_ e.g. calc(100%_-_32px) AliasCSS: "--before--hover-c-red": "::before:hover" never matches; put the state first, e.g. --hover--before AliasCSS: in "[d-flex,bad-thing,c-red]", could not compile: -bad-thing ``` Values are not validated against CSS: `bgc-notacolor` outputs `background-color:notacolor` and the browser ignores it. ## Common mistakes | Wrong | Right | Why | |---|---|---| | `p-32px @xs-p-16px` | `@xs-p-16px @sm-p-32px` | plain classes beat breakpoint classes | | `@xs-x-col-12 @lg-x-col-6` | `@xs-x-col-12 @sm-x-col-12 @lg-x-col-6` | 576–991px would get nothing | | `@2xl-…` | `@xxl-…` | there is no 2xl | | `w(calc(100%-32px))` | `w(calc(100%_-_32px))` | calc needs spaces around + and - | | `c-red/50` | `c-red/0.5` | alpha is a decimal 0–1 | | `--before--hover-c-red` | `--hover--before-c-red` | state before pseudo-element | | `_.card-title-c-red` | `_.(card-title)-c-red` | hyphenated class names need parentheses | | `--not--first-child-…` | `--not(--first-child)-…` | multi-word selectors need parentheses | | `m--x-gap:-8px` | `m--x-gap:--8px` | negative values (fallbacks too) use `--` | | `