Develop

Get up to speed quickly and start building better experiences for your users using the Mesh Design System.

Setup

All mesh packages are hosted on the npm registry. To get started, ensure you have access to both the @nib and @nib-components packages. If you need access, request it by posting your npm account email and username in the #frontend Slack channel. Accounts must have two-factor authentication (2FA) enabled to be added to our npm orgs.

You will receive an invitation email for the above mentioned packages, and it's important to accept it. After acceptance, authenticate to npm registry by running the command npm login. This will trigger the verification process. Upon successful verification, a .npmrc configuration file will be created in your home directory, containing a valid personal access token for the npm registry.

Additionally, our latest theme package depends on @nib-group/design-tokens, which is hosted in the GitHub Package Registry. There are few ways of setting up access to Github packages:

rqp-cli

rqp-cli streamlines authentication to npm organizations, enabling seamless access to Mesh packages. Please follow the rqp-cli setup

Authenticating with a personal access token

Please refer to the GitHub documentation for detailed instructions on generating the <GITHUB_AUTH_TOKEN>. Ensure that the read:package permission is enabled during token creation, and also confirm that Single Sign-On (SSO) is activated.

Next, access the .npmrc file located at your home directory, and add the following lines:

bash

//npm.pkg.github.com/:_authToken=<GITHUB_AUTH_TOKEN>

To install this package, follow these steps:

bash

npm install @nib-group/design-tokens

Finally, add the following line to the .npmrc file in either your home directory or your project directory:

bash

@nib-group:registry=https://npm.pkg.github.com

If you are using buildkite, make sure to add the github plugin in your steps:

bash

steps:
  - name: ':npm: npm install'
    plugins:
      - ssh://[email protected]/nib-group/github-packages-buildkite-plugin.git#v1.6.0:
          action: auth
          registry: npm
          include-npmjs-config: true

Design principles

As a developer, it is essential that you have an understanding of what it takes to design an experience for a user. It is not only the role of the designer to have an understanding of design principles, as these principles apply to all aspects of development.

Please refer to the design principles that underlie design at nib.

Components

Components are the building-blocks for all nib experiences. Our primary implementation of the components are built with React and distributed as individual npm packages.

For documentation on the components, see the Component overview page.

Theme is king

Our theme is integral to how we build experiences at nib. Our design system is built upon it, and many of the components will break when not rendered within the ThemeProvider. Ensure that you wrap the root of your application with our ThemeProvider component and pass in the brand for which you are building.

jsx

import ThemeProvider, {nib} from '@nib-components/theme';

const App = props => (
  <ThemeProvider theme={nib}>
    <div>Themed page</div>
  </ThemeProvider>
);

export default App;

This is required and should only be done once per application.

Selectors

Our theme also exports selectors for easily grabbing properties from the theme object.

jsx

import styled from 'styled-components';
import {colorLightest} from '@nib-components/theme';

const Box = styled.div`
  background-color: ${colorLightest};
  {/* instead of /*}
  background-color: ${props => props.theme.colors.shades.lightest};
`;

Outside of the components

Utilities

Our layout package provides mixins for spacing and responsive styling based on the open source libraries styled-components-breakpoint and styled-components-spacing.

These utilities will automatically look for breakpoints and spacing sizes from our theme.

jsx

import {breakpoint, p, mt} from '@nib/layout';

const Example = styled.div`
  ${p(4)};

  ${breakpoint('md')`
    display: none;
  `}

  > * + * {
    ${mt({xs: 2, md: 4})};
  }
`;

For more information, visit our foundation pages for both Spacing and Breakpoints.

In the past we have utilised another open source package, styled-components-grid, to define layouts on pages. However, since the introduction of our Layout components, we no longer recommend Grid for use building new pages and experiences.

The layout components are:

Browser support

Browser support should be determined from your actual users. Check google analytics for your pages and applications to determine what level of legacy browser support is required for your audience.

Generally, we support the latest 2 versions of all modern browsers (Google Chrome, Mozilla Firefox, Safari, Microsoft Edge).

We use BrowserStack to check your projects on devices and browsers you do not have access to.

There are also a number of test mobile devices in the Newcastle office available for you to test your projects on real devices.

For more details, see the Browser Support page.

Accessibility and semantic markup

Accessibility should be baked in to how we build experiences at nib. Our design system should provide you with accessible bricks to fit together, but it is your responsibility to ensure the mortar is also inclusive. Projects will always have a variable "brick to mortar" ratio and having accessible bricks does not guarantee an accessible end user experience. Make sure you test, test, test!

Some of the more basic accessibility considerations are:

Ensure sufficient color contrast (AA rating) in your layouts.
Unplug your mouse and try to navigate around your site - can you reach everywhere?
Practise good focus management, with our standard focus styling.
Use landmarks appropriately (e.g. main, aside, nav). Not everything should be a div as it tells a screenreader nothing about the nature of content within.
Pages should follow a logical, semantic heading hierarchy.
Add a Skip to content link (see our Skip Link component).
Usearia- attributes to add context or hide noise.

For a more detailed understanding on what we expect for accessibility, refer to the Accessibility Checklist.

Logical properties

Logical properties and values in CSS provide a powerful way to control layout and style based on the flow of content. Unlike traditional physical properties (such as margin-top or padding-left), logical properties adapt to different writing modes (horizontal or vertical) and text directions (left-to-right or right-to-left). This makes CSS more flexible and easier to internationalize.

There are a number of properties and values in CSS that have logical equivalents. MDN has great docs on these including mapping tables of properties and values:

Across the Mesh system, we use logical properties to ensure our components are flexible and can adapt to different writing modes and text directions. Any prop that accepts physical properties can also accept logical properties, and we encourage their use.

jsx

<Box marginBlockStart={2} textAlign="start" >I'm logical!</Box>
<Box marginTop={2} textAlign="left">I'm not</Box>

Think fluidly

The web is not static, it is fluid. Think hard before setting a fixed height or width on anything. What impacts will that have on different screen sizes, with different content lengths or number of elements. CSS is powerful and there is probably a more flexible solution to your problem.

A note on our tech stack

The Mesh design system is built using React and Styled Components. If you are looking to build something for the nib group outside of this tech stack we do offer an atomic CSS Framework based on Tailwind that will enable you to build things that "look like" our design system components.

Styled Components gives us tremendous theming capability, which powers our entire library of components, and many different brands.

RSC support

Efforts have been made to enable usage of Mesh components within an RSC project. See React Server Components (RSC) compatibility for more information.

Resources

Edit this page