LUI - Linz User Interface for CSS and React1
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.
It aims to solve the problem of consistent UI across Step and hopefully benefit all Linz, while giving squads a bunch of base elements they can start using out of the box.
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
Storybook as documentation
Where it says import { x } from "./..." that means you put import { x } from @philals/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/
When making changes to the HTML files, make sure you change the files in 10-LuiStatic.stories.tsx
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:
./compile-sass.sh
Plain CSS
Once the Lui's CSS is hosted on a CDN it is able to be consumed. Please contribute if you want to use it.
CSS is also available as a file by building following the instruction above.
TODO: Host CSS on CDN
ReactJS
npm install --save @philals/lui
This is the temp home of Lui until we build a proper automated pipeline.
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"
/>
TODO: A permanent home for NPM module
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:
npm run release:patch
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
This will bring up Storybook which will show you how to use the components and write your own:
Run tests:
npm run test
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.
Whenever the version of the package is incremented, either by changing the package.json, or by running the command npm version [major/minor/patch], the CI/CD Pipeline will build and deploy Lui to the NPM repo. Note this only happens from the Master branch.
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