Badge

In review

Live · web

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

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

count

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

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

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

Code

// 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" />

// 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)

// 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 (a ratified 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`		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`		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

Prop	Type	Default	Description
`count`	`number`		Numeric count. Clamped to `max`, rendering e.g. `99+` past it.
`label`	`string`		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`		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`		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.

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	Description
`NockerlBadge(count, tone, contentDescription)` *	`Int, NockerlBadgeTone, String?`	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`	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`	The bare 8dp disc for unseen-but-uncounted activity. Accessible name is required, non-empty; `tone` defaults to `AGENT`.
`NockerlBadgeTone`	`enum`	Semantic hue ladder: `ACCENT · SUCCESS · WARNING · DANGER · INFO · AGENT`.

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	Description
`NockerlBadge(count:tone:label:)` *	`Int, NockerlBadgeTone, String?`	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`	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`	The bare 8pt disc. Accessible `label` is required, non-empty; `tone` defaults to `.agent`.
`NockerlBadgeTone`	`enum`	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): 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.