Mercury Design System

Apply Mercury Design System styling to UIs built with Chameleon web components. This skill covers Mercury-specific usage: ch-theme, getBundles, CSS bundles, CSS classes, design tokens, typography, color, spacing, and design patterns. Use the Chameleon skill to build the component tree; then use this skill to add Mercury styling

Workflow

CRITICAL — Chameleon skill required: Before writing any component code, you MUST invoke the chameleon-controls-library skill (via the Skill tool). Mercury only handles styling (CSS bundles, classes, tokens) — component APIs (properties, events, slots, model shapes) are documented exclusively in the Chameleon skill. Skipping it leads to wrong prop names, missing events, and broken component wiring

Choose the path that matches the user's request:

Path A: Implement from a Figma design (image or frame provided)

1. Detect the theme variant (FIRST) — Look at the primary action color in the design (buttons, links, focus indicators). Blue → Mercury (default). Green → Globant (theme: "globant"). See How to detect the variant. This determines the `theme` value in `vite-plugin-mercury` and must be resolved before writing any code
2. Set up the project with the correct theme — If scaffolding a new project or the project doesn't exist yet, configure vite-plugin-mercury with the detected theme: mercury({ theme: "mercury" }) or mercury({ theme: "globant" }). If the project already exists, verify the theme in vite.config.ts matches the design
3. Analyze the design — Identify components, layout structure, colors, typography, spacing, and interaction states
4. Map Figma values to Mercury tokens — Use Figma token mapping to translate Figma variables, hex values, and font specs into Mercury tokens and classes. Critical: Figma font-weights are +100 higher than real — always subtract 100

Then continue with Common steps

Path B: Vibe code an unknown UI (no design provided)

1. Understand intent — Clarify the UI's purpose and key interactions
2. Determine the theme — Ask the user if not specified. Default to Mercury. Configure vite-plugin-mercury with the correct theme value before writing any component code
3. Choose design patterns — Consult Design patterns for Mercury-idiomatic layouts, forms, buttons, and typography hierarchy
4. Apply design foundations — Use Mercury typography, color, and spacing systems

Then continue with Common steps

Common steps (both paths)

1. Load the Chameleon skill — Invoke Skill: chameleon-controls-library. Then use its component references to select the right ch-* components and read their exact APIs (props, events, slots, models) for every component you plan to use
2. Build UI with Chameleon — Assemble the component tree using the APIs loaded in step 5. Use native <button> and <a> for buttons and links
3. Apply Mercury styling — Import getBundles, load required bundles, place <ch-theme>, apply CSS classes and design tokens
4. Use Mercury icons — For any icon in the UI, use getIconPath or getIconPathExpanded from @genexus/mercury/assets-manager.js. Never hardcode icon paths. See Mercury Icons for the full catalog, colorType reference, and usage examples
5. Validate package versions — If you installed or updated packages in this session, check that all installed versions are mutually compatible. Read Compatibility table and run npm ls @genexus/mercury @genexus/chameleon-controls-library @genexus/vite-plugin-mercury @genexus/mercury-cli 2>/dev/null. Always prefer the latest versions
6. Validate — Run through the Do's and Don'ts checklist below

Mercury Fundamentals

These rules are non-negotiable. Violating them produces broken or inconsistent UIs

• Mercury styling = CSS bundles + classes on Chameleon components. Mercury does not use JS styling or CSS-in-JS — it's pure CSS loaded via getBundles and applied via class names
• Bundle name ≠ CSS class. The bundle identifier (e.g., "components/edit") does not match the CSS class (e.g., input). Always check the bundle's .md doc for exact class names
• `ch-theme` is always a sibling, never a wrapper. It has hidden — any children inside it disappear
• NEVER invent CSS when Mercury provides a class or token. Mercury classes handle hover, focus, disabled, dark/light mode automatically
• Mercury's `base/base` already styles `body` — it sets background-color, color, font-family, font-size, line-height, font-weight, display: grid, min-block-size: 100dvh, and margin: 0. Never duplicate these in custom CSS. See Body and root container styles for the full list
• ALWAYS use semantic design tokens (--color-text-*, --color-accent-*, etc.), never hardcoded hex values. Never use primitive tokens (--color-azure-*, --color-neutral-*, --color-avocado-*, --size-*, etc.) — these are internal to the design system. If a Figma design or user input references a primitive token, translate it to the corresponding semantic token
• NEVER write CSS fallback values when using tokens. Always write var(--token-name) — never var(--token-name, fallback). Fallbacks hide missing tokens, bypass dark/light mode switching, and break design system customization. If a token is correct, it will always resolve at runtime
• Match token category to CSS property: color: → --color-text-*, background: → --color-accent-*, border: → --color-border-*, icon color → --color-icon-*. Never cross categories

