# Scrum4Me — Styling & Design System **Versie:** 0.1 — april 2026 **Onderdeel van:** CLAUDE.md context-set --- ## Overzicht Scrum4Me gebruikt **Material Design 3 (MD3)** als kleurfilosofie, geïmplementeerd via CSS custom properties in `theme.css` en direct bruikbaar als Tailwind utility classes. **shadcn/ui** levert alle UI-primitieven (Button, Dialog, Sheet, Badge, etc.) en is volledig compatibel met het MD3-kleurensysteem via de legacy-token-mapping. Lees dit document voordat je een component schrijft. Gebruik **nooit** willekeurige Tailwind-kleuren zoals `bg-blue-500` of `bg-green-600` — gebruik altijd de semantische tokens uit dit systeem. --- ## Setup ### 1. theme.css plaatsen Kopieer het meegeleverde `theme.css` bestand naar: ``` app/globals.css ← importeer theme.css hier, of plak de inhoud direct ``` Of als apart bestand: ``` styles/theme.css ``` Importeer in `app/globals.css`: ```css @import './styles/theme.css'; ``` ### 2. shadcn/ui initialiseren ```bash npx shadcn@latest init ``` Kies bij de setup: - Style: **Default** - Base color: **Slate** (wordt overschreven door theme.css) - CSS variables: **Yes** De `theme.css` overschrijft alle shadcn default-kleuren via CSS custom properties. Geen extra configuratie nodig. ### 3. Tailwind configuratie `theme.css` registreert alle tokens via `@theme inline` — ze zijn direct beschikbaar als Tailwind utility classes: ```tsx // Werkt direct: className="bg-primary text-primary-foreground" className="bg-surface-container-low" className="bg-status-done" className="bg-priority-critical" ``` ### 4. Dark mode Dark mode werkt via de `.dark` class op ``: ```tsx // components/theme-toggle.tsx 'use client' import { useState, useEffect } from 'react' export function ThemeToggle() { const [isDark, setIsDark] = useState(false) useEffect(() => { const stored = localStorage.getItem('theme') if (stored === 'dark') { document.documentElement.classList.add('dark') setIsDark(true) } }, []) const toggle = () => { document.documentElement.classList.toggle('dark') const next = !isDark setIsDark(next) localStorage.setItem('theme', next ? 'dark' : 'light') } return ( ) } ``` --- ## Kleurfilosofie Drie hoofdrollen, elk met een semantische betekenis voor een Scrum-planner: | Rol | Kleur | Betekenis | Gebruik in Scrum4Me | |---|---|---|---| | **Primary** | Blauw `#0061a4` | Productiviteit, vertrouwen | Primaire knoppen, actieve navigatie, Sprint Goal | | **Secondary** | Paars `#5b5e71` | Planning, organisatie | Secundaire acties, filters, toolbar-items | | **Tertiary** | Teal `#006874` | Voortgang, data | Voortgangsindicatoren, story-tellers, metrics | Diepte wordt gecreëerd via **tonal elevation** (lichtere/donkerdere oppervlakken), niet via schaduwen. --- ## Surface Elevation System Gebruik deze hiërarchie consequent — nooit `shadow-lg` voor diepte: ``` HOOGSTE ELEVATIE (voorgrond) surface-container-lowest → dialogs, modals, popovers surface-container-low → kaarten, panelen surface-container → standaard container surface-container-high → geneste containers surface-container-highest → achtergrondcontainers LAAGSTE ELEVATIE (achtergrond) background → app-achtergrond ``` ### In Scrum4Me specifiek | Element | Surface token | |---|---| | App achtergrond | `bg-background` | | Navigatiebalk | `bg-surface-container-low` | | Gesplitst scherm (elk paneel) | `bg-surface-container-low` | | PBI-rij | `bg-surface-container` | | Geselecteerde PBI-rij | `bg-primary-container` | | Story-blok | `bg-surface-container-low border border-border` | | Story-blok (geselecteerd) | `bg-primary-container border border-primary` | | Taakregel | `bg-surface-container` | | Dialogs / modals | `bg-surface-container-lowest` | | Slide-over (story detail) | `bg-surface-container-lowest` | | Todo-item | `bg-surface-container` | | Navigatiebar per paneel | `bg-surface-container-highest` | --- ## Statuskleur mapping ### Story- en taakstatus Gebruik **altijd** icoon + tekst naast kleur (toegankelijkheid): ```tsx // Status badge component const statusConfig = { OPEN: { label: 'Open', className: 'bg-status-todo text-white', }, IN_SPRINT: { label: 'In Sprint', className: 'bg-status-in-progress text-white', }, DONE: { label: 'Done', className: 'bg-status-done text-white', }, } // Taakstatus const taskStatusConfig = { TO_DO: { label: 'To Do', className: 'bg-status-todo text-white', }, IN_PROGRESS: { label: 'In Progress', className: 'bg-status-in-progress text-white', }, DONE: { label: 'Done', className: 'bg-status-done text-white', }, } ``` ### Prioriteitskleur mapping ```tsx const priorityConfig = { 1: { label: 'Kritiek', className: 'bg-priority-critical text-white', borderClassName: 'border-l-4 border-priority-critical', }, 2: { label: 'Hoog', className: 'bg-priority-high text-white', borderClassName: 'border-l-4 border-priority-high', }, 3: { label: 'Middel', className: 'bg-priority-medium text-white', borderClassName: 'border-l-4 border-priority-medium', }, 4: { label: 'Laag', className: 'bg-priority-low text-white', borderClassName: 'border-l-4 border-priority-low', }, } ``` ### Story-activiteitenlog ```tsx const logTypeConfig = { IMPLEMENTATION_PLAN: { label: 'Implementatieplan', className: 'bg-info-container text-info-container-foreground border-l-4 border-info', }, TEST_RESULT: { PASSED: { label: 'Tests geslaagd', className: 'bg-success-container text-success-container-foreground border-l-4 border-success', }, FAILED: { label: 'Tests mislukt', className: 'bg-error-container text-error-container-foreground border-l-4 border-error', }, }, COMMIT: { label: 'Commit', className: 'bg-secondary-container text-secondary-container-foreground border-l-4 border-secondary', }, } ``` --- ## shadcn/ui componenten — gebruik in Scrum4Me Alle shadcn-componenten gebruiken automatisch het MD3-kleurensysteem. Hieronder de aanbevolen varianten per context. ### Button ```tsx import { Button } from '@/components/ui/button' // Primaire actie (Sprint starten, PBI aanmaken, Opslaan) // Secundaire actie (Annuleren, Filters, Exporteren) // Destructieve actie (Verwijderen, Archiveren) // Ghost (icon-knoppen in navigatiebar) // Outline (minder urgente acties) ``` ### Badge (status en prioriteit) ```tsx import { Badge } from '@/components/ui/badge' // Gebruik custom className voor MD3-kleuren // shadcn Badge variant="secondary" is ook bruikbaar voor neutrale badges Done Kritiek In Sprint // Neutrale info badge (bijv. "3 taken") 3 taken ``` **PBI-status (READY / BLOCKED / DONE):** hergebruikt bestaande tokens — `status-todo` voor READY, `status-blocked` voor BLOCKED, `status-done` voor DONE. Centraal gedefinieerd in `components/shared/pbi-status-select.tsx` (`PBI_STATUS_LABELS`, `PBI_STATUS_COLORS`); importeer die in plaats van kleuren ad-hoc te kopiëren. ### Dialog (bevestigingsdialogen) ```tsx import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, } from '@/components/ui/alert-dialog' // Standaard bevestigingsdialoog voor verwijderacties PBI verwijderen? Dit verwijdert ook alle gekoppelde stories en taken. Deze actie is niet ongedaan te maken. Annuleren Verwijderen ``` ### Sheet (story detail slide-over) ```tsx import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@/components/ui/sheet' {story.title} {/* story detail inhoud */} ``` ### Input en Textarea ```tsx import { Input } from '@/components/ui/input' import { Textarea } from '@/components/ui/textarea' // shadcn Input gebruikt --input-background automatisch uit theme.css

