# waggylabs/yumekit architecture

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

- Interactive diagram: https://gitdiagram.com/waggylabs/yumekit
- Repository: https://github.com/waggylabs/yumekit

## Overview

1. **What this repo is**
   - Yumekit is a packaged **Web Components UI kit**: a library of reusable custom elements that can be consumed from plain HTML or any framework.
   - The architectural boundary is a single npm package that exports component definitions, themes, icons, and supporting utilities.

2. **Primary runtime surface**
   - `src/index.js` is the main ESM entry that registers the library for modular imports.
   - `src/index.iife.js` is the browser-friendly “drop-in” bundle for CDN/script-tag usage, and includes the full set of components plus icons.
   - `src/react.d.ts` provides TypeScript/React integration types, but React is not the runtime foundation.

3. **Component subsystem**
   - Each component lives in its own folder under `src/components/<name>/`.
   - The pattern is consistent: a component implementation file, a Storybook story, and a test file.
   - This makes components largely independent units, which is important for tree-shaking and for diagramming them as separate leaf nodes around a shared core library.

4. **Component categories**
   - The library spans layout, navigation, inputs, overlays, data display, and feedback: for example `y-button`, `y-input`, `y-dialog`, `y-popover`, `y-table`, `y-tabs`, `y-toast`, `y-tree`, and more.
   - Some components are compositional or nested, such as `y-avatar-group`, `y-button-group`, `y-panelbar`, `y-tree-item`, and `y-sidebar`.
   - The runtime model is “custom element as API”: application code configures components through attributes/properties/events rather than framework-specific bindings.

5. **Shared helper layer**
   - `src/modules/` contains cross-cutting utilities used by multiple components.
   - The notable helpers are `floating.js` for overlay/anchoring behavior, `helpers.js` for shared DOM/logic utilities, and `svg-sanitizer.js` for safe icon/SVG handling.
   - These helpers form the main internal dependency layer beneath popovers, menus, tooltips, dialogs, and other position-aware UI.

6. **Icon system**
   - `src/icons/` is a dedicated subsystem with a registry-based design.
   - `registry.js`, `index.js`, and the generated icon collections (`all.js`, `all-filled.js`, `filled/`) provide a centralized icon catalog.
   - `y-icon` and any icon-capable component depend on this registry rather than embedding SVGs directly, which keeps the icon surface consistent and reusable.

7. **Theme and token architecture**
   - Design tokens are stored in `tokens/core/` and `tokens/themes/` as JSON, with metadata in `$metadata.json` and `$themes.json`.
   - `src/components/y-theme/` is the runtime theming entry point, while `styles/style.css` holds the shared stylesheet layer.
   - `scripts/build-tokens.js` indicates a build step that converts token source data into consumable theme/style artifacts.
   - This is the key data flow for styling: token JSON → build script → CSS/theme runtime → themed components.

8. **Testing and component verification**
   - Most components have colocated tests, and the repo uses both `vitest` and `web-test-runner`, which suggests a mix of unit-level logic tests and browser-level component tests.
   - `src/components/y-code/tokenizer.js` and module tests show that non-visual logic is tested independently as well.
   - Tests are part of the component boundary, verifying behavior, accessibility, and integration with shared helpers.

9. **Documentation and visual development**
   - Storybook is a first-class subsystem: every major component has a `.stories.js` file, and `.storybook/` contains the global configuration.
   - The examples under `.claude/skills/yumekit/examples/` and the repo README show the intended usage patterns and theming flows.
   - Storybook acts as the visual contract for the library, while tests act as the behavioral contract.

10. **Build, packaging, and release pipeline**
   - `rollup.config.js` is the packaging layer for producing distributable artifacts.
   - `scripts/` contains repo automation for tokens, docs bundling, LLM docs sync, and component type copying, showing that the release output is partially generated from source assets.
   - GitHub Actions workflows handle deployment and publication: Storybook deployment, npm publishing, and release publishing.
   - In diagram terms, the source-of-truth inputs are components, tokens, and icons; the outputs are npm package bundles, Storybook docs, and published artifacts.

