This is the styleguide for Informed K12.
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
- Create a file in
- Import that new file in
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.
/* will show up under the title */@/* 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 */@ `/* or */@ `<@/* gives a description of the component and can include tips on how to use it */@/* will be rendered and the code for it will be displayed underneath */@/* 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.
Currently, Whiteboard has a handful of tests, each specified as a NPM script and can called via the command line:
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
Runs units test for our Sass configuration. This makes sure that our custom Gulp tasks outputs correctly. Our test are written in Jest.
Compiles our entire styleguide, making sure our comments and styles compile. Together with
yarn test this gives us solid coverage ensuring our styles work.
Whiteboard uses Codeship for continuous integration. The tests above are configured to run for each pull request. The tests that are run are configured in Whiteboard’s Codeship setup.
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.
Whiteboard requires both NPM packages and Ruby Gems. It uses Livingcss to convert comments into documentation, and uses Nunjucks to render templates. It also requires node version
9.11.1, which you can install via nvm:
nvm install 9.11.1
To contribute, clone the repo, and then do:
yarn // install dependencies in package.jsonbundle // install all required gems
After that, run
yarn gulp. The rendered styleguide can be accessed at localhost:8001.
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:
Now when you change any comments, the change will be visible on localhost:8001.
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 is new master is pushed up, but for now, this is a manual process. Whiteboard should be published whenever a new version is released.
To publish, run:
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
Making Changes and Releasing
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.
Follow the steps here to cut a release for Whiteboard. Below is an example of how to fill out:
Once your PR from step 2 is merged, pull master and then run
npm publish. You will need to be logged in to NPM. We have one login for
email@example.com. The username and pasword are stored in lastpass. At this point, you should see the new releases on npmjs.
Update the version of
Last but not least, make sure the latest Whiteboard documentation is published. Just follow the steps in the publishing section.