astm-ux-design-system-test

v1.0.13

Published

3 months ago

Branded UI Component Library for ASTM

0High
0Medium
0Low

ASTM Build Kit

The components in this Build Kit are built with a vanilla, framework-less approach, so the consumable aspects are HTML markup, CSS and some JavaScript.

Finding your way around

While you'll likely care most about the dist/ and src/ folders, here's a quick summary of what's inside this repo, and what they're for.

.storybook/, contains all the Storybook configuration files to customize Storybook (version 5.3.x).
config/, contains all the webpack configuration files to build and bundle the production assets.
dist/, the destination (distribution) folder containing all compiled and minified production assets.
src/, the folder containing all source code and working files, and main webpack entry point.
package.json, the file containing all npm library dependencies and npm script commands (most are dev dependencies).
readme.md, the file you're reading right now! :) Contains helpful information regarding the repo.
.babelrc, .huskyrc, .lintstagedrc, etc, configuration files for various code quality, consistency, and developer convenience libraries (linting, pre-commit hooks, code and style quality checks, etc.)

The UI components

Within src/components/, each individual component is organized into their own folders with all the files concerning that component:

[pattern-name].stories.js, the Storybook file containing all the "stories" (documentation) for the component. This is where the components are demonstrated and hooked up to Storybook features.
[pattern-name].scss, the Sass styles for the given component, scoped with their own named-spaced css class.
[pattern-name].js, the IIFE-style vanilla JS for the component's basic functionality (if the component requires JS -- most components do not).
[pattern-name].html, this is a handy default example for the default pattern markup -- it's meant to be reference only, and it's not actually used within Storybook. The *.stories.js files are what you'll likely want to reference for additional component options.

All the component JS files are bundled together in a single script dist/bundle.js, (18kb minified), but if you prefer to load only a handful of components, each component's JS file can be referenced directly for finer control over page performance.

Production Build

To update the production-ready assets with new code added to this repo, simply run npm run build to trigger a webpack production build. It will clean out the dist/ folder and replace it with the newly minified assets.

How to Use the Components

Implementation of the minified components is done the good old-fashioned way:

Include the minified CSS and JS assets on your page (found in the dist/ folder) In the <head> of the page, link to the external stylesheet.

NOTE: The bundled CSS includes a link to typefaces hosted Google Fonts (Line 1 of bundle.css). Depending on your CORS policies, you may see Cross-Origin request error preventing the resources from loading properly.

<link src="path/to/bundle.css" rel="stylesheet" />

Then in the <body>, as close to the closing` tag as possible, add a reference to the external components script.

<script src="path/to/bundle.js" defer></script>

Build your layouts and pages with the UI HTML patterns according to the source documentation. Be careful not to omit CSS classes accidentally, or the components may not display or behave properly.

Development

Running Storybook Locally

Go to the bootstrap-master-files project folder in your terminal and install the project dependencies:

cd bootstrap-master-files
npm install

To run Storybook:

npm start

Then you should be able to view the Storybook environment on http://localhost:6006/.

Serving Storybook Statically

You can host this Storybook app statically by running npm run build-storybook -- it will compile all the assets required to run Storybook statically. For more information, check out the official documentation: https://storybook.js.org/docs/basics/exporting-storybook/

Publishing

Initial Setup

Publishing relies on an environmental variable for NPM_TOKEN. For this token, please contact [email protected].
Add the token as an environmental variable on you machine. The token should be called NPM_TOKEN.

Running Publish

Run npm run publish to kickoff the lerna publish command.
Choose the next logical semantic version.

If you would like to see what is being published before you publish it, you can run npm pack to create a zip file of your published folder. If you would like to confirm that your publish was successful, you can run npm view astm-ux-design-system. For more granular control over publishing, install Lerna globally and consult the documentation: https://github.com/lerna/lerna