### Install and Run Development Server

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/README.md

Use these commands to install dependencies and start the development server for the project.

```bash
pnpm
pnpm dev
```

--------------------------------

### Install Dependencies and Build Packages

Source: https://github.com/shopify/polaris-react/blob/main/polaris-for-vscode/CONTRIBUTING.md

Run these commands to install all project dependencies and build the necessary packages before starting development.

```sh
pnpm install
pnpm build
```

--------------------------------

### Component Example Structure

Source: https://github.com/shopify/polaris-react/blob/main/documentation/Component READMEs.md

List component examples under the 'Examples' section, providing a description for each example before the code block.

```markdown
---

## Examples

### First example

Example description.

```jsx
<MyComponent aProp={true} />
```
```

--------------------------------

### Manual Token Migration Example

Source: https://github.com/shopify/polaris-react/blob/main/documentation/guides/migrating-from-v10-to-v11.md

This example shows how to stage and format files after performing manual token migrations.

```sh
# Stage all manually migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit manual migrations
git commit -m "Manually migrate X custom properties from Polaris v10 to v11"
```

--------------------------------

### Migrate HorizontalGrid to InlineGrid example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the renaming of the `HorizontalGrid` component to `InlineGrid`.

```diff
- <HorizontalGrid />
+ <InlineGrid />
```

--------------------------------

### Migrate List spacing prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `spacing` prop to `gap` on `List`.

```diff
- <List spacing="loose" />
+ <List gap="loose" />
```

--------------------------------

### Migrate Layout.Section fullWidth prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `fullWidth` prop to `variant="fullWidth"` on `Layout.Section`.

```diff
- <Layout.Section fullWidth>
+ <Layout.Section variant="fullWidth">
```

--------------------------------

### Migrate HorizontalStack to InlineStack example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the renaming of the `HorizontalStack` component to `InlineStack`.

```diff
- <HorizontalStack />
+ <InlineStack />
```

--------------------------------

### Migrate DescriptionList spacing prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `spacing` prop to `gap` for the DescriptionList component.

```diff
- <DescriptionList spacing="loose" />
+ <DescriptionList gap="loose" />
```

--------------------------------

### Migrate Layout.Section oneHalf prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `oneHalf` prop to `variant="oneHalf"` on `Layout.Section`.

```diff
- <Layout.Section oneHalf>
+ <Layout.Section variant="oneHalf">
```

--------------------------------

### Restricting Example to Platforms

Source: https://github.com/shopify/polaris-react/blob/main/documentation/Component READMEs.md

This example demonstrates how to include a React component without platform-specific restrictions.

```jsx
<MyComponent aProp={true} />
```

--------------------------------

### Install Dependencies and Build Workspaces

Source: https://github.com/shopify/polaris-react/blob/main/README.md

This command installs all project dependencies and builds all workspaces within the monorepo. It requires pnpm to be installed.

```shell
pnpm install && pnpm build
```

--------------------------------

### Automated Token Migration Example

Source: https://github.com/shopify/polaris-react/blob/main/documentation/guides/migrating-from-v10-to-v11.md

This example demonstrates the steps for automated token migration, including staging files, formatting, and committing changes.

```sh
# Example migration
npx @shopify/polaris-migrator ...
# Stage all migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit automated migrations
git commit -m "Migrate X custom properties from Polaris v10 to v11"
```

--------------------------------

### Migrate Layout.Section oneThird prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `oneThird` prop to `variant="oneThird"` on `Layout.Section`.

```diff
- <Layout.Section oneThird>
+ <Layout.Section variant="oneThird">
```

--------------------------------

### Install @shopify/polaris-icons with npm

Source: https://github.com/shopify/polaris-react/blob/main/polaris-icons/README.md

Install the @shopify/polaris-icons package as a dependency using npm.

```bash
npm install @shopify/polaris-icons --save
```

--------------------------------

### Install @shopify/polaris-icons with Yarn

Source: https://github.com/shopify/polaris-react/blob/main/polaris-icons/README.md

Install the @shopify/polaris-icons package as a dependency using Yarn.

```bash
yarn add @shopify/polaris-icons
```

--------------------------------

### Migrate Layout.Section secondary prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `secondary` prop to `variant="oneThird"` on `Layout.Section`.

```diff
- <Layout.Section secondary>
+ <Layout.Section variant="oneThird">
```

--------------------------------

### Example Linter Output

Source: https://github.com/shopify/polaris-react/blob/main/stylelint-polaris/plugins/media-query-allowed-list/README.md

Example output from Stylelint indicating invalid media queries found in a SCSS file.

```text
src/components/typography/textContainer/TextContainer.scss
  4:3  ✖  Invalid media query [(min-width: 0px)].              polaris/media-query-allowed-list
  6:5  ✖  Invalid media query [print and (min-width: 0px)].    polaris/media-query-allowed-list
```

--------------------------------

### Migrate ButtonGroup spacing prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `spacing` prop to `gap` for the ButtonGroup component.

```diff
- <ButtonGroup spacing="tight" />
+ <ButtonGroup gap="tight" />
```

--------------------------------

### Stylelint Configuration Example

Source: https://github.com/shopify/polaris-react/blob/main/stylelint-polaris/plugins/media-query-allowed-list/README.md

Example configuration for the 'polaris/media-query-allowed-list' rule in Stylelint, specifying allowed media types, feature names, and SCSS interpolations.

