@wistia/vhs

📼 Visual Hype System 📼

What is VHS?

VHS is a component library intended to provide a wide range of building blocks for React UIs.

Why build VHS?

Building user interfaces is time consuming, code-heavy, and challenging to maintain consistency in the design and the code patterns. VHS gives Wistia engineers confidence that they can build UIs quickly and maintain consistency with a DRY code approach.

How?

VHS is currently in the wistia/wistia repo, but will be moved to it's own repo and imported as an npm module in the future.

But importing and using the components will essentially be the same as if they were in an npm module:

import { ComponentName } from '@wistia/vhs';

---

Guidelines for contributing to VHS

Components

• Atomic Components - Components should be kept as atomic as possible. Therefore, VHS components shouldn't reference each other
• more to come...

Testing

In VHS, we use 2 types of testing: Jest for unit tests and Percy for automated visual regression testing.

Jest

coming soon...

Percy

Percy is an automated visual regression platform. Per the current setup, these automated visual regression "snapshots" are triggered manually by engineers.

Set up Percy Locally

From the command line

1. Get invite to Wistia's Percy organization (ask Galen)
2. $ export PERCY_TOKEN=<WISTIA-PERCY-TOKEN> get token from Percy settings page
3. $ yarn vhs:build - Need to first build a static version of Storybook
4. $ yarn vhs:snapshot - Fire the Percy snapshot.
5. Check out our Percy dashboard for the new snapshots.

Also, check out Percy's dev docs.

Styleguide

VHS uses Storybook as a styleguide generator for components. To add a styleguide "story", add a ComponentName.stories.jsx file next to the ComponentName.jsx.

Run yarn vhs to start Storybook locally.

Custom pages in the styleguide

Storybook empowers us to create non-component stories too! Here is the documentation on that.

Currently we have a handful of vhs/.storybook/*.stories.mdx files that which have names prefixed with numbers and letters in order to force their order in Storybook's navigation. That section of docs are first in the Storybook navigation because they are compiled first inside vhs/.storybook/main.js

# [all the custom MDX files + all the components stories]
module.exports = {
  stories: ['../*.stories.(jsx|mdx)', '../../src/**/*.stories.(jsx|mdx)'],
  ...
};

To complete the addition of a custom MDX doc files, you must include the following at the top of the file:

import { Meta, Subtitle } from '@storybook/addon-docs/blocks';

<Meta title="Foundations/..." />

# This is a custom H1 that will appear in the doc

<Subtitle>This is a nice thing to include, but not required in docs</Subtitle>

The rest of the file can be full of anything that can be included in MDX files - markdown and even components!

The <Meta /> component decides the placement of the document in the navigation. Separating the title attribute's strings injects hierarchy. For example, Foundations/Get Started/Overview means the document will be inside the Foundation navigation section, inside the Get Started folder, and be titled Overview. This doesn't set the <h1 /> in the document though, as you can see in the example above.

These types of MDX files can also be added to individual components. Just use this same <Meta title="..." /> naming approach.