m3l-design
m3l-design is the design system of the monte3l
organization: warm, legible foundations for everything monte3l builds. It
covers the colour, type, shape and motion tokens, seven plain HTML and CSS
components, and the contrast tables that show every pairing passes WCAG 2.2 AA.
- Version:
v1.3.2 (the system's "v1, signed off 2026-09-26")
- Docs: design.monte3l.com, built from this repository by its own docs kit
- License: MIT, with the two bundled fonts under SIL OFL-1.1. See License.
- Credits: Enrico Lionello (
enri3l) and Giulia Montevecchi (giulmonte), for monte3l. See AUTHORS.md.
Who is this for
- Someone building a monte3l repository with a visual surface (CSS, HTML, a
docs site, coloured terminal output) who wants the tokens and components
copied in at a pinned version.
- Someone with a markdown-only monte3l repository who only needs the
markdown rules and a version marker.
- A maintainer changing a token or component and cutting a release.
New to design tokens?
Quickstart
Adoption is copy-based. Never add a live dependency on this repository.
Pick the tier that matches your repository:
| Your repository has | Tier | What to do |
|---|
| Markdown only | Content | Follow the markdown rules in the org blueprint and add a design/README.md with - **Version adopted:** `vX.Y.Z` |
| Any CSS, HTML, docs site or coloured terminal output | Vendored | Add the marker, then run the sync script below. A docs site also gets the docs kit that builds and gates it |
For the vendored tier, first create design/README.md in your repository with
the line - **Version copied:** `vX.Y.Z` . The script never creates this
file, and exits with code 2 if it is missing. Then, from a clone of this
repository:
bin/sync-design.sh vX.Y.Z /path/to/your-repo
The script downloads the release, verifies it with gh release verify and
SHA256SUMS, and replaces design/source/, design/tokens.css and
design/SHA256SUMS. It only edits the version lines of design/README.md.
| Option | Effect |
|---|
--dry-run | Show what would change, and write nothing |
--from <git-ref> | Take the payload from this clone instead of a release, to rehearse a sync before the tag exists |
Commit what it wrote. Your own divergence goes in design/local/, which the
script never touches.
[!IMPORTANT]
Never hand-edit design/source/. A sync replaces it wholesale. If something
here needs to change, change it in this repository and cut a release.
What a sync gives you
your-repo/design/
├── README.md # your marker: the version line is the only part the script edits
├── source/ # the components, foundations, fonts, resolver and brand book
├── tokens.css # light and dark custom properties, @font-face rules, type classes
├── SHA256SUMS # the hash of every file in source/ and of tokens.css
└── local/ # your own divergence, never touched by a sync
To check that a copy is unedited, run cd design && sha256sum -c SHA256SUMS
(shasum -a 256 -c SHA256SUMS on macOS).
Use it
Link the tokens first, then the component bundle:
<link rel="stylesheet" href="design/tokens.css">
<link rel="stylesheet" href="design/source/components/bundle.css">
- Themes. The light theme is the default and the dark theme follows
prefers-color-scheme. Set data-theme="light" or data-theme="dark" on an
element to override it.
- Type styles are classes:
display, heading-1 to heading-4,
body-lg, body, body-strong, label, caption, code and
code-strong.
- Components are plain HTML and CSS with no runtime. The markup for each
one is in
source/components/<Name>/README.md.
- Motion drops to zero under
prefers-reduced-motion, through the tokens.
- Local rules go in
design/local/. See
m3l-groundwork/design/local/
for the reference implementation.
What is in here
The repository root has the same shape as a consumer's design/ directory, so
adopting a release is a plain copy.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
