slippers-ui

Slippers Marketing Design System

Slippers is the open-source GitLab Marketing Web Design System. In the spirit of "everyone can contribute", creating guidelines that enable people to build better web pages faster and allows us to co-create with ease. To learn more about design systems, read InVision's guide to 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!

Get Started Here!

Slippers is build with VueCLI, Storybook, and TailwindCSS. TailwindCSS has been configured as PostCSS plugin.

Local Development Instructions

• 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 60061
5. To view a webpage of the local customized TailwindCSS Config, run yarn view:tailwind on port 3000

How to use Storybook

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 workflow behind using 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

Slippers Documentation

You can find our documentation in the Storybook instance for this repository.

Keeping documentation in Storybook allows us to keep a single source of truth for this repository's documentation, alongside the code-based stories as well.

1. Get Started
2. Releases
3. Tailwind CSS
4. Storybook

Tailwind Config Viewer

A key idea that we want to reinforce about styling in Slippers is that we heavily modify the default TailwindCSS configuration. While the TailwindCSS docs page is still helpful, much of it does not reflect our configuration for this repository. To help with this, we have added a page that displays the existing utility classes within our current TailwindCSS configuration. URL: https://gitlab-com.gitlab.io/marketing/inbound-marketing/slippers-ui/tailwind/. To run locally, run yarn serve:tailwind-viewer

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.

Additional 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

• 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

• 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