# scania-digital-design-system/tegel architecture

> Architecture diagram of the GitHub repository scania-digital-design-system/tegel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scania-digital-design-system/tegel
- Repository: https://github.com/scania-digital-design-system/tegel

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Workstation"
        DEV_GIT["Git Clone (GitHub)"]:::external
        DEV_TOOL["Node.js & Docker"]:::processes
        DEV_SCRIPTS["npm scripts (start, storybook)"]:::processes
        DEV_HOOKS["Husky & Commitlint"]:::processes
    end

    %% Monorepo Root
    subgraph "Monorepo Root"
        BT["build-tokens.js"]:::source
        click BT "https://github.com/scania-digital-design-system/tegel/blob/develop//build-tokens.js"
        SD_CFG["style-dictionary.config.js"]:::source
        click SD_CFG "https://github.com/scania-digital-design-system/tegel/blob/develop//style-dictionary.config.js"
        SCSS_OUT["build/scss/"]:::outputs
        click SCSS_OUT "https://github.com/scania-digital-design-system/tegel/tree/develop//build/scss/"
    end

    %% Token Pipeline
    subgraph "Token Pipeline" 
        TOK_JSON["tokens-json/"]:::source
        click TOK_JSON "https://github.com/scania-digital-design-system/tegel/tree/develop//tokens-json/"
        STYLE_DICT["Style Dictionary"]:::processes
        TOK_SCSS["tokens/"]:::outputs
        click TOK_SCSS "https://github.com/scania-digital-design-system/tegel/tree/develop//tokens/"
        subgraph "SCSS Foundations"
            COLOR["color/"]:::source
            click COLOR "https://github.com/scania-digital-design-system/tegel/tree/develop//color/"
            SPACING["spacing/"]:::source
            click SPACING "https://github.com/scania-digital-design-system/tegel/tree/develop//spacing/"
            TYPO["typography/"]:::source
            click TYPO "https://github.com/scania-digital-design-system/tegel/tree/develop//typography/"
            GRID_DEP["grid-deprecated/"]:::source
            click GRID_DEP "https://github.com/scania-digital-design-system/tegel/tree/develop//grid-deprecated/"
            GRID["grid/"]:::source
            click GRID "https://github.com/scania-digital-design-system/tegel/tree/develop//grid/"
        end
    end

    %% Packages
    subgraph "Packages"
        subgraph "core"
            CORE_PKG["package.json"]:::source
            click CORE_PKG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/core/package.json"
            SB_CFG[".storybook/"]:::processes
            click SB_CFG "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/.storybook/"
            DOCKER_RUN["docker-test-runner.js"]:::processes
            click DOCKER_RUN "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/core/docker-test-runner.js"
            PW_CFG["playwright.config.ts"]:::processes
            click PW_CFG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/core/playwright.config.ts"
            PW_AXE["playwright-axe.config.ts"]:::processes
            click PW_AXE "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/core/playwright-axe.config.ts"
            COMP_SRC["src/components/"]:::source
            click COMP_SRC "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/src/components/"
            GLOBAL["src/global/"]:::source
            click GLOBAL "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/src/global/"
            MIXINS["src/mixins/"]:::source
            click MIXINS "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/src/mixins/"
            UTILS["src/utils/"]:::source
            click UTILS "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/src/utils/"
            PUBLIC["public/"]:::outputs
            click PUBLIC "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/public/"
            SCRIPTS["scripts/"]:::processes
            click SCRIPTS "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/core/scripts/"
            ST_CONFIG["stencil.config.ts"]:::source
            click ST_CONFIG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/core/stencil.config.ts"
        end

        subgraph "react"
            RE_PKG["package.json"]:::source
            click RE_PKG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/react/package.json"
            RE_LIB["lib/index.ts"]:::outputs
            click RE_LIB "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/react/lib/index.ts"
        end

        subgraph "angular"
            NG_CFG["angular.json"]:::source
            click NG_CFG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/angular/angular.json"
            NG_PROJ["projects/components/"]:::source
            click NG_PROJ "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/angular/projects/components/"
        end

        subgraph "angular-17"
            NG17_CFG["angular.json"]:::source
            click NG17_CFG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/angular-17/angular.json"
            NG17_PROJ["projects/components/"]:::source
            click NG17_PROJ "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/angular-17/projects/components/"
        end

        subgraph "styles"
            STY_PKG["package.json"]:::source
            click STY_PKG "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/styles/"
            BUILD_CSS["build-css.js"]:::processes
            click BUILD_CSS "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/styles/build-css.js"
            FOUNDATION["scss/foundations/"]:::source
            click FOUNDATION "https://github.com/scania-digital-design-system/tegel/tree/develop//packages/styles/scss/foundations/"
        end

        subgraph "tegel-light"
            TL_PKG["package.json"]:::source
            click TL_PKG "https://github.com/scania-digital-design-system/tegel/blob/develop//packages/tegel-light/package.json"
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GH_WORKFLOWS[".github/workflows/"]:::processes
        click GH_WORKFLOWS "https://github.com/scania-digital-design-system/tegel/tree/develop//.github/workflows/"
        TESTS["Docker Tests (Playwright & Axe)"]:::processes
        BUILD_PKGS["Build Packages"]:::processes
        PUBLISH["Publish to NPM"]:::processes
        DEPLOY_SB["Deploy Storybook"]:::processes
    end

    %% External Services
    NPM["NPM Registry"]:::external
    SB_HOST["Storybook Hosting"]:::external
    CDN["CDN (static assets)"]:::external

    %% Flows
    DEV_GIT -->|clones| BT
    DEV_GIT -->|clones| SD_CFG
    DEV_TOOL --> BT
    DEV_TOOL --> SD_CFG
    DEV_SCRIPTS --> SB_HOST
    DEV_HOOKS --> DEV_GIT

    TOK_JSON -->|feeds| STYLE_DICT
    STYLE_DICT --> TOK_SCSS
    TOK_SCSS --> COLOR
    TOK_SCSS --> SPACING
    TOK_SCSS --> TYPO
    TOK_SCSS --> GRID_DEP
    TOK_SCSS --> GRID

    CORE_PKG --> STYLE_DICT
    CORE_PKG --> TOK_SCSS
    GLOBAL --> CORE_PKG
    MIXINS --> CORE_PKG
    UTILS --> CORE_PKG
    COMP_SRC --> CORE_PKG
    PUBLIC --> CDN

    CORE_PKG --> SB_HOST
    RE_PKG --> CORE_PKG
    NG_CFG --> CORE_PKG
    NG17_CFG --> CORE_PKG
    STY_PKG --> TOK_SCSS
    TL_PKG --> CORE_PKG

    GH_WORKFLOWS --> TESTS
    TESTS --> BUILD_PKGS
    BUILD_PKGS --> PUBLISH
    PUBLISH --> NPM
    BUILD_PKGS --> DEPLOY_SB
    DEPLOY_SB --> SB_HOST

    %% Legend
    subgraph "Legend"
        A["Source Artifacts"]:::source
        B["Processes"]:::processes
        C["Outputs/Deployments"]:::outputs
        D["External Services"]:::external
    end

    classDef source fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef processes fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef outputs fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#37474F;
```
