Syntax overview

Statements

A doodle is a list of statements, like the body of a CSS rule. A { before ; makes a block; otherwise it is a declaration.

Declarations

A property and a value. Names that start with @ are directives: css-doodle reads them and does not emit them as CSS. Every other property applies to every cell.

@grid @size @place @gap @shape @content @seed @use

Selector blocks

Style the component, the grid, or an element inside each cell. :doodle and :container are generated once, not once per cell. A selector that begins with a colon attaches to the cell; any other is a descendant.

:doodle :container :hover span

Conditional blocks

Style only the cells that match. @media keeps its CSS meaning. @keyframes is hoisted.

@cell(…) @nth(…) @random

Blocks can nest. Comments are /* … */. As in CSS, the last declaration before } does not need a semicolon.

@grid and background are declarations, :doodle and :hover are selector blocks, and @cell is a conditional block.

:doodle {
  @grid: 6 / 60vmin _1px;
}

background: #eee;
transition: .2s;

@cell(random .3) {
  background: #000;
}

:hover {
  background: #e6437d;
  scale: 1.2;
  z-index: 40;
}

Functions

A function sits where a CSS value would. css-doodle evaluates it again for each cell, so @i is that cell’s index and @r(…) can be a different random value in every cell.

@name(arguments)

A doodle function, evaluated once per cell.

$(expression)

Calc. $(1 + 2) is 3.

$px(expression)

Calc, then a unit. $px(@i * 10) is a length.

Optional parentheses

Drop the parentheses when there are no arguments. @i means @i().

A number after the name

A number stuck to the function name becomes the first argument. Math names that already end in a digit, such as @log2, are left alone.

Composition

A dot chains functions. The rightmost one runs first: @p.cycle(a b c) is @p(@cycle(a b c)). The inner @ is optional.

@grid: 5 / 60vmin _2px;
background: #000;
border-radius: @p.cycle(100% 0 0 0);

Units

A unit on an argument is kept on the result. @r(10px) and @r(10)px both produce lengths. A leading operator on a cell function is a modifier: @i(*10px), @x(-1), @t(%360deg).

Arguments

Separate arguments with commas. If an argument contains a comma, wrap it in parentheses or quotes.

• In pick functions, [a-z] and [0-9] expand to a list of values.
• ±1 becomes two arguments, -1 and 1: @r(±10deg).
• --name reads that custom property when the doodle is generated.
• A backtick is a double quote, so a doodle can live in a double-quoted HTML attribute.

Cell selectors

A conditional block runs only on the cells it matches. @cell can express any of the tests below; the other names are shorter spellings. Several arguments mean "any of these". not before the parentheses inverts the test.

The first block paints both diagonals. The second rounds every cell that is not near the center.

@grid: 9 / 60vmin _1px;
background: #eee;

@cell(x = y, x + y = 10) {
  background: #000;
}
@cell not (dr < 3) {
  border-radius: 50%;
}

Expressions

Use $(…) when a value needs arithmetic or a comparison. The same language is accepted in @cell, @match, @random, and @shape.

JavaScript math names work, plus gcd(a, b) and match(cond, a, b). Chained calls run right to left: tan.cos.sin(x).

Operators

Highest precedence first:

Cell variables

Inside a cell selector, these names are available as well as custom properties:

Each ring’s size and hue come from $(…) and the cell index @i. n is the custom property --n.

@grid: 1x12 / 60vmin;
--n: 12;
@place: center;
@size: $%(100 - 6 * @i);
border: 2px solid hsl($(360 / n * @i), 70%, 55%);
border-radius: 50%;

Embedded languages

These functions take a body of their own, then compile it to an image or a shape. You use the result as a CSS value, usually on background, clip-path, or @content.

@doodle

A nested doodle, rendered to an image, or inserted as an element with @content.

The body is ordinary doodle code. Digits on the name set the pixel size of the image.

background: @doodle( ... );

@svg

An SVG image for background, mask, or @content.

Blocks are elements, declarations are attributes. circle*8 repeats the tag.

background: @svg( ... );

@shape

A polygon() for clip-path.

A preset name, or polar commands in the angle t.

clip-path: @shape( ... );

@pattern

A pixel pattern drawn on the GPU, when a real grid would be too heavy.

A virtual grid, a fill, and match rules that pick a color.

background: @pattern( ... );

@shaders

A WebGL image from GLSL, for background or @content.

Fragment source, or named sections. texture { } can hold a nested doodle.

background: @shaders( ... );

The body still uses name: value and name { }. Each language decides what a name and a value mean.

@grid: 1 / 60vmin;
background: @svg(
  viewBox: 0 0 18 16;
  circle*8 {
    fill: #000;
    r: .7;
    cx: @n(*2);
    cy: 8;
  }
);

Error recovery

Incomplete input still produces a doodle. css-doodle reports each of these once per component, in the console and on the diagnostics property.

Going further

• Start from a grid Build a finished pattern in five steps.
• Reference Every property, function, selector and method.
• Full grammar What the parser accepts, in one document.