@adlas/create-app 1.0.0

package/templates/docs/FIGMA_TO_CODE_GUIDE.md

@@ -0,0 +1,768 @@
+# Figma to Code Guide
+
+Complete guide for converting Figma designs to code in the Berndorf e-commerce project. This guide helps AI and developers translate designs accurately using existing components.
+
+## Table of Contents
+
+1. [Figma MCP Server Usage](#figma-mcp-server-usage)
+2. [Design Analysis Workflow](#design-analysis-workflow)
+3. [Design Token Mapping](#design-token-mapping)
+4. [Component Mapping Rules](#component-mapping-rules)
+5. [AI Decision Tree](#ai-decision-tree)
+6. [Examples](#examples)
+7. [Quality Checklist](#quality-checklist)
+
+---
+
+## Figma MCP Server Usage
+
+The Figma MCP Server allows AI to directly access and analyze Figma designs.
+
+### Prerequisites
+
+1. Figma file URL or file key
+2. MCP Server configured in Claude Code
+3. Access permissions to Figma file
+
+### Available Commands
+
+```typescript
+// Get file information
+mcp__figma_get_file({
+  file_key: "abc123xyz",
+  depth: 2 // Level of detail (1-4)
+})
+
+// Get specific node
+mcp__figma_get_node({
+  file_key: "abc123xyz",
+  node_id: "123:456"
+})
+
+// Get comments
+mcp__figma_get_comments({
+  file_key: "abc123xyz"
+})
+```
+
+### Usage Pattern
+
+```
+1. User provides Figma URL: https://www.figma.com/file/ABC123/Design
+2. Extract file key: ABC123
+3. Call mcp__figma_get_file to analyze design
+4. Identify components, colors, spacing, typography
+5. Map to existing components
+6. Generate code
+```
+
+---
+
+## Design Analysis Workflow
+
+Follow this workflow when converting Figma to code.
+
+### Step 1: Initial Design Analysis
+
+**Questions to ask:**
+
+1. What is the overall layout structure?
+   - Single column? Multi-column grid?
+   - Sidebar? Full-width?
+   - Responsive breakpoints needed?
+
+2. What components are used?
+   - Buttons? Forms? Cards?
+   - Navigation? Modals?
+   - Custom or standard components?
+
+3. What are the design tokens?
+   - Colors (check against design system)
+   - Spacing (check against Tailwind scale)
+   - Typography (font sizes, weights)
+   - Border radius
+
+4. What interactions are needed?
+   - Hover states?
+   - Click actions?
+   - Form submissions?
+   - Animations?
+
+### Step 2: Component Inventory
+
+Create an inventory of all UI elements:
+
+```markdown
+## Component Inventory
+
+### Existing Components Needed:
+- [ ] Button (variant: solid, color: primary)
+- [ ] Input (3 fields: email, name, message)
+- [ ] Textarea (1 field: description)
+- [ ] Card (for product display)
+
+### Element Components Needed:
+- [ ] ProductCard
+- [ ] HeaderBanner
+
+### Custom Components Needed:
+- [ ] None (use existing only!)
+```
+
+### Step 3: Design Token Extraction
+
+Extract all design tokens from Figma:
+
+```markdown
+## Design Tokens
+
+### Colors:
+- Primary: #0066CC → use text-primary or bg-primary
+- Text: #1A1A1A → use text-default-900
+- Border: #E0E0E0 → use border-default-200
+
+### Spacing:
+- Section padding: 64px → use py-16
+- Card gap: 24px → use gap-6
+- Button padding: 12px 24px → default button styling
+
+### Typography:
+- Heading: 32px, Bold → use text-3xl font-bold
+- Body: 16px, Regular → use text-base
+- Caption: 14px, Medium → use text-sm font-medium
+
+### Border Radius:
+- Buttons: 0px → radius="none" (default)
+- Cards: 0px → rounded-none
+```
+
+### Step 4: Layout Planning
+
+Plan the layout structure:
+
+```tsx
+// Layout structure
+<div className="container mx-auto px-4 py-16">
+  {/* Header Section */}
+  <div className="mb-8">
+    <h1 className="text-3xl font-bold mb-4">Title</h1>
+    <p className="text-base text-default-600">Description</p>
+  </div>
+
+  {/* Content Grid */}
+  <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
+    {/* Items */}
+  </div>
+</div>
+```
+
+---
+
+## Design Token Mapping
+
+Map Figma design tokens to project tokens.
+
+### Color Mapping
+
+| Figma Color | Hex Code | Project Token | Usage |
+|-------------|----------|---------------|-------|
+| Primary | #0066CC | `primary` | Buttons, links |
+| Secondary | #6B7280 | `secondary` | Secondary actions |
+| Success | #10B981 | `success` | Success states |
+| Warning | #F59E0B | `warning` | Warning states |
+| Danger | #EF4444 | `danger` | Error states, delete |
+| Text Dark | #1A1A1A | `default-900` | Primary text |
+| Text Medium | #6B7280 | `default-600` | Secondary text |
+| Text Light | #9CA3AF | `default-400` | Placeholder text |
+| Border | #E5E7EB | `default-200` | Borders |
+| Background | #F9FAFB | `default-50` | Backgrounds |
+| White | #FFFFFF | `background` | Cards, modals |
+
+**Usage in Code:**
+
+```tsx
+// Text colors
+className="text-default-900"      // Primary text
+className="text-default-600"      // Secondary text
+className="text-primary"          // Primary brand color
+
+// Background colors
+className="bg-primary"            // Primary background
+className="bg-default-50"         // Light background
+className="bg-background"         // White background
+
+// Border colors
+className="border-default-200"    // Default border
+className="border-primary"        // Primary border
+```
+
+### Spacing Mapping
+
+Tailwind uses a consistent spacing scale (4px base unit).
+
+| Figma Value | Tailwind Class | Pixels |
+|-------------|----------------|--------|
+| 4px | `gap-1`, `p-1`, `m-1` | 4px |
+| 8px | `gap-2`, `p-2`, `m-2` | 8px |
+| 12px | `gap-3`, `p-3`, `m-3` | 12px |
+| 16px | `gap-4`, `p-4`, `m-4` | 16px |
+| 24px | `gap-6`, `p-6`, `m-6` | 24px |
+| 32px | `gap-8`, `p-8`, `m-8` | 32px |
+| 48px | `gap-12`, `p-12`, `m-12` | 48px |
+| 64px | `gap-16`, `p-16`, `m-16` | 64px |
+
+**Usage in Code:**
+
+```tsx
+// Padding
+className="p-4"      // 16px all sides
+className="px-6"     // 24px horizontal
+className="py-8"     // 32px vertical
+
+// Margin
+className="mb-6"     // 24px bottom
+className="mt-8"     // 32px top
+
+// Gap (for flex/grid)
+className="gap-4"    // 16px gap
+className="gap-6"    // 24px gap
+```
+
+### Typography Mapping
+
+| Figma Size/Weight | Tailwind Classes | Usage |
+|-------------------|------------------|-------|
+| 12px Regular | `text-xs` | Small captions |
+| 14px Regular | `text-sm` | Body text small |
+| 14px Medium | `text-sm font-medium` | Labels |
+| 16px Regular | `text-base` | Body text |
+| 16px Semibold | `text-base font-semibold` | Emphasized text |
+| 18px Semibold | `text-lg font-semibold` | Subheadings |
+| 20px Bold | `text-xl font-bold` | Section titles |
+| 24px Bold | `text-2xl font-bold` | Page titles |
+| 32px Bold | `text-3xl font-bold` | Hero titles |
+
+**Usage in Code:**
+
+```tsx
+// Headings
+<h1 className="text-3xl font-bold">Hero Title</h1>
+<h2 className="text-2xl font-bold">Page Title</h2>
+<h3 className="text-xl font-bold">Section Title</h3>
+
+// Body text
+<p className="text-base">Regular paragraph text</p>
+<p className="text-sm text-default-600">Secondary text</p>
+
+// Labels
+<label className="text-sm font-medium">Form Label</label>
+```
+
+### Border Radius Mapping
+
+Berndorf project uses **sharp corners (no border radius)** by default.
+
+| Figma Radius | HeroUI Token | Tailwind Class |
+|--------------|--------------|----------------|
+| 0px | `none` | `rounded-none` |
+| 4px | `sm` | `rounded-sm` |
+| 8px | `md` | `rounded-md` |
+| 12px | `lg` | `rounded-lg` |
+| Full | `full` | `rounded-full` |
+
+**Default for Berndorf:**
+- Buttons: `radius="none"`
+- Inputs: `radius="none"`
+- Cards: `rounded-none`
+
+---
+
+## Component Mapping Rules
+
+Map Figma components to existing HeroUI components.
+
+### Form Elements
+
+| Figma Component | HeroUI Component | Example |
+|----------------|------------------|---------|
+| Text Input | `<Input />` | `<Input label="Email" />` |
+| Password Input | `<PasswordInput />` | `<PasswordInput label="Password" />` |
+| Text Area | `<Textarea />` | `<Textarea label="Message" />` |
+| Dropdown | `<Select />` | `<Select><SelectItem>...</SelectItem></Select>` |
+| Searchable Dropdown | `<Autocomplete />` | `<Autocomplete items={...} />` |
+| Checkbox | `<Checkbox />` | `<Checkbox>Label</Checkbox>` |
+| Radio Group | `<RadioGroup />` | `<RadioGroup><Radio>...</Radio></RadioGroup>` |
+| Number Input | `<NumberInput />` | `<NumberInput min={1} max={100} />` |
+| Date Picker | `<DatePicker />` | `<DatePicker label="Date" />` |
+| File Upload | `<FileInput />` | `<FileInput accept=".pdf" />` |
+
+### Buttons
+
+| Figma Design | Component Props | Example |
+|-------------|----------------|---------|
+| Filled Primary | `variant="solid" color="primary"` | `<Button variant="solid" color="primary">Submit</Button>` |
+| Outlined | `variant="bordered"` | `<Button variant="bordered">Cancel</Button>` |
+| Text Only | `variant="light"` | `<Button variant="light">Learn More</Button>` |
+| Danger Filled | `variant="solid" color="danger"` | `<Button variant="solid" color="danger">Delete</Button>` |
+| Danger Text | `variant="light" color="danger"` | `<Button variant="light" color="danger">Remove</Button>` |
+
+### Display Components
+
+| Figma Component | HeroUI Component | Example |
+|----------------|------------------|---------|
+| Badge/Tag | `<Chip />` | `<Chip color="success">New</Chip>` |
+| Modal/Dialog | `<Modal />` | `<Modal isOpen={open} onClose={...}>...</Modal>` |
+| Tabs | `<Tabs />` | `<Tabs><Tab>...</Tab></Tabs>` |
+| Breadcrumb | `<Breadcrumbs />` | `<Breadcrumbs><BreadcrumbItem>...</BreadcrumbItem></Breadcrumbs>` |
+| Carousel | `<Carousel />` | `<Carousel items={slides} />` |
+
+### Cards
+
+| Figma Design | Element Component | Example |
+|-------------|-------------------|---------|
+| Product Card | `<ProductCard />` | `<ProductCard name="..." price={...} />` |
+| News Card | `<NewsCard />` | `<NewsCard title="..." image="..." />` |
+| Collection Card | `<CollectionCard />` | `<CollectionCard name="..." />` |
+| Store Card | `<StoreCard />` | `<StoreCard name="..." address="..." />` |
+
+---
+
+## AI Decision Tree
+
+Follow this decision tree when analyzing Figma designs.
+
+### Decision Tree
+
+```
+START: Analyze Figma Component
+│
+├─> Is it a form element?
+│   ├─> YES → Check Form Elements mapping table
+│   │   └─> Use Input, Select, Checkbox, etc.
+│   └─> NO → Continue
+│
+├─> Is it a button?
+│   ├─> YES → Check button style
+│   │   ├─> Filled → variant="solid"
+│   │   ├─> Outlined → variant="bordered"
+│   │   └─> Text only → variant="light"
+│   └─> NO → Continue
+│
+├─> Is it a card showing content?
+│   ├─> YES → Check card type
+│   │   ├─> Product → Use ProductCard
+│   │   ├─> News → Use NewsCard
+│   │   ├─> Collection → Use CollectionCard
+│   │   └─> Custom → Use HeroUI Card with custom content
+│   └─> NO → Continue
+│
+├─> Is it a navigation element?
+│   ├─> YES → Check type
+│   │   ├─> Tabs → Use Tabs
+│   │   ├─> Breadcrumbs → Use Breadcrumbs
+│   │   └─> Menu → Use HeroUI Dropdown
+│   └─> NO → Continue
+│
+├─> Is it an overlay/popup?
+│   ├─> YES → Use Modal
+│   └─> NO → Continue
+│
+├─> Is it a badge/tag?
+│   ├─> YES → Use Chip
+│   └─> NO → Continue
+│
+└─> Custom layout
+    └─> Use div with Tailwind classes
+```
+
+### Analysis Checklist
+
+For each Figma component, ask:
+
+1. **Does an exact UI component exist?**
+   - YES → Use it with proper props
+   - NO → Check element components
+
+2. **Does an element component exist?**
+   - YES → Use it (ProductCard, NewsCard, etc.)
+   - NO → Build with HeroUI primitives
+
+3. **What are the variants/states?**
+   - Hover state?
+   - Active state?
+   - Disabled state?
+   - Loading state?
+
+4. **What are the color tokens?**
+   - Map to primary, secondary, success, danger, default
+
+5. **What is the spacing?**
+   - Map to Tailwind spacing scale
+
+6. **Is it responsive?**
+   - Define breakpoints: sm, md, lg, xl
+
+---
+
+## Examples
+
+### Example 1: Login Form from Figma
+
+**Figma Analysis:**
+- 2 text inputs (email, password)
+- 1 primary button
+- 1 text link
+- Spacing: 24px between elements
+- Colors: Primary blue, gray text
+
+**Code Implementation:**
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Form } from '@/components/ui/form/Form';
+import { Input } from '@/components/ui/Input';
+import { PasswordInput } from '@/components/ui/PasswordInput';
+import { Button } from '@/components/ui/Button';
+import { useTranslations } from 'next-intl';
+
+const schema = z.object({
+  email: z.string().email('Errors.validation.email'),
+  password: z.string().min(8, 'Errors.validation.minLength|{"min":8}'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function LoginForm() {
+  const t = useTranslations('Auth');
+  const form = useForm<FormData>();
+
+  const onSubmit = (data: FormData) => {
+    console.log(data);
+  };
+
+  return (
+    <div className="w-full max-w-md mx-auto">
+      <h1 className="text-2xl font-bold mb-6">{t('login')}</h1>
+
+      <Form form={form} validationSchema={schema}>
+        <Form.Item name="email">
+          {(props) => (
+            <Input
+              {...props}
+              label={t('email')}
+              type="email"
+              placeholder="your@email.com"
+            />
+          )}
+        </Form.Item>
+
+        <Form.Item name="password">
+          {(props) => (
+            <PasswordInput
+              {...props}
+              label={t('password')}
+              placeholder="Enter password"
+            />
+          )}
+        </Form.Item>
+
+        <div className="col-span-10">
+          <Button
+            variant="solid"
+            color="primary"
+            className="w-full"
+            onPress={form.handleSubmit(onSubmit)}
+          >
+            {t('submit')}
+          </Button>
+        </div>
+
+        <div className="col-span-10 text-center">
+          <a href="/auth/forgot-password" className="text-sm text-primary hover:underline">
+            {t('forgotPassword')}
+          </a>
+        </div>
+      </Form>
+    </div>
+  );
+}
+```
+
+### Example 2: Product Grid from Figma
+
+**Figma Analysis:**
+- Grid of product cards
+- 3 columns on desktop, 2 on tablet, 1 on mobile
+- Each card shows image, name, price, add to cart button
+- 24px gap between cards
+
+**Code Implementation:**
+
+```tsx
+'use client';
+
+import { ProductCard } from '@/components/elements/ProductCard';
+import { useProductsQuery } from '@/services/product';
+
+export function ProductGrid() {
+  const { data: products, isLoading } = useProductsQuery();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <h2 className="text-2xl font-bold mb-6">Our Products</h2>
+
+      <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
+        {products?.map((product) => (
+          <ProductCard
+            key={product.id}
+            id={product.id}
+            name={product.name}
+            price={product.price}
+            image={product.primaryImage}
+            onAddToCart={(id) => console.log('Add to cart:', id)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Example 3: Hero Section from Figma
+
+**Figma Analysis:**
+- Full-width background image
+- Centered text overlay
+- Large heading (48px bold)
+- Subheading (18px regular)
+- CTA button
+- 64px padding top/bottom
+
+**Code Implementation:**
+
+```tsx
+import { Button } from '@/components/ui/Button';
+import Image from 'next/image';
+
+export function HeroSection() {
+  return (
+    <div className="relative h-[500px] w-full">
+      {/* Background Image */}
+      <Image
+        src="/hero-background.jpg"
+        alt="Hero background"
+        fill
+        className="object-cover"
+        priority
+      />
+
+      {/* Overlay */}
+      <div className="absolute inset-0 bg-black/40" />
+
+      {/* Content */}
+      <div className="relative z-10 flex h-full flex-col items-center justify-center px-4 py-16 text-center text-white">
+        <h1 className="mb-4 text-5xl font-bold max-w-3xl">
+          Premium Cutlery Collection
+        </h1>
+        <p className="mb-8 text-lg max-w-2xl">
+          Discover our handcrafted cutlery designed for elegance and durability
+        </p>
+        <Button
+          variant="solid"
+          color="primary"
+          size="lg"
+          href="/products"
+        >
+          Explore Collection
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Example 4: Filter Sidebar from Figma
+
+**Figma Analysis:**
+- Sidebar with filters
+- Category checkboxes
+- Price range inputs
+- Apply filters button
+- 16px padding, 12px gaps
+
+**Code Implementation:**
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { Checkbox } from '@/components/ui/Checkbox';
+import { NumberInput } from '@/components/ui/NumberInput';
+import { Button } from '@/components/ui/Button';
+import { useProductStore } from '@/services/product';
+
+export function FilterSidebar() {
+  const [selectedCategories, setSelectedCategories] = useState<string[]>([]);
+  const [minPrice, setMinPrice] = useState(0);
+  const [maxPrice, setMaxPrice] = useState(1000);
+  const setFilters = useProductStore((state) => state.setFilters);
+
+  const handleApply = () => {
+    setFilters({
+      categories: selectedCategories,
+      minPrice,
+      maxPrice,
+    });
+  };
+
+  return (
+    <div className="w-64 border-r border-default-200 p-4">
+      <h3 className="text-lg font-semibold mb-4">Filters</h3>
+
+      {/* Categories */}
+      <div className="mb-6">
+        <h4 className="text-sm font-medium mb-3">Categories</h4>
+        <div className="flex flex-col gap-3">
+          <Checkbox
+            isSelected={selectedCategories.includes('cutlery')}
+            onValueChange={(checked) => {
+              setSelectedCategories(
+                checked
+                  ? [...selectedCategories, 'cutlery']
+                  : selectedCategories.filter(c => c !== 'cutlery')
+              );
+            }}
+          >
+            Cutlery
+          </Checkbox>
+          <Checkbox
+            isSelected={selectedCategories.includes('cookware')}
+            onValueChange={(checked) => {
+              setSelectedCategories(
+                checked
+                  ? [...selectedCategories, 'cookware']
+                  : selectedCategories.filter(c => c !== 'cookware')
+              );
+            }}
+          >
+            Cookware
+          </Checkbox>
+        </div>
+      </div>
+
+      {/* Price Range */}
+      <div className="mb-6">
+        <h4 className="text-sm font-medium mb-3">Price Range</h4>
+        <div className="flex flex-col gap-3">
+          <NumberInput
+            label="Min"
+            value={minPrice}
+            onChange={setMinPrice}
+            min={0}
+          />
+          <NumberInput
+            label="Max"
+            value={maxPrice}
+            onChange={setMaxPrice}
+            min={0}
+          />
+        </div>
+      </div>
+
+      {/* Apply Button */}
+      <Button
+        variant="solid"
+        color="primary"
+        className="w-full"
+        onPress={handleApply}
+      >
+        Apply Filters
+      </Button>
+    </div>
+  );
+}
+```
+
+---
+
+## Quality Checklist
+
+Before completing Figma to code conversion:
+
+### Design Accuracy
+
+- [ ] All colors match design tokens
+- [ ] All spacing matches Tailwind scale
+- [ ] All typography matches design
+- [ ] All components match Figma exactly
+- [ ] Hover states implemented
+- [ ] Active states implemented
+- [ ] Disabled states implemented
+
+### Component Usage
+
+- [ ] Using existing UI components only
+- [ ] No custom UI components created
+- [ ] Element components used where available
+- [ ] Props correctly configured
+- [ ] Variants match design
+
+### Responsive Design
+
+- [ ] Mobile layout tested (< 640px)
+- [ ] Tablet layout tested (640px - 1024px)
+- [ ] Desktop layout tested (> 1024px)
+- [ ] Grid columns adjust correctly
+- [ ] Text sizes scale appropriately
+- [ ] Images are responsive
+
+### Accessibility
+
+- [ ] Alt text for images
+- [ ] Labels for form inputs
+- [ ] Keyboard navigation works
+- [ ] Color contrast meets WCAG AA
+- [ ] Focus states visible
+
+### Code Quality
+
+- [ ] TypeScript types defined
+- [ ] No ESLint errors
+- [ ] Translations used (no hardcoded text)
+- [ ] Proper semantic HTML
+- [ ] Clean, readable code
+
+### Performance
+
+- [ ] Images optimized
+- [ ] No unnecessary re-renders
+- [ ] Lazy loading where appropriate
+- [ ] Bundle size reasonable
+
+---
+
+## Summary
+
+When converting Figma to code:
+
+1. **Analyze design thoroughly** using Figma MCP Server
+2. **Map design tokens** to project tokens
+3. **Use existing components** from UI library
+4. **Follow decision tree** for component selection
+5. **Implement responsively** with Tailwind breakpoints
+6. **Test thoroughly** against design and functionality
+7. **Verify quality** with checklist
+
+## Need More Information?
+
+- **Quick Reference** → See `AI_QUICK_REFERENCE.md`
+- **UI Components** → See `UI_COMPONENTS_GUIDE.md`
+- **Architecture** → See `ARCHITECTURE_PATTERNS.md`
+- **Implementation** → See `IMPLEMENTATION_GUIDE.md`