Merge pull request #149 from jeffreylauwers/feature/skip-link

feat(SkipLink): toegankelijkheidskoppeling om herhalende navigatie te omzeilen

Author: jeffreylauwers

README.md

@@ -65,7 +65,7 @@ pnpm --filter @dsn/design-tokens watch
 # Start Storybook in development mode
 pnpm dev
 
-# Run tests (1282 tests across 63 test suites)
+# Run tests (1292 tests across 64 test suites)
 pnpm test
 
 # Run tests in watch mode
@@ -211,6 +211,12 @@ All components are fully typed with TypeScript and include comprehensive JSDoc d
 | **MenuLink**             | Yes      | Yes   | —             |
 | **PageHeader**           | Yes      | Yes   | —             |
 
+**Accessibility Components (1)**
+
+| Component    | HTML/CSS | React | Web Component |
+| ------------ | -------- | ----- | ------------- |
+| **SkipLink** | Yes      | Yes   | —             |
+
 **Form Components (25)**
 
 | Component                 | HTML/CSS | React | Web Component |
@@ -384,7 +390,7 @@ Comprehensive documentation is available in the `/docs` folder:
 
 - **Pre-commit hooks** via Husky + lint-staged (ESLint + Prettier)
 - **Type checking** across all packages (`pnpm type-check`)
-- **1282 tests** covering React components, Web Components, and utilities
+- **1292 tests** covering React components, Web Components, and utilities
 - **CI/CD** via GitHub Actions (lint, type-check, test, build)
 
 ## Tech Stack

docs/03-components.md

@@ -1,6 +1,6 @@
 # Components
 
-**Last Updated:** April 6, 2026
+**Last Updated:** April 9, 2026
 
 Complete component specifications and guidelines for the Design System Starter Kit.
 
