css-examples: the runnable CSS samples behind the MDN reference pages

A repository of demonstration pages, not a framework

css-examples is a collection of code examples that accompany various MDN CSS documentation pages. That is the whole scope, and understanding it changes what you should expect from the repository.

There is no library here, no build step, and no API to call. What there is, in the directories the README describes, are small self-contained pages that demonstrate one CSS behaviour each, and that can be opened directly in a browser. The primary language is HTML, and the topics are css and examples.

The main directory list in the repository is broad: flexbox, grid, multicol, logical, masking, path, shapes, scroll-snap, target-text, transitions, time, houdini, cssom, css-text, display, flow, layout, contain, feature-queries, min-max-clamp, modules, variable-fonts, web-fonts, backdrop, box-alignment, is-where, inline-formatting, visual-formatting, howto, learn, css-cookbook, images, and alt-style-sheets among them. Each one is a folder of example files for a particular area of CSS.

The audience is two groups, and they use it differently. The first is MDN contributors, who need examples that can be embedded into documentation pages and kept current as the browser changes. The second is developers, who want a working file to read, since an example that runs in a browser is often faster to learn from than a specification.

The licence is CC0, a public domain dedication, which is the right choice for this kind of repository: the samples are meant to be copied into your own code without attribution strings attached.

Why an example lives here instead of in the documentation page

The note at the top of the README explains the rule, and it is the most useful thing in the file for anyone considering a contribution.

An example can be included directly in MDN pages using the {{EmbedLiveSample()}} macros, or as regular Markdown code blocks. The README notes that these methods are simpler to maintain, since the code lives beside the rest of the content.

So the default for MDN contributors is to keep the example in the documentation repository itself. This repository exists for the other case, and the README states the condition plainly: only add examples to this repository if your example does not easily run on MDN pages for technical or security reasons.

That is a much narrower purpose than the repository's size suggests. Most of the directories here are for samples that need to be independent pages rather than embedded fragments, or that need a control surface, or that are linked from a live demo rather than shown inline.

The practical consequence for a contributor is that a new example for a well supported feature probably belongs in the documentation repository, and only comes here when it genuinely needs to stand alone. For a user of the repository, the effect is that everything in it is a standalone page, and that is exactly what makes it useful outside MDN.

One idea demonstrated three ways in the timing function directory

The README works through the directories one at a time, and the animation-frames-timing-function directory is the richest example of the approach.

It contains a simple example demonstrating the difference between the steps() timing function available for CSS animations and transitions, and the new frames() timing function. Alongside the main page there are versions showing the same timing function used with transitions, and used with the Web Animations API.

Three files, one concept. That is the pattern the repository follows everywhere. A CSS feature often has several entry points, and a single demo that only shows the most common one teaches half of it. The transitions variant shows the timing function applied in a context people forget, and the Web Animations API variant shows the same behaviour driven from script, which is where people look when the CSS version does not do what they expected.

Every one of these runs live from a published URL rather than needing to be cloned and served, for example:

http://mdn.github.io/css-examples/animation-frames-timing-function/

The same is true of the other directories the README calls out. The counter-style-demo directory holds a demo for the @counter-style documentation, the moz-context-properties directory a demo for -moz-context-properties, and the object-fit-basics directory a page demonstrating typical usage of different object-fit and object-position values.

Editable samples, galleries and the tools directory

Not every example is a passive page, and the directory names distinguish the three kinds.

The editable-examples directory holds CSS examples intended to be embedded in MDN pages as live editable samples, and the repository also contains editable-samples and editable-samples-2 directories. The point of an editable sample is that the reader changes a value and sees the result immediately, which is only possible when the CSS is shipped to the browser rather than shown as text.

The object-fit-gallery directory is described as a fun image gallery that uses object-fit to display the images more nicely, both in thumbnail and full size view, which is the kind of constructed example that shows a property in a setting a reader recognises. The object-fit-basics directory is the plainer counterpart, a page demonstrating typical usage of different object-fit and object-position values, and the overscroll-behavior directory is a simple page demonstrating typical usage of different overscroll-behavior values.

The tools directory is the odd one out, because it holds tools for working with CSS rather than examples: a color picker and a box shadow generator, both published as live pages.

That last category is worth a moment of thought. A generator is not a demonstration, and including one in a repository of examples is a decision about scope. What the tools have in common with the examples is that they are standalone static pages that need no server and no build, so they can be linked from a documentation page and used without installing anything.

