Chart legend and key icon

01Preview

Pick a component, then change its props. The preview renders the real component and the code updates with it.

import { ChartLegend } from '@nuton/ui'

<ChartLegend color="blue">Lessons completed</ChartLegend>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. @remixicon/react supplies the icons you pass to KeyIcon (Remix Icon is Nuton's icon set, D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

The legend label uses the Label/X Small type tokens, which read --nu-font-body. Map it to Inter as described in the Button font setup. No provider or other setup is needed.

03Usage

import { ChartLegend, KeyIcon } from '@nuton/ui'
import { RiBookOpenLine } from '@remixicon/react'

export function ActivityLegend() {
  return (
    <ul className="legend">
      <li><ChartLegend color="blue">Lessons completed</ChartLegend></li>
      <li><ChartLegend color="orange">Quizzes taken</ChartLegend></li>
    </ul>
  )
}

export function LessonCount() {
  return <p><KeyIcon color="blue" icon={<RiBookOpenLine />} /> 12 lessons</p>
}

• Defaults: ChartLegend and ChartLegendDot are gray (the dot is md); KeyIcon is stroke, gray, 40.
• Give every series a ChartLegend with the series name. Use ChartLegendDot on its own only where text sits next to it, such as a tooltip row.
• Put two or more legends in a list (<ul> of <li>), so screen readers announce how many series there are.
• Pass a Remix icon through icon. Leave label off when text next to the key icon says the same thing.

04Variants and sizes

The family has three parts. ChartLegendDot is the coloured mark; ChartLegend is a small dot plus the series name; KeyIcon is an icon in a circle with its own palette and five sizes.

Chart legend colours

<ul>
  <li><ChartLegend color="gray">Gray</ChartLegend></li>
  <li><ChartLegend color="light-gray">Light gray</ChartLegend></li>
  <li><ChartLegend color="blue">Blue</ChartLegend></li>
  <li><ChartLegend color="orange">Orange</ChartLegend></li>
  <li><ChartLegend color="red">Red</ChartLegend></li>
  <li><ChartLegend color="green">Green</ChartLegend></li>
  <li><ChartLegend color="yellow">Yellow</ChartLegend></li>
  <li><ChartLegend color="purple">Purple</ChartLegend></li>
  <li><ChartLegend color="sky">Sky</ChartLegend></li>
  <li><ChartLegend color="pink">Pink</ChartLegend></li>
  <li><ChartLegend color="teal">Teal</ChartLegend></li>
  <li><ChartLegend color="teal" disabled>Disabled</ChartLegend></li>
</ul>

Legend dots: colour × size

All 11 colours at both sizes. The dot is 12px in both; size sets the frame around it.

<ChartLegendDot color="blue" size="md" />
<ChartLegendDot color="blue" size="sm" />

Measured in the browser (legend 16 tall). Figma binds the legend text to a remote Label/X Small style (Satoshi); code uses the local Nuton Label/X Small (C22).

Key icon appearance

<KeyIcon appearance="stroke" color="blue" icon={<RiBookOpenLine />} />
<KeyIcon appearance="lighter" color="blue" icon={<RiBookOpenLine />} />

Stroke: Bg/White, 1px inside Stroke/Soft-200, regular-shadow/x-small. Lighter: State/<colour>/Lighter fill, no border. The icon is State/<colour>/Base (gray: Icon/Sub-600).

Key icon sizes

<KeyIcon size={64} icon={<RiUser6Line />} />
<KeyIcon size={56} icon={<RiUser6Line />} />
<KeyIcon size={48} icon={<RiUser6Line />} />
<KeyIcon size={40} icon={<RiUser6Line />} />
<KeyIcon size={32} icon={<RiUser6Line />} />

Verified in the browser against Figma geometry.

Key icons: appearance × colour × size

Every Figma variant: 2 appearances × 9 colours × 5 sizes.

Colour tokens

05States

None of these components is interactive, so there are no hover, focus or pressed states. The legend has a disabled state; the key icon is either decorative or labelled.

State tokens

These custom properties are set by the component from its props, on the element itself. Use the props; the properties are listed for reference.

06Composition examples

Series toggle

Click a legend to hide or show its series. Each legend sits inside a real Button with aria-pressed; a hidden series shows the disabled legend. The chart has a text summary for screen readers.

<figure>
  <figcaption>Biology 101 · activity this week</figcaption>
  <Chart role="img" aria-label={summary} series={visibleSeries} />
  <ul aria-label="Show or hide series">
    {series.map((s) => (
      <li key={s.id}>
        <Button size="sm" appearance="ghost" aria-pressed={shown[s.id]} onClick={() => toggle(s.id)}>
          <ChartLegend color={s.color} disabled={!shown[s.id]}>{s.name}</ChartLegend>
        </Button>
      </li>
    ))}
  </ul>
  <p role="status">{message}</p>
</figure>

The disabled legend text is 1.52:1 (C23). The button's pressed state, not the grey text, tells assistive tech the series is hidden.

Chart legend

<figure>
  <figcaption>Weekly activity</figcaption>
  <ul>
    <li><ChartLegend color="blue">Lessons completed</ChartLegend></li>
    <li><ChartLegend color="orange">Quizzes taken</ChartLegend></li>
    <li><ChartLegend color="gray" disabled>Hidden: revision time</ChartLegend></li>
  </ul>
</figure>

Key icons in a space summary

Next to text, the key icon is decorative: leave label off.

<ul aria-label="Space summary">
  <li><KeyIcon color="blue" icon={<RiBookOpenLine />} /> 12 lessons</li>
  <li><KeyIcon color="purple" icon={<RiGraduationCapLine />} /> 34 students</li>
  <li><KeyIcon color="gray" appearance="lighter" icon={<RiTimeLine />} /> 6 h of content</li>
</ul>

Labelled key icons

When the icon is the only cue, such as a lesson type in a list, pass label so it's announced.

<ul className="lessons">
  <li><KeyIcon size={32} color="blue" label="Reading" icon={<RiBookOpenLine />} /> Photosynthesis</li>
  <li><KeyIcon size={32} color="red" label="Video" icon={<RiVideoLine />} /> Cell structure</li>
  <li><KeyIcon size={32} color="purple" label="Quiz" icon={<RiQuestionAnswerLine />} /> Plant cells check-in</li>
</ul>

Use only colours at 3:1 or higher for meaningful key icons: not green, yellow or teal lighter (C23).

07API reference

ChartLegend props

ChartLegendDot props

KeyIcon props

Styling hooks

ChartLegendDot renders .nu-chart-dot with data-color, data-size and data-disabled. ChartLegend renders .nu-chart-legend (with data-disabled) around a small dot and .nu-chart-legend__label. KeyIcon renders .nu-key-icon with data-appearance, data-color and data-size. Use props rather than styling these attributes.

Accessibility

You must: give every series a text legend; put several legends in a list; pair low-contrast series with patterns or direct labels in the chart itself; pass label only when the key icon alone carries meaning.

Figma mapping

Figma's description says “9 distinct colour options”; the dot and legend components have 11 (FC-13). Payment Icons (57:15965) sit on the same Figma page. They aren't part of this family and are already on the D9 clean-up list.

08Guidelines and related components

Do and don't

Common mistakes

• Putting an onClick on a legend. It isn't focusable or announced as a control; wrap it in a Button.
• Relying on the greyed disabled legend to say a series is hidden. Pair it with aria-pressed or text.
• Matching chart colours to dots by eye. Use the same State tokens the dot uses (see Colour tokens).
• Setting the dot size on a legend. ChartLegend always uses the small dot.

Related components

• ColourThe State tokens behind chart and key icon colours.
• ButtonWrap legends in a button to toggle series.
• AvatarImages and initials for people and spaces.
• Button groupSwitch between chart views or time ranges.