> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weventures.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Excellence

> Component architecture, design systems, and responsive development

# 🎨 Frontend Development Excellence

<Warning>
  Frontend implementation should strictly follow the design system and patterns identified in the discovery phase
</Warning>

<CardGroup cols={2}>
  <Card title="Component Architecture" icon="layer-group" href="#component-strategy">
    Structured approach to component development
  </Card>

  <Card title="Design System" icon="palette" href="#design-system">
    Consistent visual language from discovery
  </Card>

  <Card title="Responsive Design" icon="mobile" href="#mobile-first">
    Mobile-first with progressive enhancement
  </Card>

  <Card title="RTL & i18n" icon="globe" href="#rtl-support">
    International support when needed
  </Card>
</CardGroup>

## Component Development Strategy

<Tabs>
  <Tab title="Component Hierarchy">
    <Steps>
      <Step title="Base Components (shadcn/ui)">
        <Info>
          Start with shadcn/ui as your foundation - these are your atomic components
        </Info>

        ```bash theme={null}
        # Install base components first
        pnpm dlx shadcn-ui@latest add button card dialog form input

        # Then add as needed
        pnpm dlx shadcn-ui@latest add data-table sheet tabs
        ```

        <AccordionGroup>
          <Accordion title="Essential Components">
            * **Forms**: Form, Input, Label, Textarea, Select, Checkbox, Radio, Switch
            * **Feedback**: Alert, Toast, Dialog, AlertDialog, Tooltip, Progress
            * **Layout**: Card, Separator, ScrollArea, AspectRatio, Container
            * **Navigation**: NavigationMenu, Breadcrumb, Tabs, Pagination
            * **Data Display**: Table, DataTable, Badge, Avatar, Skeleton
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Feature Components">
        <Card title="Composite Components">
          Build feature-specific components combining base components:

          ```typescript theme={null}
          // components/features/user-profile-card.tsx
          import { Card, Avatar, Badge } from '@/components/ui'

          export function UserProfileCard({ user }) {
            return (
              <Card className="p-6">
                <Avatar src={user.avatar} />
                <h3>{user.name}</h3>
                <Badge>{user.role}</Badge>
              </Card>
            )
          }
          ```
        </Card>
      </Step>

      <Step title="Page Layouts">
        <Card title="Layout Components">
          Create consistent page structures:

          ```typescript theme={null}
          // components/layouts/dashboard-layout.tsx
          export function DashboardLayout({ children }) {
            return (
              <div className="min-h-screen">
                <Sidebar />
                <main className="lg:pl-64">
                  <Header />
                  <div className="p-4 md:p-6 lg:p-8">
                    {children}
                  </div>
                </main>
              </div>
            )
          }
          ```
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Advanced Components">
    <Warning>
      Only use advanced component libraries for specific, complex needs identified in discovery
    </Warning>

    <CardGroup>
      <Card title="HeroUI" icon="table">
        **When to use:**

        * Complex data tables with filtering
        * Advanced sorting and pagination
        * Inline editing capabilities
        * Export functionality

        **Implementation:**

        ```typescript theme={null}
        // Wrap in custom component
        import { DataTable } from 'heroui'

        export function AnalyticsTable(props) {
          return (
            <DataTable
              columns={columns}
              data={data}
              features={['sort', 'filter', 'export']}
            />
          )
        }
        ```
      </Card>

      <Card title="Aceternity" icon="sparkles">
        **When to use:**

        * Hero sections with animations
        * Interactive showcases
        * Onboarding flows
        * Marketing pages

        **Note:** Heavy on animations, use sparingly
      </Card>

      <Card title="21st.dev Patterns" icon="lightbulb">
        **When to use:**

        * Need modern UI patterns
        * Looking for inspiration
        * Complex interactions

        **Process:**

        1. Find pattern on 21st.dev
        2. Analyze implementation
        3. Rebuild with shadcn/ui base
        4. Customize for brand
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Design System Implementation

