@automattic/vip-design-system 1.3.2 → 1.4.0

package/build/system/Notice/Notice.stories.js

@@ -6,6 +6,7 @@ var _react = _interopRequireDefault(require("react"));
 var _ = require("..");
 var _jsxRuntime = require("theme-ui/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+/** @jsxImportSource theme-ui */
 /**
  * External dependencies
  */
@@ -80,13 +81,14 @@ var Default = exports.Default = function Default() {
     }), (0, _jsxRuntime.jsx)(_.Notice, {
       variant: "alert",
       sx: {
-        mb: 4
+        mb: 2
       },
       title: "There are errors in your form",
       headingVariant: "h2",
       children: (0, _jsxRuntime.jsxs)("ul", {
         sx: {
-          mb: 0
+          m: 0,
+          pl: 3
         },
         children: [(0, _jsxRuntime.jsx)("li", {
           children: (0, _jsxRuntime.jsx)(_.Link, {
@@ -105,6 +107,36 @@ var Default = exports.Default = function Default() {
           })
         })]
       })
+    }), (0, _jsxRuntime.jsx)(_.Notice, {
+      variant: "alert",
+      sx: {
+        mb: 2
+      },
+      children: (0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+        children: [(0, _jsxRuntime.jsx)(_.Heading, {
+          variant: 'h4',
+          sx: {
+            fontSize: 2
+          },
+          children: "Alternative way of printing errors"
+        }), (0, _jsxRuntime.jsxs)("ul", {
+          sx: {
+            m: 0,
+            pl: 3
+          },
+          children: [(0, _jsxRuntime.jsx)("li", {
+            children: (0, _jsxRuntime.jsx)(_.Link, {
+              href: "#name",
+              children: "Please enter your name."
+            })
+          }), (0, _jsxRuntime.jsx)("li", {
+            children: (0, _jsxRuntime.jsx)(_.Link, {
+              href: "#email",
+              children: "Please enter your email address."
+            })
+          })]
+        })]
+      })
     }), (0, _jsxRuntime.jsxs)(_.Notice, {
       variant: "alert",
       sx: {

package/build/system/Tabs/Tabs.stories.jsx

@@ -11,7 +11,7 @@ import React from 'react';
 import { Tabs, TabsTrigger, TabsList, TabsContent, Text, Link, Button } from '..';
 
 export default {
-	title: 'Tabs',
+	title: 'Navigation/Tabs',
 	component: Tabs,
 };
 

package/build/system/Wizard/Wizard.stories.js

@@ -14,7 +14,7 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "d
  * Internal dependencies
  */
 var _default = exports["default"] = {
-  title: 'Wizard',
+  title: 'Navigation/Wizard',
   component: _.Wizard
 };
 var Default = exports.Default = function Default() {

package/build/system/index.d.ts

@@ -39,6 +39,8 @@ import { Textarea } from './Form';
 import { Progress } from './Progress';
 import { Text } from './Text';
 import { Tabs } from './Tabs';
+import { Nav } from './Nav';
+import { NavItem } from './Nav';
 import { TabsTrigger } from './Tabs';
 import { TabsContent } from './Tabs';
 import { TabsList } from './Tabs';
@@ -48,4 +50,4 @@ import { Validation } from './Form';
 import { Wizard } from './Wizard';
 import { WizardStep } from './Wizard';
 import theme from './theme';
-export { Accordion, Avatar, Badge, Box, Button, ButtonSubmit, ButtonVariant, Card, Checkbox, Code, Dialog, NewDialog, Form, Dropdown, DialogButton, DialogMenu, DialogMenuItem, DialogDivider, DialogContent, DialogTrigger, ConfirmationDialog, NewConfirmationDialog, Grid, Flex, Notice, OptionRow, Heading, Input, Label, Spinner, Table, TableRow, TableCell, Tooltip, Link, Radio, RadioBoxGroup, Textarea, Progress, Text, Tabs, TabsTrigger, TabsContent, TabsList, Toggle, ToggleRow, Validation, Wizard, WizardStep, WizardStepHorizontal, theme };
+export { Accordion, Avatar, Badge, Box, Button, ButtonSubmit, ButtonVariant, Card, Checkbox, Code, Dialog, NewDialog, Form, Dropdown, DialogButton, DialogMenu, DialogMenuItem, DialogDivider, DialogContent, DialogTrigger, ConfirmationDialog, NewConfirmationDialog, Grid, Flex, Notice, OptionRow, Heading, Input, Label, Spinner, Table, TableRow, TableCell, Tooltip, Link, Radio, RadioBoxGroup, Textarea, Progress, Text, Tabs, Nav, NavItem, TabsTrigger, TabsContent, TabsList, Toggle, ToggleRow, Validation, Wizard, WizardStep, theme };

package/build/system/index.js

@@ -7,6 +7,8 @@ import { Box } from './Box';
 import { Button, ButtonSubmit, ButtonVariant } from './Button';
 import { Card } from './Card';
 import { Code } from './Code';
+import { Nav, NavItem } from './Nav';
+
 import {
 	Dialog,
 	DialogButton,
@@ -48,7 +50,7 @@ import { OptionRow } from './OptionRow';
 import { Table, TableRow, TableCell } from './Table';
 import { Text } from './Text';
 import theme from './theme';
-import { Wizard, WizardStep, WizardStepHorizontal } from './Wizard';
+import { Wizard, WizardStep } from './Wizard';
 import { Tabs, TabsList, TabsContent, TabsTrigger } from './Tabs';
 
 export {
@@ -93,6 +95,8 @@ export {
 	Progress,
 	Text,
 	Tabs,
+	Nav,
+	NavItem,
 	TabsTrigger,
 	TabsContent,
 	TabsList,
@@ -101,6 +105,5 @@ export {
 	Validation,
 	Wizard,
 	WizardStep,
-	WizardStepHorizontal,
 	theme,
 };

package/docs/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# Architecture
+
+## Basic functionality
+
+`vip-design-system` is a React component released in the NPM registry. It's a [public package](https://www.npmjs.com/package/@automattic/vip-design-system) that anyone can install.
+
+## Languages & coding standard
+
+Both JavaScript and TypeScript are used to implement the software.
+
+We require that the WPVIP defined coding style to be used, defined in [.eslintrc.js](https://github.com/Automattic/vip-design-system/blob/trunk/.eslintrc.js).
+
+We also use [.prettierrc](https://github.com/Automattic/vip-design-system/blob/trunk/.prettierrc) to have a standard on coding formatting. It's recommended to set your Editor to apply "Format on Save".
+
+[JEST](https://github.com/Automattic/vip-design-system/blob/readme-update/package.json#L16-L17) is the test-runnner used in this application.
+
+## Code structure
+
+The code is structured in the following way:
+
+- [.github/](https://github.com/Automattic/vip-design-system/tree/trunk/.github) — configuration and templates for GitHub actions.
+- [.storybook/](https://github.com/Automattic/vip-design-system/tree/trunk/.storybook) — configuration files for Storybook
+- [src/](https://github.com/Automattic/vip-design-system/tree/trunk/src) — Javascript and Typescript react component files + Theme configuration + Components tests (on each component folder).
+- [test/](https://github.com/Automattic/vip-design-system/tree/trunk/test) — Test utilities, mocks or configuration for the test suite.
+- [tokens/](https://github.com/Automattic/vip-design-system/tree/trunk/test) — VIP Design Sytem tokens exported using [Figma Studio](https://docs.tokens.studio/). This is the source of truth for the Design team tokens, variables, etc.
+
+### Components structure
+
+Components lives under the `src/system/ComponentName` directory. Each component folder contains a similar set of files. Let's use the [Avatar](https://github.com/Automattic/vip-design-system/tree/trunk/src/system/Avatar) component as an example:
+
+- **Avatar.stories.tsx**: This is the documentation file of the component. The `*.stories` is related to the Storybook story files.
+- **Avatar.test.tsx**: This is the test file for this component. We run `jest` as a runner in this application.
+- **Avatar.tsx**: This is the TypeScript component itself.
+- **index.ts**: Some components has a index file to export different files. This is not recommended anymore.
+
+### Theme UI & Radix UI Primitives
+
+Most of our components are based on [https://theme-ui.com/](https://theme-ui.com/) components. We try to write our own components as much as we can. Other components are based on [Radix UI Primitives](https://www.radix-ui.com/primitives) components. Radix usually has some solid and accessible components that we can use as a base.
+
+## Updating the Theme with VIP Design System Tokens
+
+You need to update the tokens once the VIP Design System updates the core files. The Figma Studio plugin will push files into the [tokens/](https://github.com/Automattic/vip-design-system/tree/trunk/tokens) folder. Once these files are there, you can run the following:
+
+```bash
+npm run theme-update
+```
+
+to have an updated json theme under [src/system/theme/generated/](https://github.com/Automattic/vip-design-system/tree/trunk/src/system/theme/generated).
+
+### How the theming works
+
+We use the VIP Design System Tokens as our base theme structure. All colors, spaces, types should come from a dynamic token system provided by the VIP Design team, currently using Figma as the design software. When the design system is updated by the Design team, they push files to the [tokens/](https://github.com/Automattic/vip-design-system/tree/trunk/tokens) directory.
+
+By using the [Token Transformer](https://docs.tokens.studio/sync/github#7-how-to-use-tokens-stored-in-github-in-development) and a custom npm script, we parse this file getting only the VIP Dashboard theme we need for the react components. The light theme is called: `wpvip-product-core`, and the dark theme is called `wpvip-product-dark`.
+
+Once the new file is updated, we need to generate a custom theme file in [src/system/theme/generated/valet-theme-light.json](https://github.com/Automattic/vip-design-system/blob/trunk/src/system/theme/generated/valet-theme-light.json). It will also generate a Dark theme version. This operation generates JSON files with the colors we need already filled in.
+
+Once the theme is updated, the file [src/system/theme/index.js](https://github.com/Automattic/vip-design-system/blob/trunk/src/system/theme/index.js) reads the colors and apply to all components.
+
+Use the section below to run the script and update the theme.
+
+_Important:_ If you change the `generated/valet-theme-light.json` or the `generated/valet-theme-dark.json`, or changes will be overwritten once someone runs `npm run theme-update` again.
+
+### Update theme script
+
+Run this command to update the VIP Valet Theme with the latest `tokens/**` files.
+
+```bash
+npm run theme-update
+```
+
+## Feature flags
+
+No feature flags are currently in use.
+
+## Database
+
+This project has no database storage.
+
+## Dependencies
+
+This is a standalone NPM package. Currently there's no API communication. All the code dependencies are listed in the [package.json](https://github.com/Automattic/vip-design-system/blob/trunk/package.json) file of this project.
+
+Major dependencies of this project are:
+
+- Storybook — Dev dependency for previewing our components and documentation
+- Theme UI — Base theme and components structure
+- Radix — React primitives components used to build some of our custom components

package/docs/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+## Pull requests & issues
+
+We welcome any contributions to this project.
+
+If you have a small bugfix and already have the code available, feel free to [create a pull request](https://github.com/Automattic/vip-design-system/compare). If you have a feature suggestion, please [create an issue](https://github.com/Automattic/vip-design-system/issues/new). Please follow the instructions provided. Please assign a priority to the issue/pull request according to the definitions found below.
+
+Before writing a patch or a larger chunk of code, please ensure to study the [ARCHITECTURE.md](ARCHITECTURE.md) and [TESTING.md](TESTING.md) files. Ensure that all tests pass before asking for a review of your pull request.
+
+## Watching for changes
+
+You can build it continuously so that every time you make a change, build files are automatically updated:
+
+```bash
+npm run watch
+```
+
+## Troubleshooting
+
+### Dialog + Dropdown usage
+
+If you are facing a Dialog overlaping a Dropdown content, add this CSS to your application:
+
+```css
+div[data-radix-popper-content-wrapper][data-aria-hidden='true'] {
+	opacity: 0;
+}
+```
+
+## Priorities
+
+Each GitHub issue and pull request relating to this repository should have a priority label to make prioritizing easier. The definition of each priority is as follows:
+
+- [Critical](https://github.com/Automattic/vip-design-system/labels/%5BPri%5D%20Critical): A bug currently affecting normal operation or a security problem that needs to be addressed urgently.
+- [High](https://github.com/Automattic/vip-design-system/labels/%5BPri%5D%20High): An issue that is: a) relevant to current goals of the project, b) a bug that needs to addressed soon to maintain stability, or c) a feature often requested.
+- [Normal](https://github.com/Automattic/vip-design-system/labels/%5BPri%5D%20Normal): Most issues belong here. These will include features less often requested, new lower priority features, documentation updates, etc.
+- [Low](https://github.com/Automattic/vip-design-system/labels/%5BPri%5D%20Low): Features that are good to have belong here.
+
+## Type of change labels
+
+Each GitHub issue and pull-request should have a type of change label associated with it. The definition of these are as follows:
+
+- [In Progress](https://github.com/Automattic/vip-design-system/labels/%5BStatus%5D%20In%20Progress): You can either use a draft pull request or keep as in-progress with this label.
+- [Needs Review](https://github.com/Automattic/vip-design-system/labels/%5BStatus%5D%20Needs%20Review): Marked as needs review from others.
+- [Has Feedback](https://github.com/Automattic/vip-design-system/labels/%5BStatus%5D%20Has%20Feedback): If you left feedback to the Pull request, mark with this label.
+- [Ready to Merge](https://github.com/Automattic/vip-design-system/labels/%5BStatus%5D%20Ready%20to%20Merge): Approved and ready to be merged.
+- [Bug](https://github.com/Automattic/vip-design-system/labels/%5BType%5D%20Bug): Code change to fix a bug, or a bug report.
+- [Stale](https://github.com/Automattic/vip-design-system/labels/%5BStatus%5D%20Stale): Marked as stale because it has been inactive for some period.
+- [Documentation](https://github.com/Automattic/vip-design-system/labels/%5BType%5D%20Documentation): Pull request to update documentation.
+- [Enhancement](https://github.com/Automattic/vip-design-system/labels/%5BType%5D%20enhancement): A general enhancement – new feature, better implementation, new tests and so forth.
+- [Update dependency](https://github.com/Automattic/vip-design-system/labels/dependencies): Pull request to update one or more dependencies.
+- [NPM version update](https://github.com/Automattic/vip-design-system/labels/%5B%20Type%20%5D%20NPM%20version%20update): The GitHub action bot adds this label to automated dev or package release pull requests.
+- [Question](https://github.com/Automattic/vip-design-system/labels/%5BType%5D%20Question): Prefer using the GitHub issues for asking questions.

package/docs/RELEASING.md

@@ -0,0 +1,70 @@
+# Releasing
+
+This package is published to [NPM](https://www.npmjs.com/package/@automattic/vip-design-system). The process to release to NPM should be started when all pull requests intended for publishing have been merged and the software has been fully tested for publication. You can release either using GitHub Actions or locally.
+
+## Versioning Guidelines
+
+- `patch`: for non-breaking changes/bugfixes and small updates.
+- `minor`: for some new features, bug fixes, and other non-breaking changes.
+- `major`: for breaking changes.
+
+## Note on NPM token
+
+Publishing via the GitHub Action requires that the `NPM_TOKEN` be set correctly in [GitHub Actions secrets](https://github.com/Automattic/vip-design-system/settings/secrets/actions). This should be an npm token generated for a bot user on [the npm @automattic org](https://www.npmjs.com/settings/automattic) that has publish access to this repo.
+
+## Release Methods
+
+### GitHub Actions (Preferred)
+
+This is the preferred method for pushing out the latest release. The workflow runs a bunch of validations, generates a build, bump versions + tags, pushes out to npm, and bumps to the next dev version.
+
+1. Initiate the [release process here](https://github.com/Automattic/vip-design-system/actions/workflows/npm-prepare-release.yml).
+1. On the right-hand side, select "Run Workflow".
+1. Pick your preferred version bump.
+1. Click `Run Workflow`.
+1. Wait for a pull request to appear. The pull request will update the version number and shall be assigned to you.
+1. When ready, merge the pull request. This will lead to a new version to be [published on npmjs.com](https://www.npmjs.com/package/@automattic/vip-design-system).
+1. Another pull request will be created to bump to a development version, also assigned to you. Merge it to finish the process.
+
+### Local
+
+Follow these steps to publish locally:
+
+1. Make sure you have NPM access to our @Automattic organization. Ask for #vip-platform-pâtisserie help in case you need it.
+2. Pull all the changes to your local `trunk` branch. Make sure you have the latest changes (`git pull`).
+3. We follow the [https://semver.org/](https://semver.org/) versioning. You should run the specific version you are trying to publish:
+
+```bash
+npm version major|minor|patch
+```
+
+4. You should see a version bump in the [package.json](https://github.com/Automattic/vip-design-system/blob/trunk/package.json) file.
+5. Build the application:
+
+```bash
+npm run build
+```
+
+6. Publish the application
+
+```bash
+npm publish
+```
+
+Note: You need to have two-factor enabled in your npm account. The publish command will request a two-factor code to complete the publishing process. You can also add `--otp=CODE` to the `npm publish` command if you already have the code.
+
+7. Push the tags to the repository and trunk updates.
+
+```bash
+git push --tags
+git push origin trunk
+```
+
+8. For major versions or breaking changes, it's recommended to [create a RELEASE](https://github.com/Automattic/vip-design-system/releases) with the published tag.
+
+Ps: Add a `BREAKING CHANGES` section to the release. This will avoid folks trying to figure out why their code is not working on the VIP Dashboard or any other system.
+
+## In case of problems
+
+If you released a broken version, ensure to inform in the GitHub release entry about the breaking change, and follow the instructions provided by NPM in: [Deprecating and undeprecating packages or package versions
+](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions).

package/docs/SETUP.md

@@ -0,0 +1,68 @@
+# Setup
+
+## Language & requirements
+
+- Implemented in JavaScript and TypeScript.
+- Requirements are:
+  - Node, see version in [package.json](https://github.com/Automattic/vip-design-system/blob/trunk/package.json)
+  - A few NPM packages are needed, those are listed in the same file.
+  - The software is fairly lightweight, no special hardware requirements.
+  - Network access.
+
+## Installation & setup instructions
+
+### Fetching & installing
+
+This will fetch the package and install all dependencies:
+
+```bash
+git clone git@github.com:Automattic/vip-design-system.git && \
+cd vip-design-system && npm install
+```
+
+### Building
+
+This will build all TypeScript files so they can be executed:
+
+```bash
+cd vip-design-system && \
+npm run build
+```
+
+## Usage
+
+The best experience is to use Storybook preview for set up and development.
+
+### Starting up locally
+
+Run:
+
+```bash
+npm run dev
+```
+
+You can then visit [http://localhost:60006/](http://localhost:60006/) to view.
+
+## Updating dependencies
+
+Dependencies should be updated by merging [pull requests from dependabot](https://github.com/Automattic/vip-design-system/pulls/app%2Fdependabot). However, great care should be taken before merging as updating dependencies can cause errors with the `vip-design-system` components. There can also be effects to the [RELEASING](https://github.com/Automattic/vip-design-system/blob/trunk/docs/RELEASING.md) process. This can happen silently.
+
+### Before merging
+
+Consider removing the dependency. Can the functionality needed from the dependency be implemented directly into `vip-design-system` or our own common libraries? If not, evaluate the following:
+
+1. If the dependency is one of the [development dependencies](https://github.com/Automattic/vip-design-system/blob/trunk/package.json) (`devDependencies`), and/or only used by one of those, the likelihood of customer-impacting failure is low.
+2. Is the package used in the [RELEASING](https://github.com/Automattic/vip-design-system/blob/trunk/docs/RELEASING.md) process? If it is, evaluate if any failure is likely to be silent. If that seems not to be the case, the risk of customer-impacting failure is low.
+3. Is the package used in one or more [components](https://github.com/Automattic/vip-design-system/blob/trunk/src/system)? If it is, evaluate if any failure is likely to be silent. Take a look at the [TESTING](https://github.com/Automattic/vip-design-system/blob/trunk/docs/RELEASING.md) strategies to ensure the update is good.
+
+#### Low risk dependencies
+
+If the risk of merging is low, you can go a head and merge without doing anything further (given that all tests succeed).
+
+#### Higher risk dependencies
+
+For higher risk dependencies, the jobs using the dependency [will have to be tested locally](https://github.com/Automattic/vip-design-system/blob/trunk/docs/TESTING.md#locally) and the results verified. You can [run it locally](https://github.com/Automattic/vip-design-system/blob/trunk/docs/SETUP.md#starting-up-locally) and verify that all affected components are working normally.
+
+### After merging
+
+Test any [external Applications tests](https://github.com/Automattic/vip-design-system/blob/trunk/docs/TESTING.md#external-applications-tests) using the `vip-design-system` as a dependency, for example, [the VIP Dashboard](https://github.com/automattic/vip-dashboard).

package/docs/TESTING.md

@@ -0,0 +1,63 @@
+# Testing
+
+Testing is an integral part of creating new features and maintaining the software.
+
+## Automated testing
+
+A [few actions](https://github.com/Automattic/vip-design-system/tree/trunk/.github/workflows) are automatically run via Github Actions when a pull request is created or updated.
+
+### Linting
+
+We run the following checks:
+
+- linting (`npm run lint`)
+- format checking (`npm run format:check`)
+- type checks (`npm run check-types`)
+
+### Dependency checks
+
+We use the [dependaban action](https://github.com/Automattic/vip-actions/tree/trunk/dependaban) from [Automattic/vip-actions](https://github.com/Automattic/vip-actions/) to verify that no dependencies have install scripts.
+
+### Unit tests
+
+The tests are located inside of of each component. For example: [src/system/Accordion/Accordion.test.tsx](https://github.com/Automattic/vip-design-system/tree/trunk/src/system/Accordion/Accordion.test.tsx).
+
+We recommend you to write tests close to the component implementation.
+
+#### Adding new unit tests
+
+When creating a new component, please consider adding a new unit test. Please ensure that the file name of the test matches the file name of the job. Example: `Button.test.tsx`. Put the test in the same folder as the component.
+
+### Manual tests
+
+We can test three ways:
+
+**Storybook**
+
+For components that include storybooks, we can run `npm run dev` to view the components in a sandbox-ed storybook environment.
+
+**Pull Request Preview (Easy and recommended)**
+
+Once you create a Pull request, a netlify bot will add a comment to your Pull Request with a preview link of the Storybook preview. This is helpful to share with other folks.
+
+### External Applications tests
+
+**npm link (not reliable)**
+
+1. Run `npm link` in your checkout of this repo.
+2. Spin up a local copy of [the VIP Dashboard](https://github.com/automattic/vip-dashboard) and navigate to a page using the linked components from `@automattic/vip-design-system`
+
+Note: it's super useful to run `npm run watch` in another process, so any changes will be almost immediately available / testable.
+
+**Manual Github Commit (More work, but reliable)**
+
+1. Create your local changes and push to origin a new branch.
+2. In a local copy of the [the VIP Dashboard](https://github.com/automattic/vip-dashboard) edit the vip-design-system line inside of the `package.json` file. Change the line with this:
+
+```bash
+"@automattic/vip-design-system": "github:automattic/vip-design-system#YOUR_PUSHED_COMMIT_HASH",
+```
+
+3. Run `npm install` in the vip-dashboard
+4. Run `npm run dev`
+5. You should have your changes available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip-design-system",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "main": "build/system/index.js",
   "scripts": {
     "build-storybook": "storybook build",
@@ -34,6 +34,7 @@
     "@radix-ui/react-checkbox": "^1.0.0",
     "@radix-ui/react-dialog": "^1.0.0",
     "@radix-ui/react-dropdown-menu": "^1.0.1-rc.6",
+    "@radix-ui/react-navigation-menu": "^1.1.4",
     "@radix-ui/react-switch": "^1.0.0",
     "@radix-ui/react-tabs": "^1.0.0",
     "@radix-ui/react-tooltip": "^1.0.0",

package/src/system/Form/Radio.js

@@ -31,7 +31,6 @@ const inputStyle = {
 		content: '""',
 		border: '1px solid',
 		borderColor: baseControlBorderStyle.borderColor,
-		zIndex: 3,
 		left: `${ -1 * radioPosition }px`,
 	} ),
 	'&:checked ~ label::after': {
@@ -54,7 +53,6 @@ const labelStyle = {
 		top: 1,
 		left: `${ -1 * radioPosition }px`,
 		transition: 'all .3s ease-out',
-		zIndex: 2,
 		width: '16px',
 		height: '16px',
 	},

package/src/system/Link/Link.stories.tsx

@@ -9,8 +9,8 @@ import type { StoryObj } from '@storybook/react';
 import { Link } from '..';
 
 export default {
+	title: 'Navigation/Link',
 	component: Link,
-	title: 'Link',
 };
 
 type Story = StoryObj< typeof Link >;

package/src/system/Nav/Nav.stories.tsx

@@ -0,0 +1,117 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Nav, NavItem } from '../../system';
+
+export default {
+	title: 'Navigation/Nav',
+	component: Nav,
+	parameters: {
+		docs: {
+			description: {
+				component: `
+A navigation menu is a list of links used to navigate a website. It is usually placed in a prominent position at the top of a site, or anywhere that needs a linked-navigation.
+
+## Guidance
+
+### When to use the Nav component
+
+- To link internal or external links in a menu format.
+- To link to pages that are not part of the main navigation.
+
+### When to consider something else
+
+- If you have content inside the same page that will not affect the page Route/URL, use [Tabs](/docs/tabs--docs) component instead.
+- If you are planning to have buttons in your navigation, use another navigation solution, for example: [Dropdown](/docs/dropdown--docs) component instead.
+
+## Accessibility Considerations guidance
+
+This component is based on the Radix Navigation Menu primitive, so it contains all the accessibility features from the primitive.
+
+- Adheres to the [navigation role requirements.](https://www.w3.org/TR/wai-aria-1.2/#navigation)
+- Keyboard Interactions: https://www.radix-ui.com/primitives/docs/components/navigation-menu#keyboard-interactions
+
+### Usability guidance
+
+Pick one of the available variants: Primary or Tabs. You can use the components directly from the \`Nav\` component:
+
+~~~jsx filename="index.jsx"
+import { Nav, NavItem } from '@automattic/components';
+
+<Nav.Primary> or <Nav.Tab>
+<NavItem.Primary> or <NavItem.Tab>
+~~~
+
+### Usage with Next.js framwork
+
+~~~jsx filename="index.jsx"
+import Link from 'next/link';
+
+<Nav.Primary label="Etc">
+	<NavItem.Primary
+		active
+		href="https://google.com"
+		asChild // This is important to pass the link styles to the child
+	>
+		<Link href={ \`/orgs/\${ id }/sso/configurations/\${ idP }/edit/\${ tab.path }\` }>
+			Your page name
+		</Link>
+	</NavItem.Primary>
+</Nav.Primary>
+~~~
+
+-------
+
+## Component Properties
+`,
+			},
+		},
+	},
+};
+
+type Story = StoryObj< typeof Nav >;
+
+export const Default: Story = {
+	render: () => (
+		<>
+			<p>
+				<strong>Variant: Primary</strong>
+			</p>
+			<Nav.Primary sx={ { mb: 4 } } label="Nav Primary">
+				<NavItem.Primary active href="#">
+					PHP
+				</NavItem.Primary>
+				<NavItem.Primary href="https://wordpress.com">WordPress</NavItem.Primary>
+				<NavItem.Primary href="htpps://newrelic.com/">New Relic</NavItem.Primary>
+				<NavItem.Primary disabled href="https://google.com/">
+					Not accessible
+				</NavItem.Primary>
+			</Nav.Primary>
+		</>
+	),
+};
+
+export const Tab: Story = {
+	render: () => (
+		<>
+			<p>
+				<strong>Variant: Tab</strong>
+			</p>
+			<Nav.Tab sx={ { mb: 4 } } label="Nav Tab">
+				<NavItem.Tab active href="#">
+					PHP
+				</NavItem.Tab>
+				<NavItem.Tab href="https://wordpress.com">WordPress</NavItem.Tab>
+				<NavItem.Tab href="htpps://newrelic.com/">New Relic</NavItem.Tab>
+				<NavItem.Tab disabled href="https://google.com/">
+					Not accessible
+				</NavItem.Tab>
+			</Nav.Tab>
+		</>
+	),
+};