```javascript
const stylelintConfig = {
  rules: {
    'polaris/media-query-allowed-list': {
      allowedMediaTypes: ['print'],
      allowedMediaFeatureNames: ['forced-colors', 'reduced-motion'],
      allowedScssInterpolations: [
        '$p-breakpoints-sm-up',
        '$p-breakpoints-md-up',
      ],
    },
  },
};
```

--------------------------------

### Recommended Component Migration Workflow

Source: https://github.com/shopify/polaris-react/blob/main/documentation/guides/migrating-from-v10-to-v11.md

Example commands for handling automated and manual migrations using git and prettier.

```sh
# Example migration
npx @shopify/polaris-migrator ...
# Stash files with "polaris-migrator:" comments
git stash push $(grep -r -l "polaris-migrator:" $(git ls-files -m))
# Stage all migrated files without "polaris-migrator:" comments
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit automated migrations
git commit -m "Migrate X to Y"

```

```sh
# Bring back the files with "polaris-migrator:" comments
git stash pop

```

```sh
# Stage all manually migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit manual migrations
git commit -m "Manually migrate X to Y"

```

--------------------------------

### Migrate IndexTable.Row subdued prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `subdued` prop to `tone` on `IndexTable.Row`.

```diff
- <IndexTable.Row subdued />
+ <IndexTable.Row tone="subdued" />
```

--------------------------------

### Install Polaris v12

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Install the latest version of Polaris using npm or yarn.

```bash
npm install @shopify/polaris@12
# or
yarn add @shopify/polaris@12
```

--------------------------------

### Install @shopify/polaris-tokens

Source: https://github.com/shopify/polaris-react/blob/main/polaris-tokens/README.md

Use npm to install the Polaris tokens package. This command should be run in your project's root directory.

```bash
npm install @shopify/polaris-tokens
```

--------------------------------

### Migration example: Text color prop

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the direct code change from using the `color` prop to the `tone` prop on the Text component.

```diff
- <Text color="success" />
+ <Text tone="success" />
```

--------------------------------

### Fixing Missing Section Separator

Source: https://github.com/shopify/polaris-react/blob/main/documentation/Component READMEs.md

Add a '---' before the '## Examples' heading to ensure correct parsing of the examples section.

```diff
+ ---
+
  ## Examples
```

--------------------------------

### Migration example: Rename VerticalStack to BlockStack

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the direct code change from using the `VerticalStack` component to `BlockStack`.

```diff
- <VerticalStack />
+ <BlockStack />
```

--------------------------------

### Resource Index Layout Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/patterns/resource-index-layout/variants/default.mdx

This example demonstrates a comprehensive resource index layout using multiple Polaris React components. It includes state management for filters, tabs, and search queries, showcasing interactive features like creating, renaming, duplicating, and deleting views.

