# ToCSS Complete Documentation

> ToCSS is a lightweight browser runtime that reads CSS-like declarations from a `tocss` HTML attribute and generates scoped CSS. This document describes version 0.1.0.

## Project Facts

- Stable version: `0.1.0`
- License: MIT
- Website: https://tocss.com/
- Source: https://github.com/tiennguyenvan/tocss
- Issues: https://github.com/tiennguyenvan/tocss/issues
- Package scope: `@tocss`
- Runtime attribute: `tocss`
- Browser global: `window.tocss`

ToCSS is a JavaScript runtime, not a CSS stylesheet. It processes the `tocss` attribute, generates scoped CSS in `<style>` elements, replaces the attribute with a generated class, and watches for elements added later.

## Package Selection

### `@tocss/vanilla`

Browser runtime, public API, TypeScript declarations, and standalone browser bundles.

### `@tocss/default`

Default property aliases, preset tokens, responsive screens, and theme colors.

### `@tocss/tailwind`

Tailwind-style property aliases, preset tokens, responsive screens, and colors. This preset is inspired by familiar naming; it is not full Tailwind CSS compatibility.

### `@tocss/core`

Framework-neutral parser, rule engine, color processing, and shared TypeScript types. Most browser applications should use `@tocss/vanilla` instead.

## Installation

### Browser Bundle with Default Preset

```html
<button tocss="flex; aic; g:8px; p:12px 18px; bg:#7f50ed; c:white; rad:10px">
  Get started
</button>

<script src="https://cdn.jsdelivr.net/npm/@tocss/vanilla@0.1.0/dist/tocss.min.js"></script>
<script>
  tocss.init();
</script>
```

The bundle contains the browser runtime and automatically registers the default preset. Use an exact package version in production.

### npm with Default Preset

```bash
npm install @tocss/vanilla @tocss/default
```

```js
import { init, usePreset } from '@tocss/vanilla';
import defaultPreset from '@tocss/default';

usePreset(defaultPreset);
init();
```

### npm with Tailwind-Style Preset

```bash
npm install @tocss/vanilla @tocss/tailwind
```

```js
import { init, usePreset } from '@tocss/vanilla';
import tailwindPreset from '@tocss/tailwind';

usePreset(tailwindPreset);
init();
```

### Browser Bundle with Tailwind-Style Preset

```html
<script src="https://cdn.jsdelivr.net/npm/@tocss/vanilla@0.1.0/dist/tocss-tailwind.min.js"></script>
<script>
  tocss.init();
</script>
```

### Browser Runtime Without a Preset

```html
<script src="https://cdn.jsdelivr.net/npm/@tocss/vanilla@0.1.0/dist/tocss-core.min.js"></script>
<script>
  tocss.config({
    props: {
      c: 'color',
      p: 'padding'
    },
    presets: {
      flex: 'display:flex'
    }
  });
  tocss.init();
</script>
```

## Runtime API

### `init()`

Initializes ToCSS, processes existing elements, and begins observing elements added later. It is an alias of `start()`.

```js
import { init } from '@tocss/vanilla';
init();
```

### `start()`

Starts the runtime. Calling `start()` or `init()` more than once does not create additional observers.

```js
import { start } from '@tocss/vanilla';
start();
```

### `usePreset(preset)`

Deep-merges a preset configuration into the runtime configuration. Register presets before initialization.

```js
import { init, usePreset } from '@tocss/vanilla';
import defaultPreset from '@tocss/default';

usePreset(defaultPreset);
init();
```

### `config(configuration)`

Deep-merges custom configuration, creates configured color variables, and updates the document theme.

```js
import { config, init, usePreset } from '@tocss/vanilla';
import defaultPreset from '@tocss/default';

usePreset(defaultPreset);
config({
  theme: 'auto',
  colors: {
    brand: {
      light: '#7c3aed',
      dark: '#a78bfa'
    }
  },
  screens: {
    tablet: 'width >= 768px'
  }
});
init();
```

### Browser Global API

