You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Once installed as a dependency, you need to integrate Gravity into your project's build. The [Gravity UI library NPM package](https://www.npmjs.com/package/@buildit/gravity-ui-sass) ships with the following files:
51
+
52
+
***Pre-compiled CSS file**
53
+
* The SASS source from which the CSS was compiled
54
+
***An SVG file** containing symbol definitions for all Gravity SVG icons
55
+
* A JSON file containing metadata about the individual SVG icons
56
+
***Pre-compiled client-side JS file**
57
+
58
+
You must integrate these into your own project builds as follows:
59
+
60
+
#### CSS styles
61
+
You need to get Gravity's CSS into your website or app somehow. Possible strategies include:
62
+
63
+
* Copying Gravity's pre-compiled CSS file to your build output and linking to it from your HTML.
64
+
* Combining Gravity's pre-compiled CSS with your own CSS code.
65
+
* You can keep them in separate CSS files and link to them individually from your HTML, or you can concatenate the CSS.
66
+
* Whichever way you choose, **Gravity's CSS must come first** since it includes normalisation rules and sets global default styles.
67
+
* Compiling Gravity's SASS source to CSS yourself.
68
+
* By itself this is probably pointless (just grab the pre-compiled CSS!), but when adding your own, bespoke styling on top of Gravity this is useful. As with the CSS, you should ensure that Gravity's rules come first in the output. In practice, this amounts to making sure `@import "gravity-ui-sass";` is the first statement in our main SASS file.
69
+
* Embedding Gravity's CSS in a bundle
70
+
*`import`ing Gravity's CSS or SASS into a JS bundle (with the appropriate loaders setup) is a perfectly valid approach
71
+
* However, you should **avoid using tools that mangle the CSS class names** (e.g. [CSS Modules](https://github.com/css-modules/css-modules)). Gravity's CSS is designed to be global. Attempting to scope it is not supported and may well break things. If you do this, you're on your own.
72
+
* That being said, for any _additional_ CSS rules you add _after_ the Gravity ones, you are of course free to use whatever tool or approach you like.
73
+
74
+
If your chosen approach uses Gravity's pre-compiled CSS, you **must use the [build API](./docs/build-api.md)** to grab the file's path and/or filename.
75
+
76
+
If your chosen approach uses Gravity's SASS sources, you are encouraged to use [Eyeglass](https://github.com/linkedin/eyeglass) to avoid needing to manually configure `includePaths`. If Eyeglass is not an option, then you **must use the [build API](./docs/build-api.md)** to grab the path and/or filenames for Gravity's SASS files.
77
+
78
+
79
+
#### SVG symbols
80
+
Currently, Gravity's SVG symbol definitions need to be inlined into your HTML. Then, whereever you want to _use_ one of the available icons or logos, you should use an inline SVG that references the required symbol's `id` like so:
81
+
82
+
```html
83
+
<svg
84
+
role="img"
85
+
aria-labelledby="buildit-logotype__title"
86
+
width="300"
87
+
height="33"
88
+
>
89
+
<usexlink:href="#buildit-logotype"></use>
90
+
</svg>
91
+
```
92
+
93
+
The `height` and `width` properties should be set to ensure that your inline SVG's intrinsic size matches the aspect ratio of the referenced symbol. If you omit them, browsers will [default to a width of `150px` and a height of `100px`](https://www.sitepoint.com/replaced-elements-html-myths-realities/) and the chosen symbol will appear centered within that area.
29
94
30
-
In your own SASS you can then include Gravity like so:
95
+
The `aria-lebblledby` should be set to provide a text alternative for the SVG (equivalent to `alt` in `<img>` elements). All of Gravity's SVG symbol definitions contain alternative texts in their `<title>` elements and these have unique `id`s, so that they can be referenced from elsewhere via `aria-lebblledby`.
31
96
32
-
```sass
33
-
@import 'gravity-ui-sass';
97
+
You can look up these values manually in [Gravity's pattern library](http://style.buildit.digital/?p=particles-svg-symbols). For convenience and possible automation, Gravity also ships with a JSON file that contains the symbol and title IDs and the intrinsic width and height values for every available symbol. The format of this file is as follows:
98
+
99
+
```js
100
+
{
101
+
"symbols": [
102
+
{
103
+
"symbolId":"buildit-logo-hollow",
104
+
"titleId":"buildit-logo-hollow__title",
105
+
"width":"700px",
106
+
"height":"700px"
107
+
},
108
+
// ...
109
+
]
110
+
}
34
111
```
35
112
36
-
You can view all the available UI components in the [Buildit Living Style Guide](http://style.buildit.digital/).
113
+
As with the CSS, you **must use the [build API](./docs/build-api.md)** to grab the path and/or filename(s) to Gravity's symbols SVG file and symbol info JSON file.
114
+
115
+
#### JS
116
+
117
+
_TBD_ (Currently, Gravity is first and foremost a CSS library. It is however likely that future releases will add some kind of JS for interactive UI components. When that happens, this section will be updated accordingly)
118
+
119
+
120
+
### Usage
121
+
Once the Gravity library has been integrated into your build, all you need to do is **produce the appropriate DOM elements**. You can view all the available styles and UI components in the [Buildit Living Pattern Library](http://style.buildit.digital/). Use the "Show pattern info" option to view the Nunjucks template and rendered HTML for the component you are viewing.
122
+
123
+
124
+
125
+
You need to recreate the same HTML DOM structure in your project (via static HTML, dynamically via JS or a combination of both - it doesn't matter), and you will get the same appearance.
126
+
127
+
This is pretty much the same process as using other UI libraries like [Bootstrap CSS](https://getbootstrap.com/) or [Semantic UI](https://semantic-ui.com/). There is one very important difference though: Those libraries tend to use class names exclusively to bind the CSS styles to your markup, meaning that the actual HTML element used rarely matters. For example, in Bootstrap `<button class="btn btn-primary">` and `<span class="btn btn-primary">` will both produce the same _visual_ result.
128
+
129
+
**Gravity on the other hand often mandates that certain HTML elements or attributes are used**, and sometimes doesn't use classes at all (the equivalent to the Bootstrap primary button example in Gravity would simply be `<button>`). The intention is to promote semantically correct, accessible HTML. An additional benefit is that this often makes markup code is more terse as well.
130
+
131
+
As a general rule you must therefore ensure that you match:
132
+
* The HTML element used
133
+
* The attributes used (if any) - not only `class`, but others like `type`, `aria-*`, etc. as well
134
+
* For composite "molecule" or "organism" components you must also match the way they have been nested - i.e. don't introduce additional wrappers within the component
135
+
136
+
Each component also has notes (shown in the pattern info panel) which describe what it should be used for and other noteworthy information.
37
137
38
138
39
139
## Development
@@ -43,35 +143,35 @@ You can view all the available UI components in the [Buildit Living Style Guide]
43
143
1. Clone this repo: https://github.com/buildit/gravity-ui-sass
44
144
1. Run `npm install` to install all the dev dependencies
45
145
46
-
### Building and running the style guide locally
146
+
### Building and running the pattern library locally
47
147
48
-
We use Pattern Lab to generate our [Buildit Living Style Guide](http://style.buildit.digital/). During development, it's useful to build and run the style guide locally via:
148
+
We use [Pattern Lab](https://patternlab.io/) to generate our [Buildit Living Pattern Library](http://style.buildit.digital/). During development, it's useful to build and run the pattern library locally via:
49
149
50
150
```bash
51
151
$ npm start
52
152
```
53
153
54
-
This should also open the style guide in your default web browser. In any case, the URL will be listed in the console output. By default it is: http://localhost:3000/
154
+
This should also open the pattern library in your default web browser. In any case, the URL will be listed in the console output. By default it is: http://localhost:3000/
55
155
56
156
The local server will then also watch source files under `src/` for changes and automatically trigger rebuilds & browser refreshes as necessary.
57
157
58
158
59
-
### Building the style guide
159
+
### Building the pattern library
60
160
61
-
To only build the style guide (which is, in effect, a static HTML website) but _not_ run a local server, do:
161
+
To only build the pattern library (which is, in effect, a static HTML website) but _not_ run a local server, do:
62
162
63
163
```bash
64
164
$ npm run styleguide
65
165
```
66
166
67
-
Note that this will _also_ build the UI library. The build output will go into `dist/`. You can view the style guide locally by opening `dist/index.html` in your browser.
167
+
Note that this will _also_ build the UI library. The build output will go into `dist/`. You can view the pattern library locally by opening `dist/index.html` in your browser.
68
168
69
169
This is mainly intended for automated build and deployments to our hosted [Buildit Living Style Guide](http://style.buildit.digital/).
70
170
71
171
72
172
### Building the UI library only
73
173
74
-
To only build the UI library (without the style guide), use:
174
+
To only build the UI library (without the pattern library), use:
75
175
76
176
```bash
77
177
$ npm run build
@@ -92,7 +192,7 @@ in this way may cause your PR to be rejected.
@@ -106,7 +206,7 @@ To be able to run `npm ci` on your machine, and to be sure to create a `package-
106
206
107
207
`.nvmrc` only allows us to specify Node.js version, but that alone is not enough at the moment, since Node.js 8 comes out of the box with npm version 5.6.0.
108
208
109
-
### Further Information
209
+
### Further information
110
210
*[Release process](./docs/releasing.md)
111
211
*[Travis CI setup](./docs/travis-ci.md) (for automated build & deplpoyments)
The `@buildit/gravity-ui-sass` NPM package provides a Node.js API for build scripts to use. It provides file names and paths to the relevant assets contained in the NPM package, as well as useful metadata about the package.
4
+
5
+
Projects that use Gravity's UI library are **strongly encouraged** to use this API within their build scripts (e.g. [Gulp](https://gulpjs.com/) files or [Webpack](https://webpack.js.org/) configs), instead of hard-coding paths like `../node_modules/@buildit/gravity-ui-sass/some/file.ext`. The build API is part of this package's public API surface, but the actual assets file names and locations are not. So, if `gravity.css` was renamed to `foo.css` in a future release, that would _not_ be considered a breaking change. However, renaming or remoing the `distCssFilename` property of the build API _would_ be a breaking change.
6
+
7
+
⚠️ **Note:** The build API is strictly intended for build-time scripts and tools. It should never be embedded into your actual build artefacts.
8
+
9
+
## Using the API
10
+
Simply `require()` (or `import`) `@buildit/gravity-ui-sass/build-api` and then use the properties and functions of the object you receive:
⚠️ **Note on SASS compilation:** When compiling your own SASS, it may be tempting to simply point the SASS compiler at `gravityPaths.srcSassMainFilename` (or to add `gravityPaths.srcSassPath()` to Node SASS's `inludePaths` and then `@import "gravity-ui-sass";` in one of your own SASS files). However, this alone will not work. Gravity's SASS depends on a few external SASS libraries (`@buildit/gravy`, `modularscale-sass` & `normalize-scss`). You must therefore ensure that each library's SASS directory is also added to the Node SASS's `includePaths` option.
88
+
89
+
Note that Gravity itself and all of those SASS libraries support [Eyeglass](https://github.com/linkedin/eyeglass) which avoids the need to manually set the `includePaths` like that. We therefore recommend using Eyeglass to simplify your SASS build configuration.
0 commit comments