Skip to content

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 with npm run test:ci in CI.
  • Playwright E2E tests live in frontend/e2e/ (smoke, visual, full, admin suites).
  • Use data-testid on interactive elements so tests do not depend on Dutch copy.

Accessibility

All components must:

  1. Support keyboard navigation (useFocusTrap for dialogs and drawers)
  2. Have appropriate ARIA attributes
  3. Meet WCAG 2.1 AA contrast ratios (the tokens above are tuned for this)
  4. Include data-testid for testing
<button
  aria-label="Aantal verhogen"
  data-testid="quantity-increment"
>
  +
</button>

The Storybook a11y addon reports contrast and ARIA issues per story.