Assembly.css

v1.5.1

Assembly is an atomic CSS framework with great default form element styles. Use it, and your team will never have to write CSS again.

Getting started

Include in the head of your HTML the Assembly stylesheet.

<link href="https://api.mapbox.com/mapbox-assembly/v1.5.1/assembly.min.css" rel="stylesheet">

Include the Assembly JavaScript anywhere in your HTML. It is safe to use the async and defer attributes. See Javascript API for details.

<script async defer src="https://api.mapbox.com/mapbox-assembly/v1.5.1/assembly.js"></script>

HTML Template

Get started right away with this bare-bones HTML template.

<!DOCTYPE html>
<html lang='en'>
<head>
  <title><!-- Your title goes here --></title>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <link rel='shortcut icon' href='Your favicon path goes here' type='image/x-icon'>
  <link href='https://api.mapbox.com/mapbox-assembly/v1.5.1/assembly.min.css' rel='stylesheet'>
  <script async defer src='https://api.mapbox.com/mapbox-assembly/v1.5.1/assembly.js'></script>
</head>
<body>
  <!-- Your page... -->
</body>
</html>

Unsure what else you need in the <head>? Check out MDN's detailed guide.

Philosophy

Comprehensive

Assembly includes everything you need to fully implement responsive, colorful web pages, web apps, dashboards, and more.

Flexible

The core of Assembly is a set of composable, atomic utility classes covering most of your styling needs.

Practical

Complete reliance on atomic design can slow down development and foster inconsistency and bad UX. Assembly inserts the right opinions in the right places.

Customizable

Assembly exposes its build process in a public API. Customize colors, fonts, and media queries; append your own stylesheets; and specify color variants to reduce file size.

Overview

Classes and modifier classes

A double-hyphen in a class name (e.g. border--blue) indicates that the class is a modifier class. A modifier class extends the class whose name precedes the double-hyphen (e.g. border--blue modifies border; flex-child--grow modifies flex-child). And modifier classes should only ever be used in combination with the class they modify: modifier classes will not work well on their own.

6 pixel baseline grid

Every element in Assembly is designed according to a 6 pixel baseline grid, even buttons and form components. Baseline grids don't just make your site look and feel better: they also make development more convenient. All the pieces naturally fit together without fiddling with line height or vertical alignment.

No default styling for semantic elements

You should use <h3> for third-level headings, not because you want a certain style. Similarly, you should use <button> when a button is behaviorally and semantically appropriate, instead of href-less <a> tags or other elements with click handlers.

Assembly's reset allows you to use semantically appropriate HTML without battling browser-default styles. And its CSS rules are built to behave the same regardless of which element they're applied to. A heading style, or a button style, can be applied to any element by applying the appropriate classes.

Customizable icons

Assembly comes with more than 150 icons, intended to be used as inline SVGs. Inline SVGs are easy to resize and color.

Media queries are mobile-first

Mobile-first media queries lead to cleaner code because there are fewer overrides. Start with a simple mobile layout, then add complexity with additional media-constrained rules. Assembly uses the following media queries:

  • Extra large screens: screen and (min-width: 1200px)
  • Large screens: screen and (min-width: 800px)
  • Medium screens: screen and (min-width: 640px)

Classes that take affect within certain media queries always end with a -m<size> suffix, where "size" is m, l, or xl.

Utility classes have maximum specificity

Assembly uses !important on declarations whose effect directly corresponds to a class name.

For example, in the .bg-blue rule, the background-color declaration is !important. On the .pl20 rule, the padding-left declaration is !important. This ensures that such classes always behave the same. Whenever you see the class bg-blue on an element, that element should have a blue background, regardless of its context and the other rules that apply to it.

For dynamic styles, responsive classes (described above) provide some additional flexibility. But if you need even more, you should use custom CSS instead of a utility class.

More intuitive box model

The border-box box model allows for more intuitive styling than the default content-box model. For example, when you set a w360 class, your element will always be 360 pixels wide, regardless of its padding and borders.

is-active applies active states

Assembly uses the is-active state class to designate that an element is active and style it accordingly.

The is-active state on buttons and links darkens their color. And the *-on-active state classes (e.g. only color-red-on-active) only take effect when combined with the is-active class.

Focus outlines as needed

Assembly turns off focus outlines when you mousedown and turns them back on, universally, when you hit Tab. This means that only the keyboard users who need them will see nice, prominent focus outlines, while mouse users won't have the design disturbed unnecessarily.

Javascript API

By importing assembly.js into your html page, you gain access to a set of functions on a global Assembly namespace.

Focus state

assembly.js adds event listeners that show and hide focus states depending on whether user is navigating with a keyboard or with a pointer device. If focus state is on, an outline appears around focused elements. If focus state is off, no outline appears. The Javascript API allows you to programmatically override this focus state.

Assembly.setFocusState(enable?: boolean): void

Turn focus state on or off. Inverts focus state if called with no argument.

Icons

Use these function to add icons to the page or edit them programmatically.

Assembly.createIcon(iconName: string): SVGElement

Returns an SVG element containing a <use> element referencing the designated icon.

Throws an error if the designated icon does not exist in Assembly.

Assembly.changeIcon(iconEl: SVGElement, iconName: string): SVGElement

Given an icon SVG element (not the <use> element inside it), such as what Assembly.createIcon returns, changes the icon and returns the SVG element.

Throws an error if the designated icon does not exist in Assembly.

Assembly.iconExists(iconName: string): boolean

Returns a boolean indicating whether an icon exists in Assembly.