@daikin-oss/design-system-web-components

Daikin Design System - Web Components

This project is an implementation of the Daikin Design Kit using Web Components.

Usage

Start by installing the package:

npm install @daikin-oss/design-system-web-components @daikin-oss/dds-tokens

To deploy the necessary CSS variables, import the CSS or SCSS from the @daikin-oss/dds-tokens package: For details, please check the dds-tokens repository.

import "@daikin-oss/dds-tokens/css/daikin/Light/variables.css";

You can then import necessary components in your bundle (the .js extension is optional):

import "@daikin-oss/design-system-web-components/components/button/index.js";

Fonts

We use Roboto as the font for our UI components. This font is not included in our package, so developers will need to include it in their apps.

The required weights and variants are as follows:

• Regular (400), Normal
• Bold (700), Normal

With Google Fonts

If you can use an external CDN, you can use Google Fonts to load it.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap"
  rel="stylesheet"
/>

With Fontsource

If you want to deliver fonts within your app without relying on an external CDN, you can use a package like Fontsource to do this.

Install the package with:

npm install @fontsource/roboto

Then import it in your app:

import "@fontsource/roboto/400.css";
import "@fontsource/roboto/700.css";

Dark Mode and Brands/Themes

Due to the encapsulation of styles by the Web Components specification, how themes are applied may change in the future.

For dark-mode support and non-daikin brands, you need to add the tokens package and include the CSS reference in your html:

npm install @daikin-oss/dds-tokens

Dark Mode

Reference the CSS in HTML:

<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/DKN/Dark/variables.css"
  media="(prefers-color-scheme: dark)"
/>

Using CSS @import with prefers-color-scheme:

@import "@daikin-oss/dds-tokens/css/daikin/Dark/variables.css"
  (prefers-color-scheme: dark);

Other brands/themes

Reference the CSS in HTML:

<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/AAF/Dark/variables.css"
  media="(prefers-color-scheme: light)"
/>
<link
  rel="stylesheet"
  href="node_modules/@daikin-oss/dds-tokens/build/css/AAF/Dark/variables.css"
  media="(prefers-color-scheme: dark)"
/>

Using CSS @import with prefers-color-scheme:

@import "@daikin-oss/dds-tokens/css/aaf/Light/variables.css"
  (prefers-color-scheme: light);
@import "@daikin-oss/dds-tokens/css/aaf/Dark/variables.css"
  (prefers-color-scheme: dark);

Contribution

The following are instructions for package contributors.

Setup

Clone and install dependencies:

git clone https://github.com/dsv-rp/DDS.git
cd DDS

# install dependencies
npm i

# install Playwright browsers
npx playwright install

Build

To build files for production:

npm run build

Vite is used to transform TypeScript code into JavaScript that runs in modern browsers.

The built files are written to /dist.

Documentation

Storybook is used to document design system components/tools/examples.

To run in development mode:

# Web Components version
npm run storybook

# or React version
npm run storybook:react

To produce distributable files in /storybook-static/web-components and /storybook-static/react folder:

npm run build-storybook

Testing

There are currently two test suites: VRT (Visual Regression Test) and Interaction Test.

Visual regression testing, placed in *.visual.test.ts, is done by Playwright running in a container. To eliminate rendering differences between environments, the browser which takes the screenshots must run on a container.

Currently, Web Components has full support in most major frameworks except for React. As such, we test both Web Components by themselves, and also test when imported by React:

# start a container for running the browsers
docker compose up -d

# run VRT for Web Components and React versions
npm run test:visual

# stop the container
docker compose down

For Podman users, use podman-compose -f compose.podman.yaml or podman compose -f compose.podman.yaml instead of docker compose.

To update snapshots, use npm run test:visual-update

Interaction testing, placed in *.stories.ts, is performed by Storybook, which also uses Playwright internally. Interaction tests do not use containers since rendering differences between environments do not matter.

npm run test:interaction

Linting and Type checking

Linting is performed by ESLint for general linting of JavaScript and TypeScript, and lit-analyzer to type check bindings in lit-html templates. cSpell is used for spell checking. ls-lint is also used to ensure that consistent filenames are used.

To lint the project, run:

npm run lint
npx tsc -b

If you encounter an Unknown word error, add the word to the cspell-dictionary.txt.

Design Tokens

We manage and use design tokens to ensure consistency in our design system.

• Source of Truth: The tokens we use is the foundation of our design styles and was grabbed from https://github.com/dsv-rp/dds-tokens. These design tokens are deployed as CSS variables.

• Usage in Components: The components make use of design tokens by referencing CSS variables. Since they are integrated with Tailwind CSS, they are mostly used as utility classes, but in some cases they are directly referenced using var().

@ddsElement("daikin-link")
export class DaikinLink extends DDSElement {
  static override readonly styles = css`
    ${unsafeCSS(tailwindStyles)}

    :host([show-visited]:not([disabled])) a:visited {
      /* HERE */
      color: var(--dds-color-link-text-visited-default);
    }
  `;

  override render() {
    /* AND HERE (`text-ddt-*` classes) */
    return html`
      <a
        class="text-ddt-color-link-text-default hover:text-ddt-color-link-text-hover"
        href="https://www.example.com/"
      >
        ...
      </a>
    `;
  }
}

TailwindCSS

There is a custom daikinPlugin managed here.

Developing with VSCode

This project provides recommended extensions and workspace settings for VSCode.

References Daikin Design Kit