NOTES

This package NorthStar legacy (aws-northstar) entered maintenance on April 1, 2023. On April 1, 2024, support will end for NorthStar legacy.

A new version of NorthStar, NorthStar v2 (@aws-northstar/ui) has been released and improves upon the previous version by leveraging Cloudscape Design System and with updates to the existing components with new features that make the development experience even better.

Please refer to migration guides on the NorthStar v2 website for information how to migrate you applications from NorthStar legacy to NorthStar v2.

NorthStar - Prototyping Design System

NorthStar is an open source design system with reusable React components for rapidly prototyping intuitive, meaningful and accessible user experience. It simplifies your work and ensures consistent, predictable user experience at scale for your customers. With NorthStar, you can focus on innovation and do more with less.

Whether you are a developer or a designer, NorthStar will help you delight your customers from inception to prototype.

With NorthStar, you can easily design and develop your UI applications.

Before you start

Before you start using NorthStar for your project, please note that:

• NorthStar currently only supports the React framework. It supports the most recent versions of React, starting from 16.12.0.

• NorthStar supports the latest, stable releases of modern browsers - Chrome, Firefox and Safari.

• NorthStar should be used as a rapid prototyping and design tool to ensure a consistent and repeatable design for your applications. Whilst NorthStar has been built from the ground up using best practices, you should carefully consider the use of NorthStar in a production environment.

• NorthStar is shipped with the Apache 2.0 License.

Installation

Use in your React Project

// with npm
npm install aws-northstar

// with yarn
yarn add aws-northstar

Please refer to the Examples session for an example project built by Create React App.

Setup

At the very top of your application, import the NorthStarThemeProvider component and render the NorthStarThemeProvider component.

import NorthStarThemeProvider from 'aws-northstar/components/NorthStarThemeProvider';

export default () => (
    <NorthStarThemeProvider>
        ...redux provider, Apollo client provider, react router...
    </NorthStarThemeProvider>
);

Font Family

The default font family at NorthStar is "Roboto", "Helvetica Neue", "HelveticaNeue", "Helvetica", "Arial", sans-serif. The Roboto font will not be automatically loaded by NorthStar. Roboto is used if it has been installed in users' browsers. Otherwise, the next fallback font Helvetica Neue is used. If you want to ensure Roboto font is in place, you can add:

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />

to the header of your public index.html file to instruct the browser to load the font from CDN.

Usage

Here is a quick example to get you started:

import React, { FunctionComponent } from 'react';
import Button from 'aws-northstar/components/Button';

const MyComponent: FunctionComponent = () => (
    <Button variant="primary">Hello World</Button>
);

export default MyComponent; 

This documentation website has detailed examples on how to use each component.

To learn React, check out the React documentation.

Examples

Create React App

This example demonstrates how you can setup NorthStar in a React application created by Create React App.

Download the example:

mkdir northstar && cd northstar
curl https://northstar.aws-prototyping.cloud/examples/create-react-app.tar.gz | tar -xz

Install it and run:

yarn
yarn start

CodeSandbox

You can use this CodeSandbox template to create a sandbox to play around with NorthStar components.

Support

We use GitHub Issues as a bug tracker. If you think you have found a bug, please follow the Submitting bugs section in the Contribution Guide and open an issue with detailed information about the issue.

Sourcecode

If you are interested in our source code, our repo is at https://github.com/aws/aws-northstar.

We welcome your contribution to NorthStar. Please check our Contribution Guide for more details. As a community run project, we rely on your contribution.

Changelog

Check out the Changelog