```javascript
function IndexFiltersDefault() {
  function disambiguateLabel(key, value) {
    switch (key) {
      case 'type':
        return value.map((val) => `type: ${val}`).join(', ');
      case 'tone':
        return value.map((val) => `tone: ${val}`).join(', ');
      default:
        return value;
    }
  }
  function isEmpty(value) {
    if (Array.isArray(value)) {
      return value.length === 0;
    } else {
      return value === '' || value == null;
    }
  }
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  const [itemStrings, setItemStrings] = useState([
    'All',
    'Active',
    'Draft',
    'Archived',
  ]);
  const deleteView = (index) => {
    const newItemStrings = [...itemStrings];
    newItemStrings.splice(index, 1);
    setItemStrings(newItemStrings);
    setSelected(0);
  };
  const duplicateView = async (name) => {
    setItemStrings([...itemStrings, name]);
    setSelected(itemStrings.length);
    await sleep(1);
    return true;
  };
  const tabs = itemStrings.map((item, index) => ({
    content: item,
    index,
    onAction: () => {},
    id: `${item}-${index}`,
    isLocked: index === 0,
    actions:
      index === 0
        ? []
        : [
            {
              type: 'rename',
              onAction: () => {},
              onPrimaryAction: async (value) => {
                const newItemsStrings = tabs.map((item, idx) => {
                  if (idx === index) {
                    return value;
                  }
                  return item.content;
                });
                await sleep(1);
                setItemStrings(newItemsStrings);
                return true;
              },
            },
            {
              type: 'duplicate',
              onPrimaryAction: async (name) => {
                await sleep(1);
                duplicateView(name);
                return true;
              },
            },
            {
              type: 'edit',
            },
            {
              type: 'delete',
              onPrimaryAction: async () => {
                await sleep(1);
                deleteView(index);
                return true;
              },
            },
          ],
  }));
  const [selected, setSelected] = useState(0);
  const onCreateNewView = async (value) => {
    await sleep(500);
    setItemStrings([...itemStrings, value]);
    setSelected(itemStrings.length);
    return true;
  };
  const sortOptions = [
    {label: 'Product', value: 'product asc', directionLabel: 'Ascending'},
    {label: 'Product', value: 'product desc', directionLabel: 'Descending'},
    {label: 'Status', value: 'tone asc', directionLabel: 'A-Z'},
    {label: 'Status', value: 'tone desc', directionLabel: 'Z-A'},
    {label: 'Type', value: 'type asc', directionLabel: 'A-Z'},
    {label: 'Type', value: 'type desc', directionLabel: 'Z-A'},
    {label: 'Vendor', value: 'vendor asc', directionLabel: 'Ascending'},
    {label: 'Vendor', value: 'vendor desc', directionLabel: 'Descending'},
  ];
  const [sortSelected, setSortSelected] = useState(['product asc']);
  const {mode, setMode} = useSetIndexFiltersMode();
  const onHandleCancel = () => {};
  const onHandleSave = async () => {
    await sleep(1);
    return true;
  };
  const primaryAction =
    selected === 0
      ? {
          type: 'save-as',
          onAction: onCreateNewView,
          disabled: false,
          loading: false,
        }
      : {
          type: 'save',
          onAction: onHandleSave,
          disabled: false,
          loading: false,
        };
  const [tone, setStatus] = useState(undefined);
  const [type, setType] = useState(undefined);
  const [queryValue, setQueryValue] = useState('');
  const handleStatusChange = useCallback((value) => setStatus(value), []);
  const handleTypeChange = useCallback((value) => setType(value), []);
  const handleFiltersQueryChange = useCallback(
    (value) => setQueryValue(value),
    [],
  );
  const handleStatusRemove = useCallback(() => setStatus(undefined), []);
  const handleTypeRemove = useCallback(() => setType(undefined), []);
  const handleQueryValueRemove = useCallback(() => setQueryValue(''), []);
  const handleFiltersClearAll = useCallback(() => {
    handleStatusRemove();
    handleTypeRemove();
    handleQueryValueRemove();
  }, []);

  return (
    <Page
      title="Products"
      primaryAction={primaryAction}
      onCancel={onHandleCancel}
      open={selected === 0 ? false : true}
    >
      <IndexFilters
        sortOptions={sortOptions}
        sortSelected={sortSelected}
        onSortSelected={setSortSelected}
        primaryAction={primaryAction}
        cancelAction={{onAction: onHandleCancel}}
        onClearAll={handleFiltersClearAll}
        sections={[
          {
            title: 'Status',
            items: [
              {label: 'Active', name: 'tone', value: 'active'},
              {label: 'Draft', name: 'tone', value: 'draft'},
              {label: 'Archived', name: 'tone', value: 'archived'},
            ],
            selectedItems: tone,
            onToggle فعال: handleStatusChange,
            onRemove: handleStatusRemove,
          },
          {
            title: 'Type',
            items: [
              {label: 'Physical', name: 'type', value: 'physical'},
              {label: 'Digital', name: 'type', value: 'digital'},
            ],
            selectedItems: type,
            onToggle فعال: handleTypeChange,
            onRemove: handleTypeRemove,
          },
        ]}
        queryValue={queryValue}
        queryPlaceholder="Search products"
        onChange={handleFiltersQueryChange}
        onRemove={handleQueryValueRemove}
      />
      <Card>
        <IndexTable
          itemCount={itemStrings.length}
          headings={[
            {title: 'Name'},
            {title: 'Status'},
            {title: 'Type'},
            {title: 'Vendor'},
          ]}
          selectable={false}
        >
          <IndexTable.Row
            id="1"
            name="Product 1"
            actions={[
              {type: 'edit'},
              {type: 'duplicate'},
              {type: 'delete'},
            ]}
            selected={false}
          >
            <IndexTable.Cell>Product 1</IndexTable.Cell>
            <IndexTable.Cell>
              <Badge tone="success">Active</Badge>
            </IndexTable.Cell>
            <IndexTable.Cell>Digital</IndexTable.Cell>
            <IndexTable.Cell>Super Store</IndexTable.Cell>
          </IndexTable.Row>
          <IndexTable.Row
            id="2"
            name="Product 2"
            actions={[
              {type: 'edit'},
              {type: 'duplicate'},
              {type: 'delete'},
            ]}
            selected={false}
          >
            <IndexTable.Cell>Product 2</IndexTable.Cell>
            <IndexTable.Cell>
              <Badge tone="attention">Draft</Badge>
            </IndexTable.Cell>
            <IndexTable.Cell>Local Store</IndexTable.Cell>
            <IndexTable.Cell>Local Store</IndexTable.Cell>
          </IndexTable.Row>
          <IndexTable.Row
            id="3"
            name="Product 3"
            actions={[
              {type: 'edit'},
              {type: 'duplicate'},
              {type: 'delete'},
            ]}
            selected={false}
          >
            <IndexTable.Cell>Product 3</IndexTable.Cell>
            <IndexTable.Cell>
              <Badge tone="subdued">Archived</Badge>
            </IndexTable.Cell>
            <IndexTable.Cell>Best Buy</IndexTable.Cell>
            <IndexTable.Cell>Best Buy</IndexTable.Cell>
          </IndexTable.Row>
        </IndexTable>
      </Card>
    </Page>
  );
}
```

--------------------------------

### Migration example: TextField borderless prop

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the direct code change from using the `borderless` prop to `variant="borderless"` on the TextField component.

```diff
- <TextField borderless />
+ <TextField variant="borderless" />
```

--------------------------------

### Default FooterHelp example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/navigation/footer-help.mdx

Use to direct merchants to more information related to the product or feature they’re working on. This example shows the default usage.

```tsx
import {FooterHelp} from "@shopify/polaris";

function MyComponent() {
  return (
    <FooterHelp>
      Learn more about{' '}
      <Link url="https://help.shopify.com">shipping zones</Link>
    </FooterHelp>
  );
}
```

--------------------------------

### Resource Details Layout Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/patterns/resource-details-layout/variants/default.mdx

This example demonstrates the Resource Details Layout pattern, showcasing how to arrange content within cards and grids for a product details page. It utilizes various Polaris components to create a structured and responsive layout.

