Building Webapp React Components

React Web App (Components, Pages, Layout)

Use this skill whenever you are editing React/TSX code in the web app (creating or modifying components, pages, header/footer, or layout).

Step 1 — Identify the type of component

Determine which of these three categories the request falls into, then follow the corresponding section below:

• Page — user wants a new routed page (e.g. "add a contacts page", "create a dashboard page", "add a settings section")
• Header / Footer — user wants a site-wide header, footer, nav bar, or page footer that appears on every page
• Component — everything else: a widget, card, table, form, dialog, or other UI element placed within an existing page

If it is not immediately clear from the user's message, ask:

"Are you looking to add a new page, a site-wide header or footer, or a component within an existing page?"

Then follow the matching section.

---

Clarifying Questions

Ask one question at a time and wait for the response before asking the next. Stop when you have enough to build accurately — do not guess or assume.

For a Page

1. What is the name and purpose of the page? (e.g., Contacts, Dashboard, Settings) 2. What URL path should it use? (e.g., /contacts, /dashboard) — or derive from the page name? 3. Should the page appear in the navigation menu? 4. Who can access it? Public, authenticated users only (PrivateRoute), or unauthenticated only (e.g., login — AuthenticationRoute)? 5. What content or sections should the page include? (list, form, table, detail view, etc.) 6. Does it need to fetch any data? If so, from where?

For a Header / Footer

1. Header, footer, or both? 2. What should the header contain? (logo/app name, nav links, user avatar, CTA button, etc.) 3. What should the footer contain? (copyright text, links, social icons, etc.) 4. Should the header be sticky (fixed to top while scrolling)? 5. Is there a logo or brand name to display? (or placeholder?) 6. Any specific color scheme or style direction? (dark background, branded primary color, minimal, etc.) 7. Should navigation links appear in the header? If so, which pages?

For a Component

1. What should the component do? (display data, accept input, trigger an action, etc.) 2. What page or location should it appear on? 3. Is this shared/reusable across pages, or specific to one feature? (determines file location) 4. What data or props does it need? (static content, props, fetched data) 5. Does it need internal state? (loading, toggle, form state, etc.) 6. Are there any specific shadcn components to use? (Card, Table, Dialog, Form, etc.) 7. Should it appear in a specific layout position? (full-width, sidebar, inline, etc.)

---

Implementation

Once you have identified the type and gathered answers to the clarifying questions, read and follow the corresponding implementation guide:

• Page — read implementation/page.md and follow the instructions there.
• Header / Footer — read implementation/header-footer.md and follow the instructions there.
• Component — read implementation/component.md and follow the instructions there.

---

TypeScript Standards

• Never use `any` — use proper types, generics, or unknown with type guards.
• Event handlers: (event: React.FormEvent<HTMLFormElement>): void
• State: useState<User | null>(null) — always provide the type parameter.
• No unsafe assertions (obj as User). Use type guards:

  function isUser(obj: unknown): obj is User {
    return typeof obj === 'object' && obj !== null && typeof (obj as User).id === 'string';
  }

---

Verification (MANDATORY)

Before completing, run from the web app directory force-app/main/default/webapplications/<appName>/:

cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build

• Lint: MUST result in 0 errors.
• Build: MUST succeed (includes TypeScript check).

If either fails, fix the errors and re-run. Do not leave the session with failing quality gates.

Implementation — Component

Rules

1. Always use shadcn components from @/components/ui — never build raw HTML equivalents for buttons, inputs, cards, alerts, tabs, tables, or labels. 2. All styling via Tailwind — utility classes only. No inline style={{}}, CSS Modules, or other styling systems. 3. Use design tokens — prefer bg-background, text-foreground, text-muted-foreground, border, bg-primary, text-destructive, rounded-lg over hardcoded colors. 4. Use `cn()` from @/lib/utils for conditional or composable class names. 5. TypeScript — functional components with typed props interface; always accept className?: string.

File Location — Component

Component Structure

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui";
import { cn } from "@/lib/utils";

interface MyComponentProps {
  title: string;
  value: string;
  className?: string;
}

export function MyComponent({ title, value, className }: MyComponentProps) {
  return (
    <Card className={cn("border", className)}>
      <CardHeader>
        <CardTitle className="text-sm font-medium">{title}</CardTitle>
      </CardHeader>
      <CardContent>
        <p className="text-2xl font-semibold text-foreground">{value}</p>
      </CardContent>
    </Card>
  );
}