```js
tocss.config(configuration);
tocss.usePreset(preset);
tocss.start();
tocss.init();
```

## Configuration

The public configuration fields are:

- `theme`: `light`, `dark`, or `auto`.
- `colorScheme`: CSS `color-scheme` value.
- `debugging`: when true, preserves the original attribute value in `data-tocss`.
- `colors`: named colors or theme-specific color maps.
- `props`: property aliases or property functions.
- `presets`: reusable declaration sequences.
- `screens`: named media conditions.

### Themes

```js
config({ theme: 'auto' });
```

- `light` always uses light theme values.
- `dark` always uses dark theme values.
- `auto` uses the system dark-mode preference.

The current theme is stored in `data-theme` on the document root.

### Colors

```js
config({
  colors: {
    brand: {
      light: '#7c3aed',
      dark: '#a78bfa'
    },
    success: '#22c55e'
  }
});
```

```html
<div tocss="color:brand; background:success">Colored content</div>
```

### Property Aliases

```js
config({
  props: {
    c: 'color',
    p: 'padding',
    rad: 'border-radius'
  }
});
```

Property functions may generate multiple declarations:

```js
config({
  props: {
    px: value => `padding-left:${value};padding-right:${value}`
  }
});
```

### Custom Presets

```js
config({
  presets: {
    center: 'display:flex;align-items:center;justify-content:center',
    card: 'padding:1rem;border-radius:12px;background:white'
  }
});
```

```html
<div tocss="card; center">Centered card</div>
```

### Responsive Screens

```js
config({
  screens: {
    mobile: 'width < 640px',
    tablet: '(width >= 640px) and (width < 1024px)',
    desktop: 'width >= 1024px'
  }
});
```

```html
<div tocss="display:grid; @mobile{display:block}">Responsive content</div>
```

### Debugging

```js
config({ debugging: true });
```

Normally, ToCSS removes the `tocss` attribute after processing. Debugging mode also saves the original value in `data-tocss`.

## Syntax

### Attribute

```html
<div tocss="color:red; p:1rem; flex"></div>
```

Rules are separated by semicolons. The final semicolon is optional.

### Declarations

A declaration contains a property, a colon, and a non-empty value.

```text
color:red
border-radius:4px
--brand-color:#7f50ed
c:red
background:linear-gradient(red, blue)
content:"a;b"
```

Full CSS properties and custom properties pass through unchanged. ToCSS does not validate whether the browser recognizes a property.

Configured property aliases may replace full property names. If `c` maps to `color`, `c:red` generates `color:red`.

Colons, semicolons, commas, spaces, and braces inside balanced quotes or parentheses remain part of the value.

### Preset Tokens

A bare token must match a configured preset.

```text
flex; jcc
```

Preset values are declaration sequences. Presets may reference other presets. Circular references are ignored safely. Unknown bare tokens are ignored.

### Important Shortcut

Append `!` to a declaration or preset to apply `!important`.

```text
color:red!
flex!
```

For a property function or preset that generates multiple declarations, the shortcut applies to every declaration.

### Selector Blocks

Selector blocks scope their declarations to the generated element class.

```text
:hover{color:red}
.active{color:green}
[aria-expanded="true"]{display:block}
```

Selectors without `&` are appended to the generated class. Use `&` to position the class explicitly.

```text
& .icon{color:blue}
body &{display:block}
```

Blocks may contain declarations and additional selector blocks.

### Selector Lists

```text
:hover,:focus{color:red}
:is(.primary,.secondary){color:blue}
```

Top-level commas separate selectors. Commas inside functional selectors, brackets, parentheses, or quotes do not split the list. Backslashes do not escape top-level commas, so class names containing commas are not supported.

### Responsive Blocks

Use `@` with a configured screen name.

```text
@mob{display:none}
@mob,tab{display:block}
```

Known screen names become media queries. Unknown names in a screen list are ignored when at least one configured name is present.

### Dark Mode

The reserved `@dark` block applies when the theme is `dark`, or when it is `auto` and the system prefers dark mode.