A directory per CSS feature area, and how to find the one you want

The repository layout is the index. A developer looking for a specific behaviour scans the directory names, and the names are feature areas rather than abstract categories.

Layout mechanics have their own directories, with flexbox, grid, multicol, inline-formatting, box-alignment, visual-formatting and flow among them. Graphics features are separated too, with masking, shapes, path and backdrop. Effects and motion have transitions, time and scroll-snap. Text and fonts have css-text, font-features, target-text, variable-fonts and web-fonts. Platform capabilities have contain, feature-queries, is-where, houdini, modules, cssom, min-max-clamp and css-cookbook. There are also howto and learn directories for task oriented content, and images and assets directories for shared files.

The tree also contains the kind of administrative directories you would expect in an MDN project: a .github/ directory, .editorconfig, a .gitignore, two markdownlint configuration files, .markdownlint-cli2.jsonc and .markdownlint.jsonc, a .prettierrc.json and a .prettierignore for formatting, a _config.yml, and the usual community files in CODE_OF_CONDUCT.md, CONTRIBUTING.md and SECURITY.md.

Two naming details stand out. The moz-context-properties directory is named after a prefixed property, so a vendored or experimental feature still gets a home, and the alt-style-sheets directory suggests the repository also covers the browser side of CSS, not only the language itself.

Markdown linting and Prettier are the review gate

The repository is mostly HTML and CSS, and the tooling in the root tells you how contributions are checked.

There are two markdownlint configuration files, .markdownlint.jsonc and .markdownlint-cli2.jsonc, which is a hint that the same rules are applied from two entry points, the classic configuration and the newer CLI. There is a .prettierrc.json with a matching .prettierignore, so formatting is enforced by Prettier rather than by hand, and an .editorconfig for the whitespace conventions that editors should follow.

The .github/ directory holds the workflows, and a SECURITY.md at the root means the project takes reports seriously. A file like that is mostly a statement of intent, but for a repository whose contents are embedded in documentation pages viewed by millions of readers, having a published path for reporting a problem is a reasonable expectation.

The contribution path is the standard one. The README points at CONTRIBUTING.md for the details, notes that the MDN Web Docs project welcomes contributions from everyone through content, engineering or translation work, and asks participants to read the Code of Conduct in CODE_OF_CONDUCT.md. Communication channels are listed as well, pointing at the MDN community channels page.

One asymmetry is worth flagging for anyone deciding where to put an example. The README asks you to read CONTRIBUTING.md in this repository, but the work of contributing to the documentation itself happens in the MDN Web Docs project, which has its own contribution and translation processes. The examples repository is a satellite of that project, not a replacement for it.

Publishing through GitHub Pages, and a project with no releases

The examples are served from mdn.github.io, which is the GitHub Pages address for this organisation, and the README links to the live pages directly in each section. That is the delivery mechanism: no build, no package, no version.

There are no GitHub releases for the project, and that is consistent with the model. The content is a set of static pages tied to documentation pages that change whenever the browser or the specification changes, so a numbered release would imply a stability the content does not have. The last push to the repository was on 2026-10-07, so the pages are updated continuously rather than in batches.

The consequence for a user is straightforward. If you want a copy of an example, take the file from the repository and adapt it. If you want to see the current version, open the live URL. If you want to know whether an example still reflects current browser behaviour, you have to check the source, because there is no changelog that says which example changed and when.

The CC0 licence makes that copying entirely unproblematic. There is no attribution requirement and no share-alike clause, which is what you want from a reference set that people are expected to lift code from. The homepage of the project points at the MDN CSS reference itself, developer.mozilla.org/docs/Web/CSS, which is where the prose for these samples lives.

Editorial conclusion

css-examples suits MDN contributors and anyone who wants working, self-contained CSS to read or copy, since each directory is a small static page that runs in a browser with no build step. It does not suit you if you are looking for a component library, a framework or a design system, because there is no API here, only demonstration pages, and it does not suit a team that wants examples embedded in its own documentation site without adopting the MDN macro and page structure. Check three things before you use a sample: that the feature it demonstrates is one MDN still documents at developer.mozilla.org/docs/Web/CSS, that the example is one of the directories the README describes as runnable, and that you do not need a build step, since these are plain static pages. The last push to the repository was on 2026-10-07 and the project has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. mdn/css-examples on GitHub
4. Project website
5. README