StackupUI

StackupUI is a UI library aimed at consistency, best practices, and accessibility. StackupUI is built on TailwindCSS.

Beta Components

Some of the components described in this documentation are labeled with a beta flag. This means that the component may not have been fully tested for usability or function. You may use these components, but keep in mind they are subject to possible change or deprecation.

Getting started

StackupUI is mean to be extended and modified. While it comes with strong opinions, which you are encouraged to agree with, you can modify and customize it entirely to suit your project's needs.

Copy the TailwindCSS config

Because StackupUI extends TailwindCSS, you'll need start by making a copy of the tailwind.config.js in the root of your app. This file extends the default TailwindCSS theme with StackupUI's custom colors, spacing settings, and more. Modify or extend these to suit your app's needs.

Refer to the tailwind theme configuration docs to add your own customizations.

Copy the source styles

Next you'll need to grab a copy of the src/styles directory and incorporate it into your project. This contains the CSS styles that compose StackupUI's utilities and components. Modify them freely, but cautiously.

Setup your main stylesheet

Create a root stylesheet, and incorporate this into your application in whatever way is appropriate.

Import TailwindCSS and StackupUI's stylesheets.

@import "tailwindcss/base";
@import "../src/styles/base";
/* Import your custom base-element styles here */

@import "tailwindcss/components";
@import "../src/styles/components";
/* Import your custom component styles here */

@import "tailwindcss/utilities";
@import "../src/styles/utilities";
/* Import your custom utility styles here */

Copy the PostCSS config

TailwindCSS is compiled using PostCSS. Make a copy of the postcss.config.js in the root of your app, which is configured to run Tailwind. Additional PostCSS plugins can be added as needed.

Compile with Webpack

It is (currently) recommended you use Webpack to build and package assets. Make it easy on yourself and just use @stackup/webpack. This provides functions that you can compose to build a webpack configuration.

Creating custom styles

TailwindCSS's core methodology is based on low-level, utility class names. These class names are intended to be composed together to create unique components.

Using @apply

Make use of the @apply directive whenever possible. TailwindCSS has a huge library of utility classes that cover most needs; using their classes will help keep your app looking consistent, and make sure your app's styles adapt uniformly when the Tailwind config is modified.

Creating base styles

If you need to customize base HTML element styles, you'll want to incorporate these directly after TailwindCSS and StackupUI's base styles (or just modify StackupUI's base styles), but before component styles.

Creating components

A component, in this context, is one or more CSS classes that define the appearance and behavior of some small piece of UI. For instance, a button:

.btn {
  @apply p-3 rounded bg-blue-800 text-white;
}

<button className="btn">Click me!</button>

Contextualize with TailwindCSS classes

When implementing your components in a real app, you'll often need to add more context-specific styles, that don't necessarily apply to all instances of the component. For example, you may want to add some margin to a particular button, but not all buttons.

Add Tailwind classes to your markup to achieve this:

<!-- a full-width button with some margin on the right -->
<button className="btn w-full mr-3">Click me!</button>

Creating utilities

TailwindCSS is built on utility classes, which are meant to be applied to other classes or elements. You may, in rare cases, need to create your own utilities to apply to other classes or elements.

This is nothing more than a CSS class, imported after Tailwind's utilities.

.painfully-purple {
  background-color: purple;
  color: purple;
}
... .my-purple-component {
  @apply painfully-purple;
}

Composing in markup (an alternative approach)

StackupUI's philosophy on how to create components is to make separate CSS files for each component, and import them into your CSS, as shown in the index.css file example above.

Alternatively, if you are using React or some other front-end framwork which prioritize component-based architectures, you may directly compose your components in HTML/JSX:

const Button = () => <button className="p-3 rounded bg-blue-800 text-white">Label<button>