Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.
CRITICAL: Install peer dependencies BEFORE writing any code:
# Find exact version from dashboard
pnpm list @tanstack/react-query --depth=10 | grep @medusajs/dashboard
# Install that exact version
pnpm add @tanstack/react-query@[exact-version]
# If using navigation (Link component)
pnpm list react-router-dom --depth=10 | grep @medusajs/dashboard
pnpm add react-router-dom@[exact-version]
npm/yarn users: DO NOT install these packages - already available.
Rule Categories by Priority
Priority
Category
Impact
Prefix
1
Data Loading
CRITICAL
data-
2
Design System
CRITICAL
design-
3
Data Display
HIGH (includes CRITICAL price rule)
display-
4
Typography
HIGH
typo-
5
Forms & Modals
MEDIUM
form-
6
Selection Patterns
MEDIUM
select-
Quick Reference
1. Data Loading (CRITICAL)
data-sdk-always - ALWAYS use Medusa JS SDK for ALL API requests - NEVER use regular fetch() (missing auth headers causes errors)
data-sdk-method-choice - Use existing SDK methods for built-in endpoints (sdk.admin.product.list()), use sdk.client.fetch() for custom routes
data-display-on-mount - Display queries MUST load on mount (no enabled condition based on UI state)
data-separate-queries - Separate display queries from modal/form queries
data-invalidate-display - Invalidate display queries after mutations, not just modal queries
data-loading-states - Always show loading states (Spinner), not empty states
data-pnpm-install-first - pnpm users MUST install @tanstack/react-query BEFORE coding
2. Design System (CRITICAL)
design-semantic-colors - Always use semantic color classes (bg-ui-bg-base, text-ui-fg-subtle), never hardcoded
design-spacing - Use px-6 py-4 for section padding, gap-2 for lists, gap-3 for items
design-button-size - Always use size="small" for buttons in widgets and tables
design-medusa-components - Always use Medusa UI components (Container, Button, Text), not raw HTML
3. Data Display (HIGH)
display-price-format - CRITICAL: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100
4. Typography (HIGH)
typo-text-component - Always use Text component from @medusajs/ui, never plain span/p tags
typo-labels - Use <Text size="small" leading="compact" weight="plus"> for labels/headings
typo-descriptions - Use <Text size="small" leading="compact" className="text-ui-fg-subtle"> for descriptions
typo-no-heading-widgets - Never use Heading for small sections in widgets (use Text instead)
5. Forms & Modals (MEDIUM)
form-focusmodal-create - Use FocusModal for creating new entities
form-drawer-edit - Use Drawer for editing existing entities
form-disable-pending - Always disable actions during mutations (disabled={mutation.isPending})
form-show-loading - Show loading state on submit button (isLoading={mutation.isPending})
6. Selection Patterns (MEDIUM)
select-small-datasets - Use Select component for 2-10 options (statuses, types, etc.)
select-large-datasets - Use DataTable with FocusModal for large datasets (products, categories, etc.)
select-search-config - Must pass search configuration to useDataTable to avoid "search not enabled" error
Critical Data Loading Pattern
ALWAYS follow this pattern - never load display data conditionally:
// ✅ CORRECT - Separate queries with proper responsibilities
const RelatedProductsWidget = ({ data: product }) => {
const [modalOpen, setModalOpen] = useState(false)
// Display query - loads on mount
const { data: displayProducts } = useQuery({
queryFn: () => fetchSelectedProducts(selectedIds),
queryKey: ["related-products-display", product.id],
// No 'enabled' condition - loads immediately
})
// Modal query - loads when needed
const { data: modalProducts } = useQuery({
queryFn: () => sdk.admin.product.list({ limit: 10, offset: 0 }),
queryKey: ["products-selection"],
enabled: modalOpen, // OK for modal-only data
})
// Mutation with proper invalidation
const updateProduct = useMutation({
mutationFn: updateFunction,
onSuccess: () => {
// Invalidate display data query to refresh UI
queryClient.invalidateQueries({ queryKey: ["related-products-display", product.id] })
// Also invalidate the entity query
queryClient.invalidateQueries({ queryKey: ["product", product.id] })
// Note: No need to invalidate modal selection query
},
})
return (
<Container>
{/* Display uses displayProducts */}
{displayProducts?.map(p => <div key={p.id}>{p.title}</div>)}
<FocusModal open={modalOpen} onOpenChange={setModalOpen}>
{/* Modal uses modalProducts */}
</FocusModal>
</Container>
)
}
// ❌ WRONG - Single query with conditional loading
const BrokenWidget = ({ data: product }) => {
const [modalOpen, setModalOpen] = useState(false)
const { data } = useQuery({
queryFn: () => sdk.admin.product.list(),
enabled: modalOpen, // ❌ Display breaks on page refresh!
})
// Trying to display from modal query
const displayItems = data?.filter(item => ids.includes(item.id)) // No data until modal opens
return <div>{displayItems?.map(...)}</div> // Empty on mount!
}
Why this matters:
On page refresh, modal is closed, so conditional query doesn't run
User sees empty state instead of their data
Display depends on modal interaction (broken UX)
Common Mistakes Checklist
Before implementing, verify you're NOT doing these:
Data Loading:
Using regular fetch() instead of Medusa JS SDK (causes missing auth header errors)
Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch("/admin/products") instead of sdk.admin.product.list())
Loading display data conditionally based on modal/UI state
Using a single query for both display and modal
Forgetting to invalidate display queries after mutations
Not handling loading states (showing empty instead of spinner)
pnpm users: Not installing @tanstack/react-query before coding
Design System:
Using hardcoded colors instead of semantic classes
Forgetting size="small" on buttons in widgets
Not using px-6 py-4 for section padding
Using raw HTML elements instead of Medusa UI components
Data Display:
CRITICAL: Dividing prices by 100 when displaying (prices are stored as-is: $49.99 = 49.99, NOT in cents)
Typography:
Using plain span/p tags instead of Text component
Not using weight="plus" for labels
Not using text-ui-fg-subtle for descriptions
Using Heading in small widget sections
Forms:
Using Drawer for creating (should use FocusModal)
Using FocusModal for editing (should use Drawer)
Not disabling buttons during mutations
Not showing loading state on submit
Selection:
Using DataTable for <10 items (overkill)
Using Select for >10 items (poor UX)
Not configuring search in useDataTable (causes error)
For Widgets:
Navigate to the page where your widget is displayed. Common widget zones:
Product widgets: Go to Products → Select a product → Your widget appears in the zone you configured (e.g., product.details.after)
Order widgets: Go to Orders → Select an order → Your widget appears in the configured zone
Customer widgets: Go to Customers → Select a customer → Your widget appears in the configured zone
For UI Routes (Custom Pages):
Look for your custom page in the admin sidebar/navigation (based on the label you configured)
Or navigate directly to: http://localhost:9000/app/[your-route-path]
4. Test Functionality
Depending on what was implemented, test:
Forms: Try creating/editing entities, verify validation and error messages
Tables: Test pagination, search, sorting, and row selection
Data display: Verify data loads correctly and refreshes after mutations
Modals: Open FocusModal/Drawer, test form submission, verify data updates
Navigation: Click links and verify routing works correctly
Format for Presenting Next Steps
Always present next steps in a clear, actionable format after implementation:
## Implementation Complete
The [feature name] has been successfully implemented. Here's how to see it:
### Start the Development Server
[command based on package manager]
### Access the Admin Dashboard
Open http://localhost:9000/app in your browser and log in.
### View Your Custom UI
**For Widgets:**
1. Navigate to [specific admin page, e.g., "Products"]
2. Select [an entity, e.g., "any product"]
3. Scroll to [zone location, e.g., "the bottom of the page"]
4. You'll see your "[widget name]" widget
**For UI Routes:**
1. Look for "[page label]" in the admin navigation
2. Or navigate directly to http://localhost:9000/app/[route-path]
### What to Test
1. [Specific test case 1]
2. [Specific test case 2]
3. [Specific test case 3]