State and Hooks

• Local state only: keep useState, useReducer, useRef inside the component.
• Shared or complex state: extract to a custom hook in src/hooks/ (prefix with use, e.g. useFormData). Do this when more than one component needs the state, or when multiple hooks are composed together.

Adding the Component to a Page

// In the target page file, e.g. src/pages/HomePage.tsx
import { MyComponent } from "@/components/<feature>/MyComponent";

export default function HomePage() {
  return (
    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
      <MyComponent title="Status" value="Active" />
    </div>
  );
}

Useful Patterns — Component

• Programmatic navigation: use useNavigate from react-router; call navigate(path) — consistent with GlobalSearchInput, SearchResultCard, MaintenanceTable, and other components in the web application.
• Page container: max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12
• Icons: lucide-react; add aria-hidden="true" on decorative icons
• Focus styles: use focus-visible: variants
• Multiple visual variants: use CVA (cva) and VariantProps
• shadcn import barrel: import { Button, Card, Input } from "@/components/ui"

Confirm — Component

• Imports use path aliases (@/, not deep relative paths)
• No raw <button>, <input>, or styled <div> where shadcn equivalents exist
• No inline style={{}} — Tailwind only

Implementation — Header / Footer

Rules

1. Edit `appLayout.tsx` only — header and footer are layout-level concerns. Never add them to individual page files. 2. Never modify `routes.tsx` or `app.tsx` — the router setup must remain intact. 3. Create component files in `src/components/layout/` — the designated location for layout-level components. 4. Use the full-height flex column pattern — wrap layout in min-h-screen flex flex-col so footer stays at bottom. 5. Use shadcn and Tailwind — compose from @/components/ui; style with Tailwind utility classes and design tokens. 6. Use path aliases — import with @/components/layout/... and @/components/ui; no deep relative paths. 7. Preserve existing content — if appLayout.tsx already has a <NavigationMenu /> or other shell elements, keep them in place.

Step 1 — Create the header component (if requested)

Create src/components/layout/AppHeader.tsx:

import { cn } from "@/lib/utils";

interface AppHeaderProps {
  className?: string;
}

export function AppHeader({ className }: AppHeaderProps) {
  return (
    <header
      className={cn(
        "w-full border-b bg-background px-4 sm:px-6 lg:px-8 py-4",
        className,
      )}
    >
      <div className="max-w-7xl mx-auto flex items-center justify-between">
        <span className="text-lg font-semibold text-foreground">My App</span>
      </div>
    </header>
  );
}

Step 2 — Create the footer component (if requested)

Create src/components/layout/AppFooter.tsx:

import { cn } from "@/lib/utils";

interface AppFooterProps {
  className?: string;
}

export function AppFooter({ className }: AppFooterProps) {
  return (
    <footer
      className={cn(
        "w-full border-t bg-background px-4 sm:px-6 lg:px-8 py-4",
        className,
      )}
    >
      <div className="max-w-7xl mx-auto text-center text-sm text-muted-foreground">
        &copy; {new Date().getFullYear()} My App. All rights reserved.
      </div>
    </footer>
  );
}

Step 3 — Edit appLayout.tsx

Open src/appLayout.tsx — this is the only file to modify for layout-level additions. Wrap existing content in a flex column and add header above and footer below <Outlet />:

import { Outlet } from "react-router";
import { AppHeader } from "@/components/layout/AppHeader";
import { AppFooter } from "@/components/layout/AppFooter";
// Keep all existing imports unchanged

export default function AppLayout() {
  return (
    <div className="min-h-screen flex flex-col bg-background">
      <AppHeader />
      {/* Keep any existing NavigationMenu or other shell elements here */}
      <main className="flex-1">
        <Outlet />
      </main>
      <AppFooter />
    </div>
  );
}

File Locations — Header / Footer

Why appLayout.tsx — Not Pages or Routes

AppLayout is the single shell rendered at the root route. Every page is a child rendered via <Outlet />. Placing the header and footer here ensures they appear on every page without touching individual pages or the route registry.

AppLayout (appLayout.tsx)
├── AppHeader          ← renders on every page
├── NavigationMenu     ← keep if already present
├── <Outlet />         ← active page renders here
└── AppFooter          ← renders on every page

Useful Patterns — Header / Footer

