# shoelace-style/shoelace architecture

> Architecture diagram of the GitHub repository shoelace-style/shoelace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shoelace-style/shoelace
- Repository: https://github.com/shoelace-style/shoelace

## Overview

This project is Shoelace—a cutting‐edge library of web components designed for seamless integration with any framework. The project is essentially a component library built with LitElement and bundled with esbuild. It includes an extensive documentation site (using Eleventy) and a comprehensive build pipeline with test suites, custom scripts, and tooling for creating new components.

##### Main Components
- Component Library (src/components): The heart of Shoelace. Each component (e.g., alert, button, dialog, etc.) is isolated in its own directory with separate files for the component logic, styling, tests, and integration (using LitElement).
- Build & Packaging System: Located in the root (package.json, various config files) and in the scripts/ directory. This includes custom build scripts (e.g., build.js, make-react.js) that are orchestrated by esbuild, as well as the creation of react wrappers and themes.
- Documentation System (docs/): Contains the Eleventy configuration, pages, assets, and utility scripts for generating the website that documents every component. It includes custom plugins (in docs/_utilities) and templates.
- Testing & Linting Infrastructure: Files include ESLint, Husky pre-commit hooks, web-test-runner.config.js, and testing files throughout the src directory.
- Internal Utilities & Events: The src/internal, src/events, and src/utilities directories house the internal logic that supports component behaviors (animations, event handling, drag, focus management, etc.).
- Themes & Translations: The src/themes and src/translations folders provide styling customization and internationalization support.

##### Out Relationships and Interactions
- The Internal modules (src/internal) that handle cross-cutting concerns like animations, scrolling, and form controls.
- The Events system (src/events) which standardizes custom events (like sl-change, sl-show, etc.) that these components emit.
- Build & Packaging Pipeline:
- To the core component library (src/) indicating that these scripts compile, bundle, and prepare the distribution versions.
- Documentation Generation Process:
- Testing Infrastructure:
- External integrations:
- That the library works with many frameworks by noting “Framework Integrations” (React, Angular, Vue, Svelte) as mentioned in the docs. Show these as peripheral connectors that interact with the core component library via generated wrappers or custom directives.

##### Architectural Patterns and Design Principles
- Component-based architecture: Each UI element is implemented in an isolated and reusable module.
- Modular build and deployment: Separation of concerns is visible through the distinct directories for build scripts, documentation, and core components.
- Separation of presentation, behavior, and styling: Evident by the co-located but separated files for component logic (.ts), styles (.styles.ts), and tests.
- Extensibility: Tools like the plop-based scaffolding in scripts/plop support rapid component creation.

##### Relevant Technologies
- LitElement for creating web components.
- esbuild for fast bundling.
- Eleventy (11ty) for static site generation of documentation.
- Node.js (version ≥ 14.17) as the runtime.
- Developer tooling: ESLint, Prettier, Husky for code quality and commit hooks.

##### Additional Elements
- Indication of the repository’s continuous integration via GitHub workflows (e.g., node.js.yml, release.yml) that are part of quality checks and automated build/deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core System
    subgraph "Core System"
        CL["Component Library (src/components)"]:::core
        Internal["Internal Modules (src/internal)"]:::core
        Events["Events System (src/events)"]:::core
        Util["Utilities (src/utilities)"]:::core
        CL -->|"uses"| Internal
        CL -->|"emits"| Events
        CL -->|"utilizes"| Util
    end

    %% Customization (Themes & Translations)
    subgraph "Customization"
        Themes["Themes"]:::custom
        Translations["Translations"]:::custom
    end

    %% Build & Packaging System
    subgraph "Build & Packaging"
        BPConf["Config Files (package.json, etc.)"]:::build
        subgraph "Build Scripts (scripts/)"
            build1["build.js"]:::build
            build2["make-react.js"]:::build
            build3["make-icons.js"]:::build
            build4["make-metadata.js"]:::build
            build5["make-themes.js"]:::build
            build6["plop (scaffolding)"]:::build
        end
        BPConf -->|"orchestrates"| CL
        build1 -->|"bundles"| CL
        build2 -->|"generatesWrappers"| CL
        build3 -->|"generatesIcons"| CL
        build4 -->|"generatesMetadata"| CL
        build5 -->|"generatesThemes"| CL
        build6 -->|"scaffoldsComponents"| CL
    end

    %% Documentation System
    subgraph "Documentation"
        Docs["Documentation System (docs/)"]:::doc
        Eleventy["Eleventy Config"]:::doc
        CustomUtil["Custom Utilities"]:::doc
    end
    Docs --> Eleventy
    Docs --> CustomUtil

    %% Testing & Linting Infrastructure
    subgraph "Testing & Linting"
        ESLint["ESLint & Configs (.eslintrc.cjs, .eslintignore, .prettierignore, lint-staged.config.js)"]:::test
        Husky["Husky (pre-commit)"]:::test
        WTR["Web Test Runner"]:::test
    end

    %% External Systems
    Framework["Framework Integrations (React,Angular,Vue,Svelte)"]:::external
    CI["CI Workflows (GitHub Actions)"]:::external

    %% Connections between Core and other systems
    CL -->|"generatesDocs"| Docs
    CL -->|"appliesTheming"| Themes
    CL -->|"appliesLocalization"| Translations
    CL -->|"integratesWith"| Framework
    ESLint -->|"monitors"| CL
    Husky -->|"monitors"| CL
    WTR -->|"tests"| CL
    BPConf -->|"triggers"| CI
    Husky -->|"triggersCI"| CI

    %% Class Definitions for Colour
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef build fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef doc fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef test fill:#F08080,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5;
    classDef custom fill:#E6E6FA,stroke:#000,stroke-width:2px;

    %% Click Events
    click CL "https://github.com/shoelace-style/shoelace/tree/next/src/components"
    click Internal "https://github.com/shoelace-style/shoelace/tree/next/src/internal"
    click Events "https://github.com/shoelace-style/shoelace/tree/next/src/events"
    click Util "https://github.com/shoelace-style/shoelace/tree/next/src/utilities"
    click Themes "https://github.com/shoelace-style/shoelace/tree/next/src/themes"
    click Translations "https://github.com/shoelace-style/shoelace/tree/next/src/translations"
    click BPConf "https://github.com/shoelace-style/shoelace/blob/next/package.json"
    click build1 "https://github.com/shoelace-style/shoelace/blob/next/scripts/build.js"
    click build2 "https://github.com/shoelace-style/shoelace/blob/next/scripts/make-react.js"
    click build3 "https://github.com/shoelace-style/shoelace/blob/next/scripts/make-icons.js"
    click build4 "https://github.com/shoelace-style/shoelace/blob/next/scripts/make-metadata.js"
    click build5 "https://github.com/shoelace-style/shoelace/blob/next/scripts/make-themes.js"
    click build6 "https://github.com/shoelace-style/shoelace/tree/next/scripts/plop/"
    click Docs "https://github.com/shoelace-style/shoelace/tree/next/docs/"
    click Eleventy "https://github.com/shoelace-style/shoelace/blob/next/docs/eleventy.config.cjs"
    click CustomUtil "https://github.com/shoelace-style/shoelace/tree/next/docs/_utilities"
    click ESLint "https://github.com/shoelace-style/shoelace/blob/next/.eslintrc.cjs"
    click Husky "https://github.com/shoelace-style/shoelace/tree/next/husky/"
    click WTR "https://github.com/shoelace-style/shoelace/blob/next/web-test-runner.config.js"
```
