There is a specific kind of GitHub profile that makes you stop scrolling. Not the one with forty badges. The one where the first line types itself:
A README can't run JavaScript and it strips your CSS, so that line isn't code. It's a GIF. Which sounds trivially easy, and it is, right up until you look at your profile on a friend's laptop and see this:
Left and right are the same text, same font, same export settings except one. The left one looks like it was cut out with safety scissors. Here's what's going on, and how to never ship the left one.
Why transparent GIFs get a crust
When a browser draws text, the edges of each letter aren't solid. They're a ramp of semi-transparent pixels, 15% blue here, 60% blue there, and that ramp is what makes a curve look like a curve instead of a staircase.
GIF has no idea what "60% blue" means. The format dates from 1989 and gives every pixel exactly two choices: fully there, or fully gone. So when a transparent GIF gets exported, each of those soft edge pixels has to be rounded to one or the other, and the ones that survive have to be given a solid color.
Which color? That's the whole bug. The edge pixels get blended against something before they go solid, and most tools blend them against white. On a white page you'd never notice, because a letter fading into white on a white page is exactly right. On #0d1117 it's a one-pixel white outline around every letter you typed.
That "something" has a name. It's called the matte, and it's the only setting that differs between the two halves of that comparison. Left: matte white. Right: matte #0d1117, which is GitHub's dark background.
So rule one is short: the matte must match the page the GIF will sit on.
The problem with rule one
A GitHub README doesn't sit on one page. It sits on at least three:
- Light:
#ffffff - Dark:
#0d1117 - Dark dimmed:
#22272e
A transparent GIF can only be matted for one of them. Pick dark and your light-mode visitors get a dark fringe instead. You've moved the scissors, not put them down.
You have two honest ways out.
Option A: stop being transparent. Give the GIF a solid background that matches one theme and accept a visible rectangle on the others. This is what most profiles do, and with a bit of padding it reads as a deliberate banner. It's the low-effort answer and it's fine.
Option B: ship two GIFs and let GitHub pick. GitHub's Markdown renderer keeps the <picture> element, including the prefers-color-scheme media query. So you can export one header per theme:
…and wire them up like this:
<picture> <source media="(prefers-color-scheme: dark)" srcset="./assets/typing-dark.gif"> <source media="(prefers-color-scheme: light)" srcset="./assets/typing-light.gif"> <img src="./assets/typing-light.gif" alt="Hi, I'm Sam. I build open-source tools."> </picture> Each visitor downloads only the one that matches their theme. No fringe, no rectangle, and the text colors can differ too. Notice the light version above doesn't just swap the background. The white text became near-black and the blue got darker, because #58a6ff on white is hard to read.
Three details that separate a nice header from an annoying one
Write the alt text as the sentence. A screen reader can't see your animation. If the alt says typing animation, that's what gets read out. If it says the actual sentence, the animation becomes decoration on top of real content, which is what it should be.
Hold the finished line for a beat. The most common mistake is erasing the instant the last letter lands. People read slower than GIFs type. A hold of about a second and a half on the completed phrase is the difference between "oh, nice" and "wait, what did it say?"
Keep the first phrase the important one. Plenty of people will glance for two seconds and scroll. Whatever is in phrase one is your actual headline. Phrases two and three are a bonus for people who linger.
Making one
Typing Text GIF is the tool I built for exactly this. You type the fixed part and the rotating phrases, pick a font, and it renders the GIF in your browser. Nothing gets uploaded. For a README:
- Font: a monospace like JetBrains Mono suits a developer profile, but anything works.
- Background: solid
#0d1117for dark, or transparent with the matte set to the page color. - Export, drop it in your repo (an
assets/folder keeps the root tidy), reference it with a relative path.
If you go transparent, the matte picker is the one setting to get right. It's the entire difference between the two halves of that zoomed comparison.
Your profile is username/username/README.md. Go make it say something.
What's in your README header right now: text, an image, or forty badges?





