add styling guide

Author: yhsieh1

packages/b2c-dx-mcp/README.md

@@ -105,6 +105,7 @@ The `storefront_next_development_guidelines` tool provides critical architecture
 - `state-management` - Client-side state management
 - `auth` - Authentication and session management
 - `components` - Component patterns and best practices
+- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
 - `page-designer` - Page Designer integration
 - `performance` - Performance optimization
 - `testing` - Testing strategies

packages/b2c-dx-mcp/content/components.md

@@ -101,10 +101,23 @@ src/components/product-skeleton/
     └── index.stories.tsx
 ```
 
+## Styling
+
+**Tailwind CSS 4** is the only styling approach allowed. Use utility classes directly in components.
+
+**Key rules:**
+
+- ✅ Use Tailwind utility classes
+- ✅ Use `cn()` utility for conditional classes
+- ❌ NO inline styles, NO CSS modules, NO separate CSS files
+
+**See `styling` section for:** Tailwind CSS 4, Shadcn/ui components, icons, responsive design, theme configuration, dark mode, best practices
+
 ## Best Practices
 
 1. **Extract view components** - Separate data handling from presentation
 2. **Type safety** - Define proper TypeScript interfaces
 3. **Consistent fallbacks** - Reusable skeleton components
 4. **Colocate tests** - Keep tests next to components
 5. **Story coverage** - Create stories for all reusable components
+6. **Tailwind utilities only** - Use Tailwind CSS classes, avoid inline styles or CSS modules

packages/b2c-dx-mcp/content/quick-reference.md

@@ -73,6 +73,28 @@ const ProductPage = createPage({
 export default ProductPage;
 ```
 
+### 5. Tailwind CSS 4 Only
+
+✅ **REQUIRED**: Use Tailwind utility classes only  
+❌ **BLOCKED**: No inline styles (`style={{...}}`), no CSS modules, no separate CSS files
+
+```typescript
+// ✅ CORRECT - Tailwind utilities
+<div className="rounded-lg border border-border bg-card p-4">
+    <h2 className="text-lg font-semibold text-card-foreground">
+        {product.name}
+    </h2>
+</div>
+
+// ❌ AVOID - Inline styles
+<div style={{ padding: '1rem' }}>
+
+// ❌ AVOID - CSS modules
+import styles from './product-card.module.css';
+```
+
+**Why?** Consistent styling approach, better performance, automatic dark mode support via theme variables.
+
 ---
 
 ## 📋 Quick Patterns
@@ -140,9 +162,6 @@ const { t } = getTranslation(context);
 ### Components
 
 ```typescript
-// shadcn/ui: Add via npx shadcn@latest add <component-name>
-// DO NOT modify src/components/ui/ directly
-
 // Suspense boundaries
 import { Suspense } from 'react';
 import { Await } from 'react-router';
@@ -156,6 +175,23 @@ import { Await } from 'react-router';
 
 **See `components` section for:** createPage HOC, file organization, best practices
 
+### Styling
+
+```typescript
+// Tailwind utility classes
+<div className="bg-background text-foreground border-border">
+    <button className="bg-primary text-primary-foreground rounded-md px-4 py-2">
+        Click me
+    </button>
+</div>
+
+// shadcn/ui: Add via npx shadcn@latest add <component-name>
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+```
+
+**See `styling` section for:** Tailwind CSS 4 rules, Shadcn/ui components, dark mode, responsive design
+
 ---
 
 ## 🔍 Get Detailed Guidelines
@@ -171,6 +207,7 @@ Use the `storefront_next_development_guidelines` MCP tool with specific sections
 **Available sections:**
 - `data-fetching` - Loaders, actions, useScapiFetcher, data flow
 - `components` - createPage HOC, Suspense, file organization
+- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
 - `testing` - Vitest, Storybook, coverage requirements
 - `auth` - Authentication and session management
 - `config` - Configuration system

packages/b2c-dx-mcp/content/styling.md

@@ -0,0 +1,51 @@
+# Styling Guidelines
+
+## Rules
+
+- ✅ **Use Tailwind utility classes** in component JSX
+- ✅ **Use `cn()` utility** for conditional classes (`import { cn } from '@/lib/utils'`)
+- ✅ **Follow mobile-first** responsive patterns (`md:`, `lg:` breakpoints)
+- ❌ **NO inline styles** (`style={{...}}`)
+- ❌ **NO CSS modules** (`.module.css` files)
+- ❌ **NO separate CSS files** for component styles
+- ✅ **Custom CSS** only in `src/app.css` for global styles and theme configuration
+
+## Shadcn/ui Components
+
+**Adding components:**
+
+```bash
+npx shadcn@latest add <component-name>
+```
+
+**Rules:**
+
+- ✅ **DO** customize components by editing files in `src/components/ui/`
+- ❌ **DON'T** create custom components inside `src/components/ui/`
+- ❌ **DON'T** manually copy components (use CLI instead)
+
+## Dark Mode
+
+Dark mode is supported via CSS variables and the `.dark` class. Theme variables automatically adapt:
+
+```typescript
+<div className="bg-background text-foreground border-border">
+    <button className="bg-primary text-primary-foreground">
+        Click me
+    </button>
+</div>
+```
+
+## Responsive Design
+
+Follow mobile-first responsive design:
+
+```typescript
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {/* Content */}
+</div>
+```
+
+---
+
+**Reference:** See [README-UI-STYLING.md](README-UI-STYLING.md) for complete UI and styling documentation.

packages/b2c-dx-mcp/src/tools/storefrontnext/README.md

@@ -33,6 +33,7 @@ MCP tools for Storefront Next development with React Server Components.
     - `config` - Configuration system
     - `i18n` - Internationalization patterns
     - `components` - Component best practices
+    - `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
     - `page-designer` - Page Designer integration and component registry
     - `performance` - Optimization techniques
     - `testing` - Testing strategy
@@ -74,7 +75,7 @@ MCP tools for Storefront Next development with React Server Components.
 {
   "name": "storefront_next_development_guidelines",
   "arguments": {
-    "sections": ["quick-reference", "data-fetching", "state-management", "auth", "config", "i18n", "components", "page-designer", "performance", "testing", "extensions", "pitfalls"]
+    "sections": ["quick-reference", "data-fetching", "state-management", "auth", "config", "i18n", "components", "styling", "page-designer", "performance", "testing", "extensions", "pitfalls"]
   }
 }
 ```

packages/b2c-dx-mcp/src/tools/storefrontnext/developer-guidelines.ts

@@ -44,6 +44,7 @@ const SECTIONS_METADATA = [
   {key: 'config', description: 'configuration'},
   {key: 'i18n', description: 'i18n patterns and internationalization'},
   {key: 'components', description: 'component best practices'},
+  {key: 'styling', description: 'Tailwind CSS 4, Shadcn/ui, styling guidelines'},
   {key: 'page-designer', description: 'Page Designer integration'},
   {key: 'performance', description: 'performance optimization'},
   {key: 'testing', description: 'testing strategies'},