frontend-page

name	frontend-page
description	Execute page designs from the design doc — compose shadcn components and wire to generated API types. Phase 4 execution, no re-design.

Frontend Page Execution

Build frontend pages by composing shadcn components and wiring them to api-types-mcp generated API client functions.

This skill EXECUTES. It does NOT design. Load the design doc from `docs/metaforge/specs/` first. The page tree, data sources, and component needs are already specified there. Only ask the user about gaps or ambiguities — never re-design pages, routes, or component choices that are already in the spec.

When to Use

• After api-client-gen has generated typed API functions (Phase 3 of feature cycle)
• Phase 4 of a fullstack feature cycle — before verification-before-completion
• User asks to "build a page", "create a view", "make the UI for X"

Prerequisites

• shadcn initialized in the frontend project (via shadcn-mcp or scaffold-mcp scaffold)
• API client generated via api-types-mcp generate_api_client
• Design doc exists at docs/metaforge/specs/ with page tree and component inventory

File Protection

Two directories are MCP-managed. Never edit files within them directly:

Directory	Managed By	Purpose
src/api/	api-types-mcp	Generated client, namespaces, and types
src/components/ui/	shadcn-mcp	shadcn component source files

If you need a component that doesn't exist, use shadcn-mcp to add it. If the API client is stale, re-run generate_api_client.

Process

Step 1: Load Design Doc

Read the design doc from docs/metaforge/specs/. Extract the page tree and component inventory:

• Routes, data sources, and user actions per page
• shadcn components each page needs
• Reusable patterns across pages

Step 2: Query API Types for Usage

Use api-types-mcp query_api_types to find the right functions and understand their signatures:

query_api_types({ query: "find article with pagination" })
query_api_types({ query: "create comment", operation: "create" })
query_api_types({ query: "how to filter by category", contentType: "article" })

Each result includes function signatures, TSDoc descriptions, and code snippets.

Step 3: Add Required shadcn Components

Use shadcn-mcp to add components to the project:

# Via shadcn-mcp tools:
# - search_components: find relevant components
# - get_component: add a component to the project

Step 4: Create the Page Component

Create a new .tsx file under src/pages/.

Page structure pattern:

import { useEffect, useState } from "react";
import { createStrapiClient, type Article } from "@/api";
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";

const api = createStrapiClient({
  baseUrl: import.meta.env.VITE_API_URL,
  token: import.meta.env.VITE_STRAPI_TOKEN,
});

export function ArticlesPage() {
  const [items, setItems] = useState<Article[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function loadItems() {
    setLoading(true);
    setError(null);
    try {
      const result = await api.articles.find({ sort: ["createdAt:desc"] });
      setItems(result);
    } catch (e) {
      setError(e instanceof Error ? e.message : "Failed to load");
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => { loadItems(); }, []);

  if (error) return <div className="p-6 text-red-500">{error}</div>;

  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold mb-4">Articles</h1>
      {loading ? (
        <div>Loading…</div>
      ) : (
        <Table>
          <TableHeader>
            <TableRow>
              <TableHead>Title</TableHead>
              <TableHead>Status</TableHead>
            </TableRow>
          </TableHeader>
          <TableBody>
            {items.map((item) => (
              <TableRow key={item.id}>
                <TableCell>{item.title}</TableCell>
                <TableCell>{item.status}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      )}
    </div>
  );
}

Step 5: Add the Route

Register the page in the router (src/router.tsx or src/App.tsx):

import { BrowserRouter, Routes, Route } from "react-router-dom";
import { ArticlesPage } from "@/pages/ArticlesPage";

export function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/articles" element={<ArticlesPage />} />
      </Routes>
    </BrowserRouter>
  );
}

Step 6: Verify the Page Works

1. Start the frontend dev server: cd frontend && npm run dev
2. Navigate to the page route in the browser
3. Verify data loads from Strapi (check network tab for API calls)
4. Test any forms or interactive elements

Step 7: Commit

git add frontend/src/pages/ frontend/src/App.tsx
git commit -m "checkpoint:feature/pages"

Component Selection Guide

UI Pattern	shadcn Components
List/table of data	table, badge (status), pagination
Create/edit form	form, input, select, textarea, button
Detail view	card, skeleton (loading state)
Confirmation	dialog, alert-dialog
Navigation	breadcrumb, tabs, navigation-menu
Feedback	toast, sonner, alert

API Wiring Patterns

List with filters and pagination

const [params, setParams] = useState<ArticleFindParams>({
  pagination: { page: 1, pageSize: 10 },
  sort: ["createdAt:desc"],
  filters: { status: { $eq: "published" } },
});

useEffect(() => {
  api.articles.find(params).then(setItems);
}, [params]);

Create entry from form

async function handleCreate(formData: Omit<Article, "id" | "createdAt" | "updatedAt">) {
  const created = await api.articles.create(formData);
  setItems((prev) => [created, ...prev]);
}

Delete with confirmation

async function handleDelete(id: number) {
  await api.articles.delete(id);
  setItems((prev) => prev.filter((item) => item.id !== id));
}

Call a custom route

const featured = await api.articles.featured({ limit: 5 });

File Protection Reminder

After page creation:

• src/api/ files are owned by api-types-mcp — re-run generate_api_client, don't edit
• src/components/ui/ files are owned by shadcn-mcp — re-add, don't edit
• src/pages/ files are yours — edit freely