@@ -14,8 +14,9 @@ Complete component specifications and guidelines for the Design System Starter K
 4. [Display & Feedback Components](#display--feedback-components)
 5. [Navigation Components](#navigation-components)
 6. [Branding Components](#branding-components)
-7. [Form Components](#form-components)
-8. [Web Components Registration](#web-components-registration)
+7. [Accessibility Components](#accessibility-components)
+8. [Form Components](#form-components)
+9. [Web Components Registration](#web-components-registration)
 
 ---
 
@@ -2200,6 +2201,66 @@ const [isOpen, setIsOpen] = React.useState(false);
 
 ---
 
+## Accessibility Components
+
+**Status:** Complete (HTML/CSS, React) — 1 component total
+
+### SkipLink
+
+**Status:** Complete (HTML/CSS, React)
+
+**Location:** `packages/components-{html|react}/src/skip-link/` / `SkipLink/`
+
+**Tokens:** `tokens/components/skip-link.json`
+
+**Props:** `href` (required), `children` (default: `"Ga direct naar de hoofdinhoud"`), `className` + alle `React.AnchorHTMLAttributes<HTMLAnchorElement>` attributen
+
+**Features:**
+
+- Eerste focusbaar element op de pagina — plaatsen vóór `<header>` en `<nav>` in de DOM
+- Standaard verborgen via `clip-path: inset(50%)` — blijft in de accessibility tree (screenreaders kunnen het vinden)
+- Zichtbaar bij `:focus-visible` — gepositioneerd in de hoek van het viewport met focus-stijlen
+- Z-index 600 — boven modals (500), drawer (500) en backdrop (400)
+- Voldoet aan WCAG 2.1 succescriterium 2.4.1 (Bypass Blocks, Level A)
+- `React.forwardRef<HTMLAnchorElement>`
+
+**CSS-klassen:**
+
+| Klasse          | Element | Beschrijving                                       |
+| --------------- | ------- | -------------------------------------------------- |
+| `dsn-skip-link` | `<a>`   | Verbergt de link; onthult hem bij `:focus-visible` |
+
+**Design Tokens:**
+
+| Token                                 | Waarde                   | Beschrijving                                         |
+| ------------------------------------- | ------------------------ | ---------------------------------------------------- |
+| `--dsn-skip-link-z-index`             | `600`                    | Boven modals en backdrop                             |
+| `--dsn-skip-link-padding-block`       | `{dsn.space.block.md}`   | Verticale padding bij focus                          |
+| `--dsn-skip-link-padding-inline`      | `{dsn.space.inline.lg}`  | Horizontale padding bij focus                        |
+| `--dsn-skip-link-border-radius`       | `{dsn.border.radius.md}` | Afgeronde hoeken bij focus                           |
+| `--dsn-skip-link-offset-block-start`  | `{dsn.space.block.md}`   | Afstand van boven het viewport bij focus             |
+| `--dsn-skip-link-offset-inline-start` | `{dsn.space.inline.md}`  | Afstand van de linkerkant van het viewport bij focus |
+
+**Usage:**
+
+```html
+<!-- HTML/CSS — altijd als eerste element in <body> -->
+<a href="#main-content" class="dsn-skip-link">Ga direct naar de hoofdinhoud</a>
+<header>...</header>
+<main id="main-content" tabindex="-1">...</main>
+```
+
+```tsx
+// React
+<SkipLink href="#main-content">Ga direct naar de hoofdinhoud</SkipLink>
+<header>...</header>
+<main id="main-content" tabIndex={-1}>...</main>
+```
+
+**Tests:** React (10 tests)
+
+---
+
 ## Form Components
 
 **Status:** Complete (HTML/CSS, React) — 25 components total
@@ -2511,15 +2572,15 @@ defineButton('my-custom-button');
 
 ## Component Statistics
 
-**Total Components:** 49
+**Total Components:** 50
 
 **Implementations:**
 
-- **HTML/CSS:** 49 components
-- **React:** 49 components (1282 tests total, 63 test suites)
+- **HTML/CSS:** 50 components
+- **React:** 50 components (1292 tests total, 64 test suites)
 - **Web Component:** 7 components (Button, Heading, Icon, Link, OrderedList, Paragraph, UnorderedList)
 
-**Test Coverage:** 1282 tests across 63 test suites
+**Test Coverage:** 1292 tests across 64 test suites
 
 ---
 

docs/README.md

@@ -1,7 +1,7 @@
 # Design System Documentation
 
-**Version:** 5.18.0
-**Last Updated:** April 4, 2026
+**Version:** 5.22.0
+**Last Updated:** April 9, 2026
 
 Complete documentation voor het Design System Starter Kit.
 
@@ -91,8 +91,8 @@ Complete documentation voor het Design System Starter Kit.
 
 - **Tokens per configuration:** ~1100 (400 semantic + 700 component)
 - **Configurations:** 8 (2 themes × 2 modes × 2 project types)
-- **Components:** 48 (5 layout + 10 content + 9 display/feedback + 1 branding + 3 navigation + 25 form; HTML/CSS + React)
-- **Tests:** 1248 across 62 test suites
+- **Components:** 50 (5 layout + 10 content + 9 display/feedback + 1 branding + 5 navigation + 25 form + 1 accessibility; HTML/CSS + React)
+- **Tests:** 1292 across 64 test suites
 - **Storybook stories:** 130+
 
 ---

docs/changelog.md

@@ -6,6 +6,23 @@ All notable changes to this project are documented in this file.
 
 ---
 
+## Version 5.22.0 (April 9, 2026)
+
+### SkipLink component (issue #148, PR #149)
+
+#### Added
+
+- **SkipLink** component — toegankelijkheidskoppeling als eerste focusbaar element op de pagina (PR #149)
+- Standaard verborgen via `clip-path: inset(50%)`; zichtbaar bij `:focus-visible` in de hoek van het viewport
+- Voldoet aan WCAG 2.1 succescriterium 2.4.1 (Bypass Blocks, Level A)
+- `href` prop (verplicht), `children` prop (default: `"Ga direct naar de hoofdinhoud"`), `React.forwardRef<HTMLAnchorElement>`
+- 6 design tokens: `z-index: 600`, padding-block/inline, border-radius, offset-block/inline-start
+- Z-index 500 toegevoegd aan `modal-dialog.json` en `drawer.json`
+- `backdrop.json` comment bijgewerkt met volledige z-index schaal: backdrop (400) → modal-dialog/drawer (500) → skip-link (600)
+- 10 React tests
+
+---
+
 ## Version 5.21.1 (April 6, 2026)
 
 ### Fix: PageHeader large viewport verfijningen (PR #146)

packages/components-html/src/skip-link/skip-link.css

@@ -0,0 +1,52 @@
+/**
+ * SkipLink Component
+ * Accessibility component — eerste focusbare element op de pagina.
+ * Verborgen totdat de gebruiker er met Tab op focust.
+ */
+
+.dsn-skip-link {
+  /* Verborgen standaard — zelfde patroon als dsn-visually-hidden */
+  position: absolute;
+  clip-path: inset(50%);
+  overflow: hidden;
+  white-space: nowrap;
+
+  /* Hoge z-index zodat de link altijd boven andere elementen staat bij focus */
+  z-index: var(--dsn-skip-link-z-index);
+
+  /* Structuur */
+  display: inline-block;
+
+  /* Spacing */
+  padding-block: var(--dsn-skip-link-padding-block);
+  padding-inline: var(--dsn-skip-link-padding-inline);
+
+  /* Afronding */
+  border-radius: var(--dsn-skip-link-border-radius);
+
+  /* Typografie */
+  font: inherit;
+  text-decoration: none;
+}
+
+/* Focus state — link wordt zichtbaar en gepositioneerd */
+.dsn-skip-link:focus-visible {
+  /* Clip verwijderen zodat de link zichtbaar wordt */
+  clip-path: none;
+  overflow: visible;
+  white-space: normal;
+
+  /* Positionering in de hoek van het viewport */
+  inset-block-start: var(--dsn-skip-link-offset-block-start);
+  inset-inline-start: var(--dsn-skip-link-offset-inline-start);
+
+  /* Focus stijl — consistent met dsn-link focus */
+  background-color: var(--dsn-focus-background-color);
+  color: var(--dsn-focus-color);
+  outline: var(--dsn-focus-outline-width) var(--dsn-focus-outline-style)
+    var(--dsn-focus-outline-color);
+  outline-offset: var(--dsn-focus-outline-offset);
+  box-shadow: 0 0 0
+    calc(var(--dsn-focus-outline-offset) + var(--dsn-focus-outline-width))
+    var(--dsn-focus-inverse-outline-color);
+}

packages/components-react/src/SkipLink/SkipLink.css

@@ -0,0 +1,6 @@
+/**
+ * SkipLink Component Styles for React
+ * Re-exports the base SkipLink styles from components-html
+ */
+
+@import '../../../components-html/src/skip-link/skip-link.css';

packages/components-react/src/SkipLink/SkipLink.test.tsx

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SkipLink } from './SkipLink';
+
+describe('SkipLink', () => {
+  it('renders children', () => {
+    render(<SkipLink href="#main">Ga direct naar de hoofdinhoud</SkipLink>);
+    expect(
+      screen.getByRole('link', { name: 'Ga direct naar de hoofdinhoud' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders as an anchor element', () => {
+    render(<SkipLink href="#main">Skip</SkipLink>);
+    expect(screen.getByRole('link').tagName).toBe('A');
+  });
+
+  it('sets href on the anchor', () => {
+    render(<SkipLink href="#main-content">Skip</SkipLink>);
+    expect(screen.getByRole('link')).toHaveAttribute('href', '#main-content');
+  });
+
+  it('applies base dsn-skip-link class', () => {
+    render(<SkipLink href="#main">Skip</SkipLink>);
+    expect(screen.getByRole('link')).toHaveClass('dsn-skip-link');
+  });
+
+  it('applies custom className', () => {
+    render(
+      <SkipLink href="#main" className="custom">
+        Skip
+      </SkipLink>
+    );
+    expect(screen.getByRole('link')).toHaveClass('dsn-skip-link', 'custom');
+  });
+
+  it('uses default children text when no children provided', () => {
+    render(<SkipLink href="#main" />);
+    expect(
+      screen.getByRole('link', { name: 'Ga direct naar de hoofdinhoud' })
+    ).toBeInTheDocument();
+  });
+
+  it('renders custom children text', () => {
+    render(<SkipLink href="#main">Sla navigatie over</SkipLink>);
+    expect(
+      screen.getByRole('link', { name: 'Sla navigatie over' })
+    ).toBeInTheDocument();
+  });
+
+  it('forwards ref', () => {
+    const ref = { current: null as HTMLAnchorElement | null };
+    render(
+      <SkipLink ref={ref} href="#main">
+        Skip
+      </SkipLink>
+    );
+    expect(ref.current).toBeInstanceOf(HTMLAnchorElement);
+  });
+
+  it('passes through additional anchor attributes', () => {
+    render(
+      <SkipLink href="#main" data-testid="skip-link">
+        Skip
+      </SkipLink>
+    );
+    expect(screen.getByTestId('skip-link')).toBeInTheDocument();
+  });
+
+  it('passes lang attribute', () => {
+    render(
+      <SkipLink href="#main" lang="en">
+        Skip to main content
+      </SkipLink>
+    );
+    expect(screen.getByRole('link')).toHaveAttribute('lang', 'en');
+  });
+});

packages/components-react/src/SkipLink/SkipLink.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { classNames } from '@dsn/core';
+import './SkipLink.css';
+
+export interface SkipLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * Het doel-ID waarnaar de gebruiker gesprongen wordt (inclusief `#`).
+   * Het element met dit ID moet `tabindex="-1"` hebben als het niet natively focusbaar is.
+   * @example "#main-content"
+   */
+  href: string;
+
+  /**
+   * Tekst van de skip-link — zichtbaar voor screenreaders en bij focus.
+   * @default "Ga direct naar de hoofdinhoud"
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Extra CSS klassen
+   */
+  className?: string;
+}
+
+/**
+ * SkipLink — toegankelijkheidskoppeling om herhalende navigatie te omzeilen.
+ *
+ * Plaatst de link als **eerste focusbaar element** in de DOM, vóór `<header>` en `<nav>`.
+ * Voldoet aan WCAG 2.1 succescriterium 2.4.1 (Bypass Blocks, Level A).
+ *
+ * @example
+ * ```tsx
+ * // Standaard gebruik — eerste element in <body>
+ * <SkipLink href="#main-content">Ga direct naar de hoofdinhoud</SkipLink>
+ * <header>...</header>
+ * <main id="main-content" tabIndex={-1}>...</main>
+ * ```
+ */
+export const SkipLink = React.forwardRef<HTMLAnchorElement, SkipLinkProps>(
+  (
+    { href, children = 'Ga direct naar de hoofdinhoud', className, ...props },
+    ref
+  ) => {
+    return (
+      <a
+        ref={ref}
+        href={href}
+        className={classNames('dsn-skip-link', className)}
+        {...props}
+      >
+        {children}
+      </a>
+    );
+  }
+);
+
+SkipLink.displayName = 'SkipLink';

packages/components-react/src/SkipLink/index.ts

@@ -0,0 +1 @@
+export * from './SkipLink';

packages/components-react/src/index.ts

@@ -60,6 +60,9 @@ export * from './Details';
 // Branding Components
 export * from './Logo';
 
+// Accessibility Components
+export * from './SkipLink';
+
 // Navigation Components
 export * from './BreadcrumbNavigation';
 export * from './Menu';