Design guidelines
How a Glance app should look. The Reference covers the mechanics — the API, the manifest, the hard rules that error. This section covers the part nothing errors on: layout, type, color, pixel art, and the screens people actually see from across a room.
The rules here are Glance's design requirements plus the conventions measured from the shipped catalog. Where a rule names an app, that app is the reference implementation.
Who these are for
If you're building with an AI assistant, these guidelines are already loaded — the
MCP server hands them over as
glance://reference/design, and the paste-in prompt
carries the short version. They are defaults the assistant follows and you may
override, case by case. Your design intent always wins.
What they exist to prevent is the opposite failure: a person leans on an AI, the AI leans on a template, and every app comes out looking the same.
If you're building by hand, read them the same way: the catalog's measured conventions, the traps that fail silently, and a checklist to walk before you submit.
Start with your design
Before any code is written, decide how the app should look. An AI assistant following these guidelines will ask you for this — have it ready. A drawing, a napkin sketch, a photo, or a zone-by-zone description in words all work. Collect at least:
| Decide | What it means |
|---|---|
| The layout | What sits where on the strip: left / center / right, top / bottom. |
| The hero | The one piece of content the app exists to show, and how big it should feel. |
| The pixel art | What image, if any, carries the app's identity — and what text it replaces. |
| Palette and mood | Brand colors, an accent, quiet or loud. |
| Target widths | 64x32 for the V2 and every end product, wider than 64 for SCROLL, or both. |
Then iterate on the look before wiring the data. Render a mockup of the layout with placeholder content, adjust until it's right, and only then build the data path behind it. The human designs; the AI (or the code) does the tedious part.
The goal is apps that look the best — and materially different from every other app. Two apps that both follow this section should still be visually distinct, because their designs came from two different people. If a proposed design would be indistinguishable from an existing GDN app, change it until it's its own.
And when the content resists a clean layout, decide the trade-off yourself. Some data genuinely doesn't fit — three labelled numbers plus identity art on 64x32 has no obviously right answer. A good assistant says so and hands you the trade-offs rather than shipping a forced compromise; a good developer does the same for themselves.
10x15_outline font gives the lockup its edge.The guidelines
1. Layout & the scroll sequence
Safe zones per panel width, the app-identity rule, bands, spacing, and what to do with more content than fits.
2. Type, color & stroke
Font roles, fit ladders, worst-case strings, contrast, text_stroke, the outline fonts, and what each color means.
3. Pixel art & the four screens
Graphics over text, no magic numbers, pixel-perfect art, and the live / error / empty / demo screens.
4. Data, inputs & naming
Refresh cadence, constraining API strings, picklists over free text, and naming the app.
5. Pre-flight checklist
Every rule as a box to tick before you submit.
Where these live
- On this site — you're reading them.
- In the toolkit — the same document ships as
gdn/data/design_guidelines.mdin the glance-dev-network repo. - In your AI — over MCP the server exposes
them as the
glance://reference/designresource and folds them into thebuild_an_appprompt; without MCP, the AI prompt ends with a condensed DESIGN block and a link back here. - In Studio — the sequence preview shows a scroll app between two neighbors, which is the only honest way to check the #1 scroll rule.