Component usage
How to best compose and style the components.
Keep components/ui intact
WFP Design System works a little differently from ‘traditional’ component libraries: components aren’t imported from an external dependency, but instead are copied into your project, in your components/ui directory. This gives you full control and customizability.
However, to prevent issues with updates and compatibility, avoid changes to the local components, unless absolutely necessary;
- Avoid changing any of the components’ source code inside
components/ui - Avoid adding custom components inside
components/ui - If using an AI agent, instruct it not to touch
components/ui
Follow code examples
The code examples on this website show the recommended way to implement the components.
Use defaults
Avoid custom styles that override the defaults.
While it is possible to add custom Tailwind classes to customize the styling of components, this is discouraged, since it bypasses the design system and introduces inconsistencies.
Many of the components offer several variants out of the box, to serve different use cases. Stick to these as much as possible.
If the existing component variants don’t serve your use case, contact the team to discuss extending the design system.
If the design you’re given suggests diverging from the default variants, check with your designer if this is really intentional.
✅ Do
<Badge variant="success">❌ Don’t
<Badge className="border-green-400 bg-green-200 text-green-800">Use Tailwind CSS
Use Tailwind utility classes for styling whenever possible, to help ensure consistency and quality.
Avoid traditional CSS classes and inline styles.
✅ Do
<div className="rounded-md">❌ Don’t
<div style={{ borderRadius: "8px" }}>Use colour tokens
Don’t hard-code colour values, or construct new colours with modifiers.
Use the design system colour tokens. Prefer theme colours and semantic colours over base colours.
The colour palette is regularly updated, to improve branding and accessibility. Colour tokens will inherit these improvements, hard-coded and modified values will not.
✅ Do
<p className="text-foreground">❌ Don’t
<p className="text-[#000000e9]">✅ Do
<p className="text-destructive">❌ Don’t
<p className="text-[red]">✅ Do
<div className="bg-muted">❌ Don’t
<div className="bg-[#f8f8f8]">✅ Do
<div className="border-border">❌ Don’t
<div className="border-black/10">✅ Do
<div className="border-primary-400">⚠️ Avoid
<div className="border-blue-400">Use size tokens
Don’t hard-code size values. Especially avoid px values. Use the spacing and sizing tokens.
✅ Do
<div className="p-4">❌ Don’t
<div className="p-[16px]">✅ Do
<div className="max-w-md">❌ Don’t
<div className="max-w-[448px]">✅ Do
<div className="size-6">❌ Don’t
<div className="size-[1.5rem]">✅ Do
<p className="text-lg">❌ Don’t
<p className="text-[18px]">Use font-weight tokens
Don’t use numbers for font-weight. Use the semantic font-weight tokens.
✅ Do
<p className="font-semibold">❌ Don’t
<p className="font-[600]">Use aria-label and tooltip if no text
Tooltips should be used on elements that don’t have visible text, to improve usability and accessibility.
✅ Do
<Tooltip>
<TooltipTrigger asChild>
<Button size="icon" aria-label="Add">
<Plus />
</Button>
</TooltipTrigger>
<TooltipContent>Add</TooltipContent>
</Tooltip>❌ Don’t
<Button size="icon">
<Plus />
</Button>