2nd/10_Wiki/Topics/Frontend/Shopify Polaris.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-shopify-polaris	Shopify Polaris	10_Wiki/Topics	verified	self	Polaris Shopify Design System Polaris React	none	A	0.9	applied	design-system shopify polaris react admin-ui		2026-05-10	pending	language framework TypeScript React + @shopify/polaris

Shopify Polaris

매 한 줄

"매 Polaris 는 Shopify 의 admin/merchant facing design system". React component lib + design guidelines + token (SCSS/CSS vars) 패키지. App Bridge 와 함께 매 Shopify embedded app 의 standard UI. 2026 기준 v13 — modular import + CSS vars + dark mode 지원, App Bridge React 4.x 와 통합.

매 핵심

매 패키지

• @shopify/polaris: React components + tokens
• @shopify/app-bridge-react: 매 embedded app 의 host iframe API
• @shopify/polaris-icons: SVG icon set

매 design principles

• "Built for Shopify" — merchant 가 Shopify Admin 에 익숙
• Workflow centric (page · card · resource list · index table)
• Accessibility first (WCAG 2.1 AA)

매 응용

1. Shopify Admin custom app (embedded).
2. Shopify storefront builder tools.
3. Internal merchant ops dashboards.

💻 패턴

App provider + i18n

import { AppProvider, Page, Card, Text } from "@shopify/polaris";
import "@shopify/polaris/build/esm/styles.css";
import enTranslations from "@shopify/polaris/locales/en.json";

export default function App() {
  return (
    <AppProvider i18n={enTranslations}>
      <Page title="Orders">
        <Card>
          <Text as="h2" variant="headingMd">매 orders here</Text>
        </Card>
      </Page>
    </AppProvider>
  );
}

Embedded app with App Bridge

// app/providers.tsx
"use client";
import { AppProvider } from "@shopify/polaris";
import { Provider as AppBridge } from "@shopify/app-bridge-react";
import enTranslations from "@shopify/polaris/locales/en.json";

export function Providers({
  children, apiKey, host,
}: { children: React.ReactNode; apiKey: string; host: string }) {
  return (
    <AppBridge config={{ apiKey, host, forceRedirect: true }}>
      <AppProvider i18n={enTranslations}>{children}</AppProvider>
    </AppBridge>
  );
}

IndexTable (Shopify-style data grid)

import { IndexTable, Text, useIndexResourceState } from "@shopify/polaris";

const orders = [
  { id: "1001", customer: "Alice", total: "$120" },
  { id: "1002", customer: "Bob", total: "$45" },
];

export function OrdersTable() {
  const { selectedResources, allResourcesSelected, handleSelectionChange } =
    useIndexResourceState(orders);

  return (
    <IndexTable
      resourceName={{ singular: "order", plural: "orders" }}
      itemCount={orders.length}
      selectedItemsCount={allResourcesSelected ? "All" : selectedResources.length}
      onSelectionChange={handleSelectionChange}
      headings={[{ title: "Order" }, { title: "Customer" }, { title: "Total" }]}
    >
      {orders.map((o, i) => (
        <IndexTable.Row id={o.id} key={o.id} position={i}
          selected={selectedResources.includes(o.id)}>
          <IndexTable.Cell><Text as="span" fontWeight="bold">#{o.id}</Text></IndexTable.Cell>
          <IndexTable.Cell>{o.customer}</IndexTable.Cell>
          <IndexTable.Cell>{o.total}</IndexTable.Cell>
        </IndexTable.Row>
      ))}
    </IndexTable>
  );
}

Form + Banner + Toast

import { Form, FormLayout, TextField, Button, Banner, Frame, Toast } from "@shopify/polaris";
import { useState, useCallback } from "react";

export function ProductForm() {
  const [name, setName] = useState("");
  const [error, setError] = useState<string>();
  const [toast, setToast] = useState(false);

  const submit = useCallback(async () => {
    if (!name.trim()) { setError("매 name required"); return; }
    setError(undefined);
    // await api.create({ name });
    setToast(true);
  }, [name]);

  return (
    <Frame>
      {error && <Banner tone="critical">{error}</Banner>}
      <Form onSubmit={submit}>
        <FormLayout>
          <TextField label="Product name" value={name} onChange={setName} autoComplete="off" />
          <Button submit variant="primary">매 Save</Button>
        </FormLayout>
      </Form>
      {toast && <Toast content="매 Saved" onDismiss={() => setToast(false)} />}
    </Frame>
  );
}

Resource picker via App Bridge

"use client";
import { useAppBridge } from "@shopify/app-bridge-react";
import { Button } from "@shopify/polaris";

export function PickProduct() {
  const shopify = useAppBridge();

  async function open() {
    const selected = await shopify.resourcePicker({ type: "product", multiple: true });
    if (selected) console.log("picked", selected);
  }

  return <Button onClick={open}>매 Choose products</Button>;
}

Navigation

import { Frame, Navigation } from "@shopify/polaris";
import { HomeIcon, OrderIcon, ProductIcon } from "@shopify/polaris-icons";

export function Shell({ children }: { children: React.ReactNode }) {
  const nav = (
    <Navigation location="/">
      <Navigation.Section
        items={[
          { url: "/", label: "Home", icon: HomeIcon },
          { url: "/orders", label: "Orders", icon: OrderIcon, badge: "12" },
          { url: "/products", label: "Products", icon: ProductIcon },
        ]}
      />
    </Navigation>
  );
  return <Frame navigation={nav}>{children}</Frame>;
}

Polaris tokens in custom CSS

.custom-card {
  background: var(--p-color-bg-surface);
  color: var(--p-color-text);
  padding: var(--p-space-400);
  border-radius: var(--p-border-radius-200);
}

Server Action with Polaris UI feedback

"use client";
import { Button, Toast, Frame } from "@shopify/polaris";
import { useState, useTransition } from "react";
import { syncProducts } from "./actions";

export function SyncButton() {
  const [pending, start] = useTransition();
  const [done, setDone] = useState(false);

  return (
    <Frame>
      <Button
        loading={pending}
        onClick={() => start(async () => { await syncProducts(); setDone(true); })}
      >매 Sync</Button>
      {done && <Toast content="매 Synced" onDismiss={() => setDone(false)} />}
    </Frame>
  );
}

매 결정 기준

상황	Approach
Shopify embedded app	Polaris + App Bridge
Public storefront	Hydrogen (다른 stack)
Non-Shopify admin	shadcn/ui or other DS
Shopify ecosystem reuse	Polaris (familiarity)

기본값: Shopify embedded app → Polaris v13 + App Bridge React 4.x. Storefront 는 Hydrogen.

🔗 Graph

• 부모: Design System
• 변형: shadcn/ui

🤖 LLM 활용

언제: Shopify embedded app scaffold, Shopify admin tooling, merchant-facing UX. 언제 X: Non-Shopify product (merchant-context UX 가 어색), 매 storefront (Hydrogen).

❌ 안티패턴

• Polaris outside Shopify: 매 brand bleed — non-Shopify product 에 Polaris UI.
• Skipping AppProvider: i18n / theme 깨짐.
• Custom UI for embedded: 매 merchant 혼동 — Polaris 우선.
• Forgetting App Bridge: embedded app 에서 navigation/resource picker 못함.
• Bypassing tokens: hex code 직접 → dark mode 깨짐.

🧪 검증 / 중복

• Verified (polaris.shopify.com docs, App Bridge React docs, 2026).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Shopify Polaris full content