Shopify Polaris Design System

The DataTable component is used to organize and display information from a data set, allowing merchants to compare and analyze details from an entire set.

When to use it:

• To present small amounts of data statically.
• To show sortable data for clarity.
• To display data with pagination, footers, or summary rows.
• To show fixed columns when dealing with many columns.

When NOT to use it:

• Do not use DataTable for an actionable list of items that link to detail pages; use the Resource List component instead.
• Do not use tables for layout purposes.

Web Component equivalent: s-table

Polaris is the design system used to build Shopify admin experiences. It provides a shared language for designers and developers to ensure high-quality merchant experiences. The system consists of:

• Design guidance: Principles and patterns for visual and interaction design.
• Code libraries: Reusable components and tools for implementation.
• Development opinions: Best practices and standards for building within the Shopify ecosystem.
• API documentation: Technical specifications for using the Polaris libraries.

Polaris Migrator provides codemod transformations designed to help you upgrade your Polaris codebase. It automates many of the manual changes required when moving between different versions of the Polaris library.

For detailed instructions on how to use the migrator in your specific project, refer to the official Polaris migrator documentation.

Tophatting (🎩) is the practice of performing manual testing to ensure that changes behave as expected, providing a layer of certainty that automated tests might miss. It is used to catch non-obvious regressions or UI issues that do not trigger console errors.

When to Tophat:

• Adding new features: To verify the feature works as intended.
• Refactoring existing code: To ensure current behavior remains intact.
• Big or potentially breaking changes: Perform a thorough 🎩 covering realistic workflows, including UI, API, or both.

What to test:

• Existing functionality: Especially global changes that might have side effects.
• New functionality: To ensure it meets intended behavior.
• Permutations: Test different flows, states, and conditions.
• Affected areas: If modifying a shared component, test all areas where it is used, not just the intended target.

Callout cards are a pattern used to encourage merchants to take action related to a new feature or opportunity. They are most commonly used in the sales channels section of Shopify.

Best practices for Callout cards:

• Clearly articulate the benefit of the feature and what it does.
• Provide a clear call to action (CTA).
• Target the card to merchants who will most benefit from the feature.
• Make cards dismissible so merchants can remove features they aren't interested in.
• Use illustrations to help communicate the subject or merchant benefit.

An effective error message can be composed of three optional parts:

1. Heading (optional): Clearly states the effect of the error on the merchant and commands immediate attention.
2. Body:
   • If no heading is used, the body must clearly state the effect of the error.
   • It should explain how to fix the issue.
   • It should include a link to help documentation if applicable.
3. CTA (Call to Action) (optional):
   • Should provide a one-step solution.
   • Should take the merchant directly to the location where they can fix the issue.