CLI tool
css-doodle/css-doodle avatar
css-doodle/css-doodle

css-doodle: a web component for CSS generative art

A web component for visual art and creative coding

6,081 stars211 forksJavaScriptMIT

At a glance

What is it?
css-doodle turns a grid of CSS rules into patterns, backgrounds and animations. It is a small web component with a parser and generator underneath, and it asks you to think in CSS rather than in canvas calls.
Who is it for?
Adopt css-doodle when you want generated patterns, backgrounds or icons that stay in CSS and ship as one custom element, and when you are comfortable that the drawing language is the project's own, not a standard. Skip it when you need SVG or canvas output with a stable specification, when you need server-side rendering of the result, or when the pattern must be identical across browsers without a test pass.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 8 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • css-doodle/css-doodle6,081 ★ · +40
Star history
Repository2026-09-232026-11-15
css-doodle/css-doodle6k6.1k

40 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What css-doodle is for

The README describes css-doodle as "a web component for visual art and creative coding with CSS": you write CSS rules for a grid of cells, mix in randomness and math, and draw generative patterns, backgrounds, icons and decorations. That list is the honest scope. This is not a layout library or a design system. It is a drawing tool whose output happens to be CSS.

The audience is narrow on purpose. If you write CSS for a living and want a background that changes on every reload, or a set of decorative shapes for a landing page, css-doodle gives you a syntax for that without reaching for canvas or an image editor. If you have never written CSS, the project's own examples will read as noise: the drawing language is built out of CSS properties, and the value of the tool comes from already knowing what those properties do.

The interesting part is where the output lives. A doodle is a custom element in the page, so the result is inspectable in devtools like any other DOM. You can copy a rule out of the generated markup and see what the browser actually rendered. That is a different debugging experience from a canvas painting, where the pixels and the source are separated by a draw loop.

The grid, the @-functions and the parser

The README's example links to a playground doodle:

css
<css-doodle>
  @grid: 4 / 480px / blue +.75;
  border-radius: @pn(100% 0, 0 100%, 50%);
  background: #fff;
</css-doodle>

@grid sets up the grid of cells, and the rules after it are written for those cells; the README describes the model as CSS rules for a grid of cells mixed with randomness and math.

Under the hood the package is split into named exports, which tells you how the author thinks about the internals. package.json exposes "./component", "./generator", "./parser" and "./meta" as separate entry points, with the root export pointing at css-doodle.min.js. The parser reads the doodle syntax, the generator turns it into markup and style rules, and the component wires that into a custom element. The build script is node ./build/index.js, and the test script runs node --test across test directories named core, parser, generator, component, lib and fuzz. A fuzz directory in a CSS tool is a sign that the parser is treated as the risky part, which matches what you would expect from a language with its own grammar.

That split is the most useful thing to know before adopting. If you only want to draw, you take the component. If you want to generate doodles outside a browser, the parser and generator exports are the pieces to look at, though the README does not document them as a public API.

Installing css-doodle and drawing a first pattern

The package is published on npm as css-doodle, and package.json sets "type" to "module", so it ships as an ES module. The files field includes css-doodle*.js and the src directory, so the built bundle and the source both come down with the install.

The README's Development section lists `npm install`, `npm test` for the unit tests and `npm run build` for css-doodle.min.js, and says `make` runs both:

bash
make

The Makefile defines all as test followed by build, and the build target runs npm run build, which is node ./build/index.js. Running make therefore installs dependencies, runs the test script and produces the bundle at ./css-doodle.min.js.

With the element registered, the README's example doodle can go into your page:

css
<css-doodle>
  @grid: 4 / 480px / blue +.75;
  border-radius: @pn(100% 0, 0 100%, 50%);
  background: #fff;
</css-doodle>

If you would rather not build anything, the site at css-doodle.com is the reference for the syntax and hosts the tools listed in the README: a Playground for writing and sharing doodles, Shapes for CSS polygon shapes, and an SVG playground. Those pages are where you should prototype before committing a pattern to a codebase, because the README itself is short and points at the docs rather than reproducing them. For previewing and exporting images or videos there is a separate CLI, cssd, in the css-doodle/cli repository; it is a different package from this one.

Where css-doodle gets in the way

