Theme Properties

This article provides essential guidelines for customizing themes in GoodData. It explains how to format color values, apply border styles, and manage component appearance using theme configuration files.

General Rules

When creating themes, follow these general rules:

Colors

Use the following color coding formats:

• Hexadecimal without transparency: #ff0 or #ff00ff
• Hexadecimal with transparency: #ff06 or #ff00ff80
• RGB: rgb(120,120,120)
• RGBA: rgb(120,120,120,0.6)

Ensure background colors provide sufficient contrast for text readability.

Borders

Border radius and weight are defined in pixels by default. To use a different unit, explicitly include it in the value.

Example:

"border-radius": "2em"

Widget Borders

• The recommended maximum widget border radius is 30px.
• The recommended maximum widget border width is 4px.
• To hide widget borders, use a transparent color instead of setting borderWidth to 0.

Examples:

"borderColor": "#78787800"

or

"borderColor": "rgb(120,120,120,0)"

How Aliases Work

Some visual properties in the UI use aliases (such as primary, complementary.c3, etc.) instead of direct values. Aliases map to theme values if they are defined or fall back to default values if they are not. This allows flexible styling without hardcoding specific values, and consistent branding with fewer style definitions.

Not Everything Is Customizable

The base theme includes internal styles that cannot be directly modified. Only certain aliased styles are themeable.

Understanding the Complementary Palette

What Is It?

The complementary palette is a unique feature in GoodData themes. It defines 10 colors used throughout the UI, reducing the need to manually style individual elements.

Example:

"complementary": {
  "c0": "#121212",
  "c1": "#1E1E1E",
  ...
  "c9": "#FFFFFF"
}

What It Affects

Each color in the palette typically serves specific purposes:

These mappings are guidelines rather than strict rules.

How Priority Works

When multiple styling options are defined in a theme, GoodData resolves them based on priority. This ensures that more specific design choices override more general ones. The following order determines which value is ultimately applied:

1. Direct Property Overrides Properties explicitly defined for a specific element take the highest priority.

   • Example: If a widget has "backgroundColor": "#FFFFFF" defined directly in the theme, that value will be used, regardless of the complementary palette or base color settings.

2. Complementary Palette If a direct override is not defined, the system falls back to the complementary color palette (e.g., c0–c9) for styling.

   • Example: If backgroundColor is not set on a widget, but c0 is defined in the complementary palette, the widget will use c0.

3. Base Theme Defaults If neither a direct property nor a complementary color is specified, the system uses the default value from the base GoodData theme.

Example Scenario

Imagine you’re customizing a Headline (KPI) widget. Here’s how GoodData resolves what color to apply for the title text:

"dashboards": {
  "content": {
    "kpiWidget": {
      "title": {
        "color": "#FF0000"
      }
    }
  }
}

• The color #FF0000 (bright red) will be applied because it is defined directly.
• If this were missing, the system would look for a value like "c8" in the complementary palette.
• If neither are defined, the widget would fall back to the default GoodData UI color.

When to Use Complementary vs. Specific Overrides

Best Practice: Use the complementary palette to define the overall visual tone. Then override specific elements only when needed for contrast, readability, or branding.