Merge pull request #181 from WestpacGEL/feature/80-gel-docs-update

fix(#80): list and shadow on the sidebar

apps/site/TO_DO.md

@@ -25,7 +25,7 @@ const GEL_COLORS = {
 ### /design-system
 
 1. [x] Integrate content blocks with keystatic
-2. Add box shadow to brand selector on navigation scroll
+2. [x] Add box shadow to brand selector on navigation scroll
 
 #### code tab
 
@@ -40,5 +40,5 @@ const GEL_COLORS = {
 
 ### General
 
-1. [ ] Fix list component styling, changing line height breaks current list component
+1. [x] Fix list component styling, changing line height breaks current list component
 2. [ ] Update component slugs to match current GEL navigation grouping

apps/site/content/design-system/components/accordion/accessibility/Accessibility API/content.mdoc

@@ -0,0 +1,3 @@
+- `<div role="tablist">`: Indicates that the element serves as a container for a set of tabs
+- `<button aria-controls="{PANEL_ID}" aria-expanded="true|false">`: Identifies a button element that toggles a content collapse and indicates the state of a collapsible element below. The&nbsp;*aria-controls*&nbsp;attribute creates an association between toggle button and collapsible element (panel).
+- `<div id="{PANEL_ID}" aria-hidden="false|true">`: The panel must have a unique&nbsp;*id*&nbsp;value. The toggle button&nbsp;*aria-controls*&nbsp;and panel&nbsp;*id*&nbsp;attribute values must match. The panel uses the&nbsp;*aria-hidden*&nbsp;attribute to hide from assistive technologies when no longer available.

apps/site/content/design-system/components/accordion/accessibility/Accessibility features/content.mdoc

@@ -0,0 +1,3 @@
+- The tabset is implemented as a set of buttons, rather than tabs. This approach has shown to provide a better user experience.
+- An indicator outline appears around the toggle buttons when focused
+- The tabcordion shape, text and accordion toggle icons are visible in Windows High Contrast Mode

apps/site/content/design-system/components/accordion/accessibility/Keyboard support/content.mdoc

@@ -0,0 +1 @@
+Keyboard users navigate the tabset as a set of buttons, rather than ‘tabs’. Keyboard interaction requires use of ‘tab’ and ‘enter’ (or ‘space’) keys to select, rather than arrow keys. The accordion toggles are also buttons; interaction is as expected, consistent with tabset toggles.

apps/site/content/design-system/components/accordion/accessibility/Notes on accessibility/content.mdoc

@@ -0,0 +1,17 @@
+All components comply with WCAG 2.1 AA guidelines and Success Criteria. These fall under the [four principles of accessibility](https://gel.westpacgroup.com.au/design-system/accessibility/design-system-accessibility) – Perceivable, Operable, Understandable and Robust. Below are some specific ways in which this component follows these principles:
+
+### **Perceivable**
+
+The Design System components have been designed to adhere to colour contrast ratios for both text and non-text elements. They have been coded to include text alternatives when required, and allow component text and labels to be resized. They do not use colour alone to convey information.
+
+### **Operable**
+
+The Design System components have been coded to be navigable using a keyboard and other assistive technologies. WCAG compliance recommends being aware of the time it takes for people to complete tasks and to not automatically move focus. Animation should be controlled and simple so as not to cause seizures, and it’s important to provide the ability to perform the same task in multiple ways where possible. These rules have been followed where navigation and interaction is included in Design System components or patterns.
+
+### **Understandable**
+
+WCAG compliance requires consistent and predicable interactions, clear and simple language, concise labels, no jargon or abbreviations and clear error messaging. These rules have been followed where content and interactions are included in Design System components or patterns.
+
+### **Robust**
+
+All Design System components have been coded so they can be clearly announced, understood and navigated using all modern assistive technologies.

apps/site/content/design-system/components/accordion/code.mdoc

@@ -1,4 +1,5 @@
 ### Default accordion
+
 See Visual design for the usage recommendations for the default style.
 
 ```jsx
@@ -20,6 +21,7 @@ See Visual design for the usage recommendations for the default style.
 ```
 
 ### Lego accordion
+
 See Visual design for the usage recommendations for the lego style.
 
 ```jsx

apps/site/content/design-system/components/accordion/design/Dos and don’ts/content.mdoc

@@ -0,0 +1,4 @@
+- Avoid using too much content and consider smaller viewports when designing responsive web apps.
+- Avoid changing the styles of Tabs and Accordions (border, colour, size etc )
+- Do use Tabs and Accordions on any background (light or dark).
+- Avoid making Tab and Accordion labels too long. Although they will wrap the interface will become cluttered very quickly.

apps/site/content/design-system/components/accordion/design/Tabset/content.mdoc

@@ -0,0 +1,7 @@
+\**Default tabset: **See Visual design for the usage recommendations for the default style. Tabsets can appear both ranged to the right, or justified.
+
+```tsx
+
+```
+
+\**Lego tabset: **See Visual design for the usage recommendations for the lego style. Tabsets can appear both ranged to the right, or justified.

apps/site/content/design-system/components/accordion/design/User experience/content.mdoc

@@ -0,0 +1,9 @@
+The Tabcordion component has three modes:
+
+1. **Tabset** – traditional horizontal tabs, allowing only one content panel to be visible at a time, by selecting the relevant tab.
+1. **Accordion** – collapsible content containers, allowing multiple content panels to be visible simultaneously, by selecting the relevant bar.
+1. **Tabcordion** – a responsive combination of the first two.
+
+The first two modes function in the traditional way. The third ‘Tabcordion’ is the term we use to describe a responsive tab set. When using a Tabset in our web applications we typically experience layout issues when the application needs to display on small viewports (phones). Often the tabs won’t fit horizontally in the limited screen size. To remedy this problem, we developed the Tabcordion where the Tabset will turn into an Accordion when viewed on smaller devices (phones).
+
+This component is useful when trying to simplify and group content for users to view when they need it, as opposed to displaying everything at once.

apps/site/content/design-system/components/accordion/design/Visual design/content.mdoc

@@ -0,0 +1,7 @@
+Tabset, Accordions and Tabcordions, can have one of two styles applied to them *Default* and *Lego*:
+
+The **Default style** is designed to be subtle and understated while still providing a clear indication of which tab or accordion bar is selected, and its related content. To further reinforce this relationship a transition is used to display related content when a tab or accordion bar is selected. Generous padding provides a larger hit area and important breathing space to provide emphasis without adding noise.
+
+The **Lego tabset** is designed to be more prominent. This design came out of a project request for a more emphasised component which would also add some brand colour to an otherwise dry, text heavy interface.
+
+Tab sets and accordions are intended to visually group related content. When used correctly with moderate content they do this extremely well. However, if too much content is used it becomes difficult to visualise this relationship as content extends below the viewport.

apps/site/content/design-system/components/accordion/index.yaml

@@ -1 +1,17 @@
 name: Accordion
+description: >-
+  Tabcordions are grouped sets of tabbed or accordion style panels. Use them to
+  group and simplify large amounts of content such as product information.
+pageOfContent: []
+design:
+  - title: Tabset
+  - title: User experience
+  - title: Visual design
+  - title: Dos and don’ts
+accessibility:
+  - title: Notes on accessibility
+  - title: Accessibility features
+  - title: Keyboard support
+  - title: Accessibility API
+relatedInformation:
+  - components/panel

apps/site/content/westpac-ui-info/index.yaml

@@ -1,2 +1,2 @@
-changelog: https://github.com/WestpacGEL/GEL-next/bloc/main/CHANGELOG.ms
+changelog: https://github.com/WestpacGEL/GEL-next/bloc/main/CHANGELOG.md
 currentVersion: 1.0.0

apps/site/src/app/design-system/[...component]/components/content-tabs/components/document-renderer.tsx

@@ -6,7 +6,7 @@ import { Code, Divider, Heading, List, Paragraph } from '@/components/document-r
 export const DOCUMENT_RENDERERS: Required<DocumentRendererProps>['renderers'] = {
   block: {
     divider: Divider,
-    paragraph: props => <Paragraph {...props} className="sm:w-9/12" />,
+    paragraph: props => <Paragraph {...props} className="w-full sm:w-9/12" />,
     code: props => <Code className="my-4" {...props} />,
     heading: Heading,
     list: props => <List {...props} className="sm:w-9/12" />,

apps/site/src/app/design-system/components/sidebar/sidebar.component.tsx

@@ -4,7 +4,7 @@ import { BOMShieldLogo, BSAStackedLogo, RAMSLogo, STGDragonLogo, WBCLogo, WBGLog
 import { clsx } from 'clsx';
 import Link from 'next/link';
 import { usePathname, useRouter, useSearchParams } from 'next/navigation';
-import React, { Key, useCallback, useRef } from 'react';
+import React, { Key, useCallback, useEffect, useRef, useState } from 'react';
 import { useOnClickOutside } from 'usehooks-ts';
 
 import { BrandKey } from '@/app/types/brand.types';
@@ -50,12 +50,29 @@ const BANK_OPTIONS = [
 
 export function Sidebar({ items }: SidebarProps) {
   const { open, setOpen } = useSidebar();
+  const [scrolled, setScrolled] = useState<boolean>(false);
 
-  const ref = useRef<HTMLDivElement>(null);
-  useOnClickOutside(ref, () => {
+  const outsideRef = useRef<HTMLDivElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  useOnClickOutside(outsideRef, () => {
     setOpen(false);
   });
 
+  useEffect(() => {
+    if (!listRef.current) {
+      return;
+    }
+    const listener = () => {
+      const y = listRef.current?.scrollTop || 0;
+      setScrolled(y > 0);
+    };
+    listRef.current.addEventListener('scroll', listener);
+    return () => {
+      listRef.current?.removeEventListener('scroll', listener);
+    };
+  }, [listRef]);
+
   const router = useRouter();
   const pathname = usePathname();
   const searchParams = useSearchParams();
@@ -67,6 +84,7 @@ export function Sidebar({ items }: SidebarProps) {
     },
     [router, pathname],
   );
+
   return (
     <div
       className={clsx(
@@ -75,7 +93,7 @@ export function Sidebar({ items }: SidebarProps) {
           '-translate-x-full': !open, //hide sidebar to the left when closed
         },
       )}
-      ref={ref}
+      ref={outsideRef}
     >
       <Link href="/" className="flex h-15 items-center px-3" aria-label="GEL home">
         <Logo brand={brand} />
@@ -92,7 +110,12 @@ export function Sidebar({ items }: SidebarProps) {
           ))}
         </SidebarSelect>
       </div>
-      <nav className="flex-1 overflow-y-auto overflow-x-hidden pb-4">
+      <nav
+        ref={listRef}
+        className={clsx('flex-1 overflow-y-auto overflow-x-hidden pb-4 transition-all', {
+          'shadow-[inset_rgba(0,0,0,0.26)_0_2px_5px]': scrolled,
+        })}
+      >
         <Link href="/" className="block" aria-label="Back to GEL">
           <BackToGelSvg />
         </Link>

apps/site/src/components/document-renderer/list/list.component.tsx

@@ -3,10 +3,10 @@ import { type ListProps } from './list.types';
 
 export const List = ({ children, type, className, color = 'default' }: ListProps) => {
   const Tag = type === 'unordered' ? 'ul' : 'ol';
-  const styles = listStyles({ type, className, color });
+  const styles = listStyles({ type, color });
 
   return (
-    <Tag className={styles.base({})}>
+    <Tag className={styles.base({ className })}>
       {children?.map((child, index) => (
         <li className={styles.li({})} key={index}>
           {child}

apps/site/src/components/document-renderer/list/list.style.ts

@@ -3,7 +3,7 @@ import { tv } from 'tailwind-variants';
 export const styles = tv({
   slots: {
     base: 'mb-11 w-full p-0 leading-[2] last:mb-0',
-    li: 'typography-body-9 relative mb-2 pl-3',
+    li: 'typography-body-9 relative mb-2 pl-3 leading-7',
   },
   variants: {
     color: {
@@ -20,7 +20,7 @@ export const styles = tv({
       },
       unordered: {
         base: '',
-        li: 'before:absolute before:left-0 before:top-[0.5rem] before:block before:h-[0.5rem] before:w-[0.5rem] before:rounded-full last:mb-0',
+        li: 'before:absolute before:left-0 before:top-[0.6rem] before:block before:h-[0.5rem] before:w-[0.5rem] before:rounded-full last:mb-0',
       },
     },
   },

apps/site/src/components/document-renderer/paragraph/paragraph.component.tsx

@@ -1,6 +1,6 @@
 import { styles } from './paragraph.style';
 import { type ParagraphProps } from './paragraph.types';
 
-export const Paragraph = ({ children, textAlign }: ParagraphProps) => {
-  return <p className={styles({ textAlign })}>{children}</p>;
+export const Paragraph = ({ children, textAlign, className }: ParagraphProps) => {
+  return <p className={styles({ textAlign, className })}>{children}</p>;
 };