@core-ds/primitives

• Reference

Installation

npm install @core-ds/primitives

Usage

JavaScript

After installing the @core-ds/primitives npm package, you can import and apply it in any JavaScript/TypeScript file:

import styled from "styled-components";
import { color, space } from "@core-ds/primitives";

const Example = styled.div`
  color: ${color.white};
  background-color: ${color.blue[500]};
  padding: ${space[4]};

  &:hover {
    background-color: ${color.blue[800]};
  }
`;

LESS

LESS Core Primitives are globally available in every LESS file in the iFixit/ifixit repo:

element {
  color: @color-white;
  background-color: @color-blue-500;
  padding: @space-4;

  &:hover {
    background-color: @color-blue-800;
  }
}

See the complete list of LESS variables here.

CSS Custom Properties (Variables)

CSS Core Primitives are globally available on the :root (html) element. They can be used in any (P)HTML file:

/* excerpt from core-primitives.css */
:root {
  --color-black: #11161a;
  --color-white: #fff;
  ...
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-blue-700: #1d4ed8;
  --color-blue-800: #1e40af;
  ...
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 24px;
  ...
}

/* style the element */
element {
  color: var(--color-white);
  background-color: var(--color-blue-500);
  padding: var(--space-4);

  &:hover {
    background-color: var(--color-blue-800);
  }
}

See the current list of CSS Custom Properties here.

For more capabilities, check out the MDN Custom Properties article

Contributing

Local development setup

Follow these steps to get the project setup on your local machine:

# Clone repo
git clone https://github.com/iFixit/core-primitives.git && cd core-primitives

# Install dependencies
npm install

Adding or Updating Primitives

1. Create a new branch

Create a new branch for your changes:

git checkout -b <branch>

2. Commit and push changes

Apply your changes to index.json, and keep index.d.ts in sync.

3. Test your build

Run npm run build and verify core-primitives.css and core-primitives.less are correct.

4. Open a pull request

Use GitHub to create a pull request for your branch.

5. Bump the package version

After your pull request has been approved, bump the package version by running:

npm version [major | minor | patch]

Running npm version will build, bump the version, and write the new data to package.json and package-lock.json. It will also create and push a version commit and tag.

Note: In the context of @core-ds/primitives, significant changes to the library or workflow, or removing primitives would be considered a major update, adding or updating primitives would be considered a minor update, and fixing primitives would be considered a patch. Non-code changes (e.g. documentation) do not require a version bump.

6. Publish to NPM

npm publish

7. Create a release

After your pull request has been merged, create a new release to document your changes. Use the tag you generated in step 4 to create the release.

Done 🎉