BMAD-METHOD/demos/early-v3alpha-full-stack-app-demo/10-sharded-docs/front-end-component-guide.md

Component Breakdown & Implementation Details

This document is a granulated shard from the main "5-front-end-architecture.md" focusing on "Component Library, Reusable UI Components Guide, Atomic Design Elements, or Component Breakdown & Implementation Details".

This section outlines the conventions and templates for defining UI components. While a few globally shared or foundational components (e.g., main layout structures) might be specified here upfront to ensure consistency, the detailed specification for most feature-specific components will emerge as user stories are implemented. The key is for the development team (or AI agent) to follow the "Template for Component Specification" below whenever a new component is identified for development.

Component Naming & Organization

• Component File Naming:

  • React component files will use PascalCase.tsx. For example, NewsletterCard.tsx, PodcastPlayer.tsx.
  • Next.js special files like page.tsx, layout.tsx, loading.tsx, error.tsx, global-error.tsx, and not-found.tsx will use their conventional lowercase or kebab-case names.

• Component Organization (Reiteration from Directory Structure):

  • Application-Specific Core Components: Reusable components specific to BMad DiCaster (e.g., NewsletterCard, PodcastPlayer) will reside in app/components/core/.
  • Application-Specific Layout Components: Components used for structuring page layouts (e.g., PageWrapper.tsx) will reside in app/components/layout/.
  • Shadcn UI Components: Components added via the Shadcn UI CLI will reside in components/ui/ (e.g., Button.tsx, Card.tsx).
  • Page-Specific Components: If a component is complex but only used on a single page, it can be co-located with that page's route file, for instance, in a components subfolder within that route's directory. However, the preference is to place reusable components in app/components/core/ or app/components/layout/.

Template for Component Specification

This template should be used to define and document each significant UI component identified from the UI/UX Specification (docs/ui-ux-spec.txt) and any subsequent design iterations. The goal is to provide sufficient detail for a developer or an AI agent to implement the component with minimal ambiguity. Most feature-specific components will be detailed emergently during development, following this template.

---

Component: {ComponentName} (e.g., NewsletterCard, PodcastPlayerControls)

• Purpose: {Briefly describe what this component does and its primary role in the user interface. What user need does it address?}
• Source File(s): {e.g., app/components/core/NewsletterCard.tsx}
• Visual Reference: {Link to specific Figma frame/component if available, or a detailed description/sketch if not. If based on a Shadcn UI component, note that and any key customizations.}
• Props (Properties): {List each prop the component accepts. Specify its name, TypeScript type, whether it's required, any default value, and a clear description.}

  Prop Name	Type	Required?	Default Value	Description
  exampleProp	string	Yes	N/A	Example string prop.
  items	Array<{id: string, name: string}>	Yes	N/A	An array of item objects to display.
  variant	'primary' | 'secondary'	No	'primary'	Visual variant of the component.
  onClick	(event: React.MouseEvent) => void	No	N/A	Optional click handler.

• Internal State (if any): {Describe any significant internal state the component manages using React hooks (e.g., useState).}

  State Variable	Type	Initial Value	Description
  isLoading	boolean	false	Tracks if data for the component is loading.
  selectedItem	string | null	null	Stores the ID of the currently selected item.

• Key UI Elements / Structure (Conceptual): {Describe the main visual parts of the component and their general layout. Reference Shadcn UI components if used as building blocks.}

  // Example for a Card component
  <Card>
    <CardHeader>
      <CardTitle>{"{{titleProp}}"}</CardTitle>
      <CardDescription>{"{{descriptionProp}}"}</CardDescription>
    </CardHeader>
    <CardContent>{/* {list of items or main content} */}</CardContent>
    <CardFooter>{/* {action buttons or footer content} */}</CardFooter>
  </Card>
  

• Events Handled / Emitted:
  • Handles: {List significant DOM events the component handles directly.}
  • Emits (Callbacks): {If the component uses props to emit events (callbacks) to its parent, list them here.}
• Actions Triggered (Side Effects):
  • State Management (Zustand): {If the component interacts with a Zustand store, specify which store and actions.}
  • API Calls / Data Fetching: {Specify how Client Components trigger mutations or re-fetches (e.g., Server Actions).}
• Styling Notes:
  • {Reference to specific Shadcn UI components used.}
  • {Key Tailwind CSS classes or custom styles for the "synthwave" theme.}
  • {Specific responsiveness behavior.}
• Accessibility (AX) Notes:
  • {Specific ARIA attributes needed.}
  • {Keyboard navigation considerations.}
  • {Focus management details.}
  • {Notes on color contrast.}

---

This template will be applied to each new significant component during the development process.