1. Why did the design system change?
We refreshed the system to make it brighter, more modern, and more open. The updates align with our design vision, improve usability and accessibility, and create a consistent experience across all products within the Contentful platform.
2. What happened to the icons?
We switched from custom icons to the open-source Phosphor Icons library.
Benefits for you:
More consistent and modern icon style.
Smaller package size thanks to tree-shaking (only the icons you use are loaded).
Faster access to a broad, well-maintained icon library.
You are still able to use custom icons with the
<Icon />component just like before.
3. Did the font change?
Yes. We introduced Geist (by Vercel) as the new default font.
System fonts remain as a fallback, so nothing breaks.
Geist ensures a cleaner, modern, and consistent look across applications.
4. What changed in the layouts?
We removed the Workbench component and standardized layouts.
Key updates:
Cleaner headers with better hierarchy.
Default layout is now centered (grey background, white content container with subtle shadow).
Based on a flexible 3-column layout (header + optional sidebars).
This helps guide user focus and makes better use of screen space.
5. What’s new in the navigation bar?
Restyled from dark → light gray for a seamless look.
Simplified from two lines → one line.
Clear separation of areas:
Home link
Main navigation links
Secondary navigation (Search, Help, Settings, Account)
Environment switcher moved from left → right.
Introduced mobile navigation as a step toward responsive design.
As we believe it is a less-used component, we removed it from the
@contentful/f36-componentspackage to make the size of this package smaller.
6. How was accessibility improved?
We’ve made the system easier to use for everyone:
Higher color contrast for better readability.
Larger clickable areas for touch and mouse users.
Improved keyboard navigation.
Clearer visual hierarchy and language for orientation.
7. Do I need to make changes in my product?
Please read our detailed migration guidelines to find out which migration steps you have to take before upgrading to version 5
If your codebase uses the
<Workbench />, <Layout />or<Header /> components,make sure to check your page setup to ensure it aligns with the new structure.
8. Will this affect performance?
Yes, positively.
Icons: smaller package sizes due to tree-shaking.
Layouts & typography: more consistent rendering across browsers and operating systems.
Accessibility: improved accessibility and usability reduce user friction.
9. Why are you still using Node 18 and React 16 when newer versions exist?
We are aware that React 19 and Node 24 are available.
Our current release is focused on design and accessibility improvements.
We’ve already started work on version 6, which will upgrade to newer Node and React versions along with their dependencies.
Version 6 is scheduled for release before the end of 2025.
10. Where can I learn more or get help?
Refer to the Design System Documentation for implementation details.
Please send us Feedback via this form.
Open a GitHub issue if you encounter migration issues or find any bugs.
Reach out to your Customer Success Manager if you need additional support from our engineering team.