# @apollo/space-kit

> Home base for Apollo's design system

Latest version **9.11.0** (published 2021-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @apollo/space-kit
pnpm add @apollo/space-kit
yarn add @apollo/space-kit
bun add @apollo/space-kit
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 9.11.0 |
| Published | 2021-11-04 |
| First published | 2019-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 17 |
| Unpacked size | 3.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 90 |
| Maintainers | apollo-bot |

## Links

- npm: https://www.npmjs.com/package/@apollo/space-kit
- Repository: https://github.com/apollographql/space-kit
- Homepage: https://github.com/apollographql/space-kit#readme
- Issues: https://github.com/apollographql/space-kit/issues
- npm.io page: https://npm.io/package/@apollo/space-kit

## Dependencies (17)

- [tslib](https://npm.io/package/tslib.md) ^2.0.3
- [lodash](https://npm.io/package/lodash.md) *
- [csstype](https://npm.io/package/csstype.md) ^3.0.3
- [downshift](https://npm.io/package/downshift.md) ^6.0.6
- [classnames](https://npm.io/package/classnames.md) ^2.2.6
- [tinycolor2](https://npm.io/package/tinycolor2.md) ^1.4.1
- [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.157
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.12.5
- [@tippyjs/react](https://npm.io/package/@tippyjs/react.md) ^4.2.0
- [@react-aria/focus](https://npm.io/package/@react-aria/focus.md) ^3.1.0
- [@react-aria/utils](https://npm.io/package/@react-aria/utils.md) ^3.1.0
- [@types/classnames](https://npm.io/package/@types/classnames.md) ^2.2.9
- [@types/tinycolor2](https://npm.io/package/@types/tinycolor2.md) ^1.4.2
- [@react-aria/switch](https://npm.io/package/@react-aria/switch.md) ^3.1.0
- [@react-stately/toggle](https://npm.io/package/@react-stately/toggle.md) ^3.1.0
- [use-deep-compare-effect](https://npm.io/package/use-deep-compare-effect.md) ^1.4.0
- [@react-aria/visually-hidden](https://npm.io/package/@react-aria/visually-hidden.md) ^3.1.0

## Recent versions

- 9.11.0 (latest) — 2021-11-04
- 9.11.1-canary.10052.28fc7fa.0 (canary) — 2022-01-19
- 9.11.1-canary.384.10049.0 — 2022-01-15
- 9.11.1-canary.382.10039.0 — 2021-11-04
- 9.10.1-canary.381.10022.0 — 2021-11-04
- 9.10.1-canary.381.10012.0 — 2021-11-04
- 9.10.1-canary.381.10006.0 — 2021-11-04
- 9.10.0 — 2021-10-25
- 9.9.1-canary.9986.9e7a401.0 — 2021-10-25
- 9.9.0 — 2021-09-22
- 9.8.1-canary.9961.3626014.0 — 2021-09-22
- 9.8.1-canary.378.9957.0 — 2021-09-21
- 9.8.0 — 2021-09-15
- 9.7.1-canary.377.9934.0 — 2021-09-15
- 9.7.0 — 2021-09-10
- … 615 more at https://npm.io/package/@apollo/space-kit/versions

## README

<div align="center">
  <img height="100" src="https://i.imgur.com/YPhoQOA.png">
  <h1 align="center">Space Kit</h1>
  <p>The home base for Apollo's design system, Space Kit provides essential design resources for our developers to use in the Apollo-branded interfaces that they create.</p>
  <a href="https://www.npmjs.com/package/@apollo/space-kit" title="@apollo/space-kit npm page">
    <img src="https://img.shields.io/npm/v/@apollo/space-kit.svg">
  </a>
</div>

## Getting started

```shell
npm install @apollo/space-kit @emotion/core @emotion/cache framer-motion
```

## Usage

Import things into your JS app from the `@apollo/space-kit` package. All available exports are documented [here](#exports).

```js
import "@apollo/space-kit/reset.css"; // import this at app root
import { colors } from "@apollo/space-kit";

function MyComponent() {
  return (
    <button
      style={{
        backgroundColor: colors.indigo.dark,
        color: "white",
        border: `1px solid ${colors.grey.light}`,
      }}
    >
      ...
    </button>
  );
}
```

## Exports

### Stylesheet reset

_TODO: Move this to storybook docs_

A "base" stylesheet with a few sensible rules. It uses [normalize.css](https://necolas.github.io/normalize.css/) to smooth out any inconsistencies between the ways that different browsers render elements. It also applies `box-sizing: border-box;` to everything, for [a better element sizing experience](https://www.paulirish.com/2012/box-sizing-border-box-ftw/). Lastly, the stylesheet imports and sets our two main font families: [Source Sans Pro](https://fonts.google.com/specimen/Source+Sans+Pro), and [Source Code Pro](https://fonts.google.com/specimen/Source+Code+Pro).

You'll probably want to include this file once in your app, ideally at the top-most level. For instance, in a Gatsby site that would be your [`layout.js` component](https://www.gatsbyjs.org/docs/layout-components/).

**JS + webpack or similar**

```js
import "@apollo/space-kit/reset.css";
```

**LESS**

```less
@import (inline) "../node_modules/@apollo/space-kit/reset.css
```



#### FAQ

##### My icons aren't showing up in the UI

Make sure that the icon component has a width and height applied to it. That can mean applying classes or styles directly to the Icon component, or setting the component to have `height: 100%` and `width: 100%` and then applying a size to the containing element.

##### Why can't I import from `IconServices` from `@apollo/space-kit/icons`?

My goal was to minimze the bundle size increase caused by using these icons. If I had named exports from `space-kit/icons`, then the user would have to make sure they are tree-shaking to only import the icons they are actually using. `engine-frontend` is _not_ yet tree-shaking, so we decided to not make the imports an option.

##### Why does each icon have a named export instead of a default export?

The engine-frontend team and Apollo OSS teams have decided to not use default exports; this continues that trend.

## Developing Space Kit

Developing locally against Storybook is easy; run `npm run storybook`.

### `npm link`

Run `npm run watch` to watch the entire project for changes and recompile on the fly.

You can use `npm link` to develop Space Kit features directly inside another project with a little bit of work. `npm link` does not work out of the box, however, because of React hooks requiring that the same instance of `react` be used everywhere in an application. We must use the same instance of `React` both in this project and in your consuming project. If you're using webpack, add `resolve.alias` fields to your project's configuration like so:

```js
resolve: {
  alias: {
    // Used for `npm link`'ing to Space Kit
    react: path.resolve('./node_modules/react'),
    // Used for `npm link`'ing to Space Kit
    'react-refresh/runtime': path.resolve(
      './node_modules/react-refresh/runtime',
    ),
  },
},
```

### Tests

We use `jest` and `testing-library` for unit/integration tests and will soon use [Chromatic](https://www.chromaticqa.com/) for visual regression testing.

#### Integration Tests

The hardest part about writing tests is knowing what should be tested and what shouldn't. Test interactions: test whatever you'd  test by hand that would give you release confidence.

A few dos and don'ts:

- DO: Test interactions
- DON'T: test anything that doesn't give you more confidence

    In other words, _do not_ add tests to increase code-coverage.

- DO: [Write test names that explain what is being tested, what input is being given, and what is expected](https://github.com/goldbergyoni/javascript-testing-best-practices#-%EF%B8%8F-11-include-3-parts-in-each-test-name)
- DO: [Write simple tests with no abstractions](https://github.com/goldbergyoni/javascript-testing-best-practices#%EF%B8%8F-0-the-golden-rule-design-for-lean-testing)

Some resources on testing:

- [JavaScript Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
- https://kentcdodds.com/blog/
    - [Avoid nesting when you're testing](https://kentcdodds.com/blog/avoid-nesting-when-youre-testing)
    - [Write fewer, longer tests](https://kentcdodds.com/blog/write-fewer-longer-tests)

### Releases

Releases are handled automatically after merging PRs by [`intuit/auto`](https://github.com/intuit/auto). You can split PRs into a feature branch and then send that as a PR to main; that'll use all the different PRs to create the changelog.

#### Semver

Each PR needs to have a SemVer lable in GitHub so `auto` knows how to . Available labels are:

* `patch` - Increment the patch version when merged
* `minor` - Increment the minor version when merged
* `major` - Increment the major version when merged
* `prerelease` - Create a pre-release version when merged
* `skip-release` - Preserve the current version when merged
* `internal` - Changes only affect the internal API
* `documentation` - Changes only affect the documentation

Use `skip-release` if you don't want an automatic release with your PR.

There is a CircleCI job that checks that an appropriate label is on the PR. It will always fail initially. GitHub actions are set up to re-run the CI check when labels are added or removed. it can be found in [`.github/main.workflow`](./.github/main.workflow).

#### Changelog

The changelog will be updated automatically with the title of your PR used as the line item in the changelog. The sections of the changelog will decided by the labels you gave your PR. If you want to add more information for the changelog, add a `## Release Notes` section in your PR description. https://intuit.github.io/auto/pages/auto-changelog.html#additional-release-notes

### Beta Releases

While local development should be done with [`npm link`](https://docs.npmjs.com/cli/link),sometimes we need to release pre-release versions so you can see the effects of Space Kit changes in your project somewhere you can't use `npm link`, like in a pull request. In that case, there are two options:

1. All Space Kit PRs automatically publish a canary build on `npm` and addd a link to that in your PR description
2. You can build your own canary anytime by running `npx auto canary`

## Resources

- [Space Kit's style guide (Zeplin)](https://app.zeplin.io/project/5c7dcb5ab4e654bca8cde54d/screen/5cd0c46bce9a42346c709328)
- [Engine's style guide (Storybook)](https://storybook.apollographql.com)

---
_Source: https://npm.io/package/@apollo/space-kit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._