afv-library/skills/building-ui-bundle-frontend/implementation/component.md

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 type	Location	Export
Shared UI primitive (reusable across features)	src/components/ui/ — add to index.ts	Named export
Feature-specific (e.g., dashboard widget)	src/components/<feature>/	Named export, import directly where used
Page-level layout element	src/components/layout/	Named export

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 UI bundle.
• 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