Components / Hive Credit Badge
Hive Credit Badge review
A compact pill showing the signed-in guardian's Hive Credits balance, sitting in the portal's top utility header and linking through to the Hive Credits page. A leading coin glyph, a fixed 'HIVE CREDITS' eyebrow in caps, and either the balance or a 'Start earning' prompt when the balance is zero. Always rendered on the brand gradient, in every colour mode.
Source: specs/hive-credit-badge/spec.json · specs/hive-credit-badge/notes.md
Anatomy
root- The pill: fully-rounded, filled with the brand gradient, compact padding. A link, not a static label.
icon- Leading coin glyph — `@beestera/icons` `hive-credit`, the `gold` state (46x50, so size it with `.icon-glyph`, not the square `.icon`). Decorative: the label and value carry the meaning.
eyebrow- The fixed 'HIVE CREDITS' label — uppercase, caps-tracked, the smallest step in the scale.
value- The balance, thousands-separated (e.g. '4,168'). Replaced by the 'Start earning' prompt in the zero state.
Token bindings
Each binding's value is resolved live from the built
@beestera/tokens output — tier-2 component tokens
(--hive-credit-badge-*) collapse through the foundation tier.
| Part | Property | Token | Resolved | Applies to |
|---|---|---|---|---|
root | background-image | --gradient-brand-500-700 | linear-gradient(45deg, var(--color-brand-500) 0%, var(--color-brand-700) 100%) | — |
root | border-radius | --badge-radius | 9999px --badge-radius → --radius-pill | — |
root | padding-inline | --spacing-lg | 0.75rem --spacing-lg → --spacing-scale-3 | — |
root | gap | --spacing-sm | 0.375rem --spacing-sm → --spacing-scale-1-5 | — |
root | outline-color | --focus-ring | #3d3d3d --focus-ring → --color-neutral-700 | — |
eyebrow | color | --text-primary-on-brand | #000000 --text-primary-on-brand → --color-base-black | — |
eyebrow | font-size | --font-size-text-xs | 0.75rem | — |
eyebrow | font-weight | --font-weight-semibold | 600 | — |
value | color | --text-primary-on-brand | #000000 --text-primary-on-brand → --color-base-black | — |
value | font-size | --font-size-text-sm | 0.875rem | — |
value | font-weight | --font-weight-bold | 700 | — |
Variants
-
statebalancezero - balance = the coin, the eyebrow and the thousands-separated figure. zero = the same pill with 'Start earning' in place of the figure, inviting the first earn rather than showing a bare 0. The Figma set also carries a Surface axis (Dark/Light/Brand); the client retired Dark and Light for SWARM (D24) so only the brand treatment ships.
State matrix
default- The resting pill in the utility header.
hover- The pill is a link; it must show a pointer and a visible hover affordance. The gradient does not change — brightness/opacity shift only, so the brand fill stays exact.
focus- Keyboard focus shows a visible ring via --focus-ring. Never suppress it: this is the only credits entry point in the header.
Accessibility
- Role
- link — it navigates to the Hive Credits page. MUST be a real anchor, not a styled div with a click handler.
- Contrast
- Label and value vs the gradient >= 4.5:1 (WCAG AA text) at BOTH ends of the sweep. Measured with --text-primary-on-brand (#000000): 14.97:1 on brand-500 and 10.17:1 on brand-700 — clears AAA (7:1) across the whole gradient, so the label cannot thin out at the amber end.
- Focus order
- Focusable, in the utility header's natural order. Part of the header landmark, not the page body.
- Target size
- At least 24x24 CSS px of hit area (WCAG 2.2 AA, 2.5.8). The pill's own height satisfies this; do not shrink it below that to fit a dense header.
- The accessible name must carry both the label and the amount — 'Hive Credits: 4,168', not just the number. The eyebrow alone reads as decoration to a screen reader.
- The coin glyph is decorative: aria-hidden, with the meaning left to the text.
- Never put light text on the brand gradient — white measures 1.40:1 on brand-500, far below AA.
- The badge is deliberately mode-invariant (D23): it keeps the brand gradient in light AND dark mode, so it must not inherit a dark-mode text colour from its surroundings.
Usage
Do
- Place it in the portal utility header, where the balance is persistently visible.
- Show the zero state rather than hiding the badge — 'Start earning' is the entry point to the earn flow.
- Format the value with thousands separators, matching the Hive Credits page.
Don't
- Don't reuse it as a generic status pill — the base Badge component covers that.
- Don't render it for a signed-out visitor; there is no balance to show.
- Don't render a stale or optimistic balance — show the loading state until the real figure arrives, per the round-trip's 'a widget is rendered only when backed by real data' rule.
- Don't recolour the fill per surface. The Dark and Light Figma variants are retired for SWARM.
Implementations
Not implemented in any product repo yet. This repo owns the spec; implementations land in each product repo on their own cadence.
Figma source: Badges/Hive credits