How scania-digital-design-system/tegel works
Project Type & Purpose
• This is an open-source, multi-package Design System (Tegel) providing UI components, style tokens, theming, and integration wrappers (React, Angular).
• Purpose: Ensure brand-coherent, themable components consumable via NPM, a Storybook documentation site, and a CDN/script for static assets.
High-Level Architecture Analysis
• Monorepo (root) containing:
• Build scripts & configuration (build-tokens.js, style-dictionary.config.js, stencil.config.ts)
• Package definitions under /packages:
– core: Stencil-based web components + Storybook + tests + SCSS foundations + static assets
– react, angular, angular-17: framework wrappers
– styles: standalone SCSS library
– tegel-light: theme package
• CI/CD workflows under .github/workflows: linting, testing, accessibility, smoke tests, releases
• Dev tooling: Husky (git hooks), Commitlint, Prettier, ESLint
Key Components
A. Developer Environment
• Local source (GitHub clone)
• Dev tools: Node.js, Docker (for tests), npm scripts (npm run start, npm run storybook)
• Git hooks (Husky), commit conventions (Commitizen, Commitlint)
B. Monorepo Structure
• Root: build-tokens, style-dictionary, config files
• Packages: core (Stencil + SCSS + Storybook), wrappers (React/Angular), styles, themes
• Token source: JSON → style-dictionary → SCSS tokens → component styles
C. Build & Deployment Pipeline
• CI triggers (.github/workflows) on push/PR →
1. Install & lint
2. Run unit/E2E/accessibility tests (Playwright, axe) inside Docker
3. Build each package (Stencil build, SCSS compile, ng-packagr for Angular, Babel for React)
4. Generate distribution (/dist folders, bundled assets)
5. Publish to NPM registry (@scania/tegel packages)
6. Deploy Storybook to CDN/hosting
D. Consumers & External Services
• NPM registry: package consumers
• CDN/static assets: fonts, logos script
• Storybook site: documentation & interactive examples
• Teams channel & GitHub Issues: community interactions
Relationships & Data Flow
• Source tokens (tokens-json) feed into style-dictionary → generate SCSS variables → consumed by core & styles packages.
• Core package exports web components & SCSS foundations.
• Framework wrappers import core components + typings → publish React/Angular component libraries.
• Storybook reads components from core & wrappers → renders docs site.
• CI/CD pipelines orchestrate build/test/publish → NPM and Storybook hosting.
• Developers pull from GitHub, run local build/tests, submit PRs → GitHub workflows validate → merges trigger releases.
Architectural Patterns & Principles
• Monorepo with isolated packages (modular architecture)
• Design tokens driven theming (Style Dictionary)
• Component-driven development (Storybook)
• CI-driven quality gates (lint, test, accessibility)
• Publish-on-merge continuous delivery