informedk12-whiteboard

0.32.0 • Public • Published

Whiteboard

This is the styleguide for Informed K12.

Ooops!

Overview

Whiteboard is a components library that defines components (such as buttons and form elements) for our new InformedK12 styles.

Whiteboard is released as an NPM package, which we import into synchroform. All of the classes seen in Whiteboard are available to use in our app. Classes and variables are namespaced using wb- so they don’t clash with existing css.

Since we use Bootstrap in our synchroform layouts, we cannot include it in Whiteboard. The config files would clash if we tried. So for now, we will continue using the Bootstrap that is in synchroform.

Eventually, once we have consolidated our synchroform Bootstrap configs into one, we want to move it into Whiteboard. At that point, we will be able to expand Whiteboard to do more than just components (we will be able to define our own grid, for example).

Note that no vendor prefixes are added in styles defined by Whiteboard, and it is up the app importing Whiteboard to add it into the build process. We suggest using autoprefixer.

Writing styles and comments

Check out this page for a detailed explanation of our file structure.

Adding a new page:

  • Add it to site/config/nav.js
  • Create a file in src/scss/ (components/or/styles/`)
  • Import that new file in src/scss/whiteboard.scss

Adding to components / styles file:

There are blocks of comments in these files, you can copy one over from another component / style and edit it. The comments will be parsed by livingcss to create a page in Whiteboard.

Page description /* will show up under the title */

@section Form /* will give the page a title and also html file name */

/* we use a couple of formats for each component, depending on whether it’s a class or a tag */
@element {Class} `.wb-label` `.wb-input-field` `.wb-help-text` /* or */
@element {Tag} `<textarea>`

@description /* gives a description of the component and can include tips on how to use it */

@example /* will be rendered and the code for it will be displayed underneath */

@sectionof Form /* tells livingcss where to put the component */

We define the classes underneath each component where they are first introduced. Some components may use classes that are already defined earlier in the page.

Here is an example PR of adding a new Form page & input field component.

Testing

Currently, Whiteboard has a handful of tests, each specified as a NPM script and can called via the command line:

yarn eslint

Runs our Javascript linter through all our Javascript files according to the eslint setup. Currently Javascript is only used in our our Gulp files, but in the future, it can be used to lint any React components.

yarn scss_lint

Runs sass lint through all of our sass files according to the linter setup. We use the scss_lint gem as our linter, so be sure in install it via bundle.

yarn test

Runs units test for our Sass configuration. This makes sure that our custom Gulp tasks outputs correctly. Our test are written in Jest.

yarn styleguide

Compiles our entire styleguide, making sure our comments and styles compile. Together with yarn test this gives us solid coverage ensuring our styles work.

Continuous Integration

Whiteboard uses Github Actions for continuous integration. The tests above are configured to run for each pull request. The tests that are run are configured in Whiteboard’s ruby.yml.

Future Testing

In the future, we want to add in visual regression testing for Whiteboard. This will ensure that we have complete coverage of our styles and we don’t accidentally change things we didn’t intend to.

Development

Whiteboard requires both NPM packages and Ruby Gems. It uses Livingcss to convert comments into documentation, and uses Nunjucks to render templates. The required node, ruby version are in .tools-versions and can be installed via adsf.

Once you clone the repo, install the right node and ruby version via adsf:

asdf install

Then do the following to install other packages dependencies:

yarn  // install dependencies in package.json
bundle // install all required gems

After that, run yarn gulp. The rendered styleguide can be accessed at localhost:8001.

Watchers

yarn gulp automatically watches for any changes in scss and template files and re-renders the styleguide. However, livingcss doesn’t play well with the Gulp watcher, so a special script is used to watch for documentation changes. On a separate terminal window, run:

yarn watch

Now when you change any comments, the change will be visible on localhost:8001.

Publishing

The styleguide is published to https://informedk12.github.io/whiteboard/, whose content is mapped to branch gh-pages. In the future, we could automatically publish the styleguide whenever a new main is pushed up, but for now, this is a manual process. Whiteboard should be published whenever a new version is released.

To publish, run:

yarn gh-pages

Note

Make sure origin is setup as the git remote. We use git-directory-deploy to push to gh-pages, and by default the git remote is set to origin.

Making Changes and Releasing

  1. Open a PR with the updates, and be sure to update the release notes. Within the release notes, add a [UNRELEASED] tag for updates that hasn't been pubished yet. Example PR here and here.

  2. Once the changes are ready for release, open a PR to update the release version. Also, remove the [UNRELEASED] label from the release-notes and double check that the release notes are up to date. Example PR.

  3. Follow the steps here to cut a release for Whiteboard. Below is an example of how to fill out: Release screen shot

  4. Once your PR from step 2 is merged, pull main and then run npm publish. You will need to be logged in to NPM. We have one login for eng@informedk12.com. The username and pasword are stored in lastpass. It will also ask you for a OTP (one time password AKA two-factor authentication code). Ping #engineering on slack if you need it. Once the publish goes through, you should see the new releases on npmjs.

  5. Update the version of informedk12-whiteboard in synchroform's package.json.

  6. Last but not least, make sure the latest Whiteboard documentation is published. Just follow the steps in the publishing section.

Readme

Keywords

Package Sidebar

Install

npm i informedk12-whiteboard

Weekly Downloads

23

Version

0.32.0

License

MIT

Unpacked Size

2.71 MB

Total Files

64

Last publish

Collaborators

  • informedk12eng