Explanation Cards
One developer concept per image: a title, one key sentence, the code that does it and one visual object.
The worked example
“One session holds everything for one user”, the first card in the Composio Concepts series, in both sizes. Every rule on this page came from review rounds on this card.
When to make one
What good cards do
The moves that make concept cards from other developer brands work, kept as patterns rather than copied.
- One idea per card, and the visual is the idea, not decoration around it.
- Before and after: the old way dashed and muted, the new way solid, an arrow between.
- One accent colour per card, used only on the thing that changed.
- Real input shown as it is (a prompt, a user ID), not a placeholder.
- Paths not taken faded back, so the eye lands on the chosen one.
- A numbered series, so each card can stay small and still tell the whole story.
Anatomy
Seven parts, top to bottom. Write the words first, then the visual.
Layout grids
Positions are px in the card frame. Two sizes from one JSON: landscape for X posts, portrait for the feed.
Landscape · 1200 × 675
Portrait · 1080 × 1350
Tokens
Picking the one visual
Draw the concept as one bounded object that visibly holds its parts. Match the visual to what the concept says.
Do and don't
Make one
The kit renders both sizes from one JSON with Python 3 and Pillow. Fonts, marks and app logos are in kit/assets. A WARN line means the copy is too long for its slot: shorten the words, never shrink the type.
Every visual in the table is built. kit/examples has a JSON for each one. For a new visual, add a layout function to kit/render.py that reuses its tokens, code panel, wire and footer, and keep every rule above.
Before you hand it over
- The title is a claim, 8 words or fewer, on one line (landscape) or two balanced lines (portrait).
- The key line is the full sentence and reads before the code.
- You can point at one object and say “this is the concept”.
- The highlighted code value matches the value on the object header.
- Exactly one dither, on the wire.
- No WARN lines from the renderer, nothing touching an edge, no dead space in a container.
- The code is copied from the docs and the footer URL opens the page that explains it.
- The badge count matches the series.
- Both sizes checked at full size and at phone size.

