As promised to @ngerakines.me, here’s a more formal proposal for “badge appearance”. This is not the complete proposal yet: I need to write the Lexicon definition and put down some thoughts about how to specify colors and images.
I’ll get to it by end of week (promise), but in the meantime I’m putting something down for initial comments.
Proposal: Appearance Lexicon for Badges
The Why
community.lexicon.badge.definition currently flattens the “name” field for both badge identification and badge display name- This makes it impossible to edit the display name of a badge without mutating the definition itself, causing all records to point to an older badge definition that no longer exists on the PDS and whose content cannot be verified.
- While badges definitions shouldn’t change, there are many valid reasons for updating their appearance, including:
- Typos
- New Discriminant (e.g.
Conference Attendee => 2026 Conference Attendee, should it gain a surprise second edition)
- Getting money to commission someone a better badge
- A kind soul offers to improve your alt text
- “I thought of a funnier display name/description and now I’m mad”
- This gets further compounded if we add necessary fields like:
Solution: Appearance lexicon for badges
community.lexicon.badge.appearance defines the user-facing presentation for a badge.
A badge definition represents the stable badge being awarded: it has a unique name and unchangeable description. Recipients can trust that the meaning of the badge they hold will not change under them.
Badge appearance represents how that badge should be displayed: visuals, “copy”, and link to learn more.
This separates two concerns that are currently conflated: stable identity and mutable presentation, what the badge is vs what the badge looks like. It allows for progressive enhancement and extensibility, which is particularly valuable for communities like fandom that use badges as self expression and not simple credentials. While this is a badge-specific proposal, this conflation has been a recurring issue trying to map some open standards onto fandom’s “way of (online) life”. It’d be good to name this as a pattern, and put out an example of how to do it differently.
Proposal
1. Update community.lexicon.badge.definition
A badge definition is stable for the lifetime of the badge. This already exists today.
Proposed Change
- Add an (optional) reference to a
community.lexicon.badge.appearance record describing how this badge looks
- If a
cid is present, the badge is only valid for that specific version of the appearance record (useful for when you want to avoid any tampering)
- If no
appearance is present, name and description can be a display fallback
Example:
{
"$type": "community.lexicon.badge.definition",
"name": "atconf2026-connections-rank-a",
"createdAt": "2026-03-30T09:19:25.897Z",
"description": "Awarded for making at least 100 connections at ATmosphereConf2026.",
"appearance": {
"uri": "at://did:plc:example/community.lexicon.badge.appearance/example",
"cid": "bafyreicwoikmvs5wsyxy3mbaooxhlp3vulry2aruaxgzsgwbdgkrtxp7fe"
}
}
Side proposal: doing the renaming of name → id in the same change. The current name does double duty as stable identifier and display string, and id for the identifier would make its purpose clear.
2. Create community.lexicon.badge.appearance
A badge appearance describes how a badge should be displayed.
Challenge: we want to support both types of badges:
-
Icon + colors badges, easy to create for people who just want to put a badge out without thinking too hard about it (I’m told they exist)
-
Image Badges, for the rest of us who miss the geocities era. Let’s take one of ours, for reference:
Fields:
title: display title for the badge.displayDescription (optional): display description for the badge. Can be longer than original badge description. Falls back to community.lexicon.badge.definition#description if not present.image (optional): visual representation of the badge. Like Bluesky’s, it has alt, image, and aspectRatio (but flattened).icon (optional): an emoji or character or small image that represents the badge (e.g. 
, ⌘, or an actual image). If not defined, falls back to first letter of the title. Personally, I’d allow 2-3 graphemes with the understanding that it may be cut to 1.accentColor (optional): primary color of the badge (leaves door open for distinguishing background + foreground combinations in the future).url (optional): where to go to learn more about the badge (can be an actual URL or an ATUri).
Important: image and icon/accentColor are not mutually exclusive. icon can be used to represent the image in space-constrained environments. But when possible implementers should prefer image and consider icon/accentColor a fallback
Examples
- Conference badge:
{
"$type": "community.lexicon.badge.appearance",
"title": "Grand Goose Ambassador",
"icon": "🪿",
"accentColor": "#fbbf24", // yellow,
"url": "https://atmosphereconf.org/"
}
Description is absent, so it falls back to the one in the original badge.
{
"$type": "community.lexicon.badge.appearance",
"title": "Code Gitter",
"displayDescription": "Some people would do anything for catboys, even learn version control.",
"url": "https://www.fujoweb.dev/",
"icon": "😼💻",
"accentColor": "#e0b8a3", // Git's signature peach color
"image": {
"blob": {
"$type": "blob",
"ref": {
"$link": "bafkreiexample"
},
"mimeType": "image/png",
"size": 12345
},
"alt": "FujoGuide's Git but he's nyancat, creating a rainbow as he dashes through the sky. Let's git coding is written to his right.",
"aspectRatio": {"width": 88, "height": 31}
}
}
[edit] To illustrate the difference between definition and appearance, here’s how a potential definition would look like. It has a more factual name and description, but where’s the fun in that?
{
"$type": "community.lexicon.badge.definition",
"name": "FujoGuide Issue 1 Buyer",
"description": "Awarded to folks who bought FujoGuide Issue 1",
"appearance": {
"uri": "at://did:plc:example/community.lexicon.badge.appearance/example",
}
}
Things I’d like input on
It’s a few, so please do pick and choose if you have thoughts:
Original badge definitions:
id vs name: is this a crusade only I care about and should relent on?- Anyone in favor (or really against) having
id + name so a badge fallback could still display both a title and description?
Badge appereance:
- Do people prefer
tagline or displayDescription for the appearance copy field? tagline feels more true, but taglines are by design shorter and less descriptive. displayDescription is verbose, but it separates it from “description” in the badge.
- Any sanctioned way to leave space for “rich text descriptions” in the future? What about different formats for them? (yes, we could do the same thing as profile descriptions and render links + mentions, but that’s unstructured and doesn’t preserve DIDs for mentions).
- Should
image always win over icon, or is it more an “alternate renderings according to context”? Personal preference would be image always wins over emoji-based icon, but icon in image can be used as a contextual display (so it can be displayed as a shorthand in e.g. small contexts).
- Would people be open to
colors as an object rather than a single value (e.g. colors: {accent, background})? May I interest you in a richer definition of color than just hex?
- How are people supposed to extend this with their special display metadata (because they’ll want to)?
Let me know, and I’ll work on a more formal proposal in the next days!
