slippers-ui

Slippers Marketing Design System

Slippers is the open-source Marketing Web Design System. In the spirit of "everyone can contribute", creating guidelines that enable people to build better web pages faster makes more impactful work. Learn more about design systems.

Contributing

We're always looking for feedback to improve the experience of working with Slippers. We happily accept contributions, no matter how small. Feel free to submit an issue or open a merge request!

TailwindCSS

With Slippers, we have an edited configuration of Tailwind with a configuration file that exists on the root directory as tailwind.config.js. We would recommend examining that file before trying to use the library to understand how our setup compares against TailwindCSS's default configuration. While our configuration will affect which utilities are available in comparison to their documentation, using their own robust search is a good place to start.

For example, all of our utility names are prefixed with slp- as seen on within the config file.

We have changed the root em to 10px to align with how about-gitlab currently works. Note this affects how TailwindCSS is built compared to their docs, specifically classes that use rem as their unit of choice.

Storybook Notes

Storybook is our isolated UI to code environment for creating anything from blocks and components to layouts and webpages. We are using Vue as our front-end framework for achieving this. The main concept behind storybook is:

1. Authoring a Vue component
2. Creating a corresponding "story" as different UI States that exist withing a component.stories.js file. Storybook is able to interpret these stories and render out different states of that component to the browser.
3. Add documentation to those stories within the docs panel or as standalone page.

This article is a good practical example on how Storybook works and how to use it.

Gotchas: Args in Storybook vs Props in Vue

Local Development Instructions

Slippers is build with VueCLI, Storybook, and TailwindCSS.

Requirements

• This repo has been built and maintained using macOS with consideration for Windows machines, with Linux not being officially supported.
• If you don't already, make sure you have yarn, node, and nvm installed (If you have a windows machine, you will need to addiitionally install nvm-windows, and git).

1. Use nvm install to install the same version of node as listen in .nvmrc.
2. nvm use to allow nvm to match your working version of node to the one found within the repository.
3. yarn to install storybook, tailwindcss, and their dependencies
4. yarn start to watch for changes within vue files within ./stories directory on port 6006

Building for production

Building Storybook

1. yarn build-storybook to build to /storybook-static directory

Build the Vue Library

To build the entire library, run

yarn build

We use Vue CLI to build our components using the library target. vue.config.js has some of the configuration options set up, and is extensible.

The yarn build command chains the Vue CLI script with the PostCSS script:

"build": "vue-cli-service build --target lib --name slippersComponents src/main.js && yarn build:css"

Right now we target src/main.js as the entrypoint for the library, which in turn pulls in components we manually specify. We extract (and ignore) CSS from this build, because after the Vue CLI runs its build process, PostCSS runs our Tailwind build step.

Dist files

The build step creates these files:

• dist/compiled.css: compiled CSS from PostCSS and Tailwind
• dist/demo.html: demo app from Vue CLI that shows how the library could be imported
• dist/slippersComponents.common.js: component bundle, for consumption by Webpack
• dist/slippersComponents.common.js.map: source map for Webpack component bundle
• dist/slippersComponents.umd.js: component bundle, for consumption by browsers or AMD loaders
• dist/slippersComponents.umd.js.map: source map for browser/AMD loader bundle
• dist/slippersComponents.umd.min.js: minified browser/AMD bundle
• dist/slippersComponents.umd.min.js.map: source map for minified browser/AMD bundle

Clean mode

The order of those build commands matters, since the build command in Vue CLI will automatically remove the dist/ folder first. We can disble this if need to change the ordering.

Technical Notes

Repo Infrastructure

• We're currently using Prettier setup with Lefthook. Before committing, Lefthook checks that files are formatted with Prettier. To check for formatting, run yarn prettier:check. If you would like Prettier to format your entire repo automically, run yarn prettier:write. You may also pass your own arguments to prettier by running yarn prettier.

Storybook Notes

• Storybook currently must use PostCSSv7, while Tailwindv2 is using PostCSSv8. Because of this, Tailwind was installed to be compatible with PostCSSv7. Tailwind Docs on compatibility.
• Much of Storybook is built and written with JS frameworks in mind. However, its most popular usage with React. Much of their primary docs are written with React in mind. We should consider making a contribution to their Vue docs so that others can benefit from that as well.

TailwindCSS Notes

• Under the hood, TailwindCSS uses modern-normalize as CSS reset across browsers. Tailwind on Preflight.
• TailwindCSS was installed as a PostCSS Plugin, which allows the CSS to get built out without needing TailwindCSS as a dependency Tailwind Docs on PostCSS. CSS in this form is the most portable and allows for any web project to use our styling.
• PurgeCSS uses tree shaking to help keep our styling footprint small. Building CSS without using CSSPurge makes a CSS file around ~4MB in size. It's resonable to expect packages under 25kb.
• We found a recommended extension that is unfortunately only supported in VSCode: Tailwind CSS IntelliSense

PostCSS Notes

• Autoprefixer: PostCSS Plugin adds ventor browser prefixes
• PostCSS Import: PostCSS plugin transform @import rules to a single file