npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@mapbox/assembly

v1.8.4

Published

A CSS framework

Downloads

3,631

Readme

Assembly

A CSS framework that makes the hard parts of building anything on the web easy. We define the hard parts as: managing class specificity, designing cross-browser form components that work well with each other, creating a harmonious typographic scale, maintaining a baseline grid, and keeping responsive designs simple.

For usage guidelines and documentation, check out https://labs.mapbox.com/assembly/.

Build Status

Browser support

Assembly targets modern versions of Chrome, Firefox, Safari, and Edge on desktop; Safari on iOS; and Chrome on Android.

Usage

See https://labs.mapbox.com/assembly/ for usage guidelines.

Migration

See our Migration guides to understand what changes you might need to make when upgrading Assembly in your project.

Custom Builds

Assembly exposes a JS module for creating custom builds. Why might you want to create a custom build?

  • You want to customize variables (like colors and font stacks) or media queries.
  • You want to append extra stylesheets that also use Assembly's variables and media queries.
  • You want to reduce file-size by picking and choosing the color variants you need.

buildUserAssets(outdir[, options])

Returns a Promise that resolves when all assets have been written to outdir.

const Assembly = require('assembly');
Assembly.buildUserAssets('path/to/my/outdir', myOptions)
  .then(() => /* something */)
  .catch((err) => /* handle error */);

Options, all of which are optional:

  • files: An array of file paths to stylesheets you would like to append to assembly.css. These will be processed through Assembly's PostCSS pipeline.

  • variables: An object whose properties will override and add to src/variables.json. Use this option to change or add variables. These variables are accessible in any stylesheets you append via the CSS custom properties syntax, e.g. var(--property-name).

  • mediaQueries: An object whose properties will override and add to src/mediaQueries.json. Use this option to change or add media queries. These media queries are accessible in any stylesheets you append via the CSS custom media query syntax, e.g. @media --media-query-name.

  • colorVariants: An object or array specifying the color variants you would like added to assembly.css. This is documented in detail below.

  • icons: An array of icons names to include in Assembly. Names correspond to file names in src/svgs/. Use this option to decrease the size of assembly.js by only including the icons you need.

  • browsersList: A Browserslist array to be used by Autoprefixer. Default:

    [
      'last 4 Chrome versions',
      'last 4 Firefox versions',
      'last 4 Safari versions',
      'last 2 Edge versions',
      'last 2 iOS versions',
      'last 2 Android versions',
      'not IE 11',
      'not dead'
    ]
  • quiet: Suppress logs.

colorVariants option

If the colorVariants value is an array, it must be an array of color names corresponding to variables. All components will have color variants generated for all colors in the array.

The following configuration specifies an array of default colors. All components will have these (and only these) color variants.

["red", "green-light"]

If the colorVariants value is an object, each property value must be an array of color names corresponding to variables. The property names designate which component each color array applies to:

  • default: These colors apply to all components that are not otherwise specified.
  • buttonFill: *-dark colors will not be used.
  • buttonStroke: *-dark colors will not be used.
  • inputTextarea: *-dark colors will not be used.
  • selectFill: *-dark colors will not be used.
  • selectStroke: *-dark colors will not be used.
  • checkbox: *-dark colors will not be used.
  • radio: *-dark colors will not be used.
  • switch: *-dark colors will not be used.
  • toggle: *-dark colors will not be used.
  • range: *-dark colors will not be used.
  • color
  • background
  • link: *-dark colors will not be used.
  • border
  • hoverShadow: Only lighten* and darken* colors will be used.
  • hoverBackground
  • hoverColor
  • hoverBorder

The following configuration specifies colors for individual components. In this configuration, every component not specified will have the default color variants; specified components will have their specified color variants; and switch and range components will have no color variants (only the default will be available).

{
  "default": ["lighten50", "lighten25", "gray"],
  "buttonFill": ["green", "purple"],
  "selectFill": ["green"],
  "background": ["orange", "yellow", "pink"],
  "link": ["orange"],
  "hoverShadow": ["lighten50"],
  "switch": [],
  "range": []
}

Development principles

Writing rules

Assembly strives for flat, single rule declarations and avoids overrides whenever possible. Declarations are marked as !important for classes whose names directly correspond with what they do — e.g. bg-blue, px12. This way they cannot be overridden and so are guaranteed to actually do what they say they do.

Naming classes

  • Keep names as short as reasonable.
  • Use real number values in utility class names to describe the value the utility class applies in cases where the number of utility classes describing a particular property could be unlimited. For example, .pt6 for padding-top: 6px instead an abstract scale like .pt-small or .pt-1.
  • If the number of utility classes describing a property is limited and the variants are about size, Assembly classes use the suffixes xl, l, m, s, sm.
  • Assembly provides a reset that will affect the entire page, but other than that reset none of its rules should affect the styling of elements that don't bear Assembly classes.

Media query class variants

Media query class variants (e.g. block-mm as a variant of block) are automatically generated and added to the CSS build with scripts/build-media-variants.js. If you want to generate media variants for a new class, or change which classes get media variants, you'll need to modify the lists in that file.

Development

Tools

Install and start

npm ci # Installs your `node_modules`

npm start # Builds everything, starts a dev server, rebuilds & reloads on changes

npm run build:js # Build SVGs and other JS

For other scripts, look in package.json.

Releasing

Development is done in the publisher-staging branch, but releases are made from the publisher-production branch. Here's how you cut a release:

  • From publisher-staging:
    • Document changes in the CHANGELOG.
    • Increment the version key in package.json and package-lock.json.
    • Make sure all this is committed, typically with a commit message like Prepare 0.8.0.
    • Merge these changes into the publisher-production branch. Conduct the following steps from publisher-production.
  • From publisher-production:
    • Create a tag. No message is necessary, since the changelog includes explanations of changes. For example: git tag -a 0.8.0 -m "".
    • Push the tag: git push --tags.
    • Publish the new version on npm: mbx npm publish
    • Deploy the changes. Talk to @mapbox/frontend-platform if you need help.