Main entry points: [`src/index.js`](https://github.com/waggylabs/yumekit/blob/main/src/index.js) (index), [`src/index.iife.js`](https://github.com/waggylabs/yumekit/blob/main/src/index.iife.js) (IIFE bundle), [`src/modules/helpers.js`](https://github.com/waggylabs/yumekit/blob/main/src/modules/helpers.js) (Helpers), [`.storybook/main.js`](https://github.com/waggylabs/yumekit/blob/main/.storybook/main.js) (Storybook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_src_index_js["index<br/>ESM entry<br/>[index.js]"]
  node_src_index_iife_js["IIFE bundle<br/>browser entry<br/>[index.iife.js]"]
  node_src_react_d_ts["React types<br/>type defs<br/>[react.d.ts]"]
end

subgraph group_components["Components"]
  node_y_button["Button<br/>control component<br/>[y-button.js]"]
  node_y_input["Input<br/>form component<br/>[y-input.js]"]
  node_y_menu["Menu<br/>navigation component<br/>[y-menu.js]"]
  node_y_dialog["Dialog<br/>overlay component<br/>[y-dialog.js]"]
  node_y_popover["Popover<br/>overlay component<br/>[y-popover.js]"]
  node_y_tabs["Tabs<br/>navigation component<br/>[y-tabs.js]"]
  node_y_table["Table<br/>data display<br/>[y-table.js]"]
  node_y_tree["Tree<br/>hierarchy component<br/>[y-tree.js]"]
end

subgraph group_shared["Shared Runtime"]
  node_helpers["Helpers<br/>dom utils<br/>[helpers.js]"]
  node_floating["Floating<br/>overlay utils<br/>[floating.js]"]
  node_sanitizer["Sanitizer<br/>svg safety<br/>[svg-sanitizer.js]"]
end

subgraph group_theming["Theming"]
  node_y_theme["Theme<br/>[y-theme.js]"]
  node_tokens_manifest["Token manifest<br/>design tokens<br/>[$metadata.json]"]
  node_build_tokens["Build tokens<br/>token build<br/>[build-tokens.js]"]
  node_style_css["Styles<br/>shared css<br/>[style.css]"]
end

subgraph group_icons["Icons"]
  node_icon_registry["Icon registry<br/>icon catalog<br/>[registry.js]"]
  node_y_icon["Icon<br/>[y-icon.js]"]
end

subgraph group_tooling["Tooling"]
  node_storybook_main["Storybook<br/>docs config<br/>[main.js]"]
  node_rollup_config["Rollup<br/>packaging config<br/>[rollup.config.js]"]
  node_publish_workflow["Publish<br/>release workflow<br/>[npm-publish.yml]"]
end

node_src_index_js -->|"exports"| node_y_theme
node_src_index_js -->|"exports"| node_y_icon
node_src_index_js -->|"exports"| node_y_button
node_src_index_js -->|"exports"| node_y_input
node_src_index_js -->|"exports"| node_y_dialog
node_src_index_js -->|"exports"| node_y_menu
node_src_index_iife_js -->|"bundles"| node_src_index_js
node_src_index_iife_js -->|"includes"| node_icon_registry
node_src_index_iife_js -->|"packages"| node_style_css
node_tokens_manifest -->|"feeds"| node_build_tokens
node_build_tokens -->|"generates"| node_style_css
node_build_tokens -->|"generates"| node_y_theme
node_y_theme -->|"uses"| node_style_css
node_y_icon -->|"reads"| node_icon_registry
node_icon_registry -->|"sanitizes"| node_sanitizer
node_y_popover -->|"uses"| node_floating
node_y_dialog -->|"uses"| node_floating
node_y_menu -->|"uses"| node_helpers
node_y_tabs -->|"uses"| node_helpers
node_y_tree -->|"uses"| node_helpers
node_y_table -->|"uses"| node_helpers
node_storybook_main -->|"documents"| node_y_button
node_storybook_main -->|"documents"| node_y_dialog
node_storybook_main -->|"documents"| node_y_table
node_rollup_config -->|"packages"| node_src_index_js
node_rollup_config -->|"packages"| node_src_index_iife_js
node_publish_workflow -->|"publishes"| node_rollup_config

click node_src_index_js "https://github.com/waggylabs/yumekit/blob/main/src/index.js"
click node_src_index_iife_js "https://github.com/waggylabs/yumekit/blob/main/src/index.iife.js"
click node_src_react_d_ts "https://github.com/waggylabs/yumekit/blob/main/src/react.d.ts"
click node_y_theme "https://github.com/waggylabs/yumekit/blob/main/src/components/y-theme/y-theme.js"
click node_tokens_manifest "https://github.com/waggylabs/yumekit/blob/main/tokens/$metadata.json"
click node_build_tokens "https://github.com/waggylabs/yumekit/blob/main/scripts/build-tokens.js"
click node_style_css "https://github.com/waggylabs/yumekit/blob/main/styles/style.css"
click node_icon_registry "https://github.com/waggylabs/yumekit/blob/main/src/icons/registry.js"
click node_y_icon "https://github.com/waggylabs/yumekit/blob/main/src/components/y-icon/y-icon.js"
click node_helpers "https://github.com/waggylabs/yumekit/blob/main/src/modules/helpers.js"
click node_floating "https://github.com/waggylabs/yumekit/blob/main/src/modules/floating.js"
click node_sanitizer "https://github.com/waggylabs/yumekit/blob/main/src/modules/svg-sanitizer.js"
click node_y_button "https://github.com/waggylabs/yumekit/blob/main/src/components/y-button/y-button.js"
click node_y_input "https://github.com/waggylabs/yumekit/blob/main/src/components/y-input/y-input.js"
click node_y_menu "https://github.com/waggylabs/yumekit/blob/main/src/components/y-menu/y-menu.js"
click node_y_dialog "https://github.com/waggylabs/yumekit/blob/main/src/components/y-dialog/y-dialog.js"
click node_y_popover "https://github.com/waggylabs/yumekit/blob/main/src/components/y-popover/y-popover.js"
click node_y_tabs "https://github.com/waggylabs/yumekit/blob/main/src/components/y-tabs/y-tabs.js"
click node_y_table "https://github.com/waggylabs/yumekit/blob/main/src/components/y-table/y-table.js"
click node_y_tree "https://github.com/waggylabs/yumekit/blob/main/src/components/y-tree/y-tree.js"
click node_storybook_main "https://github.com/waggylabs/yumekit/blob/main/.storybook/main.js"
click node_rollup_config "https://github.com/waggylabs/yumekit/blob/main/rollup.config.js"
click node_publish_workflow "https://github.com/waggylabs/yumekit/blob/main/.github/workflows/npm-publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index_js,node_src_index_iife_js,node_src_react_d_ts toneBlue
class node_y_button,node_y_input,node_y_menu,node_y_dialog,node_y_popover,node_y_tabs,node_y_table,node_y_tree toneAmber
class node_helpers,node_floating,node_sanitizer toneMint
class node_y_theme,node_tokens_manifest,node_build_tokens,node_style_css toneRose
class node_icon_registry,node_y_icon toneIndigo
class node_storybook_main,node_rollup_config,node_publish_workflow toneTeal
```

## Components

### Public API

Package entrypoints and type surface

- [index](https://github.com/waggylabs/yumekit/blob/main/src/index.js): ESM entry · Main module entry that registers and exports the library · `src/index.js`
- [IIFE bundle](https://github.com/waggylabs/yumekit/blob/main/src/index.iife.js): browser entry · Drop-in browser bundle for script-tag or CDN usage · `src/index.iife.js`
- [React types](https://github.com/waggylabs/yumekit/blob/main/src/react.d.ts): type defs · TypeScript/React integration surface · `src/react.d.ts`

### Components

Reusable custom elements grouped by role

- [Button](https://github.com/waggylabs/yumekit/blob/main/src/components/y-button/y-button.js): control component · Primary action control and foundation for grouped actions · `src/components/y-button/y-button.js`
- [Input](https://github.com/waggylabs/yumekit/blob/main/src/components/y-input/y-input.js): form component · Text entry and form field control · `src/components/y-input/y-input.js`
- [Menu](https://github.com/waggylabs/yumekit/blob/main/src/components/y-menu/y-menu.js): navigation component · Menu and selection surface for navigation or command lists · `src/components/y-menu/y-menu.js`
- [Dialog](https://github.com/waggylabs/yumekit/blob/main/src/components/y-dialog/y-dialog.js): overlay component · Modal surface built on shared positioning and interaction helpers · `src/components/y-dialog/y-dialog.js`
- [Popover](https://github.com/waggylabs/yumekit/blob/main/src/components/y-popover/y-popover.js): overlay component · Anchored transient panel for contextual content · `src/components/y-popover/y-popover.js`
- [Tabs](https://github.com/waggylabs/yumekit/blob/main/src/components/y-tabs/y-tabs.js): navigation component · Section switching and tabbed navigation · `src/components/y-tabs/y-tabs.js`
- [Table](https://github.com/waggylabs/yumekit/blob/main/src/components/y-table/y-table.js): data display · Structured tabular data presentation · `src/components/y-table/y-table.js`
- [Tree](https://github.com/waggylabs/yumekit/blob/main/src/components/y-tree/y-tree.js): hierarchy component · Nested hierarchical data browser · `src/components/y-tree/y-tree.js`

### Shared Runtime

Cross-cutting helpers used by multiple components

- [Helpers](https://github.com/waggylabs/yumekit/blob/main/src/modules/helpers.js): dom utils · Shared DOM and logic helpers used by many components · `src/modules/helpers.js`
- [Floating](https://github.com/waggylabs/yumekit/blob/main/src/modules/floating.js): overlay utils · Anchoring and positioning behavior for overlays and popups · `src/modules/floating.js`
- [Sanitizer](https://github.com/waggylabs/yumekit/blob/main/src/modules/svg-sanitizer.js): svg safety · Safe SVG and icon content handling · `src/modules/svg-sanitizer.js`

### Theming

Token source, generated styles, and runtime theme element

- [Theme](https://github.com/waggylabs/yumekit/blob/main/src/components/y-theme/y-theme.js): runtime theme · Applies design tokens and theme behavior at runtime · `src/components/y-theme/y-theme.js`
- [Token manifest](https://github.com/waggylabs/yumekit/blob/main/tokens/$metadata.json): design tokens · Token metadata and theme catalog source · `tokens/$metadata.json`
- [Build tokens](https://github.com/waggylabs/yumekit/blob/main/scripts/build-tokens.js): token build · Converts token source data into CSS and consumable artifacts · `scripts/build-tokens.js`
- [Styles](https://github.com/waggylabs/yumekit/blob/main/styles/style.css): shared css · Shared stylesheet layer used across components · `styles/style.css`

### Icons

Registry-backed icon catalog and consumer

- [Icon registry](https://github.com/waggylabs/yumekit/blob/main/src/icons/registry.js): icon catalog · Central registry and generated icon collections · `src/icons/registry.js`
- [Icon](https://github.com/waggylabs/yumekit/blob/main/src/components/y-icon/y-icon.js): icon component · Component consumer of the shared icon registry · `src/components/y-icon/y-icon.js`

### Tooling

Build, docs, and release automation

- [Storybook](https://github.com/waggylabs/yumekit/blob/main/.storybook/main.js): docs config · Visual development and component documentation configuration · `.storybook/main.js`
- [Rollup](https://github.com/waggylabs/yumekit/blob/main/rollup.config.js): packaging config · Bundling configuration for distributable artifacts · `rollup.config.js`
- [Publish](https://github.com/waggylabs/yumekit/blob/main/.github/workflows/npm-publish.yml): release workflow · GitHub Actions pipeline for npm publication · `.github/workflows/npm-publish.yml`

## Connections

- index → Theme: exports · Registers the runtime theme entry
- index → Icon: exports · Exposes the icon component as part of the package API
- index → Button: exports · Registers core UI components for modular imports
- index → Input: exports · Registers core UI components for modular imports
- index → Dialog: exports · Registers overlay components
- index → Menu: exports · Registers navigation and menu components
- IIFE bundle → index: bundles · Browser bundle wraps the modular ESM surface
- IIFE bundle → Icon registry: includes · Ships the full icon catalog with the drop-in bundle
- IIFE bundle → Styles: packages · Includes shared styles for browser consumption
- Token manifest → Build tokens: feeds · Token source data is converted by the build script
- Build tokens → Styles: generates · Build step emits the shared CSS layer
- Build tokens → Theme: generates · Build step supports runtime theme artifacts
- Theme → Styles: uses · Theme element applies shared styling and variables
- Icon → Icon registry: reads · Icon component resolves glyphs from the shared registry
- Icon registry → Sanitizer: sanitizes · Registry pipeline relies on SVG safety helpers
- Popover → Floating: uses · Anchored overlay behavior depends on floating utilities
- Dialog → Floating: uses · Modal positioning and overlay behavior depend on floating utilities
- Menu → Helpers: uses · Shared DOM and state helpers support menu behavior
- Tabs → Helpers: uses · Shared DOM and state helpers support tab coordination
- Tree → Helpers: uses · Hierarchy handling reuses common logic utilities
- Table → Helpers: uses · Data-grid style behavior shares common utilities
- Storybook → Button: documents · Storybook captures the visual contract for components
- Storybook → Dialog: documents · Storybook captures the visual contract for components
- Storybook → Table: documents · Storybook captures the visual contract for components
- Rollup → index: packages · Bundling consumes the package entry surface
- Rollup → IIFE bundle: packages · Packaging emits browser-friendly artifacts
- Publish → Rollup: publishes · Release workflow depends on bundled build outputs