Skip to content

Component Naming Conventions

How to name and organise components in the NepWalk design system. Follows Atomic Design + React/Next.js conventions.

Atomic Design Levels

Level What it is Examples
Atom Smallest reusable element. Single purpose. No smaller parts. Button, Input, Badge, Icon, Avatar, Toggle, Spinner, Toast, Tooltip, Divider
Molecule 2+ atoms combined. Single responsibility. FormField, TimelineItem, TripCard, DayCard, MemberRow, NotificationItem, SearchBar, EmptyState, PackageCard
Organism Composed of molecules. A full UI section. NavigationBar, TripHeader, ItineraryBuilder, PackagePicker, SharePanel, DashboardSummary, ConfirmDialog
Page Composed of organisms. A full screen. Dashboard, Login, Register, TripDetail, Itinerary, Members, Share, Packages, Notifications, Profile, Settings

Naming Rules

React/Next.js component names (code)

  • Always PascalCase
  • No abbreviations
  • Name describes what it IS, not what it does
Button          ✅
Btn             ❌
TripCard        ✅
Card            ❌  (too generic)
TimelineItem    ✅
TimelineEntry   ❌  (inconsistent with catalog)

File names (code)

  • Always kebab-case.tsx
  • Match the component name exactly
button.tsx           → Button
trip-card.tsx        → TripCard
timeline-item.tsx    → TimelineItem
navigation-bar.tsx   → NavigationBar

Design file names (Stitch prompts, specs)

  • Always kebab-case
  • Match the React component name
stitch_prompts/components/button.md
stitch_prompts/components/timeline-item.md
stitch_prompts/components/navigation-bar.md
stitch_prompts/pages/dashboard.md
pages/dashboard_spec_v1.md

Props naming (React)

  • camelCase for all props
  • Variant prop is always variant (not type or kind)
  • Size prop is always size (not sz or dimension)
  • Boolean props use is prefix for state: isLoading, isDisabled, isSelected
  • Event handlers use on prefix: onPress, onSelect, onDismiss
// Correct
<Button variant="primary" size="md" isLoading={false} onPress={handleSave} />

// Wrong
<Button type="primary" sz="medium" loading={false} onClick={handleSave} />

CSS / Token class names

  • Token names: kebab-case matching design system
  • CSS classes: Tailwind utility classes (no custom CSS unless unavoidable)
color-primary         ✅ (design token name)
colorPrimary          ❌
space-4               ✅ (spacing token)
spacing-medium        ❌

Variant names (standardised)

Use these exact names across all components for consistency:

Concept Correct names Wrong names
Button styles primary, secondary, ghost, danger, icon-only default, outlined, text, destructive
Sizes sm, md, lg small, medium, large, xs, xl
States default, hover, active, focus, disabled, loading idle, pressed, inactive, busy
Status badges draft, active, archived, published pending, live, deleted, visible
Input types text, email, password, search, textarea, number, date string, pass, area

Adding a new component

Before adding a new component to the catalog:

  1. Check if an existing component can be extended (add a variant or state).
  2. Check if a library component (shadcn/ui) covers the need.
  3. If truly new: decide the atomic level (atom/molecule/organism).
  4. Name it using the rules above.
  5. Add it to component_catalog.md with all variants and states defined.
  6. Then generate the Stitch component sheet via design: component <name>.

Never name a component before adding it to the catalog. The catalog is the source of truth for names.