Skip to content

Latest commit

 

History

History
166 lines (120 loc) · 5.46 KB

README.md

File metadata and controls

166 lines (120 loc) · 5.46 KB
Raw

JW Design Library (Hook)

Owners

Design library for colors, icons & styles used in JW Player products. Built with Amazon Style Dictionary.

For visual docs, check out ✨ Neverland Design System

Development

Ensure you're using Node v16 and run:

npm install

Adding Icons

  1. Create a feature branch from master
  2. Pull in any new SVG files into the dictionary/assets folder
  3. In /dictionary/properties, locate the yaml config of choice and add new names/values in accordance with file structure
  4. Run npm run build. If the build succeeds, you should see your changes in the /dist folder.
  5. Bump the version # accordingly to align with semantic versioning
  6. Open a PR against master

Releasing

To release Hook, we need to publish it to NPM.

  1. Set your local npm config to the internal registry
  2. Checkout master and pull in the latest: git checkout master && git pull
  3. Ensure that your local /dist folder and version # are correct
  4. Run npm publish
  5. @design/jw-design-library will reflect the new version here
  6. Draft a release with a changelog of updates and 💥 breaking changes

Usage

Everything you'll need exists in Hook's /dist folder. Style variables are available in pure CSS, SCSS, and Less.

Install in your project

Set your npm config to the JW Player NPM registry and run:

npm install @design/jw-design-library

Colors

Import the color variables and apply them in your stylesheet like this:

@import (reference) "@design/jw-design-library/dist/scss/brand-colors.scss";

p {
    color: $ds-color-brand-midnight;
}

Fonts

To use our fonts, reference the CDN route in your HTML document <head>:

<link href="https://hook.jwplayer.com/jw-design-library/5.3.0/css/fonts.css" rel="stylesheet" />

Then import the variables and apply the font-family and font-weight as needed:

@import '@design/jw-design-library/dist/scss/fonts.scss';

p {
    font-family: $ds-global-font-family-custom;
    font-weight: $ds-global-font-weight-custom-semibold;
}

code, pre {
    font-family: $ds-global-font-family-code;
}

Icons

We recommend using our WUI components if possible, but you can also import the SVGs individually.

In a create-react-app project, for example:

import React from 'react';
import { ReactComponent as DownloadIcon } from '@design/jw-design-library/dist/icon/dashboard/download.svg';

const App = () => {
  return (
    <div className="App">
      <DownloadIcon />
    </div>
  );
}
export default App;

If you prefer working with a sprite, you can import the sprite from /dist/sprites or download it directly from the Neverland docs.

<svg>
  <use href="/path_to_hook/icons/sprite_name.svg#icon_name"></use>
</svg>

Under the Hood

The file build.js imports various modules from scripts/ to build the full style-dictionary config. Here's a really quick rundown:

  • formatters/svg-sprite runs each matched icon through SVGO, then converts the SVG into a <symbol>. After all icons in the group are optimized, a wrapper is added and the SVG file is output.

  • formatters/font-face uses the structure found in font-face.yaml to output @font-face declarations in CSS. All font files referenced in the dictionary are copied to dist/fonts. If you use fonts.css then you must copy or resolve the paths for the font files, or things won't work!

  • transformers/content-array-to-list: Converts property values into comma-separated lists. This is used to output data colors for Less.

    prop:
  value:
  - '#000000'
  - '#CCCCCC'
  - '#FFFFFF'

    The example above has this final output:

    @prop: #000000, #cccccc, #ffffff;

  • transformers/content-list-to-js-array: Converts property values into bracketed arrays. This, combined with content-array-to-list, is used to output data colors for JS. The example above has this final output:

    export const prop = ["#000000","#cccccc","#ffffff"];

  • transform-groups/less-transform-group: Overrides the built-in less transformGroup, to add content/arrayList and switch to color/css for rgba output.

  • transform-groups/js-transform-group: Overrides the built-in js transformGroup, to add content/arrayToList and content/listToJsArray.

  • utils/mock-require: Rather than rewrite the combineJSON function present in style-dictionary, we intercept the require call itself to render YAML with js-yaml when necessary. This may change if combineJSON ever changes.

  • utils/svgo: Since SVGO is asynchronous by design, we use a wrapper module with sync-rpc to treat it as if it's synchronous. You may notice the dots when icons are being built - each dot represents a sprite that has been "synchronously" optimized by SVGO.

Related Links