Mercury Design System

Mercury Design System is a robust and scalable solution designed to improve product development. It's implemented over Chameleon a library of white-label, highly-customizable and reusable web components, which implements all necessary components for the Mercury DS.

Chameleon works on every framework since it's a library of web components (the standard for creating components in the web) and provides the following features:

• It's build with accessibility in mind.
• Tiny bundle size.
• Blazing fast performance.
• Full RTL and internationalization support.
• Open source.

This repository provides the following assets:

• Individual CSS modules to style each Chameleon component.
• Pre-packaged font assets (Inter family).
• Consistent icon set for UI/UX.

👟 Getting Started with Mercury

Mercury provides clear installation steps for the most popular frameworks and libraries, including React, Angular, and Stencil, making it easy to get started no matter your setup. First, install Chameleon and Mercury, and then click on the following links to view the installation steps for your specific framework:

npm

npm i --save @genexus/chameleon-controls-library @genexus/mercury

yarn

yarn add @genexus/chameleon-controls-library @genexus/mercury

Then follow the installation guide for your selected framework/library:

•   Installation for Angular
•   Installation for React (with Vite)
•   Installation for Next.js
•   Installation for Stencil

[NOTE] The following information is best read after completing any of the installation guides above.

🎨 One CSS module per Component

The CSS in Mercury's implementation is divided into separate modules of CSS (also called bundles). Each CSS module contains the specific styles needed to properly render an individual component or control. This approach ensures that each component has its required styling isolated and encapsulated.

Why one CSS per component?

Loading one CSS file per component helps limit the amount of CSS included, leading to faster page loads and better performance. Instead of forcing the browser to process a massive, monolithic stylesheet with styles for components that may not even be used, each page or feature can load only the styles it actually requires. This results in leaner CSS, faster rendering, and more maintainable code in the long run.

How do I import a CSS module?

To load the necessary CSS bundles, import the getBundles utility from Mercury. Use it to specify the bundles you need and assign the result to a variable. This variable is then passed to the <ch-theme> component, which handles applying the styles automatically.

The following snippet provides a quick, partial example using Angular, meant only to give you a sense of how it works. The approach is analogous across other frameworks. For complete installation and usage details, be sure to consult the full README for your specific framework by searching for import { getBundles }.

// ...non-essential imports for this example omitted
import { getBundles } from "@genexus/mercury/bundles.js";

@Component({
  selector: "my-own-component",
  // ...non-essential code for this example omitted
  template: `<ch-theme [model]="bundles"></ch-theme>
    <div class="field field-block">
      <label class="label" for="name">Phone</label>
      <ch-edit class="input" id="phone" />
    </div>
    <button class="button-primary" type="button">Save Changes</button>`
})
export class CustomDialogComponent {
  bundles = getBundles(
    ["components/button", "components/edit", "utils/form"],
    "{{ CSS bundles final path }}"
  );
}

CSS bundles reference:

The reference below documents all Mercury CSS bundles. The “Bundle name” is the value you pass to getBundles to load the corresponding CSS module. For a clearer understanding, check out any component example on the Mercury showcase.

| Bundle name | Content | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | chameleon/scrollbar | Styles for the scrollbar of the components | | components/accordion | Styles for the accordion component | | components/button | Styles for the button button | | components/chat | Styles for the chat component | | components/checkbox | Styles for the checkbox component | | components/code | Styles for the code block component | | components/combo-box | Styles for the combo-box component | | components/dialog | Styles for the dialog component | | components/dropdown | Styles for the dropdown component | | components/edit | Styles for the input and search components | | components/flexible-layout | Styles for the flexible layout component | | components/icon | Styles for the icon component | | components/layout-splitter | Styles for the layout splitter component | | components/list-box | Styles for the list box component | | components/markdown-viewer | Styles for the markdown viewer component | | components/navigation-list | Styles for the navigation list component | | components/pills | Styles for the pills component | | components/radio-group | Styles for the radio group component | | components/segmented-control | Styles for the segmented control component | | components/sidebar | Styles for the sidebar component | | components/slider | Styles for the slider component | | components/switch | Styles for the switch component | | components/tab | Styles for the tab component | | components/tabular-grid | Styles for the tabular grid and property grid components | | components/ticket-list | Styles for the ticket list component | | components/tooltip | Styles for the tooltip component | | components/tree-view | Styles for the tree view component | | components/widget | Styles for the widget component | | utils/elevation | Styles to apply elevations on any component | | utils/form | Styles for the label component and to build layouts for forms | | utils/layout | Styles to build common layouts | | utils/spacing | Styles to apply spacing in different components that are used as containers | | utils/typography | Styles for using the different typographies |

⚠️ Common issues

The following are some common issues and their solutions you might encounter during installation:

# Missing Type Declarations in External Dependencies

Error: ../../node_modules/livekit-client/dist/src/room/PCTransport.d.ts:1:30
error TS7016: Could not find a declaration file for module 'events'.
/genexus/mercury-monorepo/node_modules/events/events.js' implicitly has an 'any' type.

Add skipLibCheck: true to your tsconfig.json

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

# Missing Export Error: 'OverlayEventDetail' Not Found in interfaces.ts (React only)

Uncaught SyntaxError: The requested module '/src/chameleon-components/react-component-lib/interfaces.ts?t=1752010434529' does not provide an export named 'OverlayEventDetail' (at createOverlayComponent.tsx:4:10)

Update the Stencil-generated files so that the types are imported with type.

before

import { OverlayEventDetail } from "./interfaces";

after

import { type OverlayEventDetail } from "./interfaces";