St. Baldricks Design UI Toolkit

This UI toolkit is a modular design system for rapid web development. It contains small UI elements, called materials that can be assembled into more complex page layouts.

This guide contains real working examples, code snippets, documentation, and style guidelines.

Directory Structure

The library potion of the toolkit lives in src/assets/toolkit. This contains the javascript, images, scss and templates that other applications will pull in to use.

The documentation side of the toolkit lives in docs. This contains the documentation (markdown) as well as the Single Page App that pulls in the library source and displays it.

Single Page App

The single page app that contains the toolkit documentation and examples is inspired by fabricator. Fabricator didn't nicely support importing templates, so a new SPA was written that uses fabricator's CSS.

The SPA is a React application that heavily leverages the power of webpack loaders to display templates, js, css, and handle live-updating of data in templates.

Libraries Technology Used & Documentation

| Library | Official Docs | Tutorial | |---------|---------------|----------| | React | https://facebook.github.io/react/docs/hello-world.html | | | Redux | http://redux.js.org/ | https://code-cartoons.com/a-cartoon-intro-to-redux-3afb775501a6 | | Webpack | https://webpack.js.org/configuration/ | https://webpack.js.org/concepts/ |

SPA Structure

There are some loose conventions for how the SPA is put together.

Source code for the application that is the SPA itself are located in docs/src.

The documentation and related css/js lives in docs/components or docs/general.

docs/general

docs/general is where general (markdown only) documentation lives. This is for general style guidelines and practices.

Each 'page' in docs/general can have multiple parts, the index.js in any of the folders in docs/general setup the name of the page and the sections they contain.

docs/components

Components in docs/components are more complex than simple mardown documentation. Generally the index.js file in any component is the entrypoint that defines the sections of the 'component page' that will be displayed for any given component. Components often consist of a template (mustache), some styles (scss), some data (yaml) and some notes (markdown). The yaml is used to render the template in the toolkit, it also provides the defaults for the interactive editor.

I expect the shape of the component objects to change as we get a better idea of what we want to display on the page for each component.

Tieing it all together

The components and pages are all pulled in to docs/src/lib/contents.js this is where they are inserted into the menu and passed down to the view components of the SPA