Substrate Design System - Stencil Web Component Library

This repository contains only the web component library. Check out our Substrate DS Docs or the Substrate DS StoryBook for all Stencil components

The Design tokens are managed using Style Dictionary Github repository

Getting Started - DEVELOPMENT

To get the project running:

Install dependencies

npm install

To start development wit StencilJS & Storybook run start-dev in the terminal

npm run start-dev

Or run the Stencil and Storybook manually using:

npm run build
npm run start
npm run storybook

Design tokens and themes

All components are built using the design tokens. Each component has component specific tokens, which in turn are linked to a semantic layer.

Each theme has it's own semantic layer, and hence themes can be used to create a custom design system or a light and dark mode. The same design tokens can be used to create a multi-brand design system. In this case it is likely that both the semantic as well as the core tokens need to be replaced (different core tokens for each brand). Semantic layers can be used for a light/dark mode per brand.

Component specific tokens rarely need to be modified. In the rare case that this is required, the Stencil components need to be updated accordingly which is undesireable.

Design tokens can be managed in Figma using the Figma Tokens plugin, or directlty in the JSON file in the bc-design-tokens reposiory. More information on token management can be found in the readme file in this repo.

Adding new themes to the design system

Themes need to be added in both the stencil project as well as the Storybook config.

Stencil project:

Add the theme CSS files from the CDN in src/index.html

Storybook config:

Add the theme CSS files from the CDN in .storybook/manager-head.html and .storybook/preview-head.html

To access the themes using the theme switcher, a new theme needs to be defined in the parameters in .storybook/preview.js

export const parameters = {
  themes: {
    default: 'Light Mode',
    list: [
      { name: 'Light Mode', class: 'light-theme', color: '#3b5998' },
      { name: 'Dark Mode', class: 'dark-theme', color: '#00aced' },
    ],
  },
};

Getting Started - CONSUMING COMPONENTS

Substrate is not ready for use in production. Currently you will need to build and manually integrate components to experiment.

Check out our Substrate DS StoryBook to see they components in their current state.

[ Experiamental ] Use the webcomponent library to play around using unpkg by adding the following to your html head:

<script crossorigin type="module" src="https://unpkg.com/sux-ds@latest/dist/substrate-ds/substrate-ds.esm.js"></script>

Contributing

Check out our roadmap to see what we're working on and where we need help.

We welcome contributions to this project. See contributing.md for an overview of contribution guidelines.

License

COPYRIGHT © 2022 BrandCode