add-frontend-feature
Build new frontend features (pages, components, forms) following TheSmartHost project conventions and patterns.
SKILL.md.claude/skills/add-frontend-feature/SKILL.md
GitHubAdd Frontend Feature
Instructions for building new UI features, pages, and components following established patterns
Use this skill when building:
- New pages (dashboard views, detail pages)
- New components (modals, forms, tables)
- New UI features (buttons, dropdowns, cards)
File Structure Conventions
Component Organization
src/
├── components/
│ ├── [resource]/ # Group by resource/feature
│ │ ├── create/
│ │ │ └── create[Resource]Modal.tsx
│ │ ├── update/
│ │ │ └── update[Resource]Modal.tsx
│ │ ├── delete/
│ │ │ └── delete[Resource]Modal.tsx
│ │ └── preview/
│ │ └── preview[Resource]Modal.tsx
│ └── shared/ # Reusable components
│ ├── modal.tsx
│ ├── notification.tsx
│ └── TableActionsDropdown.tsx
Rules:
- Component folders use lowercase with hyphens (e.g.,
property/,client-agreement/) - Action folders are always:
create/,update/,delete/,preview/ - Component files use PascalCase and descriptive names
- Modal components always end with
Modal.tsx - Use
'use client'directive for all interactive components
Page Organization
src/
└── app/
├── (prelogin)/ # Public pages (login, signup)
│ ├── login/
│ │ └── page.tsx
│ └── signup/
│ └── page.tsx
└── (user)/ # Protected pages
└── property-manager/ # Role-based routes
├── dashboard/
│ └── page.tsx
├── properties/
│ └── page.tsx
└── clients/
└── page.tsx
Rules:
- Route groups use parentheses:
(prelogin)/,(user)/ - Role-based routes:
property-manager/,admin/,client/ - Each route has a
page.tsxfile - Pages use Server Components by default, add
'use client'only when needed
Services Organization
src/
├── services/
│ ├── [resource]Service.ts # API call wrappers
│ └── types/
│ └── [resource].ts # TypeScript interfaces
Rules:
- Service files use camelCase with
Service.tssuffix - Type files match service names (e.g.,
propertyService.ts→property.ts) - Always export named functions (not default exports)
State Management
src/
└── store/
└── use[Name]Store.ts # Zustand stores
Rules:
- Store files use camelCase with
Store.tssuffix - Hook names start with
use(e.g.,useUserStore,useNotificationStore) - Use Zustand
persistmiddleware for data that should survive refresh
Component Naming Patterns
Modals
create[Resource]Modal.tsx # e.g., createPropertyModal.tsx
update[Resource]Modal.tsx # e.g., updateClientModal.tsx
delete[Resource]Modal.tsx # e.g., deletePropertyModal.tsx
preview[Resource]Modal.tsx # e.g., previewPropertyModal.tsx
Shared Components
modal.tsx # Generic modal wrapper
notification.tsx # Toast notifications
TableActionsDropdown.tsx # Three-dot menu for tables
Pages
page.tsx # Always named "page.tsx" (Next.js convention)
layout.tsx # Layout wrapper
TypeScript Conventions
Always Define Types in services/types/
Interface over Type:
// ✅ Use interface
export interface Property {
id: string
name: string
isActive: boolean
}
// ❌ Avoid type alias for objects
export type Property = {
id: string
name: string
}
Common Type Patterns
Entity Interface:
export interface Property {
id: string
name: string
address: string
province: string
propertyType: 'STR' | 'LTR'
hostawayListingId: string
commissionRate: number
isActive: boolean
createdAt: string
updatedAt: string | null
owners: PropertyOwner[]
}
Nested Interface:
export interface PropertyOwner {
clientId: string
clientName: string
isPrimary: boolean
commissionRateOverride: number | null
}
Request Payload:
export interface CreatePropertyPayload {
clientId: string
name: string
address: string
province: string
propertyType: 'STR' | 'LTR'
hostawayListingId: string
commissionRate: number
commissionRateOverride?: number
}
API Response Wrapper:
export interface PropertyResponse {
status: 'success' | 'failed'
message?: string
data: Property
}
export interface PropertiesResponse {
status: 'success' | 'failed'
message?: string
data: Property[]
}
State Management Patterns
When to Use Zustand vs Local State
Use Zustand for:
- Global user state (profile, authentication)
- Cross-component notifications
- Persisted data (survives page refresh)
Use Local State (useState) for:
- Form inputs
- Modal open/close state
- Component-specific UI state
Zustand Store Pattern
import { create } from 'zustand'
import { persist } from 'zustand/middleware'
interface UserProfile {
id: string
fullName: string
role: 'ADMIN' | 'PROPERTY-MANAGER' | 'CLIENT'
email?: string
}
interface UserStore {
profile: UserProfile | null
isAuthenticated: boolean
setProfile: (profile: UserProfile) => void
clearProfile: () => void
}
export const useUserStore = create<UserStore>()(
persist(
(set) => ({
profile: null,
isAuthenticated: false,
setProfile: (profile) => set({ profile, isAuthenticated: true }),
clearProfile: () => set({ profile: null, isAuthenticated: false }),
}),
{
name: 'user-storage',
partialize: (state) => ({
profile: state.profile,
isAuthenticated: state.isAuthenticated
})
}
)
)
Styling Conventions
Tailwind CSS Utility Classes
Always use Tailwind directly on JSX (no CSS modules, no styled-components).
Common Patterns:
Layout:
<div className="flex justify-between items-center">
<div className="grid grid-cols-2 gap-4">
<div className="space-y-4">
Spacing:
<div className="p-6"> {/* Padding */}
<div className="mt-4 mb-2"> {/* Margin */}
<div className="gap-3"> {/* Grid/Flex gap */}
Colors:
<div className="bg-white text-black">
<div className="bg-blue-600 text-white">
<div className="border border-gray-300">
Interactive States:
<button className="hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed">
<input className="focus:outline-none focus:ring-2 focus:ring-blue-500">
Responsive Design:
<div className="w-11/12 max-w-2xl"> {/* Responsive width */}
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
For More Details
- Component patterns with full code examples: See
component-patterns.md - Form patterns with validation examples: See
form-patterns.md - Styling guide with Tailwind examples: See
styling-guide.md
Last Updated: November 4, 2025