Draw something: contribute a pixel-art template (no Rust needed)

[vyncint]

You do not need Rust to contribute here — not to write it, and not to install it. A template is a text file. Drop it in a folder, open a pull request, and your art ships inside the crate, with your name on it.

mossaic itself installs as a prebuilt binary (brew, or a download), so nothing below involves a compiler.

This is the one that shipped with 0.6.0, drawn on a real 2027 graph:

Anyone can then draw yours across their own year with one command:

mossaic-art --template your-name --year 2027

---

What a template is

Seven rows — one per weekday, Sunday first, weekend included — by up to 53 columns, one for each week of the year. Every cell is a shade from 0 to 4. That is the whole format:

# name: Cat
# author: @you
# description: A cat's face, nine weeks wide

400000004
440000044
022222220
020222020
022222220
002222200
000222000

Which draws this — ears in the brightest green, the face a shade down, eyes left dark:

█·······█
██·····██
·▒▒▒▒▒▒▒·
·▒·▒▒▒·▒·
·▒▒▒▒▒▒▒·
··▒▒▒▒▒··
···▒▒▒···

A template does not have to fill the year. That one is nine columns — nine weeks — and mossaic centres it. Thirty-three days, seventy-eight commits. Small and clear beats wide and vague at this resolution.

Save it as art/templates/cat.art and it works. There is no list to add it to — build.rs finds every .art file in that directory and embeds it when the crate compiles. If your file is there and the tests pass, --template cat works.

---

First, get mossaic — no toolchain

brew install vyncint/tap/mossaic        # macOS and Linux

Or download a static binary and skip package managers entirely:

target=x86_64-unknown-linux-musl        # or aarch64-unknown-linux-musl,
                                        # aarch64-apple-darwin, x86_64-apple-darwin
curl -fsSL "https://github.com/vyncint/mossaic/releases/latest/download/mossaic-${target}.tar.gz" \
  | tar xz --strip-components=1 --wildcards '*/mossaic*'

Windows: the .zip from the
latest release. If you
do have Rust, cargo install mossaic --locked works too — but nothing here
needs it.

Draw one by hand

The editor is the easy way, and it is why the --draw flag exists:

mossaic-art --draw -o your-name.art

key
arrows, or h j k l	move the cursor
Home / End	jump to the first or last column
0 1 2 3 4	paint that shade, and take it as the brush
space, enter	cycle this cell 0 → 1 → 2 → 3 → 4 → 0
click and drag	paint with the mouse; right-click clears
move the pointer	read a day without painting it
c / i	clear the canvas / invert every shade
u, ctrl-z	undo — a hundred and twenty-eight steps deep
s	save to the -o file
? / q	help / leave

While you draw it tells you the date under the cursor, how many days sit at each shade, what the picture would cost in commits, and how well your shades will separate for a reader. Days in the partial weeks at either end of the year are drawn as · — they can be painted and they cost nothing, because they are not days the year has.

Start from an existing one if that is easier:

mossaic-art --template dragon --draw -o your-name.art

Or skip the editor entirely. It is a text file — type 0s and 4s in whatever you already use. You can also write the shades as blocks ( ░▒▓█) if you would rather read the file as a picture; the two mean the same thing and you can mix them.

Or start from an image:

mossaic-art --image logo.png --year 2027 --dither

That fits a PNG to the calendar and quantises it, which is a good way to find a silhouette — then open it in --draw and tidy it up by hand.

---

The one rule worth knowing before you start

Use 0, 2 and 4. Not all five.

GitHub's five greens are not evenly spaced. Measured across every palette it ships:

	1	2	3	4
0	20 · faint	50 · clear	62 · clear	70 · clear
1		9 · faint	36 · clear	35 · clear
2			11 · faint	35 · clear
3				17 · faint

Every adjacent pair is faint. So {0, 2, 4} is the only set of three with no faint pair in it, and there is no clear set of four — a picture using all five cannot avoid putting two near-identical greens beside each other, however carefully it is drawn. It will look thorough in your terminal and read as a smudge on the graph.

The reference template learned this the hard way: dragon.art was drawn in all five shades first, and only rendering it to a real chart showed it up.

The test suite will not catch this for you — it is a design judgement, not a format error. The tool will, on the last line of --template:

shades 0 2 4  ·  closest pair 2 and 4  ·  ΔE 35, clear     <- good
shades 0 1 2 3 4  ·  closest pair 1 and 2  ·  ΔE 9, faint  <- redraw it