```javascript
function ResourceDetailsLayout() {
  const SkeletonLabel = (props) => {
    return (
      <Box
        background="bg-fill-tertiary"
        minHeight="1rem"
        maxWidth="5rem"
        borderRadius="base"
        {...props}
      />
    );
  };
  return (
    <Page
      backAction={{content: 'Products', url: '/products'}}
      title="Product"
      secondaryActions={[
        {
          content: 'Duplicate',
          icon: DuplicateIcon,
          accessibilityLabel: 'Secondary action label',
          onAction: () => alert('Duplicate action'),
        },
        {
          content: 'Archive',
          icon: ArchiveIcon,
          accessibilityLabel: 'Secondary action label',
          onAction: () => alert('Archive action'),
        },
        {
          content: 'Delete',
          icon: DeleteIcon,
          destructive: true,
          accessibilityLabel: 'Secondary action label',
          onAction: () => alert('Delete action'),
        },
      ]}
      pagination={{
        hasPrevious: true,
        hasNext: true,
      }}
    >
      <InlineGrid columns={{xs: 1, md: '2fr 1fr'}} gap="400">
        <BlockStack gap="400">
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <SkeletonLabel />
              <Box border="divider" borderRadius="base" minHeight="2rem" />
              <SkeletonLabel maxWidth="8rem" />
              <Box border="divider" borderRadius="base" minHeight="20rem" />
            </BlockStack>
          </Card>
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <SkeletonDisplayText size="small" />
              <InlineGrid columns={{xs: 1, md: 2}}>
                <Box border="divider" borderRadius="base" minHeight="10rem" />
                <Box border="divider" borderRadius="base" minHeight="10rem" />
              </InlineGrid>
            </BlockStack>
          </Card>
        </BlockStack>
        <BlockStack gap={{xs: '400', md: '200'}}>
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <SkeletonDisplayText size="small" />
              <Box border="divider" borderRadius="base" minHeight="2rem" />
              <Box>
                <Bleed marginInline={{xs: 400, sm: 500}}>
                  <Divider />
                </Bleed>
              </Box>
              <SkeletonLabel />
              <Divider />
              <SkeletonBodyText />
            </BlockStack>
          </Card>
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <SkeletonLabel />
              <Box border="divider" borderRadius="base" minHeight="2rem" />
              <SkeletonLabel maxWidth="4rem" />
              <Box border="divider" borderRadius="base" minHeight="2rem" />
              <SkeletonLabel />
              <SkeletonBodyText />
            </BlockStack>
          </Card>
        </BlockStack>
      </InlineGrid>
    </Page>
  );
}
```

--------------------------------

### Install Stylelint Polaris

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/tools/stylelint-polaris.mdx

Install the necessary packages for Stylelint Polaris. This includes the main package and Stylelint itself as a development dependency.

```sh
yarn add -D @shopify/stylelint-polaris stylelint
```

--------------------------------

### Migrate Icon color to tone

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the migration of an Icon component from a `color` prop to a `tone` prop.

```diff
- <Icon color="success" />
+ <Icon tone="success" />
```

--------------------------------

### Stylelint Output Example

Source: https://github.com/shopify/polaris-react/blob/main/stylelint-polaris/plugins/custom-property-allowed-list/README.md

Example output from Stylelint indicating violations of the custom property allowed list rule. It highlights unexpected or invalid custom properties.

```text
src/components/typography/textContainer/TextContainer.scss
  4:3  ✖  Unexpected custom property [--p-text-container-spacing].        polaris/custom-property-allowed-list
  6:5  ✖  Invalid custom properties [--p-text-container-spacing].         polaris/custom-property-allowed-list
 15:3  ✖  Unexpected custom property [--p-text-container-spacing].        polaris/custom-property-allowed-list
 19:3  ✖  Unexpected custom property [--p-text-container-spacing].        polaris/custom-property-allowed-list
```

--------------------------------

### Install and Symlink Dependencies

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/tools/stylelint-polaris.mdx

Command to install and symlink dependencies in the polaris monorepo. This is a prerequisite for testing stylelint-polaris updates.

```sh
pnpm install
```

--------------------------------

### Troubleshooting: Syntax Errors in Examples

Source: https://github.com/shopify/polaris-react/blob/main/documentation/Component READMEs.md

This console output highlights a syntax error within a specific example, indicating the location (line and character) of the issue.

```console
🚨 Example "Autocomplete with loading" contains a syntax error in src/components/Autocomplete/README.md: Unexpected token (18:20)
```

--------------------------------

### Migrate ButtonGroup segmented prop example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example demonstrating the migration of the `segmented` prop to `variant="segmented"` for the ButtonGroup component.

```diff
- <ButtonGroup segmented />
+ <ButtonGroup variant="segmented" />
```

--------------------------------

### Migration Example: ProgressBar prop change

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Demonstrates the replacement of the `color` prop with the `tone` prop for the ProgressBar component.

```diff
- <ProgressBar color="success" />
+ <ProgressBar tone="success" />
```

--------------------------------

### Tabs With Actions Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/navigation/tabs.mdx

Use when actions need to be performed on a tab. This example shows how to include action elements alongside tab navigation.

```tsx
import {Tabs} from "@shopify/polaris";

function TabsWithActionsExample() {
  return (
    <Tabs tabs={[
      {content: 'Default', id: 'all'},
      {content: 'With actions', id: 'merchant', actions: [
        {content: 'Primary action',
         onAction: () => console.log('Primary action clicked')
        },
        {content: 'Secondary action',
         onAction: () => console.log('Secondary action clicked')
        }
      ]},
      {content: 'Fitted', id: 'customer'},
    ]} selected={'all'} />
  );
}
```

