@atlaskit/navigation-system 7.1.2 → 7.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlassian/navigation-system
 
+## 7.1.3
+
+### Patch Changes
+
+- [`08170da1fbf62`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/08170da1fbf62) -
+  Migrate spacing prop usages on icons to Flex wrapper
+- Updated dependencies
+
 ## 7.1.2
 
 ### Patch Changes

package/constellation/layout/examples.mdx

@@ -4,18 +4,33 @@ description: Layout components define a page’s structure and the areas for nav
 order: 1
 ---
 
+import Image from '@atlaskit/image';
+
+import layoutExampleLight from './images/layout-example-light.png';
+import layoutExampleDark from './images/layout-example-dark.png';
+import layoutExampleSideNavLight from './images/layout-example-sideNav-light.png';
+import layoutExampleSideNavDark from './images/layout-example-sideNav-dark.png';
+import layoutExampleTopNav1Light from './images/layout-example-topNav-1-light.png';
+import layoutExampleTopNav1Dark from './images/layout-example-topNav-1-dark.png';
+import layoutExampleTopNav2Light from './images/layout-example-topNav-2-light.png';
+import layoutExampleTopNav2Dark from './images/layout-example-topNav-2-dark.png';
+
 import SectionMessage from '@atlaskit/section-message';
 
 import { CustomSkipLinkExample } from '../../examples/constellation/layout/custom-skip-links';
 import { ExpandSideNavButtonExample } from '../../examples/constellation/layout/expand-side-nav';
 import { ToggleSideNavKeyboardShortcutExample } from '../../examples/constellation/layout/toggle-side-nav-keyboard-shortcut';
 