```

### Select (prioriteit dropdown)

```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select'

<Select>
  <SelectTrigger className="bg-input-background border-border">
    <SelectValue placeholder="Prioriteit" />
  </SelectTrigger>
  <SelectContent className="bg-surface-container-lowest border-border">
    <SelectItem value="1">
      <span className="flex items-center gap-2">
        <span className="w-2 h-2 rounded-full bg-priority-critical" />
        Kritiek
      </span>
    </SelectItem>
    <SelectItem value="2">
      <span className="flex items-center gap-2">
        <span className="w-2 h-2 rounded-full bg-priority-high" />
        Hoog
      </span>
    </SelectItem>
    <SelectItem value="3">
      <span className="flex items-center gap-2">
        <span className="w-2 h-2 rounded-full bg-priority-medium" />
        Middel
      </span>
    </SelectItem>
    <SelectItem value="4">
      <span className="flex items-center gap-2">
        <span className="w-2 h-2 rounded-full bg-priority-low" />
        Laag
      </span>
    </SelectItem>
  </SelectContent>
</Select>
```

### Skeleton (loading states)

```tsx
import { Skeleton } from '@/components/ui/skeleton'

// PBI lijst skeleton
function PbiListSkeleton() {
  return (
    <div className="space-y-2 p-4">
      {Array.from({ length: 5 }).map((_, i) => (
        <Skeleton key={i} className="h-12 w-full bg-surface-container-high" />
      ))}
    </div>
  )
}