Do's and Don'ts

This section is a mandatory checklist. Verify every item before delivering code

MUST DO

• Detect and configure the correct theme before writing any code. Blue accents → mercury({ theme: "mercury" }). Green accents → mercury({ theme: "globant" }). The theme determines which base/base CSS is injected (color palette, tokens). Getting this wrong means all colors will be incorrect
• Load ALL required bundles for every component used (consult Component → bundles table)
• Apply Mercury CSS classes on every Chameleon component that has a corresponding bundle
• Use design tokens (--color-*, typography classes) — never raw hex/px values
• Use form utilities (field, field-block, field-inline, field-group, label, input) for every form (bundle: utils/form)
• Use button classes (button-primary, button-secondary, button-tertiary) for ALL button/link variants (bundle: components/button)
• Use Mercury spacing tokens (--spacing-padding-*, --spacing-gap-*) for all spacing — these are the primary way to apply spacing. Padding tokens work for margin and calc() too. Fall back to px from the 4pt grid only when no token matches. Never use em/rem. These tokens are global — no bundle import required
• Use --border-radius-* tokens for all border-radius — never hardcode px values. Map the Figma radius value to the closest token. These tokens are also global. See the Border radius tokens table below
• Use typography classes (heading-1..heading-6, subtitle-*, body-*, caption-*) instead of manual font styling (bundle: utils/typography). Typography classes already set font-size, line-height, font-weight, and letter-spacing — never set these properties manually when a typography class applies
• Use font-size tokens (--font-size-body-*, --font-size-header-*, --font-size-subtitle-*, --font-size-caption-*) and line-height tokens (--line-height-tight, --line-height-regular, --line-height-relaxed, --line-height-loose) when a typography class doesn't fit. Never hardcode px values for font-size or numeric values for line-height
• Set dark or light class on <html> for theme mode

MUST NOT DO

