Badge

In review

Live · web

Live: drive the inbox count (0 → dot · 1-99 → number · 100+ → 99+)

3−1+1+25Mark read

Bell shows 3 unread. The badge pops in on change, frozen under reduced-motion.

---

Anchored: pinned to a host corner (count + dot), ringed to punch out

4count

99+overflow

PMdot · avatar

dot · icon

Standalone: inline, named for assistive tech

11299999+

Solid label: filled hue + contrast label (accent · info · success · warning · danger · neutral)

accentinfosuccesswarningdangerneutral

Soft label: low-alpha tint + hue label (the inline pill idiom)

accentinfosuccesswarningdangerneutral

Sizes: sm · md (count, dot, and label)

8beta

sm

8beta

md

Language: the hue-free code tag (a language is metadata, never a status color · always lowercase mono)

typescriptkotlinswiftjsonshell

Language · app-configured color (optional): the app supplies its own mapping via the color prop

typescriptkotlinswiftjsonshell

Code

TypeScript

// Web: React, consuming @dizyx/nockerl-tokens. (Web is the laggard platform; this is the
// canonical API the published @dizyx/nockerl-react package is intended to expose. It unifies
// the shipped idioms: a count/dot overlay (Compose BadgedBox) + a tonal status pill.)
import { NockerlBadge } from '@dizyx/nockerl-react';

export function InboxBell({ unread }: { unread: number }) {
  return (
    <button aria-label={unread > 0 ? `Inbox, ${unread} unread` : 'Inbox, unseen activity'}>
      <BellIcon />
      {/* anchored: a count → "99+" overflow, falling back to a bare dot at 0 */}
      {unread > 0 ? <NockerlBadge count={unread} tone="danger" anchored /> : <NockerlBadge dot tone="danger" anchored />}
    </button>
  );
}

// standalone status pills (passive, so name them for assistive tech)
<NockerlBadge label="research" tone="warning" variant="soft" />
<NockerlBadge count={12} tone="accent" ariaLabel="12 items" />

Kotlin

// Android: the published Compose package com.dizyx.nockerl.design.components (GitHub Packages Maven).
// A first-class NockerlBadge wrapper: count pill, bare dot (NockerlBadgeDot), and tonal label pill.
// Anchor to a host with a plain Box overlay at the call site (the library ships the badge, not a BadgedBox).
import com.dizyx.nockerl.design.components.NockerlBadge
import com.dizyx.nockerl.design.components.NockerlBadgeDot
import com.dizyx.nockerl.design.components.NockerlBadgeTone
import com.dizyx.nockerl.design.components.NockerlBadgeVariant

Box(contentAlignment = Alignment.TopEnd) {
    Icon(Icons.Filled.Notifications, contentDescription = "Inbox")
    when {
        // count pill: "99+" past 99, contrast-picked label. Defaults to the agent (orange) tone.
        unreadCount > 0 -> NockerlBadge(count = unreadCount, contentDescription = "$unreadCount unread")
        // bare dot for unseen-but-uncounted activity (accessible name REQUIRED)
        hasUnseen -> NockerlBadgeDot(contentDescription = "Unseen activity")
    }
}

// inline tonal status pill, a label pill naming a state (SOFT = hue @ 15% wash + full-hue label)
NockerlBadge(text = "Research", tone = NockerlBadgeTone.WARNING, variant = NockerlBadgeVariant.SOFT)

Swift

// SwiftUI: the published NockerlDesign SwiftPM package. A first-class NockerlBadge with the
// full set: count pill, bare dot (the .dot factory), and tonal label pill (soft / solid).
// Anchor to a host with .overlay(alignment: .topTrailing).
import NockerlDesign

Image(systemName: "bell")
    .overlay(alignment: .topTrailing) {
        // count pill: "99+" past 99; bare dot at zero. Defaults to the agent (orange) tone.
        if unread > 0 {
            NockerlBadge(count: unread, label: "\(unread) unread")
        } else {
            NockerlBadge.dot(label: "Unseen activity")
        }
    }

// standalone tonal status pills (passive, named for assistive tech)
NockerlBadge("Research", tone: .warning, variant: .soft)
NockerlBadge("CI", tone: .success, variant: .solid)

Language tag

A code language is metadata, never status, so its tag carries no hue. NockerlLanguageBadge is the first-class, hue-free tag: a quiet lowercase monospace pill (neutral soft wash + muted ink) shared by the CodeBlock header, the DiffViewer header, and the Markdown code fence, so the tag reads identically everywhere. The label runs through the shared nockerlLanguageLabel contract (trim + lowercase, blank → nothing). It is byte-identical to the native rails, so 'TypeScript' renders typescript on every surface.

App-configurable color (ratified r5 relaxation)

The framework default stays hue-free and ships no per-language color map. Apps may differentiate languages via the optional color prop (their own mapping: TS ≠ Kotlin ≠ Swift), and for this one case a status hue is permitted: a language color reads as identity metadata, not state. Unset, the tag is the quiet neutral canon matching Android + Voice.

