waggylabs/yumekit

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.