@heights/heights-ui

import { theme } from '@heights/heights-ui'

Components

import {
  AppLink,
  ButtonDown,
  Carousel,
  CommunityTake,
  ContentHighlight,
  Experts,
  Hero,
  FeatureCard,
  Features,
  Footer,
  IconLink,
  IconPicker,
  Nav,
  SmartCard,
  SocialLinks,
  SubscribeForm,
} from '@heights/heights-ui'

Source files are located in the src/components directory.

Icons

import { Logo } from '@heights/heights-ui'

Source files are located in the src/icons directory.

Utils

import { bgColourPicker, BackgroundColours } from '@heights/heights-ui'

Source files are located in the src/icons directory.

Theme

The theme can be imported like so:

import { theme } from '@heights/heights-ui'

Source files are located in the src/theme directory.

Overview

The package is heavily reliant on Theme UI. Many of the components and styles need Theme UI in order to work.

Understanding Theme UI

Theme UI provides a constraint-based approach to component creation and theming. This allows you and your team to create a design system that supports the widest

To fully understand Theme UI and all that it provides, please read and understand the documentation at https://theme-ui.com/getting-started.

Using the theme

The theme matches Theme UI's specifications, so includes all the colour, font, sizing and spacing information that your app should need.

All theme-related files are located in the src/theme directory.

Add the theme to your application with the ThemeProvider, passing in the theme object as a prop.

import React from 'react'
import { ThemeProvider } from 'theme-ui'
import { theme } from '@heights/heights-ui'

export default (props) => (
  <ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)

Style your UI

This is an example of how a new component could be created without using Emotion's styled.div syntax. Read more about this method in the Theme UI docs.

/** @jsx jsx */
import { jsx } from 'theme-ui'
import { FunctionComponent } from 'react'

export const Title: FunctionComponent = ({ children }) => (
  <h1
    sx={{
      color: 'primary',
      fontFamily: 'heading',
    }}
  >
    {children}
  </h1>
)

Theme UI components

Theme UI includes pre-built UI components to make styling a page with Theme UI more quickly. The theme-ui package includes components for layouts, grids, buttons, form elements, and more.

import { Box } from 'theme-ui'

export const SomeComponent = (
  <Box
    sx={{
      color: 'white',
      bg; 'primary',
      p: 4,
    }}
  >
    Beep
  </Box>
)

Find out more in the Theme UI component docs.

Code

Files and naming

Test files use *.test.ts(x) or *.spec.ts(x)

Any file with *.story.tsx or *.stories.tsx, or *.story.mdx or *.stories.mdx can be used by Storybook. The *.mdx extensions are used for documentation.

Anatomy of a component directory

E.g. a Button found in the /src/components directory.

// src/components/button
.
├── Button.tsx        // < component code
├── README.md               // < component documentation
├── Button.story.tsx  // < component story
├── Button.test.tsx   // < component tests
├── Button.models.ts  // < component tests
├── __snapshots__           // < auto-generated snapshot files
└── index.ts                // < component entry file

Core tools and technologies

• React
• TypeScript
• Components
  • Theme UI - Build consistent, themeable React apps based on constraint-based design principles.
  • Emotion - CSS-in-JS library used by Theme UI
• Component sandboxes
  • Storybook - Storybook is a tool for developing UI components in isolation. It makes building stunning UIs organized and efficient.
• Testing
  • Jest - testing framework
  • React Testing Library
  • Jest Axe - Custom Jest matcher for aXe for testing accessibility ♿️
• Compilation/Bundling
  • Preconstruct - Module bundler based on Rollup and various other technologies
  • Babel
• Linting & formatting
  • ESLint

Build and compilation

The package uses Preconstruct to bundle all its source code. Please consult their docs if you need to update/improve the build process.

Build scripts and commands

• yarn build: Compile a production build
• yarn build:dev: Compile a development build
• yarn storybook: Run Storybook development environment
• yarn format: Format all JS with Prettier
• yarn lint: Lint JS
• yarn size: Test the file size of the build
• yarn test: Run all tests
• yarn test:js: Run all JS tests with Jest
• yarn test:coverage: Run a code coverage test with Jest
• yarn test:watch: Run test suite while watching for changes
• yarn release: Publish a new package version to npm

Tooling

The design system uses various tools to ensure better code quality. Defaults have been set for linting and code style, but can easily be overridden according to your needs.

• Prettier
• Eslint
• Husky
• lint-staged

Workflow

Commits and Pull Requests

All git commits and pull request titles should follow the Conventional Commits method. This will allow our release script to correctly bump the package version number appropriately.

Publishing new versions to npm

Running npm run release while on an up-to-date and clean master branch will update the GitHub release and publish to npm.

License

MIT