Prop	Type	Default	Description
language	string | null	n/a	The language name in any casing (e.g. 'TypeScript'). Normalized to a lowercase tag by the shared nockerlLanguageLabel contract; a blank / absent value renders nothing.
color	string	n/a	OPTIONAL app-side tag color: tints the soft wash + the lettering via NockerlBadge's arbitrary-color path. The APP owns the language→color mapping; the framework never hardcodes one. Unset = the neutral default.
size	NockerlBadgeSize	'sm'	Badge scale. Defaults to sm (the code-header pill size).

Also accepts the native <span> attributes (e.g. onClick, disabled, id, aria-*, data-*), forwarded straight through, plus a forwarded ref.

Parameters

TypeScript

Prop	Type	Default	Description
count	number	n/a	Numeric count. Clamped to max, rendering e.g. 99+ past it.
label	string	n/a	Free-text label (use instead of count for a status badge).
dot	boolean	false	Render a bare dot: no number, no text (the "unseen" indicator).
tone	NockerlBadgeTone	'accent'	Status / accent hue. Cyan is accent; the rest are warm status + neutral.
variant	NockerlBadgeVariant	'solid'	solid = filled hue + contrast label; soft = low-alpha tint + hue label.
color	string	n/a	Override the tone hue with an ARBITRARY color (e.g. a per-language code color the 6 fixed tones can't express). Drives the soft tint/label/border (or the solid fill). Falls back to tone when unset.
mono	boolean	false	Render the label in the monospace family (for code / file-type / version pills).
size	NockerlBadgeSize	'md'	NockerlBadge scale.
max	number	99	Overflow ceiling for count (e.g. 99 → 99+).
anchored	boolean	false	Pin to the parent host's top-right corner (overlapping, ringed). The parent must be the positioned host (the demo's Anchored wrapper provides it). Else the badge renders inline.
ariaLabel	string	n/a	Accessible name announced for the badge when it stands alone (e.g. "3 unread"). When the badge is anchored, name the HOST instead and leave this unset. The count is decorative there.

Also accepts the native <span> attributes (e.g. onClick, disabled, id, aria-*, data-*), forwarded straight through, plus a forwarded ref.

Kotlin

The published NockerlBadge ships as a first-class wrapper with three forms; tones map onto semantic palette slots via NockerlBadgeTone (never a raw hue).

Parameter	Type	Default	Description
NockerlBadge(count, tone, contentDescription) *	Int, NockerlBadgeTone, String?	n/a	The count pill: solid tone fill, contrast-picked label, capped "99+". tone defaults to AGENT; contentDescription defaults to the count text.
NockerlBadge(text, tone, variant) *	String, NockerlBadgeTone, NockerlBadgeVariant	n/a	The tonal label pill. variant: SOFT (the default, a hue @ 0.15 wash + full-hue label) or SOLID (tone fill + contrast ink).
NockerlBadgeDot(contentDescription, tone) *	String, NockerlBadgeTone	n/a	The bare 8dp disc for unseen-but-uncounted activity. Accessible name is required, non-empty; tone defaults to AGENT.
NockerlBadgeTone	enum	n/a	Semantic hue ladder: ACCENT · SUCCESS · WARNING · DANGER · INFO · AGENT.

Swift

The published NockerlBadge ships the full set on the same NockerlBadgeTone ladder as Compose: count pill, bare dot, and tonal label pill (soft / solid). It is a passive View; anchor it with .overlay(alignment: .topTrailing).

Parameter	Type	Default	Description
NockerlBadge(count:tone:label:) *	Int, NockerlBadgeTone, String?	n/a	The count pill: solid tone fill, contrast-picked label, capped "99+". tone defaults to .agent; label defaults to the count text.
NockerlBadge(_:tone:variant:) *	String, NockerlBadgeTone, NockerlBadgeVariant	n/a	The tonal label pill. variant: .soft (the default, a hue @ 0.15 wash + full-hue label), .solid (tone fill + contrast ink), or .outline (a 1pt tone stroke on a transparent fill + full-hue label, the Button-outline grammar; the lightest form for dense rows. Swift-first: react/compose parity tracked).
NockerlBadge.dot(tone:label:) *	NockerlBadgeTone, String	n/a	The bare 8pt disc. Accessible label is required, non-empty; tone defaults to .agent.
NockerlBadgeTone	enum	n/a	Semantic hue ladder: .accent · .success · .warning · .danger · .info · .agent.

Cross-platform drift (one open item)

The published Compose (com.dizyx.nockerl.design.components) and Swift (NockerlDesign) packages now both ship a first-class NockerlBadge with the full set: count pill, bare dot, and tonal label pill (soft / solid) on the same NockerlBadgeTone ladder. The earlier coverage gap and “no shared wrapper” drift are resolved. What remains:

• Default count hue (resolved in [adjudication 2026-07-02 · B5]): the unread-count badge hue is danger-red; the orange agent-family token was a categorical misuse. The web demo already defaults the inbox to danger-red; both native packages (today defaulting the count / dot to the .agent / AGENT orange) conform.