Education Design System

Education Design System (EDS) is a repository of presentational components used to build React-based products for Chan Zuckerberg Initiative.

Setup

First install the package.

# via npm
npm install --save @chanzuckerberg/eds

# or, if using Yarn
yarn add @chanzuckerberg/eds

We currently use Arimo as our base font. This package does not export it, so you will need to import this separately. We recommend importing from Google Fonts into a top-level CSS file:

@import url('https://fonts.googleapis.com/css2?family=Arimo:wght@400;500;600&display=swap');

and setting up base font settings:

html {
  font-size: 16px;

  /* or if using Tailwind:
  @apply text-base */
}

body {
  font-family: Arimo, sans-serif;

  /* or if using Tailwind:
  @apply font-arimo */
}

Usage

Import any of the components from this package

import { Heading } from '@chanzuckerberg/eds';

and then use them in your React components

<Heading variant="neutral" size="h2">
  Coffee!
</Heading>

Flow types

For any component, run

yarn generateFlowTypes <Component>

to get automatically generated flowtypes.

We use a combination of flowgen and common React mutations to get the best automatic types possible, but manual fixing may still be required. Thus, we recommend maintaining a flow-typed file with libdefs.

// declare a module for each component
declare module '@chanzuckerberg/eds/lib/<Component>' {
  ...
}

// re-declare each component from a root-level index
declare module '@chanzuckerberg/eds' {
  declare export var <Component>: $Exports<"@chanzuckerberg/eds/lib/<Component>">;
}

When translating your generated flow types to this flow-typed file, you will need to:

Update React type imports to follow import type { ... } from "react"
Update internal type imports to be from "@chanzuckerberg/eds/lib/..."
Update ForwardRef components. For example:

declare var x: React.ForwardRefExoticComponent<{
  ...Props,
  ...React.RefAttributes<HTMLElement>,
}>;

should become:

import type { AbstractComponent } from 'react';
declare var x: AbstractComponent<Props, HTMLElement>;

Preserve exact-typed objects when possible. If you must make them inexact, add an explicit ... at the end of the object.

Development

Requirements

Node - if using nodenv, you can install the right version with nodenv install
Yarn - install through either npm (npm install -g yarn) or homebrew (brew install yarn)

Helpful commands

Description	Command
Install dependencies	`yarn install`
Run linter	`yarn lint`
Run linter and fix all fixable issues	`yarn lint:fix`
Build package	`yarn build`
Run the component generator	`yarn create-component`

Icons

Publishing

Working with the codebase

Please refer to the following documentation to learn how to work with this codebase:

Workflow

Contribution guidelines - Please refer to these guidelines to learn how to contribute to the library.
Release guidelines - Please refer to these guidelines for instructions on how to publish a new version of the library.

Support

For questions, feature requests, bugs, and more,feel free to reach out in #help-edu-design-system or office hours if you have additional questions (note: these resources can only be accessed by CZI employees).

Project Status

This project is under active development. If you would like to contribute, check out the contribution guidelines or open an issue.

This project is governed under the Contributor Covenant code of conduct.

Reporting Security Issues

See our Security Readme.

dcwither/edu-design-system