LUI - Linz User Interface for CSS and React

Lui the happy UI worm!

Lui is a collection of generic UI components that adhere to Linz's new digital style guide, lead by STEP and welcoming contributions from across LINZ.

It aims to solve the problem of consistent UI across LINZ, while giving squads a bunch of base elements they can start using out of the box.

We aim to make each component generic, extendable and assessable.

All styles are implemented in SASS and compiled to plain CSS. This means any team can use the CSS. A ReactJS wrapper over the CSS is part of this project.

There is lots to do in this project, often things will be left until there is demand. Please join the Slack channel #lui-discussions.

Heavy inspiration is taken from https://github.com/GOVTNZ/govtnz-design-system

Layouts

Included in this CSS is a layout system based of the NZ Govt UI package which is based off https://flexboxgrid.com/. Except there is a g- prepended to all class names

How to consume

Build CSS yourself

Please also see Required styles below

npm install && npm build

You will find the CSS then in dist/lui.css.

Import CSS from NPM module

Please also see Required styles below

After install you can import with: import "@linzjs/lui/dist/lui.css";

CSS from a CDN

If you would like this feature please contribute.

ReactJS

Please also see Required styles below

npm install --save @linzjs/lui

Required styles

You'll also need to add Google font to your index.html.

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

<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/icon?family=Material+Icons+Round"
/>

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

Icons

Lui using Google's Material icons, make sure you install them with instructions above. The icons can be viewed here: https://material.io/resources/icons/?icon=more_vert&style=baseline

To use it in HTML:

<i class={"material-icons-round"}>more_vert</i>

And in React:

<i className={"material-icons-round"}>more_vert</i>

Documentation

Please see here: https://linz.github.io/Lui/?path=/story/lui-html-design-system--lui-start-here-introduction

Storybook

This is the best place for docs. It's hosted on the public internet here: https://linz.github.io/Lui

Where it says import { x } from "./..." that means you put import { x } from @linzjs/lui in the app you are building.

To view the React component library please see the sections below on running Storybook or visit https://linz.github.io/Lui/

CSS and HTML as documentation

Please see the static HTML files for documentation on how to use CSS. First you'll need to build the CSS.

You can always view source on the HTML: https://linz.github.io/Lui/?path=/story/lui-html-design-system--lui-start-here-introduction

How to contribute

This project uses TSDX as a build system. This hides a lot of the painful stuff about publishing a module. See readme-tsdx for the TSDX docs.

Here's a quick lot of commands to get you going quickly:

npm install
npm run storybook

At the same time run ./compile-sass.sh to keep style changes updated.

This will bring up Storybook which will show you how to use the components and write your own.

Run tests:

npm run test

We highly suggest first writing your new componetne in SASS and HTML with interactivity provided by basic Javascript. This helps keep your styles usable by non-React project. Once complete create a React wrapper which hides the className usesages and provides the interactivey of the basic Javascript. o View exisiting HTML stories in Storybook under the HTML section.

It's not 100% nessasary to do it in this order (HTML/CSS -> React). However, it's highly encouraged. Any new components ideally MUST Be implemented in plain HTML as well as React.

Sometimes it's nice to build in Lui and see how that component looks in your app (without cutting a Lui release to NPM). Yalc is one solution (https://github.com/whitecolor/yalc). It allows you to build to a "local" NPM and pull directly into your app.

Release notes

Changelog generation is automatic using git commit messages,

Conventional Commits is a convention that gives you a rough idea of what a git commit actually does, its formatted:

<commit type>: <commit message>
[commit body]

The most used commit types:

• feat: add a feature, this is generally some code change (or style) that adds something new or improves something
• fix: bug fixes, generally a small change
• docs: updating documention, this bypasses the changelog
• build: updating the build system (github actions) bypasses changelog

finally breaking changes I normally make as multiline commits

feat: this is a breaking change
BREAKING CHANGE: this destroys everything

if you also have sub-components or modules, you can say what scope the change affects inside of basemaps we have things like

feat(LuiInput): allow nztm projection to be used

which tells me I added a feature the the LuiInput that allows NZTM (a map projection for NZ) to be used

here is some docs: https://www.conventionalcommits.org/en/v1.0.0/

some conventional commit changelogs examples external: https://github.com/aws/aws-cdk/blob/master/CHANGELOG.md

internal (linz): https://github.com/linz/basemaps/blob/master/CHANGELOG.md https://github.com/blacha/cogeotiff/blob/master/CHANGELOG.md

and finally some decent guidelines https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines

TLDR: generally use feat: to add features and fix: for bug fixes

CI/CD and Deployment

On every push (to any branch), the CI Pipeline will run linting, formatting, and react tests on the codebase. Note, only the react tests will fail the pipeline.

When ever a new release is pushed to master, the CI/CD Pipeline will build and deploy Lui to the NPM repo. Note this only happens from the Master branch.

How to release

Lui follows sem ver (major.minor.patch). To release a patch MAKE SURE YOU ARE UPTODATE WITH MASTER AND NO UNCOTTED CHANGES. Run this command from your local machine. It does everything you need. Replace patch witt major or minor as needed.

npm run release:patch

Jump into #lui-discussions if you have any ideas and send a PR. Please check out the issues on this repo.

Tips and Trick

When you create a new scss class, import it inside the base.scss in order to use it

Recommended Libs

Modals

Lui is using react-modal for it's modals: https://github.com/reactjs/react-modal

Date pickers

There have been a few experiments with Date pickers. Current advise is to use the AirBnB date picker: https://www.npmjs.com/package/react-dates at this point in time there has been no CSS overrides needed. If you do please contribute back to Lui React.

Forms

Lui React uses Formik and the React components are coupled. Long term plans are to have un-coupled versions: https://github.com/linz/Lui/issues/112

Lui Forms without Formik

If you want, for example, a LuiCheckbox but not the React version as it is coupled with LuiFormikForm Then you can check the plain HTML and use the classNames, eg.

  <div class="lui-standard-form">
    <div class="lui-checkbox-container">
                  <input
                    class=""
                    id="anyCheckboxId1"
                    type="checkbox"
                    name="providerChoice1"
                    value="provider1"
                  />
    </div>
  </div>

Have a look at the HTML stories in Storybook.

React Router

Here is how to wrap a button in a React Router <Link/>

<Link to="/dashboard">
    <LuiButton>Click Me!</LuiButton>
</Link>