How nl-design-system/documentatie works
Project type and purpose
• This is a documentation website for the “NL Design System,” built as a static site using Docusaurus (React + Markdown/MDX).
• It’s a monorepo managed by pnpm, combining:
• Content (docs/, blog/, static/)
• Custom UI (src/components, src/theme)
• Two reusable packages (packages/archimate and packages/nlds-design-tokens)
• Build & test pipelines (.github/workflows, Docker/Apache for local simulation).
Architectural overview
• Content layer
• Markdown files under docs/ → pages on the site
• .mdx files for mixed Markdown+React
• blog/ for blog posts
• static/ for raw assets and redirects (.htaccess)
• Presentation layer
• src/components & src/theme override Docusaurus components
• CSS under src/css and component-specific .css files
• Design tokens consumed via @nl-design-system-tokens package
• Build system
• Docusaurus CLI invoked by pnpm scripts (build, start, serve)
• style-dictionary-driven token build (packages/nlds-design-tokens)
• TypeScript/JS bundling (babel.config.mjs, tsconfig.json)
• Local test environment
• Docker Compose + httpd.Dockerfile + httpd.conf for Apache testing of redirects
• CI/CD & QA
• GitHub Actions workflows: cd.yml (deploy), publish.yml (npm packages), require-autosquash.yml
• E2E tests with Playwright (test/e2e) and visual regression via Argos CI (test/visual)
• Hosting
• Production static hosting via Vercel or Apache on Docker (vercel.json present, compose.yaml)
• CDN for static assets, HTTPS, custom domain.
Main components
• “Authoring & Repo”
• Developers write Markdown/MDX, React components, token definitions
• GitHub repository with monorepo (pnpm-root)
• “CI/CD Pipeline”
• GitHub Actions build → lint → test → style-dictionary token build → Docusaurus build → deploy
• Argos CI for visual regression
• “Build System”
• Node.js, pnpm, Babel, Docusaurus CLI
• style-dictionary for design tokens
• TypeScript compile & bundling
• “Static Site Generator”
• Docusaurus Core & plugins (content-blog, content-docs, theme)
• Outputs HTML/CSS/JS and assets into build/
• “Hosting & Runtime”
• Static HTTP server (Vercel / Apache HTTPD + Docker)
• CDN & HTTPS termination
• .htaccess redirects tested locally under Docker
• “Consumers”
• End users (browsers) request pages
• Designers/Developers consume tokens from npm package
Relationships & interactions
• Author push → GitHub
→ triggers CI/CD
→ installs dependencies (pnpm install)
→ runs lint, tests, token build
→ runs Docusaurus build
→ publishes build artifacts
→ deploys to hosting
• Local dev
→ pnpm run start → Docusaurus server with hot-reload
→ (optional) Docker Compose brings up Apache to serve build/
• End user requests
→ static files served from CDN/HTTP server
→ JS hydration for dynamic components (contrast checker, MDX React components).
Architectural patterns & principles
• Monorepo with package isolation (pnpm-workspace.yaml)
• Static site generation (SSG) for performance and security
• Composition: Markdown + MDX + React components
• Theming & extensibility via Docusaurus theme overrides
• CI as code: GitHub Actions define build, test, publish, deploy
• Token-driven styling: central design tokens packaged for reuse
Technologies & frameworks
• Docusaurus (React, MDX, content-docs, content-blog)
• Node.js, pnpm, Babel, TypeScript
• style-dictionary (design tokens)
• GitHub Actions, Playwright, Argos CI
• Docker Compose, Apache HTTPD
• Vercel (optional), static CDN