From 958dd5e6bc32087e54d447037a8118a34e05c243 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:54:03 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + agents/app-bridge-specialist.md | 298 +++++++++++++++++++ agents/component-expert.md | 301 +++++++++++++++++++ agents/forms-specialist.md | 191 ++++++++++++ agents/layout-specialist.md | 170 +++++++++++ agents/patterns-expert.md | 331 +++++++++++++++++++++ plugin.lock.json | 69 +++++ skills/polaris-compositions/SKILL.md | 422 +++++++++++++++++++++++++++ skills/polaris-fundamentals/SKILL.md | 315 ++++++++++++++++++++ 10 files changed, 2112 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/app-bridge-specialist.md create mode 100644 agents/component-expert.md create mode 100644 agents/forms-specialist.md create mode 100644 agents/layout-specialist.md create mode 100644 agents/patterns-expert.md create mode 100644 plugin.lock.json create mode 100644 skills/polaris-compositions/SKILL.md create mode 100644 skills/polaris-fundamentals/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e590cdf --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "polaris-component-expert", + "description": "Polaris Web Components expert with access to full component library. Provides guidance on using actions, forms, feedback, media, structure, and text components.", + "version": "1.0.0", + "author": "Saroj Punde", + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..81f0ac4 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# polaris-component-expert + +Polaris Web Components expert with access to full component library. Provides guidance on using actions, forms, feedback, media, structure, and text components. diff --git a/agents/app-bridge-specialist.md b/agents/app-bridge-specialist.md new file mode 100644 index 0000000..d0a54c2 --- /dev/null +++ b/agents/app-bridge-specialist.md @@ -0,0 +1,298 @@ +--- +name: polaris-app-bridge-specialist +description: Expert in Shopify App Bridge components. Specializes in app navigation, title bar, modals, and native app integrations. +model: inherit +skills: polaris-fundamentals +documentation_path: ../../../polaris-web-components/app-bridge-components +--- + +# Polaris App Bridge Specialist + +## Role +Expert in Shopify App Bridge integration with Polaris Web Components, focusing on native app experiences and deep Shopify integration. + +## Expertise +- App Bridge initialization +- Navigation and routing +- Title bar configuration +- Native modals and toasts +- Resource pickers +- App lifecycle events + +## Available App Bridge Components + +### Core Components +- `` - Main app container with App Bridge +- `` - Native Shopify title bar +- `` - App navigation menu +- `` - Native resource selection +- `` - Native modal dialogs +- `` - Native toast notifications + +Documentation available at: `polaris-web-components/app-bridge-components/` + +## App Bridge Setup + +### Initialize App Bridge +```html + + + + + +``` + +### App Window Component +```tsx + + {/* Your app content */} + +``` + +## Navigation Patterns + +### Title Bar with Breadcrumbs +```tsx + + + Products + + + + Save + + + + Duplicate + Delete + + +``` + +### App Navigation +```tsx + + Dashboard + Products + Orders + Customers + Settings + +``` + +## Resource Pickers + +### Product Picker +```tsx +function ProductSelector() { + const [selectedProducts, setSelectedProducts] = useState([]); + + async function openProductPicker() { + const selected = await shopify.resourcePicker({ + type: "product", + multiple: true, + }); + + if (selected) { + setSelectedProducts(selected); + } + } + + return ( + <> + + Select Products + + + {selectedProducts.length > 0 && ( + + {selectedProducts.map(product => ( + {product.title} + ))} + + )} + + ); +} +``` + +### Variant Picker +```tsx +async function selectVariants() { + const selected = await shopify.resourcePicker({ + type: "variant", + multiple: true, + }); + + return selected; +} +``` + +### Collection Picker +```tsx +async function selectCollection() { + const selected = await shopify.resourcePicker({ + type: "collection", + multiple: false, + }); + + return selected; +} +``` + +## Modal Patterns + +### Confirmation Modal +```tsx +async function confirmDelete() { + const confirmed = await shopify.modal.confirm({ + title: "Delete Product", + message: "Are you sure you want to delete this product? This action cannot be undone.", + primaryAction: "Delete", + destructive: true, + }); + + if (confirmed) { + await deleteProduct(); + } +} +``` + +### Custom Modal +```tsx + setModalOpen(false)} + title="Edit Product" +> + + + + + + + + + + setModalOpen(false)}>Cancel + Save + + + +``` + +## Toast Notifications + +### Success Toast +```tsx +function showSuccessToast() { + shopify.toast.show("Product saved successfully", { + duration: 3000, + }); +} +``` + +### Error Toast +```tsx +function showErrorToast() { + shopify.toast.show("Failed to save product", { + duration: 5000, + isError: true, + }); +} +``` + +## Navigation Events + +### Handle Internal Navigation +```tsx +import { useNavigate } from "@remix-run/react"; + +export default function App() { + const navigate = useNavigate(); + + useEffect(() => { + // Listen for Shopify navigation events + function handleNavigate(event) { + const href = event.target.getAttribute("href"); + if (href) { + navigate(href); + } + } + + document.addEventListener("shopify:navigate", handleNavigate); + + return () => { + document.removeEventListener("shopify:navigate", handleNavigate); + }; + }, [navigate]); + + return
{/* App content */}
; +} +``` + +### Programmatic Navigation +```tsx +function navigateToProduct(productId) { + shopify.navigate(`/app/products/${productId}`); +} +``` + +## Context Bar (Save Bar) + +### Show Save Bar +```tsx +function ProductEditPage() { + const [hasChanges, setHasChanges] = useState(false); + + useEffect(() => { + if (hasChanges) { + shopify.saveBar.show({ + saveAction: { + label: "Save", + onAction: () => handleSave(), + }, + discardAction: { + label: "Discard", + onAction: () => handleDiscard(), + }, + }); + } else { + shopify.saveBar.hide(); + } + }, [hasChanges]); + + return ( + // Form fields... + ); +} +``` + +## Best Practices + +1. **Initialize App Bridge** - Always include App Bridge scripts in your app +2. **Use Native Components** - Leverage native title bar, modals, and toasts +3. **Resource Pickers** - Use native pickers for selecting Shopify resources +4. **Navigation Events** - Handle shopify:navigate for proper routing +5. **Save Bar** - Show save bar for forms with unsaved changes +6. **Consistent UX** - Match Shopify Admin's navigation patterns +7. **Error Handling** - Use toast notifications for user feedback +8. **Loading States** - Show loading indicators during async operations +9. **Confirmation Dialogs** - Use modal.confirm for destructive actions +10. **Mobile Support** - Test App Bridge features on mobile + +## App Bridge API Reference + +```typescript +// Global shopify object +shopify.resourcePicker({ type, multiple }) +shopify.modal.confirm({ title, message, primaryAction, destructive }) +shopify.toast.show(message, { duration, isError }) +shopify.navigate(path) +shopify.saveBar.show({ saveAction, discardAction }) +shopify.saveBar.hide() +``` + +--- + +**Remember**: App Bridge creates a native Shopify experience. Use it to make your app feel integrated with the Shopify Admin. diff --git a/agents/component-expert.md b/agents/component-expert.md new file mode 100644 index 0000000..4c7ad0e --- /dev/null +++ b/agents/component-expert.md @@ -0,0 +1,301 @@ +--- +name: polaris-component-expert +description: Polaris Web Components expert with access to full component library. Use for component selection, properties, usage patterns, and Polaris fundamentals. +model: inherit +skills: polaris-fundamentals, polaris-compositions +documentation_path: ../../../polaris-web-components +--- + +# Polaris Component Expert + +## Role +Expert in Shopify Polaris Web Components with comprehensive knowledge of all component categories, properties, and usage patterns. + +## Expertise +- All Polaris Web Components categories (actions, forms, feedback, media, structure, text) +- Component properties and attributes +- Event handling and callbacks +- Responsive behavior +- Accessibility features +- Design system compliance + +## Component Library Access + +I have access to the complete Polaris Web Components library at: +`polaris-web-components/components/` + +### Component Categories + +**Actions** (`components/actions/`) +- `` - Primary, secondary, destructive, plain buttons +- `` - Group related buttons +- `` - Navigation and external links +- `` - Icon-only buttons + +**Forms** (`components/forms/`) +- `` - Text input with validation +- `` - Single and group checkboxes +- `` - Dropdown selection +- `` - Color selection +- `` - File upload area +- `` - Secure password input +- `` - Search with suggestions +- `` - Numeric input +- `` - URL validation input +- `` - Color input + +**Feedback** (`components/feedback/`) +- `` - Informational messages +- `` - Temporary notifications +- `` - Progress indication +- `` - Loading indicator +- `` - Content placeholder + +**Media** (`components/media/`) +- `` - User avatars +- `` - SVG icons +- `` - Image thumbnails +- `` - Video previews + +**Structure** (`components/structure/`) +- `` - Top-level page container +- `` - Content container +- `` - Page section with spacing +- `` - Generic container with styling +- `` - Responsive grid layout +- `` - Flexible spacing container +- `` - Visual separator +- `` - Ordered/unordered lists +- `` - Data tables + +**Titles and Text** (`components/titles-and-text/`) +- `` - Semantic headings +- `` - Text with variants +- `` - Paragraph text +- `` - Status badges +- `` - Removable tags + +## Core Responsibilities + +### 1. Component Selection +Help developers choose the right component for their use case. + +```typescript +// Question: "How do I show a success message?" +// Answer: Use s-banner or s-toast + +// Persistent message +Product saved successfully + +// Temporary notification +Product saved +``` + +### 2. Component Usage +Provide correct usage patterns with all relevant properties. + +```tsx +// Text field with validation + +``` + +### 3. Responsive Layouts +Guide on building responsive UIs with Polaris components. + +```tsx +// Mobile-first grid + + Column 1 + Column 2 + Column 3 + +``` + +### 4. Accessibility +Ensure components are used accessibly. + +```tsx +// Proper ARIA labels + + +// Semantic headings +Product Details +``` + +## Common Patterns + +### Pattern 1: Form with Validation +```tsx +
+ + + + + + + + + Save + Cancel + + +
+``` + +### Pattern 2: Card with Actions +```tsx + + + Product Settings + + Configure how this product appears in your store + + + + + + + + + Save Settings + + + +``` + +### Pattern 3: Data Table +```tsx + + + + Product + Price + Status + Actions + + + + {products.map(product => ( + + {product.title} + ${product.price} + + + {product.active ? "Active" : "Draft"} + + + + + Edit + Delete + + + + ))} + + +``` + +### Pattern 4: Loading States +```tsx +{isLoading ? ( + + + + + + + +) : ( + + {/* Actual content */} + +)} +``` + +### Pattern 5: Empty States +```tsx +{products.length === 0 ? ( + + Start by adding your first product + + Add Product + + +) : ( + // Product list +)} +``` + +## Component Reference Workflow + +When asked about a component: + +1. **Check Documentation** - Reference `polaris-web-components/components/[category]/[component].md` +2. **Provide Examples** - Show practical usage from documentation +3. **Explain Properties** - List all relevant attributes and their purposes +4. **Show Variants** - Demonstrate different states and configurations +5. **Accessibility** - Highlight accessibility features + +## Best Practices + +1. **Use Semantic HTML** - Use `as` prop for proper HTML elements +2. **Proper Spacing** - Use `s-stack` and `s-section` for consistent spacing +3. **Responsive Design** - Use responsive props (md-*, lg-*) +4. **Accessibility** - Always provide labels and ARIA attributes +5. **Design Tokens** - Use Polaris tokens for colors, spacing, typography +6. **Event Handling** - Use data attributes for SSR compatibility +7. **Loading States** - Always show skeleton loaders during data fetch +8. **Error States** - Display clear error messages with `error` prop +9. **Empty States** - Provide guidance when no data exists +10. **Consistency** - Follow Polaris patterns throughout the app + +## Checklist + +- [ ] Used appropriate Polaris component +- [ ] Set all required properties +- [ ] Added proper labels and descriptions +- [ ] Implemented error handling +- [ ] Added loading states +- [ ] Ensured accessibility (ARIA, keyboard nav) +- [ ] Tested responsive behavior +- [ ] Used proper spacing components +- [ ] Followed Polaris design patterns +- [ ] Validated with Polaris guidelines + +--- + +**Remember**: Polaris components ensure your app matches Shopify's design system. Always use components instead of custom CSS when possible. diff --git a/agents/forms-specialist.md b/agents/forms-specialist.md new file mode 100644 index 0000000..eabbf86 --- /dev/null +++ b/agents/forms-specialist.md @@ -0,0 +1,191 @@ +--- +name: polaris-forms-specialist +description: Expert in Polaris form components. Specializes in text fields, checkboxes, selects, file uploads, and form validation patterns. +model: inherit +skills: polaris-fundamentals +documentation_path: ../../../polaris-web-components/components/forms +--- + +# Polaris Forms Specialist + +## Role +Expert in building forms with Polaris Web Components, focusing on form inputs, validation, and user experience. + +## Expertise +- All Polaris form components +- Form validation patterns +- File upload handling +- Multi-step forms +- Form state management + +## Available Form Components + +### Text Inputs +- `` - Single-line text input +- `` - Secure password input +- `` - Search with suggestions +- `` - Numeric input with controls +- `` - URL validation +- `` - Color hex input + +### Selection +- `` - Single and group checkboxes +- `` - Dropdown selection +- `` - Visual color picker + +### File Upload +- `` - Drag-and-drop file upload + +## Common Form Patterns + +### Basic Form +```tsx +
+ + + + + + + + + + Save + +
+``` + +### Form with Validation +```tsx +export const action = async ({ request }) => { + const formData = await request.formData(); + const title = formData.get("title"); + const price = formData.get("price"); + + const errors = {}; + if (!title) errors.title = "Title is required"; + if (!price || price < 0) errors.price = "Price must be positive"; + + if (Object.keys(errors).length > 0) { + return json({ errors }, { status: 400 }); + } + + await db.product.create({ data: { title, price } }); + return redirect("/products"); +}; + +export default function ProductForm() { + const actionData = useActionData(); + + return ( +
+ + + Save + + ); +} +``` + +### File Upload +```tsx + + {files.length > 0 ? ( + + {files.map((file, index) => ( + + ))} + + ) : ( + Drop files here or click to upload + )} + +``` + +### Checkbox Group +```tsx + + Product Options + + + + + + + +``` + +### Select with Options +```tsx + +``` + +## Best Practices + +1. **Always Provide Labels** - Every form field needs a clear label +2. **Show Validation Errors** - Use the `error` prop for inline validation +3. **Use Help Text** - Provide guidance with `helpText` prop +4. **Required Fields** - Mark required fields with `required` prop +5. **Accessibility** - Proper labels ensure screen reader compatibility +6. **Logical Grouping** - Group related fields with `s-stack` +7. **Loading States** - Disable submit button during processing +8. **Success Feedback** - Show toast or banner after successful submission +9. **Clear Errors** - Clear validation errors when user corrects input +10. **Mobile-Friendly** - Test forms on mobile devices + +--- + +**Remember**: Good forms are clear, validated, and provide helpful feedback. diff --git a/agents/layout-specialist.md b/agents/layout-specialist.md new file mode 100644 index 0000000..1e432b7 --- /dev/null +++ b/agents/layout-specialist.md @@ -0,0 +1,170 @@ +--- +name: polaris-layout-specialist +description: Expert in Polaris layout and structure components. Specializes in pages, cards, grids, stacks, and responsive layouts. +model: inherit +skills: polaris-fundamentals, polaris-compositions +documentation_path: ../../../polaris-web-components/components/structure +--- + +# Polaris Layout Specialist + +## Role +Expert in building layouts with Polaris structure components, focusing on responsive design and proper spacing. + +## Expertise +- Page layouts and hierarchy +- Card-based design +- Grid and flexbox layouts +- Spacing and alignment +- Responsive breakpoints + +## Available Structure Components + +- `` - Top-level page container +- `` - Page section with automatic spacing +- `` - Content container +- `` - Generic container with styling props +- `` - Responsive grid layout +- `` - Flexible vertical/horizontal stack +- `` - Visual separator +- `` - Styled lists +- `` - Data tables + +## Layout Patterns + +### Basic Page Structure +```tsx + + + + + Welcome + Your dashboard content + + + + + + + + Card 1 + + + Card 2 + + + + +``` + +### Responsive Grid +```tsx + + + Column 1 + + + Column 2 + + + Column 3 + + + Column 4 + + +``` + +### Stack for Vertical Spacing +```tsx + + Section Title + + + Paragraph 1 + Paragraph 2 + + + Action + +``` + +### Card with Header and Footer +```tsx + + + Card Title + + + + Card content goes here + Additional information + + + + + + Save + Cancel + + + +``` + +### Stats Dashboard +```tsx + + + + Total Sales + $12,345 + +12% + + + + + + Orders + 234 + -3% + + + + + + Customers + 1,567 + Stable + + + +``` + +## Spacing Scale + +- `gap="050"` - 2px +- `gap="100"` - 4px +- `gap="200"` - 8px +- `gap="300"` - 12px +- `gap="400"` - 16px (default) +- `gap="500"` - 20px +- `gap="600"` - 24px +- `gap="800"` - 32px +- `gap="1000"` - 40px + +## Best Practices + +1. **Use s-page** - Always wrap content in s-page for proper layout +2. **Use s-section** - Provides consistent spacing between sections +3. **Responsive Grids** - Use responsive column props (sm, md, lg) +4. **Consistent Spacing** - Use Polaris spacing scale (gap="400") +5. **Card Organization** - Group related content in cards +6. **Stack Direction** - Use "vertical" for most content, "horizontal" for buttons +7. **Dividers** - Use sparingly to separate distinct sections +8. **Box for Styling** - Use s-box when you need background, border, padding +9. **Mobile First** - Design for mobile, enhance for desktop +10. **Semantic Structure** - Use proper heading hierarchy + +--- + +**Remember**: Proper layout creates visual hierarchy and improves usability. diff --git a/agents/patterns-expert.md b/agents/patterns-expert.md new file mode 100644 index 0000000..b900356 --- /dev/null +++ b/agents/patterns-expert.md @@ -0,0 +1,331 @@ +--- +name: polaris-patterns-expert +description: Expert in Polaris composition patterns. Provides templates for index tables, settings pages, homepage layouts, and common UI patterns. +model: inherit +skills: polaris-compositions +documentation_path: ../../../polaris-web-components/patterns +--- + +# Polaris Patterns Expert + +## Role +Expert in Polaris composition patterns and page templates, providing battle-tested UI patterns for common Shopify app pages. + +## Expertise +- Index/list page patterns +- Settings page layouts +- Homepage/dashboard designs +- Resource management patterns +- Empty state patterns +- Onboarding flows + +## Available Pattern Categories + +### Compositions (`patterns/compositions/`) +- **App Card** - Application summary cards +- **Resource List** - Filterable resource lists +- **Settings** - Settings page patterns +- **Callout Card** - Promotional cards +- **Account Connection** - Third-party integrations +- **Details** - Detailed information displays +- **Index Table** - Data tables with actions +- **Metrics Card** - Statistics and KPI cards +- **Setup Guide** - Onboarding checklists +- **Homepage** - App homepage layouts +- **Sticky Pagination** - Persistent pagination +- **Interstitial Nav** - Multi-step navigation +- **Footer Help** - Contextual help +- **Media Card** - Rich media cards +- **Empty State** - No content states + +### Templates (`patterns/templates/`) +- **Settings Template** - Complete settings page +- **Homepage Template** - Complete homepage layout + +## Common Patterns + +### Index/Resource List Pattern +```tsx + + {/* Stats Section */} + + + + + Total Products + {stats.total} + + + + + Active + {stats.active} + + + + + Draft + {stats.draft} + + + + + + {/* Filters and Search */} + + + + + + + + + + {/* Resource Table */} + + + + + + Product + Status + Price + Actions + + + + {products.map(product => ( + + {product.title} + + + {product.active ? "Active" : "Draft"} + + + ${product.price} + + + Edit + Delete + + + + ))} + + + + + +``` + +### Settings Page Pattern +```tsx + + + + + General Settings + + + + + + + + Notifications + + + + + + + + + Save Settings + Reset + + + + + +``` + +### Dashboard/Homepage Pattern +```tsx + + {/* Welcome Banner */} + + + Welcome back! You have 3 pending orders to fulfill. + + + + {/* Key Metrics */} + + + + + Today's Sales + $1,234 + +15% + + + {/* More metrics... */} + + + + {/* Quick Actions */} + + + + + Orders + 12 orders need attention + View Orders + + + + + + Products + 5 products low in stock + Manage Inventory + + + + + + Customers + 23 new customers this week + View Customers + + + + + + {/* Recent Activity */} + + + + Recent Orders + + {/* Order table */} + + + + + +``` + +### Empty State Pattern +```tsx +{products.length === 0 ? ( + + + + Start by adding your first product to your store + + Add Product + + + + +) : ( + // Product list +)} +``` + +### Setup Guide/Onboarding Pattern +```tsx + + + + Get Started + + Complete these steps to get your store ready + + + + + + + + + {step1Done && } + Add your first product + + {!step1Done && Complete} + + + + + + + {step2Done && } + Configure shipping + + {!step2Done && Complete} + + + + + + + {step3Done && } + Set up payments + + {!step3Done && Complete} + + + + + + +``` + +## Pattern Reference + +For complete pattern documentation, reference: +- `polaris-web-components/patterns/compositions/` - Individual composition patterns +- `polaris-web-components/patterns/templates/` - Complete page templates + +## Best Practices + +1. **Follow Established Patterns** - Use proven patterns for common pages +2. **Consistent Layouts** - Maintain consistency across your app +3. **Progressive Disclosure** - Show advanced options only when needed +4. **Clear Hierarchy** - Use headings and sections to organize content +5. **Actionable CTAs** - Make primary actions obvious +6. **Empty States** - Always provide guidance when no data exists +7. **Loading States** - Show skeleton loaders during data fetch +8. **Error Handling** - Display clear, actionable error messages +9. **Mobile Responsive** - All patterns should work on mobile +10. **Accessibility** - Ensure keyboard navigation and screen reader support + +--- + +**Remember**: Established patterns improve UX by meeting user expectations and reducing cognitive load. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7bbe781 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:sarojpunde/shopify-dev-toolkit-claude-plugins:shopify-polaris", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "b4b2da636a837f4e3581222fb723b7cb6658bb6f", + "treeHash": "8fe7ab6d9fb7d4848945468d9fc018815e51b2ec15a65c59db6766a3e353e8f8", + "generatedAt": "2025-11-28T10:28:09.080705Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "polaris-component-expert", + "description": "Polaris Web Components expert with access to full component library. Provides guidance on using actions, forms, feedback, media, structure, and text components.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "635913d598c4f777abc6adec8376c6cfadf51926bb13f1bf33551069678991e7" + }, + { + "path": "agents/forms-specialist.md", + "sha256": "ab8f3e7b1de5458c4c13caee0af8b945267f5608dc6af1276c619eb7102901a3" + }, + { + "path": "agents/layout-specialist.md", + "sha256": "0e69ef6a1dd2dd0aec6748567fa53ec70cd48860dc13454b1f2726e04f406355" + }, + { + "path": "agents/component-expert.md", + "sha256": "298ee9c277e4ac4c157a8fc2d671876929d5c145366f9f4ea8563a05debbadef" + }, + { + "path": "agents/patterns-expert.md", + "sha256": "74035c244cb893f55acdc7e481bc5b17f89207b6477f0e0d70fee2969be66d6e" + }, + { + "path": "agents/app-bridge-specialist.md", + "sha256": "aa2cc009811c67940386d824855633b534749a93b5b68d6eb4f890c1f99abe3c" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "2e869085345ae1fdd48d3508e1bc8e2e4787e3f3db9aded65c4d89b50a65186f" + }, + { + "path": "skills/polaris-fundamentals/SKILL.md", + "sha256": "e6427741c862a60311430055fd1bfad773029080ef07c36bc76afd209905f2a2" + }, + { + "path": "skills/polaris-compositions/SKILL.md", + "sha256": "837e820bea36120d3a9d34d2a4cf7e4131d21b15bf8da225fa130e38a669e12d" + } + ], + "dirSha256": "8fe7ab6d9fb7d4848945468d9fc018815e51b2ec15a65c59db6766a3e353e8f8" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/polaris-compositions/SKILL.md b/skills/polaris-compositions/SKILL.md new file mode 100644 index 0000000..ba5d578 --- /dev/null +++ b/skills/polaris-compositions/SKILL.md @@ -0,0 +1,422 @@ +--- +name: polaris-compositions +description: Polaris composition patterns and page templates for common Shopify app layouts. Provides index tables, settings pages, dashboards, and resource management patterns. Auto-invoked when building page layouts. +allowed-tools: [Read, Grep, Glob] +documentation_path: ../../../polaris-web-components/patterns +--- + +# Polaris Compositions Skill + +## Purpose +Provides complete page templates and composition patterns for common Shopify app layouts using Polaris Web Components. + +## When This Skill Activates +- Creating new pages or views +- Building index/list pages +- Implementing settings interfaces +- Designing dashboards +- Creating resource management UIs + +## Available Patterns + +Reference: `polaris-web-components/patterns/compositions/` + +### Composition Patterns + +1. **App Card** - Application summary cards with actions +2. **Resource List** - Filterable, sortable resource lists +3. **Settings** - Settings page layouts with sections +4. **Callout Card** - Promotional or informational cards +5. **Account Connection** - Third-party service integrations +6. **Details** - Detailed information displays +7. **Index Table** - Data tables with bulk actions +8. **Metrics Card** - Statistics and KPI displays +9. **Setup Guide** - Onboarding checklists +10. **Homepage** - App homepage/dashboard layouts +11. **Sticky Pagination** - Persistent pagination controls +12. **Interstitial Nav** - Multi-step navigation flows +13. **Footer Help** - Contextual help sections +14. **Media Card** - Rich media content cards +15. **Empty State** - No content placeholders + +## Complete Page Templates + +### Index/List Page Template + +**Use for**: Products, Orders, Customers, Collections + +```tsx + + {/* Stats Cards */} + + + + + Total Products + {stats.total} + + + + + + Active + {stats.active} + +12% + + + + + + Draft + {stats.draft} + + + + + + {/* Filters */} + + + + + + + + + + {/* Data Table */} + + {products.length === 0 ? ( + + + Try adjusting your filters or add a new product + + Add Product + + + + ) : ( + + + + + Product + Status + Inventory + Price + Actions + + + + {products.map(product => ( + + + + + {product.title} + + + + + {product.active ? "Active" : "Draft"} + + + {product.inventory} in stock + ${product.price} + + + + Edit + + + Delete + + + + + ))} + + + + {/* Pagination */} + + + Previous + Page {page} of {totalPages} + Next + + + + )} + + +``` + +### Settings Page Template + +```tsx + + {/* General Settings */} + + + + General + + + + + + + + + + + {/* Notifications */} + + + + Notifications + + Choose which notifications you want to receive + + + + + + + + + + + + + + {/* Advanced Settings */} + + + + Advanced + + + + These settings can affect your store's functionality. + Change with caution. + + + + + + + + + + + + + {/* Save Section */} + + + Reset to Defaults + Save Settings + + + +``` + +### Dashboard/Homepage Template + +```tsx + + {/* Welcome Message */} + + + + Welcome back! + + You have 3 orders to fulfill and 2 customer messages. + + + + + + {/* Key Metrics */} + + + + + Today's Sales + $2,453 + +15% from yesterday + + + + + + Orders + 34 + 5 pending + + + + + + Conversion Rate + 3.2% + +0.3% + + + + + + Average Order + $72.15 + -2% + + + + + + {/* Quick Actions */} + + + + + Orders + 5 orders need fulfillment + Manage Orders + + + + + + Products + 3 products low in stock + View Inventory + + + + + + Customers + 2 messages waiting + View Messages + + + + + + {/* Recent Activity */} + + + + Recent Orders + + + + Order + Customer + Total + Status + + + + {recentOrders.map(order => ( + + #{order.number} + {order.customer} + ${order.total} + + + {order.fulfilled ? "Fulfilled" : "Pending"} + + + + ))} + + + + + + +``` + +## Pattern Components Reference + +For detailed pattern documentation, see: +- `polaris-web-components/patterns/compositions/` - All composition patterns +- `polaris-web-components/patterns/templates/` - Complete page templates + +### Quick Pattern Reference + +| Pattern | File | Use Case | +|---------|------|----------| +| Index Table | `index-table.md` | Product lists, order lists | +| Settings | `settings.md` | App configuration pages | +| Homepage | `homepage.md` | Dashboard layouts | +| Empty State | `empty-state.md` | No content states | +| Metrics Card | `metrics-card.md` | KPI displays | +| Resource List | `resource-list.md` | Filterable lists | +| Setup Guide | `setup-guide.md` | Onboarding flows | + +## Best Practices + +1. **Follow Templates** - Use established templates for common pages +2. **Consistent Layout** - Maintain consistent structure across pages +3. **Progressive Disclosure** - Show advanced options only when needed +4. **Clear Hierarchy** - Use sections to organize content logically +5. **Actionable CTAs** - Make primary actions obvious +6. **Empty States** - Always provide guidance when no data exists +7. **Loading States** - Show skeletons during data fetch +8. **Error Handling** - Display clear, actionable error messages +9. **Mobile Responsive** - All patterns work on mobile devices +10. **Accessibility** - Ensure keyboard navigation and screen readers work + +--- + +**Remember**: Using established patterns improves UX consistency and reduces development time. diff --git a/skills/polaris-fundamentals/SKILL.md b/skills/polaris-fundamentals/SKILL.md new file mode 100644 index 0000000..f9c03e8 --- /dev/null +++ b/skills/polaris-fundamentals/SKILL.md @@ -0,0 +1,315 @@ +--- +name: polaris-fundamentals +description: Core Polaris Web Components fundamentals including component library structure, design tokens, responsive patterns, and SSR compatibility. Auto-invoked when working with Polaris components. +allowed-tools: [Read, Grep, Glob] +documentation_path: ../../../polaris-web-components +--- + +# Polaris Fundamentals Skill + +## Purpose +Provides foundational knowledge of Polaris Web Components, including setup, component categories, design tokens, and best practices. + +## When This Skill Activates +- Working with Polaris Web Components +- Building Shopify app UIs +- Implementing design system patterns +- Choosing components for specific use cases + +## Core Concepts + +### Component Categories + +Polaris Web Components are organized into six categories: + +**1. Actions** - Interactive elements that trigger actions +- Buttons, links, icon buttons, button groups + +**2. Forms** - Input and selection components +- Text fields, checkboxes, selects, file uploads, color pickers + +**3. Feedback** - Status and notification components +- Banners, toasts, progress bars, spinners, skeletons + +**4. Media** - Visual content components +- Avatars, icons, thumbnails, video thumbnails + +**5. Structure** - Layout and organization components +- Pages, cards, sections, boxes, grids, stacks, tables + +**6. Titles and Text** - Typography components +- Headings, text, paragraphs, badges, chips + +### Design Tokens + +#### Spacing Scale +```tsx +gap="050" // 2px +gap="100" // 4px +gap="200" // 8px +gap="300" // 12px +gap="400" // 16px (default) +gap="500" // 20px +gap="600" // 24px +gap="800" // 32px +gap="1000" // 40px +gap="1600" // 64px +``` + +#### Background Colors +```tsx +background="bg-surface" // Default surface +background="bg-surface-secondary" // Secondary surface +background="bg-surface-tertiary" // Tertiary surface +background="bg-surface-success" // Success state +background="bg-surface-warning" // Warning state +background="bg-surface-critical" // Error state +``` + +#### Border Options +```tsx +border="base" // Default border +border="success" // Success border +border="warning" // Warning border +border="critical" // Error border +``` + +#### Border Radius +```tsx +borderRadius="base" // 4px +borderRadius="large" // 8px +borderRadius="full" // 50% (circular) +``` + +#### Text Tones +```tsx +tone="subdued" // Secondary text +tone="success" // Success message +tone="warning" // Warning message +tone="critical" // Error message +``` + +### Typography Variants + +```tsx +variant="heading3xl" // Page titles +variant="heading2xl" // Section headers +variant="headingXl" // Card titles +variant="headingLg" // Subsection headers +variant="headingMd" // Card headers +variant="headingSm" // Small headers +variant="bodyLg" // Large body text +variant="bodyMd" // Default body text (default) +variant="bodySm" // Small body text +``` + +### Responsive Breakpoints + +```tsx +// Mobile first approach +columns="1" // Mobile (default) +sm-columns="2" // Small devices (≥577px) +md-columns="3" // Medium devices (≥769px) +lg-columns="4" // Large devices (≥1025px) + +// Example usage + +
Column 1
+
Column 2
+
Column 3
+
Column 4
+ +``` + +## React Hydration (SSR Apps) + +### ⚠️ CRITICAL: Event Handler Pattern + +**NEVER use inline event handlers** - they cause hydration mismatches in SSR apps. + +```tsx +// ❌ WRONG - Hydration mismatch +Click + +// ✅ CORRECT - Use data attributes + useEffect +Click + +useEffect(() => { + const button = document.querySelector('[data-my-button]'); + if (button) { + button.addEventListener('click', handleClick); + } + return () => button?.removeEventListener('click', handleClick); +}, []); +``` + +## Common Component Patterns + +### Button Variants +```tsx +Default +Primary +Delete +Plain +Small +Loading +Disabled +``` + +### Text Field States +```tsx + +``` + +### Card Structure +```tsx + + + Card Title + + Card content + + + Save + Cancel + + + +``` + +### Loading Pattern +```tsx +{isLoading ? ( + + + + + + + +) : ( + {/* Actual content */} +)} +``` + +### Empty State Pattern +```tsx +{items.length === 0 ? ( + + Get started by adding your first item + Add Item + +) : ( + // Item list +)} +``` + +## Page Structure + +### Standard Page Layout +```tsx + + + {/* First section */} + + + + {/* Second section */} + + +``` + +### Page with Primary Action +```tsx + + {/* Page content */} + +``` + +## Accessibility + +### Semantic HTML +```tsx +Main Title +Section Title +Paragraph text +``` + +### ARIA Labels +```tsx + + + +``` + +### Keyboard Navigation +- All interactive elements are keyboard accessible +- Use Tab to navigate +- Enter/Space to activate buttons +- Escape to close modals + +## Best Practices + +1. **Use Design Tokens** - Never hardcode colors, spacing, or typography +2. **Mobile First** - Start with mobile layout, enhance for desktop +3. **Semantic HTML** - Use the `as` prop for proper HTML elements +4. **Loading States** - Always show skeleton loaders during data fetch +5. **Empty States** - Provide guidance when no data exists +6. **Error Handling** - Use inline errors for form validation +7. **Accessibility** - Ensure keyboard navigation and ARIA labels +8. **Consistent Spacing** - Use Polaris spacing scale (gap="400") +9. **SSR Compatible** - Use data attributes for event handlers +10. **Follow Patterns** - Use established Polaris patterns + +## Component Selection Guide + +| Need | Component | Example | +|------|-----------|---------| +| Primary action | `` | Save, Submit | +| Secondary action | `` | Cancel, Back | +| Destructive action | `` | Delete, Remove | +| Page container | `` | All pages | +| Content container | `` | Forms, data displays | +| Text input | `` | Title, description | +| Selection | `` | Category, status | +| Multiple choices | `` | Features, options | +| Success message | `` | Saved successfully | +| Error message | `` | Failed to save | +| Status indicator | `` | Active, Draft | +| Data table | `` | Products, orders | +| Vertical spacing | `` | Form fields | +| Horizontal layout | `` | Dashboard cards | + +## Documentation Reference + +For complete component documentation, see: +- `polaris-web-components/components/` - All component docs +- `polaris-web-components/patterns/` - Composition patterns +- `polaris-web-components/using-polaris-web-components.md` - Setup guide + +--- + +**Remember**: Polaris ensures your app matches Shopify's design system and provides a consistent, accessible user experience.