Customization

Cloud Components (ECC) provides a flexible and powerful customization system that allows you to adapt components to match your design requirements. The system is built on CSS custom properties (tokens), inspired by the excellent design patterns from shadcn/ui (opens in a new tab).

This page focuses on the global design tokens that can be used with any ECC package, be it a service package (like WES, TRS, etc.) or the design utility package.

CSS Custom Properties (Design Tokens)

All ECC components use CSS custom properties with the --ecc- prefix. You can override these in your application's CSS to customize the appearance of all components.

Available Tokens

Here are all the available design tokens you can customize:

Color Tokens

Card Tokens

Chart Colors

Layout Tokens

Typography Tokens

Sidebar Tokens

Customizing Design Tokens

To customize the appearance of ECC components, override the CSS custom properties in your application's CSS:

Basic Token Customization

:root {
  /* Change the primary color to blue */
  --ecc-primary: oklch(0.6 0.25 250);
  --ecc-primary-foreground: oklch(1 0 0);
  
  /* Customize border radius */
  --ecc-radius: 1rem;
  
  /* Update accent colors */
  --ecc-accent: oklch(0.95 0.02 250);
  --ecc-accent-foreground: oklch(0.2 0 250);
}

Theme-Specific Customization

You can also provide different values for dark mode:

:root {
  /* Light theme */
  --ecc-primary: oklch(0.4 0.25 250);
  --ecc-background: oklch(1 0 0);
}
 
.dark {
  /* Dark theme */
  --ecc-primary: oklch(0.7 0.25 250);
  --ecc-background: oklch(0.1 0 0);
}

Typography

Components inherit the page's font unless you set the typography tokens:

:root {
  --ecc-font-sans: "Inter", system-ui, sans-serif;
  --ecc-font-mono: "JetBrains Mono", monospace;
}

Dark Mode

Components switch to the dark defaults listed above when either:

• the component itself has a dark attribute (<ecc-client-ga4gh-wes-runs dark>), or
• an ancestor element has a dark attribute or a dark class (e.g. <html class="dark">).

Dark defaults are passed on to components nested inside other components, so setting dark on the outermost component is enough.

Any --ecc-* token you set takes precedence over the dark defaults.

Surface Painting

By default, components are transparent: they show the page's background and inherit its text color, which suits embedding them into an existing layout. Add the surface attribute to have a component paint its own background and text color from --ecc-background and --ecc-foreground. The surface is inset by --ecc-surface-padding (default 1rem) and its corners are rounded by --ecc-radius:

<ecc-client-ga4gh-wes-runs surface dark></ecc-client-ga4gh-wes-runs>

This lets a component use a dark (or otherwise different) theme regardless of the page it is placed on. Set surface on top-level, block-level components only, such as the service components (ecc-client-*); components nested inside them inherit the painted surface. Inline design components (e.g. badges or buttons) are not laid out as a padded box.

Code Editor

The code editor used for parameters, logs and file contents follows the same tokens: background and text use --ecc-background and --ecc-foreground, the gutter uses --ecc-muted and --ecc-muted-foreground, keys and keywords use --ecc-primary, strings are derived from --ecc-chart-2, numbers and other constants from --ecc-chart-1, invalid code uses --ecc-destructive, selections use --ecc-ring, and the font is --ecc-font-mono.

Credits

This customization system is inspired by the excellent work of shadcn/ui (opens in a new tab), which pioneered many of the patterns we use for component architecture and theming. We've adapted their approach to work seamlessly with Web Components and the ECC ecosystem.