```text
color:black; @dark{color:white}
```

### Conditional CSS Blocks

CSS conditional group rules may contain normal ToCSS declarations or selector blocks.

```text
@media (width >= 900px){display:grid}
@supports (display:grid){display:grid}
@container (width > 30rem){display:flex}
```

`@keyframes` is not supported yet because keyframes require a different internal grammar.

### Configured Color Modifiers

Configured color names become CSS variable references.

```text
color:brand
```

Modifiers use `/` segments:

```text
brand/50l
brand/+10l
brand/-10l
brand/80a
brand/+20a
brand/-20a
brand/+10l/80a
```

- `l` controls lightness.
- `a` controls alpha.
- `+` increases the current value.
- `-` decreases the current value.
- Unknown modifiers are ignored.

### Whitespace

Whitespace around rules, properties, values, selectors, and block boundaries is optional. Whitespace inside quoted strings and parentheses is preserved.

### Invalid Input

Structurally invalid input generates no CSS. Structural errors include:

- Unbalanced quotes.
- Unbalanced parentheses.
- Unbalanced square brackets.
- Unbalanced braces.

Declarations with missing properties or values are ignored. Valid declarations elsewhere in a structurally balanced attribute continue to render. Comments are not supported syntax.

## Default Preset Reference

### Default Property Aliases

```text
a=animation
ai=align-items
ac=align-content
as=align-self
ar=aspect-ratio
jc=justify-content
jf=justify-items
js=justify-self
d=display
ol=outline
olc=outline-color
olw=outline-width
ols=outline-style
olo=outline-offset
bd=border
bdr=border-right
bdl=border-left
bdt=border-top
bdb=border-bottom
bdc=border-color
bdrc=border-right-color
bdlc=border-left-color
bdtc=border-top-color
bdbc=border-bottom-color
bdw=border-width
bdrw=border-right-width
bdlw=border-left-width
bdtw=border-top-width
bdbw=border-bottom-width
bdlr=border-left and border-right
bdtb=border-top and border-bottom
bdlrc=left and right border colors
bdtbc=top and bottom border colors
bdlrw=left and right border widths
bdtbw=top and bottom border widths
rad=border-radius
radt=top border radii
radb=bottom border radii
radl=left border radii
radr=right border radii
radtl=border-top-left-radius
radtr=border-top-right-radius
radbl=border-bottom-left-radius
radbr=border-bottom-right-radius
i=inset
t=top
r=right
l=left
b=bottom
w=width
h=height
maxw=max-width
minw=min-width
maxh=max-height
minh=min-height
o=opacity
fw=font-weight
fs=font-size
ls=letter-spacing
lh=line-height
ta=text-align
td=text-decoration
c=color
bg=background
g=gap
m=margin
mt=margin-top
mb=margin-bottom
ml=margin-left
mr=margin-right
mlr,mx=left and right margins
mtb,my=top and bottom margins
p=padding
pt=padding-top
pb=padding-bottom
pl=padding-left
pr=padding-right
plr,px=left and right padding
ptb,py=top and bottom padding
z=z-index
trs=transition
trf=transform
shad=box-shadow
```

### Default Preset Tokens

```text
u=underline
b=bold
i=italic
cap=capitalize
up=uppercase
low=lowercase
tac=text-align:center
tal=text-align:left
tar=text-align:right
1ln=single-line text
1ln...=single-line text with ellipsis
rel=position:relative
abs=position:absolute
fixed=position:fixed
sticky=position:sticky
static=position:static
absfill=absolute positioning with inset:0
fixedfill=fixed positioning with inset:0
absc=absolute horizontal and vertical centering
absxc=absolute horizontal centering
absyc=absolute vertical centering
fixedc=fixed horizontal and vertical centering
row=flex row
col=flex column
flex=display:flex
aic=align-items:center
ais=align-items:start
aie=align-items:end
aib=align-items:baseline
jcc=justify-content:center
jcsb=justify-content:space-between
jcsa=justify-content:space-around
jcse=justify-content:space-evenly
jcs=justify-content:start
jce=justify-content:end
flexc=centered flex container
wrap=flex-wrap:wrap
grow=flex-grow:1
shrink=flex-shrink:1
block=display:block
grid=display:grid
none=display:none
il=display:inline
ilb=display:inline-block
w100=width:100%
h100=height:100%
whug=width:fit-content
hhug=height:fit-content
ofhid=overflow:hidden
ofclip=overflow:clip
ofscroll=overflow:scroll
ofauto=overflow:auto
ofvis=overflow:visible
cover=object-fit:cover
contain=object-fit:contain
box=box-sizing:border-box
ptr=cursor:pointer
nosel=user-select:none
```

