Component Naming

Component Naming Conventions

Use this guide when creating or modifying React components to ensure consistent naming across the portfolio.

Naming Rules

1. PascalCase for Components

All React components use PascalCase:

// ✅ Good
export const FeaturedPost = () => {};
export const TagFilter = () => {};

// ❌ Bad
export const featuredPost = () => {};
export const featured_post = () => {};

2. Domain + Role Pattern

Combine domain context with component role for clarity:

// ✅ Good - Clear domain and role
export const FeaturedPost = () => {};     // Featured (domain) + Post (role)
export const TagFilter = () => {};        // Tag (domain) + Filter (role)
export const ReadingProgress = () => {};  // Reading (domain) + Progress (role)
export const MetricCard = () => {};       // Metric (domain) + Card (role)
export const HeroSection = () => {};      // Hero (domain) + Section (role)

// ❌ Bad - Too generic or unclear
export const Card = () => {};             // No domain context
export const Filter = () => {};           // No specificity
export const Section = () => {};          // Meaningless

3. Compound Components for Subparts

Use dot notation for related subcomponents:

// ✅ Good - Compound component pattern
export const PostCard = () => {};
PostCard.Image = () => {};
PostCard.Title = () => {};
PostCard.Meta = () => {};

// Usage
<PostCard>
  <PostCard.Image src={...} />
  <PostCard.Title>...</PostCard.Title>
  <PostCard.Meta date={...} />
</PostCard>

// ❌ Bad - Flat naming for related components
export const PostCardImage = () => {};
export const PostCardTitle = () => {};
export const PostCardMeta = () => {};

4. Avoid Problematic Suffixes

Never use these suffixes:

// ❌ Avoid these suffixes
export const CardContainer = () => {};    // -Container
export const PostWrapper = () => {};      // -Wrapper
export const DataComponent = () => {};    // -Component
export const ListElement = () => {};      // -Element

// ✅ Use clear domain + role instead
export const MetricCard = () => {};
export const PostList = () => {};
export const TagBadge = () => {};

5. Avoid Layout/Styling Descriptions

Names should describe purpose, not appearance:

// ❌ Bad - Describes layout/styling
export const LeftSidebar = () => {};
export const BigHeader = () => {};
export const RedButton = () => {};
export const TwoColumnGrid = () => {};

// ✅ Good - Describes purpose
export const NavigationSidebar = () => {};
export const PageHeader = () => {};
export const DangerButton = () => {};
export const BentoGrid = () => {};

File Naming Convention

Files use kebab-case matching the component name:

Component Location

Validation Checklist

When reviewing component names:

• Uses PascalCase
• Has clear domain context (not just "Card", "List", "Item")
• Has clear role (Chart, Card, List, Section, Filter, etc.)
• No -Container, -Wrapper, -Component suffixes
• No layout/styling descriptions (Left, Big, Red, TwoColumn)
• File name matches component in kebab-case
• Related subcomponents use compound pattern

Examples for Blog Redesign

Good patterns:

Anti-patterns to avoid:

• Generic names: Card, Grid, List, Section
• Layout names: LeftPanel, MainContent, TopSection
• Suffix pollution: CardContainer, ListWrapper, PostComponent

Related Files

• .claude/skills/design-language-system/SKILL.md - Design system guidelines
• apps/blog/src/components/ - Blog components
• apps/blog/src/components/ui/ - shadcn/ui (do not modify)