• Never wrap children inside <ch-theme> — they will be hidden
• Never write custom CSS for buttons, links, or elements Mercury already styles
• Never substitute native <input>, <select>, <checkbox> when Chameleon components exist (ch-edit, ch-combo-box-render, ch-checkbox)
• Never use hex color values when a Mercury token exists
• Never use --color-text-* tokens for borders, or --color-border-* for backgrounds — respect token categories
• Never skip loading a bundle — every component needs its CSS
• Never trust Figma font-weight at face value — always subtract 100 (Figma Regular 400 → Mercury Light 300, Figma SemiBold 600 → Mercury Medium 500)
• Never use heading-h1..heading-h6 — the real classes are heading-1..heading-6
• Never use more than one primary button per page/view
• Never write custom hover/focus/disabled styles — Mercury handles all interaction states
• Never use em or rem units — Mercury provides semantic tokens for all sizing/spacing needs. Hardcoded em/rem values break when the design system scale changes or when users customize tokens
• Never use primitive tokens (--color-azure-600, --color-neutral-1400, --size-16, etc.) in code — always translate to their semantic equivalent (--color-accent-primary-default, --color-text-neutral-default, --icon-m, etc.). Primitives are internal to the design system and may change between versions or variants
• Never write CSS fallback values on tokens — var(--spacing-gap-m) ✓, var(--spacing-gap-m, 12px) ✗. Fallbacks hide missing tokens, bypass dark/light mode switching, and break design system customization
• Never pass base/base, base/icons, or resets/box-sizing to getBundles — these are injected automatically by vite-plugin-mercury
• Never import utils/spacing just to use spacing tokens (--spacing-padding-*, --spacing-gap-*) — those tokens are global. Only import utils/spacing when you need its CSS classes (spacing-body, spacing-body-block, etc.), which apply component-level padding driven by custom properties set on a parent container
• Never hardcode border-radius in px — always use --border-radius-* tokens
• Never style body with background-color, color, font-family, font-size, line-height, font-weight, margin, min-height/min-block-size, or display — Mercury's base/base already sets all of these. Writing them again overrides or duplicates the design system
• Never hardcode font-size (e.g. 18px) or line-height (e.g. 1.2) — always use a typography class or the corresponding tokens (--font-size-*, --line-height-*)
• Never set min-height: 100vh or min-block-size on a root wrapper (#root, #app, etc.) — Mercury's body already provides min-block-size: 100dvh with display: grid. Instead, apply display: contents on the wrapper so it becomes transparent to the grid layout

ch-theme and getBundles

• `getBundles(bundleNames, basePath)` — Returns the theme model for those CSS bundles. See full signature and types in references/api/bundles.md.
• bundleNames accepts only `MercuryBundleFull` identifiers — component, scope, and util bundles (e.g. ["components/button", "components/edit", "utils/form"]).
• `base/base`, `base/icons`, and `resets/box-sizing` must NOT be passed to `getBundles`. These are injected automatically by vite-plugin-mercury (or the Mercury CLI). Passing them manually causes duplicate injection and broken styles.
• basePath is the public path where Mercury CSS files are served (e.g. /assets/css/).

• `ch-theme` — Chameleon component that injects CSS from the model. It always has the `hidden` attribute — never place child elements inside it. Place it as a sibling before the UI tree

  import { getBundles } from "@genexus/mercury/bundles.js";

  const bundles = getBundles(
    ["components/button", "components/edit", "utils/form"],
    "/assets/css/"
  );

Correct:

  <ch-theme model="{bundles}"></ch-theme>
  <form class="field-group">
    <div class="field field-block">
      <label class="label" for="name-input">Name</label>
      <ch-edit class="input" id="name-input" type="text"></ch-edit>
    </div>
    <button class="button-primary" type="submit">Save</button>
  </form>

Wrong — never wrap children inside ch-theme:

  <!-- WRONG -->
  <ch-theme model="{bundles}"> <div>…</div> </ch-theme>

CSS class ≠ bundle name. Example: ch-edit uses bundle "components/edit" but the CSS class is input, not edit. Always check the bundle's .md doc. See Bundles index

Which bundles to request

Use the [Component → bundles table](references/component-bundles-table.md) to find which bundles apply to each Chameleon component or native element. Request every bundle listed for the components in your view

Mercury has 39 bundles across 6 categories:

For the full list: [Bundles index](references/bundles-index.md)

Buttons and links

Mercury's components/button bundle provides all necessary classes. Never write custom CSS for buttons or <a>

Important: Only one primary button per page or view

<button class="button-primary button-icon-and-text">
  <img src="{icon}" alt="" width="16" height="16" />
  Save
</button>
<button class="button-tertiary">Cancel</button>

Chameleon components — never native substitutes

When a Chameleon component exists, always use it:

Dark / light mode

Set the class on <html> to dark or light. Mercury handles all color adjustments automatically

Themes: mercury and globant

Two theme variants: mercury (default) and globant

• Base: base/base.css (mercury) or base/base-globant.css (globant)
• Scope: scope/theme-mercury.css and scope/theme-globant.css — only needed for multi-theme apps
• How to choose: Vite plugin: theme: "mercury" | "globant". CLI: --globant flag

How to detect the variant from a Figma design or image

Use multiple signals to determine the theme — do not rely on a single check. Evaluate them in order of reliability:

#### Signal 1: Primary action color (strongest signal)

Look at buttons, links, focus rings, and accent elements:

If you see any blue in the range #0072f8–#5ba7ff on interactive elements → Mercury. If you see green/yellow-green in the range #749519–#c3e01a → Globant

#### Signal 2: Surface and elevation colors (confirms the theme)

The elevation backgrounds differ between variants. Compare any card, panel, or page background against these tables:

Light mode surfaces:

Dark mode surfaces:

Key pattern: Mercury surfaces have a blue tint (lilac-based in light, blue-gray in dark). Globant surfaces are pure neutral grays. If the backgrounds look warm/neutral gray → Globant. If they have a cool/blue undertone → Mercury

#### Signal 3: Neutral palette tint (secondary confirmation)

Mercury uses blue-tinted grays (#2D3A48, #9DA9B6). Globant uses pure grays (#3B3B3B, #A9A9A9). Check text, borders, and secondary elements

#### Decision flow

1. Check primary action color → Blue or Green?
2. If unclear (e.g., no visible buttons/links), check surface/elevation backgrounds → Blue-tinted or pure gray?
3. If still ambiguous, check neutral grays → Blue-tinted or pure?
4. If all signals point the same way → use that theme. If signals conflict, ask the user

See Themes and variants

Body and root container styles

Mercury's base/base bundle applies the following styles to body — never duplicate them:

body {
  font-family: var(--font-family-body); /* Inter typeface */
  font-size: var(--font-size-body-m); /* 14px */
  line-height: round(1em * var(--line-height-relaxed), 1px); /* ~1.4 */
  font-weight: var(--font-style-regular); /* 300 */
  display: grid;
  grid-template-rows: 1fr;
  min-block-size: 100dvh;
  margin: 0;
  background-color: var(--color-accent-surface-surface);
  color: var(--color-text-neutral-default);
}

Because body uses display: grid + min-block-size: 100dvh, children automatically stretch to fill the viewport. If your framework inserts a wrapper element (e.g. #root, #app), do not re-declare min-height: 100vh or min-block-size — apply display: contents instead so it becomes transparent to the body grid:

/* Correct — wrapper is invisible to grid */
#root {
  display: contents;
}

/* WRONG — duplicates what body already provides */
#root {
  min-height: 100vh;
  background-color: var(--color-accent-surface-elevation-0);
  color: var(--color-text-neutral-default);
  font-family: var(--font-family-body);
}

Border radius tokens

Mercury provides semantic --border-radius-* tokens defined globally in base/base — no bundle import required. Always use them instead of hardcoded px values. Map the Figma border-radius value to the closest token:

/* Correct */
.card {
  border-radius: var(--border-radius-m);
} /* 8px from Figma → --border-radius-m */
.badge {
  border-radius: var(--border-radius-s);
} /* 4px from Figma → --border-radius-s */

/* WRONG */
.card {
  border-radius: 8px;
}
.badge {
  border-radius: 4px;
}

Focus ring pattern

Mercury does not have a --border-radius-focus token — focus rings use outline, not border, so border-radius does not apply to them

Two global tokens cover the entire focus ring:

Standard pattern — use :focus-visible for interactive elements (buttons, links, custom controls), :focus for native form inputs:

/* Custom interactive element */
.my-control:focus-visible {
  outline: var(--border-width-focus) solid var(--color-border-primary-focused);
  outline-offset: calc(var(--border-width-focus) * -1);
}

/* Native form input */
.my-input:focus {
  outline: var(--border-width-focus) solid var(--color-border-primary-focused);
  outline-offset: calc(var(--border-width-focus) * -1);
}

*Why `outline-offset: calc(var(--border-width-focus) -1)?** A negative offset equal to the outline thickness pulls the ring inward so it sits inside the element's border box. This prevents it from being clipped by ancestors with overflow: hidden`, scrollable containers, screen edges, or any other clipping context — a common failure mode with positive or zero offsets

Never write custom hover/focus/disabled styles on Mercury components — their bundles already handle all states via :focus-visible with these same tokens. Only apply this pattern to custom components you build yourself

Installation

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

Framework guides: Installation index — React (Vite), Angular, Next.js (Turbopack), Stencil

After installing, always verify that the installed versions are mutually compatible. See Compatibility table — it covers Mercury ↔ Chameleon, Mercury ↔ vite-plugin-mercury, and Mercury ↔ Mercury CLI. Always prefer the latest versions of all packages

References

• [Mercury Icons](references/icons/README.md) — Complete icon catalog (17 categories, 500+ icons), getIconPath/getIconPathExpanded usage, colorType reference
• [Design foundations](references/design-foundations/) — Typography, color, spacing, icon sizing/color tokens, Figma token mapping, design patterns
• Component → bundles table — which bundles per component
• Bundles index — all bundle docs and CSS
• Themes and variants — mercury vs globant, dark/light
• API reference — JS modules
• Installation by framework — setup guides