Web apps

NPM Registry access

CDS packages are published in a private npm registry in Azure DevOps. To install them, you need access and must authenticate with the registry.

After these steps, you can install CDS packages from the CDS Azure Artifacts npm feed.

Quick start guide

Install with:

npm install @coop/cds-tokens @coop/cds-fonts @coop/cds-icons @coop/cds-components react-aria-components

Import global CSS files:

@import '@coop/cds-tokens/variables.light.css';
@import '@coop/cds-fonts/fonts.css';

Use the components and icons:

import { Button } from '@coop/cds-components';
import { CheckmarkIcon } from '@coop/cds-icons';

export function MyButton() {
    return (
        <Button theme="primary" icon={CheckmarkIcon}>
            Continue
        </Button>
    );
}

Detailed guide

This section explains the npm packages that form CDS and how to use them in your application.

Token package

The @coop/cds-tokens package provides CSS variables for design tokens, such as colour, spacing, and typography, helping your UI stay consistent with CDS.

Install with:

npm install @coop/cds-tokens

Then import the token stylesheet once in your app’s root global CSS file:

@import '@coop/cds-tokens/variables.light.css';

This loads the classic theme (light). CDS also supports multi-brand themes and dark mode; see Themes.

Fonts package

The @coop/cds-fonts package contains Coop font files and a CSS file that registers @font-face rules for CDS typography.

Install with:

npm install @coop/cds-fonts

Then import once in your app's root global CSS file:

@import '@coop/cds-fonts/fonts.css';

Components package

The @coop/cds-components package provides React UI components styled according to CDS design in Figma. The components are built using React Aria (react-aria-components) and require React 19.1.0 or later.

Install with:

npm install @coop/cds-components react-aria-components

Note: react-aria-components is a peer dependency of @coop/cds-components and will usually be installed automatically. Because CDS is built on React Aria, you can also use CDS components together with react-aria-components if needed for more advanced composition. In that case, it’s recommended to install react-aria-components directly in your project to avoid version mismatches.

Make sure to also install @coop/cds-tokens and @coop/cds-fonts alongside the components package so design tokens and fonts work correctly.

Example usage:

import { Button } from '@coop/cds-components';

export function MyButton() {
    return <Button theme="primary">Continue</Button>;
}

For full component examples and states, visit CDS Storybook.

Typography

For shared typography utility classes in your own CSS, import once in your app’s root global CSS file:

@import '@coop/cds-components/css/typography.css';

or use SCSS typography mixins:

@use '@coop/cds-components/scss/typography.scss' as *;

For a complete set of typography classes and mixins, visit CDS Storybook's Typography page.

Set up your app framework

After adding @coop/cds-components, follow the React Aria framework setup for your stack so providers, routing, and SSR stay consistent: React Aria — UI frameworks (for example Next.js or Remix).

Icons package

The @coop/cds-icons package provides SVG icons as React components, aligned with CDS Icons. Use them in React UI wherever icons are needed, such as buttons, lists, navigation, and empty states, often together with @coop/cds-components. Requires React 19.1.0 or later.

Install with:

npm install @coop/cds-icons

Many components that use icons accept an icon prop that expects a React component. You can use the named import from @coop/cds-icons to get the icon component.

import { Button } from '@coop/cds-components';
import { CheckmarkIcon } from '@coop/cds-icons';

export function SaveButton() {
    return (
        <Button theme="primary" icon={CheckmarkIcon}>
            Save
        </Button>
    );
}

For a complete set of supported icons, visit CDS Storybook's Icons page.

Themes

CDS supports multiple themes for visual identity. The sections below explain the approach and available themes.

Approach

All CDS themes use the same --cds-* token names, only the values change. Build your UI using these semantic tokens and CDS components that consume them. Then switch themes by setting a class on <html>, for example theme-dark or theme-id26-light. Keep a single, consistent set of imports.

Experimental token sheets only include the --cds-* variables that differ from the classic theme (for example dark or ID26), not the full token set.

ID26: new visual identity

ID26 is Coop’s new visual identity. Use the theme-id26-* classes and token imports listed in the Available themes table. In a future version of @coop/cds-tokens, ID26 light and dark will become the default themes, and the classic themes will be removed.

ID26 fonts

ID26 themes must use experimental/fonts.css and not fonts.css. The classic @font-face setup is for the old fonts only. Mixing it with ID26 tokens or classes will result in incorrect typography. In a future major version of @coop/cds-fonts, only ID26 fonts will be available and the classic fonts will be removed.

@import '@coop/cds-fonts/experimental/fonts.css';

Do not import experimental/fonts.css for classic light or classic dark only.

Available themes

Paths are relative to @coop/cds-tokens (token column) and @coop/cds-fonts (font column), for example import "@coop/cds-tokens/variables.light.css". Token files must be imported in the order shown.

Versioning in your app

To reduce surprise upgrades, pin CDS packages to a patch version:

"@coop/cds-components": "~4.3.0",
"@coop/cds-tokens": "~3.1.0"

Non-React projects

@coop/cds-tokens and @coop/cds-fonts are CSS and static font assets. You can use them in non-React web stacks (or static HTML) if your pipeline can install from the feed and load CSS: follow NPM Registry access above, then use the imports for @coop/cds-tokens and @coop/cds-fonts from your global entry or bundler.