@gnist/design-system

Multi-brand React component library for Møller

@gnist/design-system is a React component library containing reusable, multi-brand GUI building blocks for applications in the Møller ecosystem.

For instructions on developing components, see the Development docs.

Consuming the library

The library is published as @gnist/design-system in the public npm registry. The prefix @moller is an npm scope associated with our organization on npm

Installing the library

Run the command

npm install @gnist/design-system @gnist/themes

Using the library

To use the library, the vanilla-extract plugin needs to be used. For Vite, you need

npm install -D @vanilla-extract/vite-plugin @vanilla-extract/esbuild-plugin

Your vite.config.ts might look like this:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
import { vanillaExtractPlugin as veEsbuildPlugin } from "@vanilla-extract/esbuild-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [react(), vanillaExtractPlugin()],
    optimizeDeps: {
        esbuildOptions: {
            // Handle vanilla-extract .css.js files during Vite dev mode optimization
            // This prevents error "Styles were unable to be assigned to a file." in dev mode
            // See https://github.com/vanilla-extract-css/vanilla-extract/discussions/1051
            plugins: [veEsbuildPlugin({ runtime: true })],
        },
    },
});

In the application entrypoint, import the required global styles and choose a theme

import { LocalizationProvider } from "@gnist/design-system";
// Import one or more of these themes
import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";
import { gumpen } from "@gnist/themes/themes/gumpen.css.js";
import { brandless } from "@gnist/themes/themes/brandless.css.js";
import { mollerBil } from "@gnist/themes/themes/mollerBil.css.js";
import { skodaDark } from "@gnist/themes/themes/skodaDark.css.js";
import { vw } from "@gnist/themes/themes/vw.css.js";
import { dahles } from "@gnist/themes/themes/dahles.css.js";
import { autoria } from "@gnist/themes/themes/autoria.css.js";
import { audi } from "@gnist/themes/themes/audi.css.js";
import { cupra } from "@gnist/themes/themes/cupra.css.js";
// Import global styles
import { globalTextStyles } from "@gnist/themes/typography.css";
// Import necessary fonts (one or more, dependent on which themes are in use)
import "@gnist/design-system/fonts/moller";
import "@gnist/design-system/fonts/bilhold";
import "@gnist/design-system/fonts/skoda";
import "@gnist/design-system/fonts/gumpen";
import "@gnist/design-system/fonts/VW";
import "@gnist/design-system/fonts/dahles";
import "@gnist/design-system/fonts/autoria";
import "@gnist/design-system/fonts/audi";
import "@gnist/design-system/fonts/cupra";
import "@gnist/design-system/fonts/tools";

// Apply the theme
document.body.classList.add(bilholdLight);

// Apply global styles
globalTextStyles.forEach((c) => {
    document.body.classList.add(c);
});

export const App: React.FC = () => {
    return (
        <LocalizationProvider language="en">
            {/* ...the rest of your app here...*/}
        </LocalizationProvider>
    );
};

Next.js projects

If you are setting up in a Next.js project, the procedure is quite the same.

You will need to install and use @vanilla-extract/next-plugin.

With this setup, your next.config.mjs might look like this

import { createVanillaExtractPlugin } from "@vanilla-extract/next-plugin";
const withVanillaExtract = createVanillaExtractPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withVanillaExtract(nextConfig);

If you are running a React version 18 project, you will also need to add this to your tsconfig.json for it to work with this React 17 library.

"paths": {
     ...
      "react": [ "./node_modules/@types/react"]
    }

Next, just add the styling to your layout.tsx file. It might look like this:

import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";
import { globalTextStyles } from "@gnist/themes/typography.css.js";
import "@gnist/design-system/fonts/bilhold";

const bodyClassList = [bilholdLight, ...globalTextStyles];

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body className={bodyClassList.join(" ")}>{children}</body>
        </html>
    );
}

Finally, import components from @gnist/design-system.

Migrating from @moller/design-system

If you are migrating from the old component library, there are some breaking changes that will affect you.

Typographies

The typographies have changed with new names and tokens. Replace the old typographies from @moller/design-system with the new ones from @gnist/design-system:

Heading styles

