I’ve worked on a few different design systems over recent years, and they all have unique properties that affect how we organized them. Specifically the most technically-ambitious design systems lived directly next to the code that consumed it, and the most design-ambitious systems needed to include hundreds of prototype page templates and variants of those pages for user testing and stakeholder review.
First let’s clarify definitions. I believe a Design System, a Component Design System, and a Pattern Library are all good names for the same thing, a web-based, documentation site that shows designers and developers what UI components are available and how to use them in web code, mobile apps, and (possibly) design software.
A UI Kit is a large file or library of components that contains the reusable components that Visual Designers use in their design software application of choice like, Sketch, Figma, XD, or Photoshop.
A Style Guide is a document or documents, on the web, or in a PDF, that instructs designers and employees about how to use the branding materials, how to write consistent messaging, and how to think about the larger design preferences of any organization.
I am going to focus on Component Design systems, specifically for web applications.
When starting a design system it’s important to think about the technical scope that you’re trying to reach. The scope does not mean just how many components will be documented, but what the use cases are for the tool, is it a place where designers turn static visuals into HTML and CSS? Are your organization’s developers going to consume the compiled CSS files from your system, are they going to consume JavaScript files or web-components from this tool? Will the build proccess be happening automatically when new commits arrive on master and then publishing to NPM or a CDN? Will the components that you document here actually be used in server-side applications like Rails partials?
If you have to cover some of those scenarios then you will be creating a code repository that needs to compile production-ready CSS files. Typically I use SCSS and/or PostCSS to create my shared CSS libraries. These tools allow you to break up your source files into multiple places around a directory structure and then selectively combine them with theming variables during compilation.
Compilation/Bundling
I still prefer to use gulp for compilation and bundling of CSS. Webpack is an excellent tool for creating JS bundles, and it’s pretty good at consuming CSS as well, but if you don’t need the complexity in your design system then don’t pursue it. I also think the Parcel bundler is a really powerful tool that’s worth looking into. Look into various tools to improve your SCSS experience like, stylelint, caching, dependency watching, sourcemaps, autoprefixer, and cssnano.
Static Site Generation
There are a few interesting options for creating the actual documentation site, including Patternlab, UIEngine and others, but I think Fractal is still the most powerful and complete tool. Though it’s maintenance history has been a little spotty lately, the new maintainers are building a new version.
At it’s core, Fractal’s job is to build static HTML files and preview how CSS rules affect those different HTML templates in different situations. It can also run as a local server with live reloading, for developer happiness.
Fractal encourages you to put each component in it’s own directory inside of src/components/ but you can customize this. Each component can have it’s own HTML, CSS, JS and README file. It also needs a config file which can be .js, .json, or .yaml. From experience I can tell you that if you choose anything other the .config.js for these files you’re asking for pain.
If you’re using Fractal here are two patterns for organizing your folders and files to make SCSS and HTML templates easy to find.
Atomic Design
This structure follows the excellent ideas of Brad Frost to organize UI pieces into larger and more complex compositions: Atoms go into Molecules, which go into Organisms. You keep any general SCSS files containing variables and shared mixins in your src/styles/ directory. The top level src/styles/app.scss file includes all the little pieces that you need to pull together to create one big CSS file. I like using the Foundation SCSS mixins (installed in node_modules) to give me access to a bunch of very well thought out and customizable CSS.
ITCSS+OOCSS
This approach organizes components inside of two different main directories. “Objects” and “Components”. Objects are less complex and Components are more complex, often comprised of other objects.
The addition to the other approach here, is that there are bunch of new folders in the styles/ directory that are named very specifically to follow the guidelines of ITCSS. In addition to the files you see here in this library I chose to include some helpers from the Inuit CSS library (installed via npm).
Browser Prototyping
There’s one other folder that I usually add to my components directory. It’s called “templates”. And it’s where I put whole page layouts. The fact is that Fractal allows us to link between templates from one template page to another. This means you can actually create whole page layouts for specific features by including all the little pieces of UI from other places with: {{> @nav_main_app}} and then you can add links to other pages with <a href="{{path "/components/templates/another" }}">Load a Thing</a>
This combination of SCSS production builds, folder organization, and complex template creation means this is more than just a design system, it’s a full workbench for web design.