-import { PageLayoutDiagram } from './diagram';
-
 The full page layout with all areas rendered has the structure depicted below, or see the
 [interactive example](https://go.atlassian.com/nav4-interactive-example).
 
-<PageLayoutDiagram />
+<Image
+	src={layoutExampleLight}
+	srcDark={layoutExampleDark}
+	alt="Example of the navigation system layout areas"
+/>
+
+The top nav overlaps the side nav when it is expanded to give the appearance of a full height side nav.
 
 When composing your page layout ensure that:
 
@@ -27,7 +42,7 @@ When composing your page layout ensure that:
 These are the distinct areas in the layout. These components are designed to contain other
 components and content.
 
-[View ready-made navigation experiences](https://hello.atlassian.net/wiki/x/rBE7MAE)
+For examples, see [navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).
 
 ### Banner
 
@@ -39,20 +54,33 @@ the top of the screen.
 Use the top nav area to render [top nav items](/components/navigation-system/top-nav-items).
 
 - It will display at the top of the screen, below the banner if one is present. It has a fixed
-  height of 48px.
+  height of 56px.
 - Use the [top nav slots](#top-nav-slots) to position actions within top nav.
-- The top nav is [responsive](/components/navigation-system/top-nav-items/examples#responsive), with
-  the top nav items changing according to the viewport size.
+- The top nav is responsive, with the [top nav items](/components/navigation-system/top-nav-items) changing according to the viewport size.
+
+[View interactive example](https://go.atlassian.com/nav4-interactive-example)
 
 #### Top nav slots
 
 The top nav has three layout components that you must use to position
 [top nav items](/components/navigation-system/top-nav-items) within the top nav flexbox.
 
-- `TopNavStart`: Area for left-aligned items.
+- `TopNavStart`: Area for left-aligned items. Appears in the side nav when the side nav is expanded to give the appearance of a full height sidebar.
 - `TopNavMiddle`: Area for centre-aligned items.
 - `TopNavEnd`: Area for right-aligned items.
 
+<Image
+	src={layoutExampleTopNav1Light}
+	srcDark={layoutExampleTopNav1Dark}
+	alt="Example of the top nav slots - side nav collapsed"
+/>
+
+<Image
+	src={layoutExampleTopNav2Light}
+	srcDark={layoutExampleTopNav2Dark}
+	alt="Example of the top nav slots - side nav opened"
+/>
+
 #### Top nav custom theming
 
 See the [custom theming](/components/navigation-system/layout/custom-theming) tab.
@@ -63,7 +91,9 @@ See the [custom theming](/components/navigation-system/layout/custom-theming) ta
   render [side nav items](https://atlaskit.atlassian.com/packages/navigation/side-nav-items). It
   will show on the left of the screen. The default width of the side nav is 320px.
 - Use the [side nav slots](#side-nav-slots) to position content within the side nav.
-- The side nav is collapsable and expandable, resizable, responsive, and offers flyout behaviour.
+- The side nav is [collapsable and expandable](#side-nav-collapseexpand), [resizable](#side-nav-resizing), [responsive](#side-nav-responsive), and offers [flyout](#side-nav-flyout) behaviour.
+
+[View interactive example](https://go.atlassian.com/nav4-interactive-example)
 
 #### Side nav slots
 
@@ -78,10 +108,28 @@ flexbox.
 Note: make sure to render `SideNavBody` to ensure that the footer is positioned at the bottom of the
 side nav, simulating a sticky footer.
 
+<Image
+	src={layoutExampleSideNavLight}
+	srcDark={layoutExampleSideNavDark}
+	alt="Example of the side nav slots"
+/>
+
 #### Side nav collapse/expand
 
-The side nav can be collapsed and expanded using the the `SideNavToggleButton` from
-[top nav items](/components/navigation-system/top-nav-items/examples#start-items).
+The side nav can collapse and expand based on user input or programmatically through hooks.
+
+##### Toggle button
+
+The side nav can collapse and expand using the `SideNavToggleButton` from
+[top nav items](/components/navigation-system/top-nav-items/examples#start-items) or the keyboard shortcut.
+
+##### Keyboard shortcut
+
+The keyboard shortcut Ctrl+[ is enabled globally through the `isSideNavShortcutEnabled` on `Root`. It’s disabled by default.
+
+When enabled, additional checks can be performed on individual keypresses through the `canToggleWithShortcut` prop on the side nav. This allows for apps to conditionally disable the shortcut based on additional app-specific requirements.
+
+##### Programmatic / Hooks
 
 There are two hooks available for programmatically toggling the side nav.
 
@@ -93,7 +141,7 @@ There are two hooks available for programmatically toggling the side nav.
 	, as they require the internal React context that it provides.
 </SectionMessage>
 
-##### useExpandSideNav
+**useExpandSideNav**
 
 Returns a function that will expand the side nav.
 
@@ -101,8 +149,9 @@ This can be useful for ensuring the side nav is expanded before displaying an on
 for example. If the side nav is already expanded, it will simply no-op.
 
 <Example Component={ExpandSideNavButtonExample} appearance="source-only" />
+<br />
 
-##### useToggleSideNav
+**useToggleSideNav**
 
 Returns a function that will toggle the side nav.
 
@@ -114,39 +163,32 @@ This is useful for toggling the side nav based on a keyboard shortcut.
 
 - In the collapsed state, hovering over the `SideNavToggleButton` from
   [top nav items](/components/navigation-system/top-nav-items/examples#start-items) will trigger the
-  side nav to open as an overlay. Moving the curser away will close it. If there are any open
+  side nav to open as an overlay. Moving the cursor away will close it. If there are any open
   supported ADS layering components (e.g. popups, dropdown menus) within the side nav, the flyout
   will stay locked open, until the layering components are closed.
 
 - The expansion and collapse of the side nav flyout is animated on **supported browsers**.
   Currently, Firefox does not support the animation. Instead, it will instantly expand and collapse.
 
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
-
 #### Side nav resizing
 
-- You can optionally render a [side nav panel splitter](#resizable-areas) as a child to make the
-  side nav resizable. It is resized using the drag handle. When hovering on the drag handle the
-  mouse pointer changes to a resize pointer.
-- The side nav can be resized to a minimum width of 240px, and a maximum width equal to 50% of the
-  total viewport width. It retains this resized width even after collapsing, reopening, or
-  refreshing the page. When resizing, any open layer components (e.g. popups, dropdowns, selects,
-  tooltips) will be closed.
-- The side nav panel splitter can be also double clicked to collapse the side nav.
-
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+You can optionally render a [side nav panel splitter](#resizable-areas) as a child to make the side nav resizable.
 
+- The side nav is resized using the drag handle. When you hover over the drag handle, the mouse pointer changes to a resize cursor.
+- The side nav can be resized to a minimum width of 240px and a maximum width equal to 50% of the viewport width.
+- The side nav retains its resized width after it's collapsed or expanded. Persist the chosen width across page refreshes by providing it to the `defaultWidth` prop.
+- When resizing, any open layer components (for example, popups, dropdowns, selects, and tooltips) are closed.
+- You can also double-click the side nav panel splitter to collapse the side nav.
+ 
 #### Side nav responsive
 
 - At `s`, `xs`, and `xxs` breakpoints (i.e. viewports smaller than 1024px), the side nav
   automatically collapses to make room for the content. Users have the option to manually
-  [open or close the side nav](/components/navigation-system/layout/examples#side-nav-collapseexpand)
+  [open or close](/components/navigation-system/layout/examples#side-nav-collapseexpand) the side nav
   according to their preferences. Doing so will open it as an overlay.
 - At `xs` and `xxs` breakpoints (i.e. viewports smaller than 768px), the max width of the overlay
   side nav is either 320px or 90% of the screen width - whichever value is smaller.
 
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
-
 ### Main
 
 Use the main area for the [page header](/components/page-header) and main page content. It will
@@ -157,10 +199,12 @@ expand to fill available space.
 - On small viewports, the element will always use body scroll, to make it easier to scroll the page
   when the content is tall.
 
+[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+
 ### Aside
 
 <SectionMessage appearance="warning" title="Caution">
-	We are planning on deprecating the aside component. Please use panel instead.
+We plan to deprecate aside. Use panel instead.
 </SectionMessage>
 
 The aside area is rendered to the right of the main area.
@@ -180,19 +224,13 @@ The aside area is rendered to the right of the main area.
 You can optionally render a [panel splitter](#resizable-areas) as a child to make the aside
 resizable.
 
-- It is resized using the drag handle. When hovering on the drag handle the mouse pointer changes to
-  a resize pointer.
-- The aside can be resized to a minimum width of 120px, and a maximum width equal to 50% of the
-  total viewport width. It retains this resized width even after refreshing the page.
-
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+- The aside is resized using the drag handle. When you hover over the drag handle, the mouse pointer changes to a resize cursor.
+- The aside can be resized to a minimum width of 120px and a maximum width equal to 50% of the viewport width. 
+- Persist the chosen width across page refreshes by providing it to the `defaultWidth` prop.
 
 #### Aside responsive
 
-At `s`, `xs`, and `xxs` breakpoints (i.e. viewports smaller than 1024px), the aside moves below the
-main area, and conforms to main width and behaviour.
-
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+At `s`, `xs`, and `xxs` breakpoints (i.e. viewports smaller than 1024px), the aside moves below the main area, and conforms to main width and behaviour.
 
 ### Panel
 
@@ -204,34 +242,25 @@ The panel area is rendered to the right of the main and aside areas.
   [resizable](/components/navigation-system/layout/examples#panel-resizing), and
   [responsive](/components/navigation-system/layout/examples#panel-responsive).
 
-Common usage is to house
-[Preview panel](https://atlaskit-website-staging.stg-east.frontend.public.atl-paas.net/#/packages/navigation/preview-panel)
+[View interactive example](https://go.atlassian.com/nav4-interactive-example)
 
 #### Panel collapse/expand
 
 The panel can be collapsed and expanded using a trigger of your choosing.
 
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
-
 #### Panel resizing
 
 You can optionally render a [panel splitter](#resizable-areas) as a child to make the panel
-resizable. It can be resized using the drag handle. When hovering on the drag handle the mouse
-pointer changes to a resize pointer.
-
-- The panel can be resized larger than the `defaultWidth` to a maximum of 50% of content area
-  (viewport minus the side nav area).
-- It retains this resized width even after collapsing, reopening, or refreshing the page.
-- It has no ability to resize smaller than `defaultWidth`.
+resizable.
 
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+- The panel is resized using the drag handle. When you hover over the drag handle, the mouse pointer changes to a resize cursor.
+- The panel can be resized larger than `defaultWidth` to a maximum of 50% of the content area (viewport minus the side nav area). The panel can't be resized smaller than `defaultWidth`.
+- The panel retains its resized width after it's collapsed or expanded. Persist the chosen width across page refreshes by providing it to the `defaultWidth` prop.
 
 #### Panel responsive
 
-At `m` breakpoints (between 1024-1440px), the panel will overlay the aside area. At `s` breakpoints
-and below (less than 1024px) it will start to overlay the main area.
-
-[View interactive example](https://go.atlassian.com/nav4-interactive-example)
+At `m` breakpoints (between 1024-1440px), the panel will overlay the aside area. At `s` breakpoints and
+below (less than 1024px) it will start to overlay the main area.
 
 ## Resizable areas
 
@@ -239,9 +268,9 @@ Render a `PanelSplitter` in a layout area to make it resizable.
 
 Resizing is supported for the following areas:
 
-- [Side nav](/components/navigation-system/layout/examples#side-nav) - use `SideNavPanelSplitter`
-- [Aside](/components/navigation-system/layout/examples#aside) - use `PanelSplitter`
-- [Panel](/components/navigation-system/layout/examples#panel) - use `PanelSplitter`
+- [Side nav](/components/navigation-system/layout/examples#side-nav): Use `SideNavPanelSplitter`
+- [Aside](/components/navigation-system/layout/examples#aside): Use `PanelSplitter`
+- [Panel](/components/navigation-system/layout/examples#panel): Use `PanelSplitter`
 
 [View interactive example](https://go.atlassian.com/nav4-interactive-example)
 

package/constellation/layout/usage.mdx

@@ -4,8 +4,14 @@ description: Layout components define a page’s structure and the areas for nav
 order: 4
 ---
 
-import layoutDo from './images/layout-do.png';
-import layoutDont from './images/layout-dont.png';
+import Image from '@atlaskit/image';
+
+import layoutAnatomyLight from './images/layout-anatomy-light.png';
+import layoutAnatomyDark from './images/layout-anatomy-dark.png';
+import layoutDoLight from './images/layout-do-light.png';
+import layoutDoDark from './images/layout-do-dark.png';
+import layoutDontLight from './images/layout-dont-light.png';
+import layoutDontDark from './images/layout-dont-dark.png';
 
 import SectionMessage from '@atlaskit/section-message';
 
@@ -14,10 +20,13 @@ import SectionMessage from '@atlaskit/section-message';
 Use layout to compose the structure of your application. It also defines the page behavior and
 navigational areas.
 
-When applying components to the navigational areas,
-[see navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
+When applying components to the navigational areas, [see navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
 
-![Diagram of the navigation system layout areas](./images/layout-anatomy.png)
+<Image
+	src={layoutAnatomyLight}
+	srcDark={layoutAnatomyDark}
+	alt="Diagram of the navigation system layout areas"
+/>
 
 <ol>
 	<li>
@@ -28,7 +37,7 @@ When applying components to the navigational areas,
 		<a href="/components/navigation-system/top-nav-items">top nav items</a>.
 		<ol type="a">
 			<li>
-				<strong>Top nav start:</strong> Area for left-aligned actions.
+				<strong>Top nav start:</strong> Area for left-aligned actions. Appears in the side nav when the side nav is expanded.
 			</li>
 			<li>
 				<strong>Top nav middle:</strong> Area for centre-aligned actions.
@@ -39,10 +48,9 @@ When applying components to the navigational areas,
 		</ol>
 	</li>
 	<li>
-		<strong>Side nav:</strong> Use to display{' '}
-		<a href="https://atlaskit.atlassian.com/packages/navigation/side-nav-items">side nav items</a>.
-		Is resizable and collapsible.
-		<ol type="a" start="4">
+		<strong>Side nav:</strong> Use to display <a href="https://atlaskit.atlassian.com/packages/navigation/side-nav-items">side nav items</a>. Is resizable and
+		collapsible.
+		<ol type="a">
 			<li>
 				<strong>Side nav header:</strong> Optional. Top part of the side nav (fixed).
 			</li>
@@ -60,7 +68,7 @@ When applying components to the navigational areas,
 	</li>
 	<li>
 		<strong>Aside:</strong> Optional. Use to display supporting or supplementary content. Is
-		resizable. <em>We plan to deprecate this component, please use panel instead.</em>
+		resizable. <em>We plan to deprecate aside, please use panel instead.</em>
 	</li>
 	<li>
 		<strong>Panel:</strong> Optional. Use to display supporting or supplementary content. Is
@@ -71,26 +79,25 @@ When applying components to the navigational areas,
 ### The difference between aside, panel and modal dialog
 
 <SectionMessage appearance="warning" title="Caution">
-	We are planning on deprecating the aside component. Please use panel instead.
+	We plan to deprecate aside. Use panel instead.
 </SectionMessage>
 
 The main difference between aside, panel and modal dialog is their behaviours:
 
 - **Aside** is not collapsible, while **panel** can be collapsible.
-- **Panel** and **aside** present content alongside the **main** area, while **modal dialog** exists
+- **Panel** and **aside** present content alongside the **main** area, while a **modal dialog** appears
   in a layer above the page.
 - On small viewports (1024px and below), the **panel** becomes an overlay, while the **aside** moves
-  below **main**.
+  below the **main** area.
 
-#### Usage guidance:
+#### Usage guidance
 
-- Use **aside** for content that needs to be constantly visible and accessible without requiring the
-  user to open it, or have the ability to close it.
-- Use **panel** for contextual information or tertiary actions that complement the user's workflow.
-  Panels enable greater multitasking by functioning as an additional work space, while keeping users
+- Use the **panel** for contextual information or tertiary actions that complement the user's workflow.
+  Panels enable multitasking by providing an additional work space, while keeping users
   connected to their primary task.
-- Use **modal dialog** when you need your user to focus their attention on a single or specific
-  task, like requiring a decision or action before they can return to their primary task.
+- Use a **modal dialog** when you need the user to focus on a specific
+  task, such as making a decision or completing an action, before they can return to their primary task.
+- Don’t use aside for new experiences. It is planned for deprecation.
 
 ## Best practices
 
@@ -100,7 +107,8 @@ The main difference between aside, panel and modal dialog is their behaviours:
 	<DoDont
 		type="do"
 		image={{
-			url: layoutDo,
+			url: layoutDoLight,
+			urlDarkMode: layoutDoDark,
 			alt: 'A layout with a grid overlay on the Main area.',
 		}}
 		isFullWidth
@@ -111,7 +119,8 @@ The main difference between aside, panel and modal dialog is their behaviours:
 	<DoDont
 		type="dont"
 		image={{
-			url: layoutDont,
+			url: layoutDontLight,
+			urlDarkMode: layoutDontDark,
 			alt: 'A layout with a grid overlay on the Main area, but also on the Side nav, Aside and Panel areas.',
 		}}
 		isFullWidth
@@ -125,4 +134,3 @@ The main difference between aside, panel and modal dialog is their behaviours:
 - [Page header](/components/page-header)
 - [Top nav items](/components/navigation-system/top-nav-items)
 - [Navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
-- [Preview panel (Atlassians only)](https://atlaskit-website-staging.stg-east.frontend.public.atl-paas.net/#/packages/navigation/preview-panel)

package/constellation/top-nav-items/examples.mdx

@@ -7,6 +7,7 @@ order: 1
 import SectionMessage from '@atlaskit/section-message';
 
 import { TopNavStartLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-start';
+import { TopNavStartToggleExample } from '../../examples/constellation/top-nav-items/top-nav-start-toggle';
 import { TopNavMiddleLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-middle';
 import { TopNavEndLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-end';
 import { AppLogoExample } from '../../examples/constellation/top-nav-items/app-logo';
@@ -18,89 +19,96 @@ import { EndItemExample } from '../../examples/constellation/top-nav-items/end-i
 import { TopNavButtonExample } from '../../examples/constellation/top-nav-items/top-nav-button';
 import { CustomTitleExample } from '../../examples/constellation/top-nav-items/custom-title';
 
-These components can be used within the
-[top nav](/components/navigation-system/layout/examples#top-nav).
+These components can be used within the top nav from [layout](/components/navigation-system/layout/examples).
 
 For other components that can be used within the top nav, see
-[navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).
+[navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).
 
 ## Start items
 
-These actions go in the [Top nav start](/components/navigation-system/layout/examples#top-nav-slots)
-area. They are left-aligned in the following order:
+These actions go in the [top nav start](/components/navigation-system/layout/examples#top-nav-slots)
+area.
 
-- SideNavToggleButton - Opens and closes the
+- Side nav toggle button: Opens and closes the
   [side nav](/components/navigation-system/layout/examples#side-nav).
-- AppSwitcher - Use to open and close an app switcher. See
-  [navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
+- App switcher: Opens and closes an app switcher. See
+  [navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
   for recommended platform components.
 
 Use one of the following logo components to orient users and provide a persistent link to the app
 landing page:
 
-- [AppLogo](#applogo) - A container for an app's [logo icon](/components/logo) and name.
-- [CustomLogo](#customlogo) - A container for custom logo images.
-- [CustomTitle](#customtitle) - Optional text used for app customisation by customers.
+- [App logo](#app-logo): A container for an app's [logo icon](/components/logo) and name.
+- [Custom logo](#custom-logo): A container for custom logo images.
+- [Custom title](#custom-title): Optional text used for app customisation by customers.
 
 <Example Component={TopNavStartLayoutExample} />
 
-### AppLogo
+### Side nav toggle button
 
-`AppLogo` displays an app [logo icon](/components/logo) and name.
+The side nav toggle button must be passed to `TopNavStart` through the `sideNavToggleButton` prop, not via `children`.
+- When the keyboard shortcut is enabled, the toggle button’s tooltip will automatically show Ctrl+[ as the shortcut.
+- The toggle button is left-aligned when the side nav is collapsed, and right-aligned when the side nav is expanded.
 
-- Max width is 320px. If larger, the text will truncate.
+<Example Component={TopNavStartToggleExample} />
+
+### App logo
+
+App logo displays an app [logo icon](/components/logo) and name.
+- It has a maximum width of 320px, after which the app name truncates. The app name also truncates based on the available space when the side nav is resized.
 - At `s` breakpoints and below (less that 1024px), the app name is not shown.
 
-See the [Responsive section](#responsive) for more information.
+See the [responsive section](#responsive) for more information.
 
 <Example Component={AppLogoExample} />
 
-### CustomLogo
+### Custom logo
 
-`CustomLogo` provides a container for custom logo images with the following width and height values:
+Custom logo provides a container for custom logo images with the following constraints:
+- Maximum width: 320px.  If the image is wider than this, or if space is limited when the side nav is resized, the logo will scale down to fit.
+- Maximum height: 24px. If the image is shorter than this, the logo will scale up to fit.
 
-- Max width 320px. If larger, the logo will scale down to fit.
-- Max height 24px. If smaller, the logo will scale up to fit.
+Do not provide explicit width and height values on the image, otherwise it will not respect the container size.
 
-Do not provide explicit width and height values otherwise they will not respect the container size.
-At `s` breakpoints and below (less that 1024px), the provided icon is shown. Above `s` breakpoints,
+At `s` breakpoints and below (less that 1024px), only the provided icon is shown. Above `s` breakpoints,
 the provided logo is shown.
 
-See the [Responsive section](#responsive) for more information.
+See the [responsive section](#responsive) for more information.
 
 <Example Component={CustomLogoExample} />
 
-### CustomTitle
+### Custom title
 
 Optional text used for app customisation by customers.
 
-When present, it sits to the right of the logo, and and will truncate after 200px. At `s`
-breakpoints and below (less than 1024px), `CustomTitle` will not display.
+- When present, it appears to the right of the logo.
+- It has a maximum width of 200px, after which the text truncates. It also truncates based on the available space when the side nav is resized.
+- At `s` breakpoints and below (less than 1024px), the custom title is not displayed.
 
 <Example Component={CustomTitleExample} />
 
 ## Middle items
 
 These actions go in the
-[Top nav middle](/components/navigation-system/layout/examples#top-nav-slots) area, and are
-centre-aligned.
+[top nav middle](/components/navigation-system/layout/examples#top-nav-slots) area.
 
-- It should consist of a search component and a create component, in that order to maintain the
+- They should consist of a search component and a create component, in that order to maintain the
   correct layout behaviour.
+- The actions are centre-aligned when the side nav is collapsed, and left-aligned when the side nav is expanded.
+- At `xl` breakpoints (1768px or greater), the middle items are centred in the viewport when the side nav is expanded, but are pushed out by the side nav to avoid overlapping.
 - We have provided placeholder components. See
-  [navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
+  [navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
   for recommended platform components.
 - Our placeholder search field scales to fill the available area of common actions, up to a maximum
   width of 780px. At `xxs` breakpoints (less than 480px), the search field converts to an icon only
   button.
 
-See the [Responsive section](#responsive) for more information. If using search or create components
+See the [responsive section](#responsive) for more information. If you use search or create components
 from other packages, you may experience different responsive behaviour.
 
 <SectionMessage>
 
-The search bar must be the first child in `TopNavMiddle`, in line with our design specifications. If
-this is not the case, you may see unexpected layout behavior.
+The search bar must be the first child of `TopNavMiddle`, in line with our design specifications. Otherwise, you may see unexpected layout behavior.
 
 </SectionMessage>
 
@@ -108,7 +116,7 @@ this is not the case, you may see unexpected layout behavior.
 
 ## End items
 
-These actions go in the [Top nav end](/components/navigation-system/layout/examples#top-nav-slots)
+These actions appear in the [top nav end](/components/navigation-system/layout/examples#top-nav-slots)
 area. They are right-aligned and provided as a list for accessibility. Contains, in the following
 order:
 
@@ -119,12 +127,12 @@ order:
 - Settings - Use to open and close a settings menu.
 - Profile/Login - A placeholder for an account component.
 
-See [navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
-for recommended platform components for these buttons, or triggered by these buttons.
+See [navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)
+for recommended platform components for these buttons, or components triggered by these buttons.
 
-At `xs` breakpoints and below (less than 768px), these buttons collapse into a single 'more' button.
+At `xs` breakpoints and below (less than 768px), these buttons collapse into a single 'More' button.
 
-See the [Responsive section](#responsive) for more details.
+See the [responsive section](#responsive) for more details.
 
 <Example Component={TopNavEndLayoutExample} />
 
@@ -132,27 +140,27 @@ See the [Responsive section](#responsive) for more details.
 
 If none of the provided end items are suitable, you can create your own icon button using `EndItem`.
 
-If you need a more customised button, use `TopNavButton` and wrap it in a list item.
+If you need a more customised button, use [top nav button](#top-nav-button) and wrap it in a list item.
 
 <Example Component={EndItemExample} />
 
-## Top Nav Button
+## Top nav button
 
-A button that supports theming. Variants available:
+A button component that supports theming. The following variants are available:
 
-- top nav icon button
-- top nav link button
-- top nav link icon button
-- top nav button
+- Top nav icon button
+- Top nav link button
+- Top nav link icon button
+- Top nav button
 
-Use if you need to add buttons to top nav. Adding buttons may negatively impact the consistency
+Use this component when you need to add buttons to the top nav. Be aware that adding custom buttons may negatively impact the consistency
 across apps.
 
 <Example Component={TopNavButtonExample} />
 
 ## Responsive
 
-Top nav items respond to the viewport size. See default behaviour below, or the
+Top nav items respond to the viewport size. See the default behaviour below, or explore the
 [interactive example](/components/navigation-system/examples#examples).
 
 **Note:** If using other platform components in top nav, they may have different responsive
@@ -169,14 +177,14 @@ behaviour.
 
 ## Custom theming
 
-Custom theming is set on the [top nav](/components/navigation-system/layout/examples#top-nav).
+Custom theming is configured on the [top nav](/components/navigation-system/layout/custom-theming).
 
 ### Logos
 
-Logos and icons from the [Logo](/components/logo) package will automatically consume the theme when
+Logos and icons from the [logo](/components/logo) package will automatically consume the theme when
 used with the `AppLogo` or `CustomLogo` component.
 
-Custom logos uploaded by organization admins are unaffected by theming.
+Custom logos uploaded by organization admins are not affected by theming.
 
 <Example Component={CustomThemingLogoExample} />
 
@@ -187,7 +195,7 @@ Search Platform components.
 
 <SectionMessage appearance="warning" title="Use sparingly">
 
-Do not create new components that rely on the `useLegacySearchTheme()` hook. It is only intended for
+Do not create new components that rely on the `useLegacySearchTheme()` hook. It is intended only for
 backwards compatibility, and may be deprecated if the Search Platform evolves.
 
 </SectionMessage>
@@ -196,12 +204,12 @@ backwards compatibility, and may be deprecated if the Search Platform evolves.
 
 ### Buttons
 
-Do not use [Button](/components/button) inside of the top navigation.
+Do not use [button](/components/button) inside of the top navigation.
 
-Use the action components exported from this package (such as `AppSwitcher` and `Create`) as they
-will automatically consume the custom theme.
+Use the action components exported from this package (such as `AppSwitcher`), as they
+ automatically consume the custom theme.
 
-Custom actions can be created using `EndItem` for icon buttons and `TopNavButton` for buttons with
+Custom actions can be created using [end item](#end-item) for icon buttons and [top nav button](#top-nav-button) for buttons with
 visible text.
 
 <Example Component={CustomThemingButtonsExample} />

package/constellation/top-nav-items/usage.mdx

@@ -4,17 +4,29 @@ description: Buttons and elements for the top nav.
 order: 3
 ---
 
-import topNavDo1 from './images/top-nav-do-1.png';
-import topNavDont1 from './images/top-nav-dont-1.png';
-import topNavDo2 from './images/top-nav-do-2.png';
-import topNavDont2 from './images/top-nav-dont-2.png';
+import Image from '@atlaskit/image';
+
+import topNavItemsAnatomyLight from './images/topNavItems-anatomy-light.png';
+import topNavItemsAnatomyDark from './images/topNavItems-anatomy-dark.png';
+import topNavItemsDo1Light from './images/topNavItems-do-1-light.png';
+import topNavItemsDo1Dark from './images/topNavItems-do-1-dark.png';
+import topNavItemsDo2Light from './images/topNavItems-do-2-light.png';
+import topNavItemsDo2Dark from './images/topNavItems-do-2-dark.png';
+import topNavItemsDont1Light from './images/topNavItems-dont-1-light.png';
+import topNavItemsDont1Dark from './images/topNavItems-dont-1-dark.png';
+import topNavItemsDont2Light from './images/topNavItems-dont-2-light.png';
+import topNavItemsDont2Dark from './images/topNavItems-dont-2-dark.png';
 
 ## Usage
 
 Use top nav items to create common utilities in
-the [top nav](/components/navigation-system/top-nav-items).
+the top nav within [layout](/components/navigation-system/layout/examples).
 
-![Diagram of the navigation system top nav](./images/top-nav-anatomy.png)
+<Image
+	src={topNavItemsAnatomyLight}
+	srcDark={topNavItemsAnatomyDark}
+	alt="Diagram of the navigation system top nav"
+/>
 
 1. **Start items:** Left-aligned buttons.
 2. **Middle items:** Centre-aligned actions.
@@ -23,8 +35,8 @@ the [top nav](/components/navigation-system/top-nav-items).
 ## Follow Atlassian's navigation patterns
 
 The current navigation has specific menu items that are similar across apps. Make sure your top
-navigation follows Atlassian patterns consistently,
-[see navigation experience guidelines (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
+navigation follows Atlassian patterns consistently. For all the guidelines, see
+[navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).
 
 ## Best practices
 
@@ -34,7 +46,8 @@ navigation follows Atlassian patterns consistently,
 	<DoDont
 		type="do"
 		image={{
-			url: topNavDo1,
+			url: topNavItemsDo1Light,
+			urlDarkMode: topNavItemsDo1Dark,
 			alt: 'Two buttons, one outlined and one solid purple, both labeled "Button".',
 		}}
 	>
@@ -43,7 +56,8 @@ navigation follows Atlassian patterns consistently,
 	<DoDont
 		type="dont"
 		image={{
-			url: topNavDont1,
+			url: topNavItemsDont1Light,
+			urlDarkMode: topNavItemsDont1Dark,
 			alt: 'Two buttons, one outlined and one solid purple, both labeled "Button".',
 		}}
 	>
@@ -57,7 +71,8 @@ navigation follows Atlassian patterns consistently,
 	<DoDont
 		type="do"
 		image={{
-			url: topNavDo2,
+			url: topNavItemsDo2Light,
+			urlDarkMode: topNavItemsDo2Dark,
 			alt: 'A segment of a top navigation bar showing standard Atlassian icons and a highlighted "ate" item.',
 		}}
 	>
@@ -66,7 +81,8 @@ navigation follows Atlassian patterns consistently,
 	<DoDont
 		type="dont"
 		image={{
-			url: topNavDont2,
+			url: topNavItemsDont2Light,
+			urlDarkMode: topNavItemsDont2Dark,
 			alt: 'A segment of a top navigation bar showing standard Atlassian icons with an additional "Logout" button and a diamond icon.',
 		}}
 	>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/navigation-system",
-	"version": "7.1.2",
+	"version": "7.1.3",
 	"description": "The latest navigation system for Atlassian apps.",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
 	"author": "Atlassian Pty Ltd",
@@ -72,12 +72,12 @@
 		"@atlaskit/layering": "^3.6.0",
 		"@atlaskit/logo": "^19.10.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/popup": "^4.14.0",
+		"@atlaskit/popup": "^4.16.0",
 		"@atlaskit/pragmatic-drag-and-drop": "^1.7.0",
 		"@atlaskit/primitives": "^18.1.0",
 		"@atlaskit/side-nav-items": "^1.12.0",
 		"@atlaskit/tokens": "^11.4.0",
-		"@atlaskit/tooltip": "^21.0.0",
+		"@atlaskit/tooltip": "^21.1.0",
 		"@atlaskit/visually-hidden": "^3.0.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
@@ -93,7 +93,7 @@
 		"@af/accessibility-testing": "workspace:^",
 		"@af/integration-testing": "workspace:^",
 		"@af/visual-regression": "workspace:^",
-		"@atlaskit/app-provider": "^4.1.0",
+		"@atlaskit/app-provider": "^4.2.0",
 		"@atlaskit/badge": "^18.4.0",
 		"@atlaskit/banner": "^14.0.0",
 		"@atlaskit/breadcrumbs": "^16.0.0",
@@ -103,21 +103,21 @@
 		"@atlaskit/link": "^3.3.0",
 		"@atlaskit/lozenge": "^13.5.0",
 		"@atlaskit/menu": "^8.4.0",
-		"@atlaskit/modal-dialog": "^14.13.0",
+		"@atlaskit/modal-dialog": "^14.14.0",
 		"@atlaskit/onboarding": "^14.5.0",
 		"@atlaskit/page-header": "^12.1.0",
 		"@atlaskit/page-layout": "^4.2.0",
 		"@atlaskit/popper": "^7.1.0",
 		"@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^2.1.0",
-		"@atlaskit/select": "^21.9.0",
+		"@atlaskit/select": "^21.10.0",
 		"@atlaskit/skeleton": "^2.1.0",
 		"@atlaskit/textfield": "^8.2.0",
 		"@atlassian/feature-flags-test-utils": "^1.0.0",
-		"@atlassian/gemini": "^1.38.0",
-		"@atlassian/search-dialog": "^9.18.0",
+		"@atlassian/gemini": "^1.39.0",
+		"@atlassian/search-dialog": "^9.20.0",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@atlassian/test-utils": "^1.0.0",
-		"@atlassian/testing-library": "^0.4.0",
+		"@atlassian/testing-library": "^0.5.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@testing-library/react": "^16.3.0",
 		"@testing-library/user-event": "^14.4.3",

package/constellation/layout/diagram.tsx

@@ -1,115 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-
-import { cssMap, jsx } from '@compiled/react';
-
-import { token } from '@atlaskit/tokens';
-
-const styles = cssMap({
-	root: {
-		display: 'grid',
-		gridTemplateColumns: '1fr 3fr 1fr 1fr',
-		gridTemplateRows: 'auto auto 300px',
-		gridTemplateAreas: `
-        "banner banner banner banner"
-        "top-bar top-bar top-bar top-bar"
-        "side-nav main aside panel"
-		`,
-		paddingBlockStart: token('space.100'),
-		paddingInlineEnd: token('space.100'),
-		paddingBlockEnd: token('space.100'),
-		paddingInlineStart: token('space.100'),
-		marginBlockEnd: token('space.100'),
-		borderWidth: token('border.width'),
-		borderStyle: 'solid',
-		borderColor: token('color.border'),
-		borderRadius: token('radius.small'),
-		backgroundColor: `linear-gradient(
-      45deg,
-      ${token('elevation.surface.sunken')} 25%,
-      transparent 25%
-    ),linear-gradient(
-      135deg,
-      ${token('elevation.surface.sunken')} 25%,
-      transparent 25%
-    ),linear-gradient(
-      45deg,
-      transparent 75%,
-      ${token('elevation.surface.sunken')} 75%
-    ),linear-gradient(
-      135deg,
-      transparent 75%,
-      ${token('elevation.surface.sunken')} 75%
-    )`,
-		backgroundPosition: '0 0,10px 0,10px -10px,0px 10px',
-		backgroundSize: '20px 20px',
-	},
-	slot: {
-		width: '100%',
-		height: '100%',
-		paddingBlockStart: token('space.100'),
-		paddingInlineEnd: token('space.100'),
-		paddingBlockEnd: token('space.100'),
-		paddingInlineStart: token('space.100'),
-	},
-	placeholder: {
-		width: '100%',
-		height: '100%',
-		backgroundColor: token('color.background.neutral'),
-		borderWidth: token('border.width'),
-		borderStyle: 'solid',
-		borderColor: token('color.border'),
-		borderRadius: token('radius.small'),
-		paddingBlockStart: token('space.100'),
-		paddingInlineEnd: token('space.100'),
-		paddingBlockEnd: token('space.100'),
-		paddingInlineStart: token('space.100'),
-	},
-	bannerSlot: {
-		gridArea: 'banner',
-	},
-	topBarSlot: {
-		gridArea: 'top-bar',
-		backgroundColor: token('elevation.surface'),
-	},
-	sideNavSlot: {
-		gridArea: 'side-nav',
-		backgroundColor: token('elevation.surface'),
-	},
-	mainSlot: {
-		gridArea: 'main',
-	},
-	asideSlot: {
-		gridArea: 'aside',
-		paddingInlineStart: token('space.0'),
-	},
-	panelSlot: {
-		gridArea: 'panel',
-		paddingInlineStart: token('space.0'),
-	},
-});
-
-export const PageLayoutDiagram: () => JSX.Element = () => (
-	<div css={styles.root}>
-		<div css={[styles.slot, styles.bannerSlot]}>
-			<div css={styles.placeholder}>Banner</div>
-		</div>
-		<div css={[styles.slot, styles.topBarSlot]}>
-			<div css={styles.placeholder}>Top nav</div>
-		</div>
-		<div css={[styles.slot, styles.sideNavSlot]}>
-			<div css={styles.placeholder}>Side nav</div>
-		</div>
-		<div css={[styles.slot, styles.mainSlot]}>
-			<div css={styles.placeholder}>Main</div>
-		</div>
-		<div css={[styles.slot, styles.asideSlot]}>
-			<div css={styles.placeholder}>Aside</div>
-		</div>
-		<div css={[styles.slot, styles.panelSlot]}>
-			<div css={styles.placeholder}>Panel</div>
-		</div>
-	</div>
-);