<CodeGroup>
  ```css Complete Design Tokens theme={null}
  /* From discovery phase brand guidelines */

  :root {
    /* Brand Colors from Discovery */
    --brand-primary: #[from-discovery];
    --brand-secondary: #[from-discovery];

    /* Semantic Colors */
    --color-success: #10b981;
    --color-warning: #f59e0b;
    --color-error: #ef4444;
    --color-info: #3b82f6;

    /* Neutral Palette */
    --gray-50: #f9fafb;
    --gray-100: #f3f4f6;
    --gray-200: #e5e7eb;
    --gray-300: #d1d5db;
    --gray-400: #9ca3af;
    --gray-500: #6b7280;
    --gray-600: #4b5563;
    --gray-700: #374151;
    --gray-800: #1f2937;
    --gray-900: #111827;
    --gray-950: #030712;

    /* Spacing System */
    --space-xs: 0.5rem;   /* 8px */
    --space-sm: 1rem;     /* 16px */
    --space-md: 1.5rem;   /* 24px */
    --space-lg: 2rem;     /* 32px */
    --space-xl: 3rem;     /* 48px */
    --space-2xl: 4rem;    /* 64px */

    /* Typography Scale */
    --font-xs: 0.75rem;    /* 12px */
    --font-sm: 0.875rem;   /* 14px */
    --font-base: 1rem;     /* 16px */
    --font-lg: 1.125rem;   /* 18px */
    --font-xl: 1.25rem;    /* 20px */
    --font-2xl: 1.5rem;    /* 24px */
    --font-3xl: 1.875rem;  /* 30px */
    --font-4xl: 2.25rem;   /* 36px */
    --font-5xl: 3rem;      /* 48px */
    --font-6xl: 3.75rem;   /* 60px */

    /* Animation */
    --duration-fast: 150ms;
    --duration-base: 250ms;
    --duration-slow: 350ms;
    --easing-default: cubic-bezier(0.4, 0, 0.2, 1);
    --easing-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  }
  ```

  ```css Glassmorphic Styles theme={null}
  /* Modern glassmorphic design system */

  .glass-card {
    background: rgba(255, 255, 255, 0.6);
    backdrop-filter: blur(12px);
    border: 1px solid rgba(255, 255, 255, 0.18);
    box-shadow:
      0 8px 32px 0 rgba(31, 38, 135, 0.15),
      inset 0 0 0 1px rgba(255, 255, 255, 0.1);
  }

  .glass-card-dark {
    background: rgba(17, 24, 39, 0.6);
    backdrop-filter: blur(12px);
    border: 1px solid rgba(255, 255, 255, 0.08);
    box-shadow:
      0 8px 32px 0 rgba(0, 0, 0, 0.37),
      inset 0 0 0 1px rgba(255, 255, 255, 0.05);
  }

  .glass-button {
    background: rgba(255, 255, 255, 0.15);
    backdrop-filter: blur(8px);
    border: 1px solid rgba(255, 255, 255, 0.25);
    transition: all var(--duration-base) var(--easing-default);
  }

  .glass-button:hover {
    background: rgba(255, 255, 255, 0.25);
    transform: translateY(-2px);
    box-shadow: 0 10px 20px -10px rgba(0, 0, 0, 0.25);
  }
  ```

  ```typescript Component Patterns theme={null}
  // Consistent component patterns from discovery

  // 1. Loading States
  export function LoadingCard() {
    return (
      <Card className="animate-pulse">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </Card>
    )
  }

  // 2. Error States
  export function ErrorState({ error, retry }) {
    return (
      <Card className="border-red-200 bg-red-50">
        <AlertCircle className="text-red-600" />
        <h3>Something went wrong</h3>
        <p>{error.message}</p>
        <Button onClick={retry}>Try again</Button>
      </Card>
    )
  }

  // 3. Empty States
  export function EmptyState({
    icon: Icon = Inbox,
    title,
    description,
    action
  }) {
    return (
      <Card className="text-center py-12">
        <Icon className="mx-auto h-12 w-12 text-gray-400" />
        <h3 className="mt-4">{title}</h3>
        <p className="text-gray-500">{description}</p>
        {action && (
          <Button className="mt-4" onClick={action.onClick}>
            {action.label}
          </Button>
        )}
      </Card>
    )
  }

  // 4. Success Feedback
  export function SuccessMessage({ message, onDismiss }) {
    return (
      <Alert className="border-green-200 bg-green-50">
        <CheckCircle className="text-green-600" />
        <AlertTitle>Success!</AlertTitle>
        <AlertDescription>{message}</AlertDescription>
      </Alert>
    )
  }
  ```
