Frontend Skill

Scope: UI development — React components, API consumption, design patterns

This skill applies when working on the React frontend, component development, or UI/UX implementation.

Technology Stack

• •React 19 + TypeScript
• •Vite for bundling
• •TailwindCSS v4 for styling
• •Framer Motion for animations
• •React Router for navigation
• •Supabase JS for auth and data

Project Structure

frontend/src/
├── components/
│   ├── Chat/           # Chat interface
│   ├── Form/           # Schema-driven forms
│   ├── Views/          # Entity CRUD views
│   ├── Focus/          # Detail overlays
│   ├── Onboarding/     # User setup flow
│   ├── Auth/           # Login
│   └── Layout/         # App shell
├── context/            # React Context providers
├── hooks/              # Custom hooks
└── lib/                # Utilities

API Consumption

Chat Endpoint

POST /api/chat
Body: {
  message: string,
  conversation_id?: string,
  ui_changes?: UIChange[]
}
Response: {
  response: string,
  conversation: object,
  entities?: object[]
}

CRUD Endpoints

GET    /api/{entity_type}         // List all
GET    /api/{entity_type}/{id}    // Get one
POST   /api/{entity_type}         // Create
PUT    /api/{entity_type}/{id}    // Update
DELETE /api/{entity_type}/{id}    // Delete

Entity types: recipes, inventory, shopping, meal-plans, tasks

Auth Header

All requests include: Authorization: Bearer <supabase_token>

Component Patterns

Schema-Driven Forms

Forms are generated from shared entity schemas:

Entity Views

Focus Overlays

Detail views that slide over the current view:

• •FocusOverlay.tsx — Container with backdrop
• •RecipeDetail.tsx — Full recipe with ingredients/steps
• •MealPlanDetail.tsx — Meal plan with linked recipe

Chat Interface

@-Mention System

Users can reference entities in chat using @ mentions.

Flow

1. •User types @ in ChatInput
2. •Autocomplete dropdown appears (grouped by entity type)
3. •User searches/selects entity
4. •Mention inserted: @[Butter Chicken](recipe:uuid-123)
5. •AI receives full entity data in context

Entity Types

State Management

ChatContext

// context/ChatContext.tsx
const { messages, sendMessage, pushUIChange } = useChatContext();

// Notify AI of user actions
pushUIChange({
  entity_type: "recipe",
  entity_id: uuid,
  action: "created",
  label: "Butter Chicken"
});

useEntities Hook

const {
  entities,
  loading,
  create,
  update,
  delete: remove
} = useEntities("recipes");

AI Context Integration

The frontend notifies the AI of user actions so it maintains awareness.

UI Changes → AI Context

When users CRUD via UI, track changes for the next chat message:

// After creating/updating/deleting via EntityForm or Views
pushUIChange({
  entity_type: "recipe",
  entity_id: uuid,
  action: "created",  // "created" | "updated" | "deleted"
  label: "Butter Chicken"
});

These are sent with chat messages and registered as created:user, updated:user, deleted:user in the AI's context.

@-Mentions → AI Context

When users @-mention, the full entity data is injected:

// ChatInput builds mentioned_entities from @-mentions
{
  "mentioned_entities": [{
    "ref_type": "recipe",
    "uuid": "uuid-123",
    "label": "Butter Chicken",
    "data": { /* full recipe data */ }
  }]
}

The AI sees this as mentioned:user with full data available.

What AI Sees

See docs/architecture/context-and-session.md for backend details.

UX Rules

• •Entity cards show status badges (created, updated, deleted)
• •Loading states use skeleton components
• •Errors display inline with retry option
• •Forms validate on blur, submit on Enter
• •Toast notifications for success/error feedback

Mobile Responsiveness Patterns

Breakpoints

Using Tailwind defaults: sm (640px), md (768px), lg (1024px)

Action Button Visibility

Edit/Delete buttons use hover-reveal on desktop, always visible on mobile:

className="md:opacity-0 md:group-hover:opacity-100 ..."

Text Truncation in Flex Containers

For flex items with variable-length text:

<div className="flex items-center gap-3 min-w-0">     {/* min-w-0 allows shrinking */}
  <span className="shrink-0 ...">Badge</span>          {/* Prevent badge shrinking */}
  <span className="truncate ...">Long text here</span> {/* Truncate with ellipsis */}
</div>

Responsive Layouts

Tables don't work well on mobile. Use dual layouts:

{/* Mobile: Cards */}
<div className="md:hidden space-y-3">
  {items.map(item => <Card key={item.id} />)}
</div>

{/* Desktop: Table */}
<div className="hidden md:block">
  <table>...</table>
</div>

Examples: InventoryView.tsx, ShoppingView.tsx

Commands

cd frontend
npm install            # Install deps
npm run dev            # Vite dev server
npm run build          # Production build
npm run lint           # ESLint

Key Files

Related Docs

• •docs/architecture/capabilities.md — User-facing capabilities
• •docs/specs/onboarding-spec.md — Onboarding flow