Design docs markdown update

docs/content/design-system/2.design/1.getting-started.md

@@ -52,12 +52,10 @@ Only use the Figma file in conjunction with the Ripple 2.0 guidance about the co
 
     You will receive access to the Ripple Design System Figma file.
 
-4. **Add Ripple to your Figma account**
+4. **Access the Ripple file from your account**
 
-    Add the Ripple 2.0 Design System Figma file to your Figma account.
+    View the the Ripple 2.0 Design System Figma file from your Figma account.
 
-5. **Set up Asset Library**
+5. **Within the Figma file read through the “Getting Started” guidance page**
 
-    In your Figma account, go to the Getting Started page.
-
-    Follow these instructions to set up the Asset Library.
+    Follow the instructions to set up and use the Ripple Design System in your own design files.

docs/content/design-system/5.components/detail-list.md

@@ -8,15 +8,15 @@ label: Core
 
 ## Usage
 
-Use the detail list to display a list with labels. This surfaces (retrieves and displays) and highlights key information to users.
+Detail list displays a list with labels. This surfaces and highlights key information to users.
 
-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'.
+Each row of the Detail list comprises a:
+- a label - a description or information (e.g. Location)
+- content - the detail (e.g. 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 such as ‘Published date', which displays as day, month, year (e.g. 22 March 2023)
+- the status of a program or grant (e.g. Opening soon, Closed).
 
 Only use the detail list for simple information. For data or complex information, consider using a table.
 
@@ -27,21 +27,50 @@ id: core-containers-description-list--with-link
 ::
 
 ### When and how to use
-- Use single words only for the label.
+- Try to use single words for the label.
 - Include a link if you need to.
-- Keep the summary content and labels clear and concise.
+- Keep the labels and summary content 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 it to surface information that is not important to users.
-- Don't use with complex or long form 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 icons unrelated to the content.
+- Don’t use icons that are not universally understood.
 
 ---
+## Variants
 
+Detail list has two variants:
+- Default
+- Icon.
+
+### Default
+The default variant displays a label followed by the content. This should be used as a first choice. 
+
+::DocsExample
+---
+id: core-containers-description-list--default-story
+---
+::
+
+### Icon
+The icon variant displays an icon next to content. Use the icon variant for displaying information such as the status of a program or grant. 
+
+It should only be used when meaningful and universally understood icons can be used for all list items.
+
+::DocsExample
+---
+id: core-containers-description-list--icons-only
+---
+::
+
+---
+
 ## Theming
 
-When a link is present, the 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

docs/content/design-system/5.components/header-status.md

@@ -0,0 +1,54 @@
+---
+title: Header Status
+description: The Header status shows the user key information or the status relating to the content on the page.  
+layout: page
+label: Core
+
+---
+
+## Usage
+The Header status draws attention to key information or data relevant to the page. 
+
+The header status can display content like:
+- the progress toward completion of a set of actions (such as recommendations from a royal commission or inquiry) 
+- the status or closing date of a job listing or grant application 
+
+The status bar updates dynamically based on its data set. The status bar completeness value can go left-to-right or right-to-left depending on data requirements. 
+
+The Header status must be used at the top of a page within the header section.
+
+::DocsExample
+---
+id: core-containers-
+---
+::
+
+### When and how to use
+- Use to indicate the status of a project or timeline.
+- Use with a relevant page title, such as a job title.
+- Can be used with the optional second support label and content when relevant.
+- Use concise content and labels.
+
+### When and how not to use
+- Do not use on pages that don't have content related to the status data.
+- Do not use to indicate a step of a linear process such as a form.
+- Do not use with an [introduction banner](/design-system/components/header#introduction-banner).
+- Do not use in conjunction with a [Header](/design-system/components/header/).
+
+---
+
+## Theming
+
+Header status uses colour to add prominence to the status. It also adopts theming from the [button](/design-system/components/button/) component.
+
+If you choose the neutral button for your site, the header site search will display buttons in the neutral theme.
+
+::DocsThemeChooser
+  ::DocsExample
+  ---
+  id: core-containers-
+  ---
+  ::
+::
+
+To create your own theme see [theming guidance for designers](https://www.vic.gov.au) or [theming guidance for developers](https://www.vic.gov.au).

docs/content/design-system/5.components/header.md

@@ -1,20 +1,21 @@
 ---
 title: Header
-description: The Header component introduces the purpose and content of a page.
+description: The Header introduces the purpose and content of a page.
 layout: page
 label: Core
 
 ---
 
 ## Usage
+The header informs the user what is on the page. The header must be used at the top of a page above the body content. 
 
-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. 
-
-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.
+It contains the page title styled as Heading 1 (H1). Optional content includes:
+- introduction text
+- journey links
+- a call to action button, text and journey link
+- image or corner graphics
+- supporting campaign logo
+- introduction banner.
 
 ::DocsExample
 ---
@@ -23,15 +24,15 @@ id: core-containers-header--default-journey-links
 ::
 
 ### When and how to use
-- Keep the header simple and concise.
-- Use clear calls to action that align with the message or task.
+- Keep the header simple. Trying to use all the available features (such as call to action and journey links) overwhelms and confuses users.
+- Use clear calls-to-action that align with the page’s 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 and introduction banners.
+- Don’t include the same links in the main banner and introduction banner.
 - Don’t use with more than 6 journey links.
 - Don’t overload with content.
 
@@ -45,13 +46,11 @@ The header has 3 variants:
 - reverse
 - image.
 
-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.
+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 important information. They can display corner graphics 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 can display a full-width or half-width background image.
 
-The image variant displays a full background image with reverse blocked text. It only supports a page title and introduction text. 
-
-All variants can be used with the introduction banner.
+The introduction banner can be used with all variants.
 
 ### Default
 
@@ -69,7 +68,7 @@ id: core-containers-header--default-call-to-action
 
 ### Reverse
 
-The reverse variant uses reversed blocked type for the title and introduction text. This adds visual prominence to the banner and its information.
+The reverse variant uses reversed blocked type for the title and introduction text. This adds visual prominence to the banner and information.
 
 ::DocsExample
 ---
@@ -85,22 +84,32 @@ id: core-containers-header--reverse-call-to-action
 
 ### Image
 
-An image can be added as a full background image. The title and introduction copy will always display as the reversed blocked type.
+An image can be added as a full or half-width background image. 
+
+The full-width background image supports a title and introduction copy. It will always display as reversed-blocked type.
+
+The half-width background image supports a title, introduction copy and an optional call to action. 
 
-Images should not be stretched or too low in resolution. They should also not be complex or include text.
+Images should not be stretched or have too low resolution. They should not be complex or include text.
 
 ::DocsExample
 ---
 id: core-containers-header--image-reverse
 ---
 ::
 
+::DocsExample
+---
+id: 
+---
+::
+
 ### 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 an optional icon and journey links
-- should contain content relating to the content in the main header.
+- can be used to add a content and call-to-action under the header banner
+- has optional journey links or buttons
+- has an optional icon that sits above the heading (H2).
 
 ::DocsExample
 ---
@@ -112,9 +121,9 @@ id: core-containers-header--intro-with-links
 
 ## Interaction with other components
 
-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.
+When using a featured campaign banner with an image, the image can overlap the header depending on the amount of content. By default, this hides the header's bottom corner graphic.
 
-The bottom corner shape won't hide if an introduction banner is between the header and campaign banner.
+If an Introduction banner is used, the featured campaign banner will display below that, so the bottom corner graphic will display.
 
 ::DocsImageExample
 ---
@@ -134,7 +143,9 @@ Headers can be themed in 2 ways:
 
 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.
+If you choose a neutral button style for your site, the header will display neutral-themed buttons.
+
+### Site theme
 
 ::DocsThemeChooser
   ::DocsExample
@@ -156,7 +167,7 @@ If you choose neutral button for your site, the header will display buttons in t
 
 ### 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; they cannot be edited or customised.
 
 ::DocsExample
 ---