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 updatefollowed 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.
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:
<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:
@importonly 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!