Skip to main content
Version: 8.6

Custom styling

You can customize the Tasklist user interface (UI) to visually align it with your organization's brand identity. You can adjust the appearance of various UI elements, such as backgrounds, layers, controls, buttons, and text.

The Tasklist UI uses the Carbon Design System, the comprehensive open-source design system created by IBM to ensure consistency, efficiency, and scalability across projects, particularly developers who need to create or maintain UI components.

Customize the Tasklist user interface

To customize the user interface, you can override specific Carbon Design System design tokens with your own CSS values. These tokens control various aspects of the UI's appearance. For example, you can override the --cds-background token to change the Tasklist UI background color.

You can override these tokens in the custom.css file located in the distribution archive or within the Docker image at /usr/local/tasklist/config/custom.css.

A typical workflow to customize the Tasklist UI is as follows:

  1. Identify design tokens: Review your own visual identity guidelines and identify the design tokens you want to update. You will modify these tokens in the custom.css file.

  2. Override the tokens in custom.css: Add or modify token values in the custom.css file. The syntax for styling is plain CSS. For example, to change the background color use the following syntax, replacing the --cds-background token hex values with your own color:

    :root[data-carbon-theme='g10']{ /* Light theme customization */
    --cds-background: #FFFF00;
    }

    :root[data-carbon-theme='g100']{ /* Dark theme customization */
    --cds-background: #008000;
    }
  3. Test your custom styles: Test your custom styles in both light and dark modes to verify that they are applied correctly across all Tasklist UI components.

  4. Validate accessibility and visual contrast: Check that your custom styles maintain good visual contrast between elements. For example, verify that text is easily readable against backgrounds, buttons are distinguishable, and important elements such as links and icons stand out properly. Contrast is especially important for accessibility and readability in both light and dark modes.

  5. Iterate based on results: If necessary, refine your customizations based on the results of your testing. Adjust values in the custom.css file to ensure a consistent look and feel throughout the Tasklist UI.

note

If you do not add any custom CSS configuration in the custom.css file, the Tasklist UI defaults to its original visual identity.

Common design tokens

You can override the following commonly used design tokens to customize the Tasklist UI.

Design tokenDescription
--cds-backgroundDefault background color of the Tasklist UI.
--cds-background-brandFeature background color.
--cds-layer-01Color for primary layer surfaces like containers and cards.
--cds-layer-selected-01Selected color for layer-01.
--cds-text-primaryPrimary color for text elements.
--cds-text-secondarySecondary color for less prominent text and input labels.
--cds-link-primaryColor for primary links.
--cds-link-primary-hoverColor for primary links when hovered.
--cds-link-secondaryColor for secondary links.
--cds-link-inverseColor for links against dark backgrounds.
--cds-icon-primaryPrimary color for icons.
--cds-icon-secondarySecondary color for icons.
--cds-icon-interactiveColor for interactive icons.
--cds-button-primaryPrimary color for buttons.
--cds-button-primary-hoverHover state color for primary buttons.
--cds-button-primary-activeActive state color for primary buttons.
--cds-button-secondarySecondary color for buttons.
--cds-button-secondary-hoverHover state color for secondary buttons.
--cds-button-secondary-activeActive state color for secondary buttons.
--cds-button-tertiaryTertiary color for buttons.
--cds-button-tertiary-hoverHover state color for tertiary buttons.
--cds-button-tertiary-activeActive state color for tertiary buttons.
--cds-button-disabledColor for disabled buttons.
--cds-field-01Color for default input fields.
--cds-focusColor for elements in focus, such as borders and underlines.
--cds-border-interactiveColor for selected and active borders.
--cds-border-subtle-00Subtle borders paired with background.
--cds-border-subtle-01Subtle borders paired with $layer-01
--cds-border-subtle-selected-01Selected color for $border-subtle-01