donut-direct-labels

name	donut-direct-labels
description	Feature guidance for Donut chart direct labels (segment name + value text placed directly around the ring, no connector line). Use when generating a Donut with direct labels enabled. Token values referenced here are defined in donut-chart-tokens.

Direct Labels

Tokens referenced below are defined in donut-chart-tokens — this file covers feature behavior only, not token values.

• Segment name: text-secondary (#505050)
• Value: text-secondary (#505050) at rest → segment's own categorical color on hover (see donut-chart-tokens behavior tokens)
• Alignment: within a single label, the segment name and value lines are always left-aligned to each other — both share the same edge, so a shorter value line never centers under a longer name line. This is about the two lines' relationship to each other, not the text-anchor side relative to the ring. The anchor side must mirror by hemisphere: labels on the right half of the donut anchor left and grow rightward (away from the ring); labels on the left half anchor right and grow leftward (away from the ring). Anchoring every label left regardless of hemisphere will draw left-hemisphere labels back across the ring, violating the no-overlap rule below.
  • Implementation direction: don't satisfy the hemisphere mirror by flipping the text-alignment property on both lines together. That makes the two lines share their far edge from the anchor, not their near edge — right-aligned to each other on the left hemisphere instead of left-aligned, which breaks the rule above. Instead: keep both lines' alignment set to start-from-the-near-edge on both hemispheres, and move the anchor point itself per hemisphere — on the right half, anchor at the ring-gap point and let both lines grow away from the ring from there; on the left half, offset the anchor back (further from the ring) by the width of the wider of the two lines, so that line's far edge still lands at the ring-gap point while both lines still start from the same near edge. Getting the offset requires the wider line's real rendered width — use real text measurement where available; if none is available at layout time, approximate width as characterCount × fontSize × k (k ≈ 0.52 for regular weight, ≈ 0.6 for bold) and flag it as an approximation, not a sourced token — it won't be pixel-exact for unusually narrow/wide-character strings.
• Gap between name and value: 0px (chart.donut.spacing.direct-label-name-value-gap) — tight, not overlapping
• Gap from the ring: 20px (chart.donut.spacing.label-ring-gap) — the label must never overlap the ring. If it would, wrap the label onto 2 lines rather than letting it overlap
  • Implementation direction: the 20px must be measured against the rendered text's actual bounding box, not just an angle/anchor coordinate. Placing an anchor point 20px outside the ring and drawing text from it is not sufficient — if the text is anchored at its vertical/horizontal center (or any point other than its ring-facing edge), part of its own rendered height/width extends back toward the ring, past the anchor, and can land closer than 20px (or overlap outright) even though the anchor itself satisfies the gap. Get the real rendered dimensions before finalizing the position — use real text measurement where available, and only fall back to the characterCount × fontSize × k approximation (see Alignment above) when no measurement primitive exists at layout time. Check the rendered bounding box's nearest edge against the ring, not the anchor coordinate — an anchor-only check without accounting for the text's own dimensions is a real, observed cause of labels landing too close to the ring
• Multiple labels colliding within the same hemisphere: see donut-label-collision for the algorithm (including the ring re-anchor step required after adjustment). Block height for its minGap is the rendered two-line label block (name + value line heights, no overlap).
• Sizes/weights: see donut-chart-tokens typography tokens
• No connector line — direct labels have no line at all, only text
• Used on Variant=4. Donut with direct labels in the Donut chart component set