On shape: seven by fifty-three is about 7.5:1 — very wide, very short. Forms that stretch along it read far better than ones that want to be square. A serpent works. A portrait does not.

---

Check it before you send it

Two commands, and neither needs a toolchain:

# 1. Does it draw, and do the shades separate?
mossaic-art --matrix your-name.art --year 2027

# 2. How it will look in the catalogue. mossaic reads ./templates/ as well as
#    its built-ins, so drop a copy there and it appears beside them — under
#    the name it will ship with, which is the point of trying it this way.
mkdir -p templates && cp your-name.art templates/
mossaic-art --list-templates

The third check is cargo test, which does need Rust — but you do not have
to run it. CI runs it on your pull request and tells you the same thing. If
you have Rust and would rather see it locally, it is cargo test in a clone.

The suite checks five things, so a mistake is a failing test with the reason rather than a broken --template for whoever tries it first:

1. exactly seven rows, and a width between 1 and 53;
2. only shade characters;
3. a # name: and a # description: — a template with neither is one nobody can tell apart in a listing;
4. no two templates with the same title;
5. more than one shade, since a picture drawn in one is a blank graph.

The file name is what people type after --template, so it must be lowercase letters, digits and dashes.

---

Send it

The file goes in art/templates/. If you use git:

git switch -c template/your-name
git add art/templates/your-name.art
git commit -s -m "feat(templates): add <your-name>"
gh pr create

If you would rather not, GitHub's web interface is enough: open
art/templates/,
press Add file → Create new file, name it your-name.art, paste the seven
rows in, and choose "Create a new branch and start a pull request". Tick
"Sign off and commit changes" if the box is offered — that is the DCO
below.

Either way there is no build step anywhere in this.

Two house rules, both in CONTRIBUTING.md:

• git commit -s. The sign-off is the DCO — you are saying you have the right to contribute the work.
• No AI attribution in the commit. Use whatever tools you like; the human opening the pull request is the author of record. CI checks both.

Put a screenshot of --template your-name --year 2027 in the PR description. It is the quickest way for anyone to see what you made.

---

Ideas, if you want one

Comment to claim one and nobody else will start it. Or ignore the list entirely — something nobody thought of is better than something on it.

Shapes that suit a very wide, very short canvas:

• a dachshund — the aspect ratio was made for this
• a train with carriages, one per month
• a wave, Hokusai-style, cresting somewhere around August
• a city skyline
• mountains, with a sun behind them
• an ECG trace — flat, then a heartbeat, then flat
• a music staff with notes on it
• a rocket and its arc
• a DNA helix
• a caterpillar, or a centipede
• a bridge
• a fish, or a school of them
• seasonal: a snowflake for December, a pumpkin for October, fireworks for the new year

What will and will not be merged

Yes: anything that reads as what it is meant to be, in shades that separate. Simple beats detailed at this size — 371 cells is not much resolution, and the ones that work are silhouettes.

No: logos and trademarks you do not own; anything a reader would find hostile; and pictures that use all five shades, which will be sent back with a suggestion rather than rejected.

Unsure whether an idea will work? Open a draft PR with the .art file and ask. Half of drawing at this size is finding out what survives the resolution, and that is quicker to see than to argue about.

---

Questions are welcome in this thread. If something in these instructions does not work, that is a bug in the instructions and worth saying so — the guide is only useful if it is right.

[vyncint]

Updated: you no longer need a Rust toolchain for any step of this.

When this was written the only way to get mossaic was cargo install, which made the title half a promise — a template is a text file, but you still had to install a compiler to see what you drew.

That is fixed. mossaic 0.6.2 ships prebuilt static binaries, and there is now a Homebrew tap:

brew install vyncint/tap/mossaic        # macOS and Linux, Intel and arm64

or a download, if you would rather not use a package manager — the Linux builds are statically linked, so they run on any distribution.

What changed in the instructions above

• every cargo run --bin mossaic-art -- … is now just mossaic-art …
• cargo test is no longer a step you have to run: CI runs it on your pull request and tells you the same thing
• the "check it" step uses ./templates/, which mossaic reads alongside its built-ins — so you can see your template in the catalogue, under the name it will ship with, without cloning anything
• you do not need git either. GitHub's web interface will create the file and open the pull request, sign-off box included

So the whole path is: install a binary, draw, paste seven lines into a form. No clone, no compiler, no build step anywhere.

The ideas list further up is still open, and still open to things nobody thought of.