--------------------------------

### Resource List with All Elements

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/lists/resource-list.mdx

A comprehensive example showcasing most of the available props for the ResourceList component.

```tsx
import {{ ResourceList, Button, Select, ChoiceList, EmptyState }} from "@shopify/polaris";
import {{ useState }} from "react";

const users = [
  {
    id: '1',
    name: 'Mae Jemison',
    email: 'mae@increments.com',
    role: 'Astronaut',
  },
  {
    id: '2',
    name: 'Nicole Mann',
    email: 'nicole@increments.com',
    role: 'Astronaut',
  },
  {
    id: '3',
    name: 'Ellen Ochoa',
    email: 'ellen@increments.com',
    role: 'Engineer',
  },
];

const sortOptions = [
  { label: 'Newest', value: 'newest' },
  { label: 'Oldest', value: 'oldest' },
];

const filterMarkup = (
  <ChoiceList
    title="Filter by role"
    choices={[
      { label: 'Astronaut', value: 'Astronaut' },
      { label: 'Engineer', value: 'Engineer' },
    ]}
    selectedOptions={['Astronaut']}
    onChange={() => {{ console.log('Filter changed') }}
    }
  />
);

const emptyState = (
  <EmptyState
    heading="No resources found"
    image="https://cdn.shopify.com/s/files/1/0262/4042/files/emptystate-files.png"
  >
    <p>Upload your first file here</p>
  </EmptyState>
);

const emptySearchResultState = (
  <EmptyState
    heading="No results found"
    image="https://cdn.shopify.com/s/files/1/0262/4042/files/emptystate-files.png"
  >
    <p>Try changing your search terms or filters.</p>
    <Button onClick={() => console.log('Clear filters clicked')}>Clear filters</Button>
  </EmptyState>
);

function App() {{
  const [selectedItems, setSelectedItems] = useState<string[]>([]);
  const [sort, setSort] = useState('newest');

  const handleSortChange = (value: string) => {{
    setSort(value);
  }};

  const promotedBulkActions = [
    {{
      content: 'Add tags',
      onAction: () => console.log('Promoted bulk action: Add tags'),
    }},
  ];

  const bulkActions = [
    {{
      content: 'Mark as unread',
      onAction: () => console.log('Bulk action: Mark as unread'),
    }},
  ];

  const sortComponent = (
    <Select
      label="Sort by"
      options={sortOptions}
      value={sort}
      onChange={handleSortChange}
    />
  );

  return (
    <ResourceList
      resourceName={{ singular: 'user', plural: 'users' }}
      items={users.map((user) => ({{ ...user, id: user.id }}))}
      selectedItems={selectedItems}
      onSelectionChange={setSelectedItems}
      promotedBulkActions={promotedBulkActions}
      bulkActions={bulkActions}
      sortComponent={sortComponent}
      filterControl={filterMarkup}
      emptyState={emptyState}
      emptySearchResultState={emptySearchResultState}
      totalItemsCount={100}
      loading
      renderItem={({ id, name, email, role }) => {{
        return (
          <ResourceList.Item
            id={id}
            name={name}
            accessibilityLabel={`View details for ${name}`}
            shortcutActions={[
              {{
                content: 'View details',
                onAction: () => console.log('View details action triggered'),
              }},
            ]}
            persistentActions={[
              {{
                content: 'Edit',
                onAction: () => console.log('Edit action triggered'),
              }},
            ]}
          >
            <p>{{ email }}</p>
            <p>{{ role }}</p>
          </ResourceList.Item>
        );
      }})
    />
  );
}}
```

--------------------------------

### Default AppProvider Usage

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/utilities/app-provider.mdx

AppProvider works by default without any additional options passed to it. This is the most basic setup.

```jsx
import {AppProvider} from '@shopify/polaris';

function App() {
  return <AppProvider>{/* App content */}</AppProvider>;
}
```

--------------------------------

### Migration Example: Modal prop change

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Illustrates the code transformation for replacing the `small` prop with `size='small'` on the Modal component.

```diff
- <Modal small />
+ <Modal size="small" />
```

--------------------------------

### Data Table with All Elements

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/tables/data-table.mdx

Use as a broad example that includes most props available to data table.

```tsx
import {DataTable} from '@shopify/polaris';

function TableWithAllElementsExample() {
  const rows = [
    ['Maple', '9.00', 'Exported'],
    ['Beetroot', '10.00', 'Exported'],
    ['Carrot', '2.00', 'Exported'],
  ];

  return (
    <DataTable
      columnContentTypes={['text', 'numeric', 'text']}
      headings={['Product', 'Revenue', 'Status']}
      rows={rows}
      totalsHeading="Total sales"
      totalsFooterContent={[
        'Total sales',
        '21.00',
        '',
      ]}
    />
  );
}

```

--------------------------------

### Install Polaris React with npm

Source: https://github.com/shopify/polaris-react/blob/main/polaris-react/README.md

Use this command to add the Polaris React library to your project when using npm.

```bash
npm install @shopify/polaris --save
```

--------------------------------

### Install Polaris React with Yarn

Source: https://github.com/shopify/polaris-react/blob/main/polaris-react/README.md

Use this command to add the Polaris React library to your project when using Yarn.

```bash
yarn add @shopify/polaris
```