The language is the project's own. @grid, @p and the rest are not CSS, and browsers do not understand them. Everything depends on the component being loaded and parsing your markup before anything appears. That is a real failure mode for a decorative background on a marketing site, and the README does not describe a no-JavaScript fallback.

Second, the output is generated DOM. A five by five grid is twenty-five elements, and the pattern scales with the grid declaration, not with your intent. The README does not discuss performance limits, and there is no guidance in it on how large a grid can get before the page suffers. Treat that as unknown rather than free.

Third, this is a rendering tool, not an export tool. The README points at the SVG playground and the cssd CLI for producing images and video, which is an admission that the component's job ends at the browser. If your pipeline needs a PNG at build time, you are outside the core package and into adjacent tooling.

Fourth, the version history deserves a look before you pin. Recent releases run v0.67.0, v0.67.1 and v0.68.0, and the zero in front is not decoration. A pre-1.0 syntax can change between minor versions, so a pattern written against one release is not guaranteed to render the same under the next. The repository keeps a changelog directory, which is the place to check.

css-doodle against plain CSS and against canvas

The obvious alternative is writing the CSS yourself. For a fixed pattern that is the right call: a repeating-linear-gradient or a handful of pseudo-elements costs nothing, needs no script, and cannot break when a dependency updates. css-doodle earns its place only when the pattern is parameterised or randomised. The moment you want one rule that produces a different result per cell, hand-written CSS turns into a generator you maintain yourself, and that is exactly what this project already is.

The other alternative is canvas or SVG. Canvas gives you per-pixel control, a mature drawing API and straightforward export to an image, at the cost of losing CSS entirely: no media queries, no custom properties, no devtools inspection of individual shapes. SVG sits between the two, with a real specification and a DOM you can style, but no built-in notion of a grid of generated cells. css-doodle's answer is to keep everything in CSS and accept a private syntax. That trade is the whole product. If you value the specification more than the syntax, SVG is the safer choice; if you value writing the pattern in the same language as the rest of your stylesheet, this is the tool that lets you.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-11-02, the same day as the v0.68.0 release. The releases before it, v0.67.1 and v0.67.0, are dated 2026-10-29 and 2026-10-28, so recent releases have landed days apart. package.json lists yuanchuan as the author.

The practical upgrade cost comes from the pre-1.0 version number. A minor bump can change the doodle syntax or the generated markup, and since the component renders into the page, a change shows up as a broken background rather than a build error. The repository has a changelog directory and a test suite covering the parser and generator, but the README does not document a migration path between versions. Pin the version, and read the changelog before moving.

Licence is MIT, which is permissive and places few obligations on how you use the output. The MIT text in the LICENSE file is the authoritative source; nothing here should be read as legal advice about your particular distribution.

Editorial conclusion

Adopt css-doodle when you want generated patterns, backgrounds or icons that stay in CSS and ship as one custom element, and when you are comfortable that the drawing language is the project's own, not a standard. Skip it when you need SVG or canvas output with a stable specification, when you need server-side rendering of the result, or when the pattern must be identical across browsers without a test pass. Before committing, open css-doodle.com and run one of your own patterns through it, check which release the site documents against the version in package.json, and read the changelog entries between that version and the latest tag.

Frequently asked questions

How do I install css-doodle?

The package name in package.json is css-doodle, and the repository's Makefile builds it: the all target runs the test script and then npm run build, producing css-doodle.min.js. The README's Development section lists npm install, npm test and npm run build, and it points at css-doodle.com for documentation.

Does css-doodle work without JavaScript?

No. The doodle syntax is parsed by the component and expanded into real elements and CSS in the browser, so if the script does not load, the markup is not rendered. The README does not describe a no-JavaScript fallback.

Can css-doodle export images or videos?

Not from the core package. The README points at a separate CLI called cssd, in the css-doodle/cli repository, for previewing and generating images and videos, and at an SVG playground on the project site.

Is css-doodle a stable API?

The version numbers are still pre-1.0, with v0.68.0 the most recent release. Minor releases can therefore change behaviour, and the repository keeps a changelog directory for checking between versions.

Official sources

  1. css-doodle/css-doodle on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/css-doodle-css-doodle.svg)](https://hysenlabs.com/projects/css-doodle-css-doodle)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/css-doodle-css-doodle.svg)](https://hysenlabs.com/projects/css-doodle-css-doodle)

Was this useful?