Usage guidelines

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 avoid issues with updates and compatibility, we highly recommend you avoid touching 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 us 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.

<Badge variant="success">…</Badge>

<Badge className="bg-green-600 text-white font-semibold border border-green-300">
  …
</Badge>

Use Tailwind CSS

Use Tailwind utility classes for styling whenever possible, to help ensure consistency and quality.

Avoid traditional CSS classes and inline styles.

<div className="rounded-md">…</div>

<div style={{ borderRadius: "8px" }}>…</div>

Use size tokens

Don’t use hardcoded size values. Especially avoid px values. Use the spacing & sizing tokens.

<div className="p-4">…</div>
<div className="max-w-md">…</div>
<div className="size-6">…</div>
<p className="text-lg">…</p>

<div className="p-[16px]">…</div>
<div className="max-w-[448px]">…</div>
<div className="size-[1.5rem]">…</div>
<p className="text-[18px]">…</p>

Use colour tokens

Don’t use hardcoded HEX or RGB codes for colours. Use the semantic tokens and colour tokens.

Our colour palette is continuously updated, to improve branding and accessibility. Colour tokens will inherit updates; hardcoded values will not.

<p className="text-primary-600">…</p>
<p className="text-danger-600">…</p>
<div className="border-border">…</div>

<p className="text-[#007dbc]">…</p>
<p className="text-[red]">…</p>
<div className="border-[#eeeeee]">…</div>

Use font-weight tokens

Don’t use numbers for font-weight. Use the semantic font-weight tokens.

<p className="font-semibold">…</p>

<p className="font-[600]">…</p>

Use aria-label & tooltip if no text

Tooltips should be used on elements that don’t have visible text, to improve usability and accessibility.

<Tooltip>
  <TooltipTrigger>
    <Button size="icon" aria-label="Add">
      <Plus />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Add</TooltipContent>
</Tooltip>

<Button size="icon">
  <Plus />
</Button>