grafana/grafana

@grafana/ui

Grafana's React design system. Source under packages/grafana-ui/. Storybook documents every component visually.

Scope

@grafana/ui provides:

Form primitives (Button, Field, Input, Select, Checkbox, Switch, RadioButtonGroup, …).
Layout primitives (Stack, Box, Grid, Splitter).
Overlays and feedback (Modal, Drawer, Tooltip, Toast, Alert, Spinner).
Data presentation (Table, IconButton, Tag, Badge, Chip).
Visualization primitives (PanelChrome, LegendList, VizLayout, VizTooltip, axis helpers).
Hooks (useStyles2, useTheme2, useToggle, useClickAway, useFocusRing, …).

Theming

Every component is themed via Emotion (@emotion/react + @emotion/css). The convention is:

import { GrafanaTheme2 } from '@grafana/data';
import { useStyles2 } from '@grafana/ui';

const Comp = () => {
  const styles = useStyles2(getStyles);
  return <div className={styles.container}>Hello</div>;
};

const getStyles = (theme: GrafanaTheme2) => ({
  container: css({
    background: theme.colors.background.primary,
    color: theme.colors.text.primary,
    padding: theme.spacing(2),
  }),
});

Components use only theme tokens; raw color literals are flagged by the @grafana/theme-token-usage ESLint rule.

Run yarn storybook to launch the design-system playground. Every component has a .story.tsx file alongside it. Stories are also used as visual regression fixtures by yarn e2e:playwright:storybook.

VizLayout / PanelChrome

PanelChrome is the wrapper that gives every panel its title bar, hover actions, error overlay, and footer. Panel plugins compose with PanelChrome and VizLayout to get consistent panel rendering.

Form integration

Form components integrate with react-hook-form via the Field and Form wrappers. Async validation and field arrays follow the upstream API.

Accessibility

All interactive components meet WCAG 2.1 AA contrast at the default themes.
Components use ARIA roles and labels; the Stack and Grid primitives forward role props.
The @grafana/e2e-selectors package defines stable selectors for tests; UI components consume them so tests remain stable across visual refactors.

Packaging

The package ships ESM and CJS bundles plus type declarations. Tree-shaking is preserved — importing from @grafana/ui without sub-paths is the canonical way (Webpack and Rollup will tree-shake unused exports).

Key directories

Directory	Purpose
`packages/grafana-ui/src/components/`	Component library
`packages/grafana-ui/src/themes/`	Theme glue (re-exports + helpers)
`packages/grafana-ui/src/hooks/`	Reusable hooks
`packages/grafana-ui/src/utils/`	Helpers (color manipulation, focus, scroll lock)