website-enchun-mgr/_bmad-output/implementation-artifacts/1-5-homepage.story.md

Story 1.5: Homepage Implementation

Status: ready-for-dev

Epic: Epic 1 - Webflow to Payload CMS + Astro Migration

Priority: P1 (High - First public page visitors see)

Estimated Time: 6-8 hours

Depends On: Story 1.4 (Global Layout Components - Header/Footer)

---

Story

As a Visitor, I want to view the homepage with hero section and service features, so that I can understand what Enchun Digital offers.

哇，這是我們網站的第一印象！首頁必須讓訪客一眼就知道恩群數位是做什麼的，並且想要繼續探索！

---

Context

這是首個完整的公開頁面實作，依賴 Story 1.4 完成 Header 和 Footer 組件。首頁是網站的門面，需要完美呈現品牌形象和核心服務。

Story Source:

• PRD: docs/prd/05-epic-stories.md - Story 1.5
• Frontend route exists at: apps/frontend/src/pages/index.astro
• CMS Globals: Header, Footer (already configured)

Current State:

• Basic index.astro exists with hardcoded content
• VideoHero component exists with video background support
• Header/Footer components fetch from Payload CMS
• Layout.astro integrates Header and Footer

---

Acceptance Criteria

AC1: Hero Section (完整英雄區域)

• Background video with overlay (desktop + mobile variants)
• Main headline: "創造企業更多發展的可能性是我們的使命"
• Subheadline: "Its our destiny to create possibilities for your business"
• Enchun logo display
• Video fallback image for non-video browsers
• Gradient overlay for text readability (from-black/80 to-black/0)

AC2: Service Features Grid (服務特色網格)

• 4 service cards in responsive grid (1 col mobile, 2 col tablet, 4 col desktop)
• Each card displays:
  • Icon (SVG or emoji)
  • Title (中文)
  • Description (中文)
• Card styling: white background, shadow, rounded corners
• Hover effects for interactivity

AC3: Portfolio Preview Section (作品預覽)

• Display 3-6 portfolio items as preview cards
• Each card shows: image, title, short description
• "View All Portfolio" CTA button linking to /website-portfolio
• Data fetched from Portfolio collection (Payload CMS)

AC4: CTA Section (行動呼籲)

• Headline: "準備好開始新的旅程了嗎"
• Description text
• Primary CTA button linking to /contact-us
• Background styling matching Webflow design

AC5: Content from Payload CMS (內容來自 CMS)

• Hero content (headline, subheadline) from Home global or Page collection
• Service features from configurable CMS source
• Portfolio items from Portfolio collection
• CTA section text from CMS

AC6: Visual Fidelity 95%+ (視覺保真度)

• Colors match Webflow design tokens
• Spacing and typography match original
• Responsive breakpoints align with Webflow
• Animations and transitions feel smooth

AC7: Lighthouse Performance 90+ (效能標準)

• Performance score >= 90
• FCP < 1.5s
• LCP < 2.5s
• CLS < 0.1

---

Tasks / Subtasks

Task 1.5.1: Create Home Global in Payload CMS (1h)

AC Coverage: AC5

• Subtask 1.5.1.1: Create Home global config
  • File: apps/backend/src/Home/config.ts
  • Fields: heroHeadline, heroSubheadline, heroVideo (upload), heroOverlay (group)
• Subtask 1.5.1.2: Register Home global in payload.config.ts
• Subtask 1.5.1.3: Add access control (read: public, update: adminOnly)
• Subtask 1.5.1.4: Seed initial content in Payload Admin
• Subtask 1.5.1.5: Verify TypeScript types regenerate

Task 1.5.2: Refactor index.astro to use Payload Data (2h)

AC Coverage: AC5, AC6

• Subtask 1.5.2.1: Create getHomeData utility function
  • File: apps/frontend/src/lib/api/home.ts
  • Fetch Home global, Portfolio items
• Subtask 1.5.2.2: Update index.astro to fetch data at build time
• Subtask 1.5.2.3: Pass props to child components
• Subtask 1.5.2.4: Handle data fetching errors gracefully
• Subtask 1.5.2.5: Test with draft=false parameter

Task 1.5.3: Enhance Hero Section (1.5h)

AC Coverage: AC1, AC6

• Subtask 1.5.3.1: Update VideoHero to accept CMS data
  • Props: heroHeadline, heroSubheadline, heroVideoUrl
• Subtask 1.5.3.2: Add fallback image when video fails to load
• Subtask 1.5.3.3: Adjust gradient overlay for text readability
• Subtask 1.5.3.4: Ensure mobile video is optimized (smaller file)
• Subtask 1.5.3.5: Test on various devices and network speeds

Task 1.5.4: Implement Service Features Grid (1.5h)

AC Coverage: AC2, AC6

• Subtask 1.5.4.1: Create ServiceFeatureCard component
  • File: apps/frontend/src/components/ServiceFeatureCard.astro
  • Props: icon, title, description
• Subtask 1.5.4.2: Create ServiceFeaturesGrid section
  • File: apps/frontend/src/sections/ServiceFeatures.astro
  • Grid layout: 1 col mobile, 2 col md, 4 col lg
• Subtask 1.5.4.3: Add hover effects (transform, shadow)
• Subtask 1.5.4.4: Configure 4 service features
  • Google Ads, 社群行銷, 論壇行銷, 網站設計
• Subtask 1.5.4.5: Test responsive behavior

Task 1.5.5: Implement Portfolio Preview Section (1h)

AC Coverage: AC3, AC5

• Subtask 1.5.5.1: Create PortfolioPreviewCard component
  • File: apps/frontend/src/components/PortfolioPreviewCard.astro
  • Props: image, title, description, slug
