From a5bb845071ad4e75b83b92c5a520dd3c142dd01f Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 17:29:53 -0500
Subject: [PATCH 1/9] Align section name with the others (Tooling => Tools)

---
 polaris.shopify.com/content/tooling/index.md  |   6 -
 .../content/tooling/stylelint-polaris.md      | 652 ------------------
 polaris.shopify.com/content/tools/index.md    |   6 +
 polaris.shopify.com/pages/[...slug].tsx       |   2 +-
 .../pages/{tooling.tsx => tools.tsx}          |   4 +-
 5 files changed, 9 insertions(+), 661 deletions(-)
 delete mode 100644 polaris.shopify.com/content/tooling/index.md
 delete mode 100644 polaris.shopify.com/content/tooling/stylelint-polaris.md
 create mode 100644 polaris.shopify.com/content/tools/index.md
 rename polaris.shopify.com/pages/{tooling.tsx => tools.tsx} (85%)

diff --git a/polaris.shopify.com/content/tooling/index.md b/polaris.shopify.com/content/tooling/index.md
deleted file mode 100644
index 3a260a3cfe3..00000000000
--- a/polaris.shopify.com/content/tooling/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Tooling
-description: Extensions, plugins, and other tools to help build and maintain Polaris within the Admin.
-icon: ToolsMajor
-order: 9
----
diff --git a/polaris.shopify.com/content/tooling/stylelint-polaris.md b/polaris.shopify.com/content/tooling/stylelint-polaris.md
deleted file mode 100644
index 545e7f2db09..00000000000
--- a/polaris.shopify.com/content/tooling/stylelint-polaris.md
+++ /dev/null
@@ -1,652 +0,0 @@
----
-title: Stylelint Polaris
-description: A configuration of Stylelint rules that promote adoption and track coverage of the Polaris design system in consuming apps.
-icon: WandMajor
-keywords:
-  - stylelint
-  - dev tools
-  - tools
-  - development
-  - plugin
----
-
-## Installation
-
-```sh
-yarn -D @shopify/stylelint-polaris stylelint
-```
-
-> Note: `stylelint-polaris` requires a peer dependency of `stylelint@>=14.15.0`
-
-[Source code](https://github.com/Shopify/polaris/tree/main/stylelint-polaris)
-
-## Usage
-
-Extend `@shopify/stylelint-polaris` in your [Stylelint config](https://stylelint.io/user-guide/configure/). Example in `package.json`
-
-```json
-{
-  "stylelint": {
-    "extends": ["@shopify/stylelint-polaris"]
-  }
-}
-```
-
-> IMPORTANT: `@shopify/stylelint-polaris` must be added to the end of the `extends` array
-
-### Run the linter
-
-```sh
-npx stylelint '**/*.{css,scss}'
-```
-
-### Run the linter and autofix failures
-
-```sh
-npx stylelint --fix '**/*.{css,scss}'
-```
-
-### Ignoring existing failures
-
-Enabling the linter could result in a large amount of warnings and errors in existing codebases. It is important to fix as many failures upfront as possible, but that shouldn't block the linter from being added. The [styles-insert-stylelint-disable](https://github.com/Shopify/polaris/tree/main/polaris-migrator#v10) migration inserts [ignore comments](https://stylelint.io/user-guide/ignore-code/) so that enabling `stylelint-polaris` can be unblocked.
-
-The migration will insert comments as follows:
-
-```diff
-+ // stylelint-disable-next-line -- generated by polaris-migrator DO NOT COPY
-padding: 1rem;
-```
-
-Run the following command substituting `<path>` with a glob pattern of files to run against:
-
-```sh
-npx @shopify/polaris-migrator styles-insert-stylelint-disable <path>
-```
-
-## Development
-
-### Add new rules
-
-1. Navigate to the root [`stylelint-polaris` config](index.js)
-1. Locate the `stylelint-polaris/coverage` options
-1. Identify the appropriate category for the new rule
-1. Insert the rule using standard Stylelint [rule configurations](https://stylelint.io/user-guide/configure#rules)
-1. Add documentation for the rule with examples of code that will be reported as a problem and code that will fix the problem
-1. The title should be the category + the stylelint rule name, for example `### colors/color-named`
-
-```js
-module.exports = {
-  rules: {
-    'polaris/coverage': {
-      colors: {...}, // Standard Stylelint rules config
-      layout: {...}, // Standard Stylelint rules config
-      motion: {
-        'new-rule': 'new-rule-options',
-      },
-    },
-  },
-};
-```
-
-### Build custom rules
-
-1. Refer to the [Writing plugins](https://stylelint.io/developer-guide/plugins) guide of the Stylelint documentation
-1. Create your rule in the [plugins](plugins) directory
-1. Validate your plugin with [tests](https://github.com/stylelint/jest-preset-stylelint#usage) (reference sibling plugins for examples)
-1. Refer to the [Add new rules](#add-new-rules) section to add your custom rule to the `stylelint-polaris` config
-
-### Add custom messages
-
-Custom messages are surfaced in the command line, CI, and supported editors along side the default `stylelint` rule messages. They are added to the root level config and aim to provide more insight on how to resolve rule violations.
-
-In a majority of cases, the default rule messages are clear and concise. However, they don't always guide developers to a desired outcome. Thus, there are two mechanisms we suggest for improving and providing custom rule messages:
-
-Set a generic custom message on the `message` property of the secondary options of a given `stylelint-polaris/coverage` category. This message is appended to the default rule message and we expect will cover most cases.
-
-```js
-module.exports = {
-  rules: {
-    'polaris/coverage': {
-      colors: [
-        {
-          'color-named': 'never'
-          'color-no-hex': true,
-        },
-        {message: 'Please use a Polaris color token: https://polaris.shopify.com/tokens/colors'},
-      ],
-    },
-  },
-}
-```
-
-Example failure message:
-
-```diff
-- Unexpected named color "red" (color-named)
-+ Unexpected named color "red" (color-named) Please use a Polaris color token
-```
-
-Set a custom message on the `message` property in the [Stylelint rule config's secondary options](https://stylelint.io/user-guide/configure/#message) if supported. This message is appended to the default rule message instead of the generic category message when provided.
-
-```js
-module.exports = {
-  rules: {
-    'polaris/coverage': {
-      layout: [
-        {
-          'property-disallowed-list': [
-            ['position'],
-            {message: 'Please use the Polaris "Sticky" component'},
-          ],
-        },
-        {message: 'Please use a Polaris layout component'},
-      ],
-    },
-  },
-};
-```
-
-Example failure message:
-
-```diff
-- Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use a Polaris layout component
-+ Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use the Polaris "Sticky" component
-```
-
-### Tophat `stylelint-polaris` updates in `polaris-react`
-
-> Open your terminal to the root of the `polaris` monorepo:
-
-1. Install and symlink dependencies
-
-```sh
-yarn install
-```
-
-2. Build `@shopify/polaris` dependencies, but not `@shopify/polaris` itself
-
-```sh
-yarn build -- --filter=@shopify/polaris^...
-```
-
-> Note: Remove the `^` character if you do want to build `@shopify/polaris`
-
-3. Run `stylelint` in `polaris-react`
-
-All files
-
-```sh
-yarn turbo run lint:styles --filter=@shopify/polaris
-```
-
-Specific file
-
-```sh
-yarn run stylelint path/to/component.scss
-
-// yarn run stylelint polaris-react/src/components/TopBar/TopBar.scss
-```
-
-## Rules
-
-[Conventions](#conventions) |
-[Colors](#colors) |
-[Motion](#motion) |
-[Typography](#typography) |
-[Shape](#shape) |
-[Spacing](#shape) |
-[Depth](#depth) |
-[Media queries](#media-queries) |
-[Z-index](#z-index) |
-[Layout](#layout) |
-[Legacy](#legacy)
-
-### Conventions
-
-#### conventions/custom-property-allowed-list
-
-Allows definition of custom properties not prefixed with `--p-`, `--pc-`, or `--polaris-version-`.
-
-```diff
-root: {
-// Don't
-- --p-animation-name-drag-handle-pulse: osui_drag-handle-pulse;
-// Do
-+ --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse;
-};
-```
-
-Flags declaration property values using `--p-*` that are not valid Polaris tokens.
-
-```diff
-// Don't
-- font-size: var(--p-fontsize-200);
-// Do
-+ font-size: var(--p-font-size-200);
-```
-
-Flags declaration property values using private `--pc-*` tokens.
-
-The following token value is considered a problem:
-
-```diff
-// Don't
-- background: var(--pc-button-color-depressed);
-// Do
-+ background: var(--p-action-secondary-depressed);
-```
-
-### Colors
-
-#### colors/color-named
-
-```diff
-// Don't
-- color: black;
-- fill: dimgray;
-// Do
-+ color: var(--p-text);
-+ fill: var(--p-icon)
-```
-
-#### colors/color-no-hex
-
-```diff
-// Don't
-- color: #202223;
-- fill: #5c5f62;
-// Do
-+ color: var(--p-text);
-+ fill: var(--p-icon)
-```
-
-#### colors/declaration-property-value-disallowed-list
-
-```diff
-// Don't
-- background: black;
-- opacity: 0.15;
-// Do
-+ background: var(--p-hint-from-direct-light);
-```
-
-#### colors/function-disallowed-list
-
-```diff
-// Don't
-- color: rgb(140, 145, 150);
-- background: color('hover');
-// Do
-+ color: var(--p-text-disabled);
-+ background: var(--p-action-secondary-hovered-dark);
-```
-
-#### colors/at-rule-disallowed-list
-
-```diff
-// Don't
-- fill: recolor-icon(--p-text-subdued);
-// Do
-+ fill: var(--p-icon-subdued);
-```
-
-#### colors/global-disallowed-list
-
-Disallows use of legacy custom properties.
-
-```diff
-// Don't
-- border: var(--p-override-transparent);
-// Do
-+ border: transparent;
-```
-
-Disallows use of legacy mixin map data.
-
-```diff
-- @type map $filter-palette-data: $polaris-color-filters;
-```
-
-### Motion
-
-#### motion/function-disallowed-list
-
-```diff
-
-```
-
-#### motion/declaration-property-unit-disallowed-list
-
-```diff
-// Don't
-- transition-duration: 200ms;
-// Do
-+ transition-duration: var(--p-duration-200);
-```
-
-#### motion/at-rule-disallowed-list
-
-```diff
-
-```
-
-#### motion/global-disallowed-list
-
-```diff
-
-```
-
-### Typography
-
-#### typography/declaration-property-value-disallowed-list
-
-```diff
-
-```
-
-#### typography/declaration-property-unit-disallowed-list
-
-```diff
-// Don't
-- font-size: 12px;
-- line-height: 1.5rem
-// Do
-+ font-size: var(--p-font-size-75);
-+ line-height: var(--p-font-line-height-3);
-```
-
-#### typography/function-disallowed-list
-
-```diff
-
-```
-
-#### typography/at-rule-disallowed-list
-
-```diff
-
-```
-
-#### typography/property-disallowed-list
-
-```diff
-
-```
-
-### Shape
-
-#### shape/declaration-property-value-disallowed-list
-
-```diff
-
-```
-
-#### shape/declaration-property-unit-disallowed-list
-
-```diff
-// Don't
-- border-width: 2px;
-- border-radius: 0.5rem;
-// Do
-+ border-width: var(--p-border-width-2);
-+ border-radius: var(--p-border-radius-2);
-```
-
-#### shape/function-disallowed-list
-
-```diff
-
-```
-
-#### shape/at-rule-disallowed-list
-
-```diff
-
-```
-
-#### shape/property-disallowed-list
-
-```diff
-
-```
-
-### Spacing
-
-#### spacing/declaration-property-value-disallowed-list
-
-```diff
-
-```
-
-#### spacing/declaration-property-unit-disallowed-list
-
-```diff
-// Don't
-- gap: 2px;
-- margin: 12px  0;
-// Do
-+ gap: var(--p-space-05);
-+ margin: var(--p-space-3) 0;
-```
-
-#### spacing/function-disallowed-list
-
-```diff
-
-```
-
-#### spacing/at-rule-disallowed-list
-
-```diff
-
-```
-
-#### spacing/property-disallowed-list
-
-```diff
-
-```
-
-### Depth
-
-#### depth/declaration-property-unit-disallowed-list
-
-Try to use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
-
-```diff
-// Don't
-- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05);
-// Do
-+ box-shadow: var(--p-shadow-card);
-```
-
-#### depth/function-disallowed-list
-
-Try to use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
-
-```diff
-// Don't
-- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
-// Do
-+ box-shadow: var(--p-shadow-base);
-```
-
-#### depth/global-disallowed-list
-
-Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
-
-```diff
-// Don't
-- box-shadow: var(--p-card-shadow);
-// Do
-+ box-shadow: var(--p-shadow-card);
-```
-
-#### depth/property-disallowed-list
-
-Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow.
-
-```diff
-// Don't
-- text-shadow: 2px 2px #ff0000;
-```
-
-### Media queries
-
-#### media-queries/function-disallowed-list
-
-Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables.
-
-```diff
-// Don't
-- @include breakpoint-after(layout-width(page-with-nav)) {}
-// Do
-+ @media (min-width: var(--p-breakpoints-md)) {}
-```
-
-#### media-queries/media-queries-allowed-list
-
-Try to use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) before creating your own custom styles.
-
-```diff
-// Don't
-- @include @media #{$my-var} {}
-// Do
-+ @include @media #{$p-breakpoints-sm-up} {}
-```
-
-#### media-queries/at-rule-disallowed-list
-
-Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables.
-
-```diff
-// Don't
-- @include breakpoint-before(layout-width(page-with-nav)) {}
-// Do
-+ @media (max-width: var(--p-breakpoints-md)) {}
-```
-
-### Z-Index
-
-#### z-index/declaration-property-value-allowed-list
-
-Try to use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
-
-```diff
-// Don't
-- z-index: 1;
-// Do
-+ z-index: var(--p-z-1);
-```
-
-#### z-index/function-disallowed-list
-
-Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
-
-```diff
-// Don't
-- z-index: z-index(content);
-// Do
-+ z-index: var(--p-z-1);
-```
-
-#### z-index/global-disallowed-list
-
-Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
-
-```diff
-// Don't
-- z-index(toast, $fixed-element-stacking-order);
-// Do
-+ z-index: var(--p-z-1);
-```
-
-### Layout
-
-#### layout/declaration-property-value-disallowed-list
-
-There are many ways to use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. Please explore the layout components before writing custom styles.
-
-```diff
-// Don't
-- width: 100%;
-// Do
-+ <Stack />
-```
-
-#### layout/function-disallowed-list
-
-Use hard coded pixel or rem values for `width` and `height` instead of legacy mixins/variables or spacing tokens.
-
-```diff
-// Don't
-- height: top-bar-height();
-// Do
-+ height: 56px;
-```
-
-#### layout/at-rule-disallowed-list
-
-Instead of using a legacy mixin, try and use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. If what you need isn't possible, either use the mixin's contents or consider contributing to an existing Polaris component.
-
-```diff
-// Don't
-- @include print-hidden;
-// Do
-+ @media print {
-+   display: none;
-+ }
-```
-
-#### layout/property-disallowed-list
-
-There are many ways to use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. Please explore the layout components before writing custom styles.
-
-```diff
-// Don't
-- display: grid;
-// Do
-+ <Columns />
-```
-
-#### layout/global-disallowed-list
-
-If [Polaris components](https://polaris.shopify.com/components) cannot be composed to create the styles you need, consider contributing to an existing Polaris component before creating custom styles.
-
-```diff
-// Don't
-- height: var(--p-choice-size);
-// Do
-+ <Checkbox />
-```
-
-### Legacy
-
-#### legacy/at-rule-disallowed-list
-
-If [Polaris components](https://polaris.shopify.com/components) cannot be composed to create the styles you need, consider contributing to an existing Polaris component before creating custom styles.
-
-```diff
-// Don't
-- @include unstyled-button;
-// Do
-+ <UnstyledButton />
-```
-
-#### legacy/function-disallowed-list
-
-```diff
-// Don't
-- @include available-names
-```
-
-#### legacy/global-disallowed-list
-
-Use [Polaris tokens](https://polaris.shopify.com/tokens) when possible. Otherwise use hard coded pixel or rem values instead of legacy mixins/variables.
-
-```diff
-// Don't
-- left: -1 * $timeline-border-width;
-// Do
-+ left: calc(-1 * var(--p-space-1));
-```
diff --git a/polaris.shopify.com/content/tools/index.md b/polaris.shopify.com/content/tools/index.md
new file mode 100644
index 00000000000..67b75db39f7
--- /dev/null
+++ b/polaris.shopify.com/content/tools/index.md
@@ -0,0 +1,6 @@
+---
+title: Tools
+description: Extensions, plugins, and other tools to help you use Polaris to build Admin experiences.
+icon: ToolsMajor
+order: 9
+---
diff --git a/polaris.shopify.com/pages/[...slug].tsx b/polaris.shopify.com/pages/[...slug].tsx
index 0eb4497d11f..770210e4ece 100644
--- a/polaris.shopify.com/pages/[...slug].tsx
+++ b/polaris.shopify.com/pages/[...slug].tsx
@@ -77,7 +77,7 @@ const catchAllTemplateExcludeList = [
   '/design',
   '/content',
   '/patterns',
-  '/tooling',
+  '/tools',
   '/tokens',
   '/sandbox',
 ];
diff --git a/polaris.shopify.com/pages/tooling.tsx b/polaris.shopify.com/pages/tools.tsx
similarity index 85%
rename from polaris.shopify.com/pages/tooling.tsx
rename to polaris.shopify.com/pages/tools.tsx
index 5d2942545bc..9aa00156412 100644
--- a/polaris.shopify.com/pages/tooling.tsx
+++ b/polaris.shopify.com/pages/tools.tsx
@@ -2,10 +2,10 @@ import FoundationsPage from '../src/components/FoundationsPage';
 import {FoundationsProps} from '../src/components/FoundationsPage/FoundationsPage';
 import {getStaticPropsForFoundations} from '../src/utils/foundations';
 
-const SECTION = 'tooling';
+const SECTION = 'tools';
 
 const FoundationsCategory = (props: FoundationsProps) => (
-  <FoundationsPage {...props} />
+  <FoundationsPage showTOC {...props} />
 );
 
 export const getStaticProps = getStaticPropsForFoundations(SECTION);

From e172a9af7f906154e8479a8556a254a57b26d75b Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 17:31:12 -0500
Subject: [PATCH 2/9] Add support for nested content folders

---
 .../tools/stylelint-polaris/conventions.md    |  51 +++++
 .../content/tools/stylelint-polaris/index.md  | 195 ++++++++++++++++++
 polaris.shopify.com/pages/[...slug].tsx       |   1 +
 .../FoundationsPage/FoundationsPage.tsx       |  10 +-
 polaris.shopify.com/src/utils/foundations.ts  |  12 +-
 5 files changed, 263 insertions(+), 6 deletions(-)
 create mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
 create mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/index.md

diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md b/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
new file mode 100644
index 00000000000..ee7b47472dd
--- /dev/null
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
@@ -0,0 +1,51 @@
+---
+title: Conventions
+description: Stylelint Polaris convention rules
+icon: WandMajor
+keywords:
+  - stylelint
+  - dev tools
+  - developer tools
+  - tools
+  - tooling
+  - development
+  - plugin
+  - rules
+  - conventions
+  - linter
+  - linting
+  - css
+---
+
+## custom-property-allowed-list
+
+Allows definition of custom properties not prefixed with `--p-`, `--pc-`, or `--polaris-version-`.
+
+```diff
+root: {
+// Don't
+- --p-animation-name-drag-handle-pulse: osui_drag-handle-pulse;
+// Do
++ --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse;
+};
+```
+
+Flags declaration property values using `--p-*` that are not valid Polaris tokens.
+
+```diff
+// Don't
+- font-size: var(--p-fontsize-200);
+// Do
++ font-size: var(--p-font-size-200);
+```
+
+Flags declaration property values using private `--pc-*` tokens.
+
+The following token value is considered a problem:
+
+```diff
+// Don't
+- background: var(--pc-button-color-depressed);
+// Do
++ background: var(--p-action-secondary-depressed);
+```
diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/index.md b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
new file mode 100644
index 00000000000..64666407f17
--- /dev/null
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
@@ -0,0 +1,195 @@
+---
+title: Stylelint Polaris
+description: A configuration of Stylelint rules that promote adoption and track coverage of the Polaris design system in consuming apps.
+icon: WandMajor
+hideChildren: true
+keywords:
+  - stylelint
+  - dev tools
+  - developer tools
+  - tools
+  - tooling
+  - development
+  - plugin
+  - rules
+  - linter
+  - linting
+  - css
+---
+
+## Installation
+
+```sh
+yarn -D @shopify/stylelint-polaris stylelint
+```
+
+> Note: `stylelint-polaris` requires a peer dependency of `stylelint@>=14.15.0`
+
+[Source code](https://github.com/Shopify/polaris/tree/main/stylelint-polaris)
+
+## Usage
+
+Extend `@shopify/stylelint-polaris` in your [Stylelint config](https://stylelint.io/user-guide/configure/). Example in `package.json`
+
+```json
+{
+  "stylelint": {
+    "extends": ["@shopify/stylelint-polaris"]
+  }
+}
+```
+
+> IMPORTANT: `@shopify/stylelint-polaris` must be added to the end of the `extends` array
+
+### Run the linter
+
+```sh
+npx stylelint '**/*.{css,scss}'
+```
+
+### Run the linter and autofix failures
+
+```sh
+npx stylelint --fix '**/*.{css,scss}'
+```
+
+### Ignoring existing failures
+
+Enabling the linter could result in a large amount of warnings and errors in existing codebases. It is important to fix as many failures upfront as possible, but that shouldn't block the linter from being added. The [styles-insert-stylelint-disable](https://github.com/Shopify/polaris/tree/main/polaris-migrator#v10) migration inserts [ignore comments](https://stylelint.io/user-guide/ignore-code/) so that enabling `stylelint-polaris` can be unblocked.
+
+The migration will insert comments as follows:
+
+```diff
++ // stylelint-disable-next-line -- generated by polaris-migrator DO NOT COPY
+padding: 1rem;
+```
+
+Run the following command substituting `<path>` with a glob pattern of files to run against:
+
+```sh
+npx @shopify/polaris-migrator styles-insert-stylelint-disable <path>
+```
+
+## Development
+
+### Add new rules
+
+1. Navigate to the root [`stylelint-polaris` config](index.js)
+1. Locate the `stylelint-polaris/coverage` options
+1. Identify the appropriate category for the new rule
+1. Insert the rule using standard Stylelint [rule configurations](https://stylelint.io/user-guide/configure#rules)
+1. Add documentation for the rule with examples of code that will be reported as a problem and code that will fix the problem
+1. The title should be the category + the stylelint rule name, for example `### colors/color-named`
+
+```js
+module.exports = {
+  rules: {
+    'polaris/coverage': {
+      colors: {...}, // Standard Stylelint rules config
+      layout: {...}, // Standard Stylelint rules config
+      motion: {
+        'new-rule': 'new-rule-options',
+      },
+    },
+  },
+};
+```
+
+### Build custom rules
+
+1. Refer to the [Writing plugins](https://stylelint.io/developer-guide/plugins) guide of the Stylelint documentation
+1. Create your rule in the [plugins](plugins) directory
+1. Validate your plugin with [tests](https://github.com/stylelint/jest-preset-stylelint#usage) (reference sibling plugins for examples)
+1. Refer to the [Add new rules](#add-new-rules) section to add your custom rule to the `stylelint-polaris` config
+
+### Add custom messages
+
+Custom messages are surfaced in the command line, CI, and supported editors along side the default `stylelint` rule messages. They are added to the root level config and aim to provide more insight on how to resolve rule violations.
+
+In a majority of cases, the default rule messages are clear and concise. However, they don't always guide developers to a desired outcome. Thus, there are two mechanisms we suggest for improving and providing custom rule messages:
+
+Set a generic custom message on the `message` property of the secondary options of a given `stylelint-polaris/coverage` category. This message is appended to the default rule message and we expect will cover most cases.
+
+```js
+module.exports = {
+  rules: {
+    'polaris/coverage': {
+      colors: [
+        {
+          'color-named': 'never'
+          'color-no-hex': true,
+        },
+        {message: 'Please use a Polaris color token: https://polaris.shopify.com/tokens/colors'},
+      ],
+    },
+  },
+}
+```
+
+Example failure message:
+
+```diff
+- Unexpected named color "red" (color-named)
++ Unexpected named color "red" (color-named) Please use a Polaris color token
+```
+
+Set a custom message on the `message` property in the [Stylelint rule config's secondary options](https://stylelint.io/user-guide/configure/#message) if supported. This message is appended to the default rule message instead of the generic category message when provided.
+
+```js
+module.exports = {
+  rules: {
+    'polaris/coverage': {
+      layout: [
+        {
+          'property-disallowed-list': [
+            ['position'],
+            {message: 'Please use the Polaris "Sticky" component'},
+          ],
+        },
+        {message: 'Please use a Polaris layout component'},
+      ],
+    },
+  },
+};
+```
+
+Example failure message:
+
+```diff
+- Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use a Polaris layout component
++ Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use the Polaris "Sticky" component
+```
+
+### Tophat `stylelint-polaris` updates in `polaris-react`
+
+> Open your terminal to the root of the `polaris` monorepo:
+
+1. Install and symlink dependencies
+
+```sh
+yarn install
+```
+
+2. Build `@shopify/polaris` dependencies, but not `@shopify/polaris` itself
+
+```sh
+yarn build -- --filter=@shopify/polaris^...
+```
+
+> Note: Remove the `^` character if you do want to build `@shopify/polaris`
+
+3. Run `stylelint` in `polaris-react`
+
+All files
+
+```sh
+yarn turbo run lint:styles --filter=@shopify/polaris
+```
+
+Specific file
+
+```sh
+yarn run stylelint path/to/component.scss
+
+// yarn run stylelint polaris-react/src/components/TopBar/TopBar.scss
+```
diff --git a/polaris.shopify.com/pages/[...slug].tsx b/polaris.shopify.com/pages/[...slug].tsx
index 770210e4ece..f3b5df49e25 100644
--- a/polaris.shopify.com/pages/[...slug].tsx
+++ b/polaris.shopify.com/pages/[...slug].tsx
@@ -93,6 +93,7 @@ export const getStaticPaths: GetStaticPaths = async () => {
   const globPath = [
     path.resolve(process.cwd(), 'content/*.md'),
     path.resolve(process.cwd(), 'content/**/*.md'),
+    path.resolve(process.cwd(), 'content/**/**/*.md'),
   ];
   const paths = globby
     .sync(globPath)
diff --git a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
index 9d85b9bb8c2..2a15ab193d0 100644
--- a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
+++ b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
@@ -10,6 +10,7 @@ export interface FoundationsProps {
   title: string;
   description: string;
   items: Item[];
+  showTOC?: boolean;
 }
 
 interface Item extends GridItemProps {
@@ -17,12 +18,17 @@ interface Item extends GridItemProps {
   icon: string;
 }
 
-function FoundationsPage({title, description, items}: FoundationsProps) {
+function FoundationsPage({
+  title,
+  description,
+  items,
+  showTOC = false,
+}: FoundationsProps) {
   return (
     <div className={styles.FoundationsPage}>
       <PageMeta description={description} />
 
-      <Page showTOC={false}>
+      <Page showTOC={showTOC}>
         <Longform>
           <h1>{title}</h1>
           <p>{description}</p>
diff --git a/polaris.shopify.com/src/utils/foundations.ts b/polaris.shopify.com/src/utils/foundations.ts
index 4c23b115467..56557fee4ca 100644
--- a/polaris.shopify.com/src/utils/foundations.ts
+++ b/polaris.shopify.com/src/utils/foundations.ts
@@ -18,13 +18,17 @@ export const getStaticPropsForFoundations = (category: string) => {
       frontMatter: {description},
     }: MarkdownFile = parseMarkdown(markdown);
 
-    const filePattern = path.resolve(process.cwd(), `content/${category}/*.md`);
+    const globPath = [
+      path.resolve(process.cwd(), `content/${category}/*.md`),
+      path.resolve(process.cwd(), `content/${category}/**/index.md`),
+    ];
+
+    const itemPaths = globby.sync(globPath);
 
     let items: FoundationsProps['items'] = [];
-    const markdownFilePaths = await globby(filePattern);
 
-    markdownFilePaths
-      .filter((path) => !path.endsWith(`index.md`))
+    itemPaths
+      .filter((path) => !path.endsWith(`content/${category}/index.md`))
       .forEach((markdownFilePath) => {
         if (fs.existsSync(markdownFilePath)) {
           const markdown = fs.readFileSync(markdownFilePath, 'utf-8');

From cc185524b460f20136daf0d990047116a10a1b1d Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 17:31:43 -0500
Subject: [PATCH 3/9] Add Polaris for VS Code doc

---
 .../content/tools/polaris-for-vscode.md       | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 polaris.shopify.com/content/tools/polaris-for-vscode.md

diff --git a/polaris.shopify.com/content/tools/polaris-for-vscode.md b/polaris.shopify.com/content/tools/polaris-for-vscode.md
new file mode 100644
index 00000000000..cdacb4820d8
--- /dev/null
+++ b/polaris.shopify.com/content/tools/polaris-for-vscode.md
@@ -0,0 +1,28 @@
+---
+title: Polaris for VS Code
+description: Official VS Code extension for building with the Shopify Polaris Design System
+icon: HintMajor
+---
+
+![Demo of Polaris for VS Code tokens autocomplete](https://github.com/Shopify/polaris/blob/main/polaris-for-vscode/docs/polaris-for-vscode-preview.gif?raw=true)
+
+## Features
+
+### Design Token Autocomplete
+
+Get code autocomplete suggestions for the [Polaris Design Tokens](https://polaris.shopify.com/tokens/colors#navigation)
+
+- 🗄️ Automatically works for CSS and Sass files
+- 🔍 Preview design token values in autocomplete description
+- 🎨 Color previews for all `color` tokens
+- 🥇 Relevant code completions based on the current line of code
+
+## How to use
+
+Install the [Polaris for VS Code extension](https://marketplace.visualstudio.com/items?itemName=Shopify.polaris-for-vscode). Once enabled, the extension will automatically run in any CSS and Sass files.
+
+To trigger the token autocomplete feature:
+
+1. Open a CSS or Sass file from your project
+2. Start typing the CSS property you want to set, for example: `color:`
+3. Type the extension trigger characters: `--`. This will bring up the relevant autocomplete tokens associated with the CSS property typed.

From 334e9e8b68173c27b49f0ec50f65fd928e5ceecd Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 18:17:57 -0500
Subject: [PATCH 4/9] revert unnecessary TOC option on FoundationsPage
 component

---
 .../content/tools/stylelint-polaris/index.md       | 14 ++++++++++++++
 polaris.shopify.com/pages/tools.tsx                |  2 +-
 .../components/FoundationsPage/FoundationsPage.tsx | 10 ++--------
 3 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/index.md b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
index 64666407f17..3212e8c74d4 100644
--- a/polaris.shopify.com/content/tools/stylelint-polaris/index.md
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
@@ -193,3 +193,17 @@ yarn run stylelint path/to/component.scss
 
 // yarn run stylelint polaris-react/src/components/TopBar/TopBar.scss
 ```
+
+## Rules
+
+[Conventions](/tools/stylelint-polaris/conventions) |
+[Colors](/tools/stylelint-polaris/colors) |
+[Motion](/tools/stylelint-polaris/motion) |
+[Typography](/tools/stylelint-polaris/typography) |
+[Shape](/tools/stylelint-polaris/shape) |
+[Spacing](/tools/stylelint-polaris/shape) |
+[Depth](/tools/stylelint-polaris/depth) |
+[Media queries](/tools/stylelint-polaris/media-queries) |
+[Z-index](/tools/stylelint-polaris/z-index) |
+[Layout](/tools/stylelint-polaris/layout) |
+[Legacy](/tools/stylelint-polaris/conventions)
diff --git a/polaris.shopify.com/pages/tools.tsx b/polaris.shopify.com/pages/tools.tsx
index 9aa00156412..61bc37bd62a 100644
--- a/polaris.shopify.com/pages/tools.tsx
+++ b/polaris.shopify.com/pages/tools.tsx
@@ -5,7 +5,7 @@ import {getStaticPropsForFoundations} from '../src/utils/foundations';
 const SECTION = 'tools';
 
 const FoundationsCategory = (props: FoundationsProps) => (
-  <FoundationsPage showTOC {...props} />
+  <FoundationsPage {...props} />
 );
 
 export const getStaticProps = getStaticPropsForFoundations(SECTION);
diff --git a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
index 2a15ab193d0..9d85b9bb8c2 100644
--- a/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
+++ b/polaris.shopify.com/src/components/FoundationsPage/FoundationsPage.tsx
@@ -10,7 +10,6 @@ export interface FoundationsProps {
   title: string;
   description: string;
   items: Item[];
-  showTOC?: boolean;
 }
 
 interface Item extends GridItemProps {
@@ -18,17 +17,12 @@ interface Item extends GridItemProps {
   icon: string;
 }
 
-function FoundationsPage({
-  title,
-  description,
-  items,
-  showTOC = false,
-}: FoundationsProps) {
+function FoundationsPage({title, description, items}: FoundationsProps) {
   return (
     <div className={styles.FoundationsPage}>
       <PageMeta description={description} />
 
-      <Page showTOC={showTOC}>
+      <Page showTOC={false}>
         <Longform>
           <h1>{title}</h1>
           <p>{description}</p>

From 2d7d70f842374b8209a876e90ea2a884fc2e6438 Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 18:21:58 -0500
Subject: [PATCH 5/9] fix name change missed

---
 .../FoundationsThumbnail/FoundationsThumbnail.module.scss       | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/polaris.shopify.com/src/components/FoundationsThumbnail/FoundationsThumbnail.module.scss b/polaris.shopify.com/src/components/FoundationsThumbnail/FoundationsThumbnail.module.scss
index 5c56ca2b8c6..48cad07e23e 100644
--- a/polaris.shopify.com/src/components/FoundationsThumbnail/FoundationsThumbnail.module.scss
+++ b/polaris.shopify.com/src/components/FoundationsThumbnail/FoundationsThumbnail.module.scss
@@ -26,7 +26,7 @@
     background: var(--decorative-3);
   }
 
-  &[data-category='tooling'] {
+  &[data-category='tools'] {
     background: var(--decorative-4);
   }
 }

From 3b7f47ba214fc4ffce6e6411af2c6f5f8f60af9b Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 18:39:40 -0500
Subject: [PATCH 6/9] fix URL for nested tooling items

---
 polaris.shopify.com/src/utils/foundations.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/polaris.shopify.com/src/utils/foundations.ts b/polaris.shopify.com/src/utils/foundations.ts
index 56557fee4ca..3cb6e674535 100644
--- a/polaris.shopify.com/src/utils/foundations.ts
+++ b/polaris.shopify.com/src/utils/foundations.ts
@@ -23,7 +23,9 @@ export const getStaticPropsForFoundations = (category: string) => {
       path.resolve(process.cwd(), `content/${category}/**/index.md`),
     ];
 
-    const itemPaths = globby.sync(globPath);
+    const itemPaths = globby
+      .sync(globPath)
+      .filter((path) => !path.endsWith(`content/${category}/index.md`));
 
     let items: FoundationsProps['items'] = [];
 
@@ -37,6 +39,7 @@ export const getStaticPropsForFoundations = (category: string) => {
 
           const url = markdownFilePath
             .replace(`${process.cwd()}/content`, '')
+            .replace('/index', '')
             .replace(/\.md$/, '');
 
           const headings = (readme.match(/\n## [^\n]+/gi) || []).map(

From db2ed5d098024e7b4246131ef5b12ec05e14615c Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloe.rice@shopify.com>
Date: Wed, 11 Jan 2023 19:12:09 -0500
Subject: [PATCH 7/9] add depth catg

---
 .../tools/stylelint-polaris/conventions.md    |  5 +-
 .../content/tools/stylelint-polaris/depth.md  | 68 +++++++++++++++++++
 2 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/depth.md

diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md b/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
index ee7b47472dd..e38787518a9 100644
--- a/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
@@ -1,7 +1,6 @@
 ---
-title: Conventions
-description: Stylelint Polaris convention rules
-icon: WandMajor
+title: Convention rules
+description: Coming soon...
 keywords:
   - stylelint
   - dev tools
diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/depth.md b/polaris.shopify.com/content/tools/stylelint-polaris/depth.md
new file mode 100644
index 00000000000..d3e27077732
--- /dev/null
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/depth.md
@@ -0,0 +1,68 @@
+---
+title: Depth rules
+description:
+  <p>{Insert why depth consistency impacts merchant [wayfinding, etc]}</p>
+
+  <p>If you've found that merchants benefit from an additional layer of visual hierarchy not represented in the current depth tokens, we'd love to learn more.</p>
+
+  <p>Contribute a <a href="https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md">feature proposal issue</a> or pull request in <a href="https://github.com/Shopify/polaris">GitHub</a> to share context and implement a proposed improvement or addition to Polaris. Start a GitHub <a href="https://github.com/Shopify/polaris/discussions/6750">discussion</a> if community collaboration is needed to find a solution.</p>
+keywords:
+  - stylelint
+  - dev tools
+  - developer tools
+  - tools
+  - tooling
+  - development
+  - plugin
+  - rules
+  - depth
+  - shadows
+  - linter
+  - linting
+  - css
+---
+
+## declaration-property-unit-disallowed-list
+
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) before custom shadows.
+
+```diff
+// Do
++ box-shadow: var(--p-shadow-card);
+
+// Don't
+- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05);
+```
+
+## function-disallowed-list
+
+Use [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of custom shadows.
+
+```diff
+// Do
++ box-shadow: var(--p-shadow-base);
+
+// Don't
+- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+```
+
+## global-disallowed-list
+
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of legacy mixins/variables.
+
+```diff
+// Do
++ box-shadow: var(--p-shadow-card);
+
+// Don't
+- box-shadow: var(--p-card-shadow);
+```
+
+## property-disallowed-list
+
+Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow.
+
+```diff
+// Don't
+- text-shadow: 2px 2px #ff0000;
+```

From 8c12427dcb21da37df1f96f0b272b65d365c0039 Mon Sep 17 00:00:00 2001
From: Sophie Schneider <thesophieschneider@gmail.com>
Date: Thu, 12 Jan 2023 20:28:16 +0000
Subject: [PATCH 8/9] add 3rd level of page nesting to the nav

---
 .../content/tools/stylelint-polaris/index.md     |  2 +-
 polaris.shopify.com/scripts/gen-cache-json.mjs   |  2 ++
 .../src/components/Frame/Frame.module.scss       | 16 ++++++++++++++++
 .../src/components/Frame/Frame.tsx               | 14 ++++++++++----
 polaris.shopify.com/src/types.ts                 |  4 ++--
 5 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/index.md b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
index 3212e8c74d4..7d7b0ba109e 100644
--- a/polaris.shopify.com/content/tools/stylelint-polaris/index.md
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
@@ -2,7 +2,7 @@
 title: Stylelint Polaris
 description: A configuration of Stylelint rules that promote adoption and track coverage of the Polaris design system in consuming apps.
 icon: WandMajor
-hideChildren: true
+collapseChildren: true
 keywords:
   - stylelint
   - dev tools
diff --git a/polaris.shopify.com/scripts/gen-cache-json.mjs b/polaris.shopify.com/scripts/gen-cache-json.mjs
index 31f817bc0bc..f6faf9ac3b7 100644
--- a/polaris.shopify.com/scripts/gen-cache-json.mjs
+++ b/polaris.shopify.com/scripts/gen-cache-json.mjs
@@ -20,6 +20,7 @@ const genNavJson = (mardownFiles) => {
       order,
       newSection,
       hideChildren,
+      collapseChildren,
       color,
       url,
       status,
@@ -36,6 +37,7 @@ const genNavJson = (mardownFiles) => {
       slug: url || `/${slug}`,
       newSection,
       hideChildren,
+      collapseChildren,
       color: color ? color.replace(/\\/g, '') : undefined,
       status,
     });
diff --git a/polaris.shopify.com/src/components/Frame/Frame.module.scss b/polaris.shopify.com/src/components/Frame/Frame.module.scss
index 9cfa06bc397..1469d6f6753 100644
--- a/polaris.shopify.com/src/components/Frame/Frame.module.scss
+++ b/polaris.shopify.com/src/components/Frame/Frame.module.scss
@@ -116,6 +116,22 @@ $breakpointNav: $breakpointTablet;
           }
         }
       }
+
+      > ul > li > ul > li {
+        > .NavItem {
+          font-size: var(--font-size-200);
+          letter-spacing: var(--letter-spacing-300);
+          padding-left: 3rem;
+
+          > a {
+            color: var(--text);
+          }
+
+          &.isCurrent > a {
+            color: var(--primary);
+          }
+        }
+      }
     }
   }
 
diff --git a/polaris.shopify.com/src/components/Frame/Frame.tsx b/polaris.shopify.com/src/components/Frame/Frame.tsx
index f59826eed4d..606fa647958 100644
--- a/polaris.shopify.com/src/components/Frame/Frame.tsx
+++ b/polaris.shopify.com/src/components/Frame/Frame.tsx
@@ -218,15 +218,21 @@ function NavItem({
             const navAriaId = `nav-${id}`;
             const segments = asPath.slice(1).split('/');
             const keyAndLevelMatchUrl = !!(segments[level] === key);
+            const removeParams = (path: string) => path.replace(/\?.+$/gi, '');
+            const isCurrent = removeParams(asPath) === child.slug;
+
+            const currentInChildren = Object.values(child.children || []).some(
+              (c) => c.slug === removeParams(asPath),
+            );
+            const autoExpanded =
+              keyAndLevelMatchUrl &&
+              (!child.collapseChildren || currentInChildren);
             const manuallyExpandedStatus = manuallyExpandedSections[key];
             const isExpanded =
               manuallyExpandedStatus === undefined
-                ? keyAndLevelMatchUrl
+                ? autoExpanded
                 : manuallyExpandedStatus;
 
-            const removeParams = (path: string) => path.replace(/\?.+$/gi, '');
-            const isCurrent = removeParams(asPath) === child.slug;
-
             return (
               <li
                 key={child.slug}
diff --git a/polaris.shopify.com/src/types.ts b/polaris.shopify.com/src/types.ts
index 90c8f206df6..8de4196d1bf 100644
--- a/polaris.shopify.com/src/types.ts
+++ b/polaris.shopify.com/src/types.ts
@@ -144,7 +144,7 @@ export interface NavJSON {
   };
 }
 
-export interface NavItem {
+export interface NavItem extends NavJSON {
   title?: string;
   description?: string;
   slug?: string;
@@ -152,7 +152,7 @@ export interface NavItem {
   icon?: string;
   color?: string;
   hideChildren?: false;
+  collapseChildren?: false;
   newSection?: true;
   status?: Status;
-  children?: NavJSON;
 }

From b7dd02f0955cb9d4e6c95cf3491cac225ef971e0 Mon Sep 17 00:00:00 2001
From: Chloe Rice <chloerice@users.noreply.github.com>
Date: Thu, 12 Jan 2023 16:12:41 -0500
Subject: [PATCH 9/9] Stylelint Polaris doc prototype: individual rule pages
 (#8035)

<img width="1512" alt="Screenshot 2023-01-11 at 7 57 36 PM"
src="https://user-images.githubusercontent.com/18447883/211951260-472b87a7-2538-4acd-b82e-2345e462eb80.png">
---
 .../tools/stylelint-polaris/conventions.md    |  50 --
 .../content/tools/stylelint-polaris/depth.md  |  68 ---
 .../content/tools/stylelint-polaris/index.md  | 468 +++++++++++++++++-
 ...claration-property-unit-disallowed-list.md |  34 ++
 polaris.shopify.com/pages/[...slug].tsx       |   1 +
 polaris.shopify.com/src/utils/foundations.ts  |   1 +
 6 files changed, 493 insertions(+), 129 deletions(-)
 delete mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
 delete mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/depth.md
 create mode 100644 polaris.shopify.com/content/tools/stylelint-polaris/rules/depth-declaration-property-unit-disallowed-list.md

diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md b/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
deleted file mode 100644
index e38787518a9..00000000000
--- a/polaris.shopify.com/content/tools/stylelint-polaris/conventions.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: Convention rules
-description: Coming soon...
-keywords:
-  - stylelint
-  - dev tools
-  - developer tools
-  - tools
-  - tooling
-  - development
-  - plugin
-  - rules
-  - conventions
-  - linter
-  - linting
-  - css
----
-
-## custom-property-allowed-list
-
-Allows definition of custom properties not prefixed with `--p-`, `--pc-`, or `--polaris-version-`.
-
-```diff
-root: {
-// Don't
-- --p-animation-name-drag-handle-pulse: osui_drag-handle-pulse;
-// Do
-+ --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse;
-};
-```
-
-Flags declaration property values using `--p-*` that are not valid Polaris tokens.
-
-```diff
-// Don't
-- font-size: var(--p-fontsize-200);
-// Do
-+ font-size: var(--p-font-size-200);
-```
-
-Flags declaration property values using private `--pc-*` tokens.
-
-The following token value is considered a problem:
-
-```diff
-// Don't
-- background: var(--pc-button-color-depressed);
-// Do
-+ background: var(--p-action-secondary-depressed);
-```
diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/depth.md b/polaris.shopify.com/content/tools/stylelint-polaris/depth.md
deleted file mode 100644
index d3e27077732..00000000000
--- a/polaris.shopify.com/content/tools/stylelint-polaris/depth.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Depth rules
-description:
-  <p>{Insert why depth consistency impacts merchant [wayfinding, etc]}</p>
-
-  <p>If you've found that merchants benefit from an additional layer of visual hierarchy not represented in the current depth tokens, we'd love to learn more.</p>
-
-  <p>Contribute a <a href="https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md">feature proposal issue</a> or pull request in <a href="https://github.com/Shopify/polaris">GitHub</a> to share context and implement a proposed improvement or addition to Polaris. Start a GitHub <a href="https://github.com/Shopify/polaris/discussions/6750">discussion</a> if community collaboration is needed to find a solution.</p>
-keywords:
-  - stylelint
-  - dev tools
-  - developer tools
-  - tools
-  - tooling
-  - development
-  - plugin
-  - rules
-  - depth
-  - shadows
-  - linter
-  - linting
-  - css
----
-
-## declaration-property-unit-disallowed-list
-
-Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) before custom shadows.
-
-```diff
-// Do
-+ box-shadow: var(--p-shadow-card);
-
-// Don't
-- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05);
-```
-
-## function-disallowed-list
-
-Use [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of custom shadows.
-
-```diff
-// Do
-+ box-shadow: var(--p-shadow-base);
-
-// Don't
-- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
-```
-
-## global-disallowed-list
-
-Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of legacy mixins/variables.
-
-```diff
-// Do
-+ box-shadow: var(--p-shadow-card);
-
-// Don't
-- box-shadow: var(--p-card-shadow);
-```
-
-## property-disallowed-list
-
-Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow.
-
-```diff
-// Don't
-- text-shadow: 2px 2px #ff0000;
-```
diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/index.md b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
index 7d7b0ba109e..16826f2611e 100644
--- a/polaris.shopify.com/content/tools/stylelint-polaris/index.md
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/index.md
@@ -196,14 +196,460 @@ yarn run stylelint path/to/component.scss
 
 ## Rules
 
-[Conventions](/tools/stylelint-polaris/conventions) |
-[Colors](/tools/stylelint-polaris/colors) |
-[Motion](/tools/stylelint-polaris/motion) |
-[Typography](/tools/stylelint-polaris/typography) |
-[Shape](/tools/stylelint-polaris/shape) |
-[Spacing](/tools/stylelint-polaris/shape) |
-[Depth](/tools/stylelint-polaris/depth) |
-[Media queries](/tools/stylelint-polaris/media-queries) |
-[Z-index](/tools/stylelint-polaris/z-index) |
-[Layout](/tools/stylelint-polaris/layout) |
-[Legacy](/tools/stylelint-polaris/conventions)
+### Conventions
+
+#### conventions/custom-property-allowed-list
+
+Allows definition of custom properties not prefixed with `--p-`, `--pc-`, or `--polaris-version-`.
+
+```diff
+root: {
+// Don't
+- --p-animation-name-drag-handle-pulse: osui_drag-handle-pulse;
+// Do
++ --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse;
+};
+```
+
+Flags declaration property values using `--p-*` that are not valid Polaris tokens.
+
+```diff
+// Don't
+- font-size: var(--p-fontsize-200);
+// Do
++ font-size: var(--p-font-size-200);
+```
+
+Flags declaration property values using private `--pc-*` tokens.
+
+The following token value is considered a problem:
+
+```diff
+// Don't
+- background: var(--pc-button-color-depressed);
+// Do
++ background: var(--p-action-secondary-depressed);
+```
+
+### Colors
+
+#### colors/color-named
+
+```diff
+// Don't
+- color: black;
+- fill: dimgray;
+// Do
++ color: var(--p-text);
++ fill: var(--p-icon)
+```
+
+#### colors/color-no-hex
+
+```diff
+// Don't
+- color: #202223;
+- fill: #5c5f62;
+// Do
++ color: var(--p-text);
++ fill: var(--p-icon)
+```
+
+#### colors/declaration-property-value-disallowed-list
+
+```diff
+// Don't
+- background: black;
+- opacity: 0.15;
+// Do
++ background: var(--p-hint-from-direct-light);
+```
+
+#### colors/function-disallowed-list
+
+```diff
+// Don't
+- color: rgb(140, 145, 150);
+- background: color('hover');
+// Do
++ color: var(--p-text-disabled);
++ background: var(--p-action-secondary-hovered-dark);
+```
+
+#### colors/at-rule-disallowed-list
+
+```diff
+// Don't
+- fill: recolor-icon(--p-text-subdued);
+// Do
++ fill: var(--p-icon-subdued);
+```
+
+#### colors/global-disallowed-list
+
+Disallows use of legacy custom properties.
+
+```diff
+// Don't
+- border: var(--p-override-transparent);
+// Do
++ border: transparent;
+```
+
+Disallows use of legacy mixin map data.
+
+```diff
+- @type map $filter-palette-data: $polaris-color-filters;
+```
+
+### Motion
+
+#### motion/function-disallowed-list
+
+```diff
+
+```
+
+#### motion/declaration-property-unit-disallowed-list
+
+```diff
+// Don't
+- transition-duration: 200ms;
+// Do
++ transition-duration: var(--p-duration-200);
+```
+
+#### motion/at-rule-disallowed-list
+
+```diff
+
+```
+
+#### motion/global-disallowed-list
+
+```diff
+
+```
+
+### Typography
+
+#### typography/declaration-property-value-disallowed-list
+
+```diff
+
+```
+
+#### typography/declaration-property-unit-disallowed-list
+
+```diff
+// Don't
+- font-size: 12px;
+- line-height: 1.5rem
+// Do
++ font-size: var(--p-font-size-75);
++ line-height: var(--p-font-line-height-3);
+```
+
+#### typography/function-disallowed-list
+
+```diff
+
+```
+
+#### typography/at-rule-disallowed-list
+
+```diff
+
+```
+
+#### typography/property-disallowed-list
+
+```diff
+
+```
+
+### Shape
+
+#### shape/declaration-property-value-disallowed-list
+
+```diff
+
+```
+
+#### shape/declaration-property-unit-disallowed-list
+
+```diff
+// Don't
+- border-width: 2px;
+- border-radius: 0.5rem;
+// Do
++ border-width: var(--p-border-width-2);
++ border-radius: var(--p-border-radius-2);
+```
+
+#### shape/function-disallowed-list
+
+```diff
+
+```
+
+#### shape/at-rule-disallowed-list
+
+```diff
+
+```
+
+#### shape/property-disallowed-list
+
+```diff
+
+```
+
+### Spacing
+
+#### spacing/declaration-property-value-disallowed-list
+
+```diff
+
+```
+
+#### spacing/declaration-property-unit-disallowed-list
+
+```diff
+// Don't
+- gap: 2px;
+- margin: 12px  0;
+// Do
++ gap: var(--p-space-05);
++ margin: var(--p-space-3) 0;
+```
+
+#### spacing/function-disallowed-list
+
+```diff
+
+```
+
+#### spacing/at-rule-disallowed-list
+
+```diff
+
+```
+
+#### spacing/property-disallowed-list
+
+```diff
+
+```
+
+### Depth
+
+_{Insert why depth consistency impacts merchant [wayfinding, etc]}_
+
+Have you found that merchants benefit from {an additional layer of visual hierarchy that's not in the depth tokens? We'd love to learn more. You can jumpstart a contribution to Polaris in GitHub by:
+
+- Starting a [discussion](https://github.com/Shopify/polaris/discussions/6750) to collaborate with the community to find a solution
+- Submitting a [feature proposal issue](https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md) to share context on your suggestion
+- Drafting a [pull request](https://github.com/Shopify/polaris/pulls) with your proposed improvement or addition
+
+#### depth/declaration-property-unit-disallowed-list
+
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows.
+
+```diff
+// Don't
+- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05);
+// Do
++ box-shadow: var(--p-shadow-card);
+```
+
+#### depth/function-disallowed-list
+
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows.
+
+```diff
+// Don't
+- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+// Do
++ box-shadow: var(--p-shadow-base);
+```
+
+#### depth/global-disallowed-list
+
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
+
+```diff
+// Don't
+- box-shadow: var(--p-card-shadow);
+// Do
++ box-shadow: var(--p-shadow-card);
+```
+
+#### depth/property-disallowed-list
+
+Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow.
+
+```diff
+// Don't
+- text-shadow: 2px 2px #ff0000;
+```
+
+### Media queries
+
+#### media-queries/function-disallowed-list
+
+Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables.
+
+```diff
+// Don't
+- @include breakpoint-after(layout-width(page-with-nav)) {}
+// Do
++ @media (min-width: var(--p-breakpoints-md)) {}
+```
+
+#### media-queries/media-queries-allowed-list
+
+Try to use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) before creating your own custom styles.
+
+```diff
+// Don't
+- @include @media #{$my-var} {}
+// Do
++ @include @media #{$p-breakpoints-sm-up} {}
+```
+
+#### media-queries/at-rule-disallowed-list
+
+Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables.
+
+```diff
+// Don't
+- @include breakpoint-before(layout-width(page-with-nav)) {}
+// Do
++ @media (max-width: var(--p-breakpoints-md)) {}
+```
+
+### Z-Index
+
+#### z-index/declaration-property-value-allowed-list
+
+Try to use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
+
+```diff
+// Don't
+- z-index: 1;
+// Do
++ z-index: var(--p-z-1);
+```
+
+#### z-index/function-disallowed-list
+
+Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
+
+```diff
+// Don't
+- z-index: z-index(content);
+// Do
++ z-index: var(--p-z-1);
+```
+
+#### z-index/global-disallowed-list
+
+Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables.
+
+```diff
+// Don't
+- z-index(toast, $fixed-element-stacking-order);
+// Do
++ z-index: var(--p-z-1);
+```
+
+### Layout
+
+#### layout/declaration-property-value-disallowed-list
+
+There are many ways to use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. Please explore the layout components before writing custom styles.
+
+```diff
+// Don't
+- width: 100%;
+// Do
++ <Stack />
+```
+
+#### layout/function-disallowed-list
+
+Use hard coded pixel or rem values for `width` and `height` instead of legacy mixins/variables or spacing tokens.
+
+```diff
+// Don't
+- height: top-bar-height();
+// Do
++ height: 56px;
+```
+
+#### layout/at-rule-disallowed-list
+
+Instead of using a legacy mixin, try and use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. If what you need isn't possible, either use the mixin's contents or consider contributing to an existing Polaris component.
+
+```diff
+// Don't
+- @include print-hidden;
+// Do
++ @media print {
++   display: none;
++ }
+```
+
+#### layout/property-disallowed-list
+
+There are many ways to use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. Please explore the layout components before writing custom styles.
+
+```diff
+// Don't
+- display: grid;
+// Do
++ <Columns />
+```
+
+#### layout/global-disallowed-list
+
+If [Polaris components](https://polaris.shopify.com/components) cannot be composed to create the styles you need, consider contributing to an existing Polaris component before creating custom styles.
+
+```diff
+// Don't
+- height: var(--p-choice-size);
+// Do
++ <Checkbox />
+```
+
+### Legacy
+
+#### legacy/at-rule-disallowed-list
+
+If [Polaris components](https://polaris.shopify.com/components) cannot be composed to create the styles you need, consider contributing to an existing Polaris component before creating custom styles.
+
+```diff
+// Don't
+- @include unstyled-button;
+// Do
++ <UnstyledButton />
+```
+
+#### legacy/function-disallowed-list
+
+```diff
+// Don't
+- @include available-names
+```
+
+#### legacy/global-disallowed-list
+
+Use [Polaris tokens](https://polaris.shopify.com/tokens) when possible. Otherwise use hard coded pixel or rem values instead of legacy mixins/variables.
+
+```diff
+// Don't
+- left: -1 * $timeline-border-width;
+// Do
++ left: calc(-1 * var(--p-space-1));
+```
diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/rules/depth-declaration-property-unit-disallowed-list.md b/polaris.shopify.com/content/tools/stylelint-polaris/rules/depth-declaration-property-unit-disallowed-list.md
new file mode 100644
index 00000000000..78bbfd50846
--- /dev/null
+++ b/polaris.shopify.com/content/tools/stylelint-polaris/rules/depth-declaration-property-unit-disallowed-list.md
@@ -0,0 +1,34 @@
+---
+title: depth/declaration-property-unit-disallowed-list
+description: Disallows box-shadow declarations with hard coded px, rem, or em units
+keywords:
+  - stylelint
+  - dev tools
+  - developer tools
+  - tools
+  - tooling
+  - development
+  - plugin
+  - rules
+  - depth
+  - shadows
+  - linter
+  - linting
+  - css
+---
+
+Use a [Polaris depth token](https://polaris.shopify.com/tokens/depth) instead of a custom box-shadow.
+
+```diff
+// Do
++ box-shadow: var(--p-shadow-card);
+
+// Don't
+- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05);
+```
+
+Have you found that merchants benefit from an additional layer of visual hierarchy that's not in the depth tokens? We'd love to learn more. You can jumpstart a contribution to Polaris in GitHub by:
+
+- Starting a [discussion](https://github.com/Shopify/polaris/discussions/6750) to collaborate with the community to find a solution
+- Submitting a [feature proposal issue](https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md) to share context on your suggestion
+- Drafting a [pull request](https://github.com/Shopify/polaris/pulls) with your proposed improvement or addition
diff --git a/polaris.shopify.com/pages/[...slug].tsx b/polaris.shopify.com/pages/[...slug].tsx
index f3b5df49e25..3788924bdc0 100644
--- a/polaris.shopify.com/pages/[...slug].tsx
+++ b/polaris.shopify.com/pages/[...slug].tsx
@@ -94,6 +94,7 @@ export const getStaticPaths: GetStaticPaths = async () => {
     path.resolve(process.cwd(), 'content/*.md'),
     path.resolve(process.cwd(), 'content/**/*.md'),
     path.resolve(process.cwd(), 'content/**/**/*.md'),
+    path.resolve(process.cwd(), 'content/**/**/**/*.md'),
   ];
   const paths = globby
     .sync(globPath)
diff --git a/polaris.shopify.com/src/utils/foundations.ts b/polaris.shopify.com/src/utils/foundations.ts
index 3cb6e674535..cefc6d13296 100644
--- a/polaris.shopify.com/src/utils/foundations.ts
+++ b/polaris.shopify.com/src/utils/foundations.ts
@@ -21,6 +21,7 @@ export const getStaticPropsForFoundations = (category: string) => {
     const globPath = [
       path.resolve(process.cwd(), `content/${category}/*.md`),
       path.resolve(process.cwd(), `content/${category}/**/index.md`),
+      path.resolve(process.cwd(), `content/${category}/**/**/*.md`),
     ];
 
     const itemPaths = globby