UMG Web Components Library README

Welcome to the UMG Web Components library! This library provides a collection of UX frontend components designed to be fast, reusable, and highly customisable for any project, without relying on proprietary technologies or frameworks. These components leverage standard Web APIs and are compatible with all modern browsers.

Learn More about Web Components

To deepen your understanding of web components, their key concepts, and the specific web APIs we employ, we recommend reading the MDN guide on Web Components.

Local Development Environment

Installation

1. Install Node.js v20.*.* globally using one of the following methods:

• Mac: NVM
• Windows: NVM for Windows
• Direct download: Node.js

2. Install PNPM globally using one of the following methods:

• Mac: brew install pnpm
• Windows PowerShell: Run the command iwr https://get.pnpm.io/install.ps1 -useb | iex

For more details, check the: PNPM documentation

1. Clone the project repository using this command:

   git clone [email protected]:Push-Entertainment/umg-web-components.git

2. Initialise the project by running the following command in your terminal within the project's root directory:

   pnpm install

Build scripts

We've provided the following build scripts to streamline the development process:

Core UMG components library:

• Develop main library: pnpm core:serve
• Build main library: pnpm core:build
• Build main library docs: pnpm core:build:docs

Shopify application:

• Develop main library: pnpm shopify:serve
• Build main library: pnpm shopify:build
• Build main library docs: pnpm shopify:build:docs

Lit - Lightning-Fast Components

Our library is built using Lit, a framework that simplifies component development without sacrificing performance or relying on non-standard frameworks. Lit builds on web component standards, is lightweight, and reduces boilerplate code. You can find Lit 2's documentation here.

To save time, minimise errors, and future-proof your code, we've written this library in TypeScript and utilise Lit's decorator methods, which TypeScript transpiles into browser-compatible JavaScript.

IDE

This project has been optimised for development in VSCode with the following extensions:

1. Install the following mandatory VSCode extensions:
   1. eslint
   2. lit-plugin
   3. lit-html
   4. MDX

Storybook Integration for Component Previews and Documentation

We've seamlessly integrated Storybook into our component library to provide you with a powerful playground tool with component previews and comprehensive documentation. Storybook serves as a valuable resource for both developers and designers, offering a visual representation of each component's behavior and appearance in different scenarios.

• Exploring Components in Storybook With Storybook, you can easily navigate and explore our components:

• Preview Components: View live, interactive previews of each component to understand how they look and behave in various situations.

• Component Variations: Explore different variations and configurations of each component, helping you tailor them to your specific project requirements.

• Interactive Documentation: Access detailed documentation and usage examples for each component, making it easier to implement them effectively in your project.

The Storybook application can be loaded into a browser by running pnpm dev-storybook in node_modules/@pushengineering/umg-web-components.

Importing components

Our components are written as ES6 modules for seamless integration into your project without the need for transpilation through tools like Webpack or Babel. You can still use pre-processors like Vite, Webpack, or Roll-up for tree shaking and minification while preserving ES modules.

To initialise a web component and render it in your HTML and the DOM, simply import the component script within your page's entry scripts or as a script tag directly inside your page.

For example, to import the slider web component and its internal component dependencies, add the following to your application script or as a script tag in your page:

import '@pushengineering/umg-web-components/slider'

Or as a raw module script tag:

<script async type="module" src="path-to-component-modules/slider.js">

Theme Styling

Design Tokens

Our web components are designed on top of a design system that uses custom CSS variables also known as design tokens. These design tokens are mapped with default values within the components and can be changed from within the application to provide the theme for your project in a cascading, controlled manner, ensuring consistent design and behavior throughout the application.

Leveraging Design Tokens

To make use of these design tokens, simply customise their values to align with your design system's specifications. You can override the default values assigned to the tokens, tailoring them to your project's exact requirements.

By integrating our components with your design tokens, you'll be able to achieve a harmonious blend of visual consistency and user experience excellence in your application, while also benefiting from the flexibility to adapt our components to your unique brand identity.

For a complete list of available tokens please see the Design Tokens Storybook documentation page and the documentation pages supplied for each component.

External Styles

There may be cases where design tokens are unable to achieve all aspects of a theme design. In this case it is possible to apply styles to shadowroot elements directly using shadowroot pseudo selectors and by understanding the following:

• Elements rendered to the Light DOM are targetable as noraml using standard CSS selectors.

• Elements within shadowroots can be targeted using the ::part() pseudo selector referencing the element's part name if provided e.g., ::part(button).

• To select specific instances of a common shadowroot element, scope the part selector to a unique parent ID or class e.g., #section-id .featured-gallery::part(button).

• Shadowroot elements without a part name are not accessible to external styles. If you see a case for adding a part name where currently one does not exist, please post a GitHub issue referencing the specific component and element(s) with a brief description and example of the design that could not be achieved using the current toolset.