• Sticky header: add sticky top-0 z-50 to the <header> element
• Separator: use <Separator /> from @/components/ui instead of border-b/border-t if a visible divider is preferred
• Nav links in header: use <Button variant="ghost" asChild> wrapping a React Router <Link>
• Icons: lucide-react; add aria-hidden="true" on decorative icons
• Design tokens: bg-background, text-foreground, text-muted-foreground, border, bg-primary

Mobile hamburger / Menu icon — Must be functional

If the header includes a hamburger or Menu icon for mobile:

• Do not add a Menu/hamburger icon that does nothing. It must toggle a visible mobile menu.
• Required: (1) State: const [isOpen, setIsOpen] = useState(false). (2) Button: onClick={() => setIsOpen(!isOpen)}, aria-label="Toggle menu". (3) Conditional panel: {isOpen && ( <div>...nav links...</div> )} with responsive visibility (e.g. md:hidden). (4) Close on navigate: each link in the panel should onClick={() => setIsOpen(false)}.
• Implement in appLayout.tsx (or the component that owns the header). Use the Menu icon from lucide-react.

Confirm — Header / Footer

• Header and footer appear on every page (navigate to at least two routes)
• Imports use path aliases (@/components/layout/...)
• No inline style={{}} — Tailwind only
• src/routes.tsx and src/app.tsx are unchanged

Implementation — Page

Rules

1. Edit the component that owns the UI, never output raw HTML — When editing the home page or any page content, modify the actual .tsx file that renders the target. If the target is inside a child component (e.g. <GlobalSearchInput /> in Home.tsx), edit the child's file (e.g. GlobalSearchInput.tsx), not the parent. Do not wrap the component with extra elements in the parent; go into the component and change its JSX. Do not paste or generate raw HTML. 2. `routes.tsx` is the only route registry — never add routes in app.tsx or inside page files. 3. All pages are children of the AppLayout route — do not create top-level routes that bypass the layout shell. 4. Default export per page — each page file has exactly one default-export component. 5. Path aliases in all imports — use @/pages/..., @/components/...; no deep relative paths. 6. No inline styles — Tailwind utility classes and design tokens only. 7. Catch-all last — path: '*' (NotFound) must always remain the last child in the layout route. 8. Never modify `appLayout.tsx` when adding a page — layout changes are a separate concern.

Step 1 — Create the page file

Create src/pages/MyPage.tsx with a default export and the standard page container:

export default function MyPage() {
  return (
    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
      <h1 className="text-3xl font-bold text-foreground">My Page</h1>
      <p className="mt-4 text-muted-foreground">Page content goes here.</p>
    </div>
  );
}

Use shadcn components from @/components/ui for UI elements. All styling via Tailwind — no inline style={{}}.

Step 2 — Register the route in routes.tsx

Open src/routes.tsx. Import the page and add it inside the layout route's children array:

import MyPage from "@/pages/MyPage";

// Inside the layout route's children array (before the catch-all):
{
  path: "my-page",
  element: <MyPage />,
  handle: { showInNavigation: true, label: "My Page" },
},

• path is a relative segment (e.g., "contacts"), not an absolute path.
• Include handle: { showInNavigation: true, label: "Label" } only if the page should appear in the navigation menu.
• The catch-all path: '*' must stay last.

Step 3 — Apply an auth guard (if needed)

Example — private page:

import { PrivateRoute } from "@/components/auth/private-route";

{
  path: "settings",
  element: <PrivateRoute><SettingsPage /></PrivateRoute>,
  handle: { showInNavigation: true, label: "Settings" },
},

Use ROUTES.* constants from @/utils/authenticationConfig for auth-related paths — do not hardcode /login, /profile, etc.

File Conventions — Page

State and Data

• Local state: useState, useReducer, useRef inside the page component
• Shared or complex state: extract to src/hooks/ with a use prefix (e.g., useContacts)
• Data fetching: prefer GraphQL (executeGraphQL) or REST utilities in src/api/; place shared data logic in src/hooks/
• Auth context: useAuth() from @/context/AuthContext when current user is needed — only valid under AuthProvider

Confirm — Page

• The page renders inside the app shell (header/nav visible)
• If showInNavigation: true, the link appears in the navigation menu
• No TypeScript errors; no broken imports; no missing exports
• Imports use path aliases (@/, not deep relative paths)