Gravity aims to make it easy to apply its look and feel to your websites and web apps. It provides ready-made CSS and JavaScript* that you can integrate into your project. For simple projects you only need to produce appropriate HTML markup and don’t need to write any of your own CSS or JavaScript. Your markup can come from static HTML files, be server-side rendered by a CMS, be generated client-side by JavaScript or any combination of those - the only requirement is that the resulting DOM is structured as mandated by this pattern library.
Gravity aims to enourage semantic, accessible and lean markup. Many of its CSS styles therefore target HTML elements and attributes rather than relying entirely on class names as many other UI libraries do. Our CSS is also architected such that, as much as possible, UI components automatically adapt their appearance to the context they are used within. Therefore, when copying the HTML structures shown in this pattern library, pay attention to the elements, all of their attributes and how they are nested. If in doubt, consult the notes for that component or contact the Gravity team for help.
As a general rule, when working with Gravity you should follow this process:
The recommended way to add Gravity to your web project is to install our @buildit/gravity-ui-web
NPM package as a dependency and wiring it into your build. Refer to the Web UI library’s documentation for detailed instructions on how to do this.
The benefits of this approach are:
npm update
followed by a rebuild will bring the latest and greatest Gravity styles into your project. Major releases will contain breaking changes, so you may need to modify your own code in order to upgrade to them. Consult the release notes for details. We aim to keep breaking changes to a minimum, so this should be a rare occurence.require()
or import
Gravity’s build API into your JavaScript-based build tools (Gulp, Webpack, etc.) to access file and directory paths to all the resources the library provides.Alternatively, Gravity releases are also published to a CDN, so you can simply link to those from your HTML. For example, to get the latest 2.x release you can use:
<!DOCTYPE html>
<html lang="en">
<head>
...
<!-- Link to CDN-hosted copies of Gravity's CSS & JS -->
<link rel="stylesheet" href="https://static.buildit.digital/gravity-ui-web/v2.x/gravity.css">
<script defer src="https://static.buildit.digital/gravity-ui-web/v2.x/gravity.js"></script>
...
</head>
...
</html>
This approach may suffice for very basic projects. It is also useful for prototypes and demos, e.g using CodePen.
Gravity’s CSS is not designed to work alongside other frameworks. If, for instance, you have an existing website or app and you try to drop in individual Gravity UI components or layer on Gravity’s CSS, the result will be highly unpredictable. Similarly, some of Gravity’s core CSS styles are likely to interfere with 3rd party UI components being embedded into a Gravity app.
However, there are some options for applying some of Gravity’s core visual attributes (colors, typography, spacing, etc.) to your UI:
@buildit/gravity-particles
NPM package exposes Gravity’s design token values, such as individual colors, as SASS variables and also as JavaScript constants. You can therefore pull those values into your code and use them to theme your UI.@import
only Gravity’s “settings” and “tools” layers. When compiled, they will not output any CSS, but they do give you access to all of Gravity’s SASS variables, functions and mixins. You can then use these to theme or customise your own CSS code.If you need help integrating Gravity into your project, have special requirements, feature requests or are facing blockers please get in touch with us!
*) Currently, Gravity only provides some minimal JavaScript. However, the amount of JS is expected to grow in future releases to support more interactive components (e.g. collapsing sections, accordions, complex form inputs, etc.).