Tetris (Deprecated)

WARNING

We've decided to deprecate Tetris and move towards component libraries that come with styling and interactions as a single element.

Please checkout one of these component libraries to see if it meets your needs:

Tetris is a collection of "atomic" CSS styles based on Bootstrap 4.

All syntax from Bootstrap CSS will generally apply to Tetris. If you want to see which features of Bootstrap are used directly, check out the screen.scss file.

Why Atomic?

Atomic CSS allows us to create a very performant, scalable, and highly reusable CSS style guide across all web projects at Lyft. The style guide can be used on 3rd party hosted pages like the help center, or on very performant apps.

Performance

Atomic CSS increases performance over regular CSS + gzip in a number of ways.

It firstly will be a smaller build in large apps even with the best gzipping since it's defining many classes and not reusing them. Also, not all gzipping is created equally: on projects like www2, we would be gzipping separate CSS files where we aren't building everything into a single file; instead, they're small files that are being loaded when needed by each directive.
There is a single paint cycle, this means we aren't repainting on inline styles vs classes vs ids etc. If everything uses only classes there is only one pass where anything is painted
Atomic CSS scales really well too, we have a single file that stays the same size vs growing out of control as the projects grows

Ease of Use

Prototying and building pages also gets way faster. Instead of having any number of spacings, text sizes, etc, we have filtered it down to a few choices that should be communicated with the design on how to use them. This should hopefully mean that you can easily prototype something with basic html, and not worry about how things will be sized since there are a few limited choices.

We also don't have to worry about selector specificity since everything is the same level of specificity, yay!

Reusability

Each atom is extremely reusable, as it is basically a single css selector + value. Beyond that, since it's pre-built we can reuse it in any number of ways. We can use it on pages that have sophisticated build systems and do tree-shaking where we never link to external pages - or the opposite end where we aren't even hosting the page itself (like the help center).

The ideal use is to have a CDN-cached version that is the same URL across all applications. This would mean that as a user jumps between services / pages, they'll have all of our styles already cached locally.

Installing

Install Tetris into a project using npm. Tetris releases are hosted on a private Gemfury server, under the @lyft scope. To install run:

npm install @lyft/tetris --save

Usage

Tetris should be included and built inside of a service that uses it. The service should include either the tetris.scss file or the specific files needed. The latter can be done in conjunction with webpack to build modular stylesheets.

Documentation

The latest docs are at docs.lyft.net/tetris.

Development

Tetris does not run in a devbox container because it is not a service. It should be included in another service that does run in a container. By locally linking tetris inside that container, it's possible to develop and test Tetris changes in real time.

Set up local link

Edit the ~/.devbox/config file to contain the following (paste it at the end):
```
 [npm]
 @lyft/tetris: tetris
```
Restart your service:
```
 control restart [SERVICE_NAME]
```
Now, any changes made inside the tetris repo will be transferred instantly to the including service. You may need to trigger a build of the service before changes appear in the browser. The specifics will depend on the service.

For more details about the .devbox/config file, see the devbox readme.

New Atoms

When creating new atoms, use KSS to markup the SASS files. This allows for the automatic generation of a styleguide, including example code, from the documentation itself. This is also a great way to test that your styles are working as expected.

Tetris uses kss-node to parse KSS.

Adding dependencies

Use package.json for all dependencies.

To include new dependencies, decide if they're for dev or production use, and install via npm accordingly:

npm install PACKAGE [--save] [--save-dev]

Styleguide

Building a local version of the styleguide allows you to test your KSS changes, and ensure that new atoms are displayed correctly.

Set up the development environment:
```
npm install
```
Build styleguide assets:
```
npm start
```
Or use the watcher:
```
gulp watch
```
View the styleguide:

You will now have a local web server hosting the styleguide at http://localhost:3000/.

Search

Everything you need to know about the full-text search in Tetris is here and here.

Distributing

To release a new version of Tetris:

Increment the version in package.json so that Gemfury picks up the change. This should be done as part of your PR.

The version is a dot-separated string of the format, M.m.b, where M is a major release, m is a minor release, and b is a bugfix release. See Semantic Versioning.
Merge your branch into master through Submit Queue or GitHub.
Publish a release in Github for the new version. Your release should point to the merge commit. This will trigger a build and push the result to GemFury.

Troubleshooting

npm install fails with a libsass error
```
 Error: The `libsass` binding was not found in /[...]
 This usually happens because your node version has changed.
```
This occurs because the libsass library was compiled under a different architecture than the current one. The most likley reason for this is that Tetris was built in devbox and then it was used from the Mac, or vice-versa. To fix this, try a clean install:
```
 rm -Rf node_modules
 npm install
```