Stylelint Polaris doc prototype: rule category pages

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
+---

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.

polaris.shopify.com/content/tooling/stylelint-polaris.md → polaris.shopify.com/content/tools/stylelint-polaris/index.md

@@ -2,12 +2,19 @@
 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
+collapseChildren: true
 keywords:
   - stylelint
   - dev tools
+  - developer tools
   - tools
+  - tooling
   - development
   - plugin
+  - rules
+  - linter
+  - linting
+  - css
 ---
 
 ## Installation
@@ -189,18 +196,6 @@ yarn run stylelint path/to/component.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
@@ -449,9 +444,17 @@ Disallows use of legacy mixin map data.
 
 ### 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
 
-Try to use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows.
 
 ```diff
 // Don't
@@ -462,7 +465,7 @@ Try to use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index
 
 #### depth/function-disallowed-list
 
-Try to use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles.
+Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows.
 
 ```diff
 // Don't

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

polaris.shopify.com/pages/[...slug].tsx

@@ -77,7 +77,7 @@ const catchAllTemplateExcludeList = [
   '/design',
   '/content',
   '/patterns',
-  '/tooling',
+  '/tools',
   '/tokens',
   '/sandbox',
 ];
@@ -93,6 +93,8 @@ 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'),
+    path.resolve(process.cwd(), 'content/**/**/**/*.md'),
   ];
   const paths = globby
     .sync(globPath)

polaris.shopify.com/pages/tooling.tsx → polaris.shopify.com/pages/tools.tsx

@@ -2,7 +2,7 @@ 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} />

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,
     });

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);
   }
 }

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);
+          }
+        }
+      }
     }
   }
 

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}

polaris.shopify.com/src/types.ts

@@ -144,15 +144,15 @@ export interface NavJSON {
   };
 }
 
-export interface NavItem {
+export interface NavItem extends NavJSON {
   title?: string;
   description?: string;
   slug?: string;
   order?: number;
   icon?: string;
   color?: string;
   hideChildren?: false;
+  collapseChildren?: false;
   newSection?: true;
   status?: Status;
-  children?: NavJSON;
 }

polaris.shopify.com/src/utils/foundations.ts

@@ -18,13 +18,20 @@ 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`),
+      path.resolve(process.cwd(), `content/${category}/**/**/*.md`),
+    ];
+
+    const itemPaths = globby
+      .sync(globPath)
+      .filter((path) => !path.endsWith(`content/${category}/index.md`));
 
     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');
@@ -33,6 +40,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(