• Subtask 1.5.5.2: Create PortfolioPreview section
  • File: apps/frontend/src/sections/PortfolioPreview.astro
  • Display 3 items (limit query)
• Subtask 1.5.5.3: Add "View All" CTA button
• Subtask 1.5.5.4: Fetch from Portfolio collection with proper sorting
• Subtask 1.5.5.5: Handle empty portfolio state

Task 1.5.6: Implement CTA Section (1h)

AC Coverage: AC4, AC6

• Subtask 1.5.6.1: Create CTASection component
  • File: apps/frontend/src/sections/CTASection.astro
  • Props: headline, description, ctaText, ctaLink
• Subtask 1.5.6.2: Style with gradient background matching Webflow
• Subtask 1.5.6.3: Add primary button styling
• Subtask 1.5.6.4: Connect to Contact page route
• Subtask 1.5.6.5: Make text configurable via CMS

Task 1.5.7: Performance Optimization and Testing (1h)

AC Coverage: AC7

• Subtask 1.5.7.1: Run Lighthouse audit (desktop + mobile)
• Subtask 1.5.7.2: Optimize images (use WebP, responsive sizes)
• Subtask 1.5.7.3: Implement lazy loading for below-fold content
• Subtask 1.5.7.4: Minimize CLS (reserve space for dynamic content)
• Subtask 1.5.7.5: Test on actual devices (iOS, Android)

---

Dev Notes

Architecture Patterns

1. Data Fetching Pattern:

   • Use Astro's server-side fetching in the frontmatter
   • Cache aggressively (Payload CMS responses are stable)
   • Use draft=false for public content

2. Component Structure:

   index.astro (main page)
   ├── VideoHero (hero section)
   ├── ServiceFeatures (services grid)
   ├── PortfolioPreview (portfolio cards)
   ├── CTASection (call to action)
   └── uses Layout.astro (wraps with Header/Footer)
   

3. Styling Approach:

   • Use Tailwind CSS utility classes
   • Reference design tokens from apps/frontend/src/styles/theme.css
   • Maintain consistency with existing components

Project Structure Notes

Files to Create:

apps/backend/src/
├── Home/
│   └── config.ts              # Home global configuration

apps/frontend/src/
├── lib/
│   └── api/
│       └── home.ts            # Data fetching utilities
├── components/
│   └── ServiceFeatureCard.astro
├── sections/
│   ├── ServiceFeatures.astro
│   ├── PortfolioPreview.astro
│   └── CTASection.astro

Files to Modify:

apps/frontend/src/
├── pages/
│   └── index.astro            # Main page, refactor to use CMS data
└── components/
    └── videoHero.astro        # Enhance for CMS integration

Naming Conventions:

• Components: PascalCase.astro (e.g., ServiceFeatureCard.astro)
• Sections: PascalCase.astro (e.g., ServiceFeatures.astro)
• Utilities: camelCase.ts (e.g., getHomeData.ts)

Design Tokens (from theme.css)

/* Primary Colors */
--color-enchunblue: #0E79B2;
--color-tropical-blue: #E6F4FC;
--color-amber: #F9A825;
--color-st-tropaz: #2C5282;

/* Text Colors */
--color-tarawera: #3D4C53;
--color-dove-gray: #666666;

/* Use these for consistency! */

References

• Source: docs/prd/05-epic-stories.md#Story-15
• Source: apps/frontend/src/pages/index.astro (existing implementation)
• Source: apps/backend/src/Header/config.ts (Global pattern reference)
• Source: apps/backend/src/Footer/config.ts (Global pattern reference)
• Source: research/www.enchun.tw/index.html (Original Webflow)

---

Testing Requirements

Visual Testing Checklist

• Hero section displays correctly on all screen sizes
• Video background plays smoothly on desktop
• Mobile video loads and plays on mobile devices
• Service cards align properly in grid
• Portfolio preview cards have consistent heights
• CTA section button is prominent and clickable

Functional Testing

• All navigation links work correctly
• CTA buttons route to correct pages
• Portfolio preview cards link to detail pages
• Data loads from Payload CMS without errors
• Fallback content displays if CMS is unavailable

Performance Testing

# Run Lighthouse audit
npx lighthouse http://localhost:4321 --view

Targets:

• Performance: >= 90
• Accessibility: >= 90
• Best Practices: >= 90
• SEO: >= 90

Manual Testing Steps

1. Start dev server: pnpm dev
2. Navigate to http://localhost:4321
3. Verify hero video loads and plays
4. Scroll through all sections
5. Click all CTA buttons
6. Test on mobile (resize browser or use device)
7. Check console for errors

---

Risk Assessment

Risk	Probability	Impact	Mitigation
Video file too large	Medium	High	Compress video, use separate mobile version
CLS from dynamic content	Low	Medium	Reserve space with aspect-ratio
CMS fetch fails	Low	Medium	Add error boundaries and fallback UI
Portfolio empty state	Medium	Low	Show placeholder or hide section

---

Definition of Done

• All 7 tasks completed
• Home global created and seeded with content
• index.astro refactored to use Payload CMS data
• All sections (Hero, Services, Portfolio, CTA) implemented
• Visual fidelity matches Webflow (95%+)
• Lighthouse Performance score 90+
• No console errors on page load
• Code follows existing patterns
• No linting errors (pnpm lint)
• sprint-status.yaml updated to mark story as ready-for-dev

---

Dev Agent Record

Agent Model Used

To be filled by Dev Agent

Debug Log References

To be filled by Dev Agent

Completion Notes

To be filled by Dev Agent

File List

To be filled by Dev Agent

---

Change Log

Date	Action	Author
2026-01-31	Story created (Draft)	SM Agent (Bob)