Component Library¶
Guidelines for using and creating components.
Design System¶
Colors¶
The design system defines CSS custom properties in frontend/app/globals.css
under :root, and re-exposes them to Tailwind 4 via @theme inline (so
--primary is usable as e.g. text-primary). The hex values below are current
brand values (several were darkened for WCAG AA contrast):
--primary: #15808d; /* Brand teal (darkened for WCAG AA, white on teal 4.66:1) */
--primary-dark: #126b75; /* Hover */
--primary-darker: #0e565e; /* Active/pressed */
--primary-light: #b1e0e8;
--primary-text: #0f7c8a; /* Teal text on white (AA) */
--accent: #dc2626; /* CTA red (darkened for WCAG AA) */
--accent-dark: #b91c1c; /* Hover */
--foreground: #131117; /* Dark navy text */
--muted-foreground: #525960; /* AA-compliant on white */
/* Frost / Ice / Coral theme tokens, defined as numbered scales */
--frost-50: #f0f9ff; /* scale runs 50–600 */
--frost-300: #7dd3fc;
--frost-600: #0284c7;
--ice-100: #e0f7fa; /* scale runs 100–400 */
--ice-400: #4dd0e1;
--coral-400: #fb7185; /* warm accent, also --coral-500 */
Typography¶
Font stacks are system fonts (--font-plus-jakarta resolves to Avenir Next /
Segoe UI / Helvetica, --font-geist-mono to SF Mono / Menlo / Consolas), mapped to
--font-sans and --font-mono in @theme inline.
--text-xs: 0.75rem; /* 12px */
--text-sm: 0.875rem; /* 14px */
--text-base: 1rem; /* 16px */
--text-lg: 1.125rem; /* 18px */
--text-xl: 1.25rem; /* 20px … up to --text-4xl (36px) */
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
Spacing¶
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px … up to --space-16 (64px) */
Component Patterns¶
Props Interface¶
Always define typed props:
interface ComponentProps {
/** Primary content */
children: React.ReactNode;
/** Visual variant */
variant?: 'primary' | 'secondary';
/** Additional CSS classes */
className?: string;
}
Default Props¶
Use destructuring for defaults:
export function Component({
variant = 'primary',
className = '',
children,
}: ComponentProps) {
// ...
}
Composition¶
Prefer composition over configuration:
// Good
<Card>
<CardHeader>
<CardTitle>Title</CardTitle>
</CardHeader>
<CardContent>Content</CardContent>
</Card>
// Avoid
<Card
title="Title"
content="Content"
showHeader={true}
/>
Server vs client¶
Pages and layouts are server components unless they need browser APIs or hooks;
interactive components start with 'use client'. Shared, heavy client-only pieces
(PostHog, Motion, Navigation, Footer, CookieConsent) are loaded with next/dynamic
in the layouts.
Dutch copy¶
All customer-facing text is Dutch. Do not translate existing strings; for business-specific wording (product names, legal text, payment statuses) ask Ivar.
Creating Stories¶
Every reusable presentational component should have a story. Stories live next to
the component as Component.stories.tsx and are picked up by
frontend/.storybook/main.ts (components/**/*.stories.tsx). The existing stories
import their types from @storybook/nextjs:
// ProductCard.stories.tsx
import type { Meta, StoryObj } from '@storybook/nextjs';
import ProductCard from './ProductCard';
import type { Product } from '@/types';
const meta: Meta<typeof ProductCard> = {
title: 'Products/ProductCard',
component: ProductCard,
tags: ['autodocs'],
};
export default meta;
type Story = StoryObj<typeof ProductCard>;
export const Default: Story = {
args: {
product: sampleProduct,
},
};
Components that need API data should receive it as props (or be wrapped with a
QueryProvider decorator in the story) so they render without a backend.
Testing¶
- Jest unit tests live in
frontend/__tests__/(e.g.__tests__/components/Footer.test.tsx), run withnpm run test:ciin CI. - Playwright E2E tests live in
frontend/e2e/(smoke, visual, full, admin suites). - Use
data-testidon interactive elements so tests do not depend on Dutch copy.
Accessibility¶
All components must:
- Support keyboard navigation (
useFocusTrapfor dialogs and drawers) - Have appropriate ARIA attributes
- Meet WCAG 2.1 AA contrast ratios (the tokens above are tuned for this)
- Include
data-testidfor testing
The Storybook a11y addon reports contrast and ARIA issues per story.