--------------------------------

### Create New Component

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/README.md

Run this command to quickly scaffold new components within the project.

```bash
pnpm create-component
```

--------------------------------

### Migrate Icon color="highlight" to tone="info"

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the migration of an Icon component from `color="highlight"` to `tone="info"`.

```diff
- <Icon color="highlight" />
- <Icon tone="highlight" />
+ <Icon tone="info" />
```

--------------------------------

### Heading Text Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/typography/text.mdx

Use to create various levels of hierarchy on the page. This example demonstrates a heading.

```tsx
import {Text} from '@shopify/polaris';

function HeadingExample() {
  return (
    <Text variant="headingLg" as="h2">
      Online store dashboard
    </Text>
  );
}
```

--------------------------------

### Component Metadata and Introduction

Source: https://github.com/shopify/polaris-react/blob/main/documentation/Component READMEs.md

Define component metadata using YAML at the beginning of the README, followed by the component name and a brief introduction.

```markdown
---
name: ComponentName
category: Category # for example: “Actions”
keywords:
  - keywords are useful
  - for improving search results
  - in the style guide
---

# ComponentName

Short introduction about the component.
```

--------------------------------

### Migrate Icon with backdrop to Box component

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing how to replace an Icon component with a `backdrop` prop with a Box component, which should be used for backdrops.

```diff
- <Icon source={CirclePlusMinor} color={iconColor} backdrop />
+ <Box background={boxBackground} padding="100" width="28px" borderRadius="full">
+  <Icon source={CirclePlusMinor} color={iconColor} />
+ </Box>
```

--------------------------------

### Text Alignment Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/typography/text.mdx

Use to set text alignment. This example is for demonstration purposes and does not include specific code.

--------------------------------

### Migrate Icon color="warning" to tone="caution"

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the migration of an Icon component from `color="warning"` to `tone="caution"`.

```diff
- <Icon color="warning" />
- <Icon tone="warning" />
+ <Icon tone="caution" />
```

--------------------------------

### Commit Manual Migrations and Format

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Stage all manually migrated files, format them using Prettier, optionally run Stylelint, and then commit the changes.

```bash
# Stage all manually migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Optional: run stylelint if using stylelint-polaris and running migrations on stylesheets
npx stylelint "**/*.{css,scss}"
#  Commit manual migrations
git commit -m "[Manual] Migrate X from Polaris v11 to v12"
```

--------------------------------

### App settings layout example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/patterns/app-settings-layout/variants/default.mdx

Use this layout to organize app settings. It utilizes BlockStack, Card, InlineGrid, and Box components for structure and layout.

```javascript
function AppSettingsLayoutExample() {
  const {smUp} = useBreakpoints();
  return (
    <Page
      divider
      primaryAction={{content: 'View on your store', disabled: true}}
      secondaryActions={[
        {
          content: 'Duplicate',
          accessibilityLabel: 'Secondary action label',
          onAction: () => alert('Duplicate action'),
        },
      ]}>
      <BlockStack gap={{xs: '800', sm: '400'}}>
        <InlineGrid columns={{xs: '1fr', md: '2fr 5fr'}} gap="400">
          <Box
            as="section"
            paddingInlineStart={{xs: 400, sm: 0}}
            paddingInlineEnd={{xs: 400, sm: 0}}>
            <BlockStack gap="400">
              <Text as="h3" variant="headingMd">
                InterJambs
              </Text>
              <Text as="p" variant="bodyMd">
                Interjambs are the rounded protruding bits of your puzzlie piece
              </Text>
            </BlockStack>
          </Box>
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <TextField label="Interjamb style" />
              <TextField label="Interjamb ratio" />
            </BlockStack>
          </Card>
        </InlineGrid>
        {smUp ? <Divider /> : null}
        <InlineGrid columns={{xs: '1fr', md: '2fr 5fr'}} gap="400">
          <Box
            as="section"
            paddingInlineStart={{xs: 400, sm: 0}}
            paddingInlineEnd={{xs: 400, sm: 0}}>
            <BlockStack gap="400">
              <Text as="h3" variant="headingMd">
                Dimensions
              </Text>
              <Text as="p" variant="bodyMd">
                Interjambs are the rounded protruding bits of your puzzlie piece
              </Text>
            </BlockStack>
          </Box>
          <Card roundedAbove="sm">
            <BlockStack gap="400">
              <TextField label="Horizontal" />
              <TextField label="Interjamb ratio" />
            </BlockStack>
          </Card>
        </InlineGrid>
      </BlockStack>
    </Page>
  );
}
```

--------------------------------

### Example Media Query Usage

Source: https://github.com/shopify/polaris-react/blob/main/documentation/guides/migrating-from-v9-to-v10.md

Demonstrates how to use the generated Sass breakpoint variables within media queries for responsive styling.

```scss
@media #{$p-breakpoints-md-up} {/*...*/}
@media #{$p-breakpoints-md-down} {/*...*/}
@media #{$p-breakpoints-md-only} {/*...*/} 
```

--------------------------------

### Align FooterHelp example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/navigation/footer-help.mdx

Control the horizontal alignment of the component using the align prop. This example demonstrates aligning the content to the end.

```tsx
import {FooterHelp, Link} from "@shopify/polaris";

function MyComponent() {
  return (
    <FooterHelp align="end">
      Learn more about{' '}
      <Link url="https://help.shopify.com">shipping zones</Link>
    </FooterHelp>
  );
}
```

--------------------------------

### Body Text Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/typography/text.mdx

