td-stylekit 🎨

A common set of components and styles to be used across frontend products as well as documentation based on these components.

Installation 💻

yarn add td-stylekit react react-dom moment react-syntax-highlighter react-virtualized

Note: If using create-react-app no need to install react and react-dom

Find us on npm.

Usage ⚛️

import { Text, ThemeProvider } from 'td-stylekit'

return () => (
  <ThemeProvider customTheme={ThemeProvider.v5Theme}>
    <Text>text</Text>
  </ThemeProvider>
)

Scripts 👩‍💻

| script | description | | -------------------- | ------------------------------------- | | build | generate a production build of module | | test | run unit tests | | tdd | run tests in watch mode | | start | start dev documentation server | | docs:build | generate static build of docs | | download:snapshots | copy changed snapshots from CircleCI | | publish:yalc | publishes stylekit to yalc |

Etiquette

Writing stories

As of May 2022, stories must be specified in the following format:

import type { Meta, Story } from '@storybook/react'

export default {
   title: 'v5/Control',  // <-- Change as necessary
   .... // and other properties
} as Meta

This ensures that all *.stories.tsx are parsed correctly and available for visual regression tests.

Testing td-stylekit locally in other projects

To test td-stylekit locally in other projects perform the following steps:

In td-stylekit

In the root folder of the project issue the following: yarn publish:yalc

If you make subsequent changes - repeat the command above.

In the dependent project (e.g. td-crystal)

In the root folder of the project issue the following: yalc link td-stylekit --no-pure yarn

To cleanup: yalc remove td-stylekit

Problems when using yalc

If you consistently notice errors when issuing yarn - you may need to clean everything and start again by issuing the following:

rm -rf node_modules yarn

Release 🛸

Fully automated! We follow the conventional commit format and deploy on every meaningful commit to main.

Detailed documentation on the release process and how to format commit messages can be found here.

Visual Regression Testing 📉

Visual regression tests take snapshots of each Storybook story and compare them to existing snapshots to identify any visual differences introduced by code changes.

If a visual regression test fails, that means you've made visual changes to a component. If this is unintentional, it'll alert you to your mistake. If this is intentional, you'll need to update the snapshots to make the test pass.

Updating Visual Regression Tests 🌠

Prerequisites

• Set up the $CIRCLECI_TOKEN environment variable in your local environment
  • Instructions can be found here

Steps

Push your changes, allow CircleCI to finish executing the Visual Regression step, then run:

yarn download:snapshots # Use the --help flag for more options

• This will script will download any altered snapshots that have been saved in CircleCI's Artifacts to your local snapshot directory.

• From there, you can simply commit the new snapshots.

Disabling Visual Regression Tests ❌

Screenshot are automatically generated for all stories. However, if you need to disable tests due to hard-to-screenshot stories, like animations, you have a couple options:

• Disable a single story by adding the tag to the story config
• Disable an entire file of stories by adding the tag to the story meta

Both of these options require the same skip-snapshot-test tag to be added:

{
  tags: ['skip-snapshot-test']
}

Browser support 🖥️

See: https://docs.treasuredata.com/display/public/PD/Browser+Support+for+TD+Console

Working with the CircleCI build image 💅

See: https://treasure-data.atlassian.net/wiki/spaces/EN/pages/1891401733/Work+with+the+CircleCI+build+image

Contributing 🙌

Contributions are always welcome! Read our contribution guidelines.

Documentation 📝

• Stylekit Stories
• Stylekit Confluence

Debugging in Visual Studio Code 🐛

• Install Debugger for Chrome extension.
• Set break points wherever you need
• Press F5. This will launch a new Chrome browser and run td-stylekit in debugging mode

Resolving Security Issues 🔐

Using Dependabot

Dependabot is a tool which checks your Github repository for security issues.

• You can see a list of security issues under Dependabot Alerts on Github, under the Security tab (or click here).

• If Dependabot is able to bump a package's version to fix the security issue, it will create a pull request.

Otherwise, you can try to fix the issue manually.

Manually

Some dependencies used by Stylekit have vulnerabilities. As often as possible, these security issues should be mitigated by updating their package versions.

• Use yarn audit to identify dependencies with vulnerabilities
  • (optionally) yarn audit --level [low|moderate|high|critical] to filter by severity
• Use yarn why to find out which package requires that dependency
• Use yarn upgrade [package name] to upgrade that package
  • If a new version of that package is available, it may include a fix for the vulnerability
  • If not, we either need to remove that package/dependency, or wait until a new version of the package is released.