Site Scan Pattern Library

Hosted through Github Pages at https://3drobotics.github.io/sitescan-ui-patterns/.

Development

Dependencies

Install Node JS

Install Yarn

Install Rollup

Install app dependencies

yarn install

Managing Dependencies

Use the Yarn CLI to add or remove dependencies. (Documentation)

For example, yarn add [package]@[version].

Building (Handled by Rollup)

Building is handled by rollup, a module bundler that leverages ES6 modules to maximize efficiency. To build, run the yard build command.

Build configuration is stored in the rollup.config.js file, and bundle output is stored in the dist folder.

Local Development Between Repositories

With a reusable pattern library like this, it's ideal to be able to view live updates while developing in other local repositories. To do this, use the yarn link command in this library's directory. Next navigate to the directory you want to link it to and run yarn link "@3dr/sitescan-ui-patterns".

To enable automatic rebuilds whenever updates are made, run the yarn dev command in this library's directory. This command is enabled by the rollup-watch addon. Alongside the yarn link setup, this will allow for live updates to pattern components in the linked repositorys.

Note: Before this repository can be linked, you must run yarn build.

Storybook Development

Storybook is used to provide a simple UI development environment. It helps provide documentation and an interactive sandbox for each component. The development server is run with webpack using storybook's default configuration:

yarn storybook

Navigate to localhost:9001 to view the storybook interface and develop components and their stories.

Each component should have a corresponding [componentName].js file in the stories folder that contains the logic for viewing and interact with the component in Storybook.

Most stories will make use of some of storybook addons, such as info and knobs, to enhance documentation and flexibility. These addons are registered in the .storybook/addons.js file and can be used in any story file.

Building and Deploying storybook

The storybook interface is deployed to Github Pages using the storybook deployer. To make a build, run the command:

yarn build-storybook

This will add the library bundle to an .out folder available in the gh-pages branch. To deploy, run:

yarn deploy-storybook

Your updates should now be viewable at https://3drobotics.github.io/sitescan-ui-patterns/. This will be necessary to update the deployed site when the master branch is updated.

Styles

The CSS-in-JS library glamorous is used to style components. This simple library with low configuration overhead provides scoped styles by default and allows style properties to be treated like normal React component props. Support for more advanced CSS techniques like media queries and pseudo selectors is still provided with glamorous.

Each component should have a corresponding [componentName].styles.js file that stores component styles in JavaScript objects. The base styles can then be merged with any applicable modifiers according to the given inputs through the glamorous css method. Any provided instance-specific style properties can be passed along directly through ...props, which ensures they take priority over the css generated class.

Example - <Input />

/* Input.styles.js */
export default {
  base: { border: '1px solid black' }, // styles applicable to all instances
  small: { fontSize: '12px', width: '40px' },
  large: { fontSize: '16px', width: '60px' },
}

/* Input.js */
import styles from ./Input.styles.js;

<glamorous.Input
  className={css({
    ...styles.base,
    ...styles[size], // size prop can default to 'small' or 'large'
  })}
  {...props} // can contain individual style properties
/>

Style Adjustments

Library elements need to be built with the flexibility to have their styles adjusted based on a given use case. In most cases, this will involve the use of props such as modifiers and size.

In general, modifiers change the appearance of an element through more decorative properties such as background color, font color, border, etc. Size props affect the size of an element at the highest level. Modifiers and size are separated because a given element instance should not have multiple modifiers or multiple sizes but can have one of each.

Some elements may also have styling logic based on specific props such as a disabled button. Those instances can be passed in as separate props and the component can apply conditional styles according to their values.

Elements are built with pre-defined styles corresponding to each these props that should be used to adjust appearance when possible. However, if additional styling tweaks are needed for a given implementation, glamorous allows style properties to be passed on to an element directly as props.

Example:

<Button modifiers="danger" size="large" marginLeft="40px" disabled>
  Button
</Button>

Linting

JavaScript linting configuration is shared with Site Scan Manager and SS Admin through the eslint-config-sitescan repository.

Linting for styling syntax is also available through stylelint-processor-glamorous. However, it is relatively limited and manual due to the fact that styles are primarily stored in JavaScript objects. The yarn stylelint 'src/**/*.js' command is used to check validity of a style module's syntax, but note that it only runs against styles configured in the specific ways listed in the stylelint-processor-glamorous documentation.

Given the nature of this setup and this library's style configuration, this is useful primarily in the case of syntax debugging. A quick way to lint a style module during development is to add the @css annotation right before its opening bracket and then run the yarn stylelint 'src/**/*.js' command:

const styles = // @css
  {
    notACssProperty: 'test',
  };

Releases and Versioning

sitescan-ui-patterns is published to NPM under the @3dr namespace @3dr/sitescan-ui-patterns.

yarn publish --access public --[major|minor|patch]

Follow semantic versioning for versioning.

A new commit will automatically be created that bumps the version in package.json.