Use to create a range of body text. These styles are primarily used within components and blocks of text. This example shows a caption.

```tsx
import {Text} from '@shopify/polaris';

function CaptionExample() {
  return (
    <Text variant="bodySm" as="p">
      Received April 21, 2017
    </Text>
  );
}
```

--------------------------------

### Migration example: Text variant prop (heading4xl)

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the direct code change for updating the Text component's `variant` prop from `heading4xl` to `heading3xl`.

```diff
- <Text variant="heading4xl">
+ <Text variant="heading3xl">
```

--------------------------------

### Migration example: Text variant prop (headingXs)

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx

Example showing the direct code change for updating the Text component's `variant` prop from `headingXs` to `headingSm`.

```diff
- <Text variant="headingXs">
+ <Text variant="headingSm">
```

--------------------------------

### Configure Stylelint with Custom Property Rules

Source: https://github.com/shopify/polaris-react/blob/main/stylelint-polaris/plugins/custom-property-allowed-list/README.md

Example configuration for Stylelint, specifying rules for allowed custom properties and their values. Property keys for `allowedValues` are evaluated in order, from most specific to least specific.

```javascript
const stylelintConfig = {
  rules: {
    'polaris/custom-property-allowed-list': {
      allowedProperties: ['/--pc-.+/'],
      allowedValues: {
        width: ['--p-space-0', '--p-space-100' /* etc... */],
        '/.+/': ['/--pc-.+/', '--p-space-0', '--p-space-100' /* etc... */],
      },
    },
  },
};
```

--------------------------------

### Tabs With Custom Disclosure Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/navigation/tabs.mdx

Use to provide information about the popover contents. This example demonstrates how to implement custom disclosure actions for tabs, typically used for more complex interactions.

```tsx
import {Tabs, Button, Popover, ActionList} from "@shopify/polaris";

function TabsWithCustomDisclosureExample() {
  const actions = [
    {content: 'New single',
     onAction: () => console.log('New single clicked')
    },
    {content: 'New batch',
     onAction: () => console.log('New batch clicked')
    },
    {content: 'Delete collection',
     onAction: () => console.log('Delete collection clicked')
    }
  ];

  return (
    <Tabs tabs={[
      {content: 'Default', id: 'all'},
      {content: 'With custom disclosure',
       disclosure: {
         content: 'Actions',
         activeContent: (
           <Popover
             active
             activator={<Button>
               Actions
             </Button>}
             onClose={() => {}}
           >
             <ActionList items={actions} />
           </Popover>
         )
       },
       id: 'merchant'
      },
      {content: 'Fitted', id: 'customer'},
    ]} selected={'all'} />
  );
}
```

--------------------------------

### Skeleton body text default example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/feedback-indicators/skeleton-body-text.mdx

Use this component to represent a block of content being loaded. For example, you could use it to represent an entire product description card on the product page.

```tsx
import {{ SkeletonBodyText }} from '@shopify/polaris-react';

function MyComponent() {
  return <SkeletonBodyText accessibilityLabel="Product description loading state" lines={4} />;
}
```

--------------------------------

### Implement Focus Ring with Tokens

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/tools/stylelint-polaris/rules/border-at-rule-disallowed-list.mdx

Use Polaris design tokens for focus rings to ensure consistency. This example shows the recommended approach using `outline` and `outline-offset` with token values.

```diff
// Do
+ &:focus {
  + outline: var(--p-border-width-050) solid var(--p-color-border-focus);
  + outline-offset: var(--p-space-050);
+ }
// Don't
- @include focus-ring
```

--------------------------------

### Add New Site Section with Landing Page

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/README.md

Create a new section by adding a directory to `/content` and including an `index.md` file for the landing page.

```bash
├── content
│   ├── your-new-section
│   │   ├── index.md
```

--------------------------------

### Styling Content Tiles with Variants

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/contributing/documentation/creating-layout.mdx

Use Small, Medium, Large, and ExtraLarge components to create tiles for various content types. Apply styles using the 'variant' prop for directives, positive examples, negative examples, cautions, and tips.

```mdx
<Small variant="directive">...</Small>
<Small variant="do">...</Small>
<Small variant="dont">...</Small>
<Small variant="caution">...</Small>
<Small variant="tip">...</Column>
```

--------------------------------

### Resource List with Bulk Actions and Pagination

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/lists/resource-list.mdx

Integrates both bulk actions and pagination, demonstrating how these features work together in a list with many rows.

```tsx
import {{ ResourceList, Button, Pagination }} from "@shopify/polaris";
import {{ useState }} from "react";

const users = Array.from({ length: 50 }, (_, i) => ({
  id: `${i}`,
  name: `User ${i}`,
  email: `user${i}@example.com`,
  role: 'Customer',
}));

function App() {{
  const [selectedItems, setSelectedItems] = useState<string[]>([]);

  const promotedBulkActions = [
    {{
      content: 'Delete',
      onAction: () => console.log('Promoted bulk action: Delete'),
    }},
  ];

  const bulkActions = [
    {{
      content: 'Archive',
      onAction: () => console.log('Bulk action: Archive'),
    }},
  ];

  const paginationComponent = (
    <Pagination
      label="User list 1 - 50 of 100"
      hasNext
      onNext={() => {{ console.log('Next page') }}
      }
      onPrevious={() => {{ console.log('Previous page') }}
      }
    />
  );

  return (
    <ResourceList
      resourceName={{ singular: 'user', plural: 'users' }}
      items={users.map((user) => ({{ ...user, id: user.id }}))}
      selectedItems={selectedItems}
      onSelectionChange={setSelectedItems}
      promotedBulkActions={promotedBulkActions}
      bulkActions={bulkActions}
      paginationComponent={paginationComponent}
      renderItem={({ id, name, email, role }) => {{
        return (
          <ResourceList.Item
            id={id}
            name={name}
            accessibilityLabel={`View details for ${name}`}
          >
            <p>{{ email }}</p>
            <p>{{ role }}</p>
          </ResourceList.Item>
        );
      }})
    />
  );
}}
```