// Story blokken skeleton
function StoryGridSkeleton() {
  return (
    <div className="flex flex-wrap gap-3 p-4">
      {Array.from({ length: 6 }).map((_, i) => (
        <Skeleton key={i} className="h-24 w-[10%] min-w-[100px] bg-surface-container-high" />
      ))}
    </div>
  )
}
```

### Tooltip (demo-gebruiker write-protection)

```tsx
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip'

// Gebruik voor alle uitgeschakelde knoppen bij demo-gebruiker
function DemoProtectedButton({ children, isDemo, onClick, ...props }) {
  if (!isDemo) {
    return <Button onClick={onClick} {...props}>{children}</Button>
  }

return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <span>
            <Button disabled {...props}>{children}</Button>
          </span>
        </TooltipTrigger>
        <TooltipContent className="bg-surface-container-lowest border-border">
          <p className="text-sm text-muted-foreground">Niet beschikbaar in demo-modus</p>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

---

## Scrum4Me component patronen

### PBI-rij

```tsx
// Geselecteerd PBI heeft primary-container achtergrond
<div
  className={cn(
    "flex items-center gap-3 px-4 py-3 rounded-lg cursor-pointer transition-colors border-l-4",
    priorityConfig[pbi.priority].borderClassName,
    isSelected
      ? "bg-primary-container text-primary-container-foreground"
      : "bg-surface-container hover:bg-surface-container-high"
  )}
  onClick={() => setSelectedPbi(pbi.id)}
>
  <span className="flex-1 text-sm font-medium truncate">{pbi.title}</span>
  <Badge className={priorityConfig[pbi.priority].className}>
    {priorityConfig[pbi.priority].label}
  </Badge>
</div>
```

### Story-blok

```tsx
// ~10% schermbreedte, compacte weergave
<div
  className={cn(
    "relative flex flex-col gap-1 p-3 rounded-lg border cursor-pointer",
    "min-w-[100px] w-[10%] h-24 text-xs",
    "transition-colors hover:border-primary",
    "bg-surface-container-low border-border"
  )}
>
  <span className="font-medium leading-tight line-clamp-2">{story.title}</span>
  <div className="mt-auto flex items-center justify-between">
    <span className={cn("px-1.5 py-0.5 rounded text-[10px] font-medium", statusConfig[story.status].className)}>
      {statusConfig[story.status].label}
    </span>
    <span className={cn("w-2 h-2 rounded-full", `bg-priority-${priorityLabel}`)}>
    </span>
  </div>
</div>
```

### Prioriteitsgroep scheidingslijn

```tsx
// Visuele scheiding per prioriteitsgroep in PBI-lijst en story-grid
<div className="mt-4 mb-2">
  <div className="flex items-center gap-2">
    <span className={cn(
      "text-xs font-semibold uppercase tracking-wider",
      priority === 1 && "text-priority-critical",
      priority === 2 && "text-priority-high",
      priority === 3 && "text-priority-medium",
      priority === 4 && "text-priority-low",
    )}>
      {priorityConfig[priority].label}
    </span>
    <div className={cn(
      "flex-1 h-px",
      priority === 1 && "bg-priority-critical/30",
      priority === 2 && "bg-priority-high/30",
      priority === 3 && "bg-priority-medium/30",
      priority === 4 && "bg-priority-low/30",
    )} />
    <span className="text-xs text-muted-foreground">{count}</span>
  </div>
</div>
```

### Voortgangsindicator (story → taken)

```tsx
// Gebruikt tertiary kleur voor voortgang
function StoryProgress({ done, total }: { done: number; total: number }) {
  const pct = total === 0 ? 0 : Math.round((done / total) * 100)

return (
    <div className="flex items-center gap-2 text-xs">
      <div className="flex-1 h-1.5 bg-surface-container-highest rounded-full overflow-hidden">
        <div
          className="h-full bg-tertiary rounded-full transition-all"
          style={{ width: `${pct}%` }}
        />
      </div>
      <span className="text-muted-foreground tabular-nums">
        {done}/{total}
      </span>
    </div>
  )
}
```

### Activiteitenlog entry

```tsx
function LogEntry({ entry }: { entry: StoryLog }) {
  const config = entry.type === 'TEST_RESULT'
    ? logTypeConfig.TEST_RESULT[entry.status ?? 'PASSED']
    : logTypeConfig[entry.type]

return (
    <div className={cn("rounded-lg p-3 text-sm", config.className)}>
      <div className="flex items-center justify-between mb-1">
        <span className="font-medium text-xs uppercase tracking-wide">
          {config.label}
        </span>
        <span className="text-xs opacity-70">
          {formatDate(entry.created_at)}
        </span>
      </div>
      <p className="text-sm leading-relaxed whitespace-pre-wrap">
        {entry.content}
      </p>
      {entry.commit_hash && (
        <a
          href={`${repoUrl}/commit/${entry.commit_hash}`}
          target="_blank"
          rel="noopener noreferrer"
          className="mt-1 inline-flex items-center gap-1 text-xs font-mono opacity-80 hover:opacity-100 underline"
        >
          {entry.commit_hash.slice(0, 7)} — {entry.commit_message}
        </a>
      )}
    </div>
  )
}
```

### Sprint Goal banner

```tsx
// Prominent bovenaan Sprint-schermen
<div className="bg-primary-container text-primary-container-foreground rounded-lg px-4 py-3 mb-4">
  <span className="text-xs font-semibold uppercase tracking-wider opacity-70">
    Sprint Goal
  </span>
  <p className="mt-0.5 font-medium">{sprint.sprint_goal}</p>
</div>
```

### Toast notificaties (Sonner)

```tsx
import { toast } from 'sonner'

// Success (aanmaken, opslaan)
toast.success('PBI aangemaakt')
toast.success('Story toegevoegd aan Sprint')

// Error (mislukte Server Action)
toast.error('Opslaan mislukt. Probeer opnieuw.')

// Info (neutrale melding)
toast.info('Sprint afgerond')

// Geen toast bij drag-and-drop (te frequent)
```

---

## Regels (nooit overtreden)

```
❌ bg-blue-500, bg-green-600, bg-red-400    → gebruik semantische tokens
❌ shadow-lg, shadow-md                     → gebruik surface elevation
❌ opacity-50 op een primary button         → gebruik -container variant
❌ Kleur alleen voor status (geen tekst)    → altijd tekst + kleur
❌ Hardcoded hex-waarden in className       → altijd via CSS token
❌ bg-white of bg-black                     → bg-background of bg-foreground

✅ bg-primary text-primary-foreground
✅ bg-surface-container-low
✅ bg-status-done + tekst "Done"
✅ bg-error-container text-error-container-foreground
✅ border-l-4 border-priority-critical
```

---

## Bestandslocaties

```
styles/
  theme.css                 ← bronbestand, niet aanpassen
app/
  globals.css               ← importeert theme.css
components/
  ui/                       ← shadcn/ui (auto-gegenereerd, niet aanpassen)
  shared/
    status-badge.tsx        ← herbruikbare status badge
    priority-badge.tsx      ← herbruikbare prioriteit badge
    demo-button.tsx         ← Button met demo-protection tooltip
    story-log.tsx           ← activiteitenlog entries
    story-progress.tsx      ← voortgangsindicator
    priority-group.tsx      ← prioriteitsgroep scheidingslijn
```

---

## Toegankelijkheid

- Alle kleurcombinaties voldoen aan **WCAG AA** (contrast ratio ≥ 4.5:1 voor normale tekst)
- Gebruik **altijd** tekst + kleur voor statusindicatoren, nooit kleur alleen
- Alle interactieve elementen hebben een zichtbare `focus:ring-primary`
- Dark mode is volledig ondersteund via de `.dark` class

---

*Bijlage bij CLAUDE.md — lees beide voor je begint met bouwen.*