### Default Screens

```text
mob: width < 480px
tab: (width >= 480px) and (width < 768px)
lap: (width >= 768px) and (width < 1024px)
desk: width >= 1024px
```

### Default Colors

```text
--prim
--second
--bg
--text
--border
--card
--overlay
--done
--err
--warn
--info
```

## Tailwind-Style Preset Reference

### Tailwind-Style Property Aliases

```text
w=width
h=height
minw=min-width
maxw=max-width
minh=min-height
maxh=max-height
m=margin
mt=margin-top
mr=margin-right
mb=margin-bottom
ml=margin-left
mx=left and right margins
my=top and bottom margins
p=padding
pt=padding-top
pr=padding-right
pb=padding-bottom
pl=padding-left
px=left and right padding
py=top and bottom padding
bg=background-color
c=color
fw=font-weight
fs=font-size
lh=line-height
ls=letter-spacing
br=border-radius
bd=border
bdc=border-color
bdw=border-width
shadow=box-shadow
opa=opacity
z=z-index
```

### Tailwind-Style Preset Tokens

```text
block=display:block
inline=display:inline
iblock=display:inline-block
hidden=display:none
flex=display:flex
iflex=display:inline-flex
grid=display:grid
col=flex column
row=flex row
wrap=flex-wrap:wrap
nowrap=flex-wrap:nowrap
itemsstart=align-items:flex-start
itemscenter=align-items:center
itemsend=align-items:flex-end
justifystart=justify-content:flex-start
justifycenter=justify-content:center
justifybetween=justify-content:space-between
justifyend=justify-content:flex-end
relative=position:relative
absolute=position:absolute
fixed=position:fixed
sticky=position:sticky
textleft=text-align:left
textcenter=text-align:center
textright=text-align:right
uppercase=text-transform:uppercase
lowercase=text-transform:lowercase
capitalize=text-transform:capitalize
italic=font-style:italic
notitalic=font-style:normal
underline=text-decoration:underline
nounderline=text-decoration:none
```

### Tailwind-Style Screens

```text
sm: width >= 640px
md: width >= 768px
lg: width >= 1024px
xl: width >= 1280px
2xl: width >= 1536px
```

### Tailwind-Style Colors

```text
slate50
slate100
slate500
slate900
gray100
gray500
gray900
red500
amber500
green500
blue500
indigo500
white
black
```

## Current Limitations

- Official React, Vue, and other framework adapters are not available yet.
- `@keyframes` is not supported yet.
- ToCSS requires JavaScript in the browser.
- Comments are not supported inside `tocss` syntax.
- Class names containing commas are not supported in selector lists.
- Do not use `npm install tocss`; use scoped `@tocss/*` packages.
- Do not add a ToCSS stylesheet; the runtime generates CSS.

## Canonical Links

- Installation: https://tocss.com/docs/installation/
- Syntax: https://tocss.com/docs/syntax/
- API and configuration: https://tocss.com/docs/configuration/
- npm vanilla runtime: https://www.npmjs.com/package/@tocss/vanilla
- npm default preset: https://www.npmjs.com/package/@tocss/default
- npm Tailwind-style preset: https://www.npmjs.com/package/@tocss/tailwind
- npm core: https://www.npmjs.com/package/@tocss/core
- GitHub: https://github.com/tiennguyenvan/tocss