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