--------------------------------

### Navigation Using Icons

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/internal-only/navigation.mdx

This example shows how to use the shouldResizeIcon prop when using icons.

```tsx
import {Navigation} from "@shopify/polaris";
import {HomeIcon, OrdersIcon, ProductsIcon} from "@shopify/polaris-icons";

function NavigationExample() {
  return (
    <div style={{height: '300px'}}>
      <Navigation location="/">
        <Navigation.Section
          items={[
            {
              label: 'Page one',
              icon: HomeIcon,
              onClick: () => {},
              shouldResizeIcon: true,
            },
            {
              label: 'Page two',
              icon: OrdersIcon,
              onClick: () => {},
              shouldResizeIcon: true,
            },
            {
              label: 'Page three',
              icon: ProductsIcon,
              onClick: () => {},
              shouldResizeIcon: true,
            },
          ]}
        />
      </Navigation>
    </div>
  );
}
```

--------------------------------

### Complete Badge

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/feedback-indicators/badge.mdx

Use to indicate when a given task has been completed, for example, when an order has been fulfilled.

```tsx
import {Badge} from '@shopify/polaris';

function MyComponent() {
  return <Badge progress="complete">Fulfilled</Badge>;
}
```

--------------------------------

### Run VisuallyHidden Component Migration

Source: https://github.com/shopify/polaris-react/blob/main/documentation/guides/migrating-from-v10-to-v11.md

Use this command to migrate the VisuallyHidden component. Replace `<path>` with the target directory.

```sh
npx @shopify/polaris-migrator v10-react-replace-text-components --componentName='VisuallyHidden' <path>
```

--------------------------------

### Combobox Default Example

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/selection-and-input/combobox.mdx

Use when merchants can select one option from a predefined or editable list.

```tsx
import {Combobox, TextField} from "@shopify/polaris";
import {useState, useCallback} from "react";

export default () => {
  const emptyValue = {
    label: "",
    value: "",
  };
  const [selectedValue, setSelectedValue] = useState(emptyValue);
  const [inputValue, setInputValue] = useState("");

  const options = [
    {label: "Pear", value: "pear"},
    {label: "Plum", value: "plum"},
    {label: "Strawberry", value: "strawberry"},
    {label: "Raspberry", value: "raspberry"},
    {label: "Apple", value: "apple"},
    {label: "Grape", value: "grape"},
    {label: "Blueberry", value: "blueberry"},
  ];

  const updateSelectionValue = useCallback(
    (value: string) => {
      setSelectedValue({
        label: value,
        value: value.toLowerCase(),
      });
      setInputValue(value);
    },
    [],
  );

  const handleInputChange = useCallback(
    (value: string) => {
      setInputValue(value);
      // Filter options based on input value
      // For this example, we're not filtering, but in a real app you would
    },
    [],
  );

  const handleOnFocus = useCallback(() => {
    // Potentially show all options when focused
  }, []);

  const comboboxOptions = options.map((option) => (
    <Combobox.Option
      key={option.value}
      value={option.value}
      selected={selectedValue.value === option.value}
      disabled={option.disabled}
    >
      {option.label}
    </Combobox.Option>
  ));

  return (
    <div style={{height: "250px"}}>
      <Combobox
        activator={
          <TextField
            label="Fruit"
            value={inputValue}
            onChange={handleInputChange}
            onFocus={handleOnFocus}
            placeholder="Select a fruit"
            autoComplete="off"
          />
        }
        // @ts-ignore
        onSelect={updateSelectionValue}
        selected={selectedValue.value}
      >
        <Combobox.OptionsList>
          {comboboxOptions}
        </Combobox.OptionsList>
      </Combobox>
    </div>
  );
};
```

--------------------------------

### Navigation with aria-labelledby

Source: https://github.com/shopify/polaris-react/blob/main/polaris.shopify.com/content/components/internal-only/navigation.mdx

This example shows how to add an aria-labelledby to add a hidden label to the `nav` element.

```tsx
import {Navigation} from "@shopify/polaris";
import {HomeIcon, OrdersIcon, ProductsIcon} from "@shopify/polaris-icons";

function NavigationExample() {
  return (
    <div style={{height: '300px'}}>
      <Navigation location="/">
        <Navigation.Section
          items={[
            {
              label: 'Page one',
              icon: HomeIcon,
              onClick: () => {},
            },
            {
              label: 'Page two',
              icon: OrdersIcon,
              onClick: () => {},
            },
          ]}
        />
      </Navigation>
      <span id="nav-label">Main navigation</span>
    </div>
  );
}
```

--------------------------------

### Run Dev Server for Polaris Website

Source: https://github.com/shopify/polaris-react/blob/main/README.md

This command uses turbo to run the 'dev' command for the 'polaris.shopify.com' workspace, starting the Next.js development server for the documentation site.

```shell
pnpm turbo run dev --filter=polaris.shopify.com
```