Skip to content

Commit

Permalink
update/readme-whats-happening (#341)
Browse files Browse the repository at this point in the history 
* Update README.md, update/add link state colours and update what's happening changelog

* Update README.md

* Update index.hbs
  • Loading branch information
@laurenhitchon
laurenhitchon authored Aug 27, 2023
1 parent 0f82d49 commit 0f0ade0
Show file tree
Hide file tree
Showing 4 changed files with 198 additions and 70 deletions.
164 changes: 108 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,108 +4,160 @@
[![](https://data.jsdelivr.com/v1/package/npm/nsw-design-system/badge)](https://www.jsdelivr.com/package/npm/nsw-design-system)
[![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/b183fe4d/nsw-design-system)

View documentation for [NSW Design System](https://digitalnsw.github.io/nsw-design-system/).
View online documentation for the [NSW Design System](https://digitalnsw.github.io/nsw-design-system/).

## Using the design system
# NSW Design System Documentation

How you use the NSW Design System depends on your team's capabilities. We recommend using `npm` but also provided in a CDN, and a downloadable starter kit which includes all the compiled assets.
Welcome to the documentation for the NSW Design System, a frontend toolkit of styles, patterns, standards and guidance for everyone creating distinctly NSW digital products and services. It helps us create unified, trusted, inclusive and audience centered digital experiences for our users that are clearly simple, current and purposeful.

This document provides instructions on how to easily integrate and utilise the NSW Design System styles and components in your projects.

1. [Installing with NPM](#installing-with-npm)
2. [Import styles](#importing-all-styles)
3. [Adding the font and icons](#adding-the-font-and-the-icons)
4. [Importing javascript into your project](#importing-javascript-into-your-project)
5. [Using JSDelivr CDN](#using-jsdelivr-cdn)
## Choosing Your Integration Method

### Installing with NPM
1. Install `Node/npm`.
How you use the NSW Design System depends on your team's capabilities.

- More information can be found via the nodejs [Installation guides](https://nodejs.org/en/download/)
We recommend the following methods:

2. Generate a `package.json` file using the `npm init` command in the terminal. You will be prompted to enter several pieces of information, like the name of your application, version, description etc.
1. [Download the latest release](https://github.com/digitalnsw/nsw-design-system/releases)

4. Add `nsw-design-system` to your project’s `package.json`:
- `npm install --save nsw-design-system`
2. Clone the repo: `git clone https://github.com/digitalnsw/nsw-design-system.git`

The NSW Design System is now installed as a dependancy of your project, check out how to [import styles](#importing-styles-into-your-project) and [javascript](#importing-javascript-into-your-project) in to your project build.
3. **Using npm Package Manager:** This method provides a structured and customisable approach to integrating the design system into your project.

### Importing styles
#### All styles
To import all styles as a single package you need to add following snippet at the start of your main SCSS file:
```css
4. **Using JSDelivr CDN:** If you prefer a quicker setup, you can use the JSDelivr content delivery network to directly include the design system's CSS and JavaScript files in your project.

Read the [Getting started page](https://digitalnsw.github.io/nsw-design-system/docs/content/develop/getting-started.html) for information on the framework contents, templates, examples, and more.

## Installing with NPM

Follow these steps to integrate the NSW Design System into your project using npm:

1. **Install Node.js and npm:** If you haven't already, install Node.js and npm by following the instructions in the Node.js installation guides.

2. **Create a package.json:** In your project's root directory, run the `npm init` command in your terminal. Follow the prompts to generate a `package.json` file, providing essential project information.

3. **Add nsw-design-system to your dependencies:** Run the following command to install the NSW Design System as a dependency in your project:

```
npm install --save nsw-design-system
```

4. **Import Styles and JavaScript:** Learn how to import the design system's styles and JavaScript into your project's build by referring to the relevant sections below.

### Importing Styles

#### All Styles

To import all design system styles as a single package, add the following snippet at the start of your main SCSS file:

```
@import 'node_modules/nsw-design-system/src/main';
```

#### Core and selected components
Our core library includes the design system's base theme, typography, mixins and helper functions. Once you imported it, you can take full advantage of our variables and helpers. To import core library you need to add following snippet at the start of your main SASS file:
#### Core and Selected Components

The core library includes the design system's base theme, typography, mixins, and helper functions. Import the core library at the start of your main SASS file:

```css
```
// Core libraries
@import 'node_modules/nsw-design-system/src/global/scss/settings/settings';
@import 'node_modules/nsw-design-system/src/global/scss/base/all';
@import 'node_modules/nsw-design-system/src/global/scss/helpers/all';
@import 'node_modules/nsw-design-system/src/global/scss/settings/palette';
@import 'node_modules/nsw-design-system/src/global/scss/settings/theme';
@import 'node_modules/nsw-design-system/src/core/all';

```

Once you have installed the core library you can start importing components as you need it. To import individual components you need to add following snippets to your main SASS file under core libraries import:
After importing the core library, you can start importing individual components as needed:

```css
```
// Components
@import 'node_modules/nsw-design-system/src/components/accordion/accordion';
@import 'node_modules/nsw-design-system/src/components/card/card';
@import 'node_modules/nsw-design-system/src/components/notification/notification';
```

With this setup you can also start theming with a few sets of variable changes.
### Adding Fonts and Icons

Include the following lines of code in the `<head>` tag of your main HTML document, placing them before the NSW Design System styles import:

#### Adding the font and the icons
In your main html document add this line of code inside the `<head>` tag. Make sure that it's placed before the NSW Design System styles import.
```html
<link href="https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
```
Another way is to import it in css:
```css
@import url('https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap');
@import url('https://fonts.googleapis.com/icon?family=Material+Icons');
<link href="<https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap"> rel="stylesheet">
<link href="<https://fonts.googleapis.com/icon?family=Material+Icons"> rel="stylesheet">
```
### Importing javascript into your project
Some NSW Design System components require javascript to provide advanced functionality. To ensure the page is ready for javascript to run, include the follow scripts tags at the end of the html document.
```html
<script src="path/to/main.js"></script>
<script>window.NSW.initSite()</script>
</body>

Alternatively, you can import fonts and icons directly in your CSS:

```
@import url('<https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap');>
@import url('<https://fonts.googleapis.com/icon?family=Material+Icons');>
```

### Importing JavaScript

Certain NSW Design System components require JavaScript to enable advanced functionality. To ensure your page is ready for JavaScript execution, include the following script tags at the end of your HTML document:

```
<script src="path/to/main.js"></script>
<script>window.NSW.initSite()</script>
</body>
</html>
```
Depending on your project set up, you might wish to copy the file into your project from `node_modules` or add the reference to your build workflow.

Depending on your project setup, you can copy the JavaScript file from `node_modules` or add a reference in your build workflow.

## Using JSDelivr CDN

### Using JSDelivr CDN
The bundled css and js files are also hosted in [JSDelivr](https://www.jsdelivr.com).
For a faster setup, you can utilize the JSDelivr CDN to include the NSW Design System's CSS and JavaScript files directly in your project's HTML:

You can add the files to your main html document
```html
```
<html>
<head>
...
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/css/main.css">
<!-- ... -->
<link rel="stylesheet" href="<https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/css/main.css">>
</head>
<body>
...
<script src="https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/js/main.min.js"></script>
<!-- ... -->
<script src="<https://cdn.jsdelivr.net/npm/nsw-design-system@3/dist/js/main.min.js"></script>>
<script>window.NSW.initSite()</script>
</body>
</html>
```

## Design System Figma UI kit
Access all the design assets required to design, share and prototype in our [Figma UI Kit](https://digitalnsw.github.io/nsw-design-system/docs/content/design/figma-ui-kit.html).
## Contributing

Please read through our [contributing guidelines](https://www.digital.nsw.gov.au/delivery/digital-service-toolkit/design-system/contributing). Included are directions for opening issues, coding standards, and notes on development.

## Community

Get notified when there’s an update or new release on the NSW Design System's and chat with the project maintainers and community members.

* Join our [Digital NSW Community](https://community.digital.nsw.gov.au/).

* Watch the [NSW Design System Github](https://github.com/digitalnsw/nsw-design-system).

* Ask and explore [our GitHub Discussions](https://github.com/digitalnsw/nsw-design-system/discussions).

## Report an issue

View and raise issues and bugs through our [Issues tracker on Github](https://github.com/digitalnsw/nsw-design-system/issues) or [report a bug on the Digital NSW community](https://community.digital.nsw.gov.au/c/components/report-a-bug/27).

## Design System Figma UI Kit

Access the complete set of design assets required for designing, sharing, and prototyping using our [Figma UI Kit](https://digitalnsw.github.io/nsw-design-system/docs/content/design/figma-ui-kit.html).

## Versioning
We are using semantic versioning so our version number are increments of MAJOR.MINOR.PATCH where:
- MAJOR version used for incompatible global changes
- MINOR version used for large backwards-compatible updates and release of new components
- PATCH version used for small backwards-compatible updates, new component variations and bug fixes

For transparency into our release cycle and in striving to maintain backward compatibility, The NSW Design System is maintained under [the Semantic Versioning guidelines](https://semver.org/). Sometimes we make mistakes, but we adhere to those rules whenever possible.

Our version numbers consist of MAJOR.MINOR.PATCH, where:

* **MAJOR** version is used for incompatible global changes.

* **MINOR** version is used for significant backward-compatible updates and the release of new components.

* **PATCH** version is used for minor backward-compatible updates, new component variations, and bug fixes.

See [the Releases section of our GitHub project](https://github.com/digitalnsw/nsw-design-system/releases) for changelogs for each release version. Release posts on our [what’s happening page](https://digitalnsw.github.io/nsw-design-system/docs/content/about/whats-happening.html) contain summaries of the most noteworthy changes made in each release.

Feel free to reach out if you have any questions or need more help with integrating the NSW Design System into your projects!
92 changes: 78 additions & 14 deletions src/core/colour/index.hbs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ meta-index: true
</div>

<h3>Text colours</h3>
<p>This set of text colours have a ratio of at least 4.5:1 (or 3:1 for text larger than 18 point) to met Web Content Accessibility Guidelines (WCAG 2.1). </p><p>Interaction colours are in addition to the NSW Government colour palette to maintain consistent and accessible text and not conflict with brand colours.</p>
<p>This set of text colours have a ratio of at least 4.5:1 (or 3:1 for text larger than 18 point) to met Web Content Accessibility Guidelines (WCAG 2.1). </p>

<div class="nsw-section nsw-section--white nsw-block nsw-p-x-sm nsw-p-top-sm">
<div class="nsw-table nsw-table--valign-middle">
Expand Down Expand Up @@ -292,46 +292,110 @@ meta-index: true
<p><code>--nsw-text-light</code></p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

<h3>Link state colours</h3>

<p>Link state colours are in addition to the NSW Government colour palette to maintain consistent and accessible text and not conflict with brand colours.</p>

<div class="nsw-section nsw-section--white nsw-block nsw-p-x-sm nsw-p-top-sm">
<div class="nsw-table nsw-table--valign-middle">
<table>
<tbody>
<tr>
<th style="width: 10%">
<div>
<p>Swatch</p>
</div>
</th>
<th style="width: 30%">
<div>
<p>Colour</p>
</div>
</th>
<th style="width: 30%">
<div>
<p>Hex value</p>
</div>
</th>
<th>
<div>
<p>CSS variable</p>
</div>
</th>
</tr>
<tr>
<td>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-focus)"></div>
<div class="nsw-docs__swatch" style="color: var(--nsw-text-link)"></div>
</td>
<td>
<p>Text focus</p>
<p>Link</p>
</td>
<td>
<p><code>#0085B3</code></p>
<p><code>#002664</code></p>
</td>
<td>
<p><code>--nsw-focus</code></p>
<p><code>--nsw-text-link</code></p>
</td>
</tr>
<tr>
<td>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-text-visited)"></div>
</td>
<td>
<p>Link visited</p>
</td>
<td>
<p><code>#551A8B</code></p>
</td>
<td><code>--nsw-text-visited</code></td>
</tr>
<tr></tr>
<tr>
<td>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-text-hover)"></div>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-text-link-hover)"></div>
</td>
<td>
<p>Link hover background</p>
</td>
<td>
<p><code>rgba(0, 38, 100, 0.1)</code></p>
</td>
<td>
<p><code>--nsw-text-link-hover</code></p>
</td>
</tr>
<!--
<tr class="nsw-section--invert" style="background-color: var(--nsw-palette-grey-01)">
<td>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-text-link-hover-light)"></div>
</td>
<td>
<p>Text hover background</p>
<p>Link hover light background</p>
</td>
<td>
<p><code>rgb(0, 133, 179, 0.2)</code></p>
<p><code style="color: var(--nsw-text-dark);">rgba(255, 255, 255, 0.1)</code></p>
</td>
<td>
<p><code>--nsw-text-hover-bg</code></p>
<p><code style="color: var(--nsw-text-dark);">--nsw-text-link-hover-light</code></p>
</td>
</tr>
-->
<tr>
<td>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-text-visited)"></div>
<div class="nsw-docs__swatch" style="background-color: var(--nsw-focus)"></div>
</td>
<td>
<p>Text visited</p>
<p>Link focus</p>
</td>
<td>
<p><code>#551A8B</code></p>
<p><code>#0085B3</code></p>
</td>
<td>
<p><code>--nsw-focus</code></p>
</td>
<td><code>--nsw-text-visited</code></td>
</tr>
</tbody>
</table>
Expand Down
11 changes: 11 additions & 0 deletions src/docs/content/about/whats-happening.hbs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,17 @@ meta-index: true
</tr>
</thead>
<tbody>
<tr>
<td>v3.10.0</td>
<td>22.08.23</td>
<td>
<ul>
<li>Adds utility classes for <a href="/docs/content/utilities/background.html">Background</a>, <a href="/docs/content/utilities/borders.html">Borders</a>, <a href="/docs/content/utilities/box-shadow.html">Box Shadow</a>, <a href="/docs/content/utilities/display.html">Display</a>, <a href="/docs/content/utilities/flex.html">Flex</a>, <a href="/docs/content/utilities/float.html">Float</a>, <a href="/docs/content/utilities/overflow.html">Overflow</a>, <a href="/docs/content/utilities/position.html">Position</a>, <a href="/docs/content/utilities/svg.html">SVG</a>, <a href="/docs/content/utilities/text.html">Text</a>, <a href="/docs/content/utilities/vertical-align.html">Vertical align</a>, <a href="/docs/content/utilities/visibility.html">Visibility</a> and <a href="/docs/content/utilities/z-index.html">Z-index</a>.</li>
<li>New <a href="/components/close-button/index.html">Close button</a> component documentation</li>
</ul>
</td>
<td><a target="_blank" href="https://github.com/digitalnsw/nsw-design-system/releases/tag/v3.10.0" target="_blank">Code kit</a></td>
</tr>
<tr>
<td>v3.9.0</td>
<td>20.07.23</td>
Expand Down
1 change: 1 addition & 0 deletions src/global/scss/settings/_theme.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@

--nsw-text-link: var(--nsw-palette-blue-01);
--nsw-text-link-hover: rgba(var(--nsw-palette-blue-01-rgb), 0.1);
--nsw-text-link-hover-light: rgba(var(--nsw-palette-white-rgb), 0.1);

--nsw-text-visited: var(--nsw-palette-visited);
--nsw-focus: var(--nsw-palette-focus);
Expand Down

0 comments on commit 0f0ade0

Please sign in to comment.