diff --git a/.vscode/extensions.json b/.vscode/extensions.json index abb7517966..5450b9b4d3 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -10,6 +10,7 @@ "editorconfig.editorconfig", "stylelint.vscode-stylelint", "alexkrechik.cucumberautocomplete", - "circleci.circleci" + "circleci.circleci", + "nuxt.mdc" ] } diff --git a/.vscode/settings.json b/.vscode/settings.json index ff850624dd..e008e58daf 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -31,6 +31,9 @@ "cSpell.words": [ "colour", "composables", + "customisation", + "customising", + "familiarise", "formkit", "jsonapi", "maxlength", diff --git a/docs/app.config.ts b/docs/app.config.ts index a6513bed96..6243fddccf 100644 --- a/docs/app.config.ts +++ b/docs/app.config.ts @@ -9,7 +9,7 @@ export default defineAppConfig({ neutralFooter: false }, framework: { - title: 'Ripple Layer Development Guide', + title: 'Ripple Framework', color: 'var(--rpl-clr-dark)', neutralFooter: true } diff --git a/docs/components/content/DocsIcon.vue b/docs/components/content/DocsIcon.vue new file mode 100644 index 0000000000..1acaa1e917 --- /dev/null +++ b/docs/components/content/DocsIcon.vue @@ -0,0 +1,14 @@ + + + diff --git a/docs/content/1.index.md b/docs/content/1.index.md index 22adbca9cd..12c445873a 100644 --- a/docs/content/1.index.md +++ b/docs/content/1.index.md @@ -5,13 +5,13 @@ icon: carbon:home layout: home primaryCTA: title: For Designers - description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. + description: Information for designers using Ripple to create brand Victoria compliant digital experiences. image: src: /assets/img/for-designers.png url: /design-system/design/getting-started secondaryCTA: title: For Developers - description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. + description: How to get started implementing Ripple UI components in digital products. image: src: /assets/img/for-developers.png url: /design-system/develop/getting-started @@ -20,25 +20,30 @@ modulesCTA: description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. url: /framework quickLink1: - title: Who should use it - description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. - url: / + title: About Ripple + description: Ripple is a system of reusable styles, components, patterns and tools for creating Victorian government digital experiences. + url: /design-system/about/what-is-ripple quickLink2: - title: How it works - description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. - url: / + title: Who should use it + description: Ripple is built by government for government to deliver services Victorians trust and rely on. + url: /design-system/about/whos-it-for quickLink3: - title: Getting help - description: Paragraph Default. Cards contain actionable content about a single topic. These are usually grouped as similar style sets. - url: / + title: Design principles + description: The guiding principles that are the foundation of the Ripple Design System. + url: /design-system/design/our-design-principles + +framework: + title: Ripple framework + description: Ripple framework contains the tools for building SDP sites using Ripple design system components. + url: /framework # whatsNew: # title: What's new # description: Ripple release information text # links: # - -# text: 'This link goes somewhere' +# text: 'Ripple 2.0 changelog' # url: '#first' # - -# text: 'As does this one' +# text: 'Ripple 2.0 Figma changelog' # url: '#second' --- diff --git a/docs/content/design-system/1.about/1.what-is-ripple.md b/docs/content/design-system/1.about/1.what-is-ripple.md index 4f0fbe7724..71296e7eaf 100644 --- a/docs/content/design-system/1.about/1.what-is-ripple.md +++ b/docs/content/design-system/1.about/1.what-is-ripple.md @@ -1,7 +1,66 @@ --- -title: What is ripple -description: Page description +title: About Ripple +description: The design system for brand Victoria digital products layout: page --- -## Content goes here +Ripple is a system of reusable styles, components, patterns and tools for building brand Victoria digital products. + +Developed by the Single Digital Presence (SDP) team within the Department of Government Services, +Ripple strives to: + +- make it easier for citizens to find, understand and use government information +- ensure users can easily navigate sites regardless of technical ability, location or device +- allow designers and developers to create consistent Brand Victoria digital products +- increase the speed of delivery for digital products and services + +Over 50 government websites use Ripple to date, including our main vic.gov.au platform. These sites attract the visitation of millions of views per month. + + +![Screenshots of websites using SDP, vic.gov.au, police.vic.gov.au, health.vic.gov.au, legislation.vic.gov.au](/assets/img/sites.png){.docs-center-img} + + +## Why use Ripple? + +### We solve the hard problems so you don’t have to + +We have spent the past 5 years refining Ripple based on user feedback to ensure it... + +- meets the publishing needs of government users, and +- makes it easier for citizens to interact with government services + +Ripple users can be confident their site meets the highest industry standards and best practices for: + +- accessibility +- SEO +- security +- performance + +### Promotes efficiency and reuse across government + +Ripple promotes efficiency and reuse by providing reusable styles, components and patterns. + +It provides a set of standards to manage design at scale, to... + +- reduce redundancy +- create a shared language +- provide visual consistency + +Developer contributions can be shared across projects, adding value to all government departments. This results in reduced project development time and expense. + +### By government, for government + +The Ripple design system has been made open source by to foster collaboration across government. By making the system open source, departments and agencies can help improve the citizen experience across government. Ripple has been developed by government, for government and retains all intellectual property and expertise. + + +## Who can use Ripple? + +Ripple is open to all departments or agencies that use Victorian Government branding. + +See [Who's it for](2.whos-it-for.md) for more information on who Ripple is for. + +## How do I find out more? + +If you are a Victorian Government department or agency wanting to use Ripple in a brand Victoria digital product (or a vendor supporting them), please visit [https://www.vic.gov.au/work-sdp](https://www.vic.gov.au/work-sdp) or contact digital@dpc.vic.gov.au + +To find out more about the Single Digital Presence program please see [https://www.vic.gov.au/single-digital-presence](https://www.vic.gov.au/single-digital-presence). diff --git a/docs/content/design-system/1.about/2.whos-it-for.md b/docs/content/design-system/1.about/2.whos-it-for.md new file mode 100644 index 0000000000..65e724df2d --- /dev/null +++ b/docs/content/design-system/1.about/2.whos-it-for.md @@ -0,0 +1,13 @@ +--- +title: Who's it for? +description: Built by government for government. +layout: page +--- + +Ripple is built to help deliver websites to deliver government information to Victorian citizens. It is primarily used by Victorian government departments and agencies through the [SDP program](https://www.vic.gov.au/single-digital-presence). + +Ripple is designed to make it easy to communicate government information in a clear, concise and accessible manner for all Victorians. It is solely used to represent the Victorian government brand in digital products and services. + +> Ripple is intended for Victorian government branded products only, and should only be used to produce approved Victorian government branded communications. + +As the system is intended to be modular, it is possible to opt into various parts of the system. For example projects not on SDP can adopt the design into their own digital products, either by building their own components, referencing our styles or importing our components. See the [Usage page](../3.develop/3.usage.md) for more information. If you are site using or wanting to use Ripple in a non SDP project please get in [touch with us](3.getting-support.md) to see how we can support your project. diff --git a/docs/content/design-system/1.about/3.getting-support.md b/docs/content/design-system/1.about/3.getting-support.md new file mode 100644 index 0000000000..ff3f65d191 --- /dev/null +++ b/docs/content/design-system/1.about/3.getting-support.md @@ -0,0 +1,26 @@ +--- +title: Support +description: How to get help +layout: page +--- + + +The [Ripple design system](https://www.vic.gov.au/ripple-design-system) is maintained by the [Single Digital Presence (SDP)](https://www.vic.gov.au/single-digital-presence) team at the Victorian Department of Government Services. + +You can reach out to us via the following channels: + +### For technical and project support + +- join the discussion on [GitHub](https://github.com/dpc-sdp/ripple-framework/discussions) +- log a request through our [helpdesk](https://digital-vic.atlassian.net/servicedesk/customer/portals) +- sign up to the [SDP Slack](vic-sdp.slack.com) (Open to projects with an MoU for application support) + +## Design enquiries + +Email: design@dpc.vic.gov.au + +## General enquiries + +Email: digital@dpc.vic.gov.au + + diff --git a/docs/content/design-system/1.about/4.get-support/1.support-avenues.md b/docs/content/design-system/1.about/4.get-support/1.support-avenues.md deleted file mode 100644 index 6b8f1505dd..0000000000 --- a/docs/content/design-system/1.about/4.get-support/1.support-avenues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Support avenues -description: Page description -layout: page - ---- - -## Content goes here diff --git a/docs/content/design-system/1.about/4.get-support/2.faq.md b/docs/content/design-system/1.about/4.get-support/2.faq.md deleted file mode 100644 index 82bee8aa38..0000000000 --- a/docs/content/design-system/1.about/4.get-support/2.faq.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: FAQ -description: Page description -layout: page - ---- - -## Content goes here diff --git a/docs/content/design-system/1.about/4.get-support/3.reporting-issues.md b/docs/content/design-system/1.about/4.get-support/3.reporting-issues.md deleted file mode 100644 index 0a42ae7095..0000000000 --- a/docs/content/design-system/1.about/4.get-support/3.reporting-issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Reporting issues -description: Page description -layout: page - ---- - -## Content goes here diff --git a/docs/content/design-system/1.about/4.get-support/index.md b/docs/content/design-system/1.about/4.get-support/index.md deleted file mode 100644 index d0ae4d7c84..0000000000 --- a/docs/content/design-system/1.about/4.get-support/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Get support -description: Page description -layout: page - ---- - -## Content goes here diff --git a/docs/content/design-system/1.about/5.accessibility-statement.md b/docs/content/design-system/1.about/_5.accessibility-statement.md similarity index 100% rename from docs/content/design-system/1.about/5.accessibility-statement.md rename to docs/content/design-system/1.about/_5.accessibility-statement.md diff --git a/docs/content/design-system/2.design/1.getting-started.md b/docs/content/design-system/2.design/1.getting-started.md index 69cf0b1f32..f22d47874a 100644 --- a/docs/content/design-system/2.design/1.getting-started.md +++ b/docs/content/design-system/2.design/1.getting-started.md @@ -4,7 +4,7 @@ description: layout: page --- -Ripple is the design system for the Victorian Government’s digital products. The Ripple Design System makes websites and other digital products look and feel like part of the vic.gov.au brand. +Ripple is the design system for Victorian Government digital products. The Ripple Design System makes websites and other digital products look and feel like part of the vic.gov.au brand. The Ripple Design System creates an accessible and consistent visual user interface across all our digital products. This helps citizens trust they are visiting an official source of Victorian Government information. diff --git a/docs/content/design-system/2.design/2.our-design-principles.md b/docs/content/design-system/2.design/2.our-design-principles.md index 85c33f812a..62720938fb 100644 --- a/docs/content/design-system/2.design/2.our-design-principles.md +++ b/docs/content/design-system/2.design/2.our-design-principles.md @@ -17,7 +17,7 @@ The Ripple Design System uses these principles when making design decisions. ### Inclusive. -- A11y is top priority +- Accessibility is top priority - Collaborative in design - Transparent documentation - Friendly, helpful and trustworthy diff --git a/docs/content/design-system/2.design/3.design-tokens.md b/docs/content/design-system/2.design/3.design-tokens.md index ef4fbb1862..e9cd2084eb 100644 --- a/docs/content/design-system/2.design/3.design-tokens.md +++ b/docs/content/design-system/2.design/3.design-tokens.md @@ -95,4 +95,4 @@ Design tokens prevent or reduce the need to find and replace thousands of instan ## For developers -Design tokens in Ripple are implemented as CSS variables. E.g. `--rpl-clr-primary: #0052C2`. Theming is achieved by overriding or adjusting the value of these CSS variables. +For information for developers using tokens to theme Ripple components see the [theming guide](../3.develop/2.theming.md) diff --git a/docs/content/design-system/2.design/4.theming-guidance-for-designers.md b/docs/content/design-system/2.design/4.theming-guidance-for-designers.md new file mode 100644 index 0000000000..18fea94f15 --- /dev/null +++ b/docs/content/design-system/2.design/4.theming-guidance-for-designers.md @@ -0,0 +1,198 @@ +--- +title: Accordion +description: The Accordion component is a panel designed to save space by hiding and revealing content as required. +layout: page +label: Core + +--- +- [Create a custom theme](). +- [Component-specific theming](). +- [Theme accessibility](). +- [Automatic colour token logic](). + +--- + +Ripple 2.0 has been designed with in-built custom theming capabilities. Theming can be applied if your site requires department or entity branding and has been approved to use theming. Please note it is recommend you utilise the brand equity of vic.gov.au where possible and only theme your site if needed and approved. Please contact the SDP team for more information on approvals for theming. + +Ripple uses primary and accent colours, an optional gradient, a link colour and a focus state colour. You can read more about their roles and uses in the colour documentation. + +When theming your site, its styles and components will re-theme automatically. This has been done through the use of design tokens. Design tokens represent repeated design decisions that make up a design system's visual style. Tokens replace static values, such as hex codes for colour. The token informs how colour is used and inherited to ensure a consistent and accessible user experience. + +We’ve designed a colour testing process to ensure the selected colours will pass the accessibility contrast ratios. It classifies the selected colours into a ‘light’ or ‘dark’ category. The colour system will automatically provide accessible colour contrast to ensure legibility of all content. You will not need to check if you meet Web Content Accessibility Guideline (WCAG) requirements, as we have done this for you. + +To learn more about if your site should be themed, please contact the Single Digital Presence (SDP) team. + +--- + +## Create a custom theme +Ripple has been designed with a primary and accent colour. These inform the colour framework. + +A link colour, focus colour and optional gradient are also required when theming. + +The primary, accent and focus colours can be either light or dark: +- 'Light' means the colour is WCAG 2.1 AA compliant with dark type (rpl-clr-dark / #1A1A1A). +- ‘Dark’ means the colour is WCAG 2.1 AA compliant with light type (rpl-clr-light / #FFFFFF). + +To classify your colour as light or dark, we recommend the use [WebAim Colour Contrast Checker](https://webaim.org/resources/contrastchecker/) or the [Figma plugin, A11y - Colour Contrast Checker](https://www.figma.com/community/plugin/733159460536249875) to see if the colour is accessible with the Ripple 2.0 dark or light type colours listed above. + +Classifying colours as either ‘dark’ or ‘light’ informs the implementation of other colour tokens, aiming to conform to WCAG 2.1 AA colour contrast requirements. + +It is recommended that the primary colour is always visually darker than the accent and is visually different at glance. This will ensure your users are quickly and easily directed to the most important areas of a web page. + +Guidance for creating your own theme can be found on the Theming page of the [Ripple 2.0 Design System Figma file](). + +If you don’t have access, you can [request access to view the Ripple 2.0 Design System](). + +--- + +## Component-specific theming +The Ripple 2.0 Design System has components that allow for specific theming. This is optional and if not used, components will adopt the default framework styling. Component-specific theming is defined at a site level, and will affect all instances of the component. + +There are 2 options for component-specific styling: +- neutral +- custom. + +### Neutral +Neutral can be applied to the following components: +- buttons +- header (only reverse and image variants) +- footer. + +The colour of neutral component variants cannot be changed. Neutral components have predefined neutral styling and cannot be edited or customised. + +### Custom +Custom component theming can only be applied to the footer. + +The footer has been created with component-specific design tokens. It is recommended custom theming is only done if required. + +To learn more about custom styling please see the Theming page of the [Ripple 2.0 Design System Figma file](). + +--- + +## Theme accessibility +Ripple 2.0 has been designed with the aim to conform to WCAG 2.1 AA standards (below). For websites built on the SDP platform, it is mandatory to meet WCAG 2.1 AA level standards. These accessibility standards are also strongly recommended for all Victorian Government communications built using the Ripple design system (see: [Brand Victoria guidelines](https://www.vic.gov.au/brand-victoria-guidelines-logos) for more information). + +Colour contrast is the amount of perceived difference between 2 colours. This is represented as a ratio. A high ratio indicates greater difference between colours and therefore higher contrast. + +Colour contrast impacts the readability of your content. It is important for users with low vision or a colour vision deficiency. + +>[1.4.3 Contrast Minimum (Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) +>The visual presentation of [text](https://www.w3.org/TR/WCAG21/#dfn-text) and [images of text](https://www.w3.org/TR/WCAG21/#dfn-images-of-text) has a [contrast ratio](https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio) of at least 4.5:1, except for the following: +> +>[Large-scale](https://www.w3.org/TR/WCAG21/#dfn-large-scale) text and images of large-scale text have a contrast ratio of at least 3:1; +> +>Text or images of text that are part of an inactive [user interface component](https://www.w3.org/TR/WCAG21/#dfn-user-interface-components), that are [pure decoration](https://www.w3.org/TR/WCAG21/#dfn-pure-decoration), that are not visible to anyone, or that are part of a picture that contains significant other visual content, have no contrast requirement. +> +>Text that is part of a logo or brand name has no contrast requirement. + +### Accessibility testing requirements +When testing, websites on the SDP platform are required to meet AA standards. Your website must meet a [minimum contrast ratio of 4:5:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) for normal text contrast, 3:1 for large text and non-text elements must be met. + +Links are required to meet a ratio of 4.5:1 colour contrast. + +In the Ripple 2.0 Design System the primary, accent and focus colours are tested against: +- dark type / rpl-clr-dark / #1A1A1A +- light type / rpl-clr-light / #FFFFFF. + +The link colour is tested against 3 colours: +- light type / rpl-clr-light / #FFFFFF +- rpl-clr-neutral-100 / #F5F5F5 +- rpl-clr-accent-alt / #E6F5FD (example hex only). + +Colour vision deficiency: it is recommended to also test your colour palette for colour blindness. Some colours can appear similar to people with colour vision deficiency. We recommend using the [Figma plugin 'Color Blind'](https://www.figma.com/community/plugin/733343906244951586). + +--- + +## Colour token automatic logic +Below is a full list of colour tokens required to theme the Ripple 2.0 Design System. + +Aiming to meet WCAG 2.1 AA colour contrast requirements, some token values are automatic based on their use in the system. This ensures all text-based content meets colour contrast accessibility requirements. +For example, if the primary colour is classified as dark: +- rpl-clr-type-primary-contrast will automatically be rpl-clr-light +- rpl-clr-type-primary-accessible will automatically be rpl-clr-primary. + +### Core + +| Token | Custom / Automatic | +|-----------------------------|----------------------------------------| +| rpl-clr-primary | Custom | +| rpl-clr-primary-alt | Custom | +| rpl-clr-primary-alpha | Automatic (based on ‘rlp-clr-primary') | +| rpl-clr-accent | Custom | +| rpl-clr-accent-alt | Custom | +| rpl-clr-focus | Custom | +| rpl-clr-link | Custom | +| rpl-clr-gradient-horizontal | Custom | +| rpl-clr-gradient-vertical | Custom | + +### Typography colour tokens + +| Token | Custom / Automatic | +|-------------------------------------|--------------------------------------------------------------| +| rpl-clr-type-primary-contrast | Automatic (based on ‘rlp-clr-primary’ contrast requirements) | +| rpl-clr-type-primary-contrast-alpha | Automatic (based on ‘rlp-clr-type-primary-contrast') | +| rpl-clr-type-accent-contrast | Automatic (based on ‘rlp-clr-accent’ contrast requirements) | +| rpl-clr-type-primary-accessible | Automatic (based on ‘rlp-clr-primary’ contrast requirements) | +| rpl-clr-type-primary-alt-accessible | Automatic (based on ‘rlp-clr-primary’ contrast requirements) | +| rpl-clr-type-focus-contrast | Automatic (based on ‘rlp-clr-focus’ contrast requirements) | + +### Footer-specific (optional) +See: component-specific theming + +| Token | Custom / Automatic | +|--------------------------------|-------------------------------------------------------------| +| rpl-clr-footer | Custom or automatic | +| rpl-clr-footer-alt | Custom or automatic | +| rpl-clr-footer-contrast | Automatic (based on ‘rlp-clr-footer’ contrast requirements) | +| rpl-clr-type-footer-accessible | Automatic (based on ‘rlp-clr-footer’ contrast requirements) | + +--- + +## Automatic Colour Token Logic +Based on the colour contrast requirements for the primary, accent and focus colours, some tokens are automatic to aim to conform to WCAG 2.0 AA colour contrast accessibility. +- ‘Light’ means the colour (for example, primary) is AA compliant with dark type (rpl-clr-dark / #1A1A1A). +- ‘Dark’ means the colour (for example, primary) is AA compliant with light type (rpl-clr-light / #FFFFFF). + +### Primary, Access, Focus and Link + +#### Primary + +| Token | Colour ‘Dark’ | Colour 'Light | +|-------------------------------------|----------------------------------------------|----------------------------------------------| +| rpl-clr-primary-alpha | rpl-clr-primary at 50% opacity | rpl-clr-primary at 50% opacity | +| rpl-clr-type-primary-contrast | rpl-clr-light | rpl-clr-dark | +| rpl-clr-type-primary-contrast-alpha | rpl-clr-type-primary-contrast at 75% opacity | rpl-clr-type-primary-contrast at 75% opacity | +| rpl-clr-type-primary-accessible | rpl-clr-primary | rpl-clr-dark | +| rpl-clr-type-primary-alt-accessible | rlpl-clr-primary-alt | rpl-clr-dark | + +#### Accent + +| Token | Colour ‘Dark’ | Colour 'Light | +|------------------------------|---------------|---------------| +| rpl-clr-type-accent-contrast | rpl-clr-light | rpl-clr-dark | + +#### Focus + +| Token | Colour ‘Dark’ | Colour 'Light | +|-----------------------------|---------------|---------------| +| rpl-clr-type-focus-contrast | rpl-clr-light | rpl-clr-dark | + +#### Link + +| Token | Colour ‘Dark’ | Colour 'Light | +|--------------|---------------------|----------------------| +| | _If Primary ‘Dark’_ | _If Primary ‘Light’_ | +| rpl-clr-link | rpl-clr-primary | Custom | + +### Gradient +Including a gradient is optional for theming. + +If a gradient is not used, 'rpl-clr-accent' will be used in its place. + +#### Gradient + +| Token | Gradient | Accent | +|-----------------------------|--------------------------------|----------------| +| rpl-clr-gradient-horizontal | rpl-clr-gradient (90 degrees) | rpl-clr-accent | +| rpl-clr-gradient-vertical | rpl-clr-gradient (180 degrees) | rpl-clr-accent | + diff --git a/docs/content/design-system/3.develop/1.getting-started.md b/docs/content/design-system/3.develop/1.getting-started.md index 9bb2e86e64..be92b82870 100644 --- a/docs/content/design-system/3.develop/1.getting-started.md +++ b/docs/content/design-system/3.develop/1.getting-started.md @@ -15,15 +15,16 @@ This section contains information about the Ripple user interface libraries. The - `ripple-ui-core`: A collection of common UI components used in SDP sites. For example buttons, cards, icons and typography. - `ripple-ui-forms`: A collection of form inputs and support for building complex forms via [Formkit](https://formkit.com/) + > **These docs are for Ripple 2** > > Ripple 2 is a complete rebuild. If you are looking for information about the previous version of Ripple please visit the [original Ripple GitHub repo](https://github.com/dpc-sdp/ripple). > **Are you developing a site on the SDP platform?** > -> This section is about the Ripple UI component libraries, and there is a lot more to developing a Ripple/Tide/Bay site that is not covered here. +> This section is about the Ripple UI component libraries, and there is a lot more to developing a site on the Single Digital Presence (SDP) stack that is not covered here. > -> For more relevant documentation, visit the [Ripple Layer development guide (TODO)](#TODO) +> For information about using Ripple in SDP sites, visit the [Ripple Framework for SDP documentation](../../framework/1.index.md) ## Accessing the Source code @@ -44,64 +45,6 @@ Most of the examples found on this documentation site link directly examples in ## Usage -### Using in an SDP website - -> If you are using Ripple 2 to build a site on the SDP platform, the UI libraries will be included automatically when scaffolding your project. -> -> For more relevant documentation, visit the [Ripple Layer development guide (TODO)](#TODO) - -### Using in a Vue app - -To install Ripple UI in your project, run: - -`npm install @dpc-sdp/ripple-ui-core --save` - -In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue or index.js file): - -```js -import '@dpc-sdp/ripple-ui-core/style'; -import '@dpc-sdp/ripple-ui-core/style/components'; -``` - -To use a component, import it from `@dpc-sdp/ripple-ui-core/vue`, note the addition of `/vue`. - -```js - - - -``` - -### Using in a Nuxt app - -To install Ripple UI in your project, run: - -`npm install @dpc-sdp/ripple-ui-core --save` - -Ripple UI exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`: - -```js -export default defineNuxtConfig({ - modules: [ - '@dpc-sdp/ripple-ui-core/nuxt' - ] -}) -``` - -In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue file): - -```js -import '@dpc-sdp/ripple-ui-core/style'; -import '@dpc-sdp/ripple-ui-core/style/components'; -``` -There is no need to import the components as they will be registered globally by the nuxt module +See the [usage](3.usage.md) guide for information about getting started with the different ways of implementing Ripple. -```js - -``` diff --git a/docs/content/design-system/3.develop/2.theming.md b/docs/content/design-system/3.develop/2.theming.md index 78b293c55c..39683bbe0e 100644 --- a/docs/content/design-system/3.develop/2.theming.md +++ b/docs/content/design-system/3.develop/2.theming.md @@ -1,17 +1,15 @@ --- -title: Theming guidance for developers -description: Information for developers using the Ripple 2 UI libraries +title: Theme and brand application +description: Information for developers using Ripple 2 UI libraries layout: page -links: - - text: Github - url: https://github.com/dpc-sdp/ripple-framework - - text: Storybook - url: /storybook --- -Ripple is fully theme-able using standard [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). For guidance on how to theme Ripple in an accessible and consistent way, see the [theming guidance for designers](). +Ripple allows for customisation of it's components to allow application of Victorian government departments and agencies brand and identity within a common framework. For guidance on how to theme Ripple in an accessible and consistent way, see the [theming guidance for designers](../2.design/4.theming-guidance-for-designers.md) -See the [colour](/design-system/styles/colour) page for a list of theme-able colours. + +## CSS Variables + +Ripple is fully theme-able using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), this allows runtime customisation of site variables within all modern browsers. CSS variables form the API for allowing customisation of SDP sites by setting base tokens for your site. ## Example @@ -22,3 +20,18 @@ To override theme values, simply set the css variable at `:root` or an element t --rpl-clr-primary: #6B19A3; } ``` + +See the [colour](/design-system/styles/colour) page for a list of theme-able colours. + +## Assets + +Alongside the inclusion of site logos, Ripple also uses graphic devices in several key components that allow for customising to apply brand. + +See the following components for guidance on providing graphic elements to theme your site: + +- [Logos](/design-system/styles/logo) +- [Header](/design-system/components/header) + +## Brand application in SDP sites + +See the [SDP Ripple framework](/framework) section for more information on customising SDP websites and applying brand. diff --git a/docs/content/design-system/3.develop/3.usage.md b/docs/content/design-system/3.develop/3.usage.md new file mode 100644 index 0000000000..daba8c3eae --- /dev/null +++ b/docs/content/design-system/3.develop/3.usage.md @@ -0,0 +1,116 @@ +--- +title: Usage +description: Ripple components can be used in several different ways depending on your project needs. +layout: page +links: + - text: Github + url: https://github.com/dpc-sdp/ripple-framework + - text: Storybook + url: /storybook +--- + + +## Using Ripple UI components + +Whilst Ripple is built to implement sites using a framework built on Vue JS and Nuxt, its modular architecture allows adopting different parts depending on your requirements. + +![ripple is made up of Figma design, CSS styles, Vue JS components and Nuxt JS Sites](/assets/img/modules/rpl-modules.png) + + +Ripple UI libraries are usable in the following contexts: + + + +| Library | CSS styles | Vue Components | Ripple Framework (Nuxt) | Web components | +| --------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------- | +| Ripple UI Core | supported | supported |supported | Partial support | +| Ripple UI Forms | supported | supported |supported | not supported | + + + + +### Using in an SDP website + +> If you are using Ripple 2 to build a site on the SDP platform, the UI libraries will be included automatically when scaffolding your project. +> +> For documentation on using Ripple with Nuxt in SDP sites, visit the [Ripple Framework documentation](../../framework/1.index.md) + +### Using in a Vue app + +To install Ripple UI in your project, run: + +`npm install @dpc-sdp/ripple-ui-core --save` + +In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue or index.js file): + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +To use a component, import it from `@dpc-sdp/ripple-ui-core/vue`, note the addition of `/vue`. + +```js + + + +``` + +### Using in a Nuxt app + +To install Ripple UI in your project, run: + +`npm install @dpc-sdp/ripple-ui-core --save` + +Ripple UI exports a nuxt module that you can add to your nuxt config, note the addition of `/nuxt`: + +```js +export default defineNuxtConfig({ + modules: [ + '@dpc-sdp/ripple-ui-core/nuxt' + ] +}) +``` + +In order for the styles to appear correctly, you will need to import them. Do this at the root of your project (usually in your app.vue file): + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +There is no need to import the components as they will be registered globally by the nuxt module + +```js + +``` + +### Webcomponents + +> Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML. +> +> Web components are based on existing web standards. Features to support web components are currently being added to the HTML and DOM specs, letting web developers easily extend HTML with new elements with encapsulated styling and custom behavior. +> https://www.webcomponents.org/ + +Ripple exports a limited set of components as standard browser native webcomponents. The advantage of using Webcomponents is they can be dropped straight into traditional webpages and CMS's that do not have javascript build pipeline such as Squiz Matrix and Salesforce. + +Support for this output target is currently experimental, if you think you have a use case for using Webcomponents in your project please add a comment [here](https://github.com/dpc-sdp/ripple-framework/discussions/658). + +### Using Ripple CSS styles only + +Ripple UI core exports it's CSS stylesheets directly. If you have a use case where you can't use any of the other outputs, you can use our styles directly and provide your own markup based upon the rendered examples in Storybook. + +To import CSS styles only you can import them from the ripple-ui-core package. + +```js +import '@dpc-sdp/ripple-ui-core/style'; +import '@dpc-sdp/ripple-ui-core/style/components'; +``` + +We recommend that you lock the version of `@dpc-sdp/ripple-ui-core` so that any future changes of styles without changes to markup do not break your application. diff --git a/docs/content/design-system/4.styles/focus-state.md b/docs/content/design-system/4.styles/focus-state.md index 038dc63691..8914ab6cde 100644 --- a/docs/content/design-system/4.styles/focus-state.md +++ b/docs/content/design-system/4.styles/focus-state.md @@ -72,4 +72,4 @@ colours: :: ### Theming -For advice on focus state theming, see [theming guidance for designers](https://www.google.com) or [theming guidance for developers](https://www.google.com). +For advice on focus state theming, see theming guidance [for designers](../2.design/4.theme-and-brand-application.md) or [for developers](../3.develop/2.theming.md). diff --git a/docs/content/design-system/5.components/accordion.md b/docs/content/design-system/5.components/accordion.md index 97943aeb80..78fbd9d570 100644 --- a/docs/content/design-system/5.components/accordion.md +++ b/docs/content/design-system/5.components/accordion.md @@ -1,6 +1,6 @@ --- title: Accordion -description: The Accordion component is an expandable panel designed to save space by hiding and revealing content as required. +description: The Accordion component is a panel designed to save space by hiding and revealing content as required. layout: page label: Core diff --git a/docs/content/design-system/5.components/acknowledgment.md b/docs/content/design-system/5.components/acknowledgment.md index 5807d8c005..198af3bba2 100644 --- a/docs/content/design-system/5.components/acknowledgment.md +++ b/docs/content/design-system/5.components/acknowledgment.md @@ -1,5 +1,5 @@ --- -title: Acknowledgment +title: Acknowledgement description: The Acknowledgement component pays respect to the First Peoples of Victoria. layout: page label: Core @@ -11,7 +11,7 @@ label: Core The Acknowledgement of Traditional Owners message: - displays alongside the Aboriginal and Torres Strait Islander flags -- is used in the Footer. +- is used in the footer. ::DocsExample --- diff --git a/docs/content/design-system/5.components/alert.md b/docs/content/design-system/5.components/alert.md index 92933ee4a3..98231190ce 100644 --- a/docs/content/design-system/5.components/alert.md +++ b/docs/content/design-system/5.components/alert.md @@ -1,6 +1,6 @@ --- title: Alert -description: The Alert component displays required actions or important messages to users. +description: The Alert component display required actions or important messages to users. layout: page label: Core diff --git a/docs/content/design-system/5.components/checkbox.md b/docs/content/design-system/5.components/checkbox.md index 8ca8b3ae9a..0233a31a70 100644 --- a/docs/content/design-system/5.components/checkbox.md +++ b/docs/content/design-system/5.components/checkbox.md @@ -1,17 +1,17 @@ --- title: Checkbox -description: Let users select one or more options from a list. +description: The Checkbox component lets users select one or more options from a list. layout: page label: Core --- ## Usage -Users can use checkboxes to: +Use checkboxes to allow users to: - select one or more list options - toggle one option on or off. -Don't use a checkbox if only one option is available, or if you expect the user to only select one option. For this, use the [radio button](/design-system/components/radio-button/) component instead. +Don't use a checkbox if only one option is available or if you expect the user to only select one option. For this, use the radio button component instead. ::DocsExample --- @@ -20,7 +20,7 @@ id: forms-checkbox-group--default-variant :: ### How this component works -Use checkboxes with: +Use checkboxes with a: - form label - optional requirement label - optional hint text @@ -29,31 +29,31 @@ Use checkboxes with: Checkboxes should always have a form and checkbox label. #### Single checkbox -Single checkboxes confirm a user's selection or preference. For example, if a user is agreeing to terms and conditions or are registering for an option. +A single checkbox confirms a user's selection or preference. Examples include when a user is agreeing to terms and conditions or registering for a the only available option presented. #### Checkbox group Checkbox groups provide a list of available items for the user to choose from. Always tell the user how many options they can select. Always give checkbox groups a clear and descriptive label. The label should say what the options represent and should help the user to choose one. Doing so ensures good accessibility, as screen readers read each option's label. -Not all users will know the visual difference between a checkbox and a radio button. You could add extra instructions to guide them, like 'select up to 3 options'. +Not all users will know the visual difference between a checkbox and a radio button. You can could add extra instructions to guide users, for example, ‘Select up to 3 options’. ### When and how to use -- Use checkboxes for more than one selectable list options. -- Use hints to inform users that more than one option can be selected e.g. 'Select all that apply'. -- Always position checkboxes to the left of their labels. This makes them easier to find, especially if using a screen magnifier. -- Ensure you list options in a logical and unbiased manner. It could be helpful to users if you order them from most-to-least common. +- Use checkboxes for lists with more than one selectable option. +- Use hints to inform users that more than one option can be selected, for example, 'Select all that apply'. +- Always position checkboxes to the left of their labels because this makes them easier to find, especially if using a screen magnifier. +- Ensure you list the options in a logical and unbiased manner. It could be helpful to users if you order them from most common to least common. ### When and how not to use -- Don't use checkboxes for a single selectable list option. Use [radio buttons](/design-system/components/radio-button/) for this. -- Don't pre-select checkboxes. Users are more likely to not realise they’ve submitted the wrong answer or missed a question. +- Don't use checkboxes for a single selectable list option, use radio buttons for this. +- Don't pre-select checkboxes because users may not realise they submitted the wrong answer or missed a question. --- ## Variants -Checkboxes have two variants: -- Default, used on white backgrounds. -- Reverse, used on neutral backgrounds. +Checkboxes have 2 variants: +- default, used on white backgrounds +- reverse, used on neutral backgrounds. ### Default ::DocsExample @@ -74,15 +74,19 @@ id: forms-checkbox-group--reverse-variant ### Error All form inputs share error state styling. -Make sure errors follow error message guidance. Always have specific error messages for specific errors. +Make sure errors follow error message guidance. Always have specific error messages for specific errors. Users need to understand why their input or selection was not valid. -**If nothing is selected and the question has options in it** +**Error: nothing is selected and the question has options in it** -Structure this message to help the user to choose which options apply to them. Say ‘Select if \[options\]’. For example, ‘Select if you like summer, winter, autumn, and/or spring.' +Structure this message to help the user to choose which options apply to them. +- Error message: ‘Select if \[options\]’. +- Example: ‘Select if you like summer, winter, autumn, and/or spring'. -**If nothing is selected and the question does not have options in it** +**Error: nothing is selected and the question does not have options in it** -Structure this message to help the user to choose which options apply to them. Say ‘select \[options\]’. For example, 'Select your favourite season.' +Structure this message to help the user to choose which options apply to them. +- Error message: ‘Select \[options\]’. +- Example: 'Select your favourite season'. ::DocsExample --- @@ -94,7 +98,9 @@ id: forms-checkbox-group--invalid --- ## Theming -Checkboxes use colour for interactive states. It adopts the site focus state colour for a consistent focus to active state experience. +A checkbox uses colour for interactive states. + +A checkbox in an active state will adopt the same colour as the overall site’s focus state colour. This means a user’s experience of a checkbox remains consistent while it transitions from a focus to an active state. ::DocsThemeChooser ::DocsExample @@ -109,6 +115,6 @@ To create your own theme see [theming guidance for designers](/design-system/des --- ## Rationale -Both the active and focus state use the site focus colour. This creates a seamless user experience. If we used a different colour, keyboard users would have colour changes between focusing on and interacting with an input field. This could be jarring or confusing to users. +The active and focus states both use the site’s focus state colour. This creates a seamless user experience. If we used a different colour, keyboard users would have colour changes between focusing on and interacting with an input field. This could be jarring or confusing to users. -This is across all form and input elements for a consistent experience. +This occurs across all form and input elements, for a consistent experience. diff --git a/docs/content/design-system/5.components/contact-us.md b/docs/content/design-system/5.components/contact-us.md index 5233b58796..07d5a07630 100644 --- a/docs/content/design-system/5.components/contact-us.md +++ b/docs/content/design-system/5.components/contact-us.md @@ -1,19 +1,19 @@ --- title: Contact us -description: A list of contact details and links to help the user get in touch with you. +description: The Contact us component is a list of contact details and links to help the user get in touch with you. layout: page label: Core --- ## Usage -Contact Us presents the user with multiple pieces of contact information or actions. The details should be related to the page content and a single point of contact. +Use the contact us component to show the user multiple pieces of contact information or actions. The details should be related to the page content and a single point of contact. -Contact Us details can include: -- a contact person -- an address -- a phone number -- social media accounts. +Contact us details can include a: +- contact person +- address +- phone number +- social media account. ::DocsExample --- @@ -27,13 +27,13 @@ id: core-containers-contact-us--contact-us - Display in the sidebar of the page. ### When and how not to use -- If you add social media accounts to Contact Us, don’t add the [Social Share](link) component. +- If you add social media accounts to the contact us component, don’t add the social share component. - Never use unrelated contact details or social media accounts. --- ## Theming -Contact Us uses colour for: +Contact us uses colour for: - visual prominence for key information - link icons. diff --git a/docs/content/design-system/5.components/detail-list.md b/docs/content/design-system/5.components/detail-list.md index 57b6609737..f06f3b89db 100644 --- a/docs/content/design-system/5.components/detail-list.md +++ b/docs/content/design-system/5.components/detail-list.md @@ -1,6 +1,6 @@ --- title: Detail list -description: Display a list of key information to users. +description: The Detail list component shows a list of key information to users. layout: page label: Core @@ -8,19 +8,17 @@ label: Core ## Usage -Detail List displays a list with labels. This surfaces and highlights key information to users. +Use the detail list to display a list with labels. This surfaces (retrieves and displays) and highlights key information to users. -Each row of the Detail List comprises a: +Each row of the detail list comprises a: +- label, a descriptive or informative label for your content, for example, 'Location' +- content, the piece of information itself, for example, 'East Gippsland'. -- Label, which is a description or information label, like 'Location' -- Content, which is the piece of information itself, such as 'East Gippsland'. +The detail list is used to display: +- metadata, for example, ‘Published date' (which shows as '22 March 2023’) +- status, for example of a program or grant. -It's used to display: - -- metadata like ‘Published Date', which would display like ‘22 March 2023’ -- a status of a program or grant. - -Only use the Detail List for simple information. For data or complex information, consider using a [table](design-system/components/table). +Only use the detail list for simple information. For data or complex information, consider using a table. ::DocsExample --- @@ -29,21 +27,21 @@ id: core-containers-description-list--with-link :: ### When and how to use -- Use single words only for the label -- Include a link if you need to -- Keep the labels and summary content clear and concise -- Align all summary content to the longest label +- Use single words only for the label. +- Include a link if you need to. +- Keep the summary content and labels clear and concise. +- Align all summary content to the longest label. ### When and how not to use -- Don't use labels for unrelated summary content -- Don't use to surface information that is not important to users -- Don't use with complex or long form content +- Don't use labels for unrelated summary content. +- Don't use it to surface information that is not important to users. +- Don't use with complex or long form content. --- ## Theming -When a link is present, Detail List uses the link colour for interaction states. +When a link is present, the detail list uses the link colour for interaction states. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/dropdown.md b/docs/content/design-system/5.components/dropdown.md index 8ebb527c81..910b0a9f26 100644 --- a/docs/content/design-system/5.components/dropdown.md +++ b/docs/content/design-system/5.components/dropdown.md @@ -15,7 +15,7 @@ Dropdowns should only be used as a last resort. For example, to find a compromis Many users find dropdowns hard to use. Dropdowns hide content by default and create user confusion, cross-device issues and limited accessibility. Use radio buttons, checkboxes or input fields for most small lists instead. -A compromise might be needed for a long list of options (for example, all dog breeds). Or, when option description lengths vary or wrap over multiple lines. These situations also confuse users by creating layout issues for [checkboxes](/design-system/components/checkbox/), [input fields](/design-system/components/input-field/) or [radio buttons](/design-system/components/radio-button/). +A compromise might be needed for a long list of options (for example, all dog breeds). Or, when option description lengths vary or wrap over multiple lines. These situations also confuse users by creating layout issues for checkboxes, input fields or radio buttons. A dropdown is often called a 'select'. diff --git a/docs/content/design-system/5.components/file.md b/docs/content/design-system/5.components/file.md index e871be52c4..86c00246c6 100644 --- a/docs/content/design-system/5.components/file.md +++ b/docs/content/design-system/5.components/file.md @@ -1,14 +1,13 @@ --- title: File -description: A link to download a file with additional metadata. +description: The File component shows a link, with additional metadata, and lets a user download a file attachment. layout: page label: Core --- ## Usage - -File is a download link that allows users to download an attachment. It is accompanied by an optional description to give the user more information. +Use the File component to let users download an attachment. It is accompanied by an optional description so you can give the user more information. File is made up of: @@ -24,15 +23,15 @@ id: core-containers-file--with-caption ### When and how to use -- Use on any page type -- Include in page content areas only -- Add an optional description -- Add optional updated data if it’s relevant to users -- Always include metadata +- Use on any page type. +- Include in page content areas only. +- Add an optional description. +- Add optional updated data if it’s relevant to users. +- Always include metadata. ### When and how not to use -- Do not use with a non-descript file name. +- Don’t use with a non-descriptive file name. --- diff --git a/docs/content/design-system/5.components/footer.md b/docs/content/design-system/5.components/footer.md index fee309462c..d9d959f87e 100644 --- a/docs/content/design-system/5.components/footer.md +++ b/docs/content/design-system/5.components/footer.md @@ -1,6 +1,6 @@ --- title: Footer -description: Footers help users find information at the bottom of a page. +description: The Footer component helps help users find information at the bottom of a page. layout: page label: Core @@ -8,7 +8,7 @@ label: Core ## Usage -Footers help users find what they need after scrolling to the bottom of a page. They provide supplementary information such as: +Use footers to help users find what they need after scrolling to the bottom of a page. Footers provide supplementary information such as: - copyright - contact information @@ -26,40 +26,33 @@ id: core-navigation-footer--default-story ### How this component works The footer is made up of: - -- optional section links - - Optional Section Links helps you avoid dead-ends by giving a user a way to continue their journey. It provides a user with: - - additional links, both internal and external - - a way to bypass a page’s main navigation. -- optional social links - - Links and social icons can be used to link to social media accounts. -- core site links - - This must always be used. It includes links such as the privacy statement, contact information and terms of use. -- copyright statement - - This adds a copyright statement to the footer to clarify who owns the copyright, specific to your agency or department. For vic.gov.au services, add the Vic Gov State Logo to keep things consistent with the rest of vic.gov.au. -- acknowledgement of country ([acknowledgment](/design-system/components/acknowledgment/) component). +- optional section links, which help avoid dead ends by giving users a way to continue their journey through: + - additional links (internal and external) + - bypassing main navigation +- optional social links, which can be used to link to social media accounts +- core site links, which must always be used and include the privacy statement, contact information and terms of use +- a copyright statement, which clarifies who owns the copyright and is specific to your agency or department (add the State Government of Victoria logo to vic.gov.au services, for sitewide consistency) +- an Acknowledgement of Traditional Owners message (an acknowledgement component). ### When and how to use - -- Use with an optional supporting logo relevant to the site contents -- Use a consistent themed footer across all pages of your site -- Use the optional neutral theme -- Use with an optional image credit for the header image +- Use with an optional supporting logo relevant to the site content. +- Use a consistently-themed footer across all pages of your site. +- Use the optional neutral theme. +- Use with an optional image credit for the header image. ### When and how not to use -- Don’t alter the required links in the core section of the footer -- Don’t change the Acknowledgement Text -- Don’t use with links that are not relevant to your agency +- Don’t alter the required links in the core section of the footer. +- Don’t change the text in the acknowledgement component. +- Don’t use with links that are not relevant to your organisation. --- ## Theming -You can theme the footer in three ways: - -- Site colour palette. -- Neutral colour palette. -- Custom colour palette - see [theming guidance for designers](). +You can theme the footer in 3 ways: +- site colour palette +- neutral colour palette +- custom colour palette (see [theming guidance for designers]()). ### Site colour palette diff --git a/docs/content/design-system/5.components/form-alert.md b/docs/content/design-system/5.components/form-alert.md index c4f410159f..ca6374164c 100644 --- a/docs/content/design-system/5.components/form-alert.md +++ b/docs/content/design-system/5.components/form-alert.md @@ -1,13 +1,13 @@ --- title: Form alert -description: Show the user the outcome of a form submission or validation. +description: The Form alert component shows the user the outcome of a form submission or validation. layout: page label: Core --- ## Usage -Form alerts tell the user if a form has been submitted, or if there were errors in the form that prevented submission. +Use a form alert to tell the user if a form has been submitted, or if there were errors in the form that prevented submission. The form alert appears at the top of the form and the user is automatically scrolled to it on submission. @@ -35,7 +35,7 @@ id: forms-form-alert--error --- ## Variants -Form alert has two variants: +Form alert has 2 variants: - success - error. @@ -81,7 +81,6 @@ id: forms-form-alert--error :: #### Error messages -Error messages Specific error messages must be provided for specific error states. Style your error messages as directed by the ‘Error’ section on the pages for the following form components: - [input field](/design-system/components/input-field/) - [text area](/design-system/components/text-area/) diff --git a/docs/content/design-system/5.components/form.md b/docs/content/design-system/5.components/form.md index 6520439d35..49721a4003 100644 --- a/docs/content/design-system/5.components/form.md +++ b/docs/content/design-system/5.components/form.md @@ -1,21 +1,27 @@ --- title: Form -description: A form guides users to give information and consists of a group of related inputs or controls. +description: The Form component guides users to give information and consists of a group of related inputs or controls. layout: page label: Core --- ## Usage -A form consists of a group of related inputs or controls. Add form input components to your form to capture data from users. +Use a form and its form input components to capture data from users. A form consists of a group of related inputs or controls. -Common form components include the [input field](/design-system/components/input-field/), [text area](/design-system/components/text-area/), [date input](/design-system/components/date-input/), [radio button](/design-system/components/radio-button/), [checkbox](/design-system/components/checkbox/) and [dropdown](/design-system/components/dropdown/). +Common form components include the: +- [input field component](/design-system/components/input-field/) +- [text area component](/design-system/components/text-area/) +- [date input component](/design-system/components/date-input/) +- [radio button component](/design-system/components/radio-button/) +- [checkbox component](/design-system/components/checkbox/) +- [dropdown component](/design-system/components/dropdown/). -An [input field](/design-system/components/input-field/) is for short (single line) text entry. A [text area](/design-system/components/text-area/) is for longer text. +An input field) is for short (single-line) text entry. A text area is for longer text. -Other input types let a user select from predefined options. Use a [radio button](/design-system/components/radio-button/) when a user needs to make only one selection. Use a [checkbox](/design-system/components/checkbox/) for multiple selections. +Other input types let a user select from predefined options. Use a radio button when a user needs to make only one selection. Use a checkbox for multiple selections. -Group related form components in logical chunks (fieldsets). A single form can have multiple fieldsets. For example, a fieldset with several [input fields](/design-system/components/input-field/) for an address, plus a fieldset with a [date input](/design-system/components/date-input/) and [radio button](/design-system/components/radio-button/) for delivery preferences. +Group related form components in logical chunks (fieldsets). A single form can have multiple fieldsets. For example, a fieldset with several input fields for an address, plus a fieldset with a date input and radio button for delivery preferences. The user can submit a form when all fields are valid (see [form alert](/design-system/components/form-alert/)). @@ -40,7 +46,7 @@ Put a label above its component (top-aligned). Labels will then be consistently Placeholder text should not be used as a label. -#### Requirement - Optional vs. mandatory +#### Requirement - optional vs. mandatory Mark an input as ‘required’ if you do not want the form submission to work unless the user gives that information. @@ -69,12 +75,12 @@ Always have specific error messages for specific errors. Users need to understan #### Buttons Button labels should say what the button will do when a user interacts with it. -Ensure the main action button tells the user when the form is being submitted ([see button loading spinner](/design-system/components/button/#loading-spinner)). +Ensure the main action button tells the user when the form is being submitted (see [button loading spinner](/design-system/components/button/#loading-spinner)). To avoid confusing users about how to submit the form, use only one main action button. Do not use a reset button. #### Validation -[Form alert](/design-system/components/form-alert/) is used to tell the user the outcome of the form validation. +Form alert is used to tell the user the outcome of the form validation. If the form has been submitted successfully, the success alert will replace the form. @@ -85,7 +91,7 @@ All fields need a visible, accessible label. (Search fields are sometimes an exc On devices such as mobiles, display the keyboard required for the input. For example, a number keyboard for a date input. -Never disable a submit button. Allow the user to submit the form and then display the error message. Use [form alert](/design-system/components/form-alert/) to display the validation outcome. +Never disable a submit button. Allow the user to submit the form and then display the error message. Use form alert to display the validation outcome. Avoid using placeholder text where possible. It disappears when a user starts typing. Not all screen readers will read out placeholder text. Its colour often lacks the contrast needed for accessible content when using some browser default styling. diff --git a/docs/content/design-system/5.components/header.md b/docs/content/design-system/5.components/header.md index 4a02306594..4673c3a791 100644 --- a/docs/content/design-system/5.components/header.md +++ b/docs/content/design-system/5.components/header.md @@ -1,6 +1,6 @@ --- title: Header -description: The header introduces the purpose and content of a page. +description: The Header component introduces the purpose and content of a page. layout: page label: Core @@ -8,9 +8,11 @@ label: Core ## Usage -Headers inform the user what is on the page. The header must be used at the top of a page above the main body content and styled as level (H1) headings. They include optional content such as introduction text, journey links, a call to action or an introduction banner. +Use headers to inform the user of what is on the page. The header must be placed at the top of a page above the main body content and styled as an H1-level heading. -They should feature a primary message and/or call to action. They can be accompanied by supporting content such as images or corner graphics. +Headers include optional content such as introduction text, journey links, a call to action and an introduction banner. + +Headers should feature a primary message and/or call to action. They can be accompanied by supporting content such as images or corner graphics. The header can also support a campaign logo if required. This will display above the page title. @@ -21,19 +23,17 @@ id: core-containers-header--default-journey-links :: ### When and how to use - -- Keep the header simple and concise -- Use clear call to actions that align with the message or task -- Only use images that add value to the content and support the message -- Include with featured links and buttons to help users perform key tasks -- Include an optional campaign logo +- Keep the header simple and concise. +- Use clear calls to action that align with the message or task. +- Only use images that add value to the content and support the message. +- Include with featured links and buttons to help users perform key tasks. +- Include an optional campaign logo. ### When and how not to use - -- Don’t use a mix of reverse and default page title and introduction text styling -- Don’t include the same links in the main banner and introduction banner -- Don’t use with more than six journey links -- Don’t overload with content +- Don’t use a mix of reverse and default page title and introduction text styling. +- Don’t include the same links in the main and introduction banners. +- Don’t use with more than 6 journey links. +- Don’t overload with content. --- @@ -41,13 +41,13 @@ id: core-containers-header--default-journey-links The header has 3 variants: -- Default. -- Reverse. -- Image. +- default +- reverse +- image. -The default and reverse variants can be used with journey links or a call to action. This guides users to perform tasks or navigate to related information. +The default and reverse variants can be used with journey links or a call to action. These guide users to perform tasks or navigate to related information. -They can display corner images to allow for brand recognition and visual prominence. They can also display a supporting campaign logo if required. +They can display corner images to enhance brand recognition and visual prominence. They can also display a supporting campaign logo if required. The image variant displays a full background image with reverse blocked text. It only supports a page title and introduction text. @@ -69,7 +69,7 @@ id: core-containers-header--default-call-to-action ### Reverse -Reverse uses reversed blocked type for the title and introduction text. This adds visual prominence to the banner and information. +The reverse variant uses reversed blocked type for the title and introduction text. This adds visual prominence to the banner and its information. ::DocsExample --- @@ -87,7 +87,7 @@ id: core-containers-header--reverse-call-to-action An image can be added as a full background image. The title and introduction copy will always display as the reversed blocked type. -Images should not be stretched or too low a resolution. They should also not be complex or include text. +Images should not be stretched or too low in resolution. They should also not be complex or include text. ::DocsExample --- @@ -95,13 +95,12 @@ id: core-containers-header--image-reverse --- :: -### Introduction Banner +### Introduction banner The introduction banner: - - can be used to add content and journey links under the page title and introduction section in the main header banner -- has optional journey links and icon -- content should be related to the content in the main header. +- has an optional icon and journey links +- should contain content relating to the content in the main header. ::DocsExample --- @@ -113,7 +112,7 @@ id: core-containers-header--intro-with-links ## Interaction with other components -When using a featured campaign banner with an image, it can overlap the header depending on the amount of content. By default, this will hide the header's bottom corner shape. +When using a featured campaign banner with an image, the image can overlap the header, depending on the amount of content. By default, this will hide the header's bottom corner shape. The bottom corner shape won't hide if an introduction banner is between the header and campaign banner. @@ -128,12 +127,12 @@ alt: 'A demonstration of the interaction between the Header component and the ca ## Theming -Headers can be themed in two ways: +Headers can be themed in 2 ways: -- Site colour palette. -- Neutral colour palette. +- site colour palette +- neutral colour palette. -It will also adopt theming from the [button](/design-system/components/button) component when displaying the call to action. +It will also adopt theming from the button component when displaying the call to action. If you choose neutral button for your site, the header will display buttons in the neutral theme. @@ -155,9 +154,9 @@ If you choose neutral button for your site, the header will display buttons in t :: :: -### Neutral Theme +### Neutral theme -Implemented at a site level, headers can have a neutral theme option. This option is only applicable to the reverse blocked type. Neutral Headers have predefined neutral colour values that must be used and cannot be edited or customised. +Implemented at a site level, headers can have a neutral theme option. This option is only applicable to the reverse blocked type. Neutral headers have predefined neutral colour values that must be used and cannot be edited or customised. ::DocsExample --- diff --git a/docs/content/design-system/5.components/in-page-navigation.md b/docs/content/design-system/5.components/in-page-navigation.md index 4f85c13be7..19d97346e7 100644 --- a/docs/content/design-system/5.components/in-page-navigation.md +++ b/docs/content/design-system/5.components/in-page-navigation.md @@ -1,6 +1,6 @@ --- title: In-page navigation -description: Help users scan a page and allow for quick navigation. +description: The In-page navigation component sits above a page’s main content and shows a set of links. layout: page label: Core @@ -8,9 +8,9 @@ label: Core ## Usage -A set of links that help users navigate page content. Placed above the main content at the top of a page, it anchor links headings to their page location. +Use in-page navigation to make scanning and navigating within a single page quicker for users. This component shows links to headings that are on the current page. It sits at the top of the page. -Use In-page Navigation for longer content pages. It acts as a table of contents, providing users with a summary and quick navigation across the page. +Use in-page navigation for longer content pages. It acts as a table of contents, providing users with a summary and quick navigation across the page. The left-hand highlight bar: @@ -24,24 +24,23 @@ id: core-navigation-in-page-navigation :: ### When and how to use -- In-page Navigation is ideal for pages with a lot of content. This will help users find their relevant content -- Use headings throughout your content, such as headings level 2 (H2) and 3 (H3). You can use these as navigation links at the start of the page, like a table of contents -- Use subheadings as indented navigation links from the page +- In-page Navigation is ideal for pages with a lot of content. This will help users find their relevant content. +- Use headings throughout your content, such as headings level 2 (H2) and 3 (H3). You can use these as navigation links at the start of the page, like a table of contents. +- Use subheadings as indented navigation links from the page. ### When and how not to use -- Don't link to other pages, including on external sites -- Never use colons in the heading -- Don't use it if you have less than 2 navigation links -- Don't use it with component headings, such as accordion item headings +- Don't link to other pages, including on external sites. +- Never use colons in the heading. +- Don't use it if you have less than 2 navigation links. +- Don't use it with component headings, such as accordion item headings. --- ## Theming -In-page Navigation uses colour to: - -- visually group the navigation -- separate the component from the page content +Ripple’s theming applies colour to in-page navigation so that the user understands: +- its links and navigation heading relate to each other +- they are deliberately separated from the main content. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/input-field.md b/docs/content/design-system/5.components/input-field.md index 4565b81367..ed14d7cd2f 100644 --- a/docs/content/design-system/5.components/input-field.md +++ b/docs/content/design-system/5.components/input-field.md @@ -1,25 +1,25 @@ --- title: Input field -description: Let users input a short amount of text. +description: The Input field component lets users input a short amount of text. layout: page label: Core --- ## Usage -Input fields let users enter, select and search for text. They are normally found in a form but can also be part of a modal or search. +Use input fields to let users enter, select and search for text. They are normally found in a form but can also be part of a modal or search. Use an input field for users to enter text shorter than a single line. Input fields can have multiple input types, depending on the need and use case. They have a text input type by default. Input fields can be used for entering: -- text - basic text or search terms -- phone - a telephone number. -- email - an email address. -- passwords - a user's input is obscured with a dot ('•'), asterisk ('*') or other symbol as they type. +- text: basic text or search terms +- phone: a telephone number +- email: an email address +- passwords: a user's input is obscured with a dot (' • '), asterisk (' * ') or other symbol as they type. -Don’t use input field if the user’s text needs to be more than one line long: use [text area](/design-system/components/text-area/) instead. +Don’t use an input field if the user’s text needs to be more than one line long: use a text area component instead. ::DocsExample --- @@ -77,7 +77,7 @@ If you need a specific type of information, say so in the input label and hint t - Don’t disable copy and paste. - Don’t set a minimum or maximum input limit without explicitly saying this in the hint text. - Don’t use placeholder text to give instructions. -- Don’t write ambiguous error messages only stating what's wrong - explain how the user can fix it. +- Don’t write ambiguous error messages only stating what's wrong, explain how the user can fix it. --- diff --git a/docs/content/design-system/5.components/key-dates.md b/docs/content/design-system/5.components/key-dates.md index d2d974ba8a..59d472faf7 100644 --- a/docs/content/design-system/5.components/key-dates.md +++ b/docs/content/design-system/5.components/key-dates.md @@ -1,6 +1,6 @@ --- title: Key dates -description: A card promoting key dates or events. +description: The Key dates component shows users a card promoting key dates or events. layout: page label: Core @@ -8,7 +8,7 @@ label: Core ## Usage -Use Key Dates to provide a card with brief summaries of up to two events or key dates with a call to action. +Use key dates to provide a card with brief summaries of up to 2 events or key dates with a call to action. ::DocsExample --- @@ -18,28 +18,28 @@ id: core-navigation-card--key-dates ### When and how to use -- Use only on landing pages -- Include in a grid of promo cards -- Only use it once -- Use clear and concise content -- Only use as the last card in the grid -- Include a summary +- Use only on landing pages. +- Include in a grid of promo cards. +- Only use once per page. +- Use clear and concise content. +- Only use as the last card in the grid. +- Include a summary. ### When and how not to use -- Don’t use with navigation cards -- Don’t use the key dates card by itself -- Don’t overload with content -- Don’t use with other interactive elements, like links +- Don’t use with navigation cards. +- Don’t use the key dates card by itself. +- Don’t overload with content. +- Don’t use with other interactive elements like links. - Don’t use it to replace a call to action. --- ## Theming -Key date card uses colour to: +The key date card uses colour to: -- add visual prominence for key information +- add visual prominence to key information - indicate an interaction to users. ::DocsThemeChooser diff --git a/docs/content/design-system/5.components/media-embed.md b/docs/content/design-system/5.components/media-embed.md index c41b321466..eada8c1a0e 100644 --- a/docs/content/design-system/5.components/media-embed.md +++ b/docs/content/design-system/5.components/media-embed.md @@ -1,6 +1,6 @@ --- title: Media embed -description: Images or video with optional text to give context within content. +description: The Media embed component shows an image or video within the page content, with optional text to give context. layout: page label: Core @@ -8,7 +8,9 @@ label: Core ## Usage -Media Embed combines visual elements with text to give context within content. It's used for complex media like graphs and charts with supporting data. +Use media embed to add visual elements including images, videos, graphs, infographics, maps and charts to your page content. + +Use the optional text to combine the visual element with text, so that the user understands the visual element’s context. Optional text should always be used for complex media like graphs and charts with supporting data. Media can be an image or video. Images can display as small, medium or large. @@ -23,32 +25,28 @@ id: core-containers-media-embed--image-landscape :: ### When and how to use - -- Use it with videos, images or complex images -- Add data when using the complex image variant -- Ensure the media is the right size so that it displays without error -- Only add it to the content section of a page -- Add optional image caption and metadata -- Always include alt text +- Use it with videos, images or complex images. +- Add data when using the complex image variant. +- Ensure the media is the right size so that it displays without error. +- Only add it to the content section of a page. +- Add an optional image caption and metadata. +- Always include alt text. ### When and how not to use - -- Don't include media unrelated to the page -- Avoid adding interactive elements, like links, to the caption or metadata sections -- Never use a video without closed captions and a transcript +- Don't include media unrelated to the page. +- Avoid adding interactive elements, like links, to the caption or metadata sections. +- Never use a video without closed captions and a transcript. --- ## Variants Media embed has 3 variants: +- image +- video +- complex media. -- Image. -- Video. -- Complex Media. - -Depending on the variant used, you could display: - +Depending on the variant used, you can display: - a caption - metadata - a transcript link @@ -56,12 +54,12 @@ Depending on the variant used, you could display: ### Image -The image variant has four display options: +The image variant has 4 display options: -- Landscape / 16:9 ratio. -- Portrait / 3:4 ratio. -- Square / 1:1 ratio. -- Avatar / circle. +- landscape / 16:9 ratio +- portrait / 3:4 ratio +- square / 1:1 ratio +- avatar / circle. You can display portrait, landscape and square as small, medium or large. Avatar only displays in small or medium. @@ -113,7 +111,7 @@ id: core-containers-media-embed--video --- :: -### Complex Media +### Complex media Complex media items contain detail. They include: @@ -128,11 +126,11 @@ You can support media by including: - a view fullscreen link - a download media link. -Optional supporting data displays in a dropdown list. Use the best type of content to represent the data, like plain text or a table. +Optional supporting data displays in a dropdown list. Use the type of content that will best communicate your supporting data to the user. For example, some information is conveyed better by a table, rather than plain text. Complex media will always display the full image. The media item will display at a predefined max height or width. -When the media is fullscreen, it displays in the [media fullscreen](/design-system/components/media-fullscreen/) component. +When the media is fullscreen, it displays in the media fullscreen component. ::DocsExample --- diff --git a/docs/content/design-system/5.components/media-fullscreen.md b/docs/content/design-system/5.components/media-fullscreen.md index 89aa8d23f0..1154cc62d0 100644 --- a/docs/content/design-system/5.components/media-fullscreen.md +++ b/docs/content/design-system/5.components/media-fullscreen.md @@ -1,6 +1,6 @@ --- title: Media fullscreen -description: View one or more related media items in fullscreen. +description: The Media fullscreen component is an icon, with text instructions, beneath your media items for users to interact with so they can view one or more related media items in fullscreen. layout: page label: Core @@ -8,11 +8,11 @@ label: Core ## Usage -Media Fullscreen displays media and content from [Media Embed](/design-system/components/media-embed/) and [Media Gallery](/design-system/components/media-gallery/). It always displays the full media item, regardless of its ratio. The item fills the width or height of the available area. +Use media fullscreen to give users the option to toggle a fullscreen view of some media items. Media fullscreen can display media and content from your page’s media embed and media gallery components. It always displays the full media item, regardless of its ratio. The item fills the width or height of the available area. Fullscreen view includes the media item's title and caption. -Media Fullscreen takes over the viewport completely. A transparent background helps users to know they are still on the page. When a user closes fullscreen view, they return to that item in the gallery. +Media fullscreen takes over the viewport completely. A transparent background helps users to know they are still on the page. When a user closes fullscreen view, they return to that same item in the gallery. See [media](/design-system/components/media/) for information relating to file type, ratios and focal point. @@ -24,24 +24,24 @@ id: core-containers-media-gallery--default-story ### When and how to use -- Always display the media item max height or width of the content area -- Always include a title for the media item -- Always include alt text -- Display the media title and caption if used in the base component -- Use when you need to display a media item fullscreen +- Always display the media item max height or width of the content area. +- Always include a title for the media item. +- Always include alt text. +- Display the media title and caption if used in the base component. +- Use when you need to display a media item fullscreen. ### When and how not to use -- Don't use with items that aren't media -- Don't use with a completely opaque background -- Don't use pagination for one media item only -- Don't crop or hide the media item +- Don't use with items that aren't media. +- Don't use with a completely opaque background. +- Don't use pagination for one media item only. +- Don't crop or hide the media item. --- ## Theming -Media Fullscreen adopts its theming from the [pagination](/design-system/components/pagination/) component. +Media fullscreen adopts its theming from the pagination component. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/media-gallery.md b/docs/content/design-system/5.components/media-gallery.md index 5b1ae790c2..7674a45b47 100644 --- a/docs/content/design-system/5.components/media-gallery.md +++ b/docs/content/design-system/5.components/media-gallery.md @@ -1,6 +1,6 @@ --- title: Media gallery -description: A series of images users can side-scroll through. +description: The Media gallery component is a series of images users can side-scroll through. layout: page label: Core @@ -8,11 +8,11 @@ label: Core ## Usage -Media Gallery collects a series of related images into a gallery. It allows users to scroll through related images. It's best used for displaying images. +Use a media gallery to collate a series of related images into a gallery. Media gallery allows users to scroll through related images. It's best used for displaying images. -It combines images and text to give users context within the content. +Media gallery combines images and text to give users context within the content. -Media will display either landscape or portrait at predefined ratios. +Media items inside a media gallery will display as either landscape or portrait, at predefined ratios. See [media](/design-system/components/media/) for information relating to file type, ratios and focal point. @@ -23,19 +23,17 @@ id: core-containers-media-gallery--default-story :: ### When and how to use - -- Use with related images only -- Use at least 2 images -- Always use a media title -- Include an optional caption -- Use on any page type +- Include related images only. +- Use at least 2 images. +- Always use a media title. +- Include an optional caption to help users understand images' context and relevance to the page content. +- Use on any page type. ### When and how not to use - -- Don't use for decorative purposes -- Don't use sensory images -- Don't use for a single image. Consider using the [media embed](/design-system/components/media-embed/) component -- Don't use with media unrelated to page content +- Don't use for decorative purposes. +- Don't use sensory images. +- Don't use for a single image, instead use the media embed component. +- Don't use with media unrelated to page content. --- @@ -47,7 +45,7 @@ Media embed uses colour for: - indicating an interaction to users - interactive states. -It also adopts its theming from the [pagination](/design-system/components/pagination/) component. +It also adopts its theming from the pagination component. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/media.md b/docs/content/design-system/5.components/media.md index 6d7fcc6edc..a6fb55c6dd 100644 --- a/docs/content/design-system/5.components/media.md +++ b/docs/content/design-system/5.components/media.md @@ -1,6 +1,6 @@ --- title: Media -description: Media communicates and differentiates a product through visuals. +description: The Media component is a container that houses media items to use in other components on a page. layout: page label: Core @@ -8,11 +8,13 @@ label: Core ## Usage -Media is a container that houses media items to use in other components. These can include in a media gallery, on cards, etc. +Use media to communicate and differentiate specific information through visuals. + +Media items sit within other components such as cards, or a media gallery. Use images if they help users complete a task. Images can make it easier for some people to understand information. -Use Media to combine visual elements with text. This gives your content context and alignment. +Use media to combine visual elements with text. This gives your content context and alignment. ::DocsExample --- @@ -21,20 +23,18 @@ id: core-containers-image--image :: ### When and how to use - -- Always get copyright for all media used -- Nest Media in other components -- Choose diverse images that reflect and support the diversity of Victoria -- Only media that's relevant to the content -- Always include alt text for each media item -- Use appropriate resolution for the content -- Always include a transcription for all audio content +- Always get copyright for all media used. +- Nest media in other components. +- Choose diverse images that reflect and support the diversity of Victoria. +- Only media that's relevant to the content. +- Always include alt text for each media item. +- Use appropriate resolution for the content. +- Always include a transcription for all audio content. ### When and how not to use - -- Don't use a media item without alt text -- Don't use video content without captions -- Don't crop an image without a clear focal point +- Don't use a media item without alt text. +- Don't use video content without captions. +- Don't crop an image without a clear focal point. --- @@ -47,15 +47,15 @@ The ratios you can use for media include: - 16:9 - 21:9 - 3:1 -- Avatar (circle) +- avatar (circle). -### Copyright Requirements +### Copyright requirements You must get permission (a licence) to use copyright material. This includes images and text. Some images are available under an open access licence, such as [Creative Commons](https://au.creativecommons.net/). Alt text is also licensed under copyright. -### File Resolution +### File resolution Image resolution must be appropriate for the content. @@ -63,13 +63,13 @@ Don’t embed images with a large file size into content that you will publish o Design for mobile devices first. An image will scale to the device people view it on. Check that it’s easy to read on a mobile phone screen and a desktop before you publish it. -### Focal Point +### Focal point Always ensure that images work on all screen sizes. Select the focal point of the image to best position images in any area. Consider cropping smaller images more to keep the impact of the original image. -### Media Types +### Media types Multiple types of media can are supported and used to add meaning to content. These include: @@ -85,56 +85,46 @@ Multiple types of media can are supported and used to add meaning to content. Th Make sure you use the correct media type for the content it is supporting. -### Files types +### File types There are many image file types. Seek specialist advice to optimise an image file as a vector or raster file format. The following file types are recommended: - -- Photographs - - jpeg - - png -- Icons +- photographs + - jpeg + - png +- icons - svg - - png -- Charts / Graphs + - png +- charts/graphs - svg - png -- Video +- video - mp4 -- Audio - - wav +- audio + - wav. ### Alternative text -Alternative text (alt text) is: - -- read out by screen readers -- displayed if an image doesn't load -- displayed if images are switched off. - -Except for decorative images, all images must have alt text. Alt text must: +All images, except purely decorative images, need a text alternative (alt text). Without this, your page will not address [WCAG 2.0 Criterion 1.1.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html) or meet WCAG 2.0 AA standards. These are the minimum accessibility standards required for all Victorian Government communications (see: [Brand Victoria guidelines](https://www.vic.gov.au/brand-victoria-guidelines-logos) for more information). -- inform a user what information the image conveys -- describe the content and the image function -- be specific to that image, relevant and concise -- include normal punctuation, so that the text is easy to read and understand. +The [Web Accessibility initiative alt decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) also guides you on whether your image needs alt text or not. -When writing alt text, never: +For purely descriptive images, the alt text attribute instead reads: alt=””. -- repeat page information -- include information not already in the image -- include photographer name or image creator -- begin with 'graphic of, 'image of', etc. +#### What alt text does -For no alt text, use alt="" . This includes if the image is: +Alt text gives users who use screen readers (or devices that are not loading, or displaying, images) the information an image is meant to convey because: +- a screen reader can read the alt text aloud +- alt text is shown in the place of ‘broken’ or unloaded images on the page. -- an icon that already has a text label (to avoid repetition) -- decorative and/or doesn't include important content -- linked elsewhere and isn't needed to understand where it's linking to. -If you need help with images and alt text, use the [Web Accessibility initiative alt decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/). +#### How to write alt text -Avoid images that contain text. If a PNGs JPGs has text, zooming renders it unreadable. For images with text, use SVG. Always use the image text for alt text. +Alt text must serve the equivalent purpose of the image itself, by: +- being short but specific (for example, ‘a Harry Potter novel’ rather than ‘a novel’) +- explaining the image’s function in the context of the page or content section (for example, ‘Search’ rather than ‘Magnifying glass’) +- using normal punctuation that helps users understand the text +- including the image text in the alt text (for images with text). -For guidance on writing alt text, refer to [Alt text, captions and titles for images](https://www.stylemanual.gov.au/content-types/images/alt-text-captions-and-titles-images) in the Australian Government Style Manual. +For more guidance on writing alt text, refer to [Alt text, captions and titles for images](https://www.stylemanual.gov.au/content-types/images/alt-text-captions-and-titles-images) in the Australian Government Style Manual. diff --git a/docs/content/design-system/5.components/option-button.md b/docs/content/design-system/5.components/option-button.md index 795ecfcfe0..5b2581c092 100644 --- a/docs/content/design-system/5.components/option-button.md +++ b/docs/content/design-system/5.components/option-button.md @@ -1,6 +1,6 @@ --- title: Option button -description: A set of buttons to help users filter content. +description: The Option button component is a set of buttons to help users filter content. layout: page label: Core @@ -28,17 +28,17 @@ Never preselect an option button on default. Users might miss that a filter has ### When and how to use -- Help users filter content or results -- Use short labels only -- Order labels in alphabetical order to help users scan quickly -- Add an ‘apply filter’ button if the option button will be used together with other form elements +- Help users filter content or results. +- Use short labels only. +- Order labels in alphabetical order to help users scan quickly. +- Add an ‘apply filter’ button if the option button will be used together with other form elements. ### When and how not to use -- Don’t use for a call to action -- Don’t use with long content -- Never use without a form label -- Never preselect an individual option button +- Don’t use for a call to action. +- Don’t use with long content. +- Never use without a form label. +- Never preselect an individual option button. --- diff --git a/docs/content/design-system/5.components/page-action.md b/docs/content/design-system/5.components/page-action.md index f9743a52ae..ea2dd0ae36 100644 --- a/docs/content/design-system/5.components/page-action.md +++ b/docs/content/design-system/5.components/page-action.md @@ -1,6 +1,6 @@ --- title: Page action -description: Links that allow users a choice of actions, such as printing or downloading a document. +description: The Page action component presents a collection of links that offer users a choice of actions, such as printing or downloading a document. layout: page label: Core @@ -8,17 +8,19 @@ label: Core ## Usage -A collection of links that allow users a choice of actions at a page level. This includes printing or downloading a document. +Use the Page action component to let users print or download pages and content. -The Page Action component displays a combination of two page level actions: +Page action presents as a collection of links giving users a choice of actions at a page level. This includes printing or downloading a document. -- Print page: print the page a user is on. -- Print full document: prints all pages in a publication or document. Printing a full document page action prints all pages in the publication, not only the page the user is on. -- Download document: download a copy of the content that the page editor uploaded. You can add more than one document to the page action component. But, the documents should only be what's already on the page. Don't add new or extra content. +The component displays a combination of page-level actions. -Never use page actions for anything other than what we've stated above. Don't use it for links. +- Print page: prints the page a user is on. +- Print full document: prints all pages in a publication or document, not only the page the user is on. +- Download document: downloads a copy of the content that the page editor uploaded. You can add more than one document to the page action component. The documents should only be what's already on the page. Don't add new or extra content. -The print action prints the full document (section), not just the page the user is on. The document action, downloads a document that has been uploaded in the content management system. +Never use page actions for anything other than the above. Don't use it for links. + +The print action prints the full document (section), not just the page the user is on. The document action downloads a document that has been uploaded in the content management system. ::DocsExample --- @@ -28,16 +30,16 @@ id: core-containers-page-action--default-story ### When and how to use -- Only use in a page's sidebar section -- Use as the first component in the sidebar, above the [vertical navigation](/design-system/components/vertical-navigation/) -- Use with or without one or more documents -- Include metadata with uploaded documents +- Only use in a page's sidebar section. +- Use as the first component in the sidebar, above the vertical navigation. +- Use with or without one or more documents. +- Include metadata with uploaded documents. ### When and how not to use - Don't use: - in the content area of a page - - with a document that has different content to the page + - with a document that has content different to the page's content - for any other user actions. --- diff --git a/docs/content/design-system/5.components/pagination.md b/docs/content/design-system/5.components/pagination.md index 53a7d23dd5..3a57623e65 100644 --- a/docs/content/design-system/5.components/pagination.md +++ b/docs/content/design-system/5.components/pagination.md @@ -1,6 +1,6 @@ --- title: Pagination -description: Pagination helps users navigate forwards and backwards through content. +description: The Pagination component divides your content across more than one page into smaller lists to help users navigate forward and backwards. layout: page label: Core @@ -8,6 +8,8 @@ label: Core ## Usage +Use pagination to help users navigate forwards and backwards through your content. + Pagination breaks down content, making it more concise and less overwhelming. It does this by dividing your content across more than one page and into smaller lists. This makes it easier for users to find what they need. Examples include: @@ -19,7 +21,7 @@ Pagination helps users to identify: - how many pages or items they can navigate through - where the page or item they are viewing sits in the order of other pages or items -- how they can immediately navigate to other pages or items +- how they can immediately navigate to other pages or items. Pagination sits at the bottom of each page. It's a quick and easy way for users to move between each page. @@ -35,32 +37,32 @@ id: core-navigation-page-links--page-links ### When and how to use -- Stack Standard pagination variant links vertically -- Only use Standard and Complex variants at the bottom of the body content area -- Use the Simple variant nested in components. For example, the [Media Gallery](/design-system/components/media-gallery/) or [Carousel](/design-system/components/carousel/) -- Use an ellipses to replace any skipped pages -- Use pagination to avoid an infinite scroll of results, which can be a problem for keyboard users +- Stack standard pagination variant links vertically. +- Only use standard and complex variants at the bottom of the body content area. +- Use the simple variant nested in components, for example, the [media gallery](/design-system/components/media-gallery/) or [carousel](/design-system/components/carousel/). +- Use ellipses to replace any skipped pages. +- Use pagination to avoid an infinite scroll of results, which can be a problem for keyboard users. ### When and how not to use -- Don't use pagination for one page only -- Only choose one pagination variant, never mix or combine them -- Always put the user first, so don't break up content if it reduces usability or performance -- Don't user pagination if a user journey is linear, like when completing a form +- Don't use pagination for one page only. +- Only choose one pagination variant, never mix or combine them. +- Always put the user first, so don't break up content if it reduces usability or performance. +- Don’t use for linear user journeys such as form completion. --- ## Variants -Pagination has three main variants: +Pagination has 3 main variants: -- Simple, for a small number of items or used in other components. -- Standard, to navigate through a sall number of pages. -- Complex, when there are a large number of pages to navigate through. +- simple, for a small number of items or used in other components +- standard, to navigate through a small number of pages +- complex, when there is a large number of pages to navigate through. ### Simple -The simple variant is for navigating through a small number of items. Use it to nest pagination in other components, like [Media Gallery](/design-system/components/media-gallery/), [Media Fullscreen](/design-system/components/media-fullscreen/) and [Carousel](/design-system/components/carousel/). +The simple variant is for navigating through a small number of items. Use it to nest pagination in other components, like media gallery, media fullscreen and carousel. ::DocsExample --- @@ -70,10 +72,10 @@ id: core-navigation-pagination--simple-tally ### Standard -The standard variant is for navigating through a small number of pages. It has two options for label display: +The standard variant is for navigating through a small number of pages. It has 2 options for label display: -- Page titles. -- Page numbers. +- page titles. +- page numbers. You can use page titles to give more context. @@ -101,9 +103,9 @@ id: core-navigation-page-links--example-count The complex variant lets users navigate through a large number of pages. It's ideal for a long list of search results. -The user can use the next and back controls to move forward and backward through the pages. The user can navigate straight to a page by selecting its specific page number. +The user can interact with the next and back controls to move forward and backward through the pages. The user can navigate straight to a page by selecting its specific page number. -Three pages should always remain highlighted: +There are 3 pages that should always remain highlighted: - The first page. - The current page. @@ -114,9 +116,9 @@ Never show the previous page link on the first page because it will confuse the Display page numbers for the: - current page on all screen sizes -- previous and next pages on smaller screens sizes +- previous and next pages on smaller screen sizes - page immediately before and after the current page on larger screen sizes -- first and last pages on all screen sizes. +- first and final pages on all screen sizes. ::DocsExample --- diff --git a/docs/content/design-system/5.components/primary-navigation.md b/docs/content/design-system/5.components/primary-navigation.md index 1d6ee165df..820bd0bcd5 100644 --- a/docs/content/design-system/5.components/primary-navigation.md +++ b/docs/content/design-system/5.components/primary-navigation.md @@ -1,16 +1,19 @@ --- title: Primary navigation -description: Help users identify where they are by providing links to key areas of the website. This help users get to where they need to go. +description: The Primary navigation component appears as a menu sitting at the top of the page and contains links to site’s content pages. layout: page label: Core --- ## Usage -The primary navigation helps a user to find the right content for them. Use it to show the level of your site's information architecture (IA). It works with the [Header](/design-system/components/header/) to orientate your users, and helps keep all pages consistent. Use it as the primary way for users to navigate your site. + +Use primary navigation to help users get to where they need to go. It shows links to key areas of the website and guides users to the content they are looking for. The main way users journey through your site should be through primary navigation. + +Use primary navigation to let users identify where they are. It helps users know their current page location within the overall site. The primary navigation contains: -- site logo +- a site logo - navigation links - optional search link. @@ -26,20 +29,22 @@ id: core-navigation-primary-nav--default-story ### How this component works #### Logo -The logo helps users understand which site they are visiting. Clicking it should always take users back to a homepage. It's always centred vertically in the primary navigation bar. +The logo lets users instantly recognise which organisation or entity owns the current page. When users interact with the logo, it should direct them to the site’s homepage. -#### Co-Branding Logos +Within the primary navigation component, the logo is centred vertically. + +#### Co-branding logos Primary navigation allows for co-branding when required. The maximum size a co-branded logo can appear is 40h x 140w pixels. See [logo](/design-system/styles/logo/) for guidance and requirements including co-branding. #### Navigation links -The primary navigation displays the top level of the site’s IA. When the link has child pages, a chevron displays next to the top page name. When clicked, this opens the mega menu and displays the child pages. +The primary navigation displays the top level of the site’s information architecture (IA). When the link has child pages, a chevron (a v-shaped arrow icon) displays next to the top page name. When clicked, this opens the mega menu and displays the child pages. When there are no child pages, there is no chevron and it takes users to the page. #### Mega menu -The mega menu gives users access to pages deeper into the site. Use it if your site or service has more than 1 level of navigation. If a mega menu item has a chevron, users can expand it to display its child pages. +The mega menu gives users access to pages deeper in the site. Use it if your site or service has more than one level of navigation. If a mega menu item has a chevron, users can expand it to display its child pages. #### Search menu The menu can display a search bar to provide users the option to perform a site search. @@ -47,7 +52,7 @@ The menu can display a search bar to provide users the option to perform a site #### Smaller devices The primary navigation adapts to small devices. The breakpoint for displaying the collapsed menu is 992px. -It displays as a single menu labelled dropdown option. And it displays all levels when opened. +On smaller devices primary navigation shows as a dropdown showing only one labelled menu item. It contains more levels of navigation options, which remain hidden until the single dropdown is interacted with and opens. To meet [WCAG2.0 Criterion 1.1.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv.html), and for increased consistency across screens sizes, the primary navigation: - uses the menu label and a chevron @@ -56,7 +61,7 @@ To meet [WCAG2.0 Criterion 1.1.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/tex > 1.1.1 Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. #### Responsive behaviour -The main navigation won't support a large number of items. This is because it is a horizontal list. +Primary navigation supports only a small number of items. This is because it is a horizontal list. Take this into account when defining your site's IA. @@ -64,37 +69,37 @@ A maximum number of links can display before the navigation bar will respond to When used with a single logo: - 992-1199px breakpoint can display 6 links (including search) -- 1200+ breakpoint can display 7 links (including search) +- 1200+ breakpoint can display 7 links (including search). When used with a co-branded logo: - 992-1199px breakpoint can display 5 links (including search) -- 1200+ breakpoint can display 6 links (including search) +- 1200+ breakpoint can display 6 links (including search). When using the collapsed menu in the navigation bar, the mega menu will also display the mobile (collapsed) version. #### Scroll behaviour The primary navigation has show and hide behaviour on user scroll. -- Scroll down - the primary navigation hides from view. -- Scroll up - the primary navigation shows at the top of the viewport. +- Scroll down: the primary navigation hides from view. +- Scroll up: the primary navigation shows at the top of the viewport. #### Interaction with other components -When a site has a [quick exit button](/design-system/components/button/#destructive), it sits underneath the primary navigation. If the user opens the mega menu or search menu, the quick exit button moves inside the menu container. So, this action will always be available to users. +When a site has a quick exit button (a button component that uses the destructive variant), it sits underneath the primary navigation. If the user opens the mega menu or search menu, the quick exit button moves inside the menu container. So the quick exit action will always be available to users. --- ### When and how to use - Use across all pages of your site. - Use descriptive, recognisable link labels. -- Display links in priority order. More in-demand links should start on the left, with other links on the right. -- Structure your navigation according to user need. Your research should point to what tasks and information your users need most. -- Do use with optional user action such as login if required. +- Display links in priority order: move from left (for most-used links) to right (for least-used links). +- Base your navigation's structure on user research. +- Structure navigation to prioritise tasks and information your research says users need the most. +- Use with optional user action, such as login, if required. ### When and how not to use - Don’t label links with jargon or unfamiliar terms. - Don't use more than 150 characters per menu item. -- Don't use hover to expand dropdown lists. Some users find it difficult and it doesn't work on touch screen devices. -- Design your IA based on user research, and not your organisational structure. - +- Hover should never be used to expand dropdown lists as it is not reliably accessible or responsive. +- An organisational structure should not be used as a navigation stucture. --- ## Theming @@ -102,7 +107,7 @@ Primary navigation uses colour for: - visual prominence and brand recognition - interactive states. -Primary navigation also adopts its theming from the [Search bar]() component. +Primary navigation also adopts its theming from the search bar component. ::DocsThemeChooser ::DocsExample @@ -115,7 +120,7 @@ Primary navigation also adopts its theming from the [Search bar]() component. --- ## Accessibility -To meet [WCAG2.2 Criterion 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum), the primary navigation bar uses the space either side of menu items. This allows for increased touch targets and the use of the [block focus state](/design-system/styles/focus-state/). +To meet [WCAG2.2 Criterion 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum), the primary navigation bar uses the space either side of menu items. This allows for increased touch targets and the use of the block focus state styling. > 2.5.8 Target Size (Minimum) The size of the [target](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum#dfn-target) for [pointer inputs](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum#dfn-pointer-input) is at least 24 by 24 [CSS pixels](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum#dfn-css-pixel), diff --git a/docs/content/design-system/5.components/profile.md b/docs/content/design-system/5.components/profile.md index 24ea0a32c7..0a791c1220 100644 --- a/docs/content/design-system/5.components/profile.md +++ b/docs/content/design-system/5.components/profile.md @@ -1,6 +1,6 @@ --- title: Profile -description: An avatar with supporting text to display key information. +description: The Profile component shows an avatar (image) on your page, with supporting text to display key information. layout: page label: Core @@ -8,7 +8,7 @@ label: Core ## Usage -Profile displays an avatar image with summary content. This highlights key information to users. +Use profile to highlight key information to users by showing an avatar image with summary content. This highlights key information to users. Each row of content includes a: @@ -21,7 +21,7 @@ It's used to display key information, including: - date - category. -Only use the Profile component for displaying simple information. For data or complex information, consider using a [table](/design-system/components/table/). +Only use the profile component for displaying simple information. For data or complex information, consider using a table. ::DocsExample --- @@ -31,15 +31,15 @@ id: core-containers-profile--default-story ### When and how to use -- Keep label as short as possible (1 to 2 words, like a name) -- Keep all content clear and concise -- Display at the top of profile pages -- Always add alt text to the image -- Only use an image that's relevant to the summary +- Keep label as short as possible (under 2 words, like a name). +- Keep all content clear and concise. +- Display at the top of profile pages. +- Always add alt text to the image. +- Only use an image that's relevant to the summary. ### When and how not to use -- Never use a label that doesn't match the summary -- Don't use unimportant, complex, or longform content -- Don't include punctuation -- Never use full URLs in the label or summary +- Never use a label that doesn't match the summary. +- Don't use unimportant, complex or longform content. +- Don't include punctuation. +- Never use full URLs in the label or summary. diff --git a/docs/content/design-system/5.components/radio-button.md b/docs/content/design-system/5.components/radio-button.md index a7967b7dbc..c331ede0ec 100644 --- a/docs/content/design-system/5.components/radio-button.md +++ b/docs/content/design-system/5.components/radio-button.md @@ -1,6 +1,6 @@ --- title: Radio button -description: Let users select one option from a list. +description: The Radio button component shows a list of options, with a radio (round) button to the left of each option’s description. layout: page label: Core @@ -8,9 +8,11 @@ label: Core ## Usage -Radio buttons help users make a single selection from a list of available items. +Use radio buttons to let users select one option from a list. -Never use radio buttons if a user may select multiple options. When they need more than one option, use the [checkbox](/design-system/components/checkbox/) component. +They help users make a single selection from a list of available items. + +Never use radio buttons if a user may select multiple options. Use a checkbox component instead. ::DocsExample --- @@ -21,11 +23,10 @@ id: forms-radio-group--default-variant ### How this component works Use radio buttons with: - - form label - radio label - optional requirement label -- optional hint text +- optional hint text. Radio buttons should always have a form and radio label. @@ -34,28 +35,26 @@ Always use a descriptive label for groups of radio buttons. The label should say Not all users will know the visual difference between a radio button and a checkbox. You could add extra instructions to guide then, like 'select one option’. ### When and how to use - -- Use if only one options needs selecting from a list -- Use reverse variant on grey backgrounds -- Always write clear and concise radio label descriptions -- Ensure you list options in a logical and unbiased manner. It could be helpful to users if you order them from most-to-least common -- Use hints to tell users they can only select one option -- Always position radios to the left of their labels. This makes them easier to find, especially if using a screen magnifier +- Use if only one options needs selecting from a list. +- Use the reverse variant on grey backgrounds. +- Always write clear and concise radio label descriptions. +- Ensure you list options in a logical and unbiased manner. +- If unsure about the list order, place from most common, to least common. +- Use hints to tell users they can only select one option. +- Always put the radio button on the left side of its label description to allow users, particularly those using screen magnifiers, to find labels. ### When and how not to use - -- Don't use for lists with more than one possible option. Use [checkboxes](/design-system/components/checkbox/) for these -- Don't use a radio group with an horizontal alignment for displaying more than 2 options -- Don't list all possible options. Add an option for 'other' +- Don't use for lists with more than one possible option. Use checkboxes for these. +- Don't use a radio group with an horizontal alignment for displaying more than 2 options. +- Don't list all possible options. Add an option for 'other'. --- ## Variants -Radio buttons have two variants: - -- Default, used on white backgrounds. -- Reverse, used on neutral backgrounds. +Radio buttons have 2 variants: +- default, used on white backgrounds +- reverse, used on neutral backgrounds. ### Default @@ -75,23 +74,27 @@ id: forms-radio-group--reverse-variant ### Error -All form inputs share error state styling. - -Make sure errors follow error message guidance. Always have specific error messages for specific errors. +All form inputs share error state styling. Always have specific error messages for specific errors. Users need to understand why their input or selection was not valid. -**If it’s a ‘yes’ or ‘no’ question** +When creating an error message for radio buttons, use the wording below. -Structure this message to help the user understand why they would say yes. For example, say ‘Select yes if [true value]’. Like, ‘Select yes if you drive a car’. +**Error: invalid response to a yes/no question** -**If there are two options which are not ‘yes’ and ‘no’** +Structure this message to help the user understand why they would say yes. +- Error message: ‘Select yes if \[the information is true\]’. +- Example: 'Select yes if you drive a car'. -Structure this message to help the user to choose one of two options. For example, say 'Select if [true value]’. Like, 'Select if you drive a car or a truck'. +**Error: invalid response to a choice (other than yes/no) from 2 options** -**If there are more than two options** +Structure this message to help the user choose the option that applies to them. +- Error message: ‘Select if \[the choice you are asking the user to make\].' +- Example: ‘Select if you drive a car or truck’. -Structure this message to help the user to choose one from more than two options. For example, ‘Select the day of the week you drive the most.' +**Error: invalid response to a choice from 3 or more options** -**Need an example for error message, this is a placeholder** +Structure this message to help the user to choose a single option from 3 or more options. +- Error message: ‘Select the \[singular piece of information you are seeking from the user\].' +- Example: ‘Select the day of the week you drive the most.' ::DocsExample --- @@ -103,7 +106,9 @@ id: forms-radio-group--default-variant ## Theming -Radio buttons use colour for interactive states. It adopts the site focus state colour for a consistent focus to active state experience. +Radio buttons use colour for interactive states. + +A radio button component in an active state will adopt the same colour as the overall site’s focus state colour. This means a user’s experience of that radio button remains consistent while it transitions from a focus to an active state. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/related-links.md b/docs/content/design-system/5.components/related-links.md index c8fa14f019..4e065da6f6 100644 --- a/docs/content/design-system/5.components/related-links.md +++ b/docs/content/design-system/5.components/related-links.md @@ -1,6 +1,6 @@ --- title: Related links -description: A list of links to help users discover related content. +description: The Related links component is a list of links to help users discover related content. layout: page label: Core @@ -8,7 +8,7 @@ label: Core ## Usage -Related links present a user with a list of links. They can use these to explore content related to the current page or context, or to the next best action. +Use related links to present a user with a list of links. They can use these to explore content related to the current page or context, or to the next best action. Use if you’re presenting the user with related information or actions to help them deep dive into content. @@ -22,16 +22,16 @@ id: core-navigation-related-links--related-links ### When and how to use -- Use to help users discover related content -- Only use in the side bar section pages -- Use at least 2 links -- Use no more than 8 links -- Keep description clear and concise, and specific to each link +- Use to help users discover related content. +- Only use in the sidebar section pages. +- Use at least 2 links. +- Use no more than 8 links. +- Keep description clear, concise and specific to each link. ### When and how not to use -- Don't add unrelated links -- Don't overload each with too many words -- Don't use punctuation -- Don't link to documents or videos. Embed these, instead -- Don't include other interactive elements, like buttons +- Don't add unrelated links. +- Don't overload each link with too many words. +- Don't use punctuation. +- Don't link to documents or videos - instead, embed them. +- Don't include other interactive elements, like buttons. diff --git a/docs/content/design-system/5.components/results-listing.md b/docs/content/design-system/5.components/results-listing.md index f1740fec27..4dc4d95fb9 100644 --- a/docs/content/design-system/5.components/results-listing.md +++ b/docs/content/design-system/5.components/results-listing.md @@ -1,6 +1,6 @@ --- title: Results listing -description: Display a list of results to users displaying key information related to the search. +description: The Results listing component shows a list of search result items, with each item displaying key information relevant to that search. layout: page label: Core @@ -8,17 +8,16 @@ label: Core ## Usage -Use a results listing to display content results, like search results or news items. It surfaces important information to the user. +Use a results listing to display content results, like search results or news items. It surfaces (retrieves and shows) important information to the user. -This component includes: - -- Title, to identify the page or result title -- Summary, to sum up the content for the user -- URL, which tells the user where the content is -- Featured content, which gives key items visual prominence -- Topic/Category, which is a way to give a user greater context over the item -- Date, which can display a published or updated date. Only use if it will improve the user experience and is relevant to the content -- Keyword term bold styling, which gives visual prominence to the search keyword term +A results listing shows multiple results items, each with their own: +- title, telling the user the name of the result +- summary, summing up the result’s content for the user +- URL, telling the user the website address for the result +- featured content, visually highlighting key content from the result +- topic/category, putting the result into its context within a broader page or site +- date, showing a result’s published (simple variant) or updated (default variant) date +- keyword term bold styling, showing the search term(s) in bold in the result displayed. When displaying the results listing, consider a user's needs. Only display what will help them to make an informed decision. @@ -29,25 +28,22 @@ id: core-navigation-result-listing--result-listing :: ### When and how to use - -- Bold the search term -- Test results. They must always be accurate and relevant -- Keep descriptions short, no more than 150 words -- Display up to 10 results +- Put the search term in bold. +- Test results so they are correct and relevant to the search term. +- Keep descriptions under 150 words. +- Display up to 10 results. ### When and how not to use - -- Don't display the result title only -- The title shouldn't be the only interactive element. Ensure the entire item is interactive -- Don't use both updated date and published date. Choose one only -- Don't display more than 10 results +- Don't display the result title only. +- Don’t make only the title interactive, ensure the entire result is interactive. +- Don't use both updated date and published date, choose one only. +- Don't display more than 10 results. --- ## Variants -A result listing's two main variants are: - +A result listing's 2 main variants are: - default - simple. @@ -59,9 +55,9 @@ Key information can include: - audience - status -- grants metadata such as grant value +- grants metadata such as grant value. -The default variant users the 'updated date' by default. +The default variant users the updated date by default. ::DocsExample --- @@ -73,7 +69,7 @@ id: core-navigation-result-listing--with-details The simple variant displays the page title with accompanying metadata. -It uses the published date by default, which pulls in from the metadata. +It uses the published date by default, which is automatically pulled in from the metadata. We recommend using this variant when displaying simple results, like news items. @@ -90,7 +86,7 @@ id: core-navigation-result-listing--with-meta Results listing uses colour for: - icons -- indicating to the user there is an interaction +- indicating to the user there is an interaction possible - interactive states. When displaying key information such as status, the icon should adopt the relevant semantic colour. diff --git a/docs/content/design-system/5.components/search-bar.md b/docs/content/design-system/5.components/search-bar.md index 01bd807734..7cb28d8922 100644 --- a/docs/content/design-system/5.components/search-bar.md +++ b/docs/content/design-system/5.components/search-bar.md @@ -1,6 +1,6 @@ --- title: Search bar -description: Allow users to enter keywords and search content on the website. +description: The Search bar shows a text input field with a search button to let users enter keywords and search content on the website. layout: page label: Core @@ -8,9 +8,11 @@ label: Core ## Usage +Use the search bar to help users find what they are looking for. + Users often rely on search to find the information they need. You can use it as an alternative to on-page navigation. -Users will use keywords in the search bar, often using different words or phrases. Search is useful for sites with a lot of pages. +Users will use keywords in the search bar, often using different words or phrases. Search is especially helpful for users when navigating site that have many pages. The search bar includes: @@ -28,7 +30,7 @@ id: core-navigation-search-bar--default-story ### How this component works -#### Input Text +#### Input text Include short, descriptive placeholder text. This tells the user what they can search for. The text the user inputs replaces the placeholder text. @@ -36,50 +38,49 @@ The text the user inputs replaces the placeholder text. #### Search button The search button contains a button label and search icon. -To allow more space for text in the search bar, the responsive variation: - -- hides the button label -- displays a search icon on smaller devices only. +Smaller devices show a responsive variant with: +- only a search icon +- no button label. -Users know that magnifying glass indicates a search function. Because of this, on small screen we don't pair it with the word 'search' due to space limitations. However, it is kept in the code for screen readers. +This gives the user more space to write search text. Users know that a magnifying glass represents a search function. -The search button must submit an action, which reduces the time it takes to use the search bar. A user can enter their own search word or select a suggestion if that option is available. The search submits once a user selects 'enter' or 'return', +The word ‘Search’ must appear in the alt text for screen readers. -The search keyword remains once the search results display. +The button type should be a submit button. This lets a user conduct a search: +- using the enter/return key +- using fewer keystrokes +- by choosing a suggestion (if applicable) +- that afterwards, still displays the search keyword. #### Predictive keyword list -Making suggestions can improve the user experience. This can lead to less spelling errors and less effort for the user to reach their result. - -Useful suggestions can help guide users to their destination. +Useful suggestions let users find what they need with less effort. They also reduce spelling errors and typing. -Keyword suggestions should be in a compact and organised list. +Use a short, ordered list of no more than 10 keyword suggestions. -Provide suggestions after the user enters the third character. This reduces user effort. But don’t overwhelm users with a lot of suggestions. Keep the amount of suggestions under 10. +They should appear after only a few keystrokes. -Allow for keyboard navigation through the suggestions: +Let the user scroll through keyword suggestions using keyboard navigation, with the Esc key to exit. -- The user should be able to scroll through the items. -- Once the user goes past the last item, they should return to the top. This should be the same going in reverse, but appear at the bottom. -- The Esc key should allow users to exit the list. +Scrolling ‘down’ past the last suggestion should loop the user back to the first one. Scrolling ‘up’ before the first suggestion should loop the user to the last (bottom) one. ### When and how to use -- Use the search bar for site search. -- Use default search field on white page background -- Use reverse search field on grey background -- Use menu variant in the mega menu only -- Use only default and reverse variants with predictive list suggestions -- Even if it's hidden, still use a label. This is for screen readers -- Keep placeholder text concise and descriptive +- Use the search bar to let users search your site (site search). +- Use default search field on white page background. +- Use reverse search field on grey background. +- Use menu variant in the mega menu only. +- Use only default and reverse variants with predictive list suggestions. +- Even if it's hidden from view, always use a form label for screen readers. +- Keep placeholder text concise and descriptive. ### When and how not to use -- Don't use default or reverse variants in the mega menu -- Don't use filters or refine search with the menu variant -- Don't use multiline search inputs -- Revised search shouldn't be by default -- Don't use with the refine search link if no filters are available +- Don't use default or reverse variants in the mega menu. +- Don't use filters or refine search with the menu variant. +- Don't use multiline search inputs. +- Revised search shouldn't be by default. +- Don't use with the refine search link if no filters are available. --- diff --git a/docs/content/design-system/5.components/skip-link.md b/docs/content/design-system/5.components/skip-link.md index adcc7d518d..26d5d96941 100644 --- a/docs/content/design-system/5.components/skip-link.md +++ b/docs/content/design-system/5.components/skip-link.md @@ -1,6 +1,6 @@ --- title: Skip link -description: The skip link helps keyboard users skip to the main content on a page. +description: The Skip link component makes your page more accessible and easier to navigate, by helping keyboard users skip to the main content on a page. layout: page label: Core @@ -8,11 +8,16 @@ label: Core ## Usage -Users can use their keyboard to navigate through links and form elements. Including this component allows them to bypass the top-level navigation links and send them directly to the main page content. +Use skip links to let users: +- navigate quickly through links and form elements +- navigate your page when interacting only through the keyboard +- let users navigate directly to the main page content. -The skip link component will not display until a keyboard press activates it. When visible, it's always the first item on a page and pushes down all page content. +Skip links bypass the primary navigation links (the top horizontal menu items appearing on every page). -**I don't think this is the correct example** +Until the user activates it through a keyboard press, a skip link won’t display. + +When visible, it's always the first item on a page and pushes down all page content. ::DocsExample --- @@ -21,21 +26,19 @@ id: core-layout-skip-links--stand-alone :: ### When and how to use - -- It must be on every page -- When visible, it must be the first element on the page +- It must be on every page. +- When visible, it must be the first element on the page. ### When and how not to use - -- Only use at the top of the page -- Don't edit the styling -- Don't overlay page content. It must push down the page content +- Only use at the top of the page. +- Don't edit the styling. +- Don't overlay page content. It must push down the page content. --- ## Theming -The skip link adopts the site focus state colour for a consistent focus state experience. +The skip link uses the site’s focus state colour. This creates a seamless user experience. If we used a different colour, keyboard users would have colour changes between focusing on and interacting with a skip link. This could be jarring or confusing to users. ::DocsThemeChooser ::DocsExample diff --git a/docs/content/design-system/5.components/social-share.md b/docs/content/design-system/5.components/social-share.md index a32469cc54..c7737bdb7e 100644 --- a/docs/content/design-system/5.components/social-share.md +++ b/docs/content/design-system/5.components/social-share.md @@ -1,6 +1,6 @@ --- title: Social share -description: A list of links to help users to share pages to social media. +description: The Social share component shows a list of links to help users to share pages to social media. layout: page label: Core @@ -8,7 +8,7 @@ label: Core ## Usage -Social Share allows uses to share a page to their own social media channels. +Use social share to let users share pages to their own social media channels. It uses the social media icons to: @@ -25,21 +25,21 @@ id: core-navigation-social-share--social-share ### When and how to use -- Use it to enable users to share pages to social media -- Place in sidebar section of pages -- Link labels should be the social media platform +- Use it to enable users to share pages to social media. +- Place in sidebar section of pages. +- Link labels should be the social media platform name. ### When and how not to use -- Don't use for sites that aren't social media channels -- Avoid placing in a page's body section -- Don't use with labels that aren't social media platform names +- Don't use for links to sites that aren't social media channels. +- Avoid placing in a page's body section. +- Don't use with labels that aren't social media platform names. --- ## Theming -Social Share uses colour for: +Social share uses colour for: - indicating an action to users - icons. diff --git a/docs/content/design-system/5.components/statistics-grid.md b/docs/content/design-system/5.components/statistics-grid.md index 005dc07f11..0a1cc7dcc6 100644 --- a/docs/content/design-system/5.components/statistics-grid.md +++ b/docs/content/design-system/5.components/statistics-grid.md @@ -1,6 +1,6 @@ --- title: Statistics grid -description: Show a summary of 2 to 8 key statistics in a grid layout. +description: The Statistics grid component shows a summary of 2 to 8 key statistics in a grid layout. layout: page label: Core @@ -8,14 +8,14 @@ label: Core ## Usage -Statistics grid present a user with multiple pieces of key information. This can help the user to determine if a page is relevant to them or not. +Use the statistics grid to present a user with multiple pieces of key information. This can help the user to determine if a page is relevant to them or not. Each cell features: - a key statistic - content to give the statistic context. -It can act as a summary to help users view multiple related pieces of content. +A statistics grid can act as a summary to help users view multiple related pieces of content. ::DocsExample --- @@ -25,27 +25,27 @@ id: core-containers-stats-grid--on-light ### When and how to use -- You can use text or numbers in the content -- Use it to represent a high level summary of key information -- The grid will always span the full available width -- Place in the body section of pages +- Use text or numbers in the content. +- Give a high-level summary of key information. +- The grid will always span the full available width. +- Place in the body section of pages. ### When and how not to use -- Don't use with less than 2 or more than 8 statistics -- Don't overload with content -- Don't use when you need a large amount of text for context -- Don't use imagery -- Don't add links +- Don't use with under 2 or over 8 statistics. +- Don't overload with content. +- Don't use when you need a large amount of text for context. +- Don't use images or graphics. +- Don't add links. --- ## Variants -The statistic grid has two variants: +The statistic grid has 2 variants: -- Default, which is for use on white backgrounds. -- Reverse, which is for use on neutral backgrounds. +- default, for white backgrounds +- reverse, for neutral backgrounds. ### Default diff --git a/docs/content/design-system/5.components/table.md b/docs/content/design-system/5.components/table.md index 38140dc31a..bbbc094401 100644 --- a/docs/content/design-system/5.components/table.md +++ b/docs/content/design-system/5.components/table.md @@ -1,6 +1,6 @@ --- title: Table -description: Tables make it easier for users to scan and compare data and content. +description: The Table component makes it easier for users to scan and compare data and content. layout: page label: Core @@ -14,9 +14,9 @@ Users tend to read tables one row or column at a time. So, it's important that c A table can include a combination of: - row and/or column headings that help users know what the rows and columns represent - body rows that display data or content -- a table caption that helps users find, navigate and understand tables, which should describe the tables contents +- a table caption describing its content and helping users find, navigate and understand its information - a table footer that provides additional details, if required -- an expandable section with expandable rows. These can show extra related or supplementary information or data. +- an expandable section with expandable rows, which can show extra related or supplementary information or data. ::DocsExample --- @@ -25,13 +25,13 @@ id: core-containers-data-table--structured-content :: ### How this component works -Table content should be left-aligned because we read left-to-right. However, tables with financial figures should have numeral columns set to right-aligned. +Table content should be left-aligned because we read from left to right. However, tables with financial figures should have columns that contain numerals set to right-aligned. Only left-align numbers that are arbitrary identifiers, known as 'nominal numbers'. These are numbers you cannot compare or combine arithmetically. These can include postal codes, IP addresses, or phone numbers. Column headers follow the alignment of the data. -The data table use a zebra stripe styling which, alternates table row colours. This makes it easier for the user to scan horizontal information. +The data table uses a zebra-stripe styling which alternates table row colours. This makes it easier for the user to scan horizontal information. -Don't allow for too many columns as it's easier for users to scan down a list than to scroll across a page. So, consider more rows before more columns. +Don't include too many columns as it's easier for users to scan down a list than to scroll across a page. So, consider more rows before more columns. Tables can respond differently based on how your website is built. Where tables do not respond, they will display with a horizontal scroll bar to view all the content. Where tables do respond on smaller screens, tables will stack vertically. @@ -40,21 +40,21 @@ The complex variant has the option of expandable extra information in nested row ### When and how to use - Add a caption or footer, if required. - Use for complex content and data sets. -- Align numbers to the right. +- Align numbers to the right (except nominal numbers). - Align headers according to their column data. ### When and how not to use - Don't repeat the same content in both the caption and summary. - Don't use with long form content. Cell content should be brief and scannable. -- Don't use without zebra striping. -- Don't centre align content. +- Don't use without zebra-stripe styling.. +- Don't centre-align content. --- ## Variants -Table has two variants: -- Simple, best used for simple data. -- Complex, best used for complex data. +Table has 2 variants: +- simple, best used for simple data. +- complex, best used for complex data. ### Simple @@ -65,7 +65,7 @@ id: core-containers-content--table-scrollable :: ### Complex -It is best used to display complex data sets. +The complex variant is best used to display complex data sets. ::DocsExample --- diff --git a/docs/content/design-system/5.components/tabs.md b/docs/content/design-system/5.components/tabs.md index 709f467941..b63362e049 100644 --- a/docs/content/design-system/5.components/tabs.md +++ b/docs/content/design-system/5.components/tabs.md @@ -1,6 +1,6 @@ --- title: Tabs -description: Tabs help users navigate between related sections of content. +description: The Tab component lets you organise related content so that users can switch between related information on the same page. layout: page label: Core @@ -8,24 +8,24 @@ label: Core ## Usage -Tabs let users quickly switch between related information if: +Use tabs to let users stay on the same page, but access more content. -- you can separate your content into clearly labelled sections -- the first section is more relevant (for most users) than the other sections -- users won't need to view all the sections at once. - -Tabs allow users to navigate different sections without having to leave the page. They will always feature at least two options, and one tab is active at a time +Only one tab is active at a time. Tabs help users navigate between, and display and hide, relevant content on your page so long as: +- you can split, categorise and clearly label the content +- there is a section more relevant for most users, which is placed first +- seeing the all sections at the same time is not needed +- you have a minimum of 2 tabs. Use tabs to organise content so a user doesn't have to navigate away to complete their task. Tabs are useful for maps or dashboards. -Don't use tabs if your content is sequential. Use it for related content, only. +Never use tabs if your content is sequential. Use it to present related content together, as a group. Tabs include: - labels - an optional icon. -Icons tell the user what type of content is under a tab. Keep icons simple and recognisable, and reinforce the label. +Icons tell the user the category of content under a tab. Keep icons simple and easily understood, and reinforce the label. ::DocsExample --- @@ -35,34 +35,33 @@ id: core-navigation-tabs--default-story ### When and how to use -- Order your tabs according to importance -- Labels should clearly and succinctly describe the content within the tab -- Only use tabs to organise related content that sit on the same level of hierarchy -- Limit labels to one word and ensure they are unique +- Order your tabs according to importance. +- Labels should clearly and succinctly describe the content within the tab. +- Only use tabs to group content that all sits at the same level of hierarchy. +- Limit labels to one word and ensure they are unique. ### When and how not to use -- Never use tabs within tabs -- Don't display disabled tabs -- Don't display more than one row of tabs when using the horizontal variant -- Don't use tabs for important information. A user will choose which tab to open, so they may not see some content -- Don't use if your content is short. Instead use lists or paragraph text -- Never use tabs for your primary navigation -- Don't use tabs to indicate progress -- Don't use tabs if the user is comparing information in two groups. This will result in the user clicking back and forth to complete a task +- Never use tabs within tabs. +- Don't display disabled tabs. +- Don't display more than one row of tabs when using the horizontal variant. +- Don't use tabs for important information, since a user will choose which tab to open, so they may not see some content. +- Don't use if your content is short, instead use lists or paragraph text. +- Tabs are not a substitute for primary navigation, so never use tabs as primary navigation. +- Don't use tabs to tell the user about their progress through a page or content. +- Don’t use tabs when the user needs to compare information, since only one tab is visible at a time. --- ## Variants -Tabs have two display variants: - -- Default. -- Vertical. +Tabs have 2 display variants: +- default +- vertical. ### Default -The tab group bottom border will span the full available content width. +The default variant sets the tab group bottom border to span the full available content width. ::DocsExample --- @@ -72,7 +71,7 @@ id: core-navigation-tabs--default-story ### Vertical -The tab group left border will span the height of the tab group. +The vertical variant sets the tab group left border to span the height of the tab group. ::DocsExample --- diff --git a/docs/content/design-system/5.components/tag.md b/docs/content/design-system/5.components/tag.md index faa63ad055..411d0d9854 100644 --- a/docs/content/design-system/5.components/tag.md +++ b/docs/content/design-system/5.components/tag.md @@ -1,17 +1,17 @@ --- title: Tag -description: Label and draw attention to content such as a category. +description: The Tag component adds, and draws attention to, a category name for your content. layout: page label: Core --- ## Usage -Tags help categorise content. They help users to scan and find content that's relevant to them. +Use tags to help categorise content. Tags help users to scan and find content that's relevant to them. Content can have more than one category or theme. Using the tag component helps indicate this to the user. -When naming tags, use a noun or adjective. Don't use verbs as a user may confuse it with an action. +When naming tags, use a noun or adjective. Don't use verbs as a user may confuse the tag with an action. ::DocsExample --- @@ -21,7 +21,7 @@ id: core-containers-tag--neutral ### When and how to use - Use keywords. -- Use to draw attention to a category or label. +- Use to draw attention to a category of content or information. - Use nouns or adjectives. ### When and how not to use @@ -35,9 +35,9 @@ id: core-containers-tag--neutral --- ## Variants -Tags have two variants: -- Default, which is for use on neutral backgrounds. -- Neutral, which is for use on white backgrounds. +Tags have 2 variants: +- default, for use on neutral backgrounds +- neutral, for use on white backgrounds. ### Default ::DocsExample diff --git a/docs/content/design-system/5.components/text-area.md b/docs/content/design-system/5.components/text-area.md index f425989003..9373f57371 100644 --- a/docs/content/design-system/5.components/text-area.md +++ b/docs/content/design-system/5.components/text-area.md @@ -1,6 +1,6 @@ --- title: Text area -description: Let users select one option from a list. +description: The Text area component lets users select one option from a list. layout: page label: Core @@ -10,11 +10,11 @@ label: Core Use text area so users can enter multiple lines of text. -Text area is used information longer than a single line of text is needed or expected. For example, comments fields. +Text area is used when information longer than a single line of text is needed or expected. For example, comments fields. Text areas can be resized and can be used with a character counter. -Don’t use text area for succinct responses such as a email addresses or names. In this case, you should use the [input field](/design-system/components/input-field/) component. +Don’t use text area for succinct responses such as email addresses or names. In this case, you should use the input field component. ::DocsExample --- @@ -24,16 +24,16 @@ id: forms-textarea--default-story ### How this component works -You must use a form label with a text area. +You must use a form label with a text area component. -You can use an text area with: +You can use text area with: - requirement label - hint text - metadata - placeholder text. -Guide users about the amount of text wanted. Set the text area to match the amount preferred. It has no maximum height, but a minimum height of 96px. +Guide users about the amount of text wanted. Set the text area to match the amount preferred. It has no maximum height, but has a minimum height of 96px. #### Resize handle @@ -61,7 +61,7 @@ Only use hint text where it’s needed. Don’t repeat the label. Don’t use it A character count can sit below the text area field. It tells users the maximum characters and their input’s current count. -Users can enter more characters than the maximum. The character count says they’ve entered too many characters before they submit the text area. The user can then copy or reduce their full answer. +Users can enter more characters than the maximum. The character count then says they’ve entered too many characters before they submit the text area. The user can copy or reduce their full answer. Even though there is a live character count, normal error responses (below) must appear if a user tries to submit a text area with too many characters. @@ -69,25 +69,25 @@ Only use character count when there is a good reason. For example, legal reasons ### When and how to use -- Always use a label for text areas -- Use hint text to specify helpful information such as specific formatting or information requirements -- Specify character counts when required +- Always use a label for text areas. +- Use hint text to specify helpful information such as specific formatting or information requirements. +- Specify character counts when required. ### When and how not to use - Never use without a label -- Avoid placeholder text because it can cause accessibility issues -- Don’t disable copy and paste -- Don’t set a minimum or maximum input limit without explicitly saying this in the character count -- Do not use hint text if it isn’t relevant or meaningful to the user -- Don’t use placeholder text to give instructions -- Don’t write ambiguous error messages only stating what's wrong - explain how the user can fix it +- Avoid placeholder text because it can cause accessibility issues. +- Don’t disable copy and paste. +- Don’t set a minimum or maximum input limit without explicitly saying this in the character count. +- Do not use hint text if it isn’t relevant or meaningful to the user. +- Don’t use placeholder text to give instructions. +- Don’t write ambiguous error messages only stating what's wrong - explain how the user can fix it. --- ## Variants -The text area has two variants: +The text area has 2 variants: - default, used on white backgrounds - reverse, used on neutral backgrounds. @@ -118,33 +118,33 @@ When creating an error message for an input field, use the wording below. **Error: empty input** -- Error message: ‘Enter \[the missing information\]' -- Example: 'Enter your name' +- Error message: ‘Enter \[the missing information\]'. +- Example: 'Enter your name'. **Error: input is too long** -- Error message: ‘\[The input\] must be \[number\] characters or less' -- Example: 'Delivery address must be 56 characters or less' +- Error message: ‘\[The input\] must be \[number\] characters or less'. +- Example: 'Delivery address must be 56 characters or less'. **Error: input is too short** -- Error message: ‘\[The input\] must be \[number\] characters or more' -- Example: 'Previous employer must be 3 characters or more' +- Error message: ‘\[The input\] must be \[number\] characters or more'. +- Example: 'Previous employer must be 3 characters or more'. **Error: input is too long or to short** -- Error message: ‘\[The input\] must be between \[number\] and \[number\] characters' -- Example: 'Justification must be between 3 and 56 characters' +- Error message: ‘\[The input\] must be between \[number\] and \[number\] characters'. +- Example: 'Justification must be between 3 and 56 characters'. **Error: input uses known characters that aren’t allowed** -- Error message: ‘\[The input\] must not include \[characters\]' -- Example: ‘Reasons must not include + & ~' +- Error message: ‘\[The input\] must not include \[characters\]'. +- Example: ‘Reasons must not include + & ~'. **Error: input uses unknown characters that aren’t allowed** -- Error message: ‘\[The input\] must only include \[list of allowed characters\]' -- Example: ‘Explanations must only include letters, numbers and commas' +- Error message: ‘\[The input\] must only include \[list of allowed characters\]'. +- Example: ‘Explanations must only include letters, numbers and commas'. ::DocsExample --- diff --git a/docs/content/design-system/5.components/timeline.md b/docs/content/design-system/5.components/timeline.md index 48a5137278..75c3915c72 100644 --- a/docs/content/design-system/5.components/timeline.md +++ b/docs/content/design-system/5.components/timeline.md @@ -1,6 +1,6 @@ --- title: Timeline -description: Blocks of content displayed in a linear order. +description: The Timeline component contains blocks of content displayed in a linear order. layout: page label: Core @@ -15,13 +15,20 @@ A timeline can include a combination of: - summary - image. -Timelines create a clear hierarchy. They help users to make a connection from one linear piece of information to another. +Use timelines to show a clear and sequential order of information. This assists users in linking pieces of information together. -For example, this could include: -- stages or steps along a process -- sequential outcomes or dates. +Some examples include: +- dates +- steps +- stages +- events +- actions +- outcomes. + +The timeline component is ordered from top to bottom. + +Use between 3 to 8 discrete sections of content, so the user is not overwhelmed. -A timeline displays in order from top to bottom. Only include 3 to 8 steps to prevent it from overwhelming the user. ::DocsExample --- @@ -36,17 +43,17 @@ id: core-containers-timeline--default-story - Add a link if you're providing more details on another page. ### When and how not to use -- Don't add less than 3 or more than 8 blocks. +- Don't add fewer than 3 or more than 8 blocks. - Don't use without a heading for each block. - Never include unrelated content. -- Don't use if content doesn't come together in sequential or linear order. Consider bullets points instead. +- Don't use if content doesn't flow in a sequential or linear order. Consider bullets points instead. --- ## Variants -Timeline has two variants: -- Default. -- Progressive. +Timeline has 2 variants: +- default +- progressive. ### Default This is for steps or stages along a process. Use the default timeline when progress is not relevant to the user. diff --git a/docs/content/design-system/5.components/vertical-navigation.md b/docs/content/design-system/5.components/vertical-navigation.md index 84dc730440..8afe0ddb9c 100644 --- a/docs/content/design-system/5.components/vertical-navigation.md +++ b/docs/content/design-system/5.components/vertical-navigation.md @@ -1,23 +1,24 @@ --- title: Vertical navigation -description: A vertical list of links to help users navigate a section of related pages. +description: The Vertical navigation component displays a list of links to help users navigate a section of related pages. layout: page label: Core --- ## Usage -The vertical navigation component: -- displays the user's current position in your site's content hierarchy -- helps users to move between different sections and other related content -- supports four levels of hierarchy nesting -- supports a heading. +Use vertical navigation to help users navigate a section of related pages. -Place the vertical navigation next to a page's body content. This helps users navigate a section of related pages. +Use vertical navigation to: +- let users find and navigate to relevant information +- show the user where, within your site’s content hierarchy, the page they are viewing is located +- show 4 nested content sections (parent sections) and a heading for the names of each section. -We've hidden child page navigation by default, and the user can reveal them via a chevron. When they select a parent section, it expands and displays the children pages. +Vertical navigation is placed next to your page’s body content. -The chevron remains upturned until a user closes it. This tells the user which sections they are in, reducing visual complexity. +A chevron (v-shaped icon) next to each parent section lets users expand that parent section. This reveals the names of content pages falling within the parent section (child pages). Child page links are hidden by default. + +The chevron flips up and parent sections stay expanded until the user interacts with the chevron to hide the child pages. This helps the user find what they need and minimises visual clutter. ::DocsExample --- @@ -34,15 +35,15 @@ id: core-navigation-vertical-navigation--vertical-navigation ### When and how not to use - Don't embed on a page that doesn't have a sidebar. -- Don't add more than four child levels. The indentation will become indiscernible, which affects usability. -- Don't use on a site with less than 5 pages. +- Don't add more than 4 child levels. Users will not see the indents, so navigation will become confusing. +- Don't use on a site with fewer than 5 pages. - Don’t use with icons. - Never use it to link to other sites. --- ## Theming -Vertical navigation uses colour to highlight the current page the user is on. +Vertical navigation uses colour and active state focus to highlight the current page the user is on. ::DocsThemeChooser ::DocsExample @@ -57,7 +58,7 @@ To create your own theme see [theming guidance for designers](/design-system/des --- ## Rationale -The current page active state shows which page a user is currently on. It uses an underline (that is, something other than colour) to meet [Web Content Accessibility Guidelines 2.0 Success Criterion 1.4.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-without-color.html). +To show the user which page in the vertical navigation they are currently on, the active state is used. This displays as an underline in addition to colour, to address the [Web Content Accessibility Guidelines 2.0 Success Criterion 1.4.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-without-color.html). > **[1.4.1](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#visual-audio-contrast-without-color) Use of Color:** Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element. diff --git a/docs/content/design-system/markdown-reference-file.md b/docs/content/design-system/_markdown-reference-file.md similarity index 100% rename from docs/content/design-system/markdown-reference-file.md rename to docs/content/design-system/_markdown-reference-file.md diff --git a/docs/content/framework/1.index.md b/docs/content/framework/1.index.md index 4088292d15..19de368bd8 100644 --- a/docs/content/framework/1.index.md +++ b/docs/content/framework/1.index.md @@ -1,7 +1,30 @@ --- -title: Ripple Layer Development Guide -description: 'Here is some information about how we build websites' +title: About +description: Ripple framework contains the tools for building SDP sites using the Ripple design system components. layout: page +links: + - text: Github + url: https://github.com/dpc-sdp/ripple-framework + - text: Single Digital Presence + url: https://www.vic.gov.au/single-digital-presence --- -Work in progress +## What is it? + +The Ripple design system consists of the design elements and components used to build _any_ web application using the Victorian government brand. Ripple _framework_ is a collection of [Nuxt 3](2.key-concepts/1.nuxt.md) modules and [layers](2.key-concepts/2.nuxt-layers.md) primarily used to create headless SDP websites using the Tide Drupal CMS. + +![ripple is made up of Figma design, CSS styles, Vue JS components and Nuxt JS Sites](/assets/img/modules/rpl-modules.png){.rpl-u-padding-t-4} + + +## Who's it for? + +Whilst the Ripple UI components can be used in non SDP projects, Ripple framework assumes a Tide Drupal backend in most cases. + +Using the Ripple framework, developers are able to build headless frontend websites that derive content from the Tide Drupal CMS via it's JSON API. + +### SDP architecture + +![SDP Architecture](/assets/img/modules/sdp-architecture.png){.rpl-u-padding-12} + + +To find out more about Single Digital presence please visit https://www.vic.gov.au/single-digital-presence diff --git a/docs/content/framework/2.key-concepts/1.nuxt.md b/docs/content/framework/2.key-concepts/1.nuxt.md new file mode 100644 index 0000000000..8e7274050e --- /dev/null +++ b/docs/content/framework/2.key-concepts/1.nuxt.md @@ -0,0 +1,37 @@ +--- +title: Nuxt +description: Nuxt is the framework used in Ripple to deliver headless SDP websites that connect to Tide Drupal backends for content. +draft: true +layout: page +links: + - text: Nuxt documentation + url: https://nuxt.com/ +--- + + +Nuxt is a framework for building web application that can be rendered both server side using Node.js and client side with Vue.js components. Nuxt is the framework used in Ripple to deliver headless SDP websites that connect to Tide Drupal backends for content. + +> **"Nuxt is a fantastic choice for teams building a production-grade product on the web. It aims to bake in performance best-practices while maintaining excellent Vue.js DX"** +> +> Addy Osmani - Chief Engineer of Chrome + + +It is recommended that developers new to Ripple familiarise themselves with Nuxt by reading the documentation site, in particular the following sections + +- [Introduction · Get Started with Nuxt ](https://nuxt.com/docs/getting-started/introduction) +- [Vue.js Development · Nuxt Concepts](https://nuxt.com/docs/guide/concepts/vuejs-development) +- [ Server Engine · Nuxt Concepts ](https://nuxt.com/docs/guide/concepts/server-engine) +- [.nuxt/ · Nuxt Directory Structure](https://nuxt.com/docs/guide/directory-structure/nuxt) +- [Authoring Nuxt Layers · Nuxt Advanced](https://nuxt.com/docs/guide/going-further/layers) + + +For support and help working with Nuxt please see https://nuxt.com/docs/community/getting-help and https://nuxt.com/support/solutions + +There are a number of recommended resources for learning Nuxt 3 including: + +- [https://masteringnuxt.com/nuxt3](https://masteringnuxt.com/nuxt3) +- [https://frontendmasters.com/courses/nuxt/](https://frontendmasters.com/courses/nuxt/) +- [https://www.youtube.com/watch?v=ww94Jvi8JJo](https://www.youtube.com/watch?v=ww94Jvi8JJo) + + + diff --git a/docs/content/framework/2.key-concepts/2.nuxt-layers.md b/docs/content/framework/2.key-concepts/2.nuxt-layers.md new file mode 100644 index 0000000000..286353b19f --- /dev/null +++ b/docs/content/framework/2.key-concepts/2.nuxt-layers.md @@ -0,0 +1,25 @@ +--- +title: Layers +description: Nuxt layers are used to encapsulate Ripple functionality to share and reuse +draft: true +layout: page +links: + - text: Nuxt layers documentation + url: https://nuxt.com/docs/getting-started/layers +--- + + +[Nuxt](1.nuxt.md) 3 provides a way to encapsulate part of a Nuxt project into what they call a Layer. + +> Nuxt layers are a powerful feature that you can use to share and reuse partial Nuxt applications within a monorepo, or from a git repository or npm package. The layers structure is almost identical to a standard Nuxt application, which makes them easy to author and maintain. +> + + + +In Ripple 2, we utilise Nuxt Layers extensively to share isolated features between SDP sites. A good example is a content type. Using a Nuxt Layer we are able to add the components, API endpoints, composables, etc needed to implement the feature, without having the overhead of a Nuxt Module. + +A great feature of Nuxt Layers is that you can reference them from any public or private Git repo in addition to publishing via an NPM module. + +Below is a diagram showing how Ripple 2 features are distributed through Nuxt layers and used within projects. + +![Ripple layers architecture diagram. Shows how modules can be shared between projects](/assets/img/modules/layers.png) diff --git a/docs/content/framework/2.key-concepts/3.API-endpoints.md b/docs/content/framework/2.key-concepts/3.API-endpoints.md new file mode 100644 index 0000000000..cabe50bd89 --- /dev/null +++ b/docs/content/framework/2.key-concepts/3.API-endpoints.md @@ -0,0 +1,16 @@ +--- +title: API endpoints +description: +draft: true +layout: page +links: + - text: Nuxt API routes documentation + url: https://nuxt.com/docs/guide/directory-structure/server#api-routes +--- + +Nuxt 3 introduces the concept of server API routes - see server/ · Nuxt Directory Structure powered by the Nitro rendering engine and H3. In Ripple 2 we use API routes to create a backend for frontend API that handles communicating with the Drupal Tide JSON API and maps the response to only what is required to render the page in in Ripple. + +TODO : Insert diagram here + + +Nitro is the server layer that creates API routes in a Nuxt application. Nitro plugins run at build time and we use them to add the mapping needed to tell Ripple-tide-api package how to respond to a Drupal JSON API request for a content type node diff --git a/docs/content/framework/2.key-concepts/4.content-types.md b/docs/content/framework/2.key-concepts/4.content-types.md new file mode 100644 index 0000000000..ca7e4d916f --- /dev/null +++ b/docs/content/framework/2.key-concepts/4.content-types.md @@ -0,0 +1,21 @@ +--- +title: Content types +description: Implementing content type specific page layouts +draft: true +layout: page +--- + +Content types are a Drupal concept that allow for modelling content to suit your needs. See the [Drupal documentation](https://www.drupal.org/docs/7/understanding-drupal/content-types) for more details. + + +## Core content types + +In Tide we have a number of content types which are part of the core distribution and are initially included in SDP sites + +- Landing page +- Event +- Grant +- News +- Publication (page) +- Alert + diff --git a/docs/content/framework/2.key-concepts/5.dynamic-components.md b/docs/content/framework/2.key-concepts/5.dynamic-components.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/content/framework/3.guides/1.migrating.md b/docs/content/framework/3.guides/1.migrating.md new file mode 100644 index 0000000000..0830346e0f --- /dev/null +++ b/docs/content/framework/3.guides/1.migrating.md @@ -0,0 +1,72 @@ +--- +title: Migrating from Ripple 1.x +description: This guide is intended to outline the process of updating SDP sites using Ripple 1.x to Ripple 2. It is intended for developers tasked with porting Ripple 1 sites and features to Ripple 2. +layout: page +--- + + +## Background + +Ripple 2 is a complete rewrite of both the design system and the Nuxt modules used to create SDP sites with it. It is a breaking change with the processes used to create sites and functionality used in Ripple 1. This was required due to the following reasons + +- Latest versions of Vue and Nuxt 3 introducing breaking changes +- Deprecation of IE11 support allowing us to support modern browser features +- Opportunity to adopt best practices such as Typescript and modern CSS +- Build up of technical and design debt +- Improvements to the design allowing better theming and accessibility + +> Due to breaking changes between versions 2 and 3 of both Vue and Nuxt there is no automated way to upgrade Ripple components and sites. +> _Custom functionality built on Ripple 1 will need to be rewritten to use Ripple 2 API’s and design._ + +## Migrating your site + +If your site is supported by the SDP team for upgrades, the initial site upgrade will be handled by the SDP team. The process will be as follows: + +- a new empty V2 branch will be created in the site repository +- a fresh install of Ripple 2 will be added to the site +- all required environment variables will be added to the project to connect the site to the Tide content backend +- the V2 branch will be setup to be served from behind the Section.io CDN + +The migration of the following will be out of scope for sites without an MoU for SDP support: + +- Custom content types +- Custom user facing components +- Custom pages +- Extensive theme customisation outside of those documented in the theming guide + +## Migrating features from Ripple 1.x + +Please review the following concepts before proceeding: + +- [Content types](../2.key-concepts/4.content-types.md) +- [API mapping](../2.key-concepts/3.API-endpoints.md) +- [Dynamic components](../2.key-concepts/5.dynamic-components.md) + +### Content types + +Content types in Tide allow for defining custom fields that can be returned via the Drupal JSON API. Because SDP sites are headless, we need to tell Ripple how to render each custom content type on the front end. + +In Ripple 1.x, each content type was added through the convention of adding a folder named tide and each content type as a subfolder. See [Ripple 1 example](https://github.com/dpc-sdp/ripple/tree/develop/examples/basic-examples/tide/modules/example-content-type). +The mapping of the tide API response was done through [tide.config.js](https://github.com/dpc-sdp/ripple/blob/develop/packages/ripple-nuxt-tide/modules/news/tide.config.j). The JSON API response was returned in its entirety and mapping the Drupal fields to Ripple components was done through the Page component. + +> In Ripple 2.x we move the mapping of data to the Nuxt server layer. This allows us to only return the necessary data need to the end user, reducing the JSON payload from Drupal. + +For more information on creating new content types see the guide on [creating content types](4.creating-content-types.md) + +### Dynamic components + +Tide CMS makes use of [Drupal paragraphs](https://www.drupal.org/project/paragraphs) to structure content types to allow content creators flexibility when composing content. Creating new paragraph types that can be reused for the landing page content or across others is a common customisation task. + +In Ripple 1, new paragraph support was added through custom mappings [See Ripple 1](https://github.com/dpc-sdp/ripple/blob/develop/examples/basic-examples/tide/modules/example-override-mapping/tide.config.js) + +In Ripple 2, we need to add similar support - See [Guide to creating dynamic components](5.dynamic-components.md) + +### Search listing pages + +> This feature is still in Beta, please see the [feature proposal](https://github.com/dpc-sdp/ripple-framework/discussions/660) for more information. + +Listing pages are pages which contain dynamic lists of links to other pages. These are typically used to generate index pages when there are large amounts of similar items. See https://www.vic.gov.au/grants, https://www.vic.gov.au/victorian-honour-roll-of-women for example. + +In Ripple 1 there was no dedicated content type for creating listing pages and hence these page were usually created as static pages in the frontend. + +In Ripple 2 we intend to move to a standard content type that allows configuring the search experience from the backend. Please see the [feature proposal](https://github.com/dpc-sdp/ripple-framework/discussions/660) for more info. diff --git a/docs/content/framework/3.guides/2.new-sites.md b/docs/content/framework/3.guides/2.new-sites.md new file mode 100644 index 0000000000..a509070ec5 --- /dev/null +++ b/docs/content/framework/3.guides/2.new-sites.md @@ -0,0 +1,52 @@ +--- +title: Setting up a new site +description: A guide to setting up new SDP frontend sites using Ripple framework. +layout: page +--- + + +Setting up new sites with Ripple 2 is made easy with our CLI tool and provisioning process. Before you do so though please ensure you have got in touch with the SDP engagement manager (digital@dpc.vic.gov.au) prior and have submitted a support request to the Digital Victoria Help center https://digital-vic.atlassian.net/servicedesk/customer/portals + + +## Requirements + +When onboarding a new project to SDP the following will be provisioned for you: + +- Git repo created +- Required platform files added to repo, required Dockerfile, etc +- Bay hosting environment configured +- Section.io CDN setup and configured +- Environment variables set to your project specific requirements + + +## Local development dependencies + +Please make sure you have the following dependencies installed before proceeding. Typically local development is not performed through a docker container on the front end. + +- Node version 16.11.0 or greater (We recommend installing Node through Node Version Manager - See https://github.com/nvm-sh/nvm for install guide) +- NPM version 8.1.0 or greater + +Please see `engines` key in `package.json` for most accurate versions. + +## Installing Ripple + +> For SDP sites, this will also be applied. However if you wish to create a local install of Ripple outside of a project see below. + +Installing Ripple is easy with the included CLI tool: + +``` +npx @dpc-sdp/nuxt-ripple-cli init site ~/path/to/site --name "My Site" +``` + +This will copy the required files needed to setup your site into `~/path/to/site` + +``` +cd ~/path/to/site && npm install +``` + +This will install all dependencies with NPM, you can then run the development server with + +``` +npm run dev +``` + diff --git a/docs/content/framework/3.guides/3.brand-application.md b/docs/content/framework/3.guides/3.brand-application.md new file mode 100644 index 0000000000..2eead33162 --- /dev/null +++ b/docs/content/framework/3.guides/3.brand-application.md @@ -0,0 +1,13 @@ +--- +title: Applying theme and brand +description: A guide to applying theme and brand assets to Ripple sites. +layout: page +--- + +This is how you do that + +```js +Some code +``` + + diff --git a/docs/content/framework/3.guides/4.creating-content-types.md b/docs/content/framework/3.guides/4.creating-content-types.md new file mode 100644 index 0000000000..03a018b95f --- /dev/null +++ b/docs/content/framework/3.guides/4.creating-content-types.md @@ -0,0 +1,11 @@ +--- +title: Creating content types +description: A guide to creating new content templates. +layout: page +--- + +This is how you do that + +```js +Some code +``` diff --git a/docs/content/framework/3.guides/5.creating-new-layers.md b/docs/content/framework/3.guides/5.creating-new-layers.md new file mode 100644 index 0000000000..4316453c20 --- /dev/null +++ b/docs/content/framework/3.guides/5.creating-new-layers.md @@ -0,0 +1,76 @@ +--- +title: Creating new layers +description: Implementing custom functionality through layers +draft: true +layout: page +links: + - text: Nuxt layers documentation + url: https://nuxt.com/docs/getting-started/layers +--- + +Nuxt layers are used to encapsulate Ripple functionality, so it can easily be shared and reused across projects, see [key concepts - layers](/framework/key-concepts/nuxt-layers) for a conceptual overview of what layers are and how they are used within Ripple. + +## Creating a new layer + +The Nuxt Ripple CLI provides a simple way to initialise new layers, to create a new layer just run the following command: + +``` +npx @dpc-sdp/nuxt-ripple-cli init layer [DIRECTORY] --name {NAME} +``` + +Where `[DIRECTORY]` is the location to output the layer scaffolding and `{NAME}` is the name of the new layer. This command will scaffold everything you need to get started developing a new layer. + +## Developing the layer + +Once the layer has been created you can start working with it by running the command below from the new layers directory. This will start a development server and allow you to start working on the layer. + +```bash +npm run dev +``` + +The `playground` folder contains the essentials to get a test Nuxt application up and running, it includes a `app.config.js`, `nuxt.config.js` and `.env` file. The `nuxt.config.js` includes a core set of layers used by Ripple to get a reference sdp site up and running, it also includes the new layer itself. + +> The `playground` folder is a fully functional Nuxt application and can be used to test the new layer in isolation. + +The layers structure is almost identical to a normal Nuxt app, meaning you can utilise the same features and conventions as a standard Nuxt application. i.e. create a `pages` folder for new pages, create a `components` folder for new components, etc. + +Other useful commands: +- `npm run build` to do a production build the `.preview` application (for testing purposes) +- `npm run lint` to lint the layer code with [eslint](https://eslint.org/) +- `npm run test` to run any unit tests with [jest](https://jestjs.io/) + +## Publishing the layer + +Once the layer is ready to be published it can be published to npm or pushed to a remote git repository, [GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), and [Bitbucket](https://bitbucket.org/) are supported. +For more on publishing to npm see [contributing packages to the npm registry](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry). + +## Using the layer + +Nuxt layers can be added to any Nuxt site by including the layer in the `nuxt.config.js` file under extends. If the layer is published to npm don't forget to `npm install` it first. + +```js +export default defineNuxtConfig({ + extends: [ + '@dpc-sdp/nuxt-ripple', // An npm installed package + 'github:dpc-sdp/ripple-vic-gov-au-custom#1.0.0' // A tagged git repository + ] +}) +``` + +Also, make sure to check the layers documentation for any additional configuration that may be required. + +> To extend from a private repository, you need to add a `GIGET_AUTH=` environment variable, with an auth token from your git provider. + +### Caveats when using layers from a git repository + +If a layer is added via a git repository and that layer has npm dependencies, you will need to manually install them within the Nuxt application utilising the layer. The Nuxt team are looking at auto-installing layer dependencies in the future, see [issue #13367](https://github.com/nuxt/nuxt/issues/13367). + +You will also need to alias the dependencies in the Nuxt application, so they can be resolved to the correct package location. This can be done by adding an `alias` object to the `nuxt.config.js` file. + +```js +export default defineNuxtConfig({ + alias: { + 'date-fns': require.resolve('date-fns') + } +}) +``` diff --git a/docs/content/framework/3.guides/dynamic-components.md b/docs/content/framework/3.guides/5.dynamic-components.md similarity index 100% rename from docs/content/framework/3.guides/dynamic-components.md rename to docs/content/framework/3.guides/5.dynamic-components.md diff --git a/docs/content/framework/4.modules/@dpc-sdp-nuxt-ripple/_module.json b/docs/content/framework/4.modules/@dpc-sdp-nuxt-ripple/_module.json index af999f3972..c1df272c7e 100644 --- a/docs/content/framework/4.modules/@dpc-sdp-nuxt-ripple/_module.json +++ b/docs/content/framework/4.modules/@dpc-sdp-nuxt-ripple/_module.json @@ -1,10 +1,11 @@ { "isModuleInfo": true, "name": "Nuxt Ripple", - "description": "Testing the description", + "description": "Nuxt layer for adding Ripple UI and shared functionality for setting up support for Tide content", "packageName": "@dpc-sdp/nuxt-ripple", - "sourceUrl": "https://github.com/dpc-sdp/ripple-framework/tree/develop/packages/ripple-tide-landing-page", + "sourceUrl": "https://github.com/dpc-sdp/ripple-framework/tree/develop/packages/nuxt-ripple", "issuesUrl": "https://github.com/dpc-sdp/ripple-framework/issues", + "readmePath": "./../../../../packages/nuxt-ripple/README.md", "contributor": { "name": "SDP", "url": "https://www.vic.gov.au/single-digital-presence" diff --git a/docs/layouts/home.vue b/docs/layouts/home.vue index d0bd0fcfd2..57dfe183ea 100644 --- a/docs/layouts/home.vue +++ b/docs/layouts/home.vue @@ -38,25 +38,7 @@ - -
-
- -

- {{ page.modulesCTA.description }} -

- -
-
- - - +
@@ -82,6 +64,24 @@
+ +
+
+ +

+ {{ page.framework.description }} +

+ +
+
+ +