• The Display style is still present, but is a bit smaller on all screen sizes.
• Headline has been replaced by Heading1Text and is the same size as before.
• Subtitle has been replaced by Heading2Text and is larger on all screen sizes.
• Overline has been replaced by Heading3Text and is larger on all screen sizes, with the smallest size going from 12px to 18px. The typography is no longer uppercase text. If you want this font style with uppercase, you must add it yourself.

Body styles

• The LeadText style is still present, but is smaller on all screen sizes, making it truly smaller than Heading3Text.
• The BodyText style is still present and is the same size as before.
• The LinkText style is still present and is the same size as before.
• DetailText is a new style and shall replace every usage of DescriptionText and LabelText. The smallest size for DetailText is 14px, whereas the smallest in the previous version was 10px for LabelText. This enlargement is to ensure optimal readability, and it may affect your layout.
• ActionText is no longer present and shall be replaced with BodyText. The only difference between these two is that ActionText had a bold font weight, so it you want the same layout you need to add this yourself.
• NoticeText is no longer present and shall be replaced with BodyText. The only difference between these two is that NoticeText had a bold font weight and uppercase text, so it you want the same layout you need to add this yourself.

CSS variables

It is still possible to use css variables like before, e.g. var(--moller-color-primary). However, it is not type safe and you will not get an error if you use a css variable that no longer exists. For instance, since the typographies have been changed, there is no longer a css variable named --moller-type-large-subtitle-font-size. Instead, you must use --moller-type-large-heading2-font-size. Moreover, if tokens are changed or deprecated in the future, you will not get an error for using an outdated css variable. To solve this and make the type checking secure, we recommend that you use tokens from the @gnist/themes package instead.

Furthermore, please note that all the CSS variables prefixed with the following no longer exist:

• --moller-type-{small/medium/large}-headline-{...}
  • replace with --moller-type-{small/medium/large}-heading1-{...}
• --moller-type-{small/medium/large}-subtitle-{...}
  • replace with --moller-type-{small/medium/large}-heading2-{...}
• --moller-type-{small/medium/large}-overline-{...}
  • replace with --moller-type-{small/medium/large}-heading3-{...}
• --moller-type-{small/medium/large}-description-{...}
  • replace with --moller-type-{small/medium/large}-detail-{...}
• --moller-type-{compact/default}-notice-{...}
  • replace with --moller-type-{small/medium/large}-detail-{...}
• --moller-type-{compact/default}-label-{...}
  • replace with --moller-type-{small/medium/large}-detail-{...}
• --moller-type-{compact/default}-action-{...}
  • replace with --moller-type-{small/medium/large}-body-{...}

The ... above is the text token type, e.g. --moller-type-small-heading1-font-family or --moller-type-small-heading1-line-height.

Deleted components

The components CheckboxCardGroup and RadioCardGroup has been removed completely. The consequence is that wherever these components are used, you must rewrite to use a mapping of multiple CheckboxCard and RadioCard, or make your own version of the group components. They are removed due to lack of use and high maintenance cost.

The AssistChip is removed. We recommend that you use Lozenge for the same use case instead.

Reference components for inline CSS with styled-components

You can no longer reference components with inline CSS selector in styled-components style. For instance, before you could style Icon like this:

${Icon}:hover { ..styling.. }

Now, you must add .selector to achieve the same goal.

${Icon.selector}:hover { ..styling.. }

Chips

You can no longer have children of the different Chip components, ActionChip, FilterChip and TagChip. To set the label inside a Chip, use the label prop instead.

The outline variant has been removed from the Chip components.

Buttons

GhostButton, TextButton and IconButton no longer accept the inverted prop. The prop has been deprecated.

Themes

Themes have been moved to @moller/gnist-themes, and require the use of a vanilla-extract plugin. This ensures better support for server-side rendering. Setup of the library in applications has thus changed significantly, but this should only require changes in some initialization and config files in your app. See Using the library in README for details.

Requirements for module resolution

The compiled library files in the published package have been moved from root to the dist subdirectory.

This requires consumers to respect the "exports" field in package.json. Bundlers typically do this already, but TypeScript requires "moduleResolution": "bundler" (or "node16" or "nodenext", but "bundler" is recommended).