Visual refresh: Ensure your plugin is compatible with the new visual refresh

We have finalized the initial phase of development work as part of the UI Refresh initiative. Your plugin or UI surface may now have unwanted visual changes; here's what's coming and what we need you to do.

How the rollout works in this phase

Everything ships behind the new grafana.visualDesignRefresh feature flag.

[!NOTE] With the FF on, the current light/dark themes will be replaced with the refreshed ones.

This uses a combination of a new theme definition and the feature flag. Where possible, we add changes to the new theme definitions (visual_refresh_light/visual_refresh_dark), dogfood internally until we’re happy, then eventually merge the changes from the new theme into the main theme at a set cadence. This phase is the smaller, polished changes. No workflow or layout changes, no sizing changes.

What we need from you

We will be enabling the new experimental theme in Ops sometime on July 28th, 2026. If you need to enable it locally, use the feature flag grafana.visualDesignRefresh.

Make a visual inspection of the interfaces of the plugin. If they seem like they do not match the rest of the chrome and other components, review that you’re not using hardcoded values. Instead, use the new color, border, and shadow tokens.

For some changes, you should gate them behind the grafana.visualDesignRefresh OpenFeature feature flag (using the useFlagGrafanaVisualDesignRefresh hook if in grafana/grafana).

Particular things to look out for:

• Mismatched backgrounds
  • There is now a single page style with a new theme.colors.background.page token
  • This may mean components in your plugin (e.g. sticky headers) are using a background token that no longer matches
  • Your minVersion will need to update to be at least >=13.1.0
  • You should make these changes behind the feature flag
• Incorrect or missing border radius
  • The new UI is rounder, which makes missing border radius (theme.shape.radius) stand out more. If you see a component anywhere with square edges, it’s probably wrong.
  • sm for small/inner widgets such as checkboxes or badges
  • md for most standard form widgets
  • lg for containers (cards, panels, menus, modals, etc)
  • Your minVersion will need to update to be at least >=12.3.0
  • You can make these changes in your plugin without the feature flag
• Incorrect use of primary color
  • As primary is now white (in dark mode), it stands out quite a lot
  • For most cases, this should be reserved for the primary action, and there should only be 1 of these on a given page
  • We've therefore split out some use cases of the primary token into a new accent token
  • This is orange in the visual refresh, and is used for things like checkbox/switch styles and focus styles.
  • Your minVersion will need to update to be at least >=13.1.0
  • You can make these changes in your plugin without the feature flag

If you notice core UI components that have any of these issues, please flag that to us in #wg-ui-refresh

Please test and address any visual inconsistencies you find for this phase by Aug 14, 2026. Not a hard gate, but it's how we catch breakage before users do.

Please reach out if you want help. This project's working group in Slack is #wg-ui-refresh and @ashharrison90 would love to help and pair with anyone. It should not take more than 60 mins (probably a lot less depending on the size of your plugin), and we can have your plugin looking