Design & badges

How DEBT looks in the wild.

Visual identity, badge designs, color palette, embed snippets, and rendering rules. Everything you need to display DEBT scores consistently on your own site.

Score severity ramp

Per-axis scores 1–9 map to colors on a five-stop ramp. The ramp expresses severity at a glance — green for benign, deep red for catastrophic — without requiring the reader to remember what each number means.

benign

#16a34a

2–3

mild

#ca8a04

4–5

notable

#ea580c

6–7

serious

#dc2626

8–9

catastrophic

#991b1b

N/A

#71717a

Use the same ramp regardless of which axis is being shown. The semantic meaning ("how much pain on this dimension") is the same across all four; using a uniform severity ramp keeps the visual language consistent.

Score 0 is not on the severity ramp — it's a meta-state meaning "the axis doesn't apply to this concept." It uses zinc grey (the colour of "out of scope") rather than a green that would imply "very low severity." See the N/A band on the spec for when to use it; the reasoning page explains why it exists as a separate category.

Per-axis identity colors

Each axis carries its own identity color — distinct hue per kind of debt. These appear on axis labels, axis-card borders, and anywhere we name an axis. Picked to not collide with the severity ramp (no greens / oranges / reds) so a card can wear an identity color AND a score color without confusion.

Detect (operational)

#2563eb

Effort (remediation)

#db2777

Burden (structural)

#7c3aed

Trap (cognitive)

#0891b2

Brand accent

For the standard's identity (the word DEBT, the format string, page chrome) the canonical color is ledger amber — chosen because debt evokes a balance sheet, and amber distinguishes the DEBT pillar from glossary's blue and codex's grey at codeclaritylab.com.

accent

ledger amber

#b45309

accent2

deep amber

#92400e

Compact badge

The default rendering. Compact, fits inline next to a concept name or in a table cell. Use this anywhere you'd inline a CVSS vector string. Score colors come from the severity ramp.

sql_injection

Mid-trap, mid-detect, low-effort, low-burden. The classic security-fix profile.

prototype_pollution

Catastrophic trap, mostly invisible to tools, localised fix, no lasting cost.

microservices_too_early

Not a trap; invisible operationally; expensive to undo; project-killing burden.

unused_variable

Trivial all the way down. The benign baseline.

Bar-style badge

For term pages or anywhere with vertical room. Axis labels carry their identity color (so you know which axis); bars carry the severity color (so you know how bad). Two color systems on one badge.

sql_injection

prototype_pollution

microservices_too_early

unused_variable

Badge generator

Set four scores, get a badge. The URL on the right is the canonical badge URL — copy it into your README, term page, or anywhere else that supports an <img> tag.

DEBT itself doesn't score concepts — you do, with whatever LLM you use, against the rubric. This generator only renders. If you don't have scores yet, paste the scoring prompt into Claude / ChatGPT / Gemini with your concept's definition; they return four numbers; you put them here.

d — Detectability e — Effort

b — Burden t — Trap

Style

Badge URL Markdown snippet

Rendering rules

Always show all four axes. Never display only one or two scores; the orthogonality of the system depends on readers seeing the full profile. debt(d?/e?/b?/t9) is misleading.

Never collapse to a single number. No sums, no averages, no "DEBT score: 21." If you need a sortable scalar, use the highest single-axis value (max(d,e,b,t)) and clearly label it as such.

Use the canonical letter order. d/e/b/t — not alphabetical, not "by severity." The order is fixed because the four letters spell the standard's name (debt(d_/e_/b_/t_)), making the format self-documenting.

Color is decorative, not authoritative. The numbers are the score. A color-blind user reading the raw text debt(d7/e4/b2/t9) must get the same information as a sighted user reading the badge.

Link the badge to the spec. Wrap badges in a link to https://codeclaritylab.com/debt so anyone seeing a score for the first time can find the rubric. Same convention as MIT-license badges linking to the license text.

Embed snippets

HTML snippet for inline display. Drop into your term page, README, or any spot that supports raw HTML:

The badge endpoint at /debt/badge is stateless: same URL params always produce the same SVG, cached for one day. Add &style=bar for the bar-style badge. Use the generator above if you want to preview before embedding.

Markdown snippet (for READMEs and similar):

[![debt(d4/e3/b2/t5)](https://codeclaritylab.com/debt/badge?d=4&e=3&b=2&t=5)](https://codeclaritylab.com/debt/spec#d4-e3-b2-t5)

Plain text reference (when graphics aren't available):

debt(d4/e3/b2/t5) — see https://codeclaritylab.com/debt/spec#d4-e3-b2-t5

The link target /debt/spec#d4-e3-b2-t5 deep-links to the anchor grid with the four cells corresponding to the badge's scores highlighted. The hash parser is permissive — #d4e3b2t5, #d4/e3/b2/t5, #debt-d4-e3-b2-t5, and even query-string-style #d=4&e=3&b=2&t=5 all work. If you'd rather link to your own page (e.g. the term that's being scored), replace the href with your URL.

Typography

Use a monospaced font for any DEBT score, badge, or vector string. Monospace makes the per-axis values align visually and signals "this is structured data, not prose."

Recommended monospace stack (in order of preference): JetBrains Mono, IBM Plex Mono, ui-monospace, Cascadia Mono, Menlo, Consolas, monospace. Any of these renders the format correctly.

For DEBT-pillar headers and editorial content, the typography matches CodeClarityLab's defaults. You're not required to match this when you adopt DEBT — only the score format and color ramp are normative.

What's normative vs cosmetic

When implementing DEBT on your own site, these are required for spec conformance:

The format debt(d<n>/e<n>/b<n>/t<n>)
The four axis letters: d, e, b, t — lowercase, in this order
The score range [0, 9] with 0 reserved for "not applicable"
Showing all four axes whenever a score is rendered
When embedding the badge in HTML or Markdown, wrap it in a link to https://codeclaritylab.com/debt (raw inline SVG can't carry a link, but any <img> embed should)
Storing scores with required rationale per axis (see JSON schema)

These are recommended but not required:

The five-stop severity color ramp shown above
The four per-axis identity colors
The ledger amber pillar accent
Monospace typography for scores
The compact and bar-style badge designs

See also: the formal spec · design reasoning