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)