</CodeGroup>

## Mobile-First Responsive Design

<Tabs>
  <Tab title="📱 Responsive Strategy">
    <Steps>
      <Step title="Mobile Base (320px)">
        <Card title="Mobile First Approach">
          Start with mobile design and enhance progressively:

          ```css theme={null}
          /* Base mobile styles */
          .component {
            padding: 1rem;
            font-size: 0.875rem;
          }

          /* Tablet enhancement */
          @media (min-width: 768px) {
            .component {
              padding: 1.5rem;
              font-size: 1rem;
            }
          }

          /* Desktop enhancement */
          @media (min-width: 1024px) {
            .component {
              padding: 2rem;
              font-size: 1.125rem;
            }
          }
          ```
        </Card>
      </Step>

      <Step title="Breakpoint System">
        | Breakpoint | Min Width | Target Devices | Columns |
        | ---------- | --------- | -------------- | ------- |
        | Base       | 320px     | Small phones   | 4       |
        | sm         | 640px     | Phones         | 6       |
        | md         | 768px     | Tablets        | 8       |
        | lg         | 1024px    | Small laptops  | 12      |
        | xl         | 1280px    | Desktops       | 12      |
        | 2xl        | 1536px    | Large screens  | 12      |
      </Step>

      <Step title="Responsive Patterns">
        ```typescript theme={null}
        // Responsive grid example
        <div className="
          grid
          grid-cols-1      // Mobile: 1 column
          sm:grid-cols-2   // Small: 2 columns
          md:grid-cols-3   // Medium: 3 columns
          lg:grid-cols-4   // Large: 4 columns
          gap-4
          md:gap-6
          lg:gap-8
        ">
          {items.map(item => <Card key={item.id} />)}
        </div>

        // Responsive navigation
        <nav className="
          fixed bottom-0 left-0 right-0  // Mobile: bottom nav
          md:static md:top-0              // Tablet: top nav
          lg:fixed lg:left-0 lg:top-0 lg:bottom-0 lg:w-64  // Desktop: sidebar
        ">
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="🌍 RTL & Internationalization">
    <Card title="RTL Implementation Guide">
      Implement full RTL support when required by discovery phase
    </Card>

    <Steps>
      <Step title="CSS Logical Properties">
        ```css theme={null}
        /* Instead of left/right, use logical properties */
        .component {
          /* Old way */
          /* margin-left: 1rem; */
          /* padding-right: 2rem; */

          /* Logical way */
          margin-inline-start: 1rem;
          padding-inline-end: 2rem;
          inset-inline-start: 0;
          border-inline-end: 1px solid;
        }
        ```
      </Step>

      <Step title="Tailwind RTL Classes">
        ```jsx theme={null}
        // RTL-aware Tailwind classes
        <div className="
          text-left rtl:text-right
          ml-4 rtl:ml-0 rtl:mr-4
          space-x-4 rtl:space-x-reverse
          divide-x rtl:divide-x-reverse
        ">
          <button className="
            pl-4 pr-8
            rtl:pl-8 rtl:pr-4
            border-l-4
            rtl:border-l-0 rtl:border-r-4
          ">
            <ChevronRight className="rtl:rotate-180" />
          </button>
        </div>
        ```
      </Step>

      <Step title="i18n Implementation">
        ```typescript theme={null}
        // i18n configuration
        import { useTranslation } from 'next-i18next'

        export function Component() {
          const { t, i18n } = useTranslation()
          const isRTL = ['ar', 'he', 'fa'].includes(i18n.language)

          return (
            <div dir={isRTL ? 'rtl' : 'ltr'}>
              <h1>{t('welcome')}</h1>
            </div>
          )
        }
        ```
      </Step>
    </Steps>

    <Warning>
      Test RTL thoroughly with native speakers - automatic RTL is rarely perfect
    </Warning>
  </Tab>
</Tabs>

***

<Card title="Next Step" icon="arrow-right" href="/ai-development/prompting/backend">
  With frontend patterns established, proceed to backend architecture →
</Card>