feat(spec): complete implementation plan for Halloween event page

Created comprehensive planning documentation following Spec-Kit standards: Phase 0 - Research: - Analyzed 10 technical decisions (HTML5, ASCII art, countdown, responsive design) - Resolved edge cases (post-countdown, post-event, JS disabled, small screens) - Documented rationale and alternatives for each decision Phase 1 - Design: - Defined 4 data entities (Event, Countdown, VisualTheme, Content) - Created JSON schema contract for page content validation - Mapped 35 functional requirements to implementation approach - Generated quickstart testing checklist with 10 test categories Technical decisions: - Single-file HTML architecture (no external dependencies) - Pure CSS animations (blinking cursor) - JavaScript countdown with GMT+8 timezone handling - Responsive ASCII art (desktop/mobile versions) - WCAG 2.1 AA compliance (21:1 contrast ratio) Constitution compliance: PASS - No violations detected - Follows user-centric, professional excellence principles - Minimal technical stack aligns with simplicity requirement Artifacts created: - spec.md: 35 functional requirements - plan.md: Implementation strategy and phases - research.md: 10 technical research decisions - data-model.md: 4 entity definitions with validation - contracts/page-content.schema.json: JSON Schema - quickstart.md: Comprehensive testing checklist Ready for: /tasks command to generate tasks.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-04 19:20:25 +08:00
parent 17730359b8
commit 325eeaf063
6 changed files with 2214 additions and 0 deletions
--- a/specs/001-mcdonald-s-it/quickstart.md
+++ b/specs/001-mcdonald-s-it/quickstart.md
@@ -0,0 +1,442 @@
+# Quickstart: McDonald's IT Halloween Event Page
+
+**Feature**: Halloween event announcement webpage
+**Date**: 2025-10-04
+**Purpose**: Step-by-step testing and validation checklist
+
+## Prerequisites
+
+- Modern web browser (Chrome, Firefox, Safari, or Edge - latest 2 versions)
+- Text editor (for viewing source if needed)
+- Internet connection (for online validators)
+- Device with different screen sizes OR browser dev tools for responsive testing
+
+## Quick Test (2 minutes)
+
+1. **Open the page**
+   ```bash
+   # Navigate to project directory
+   cd /Users/snowprint/workspace/claude/test-project
+
+   # Open index.html in default browser
+   open index.html
+   # OR for other systems:
+   # xdg-open index.html  (Linux)
+   # start index.html     (Windows)
+   ```
+
+2. **Visual check** ✅
+   - [ ] Black background (#000000)
+   - [ ] Green text (#00FF00) for primary content
+   - [ ] Amber text (#FFBF00) for key information
+   - [ ] Monospace font (looks like terminal/code)
+   - [ ] No shadows, gradients, or decorative effects
+
+3. **Content check** ✅
+   - [ ] McDonald's ASCII art logo visible at top
+   - [ ] "i'm lovin' IT" tagline below logo with blinking cursor
+   - [ ] Countdown timer showing days, hours, minutes, seconds
+   - [ ] Event details: Oct 31 2025, 18:00-21:00 GMT+8
+   - [ ] Location: MITA Building 2F Pantry
+   - [ ] Organizer: Jessi Pan (jessi.pan@cn.mcd.com)
+   - [ ] Activities listed (Cosplay, Debugging Games, Lucky Draw)
+   - [ ] Halloween decorations (🎃👻🦇 or ASCII art)
+   - [ ] Footer: "McDonald's IT Academy"
+
+4. **Functionality check** ✅
+   - [ ] Countdown timer updates every second
+   - [ ] No JavaScript errors in browser console (F12 → Console tab)
+   - [ ] Browser tab title shows "2025 MITA Halloween"
+   - [ ] Favicon shows pumpkin emoji 🎃
+
+5. **Responsive check** ✅
+   - [ ] Resize browser to mobile width (< 768px)
+   - [ ] ASCII art switches to mobile version OR remains legible
+   - [ ] No horizontal scrollbar appears
+   - [ ] All content readable without zooming
+
+## Full Test Suite (15 minutes)
+
+### 1. Visual Design Validation
+
+**Test**: Verify terminal aesthetic
+- [ ] Background is pure black (#000000)
+- [ ] Primary text is terminal green (#00FF00)
+- [ ] Accent text is amber (#FFBF00)
+- [ ] Font is monospace (Courier New, Monaco, Consolas, or Menlo)
+- [ ] No shadows on any elements
+- [ ] No gradients anywhere
+- [ ] No borders or decorative effects
+- [ ] Overall look is minimalist and geek-style
+
+**Expected**: Page looks like a terminal/command-line interface
+
+---
+
+### 2. Content Verification
+
+**Test**: Verify all required content is present and correct
+
+**Event Information**:
+- [ ] Title: "2025 MITA Halloween" (in browser tab)
+- [ ] Date: October 31, 2025
+- [ ] Time: 18:00 - 21:00 (6:00 PM - 9:00 PM)
+- [ ] Timezone: GMT+8 clearly stated
+- [ ] Location: MITA Building 2F Pantry
+- [ ] Organizer: Jessi Pan
+- [ ] Contact: jessi.pan@cn.mcd.com
+
+**Activities**:
+- [ ] Cosplay (encouraged)
+- [ ] Bug debugging games
+- [ ] Lucky draw
+
+**Notes**:
+- [ ] Costumes encouraged
+- [ ] Food and drinks provided
+
+**ASCII Art**:
+- [ ] McDonald's logo with Golden Arches M
+- [ ] Halloween decorations (pumpkins, ghosts, bats)
+
+**Tagline**:
+- [ ] "i'm lovin' IT" displayed
+- [ ] Blinking cursor animation after tagline
+
+**Footer**:
+- [ ] "McDonald's IT Academy" displayed
+
+**Expected**: All content matches specification exactly
+
+---
+
+### 3. Bilingual Content Check
+
+**Test**: Verify English/Chinese alternating pattern
+
+- [ ] Each piece of information has English version
+- [ ] Each piece of information has Chinese version
+- [ ] Lines alternate: English, then Chinese
+- [ ] `lang="en"` attribute on English paragraphs
+- [ ] `lang="zh-CN"` attribute on Chinese paragraphs
+- [ ] Both languages are legible and well-formatted
+
+**Expected**: Clear bilingual display with proper language tagging
+
+---
+
+### 4. Countdown Timer Functionality
+
+**Test**: Verify countdown accuracy and updates
+
+**Before Event** (current time < Oct 31 2025 18:00 GMT+8):
+- [ ] Countdown displays days, hours, minutes, seconds
+- [ ] Timer updates every second
+- [ ] Values are accurate (check against system clock)
+- [ ] No negative values shown
+- [ ] Format is clear (e.g., "365d 12h 34m 56s")
+
+**Manual Time Test** (using browser dev tools):
+```javascript
+// Open browser console (F12)
+// Override system date to test different states
+
+// Test: Just before event starts
+const testDate = new Date('2025-10-31T09:59:50Z'); // 17:59:50 GMT+8
+// Check countdown shows 0d 0h 0m 10s (approximately)
+
+// Test: Event starting
+const testDate = new Date('2025-10-31T10:00:00Z'); // 18:00:00 GMT+8
+// Check displays "🎃 EVENT STARTING NOW! 🎃"
+
+// Test: Event ended
+const testDate = new Date('2025-10-31T13:00:01Z'); // 21:00:01 GMT+8
+// Check displays "👻 EVENT COMPLETED - Thanks for joining! 👻"
+```
+
+**Expected**: Countdown is accurate and handles all three states correctly
+
+---
+
+### 5. Responsive Design Testing
+
+**Test**: Page adapts to different screen sizes
+
+**Desktop (1024px+)**:
+- [ ] Full ASCII art logo visible
+- [ ] All content displayed comfortably
+- [ ] No horizontal scroll
+- [ ] Text is readable without zooming
+
+**Tablet (768-1023px)**:
+- [ ] Layout adapts smoothly
+- [ ] ASCII art remains legible OR switches to simpler version
+- [ ] No horizontal scroll
+- [ ] All features functional
+
+**Mobile (320-767px)**:
+- [ ] Mobile ASCII art version displayed (if different)
+- [ ] Countdown timer visible and readable
+- [ ] Bilingual content stacks vertically
+- [ ] No horizontal scroll
+- [ ] Tap targets are adequate (buttons, links)
+
+**Very Small (< 320px)** [optional]:
+- [ ] Ultra-minimal ASCII art or text fallback
+- [ ] Core content still accessible
+
+**How to test**:
+1. Open browser DevTools (F12)
+2. Toggle device toolbar (Ctrl+Shift+M / Cmd+Shift+M)
+3. Select different device presets OR
+4. Drag responsive width to test breakpoints
+
+**Expected**: Page is fully functional and readable at all sizes
+
+---
+
+### 6. Accessibility Testing
+
+**Test**: WCAG 2.1 AA compliance
+
+**Contrast Ratios** (use https://webaim.org/resources/contrastchecker/):
+- [ ] Green (#00FF00) on black (#000000) = 21:1 ratio ✅ (exceeds WCAG AAA)
+- [ ] Amber (#FFBF00) on black (#000000) = 12:1 ratio ✅ (exceeds WCAG AA)
+
+**Screen Reader Test** (optional but recommended):
+- [ ] Enable screen reader (VoiceOver on Mac, NVDA on Windows)
+- [ ] Navigate through page
+- [ ] All content is announced
+- [ ] Language switches are detected (English → Chinese)
+- [ ] ARIA labels provide context for visual elements
+
+**Keyboard Navigation**:
+- [ ] Tab through all interactive elements
+- [ ] Focus indicators are visible
+- [ ] All functionality accessible via keyboard
+
+**Semantic HTML**:
+- [ ] Proper heading hierarchy (h1, h2, etc.)
+- [ ] Semantic tags used (<header>, <main>, <section>, <footer>)
+- [ ] `lang` attributes on bilingual content
+
+**Expected**: Page meets WCAG 2.1 AA standards
+
+---
+
+### 7. Performance Testing
+
+**Test**: Load time and file size
+
+**File Size**:
+```bash
+# Check file size
+ls -lh index.html
+# Should be < 50KB
+```
+- [ ] File size is under 50KB (51,200 bytes)
+
+**Load Time**:
+1. Open browser DevTools (F12)
+2. Go to Network tab
+3. Hard refresh page (Ctrl+Shift+R / Cmd+Shift+R)
+4. Check "Load" time in bottom status bar
+
+- [ ] Page loads in under 1 second
+
+**Animation Performance**:
+1. Open DevTools → Performance tab
+2. Record for 5 seconds
+3. Check frame rate (FPS)
+
+- [ ] Cursor blinking animation runs at 60fps
+- [ ] Countdown updates don't cause jank
+
+**Expected**: Fast load, smooth animations, small file size
+
+---
+
+### 8. Browser Compatibility
+
+**Test**: Page works in all target browsers
+
+- [ ] **Chrome** (latest): All features work
+- [ ] **Firefox** (latest): All features work
+- [ ] **Safari** (latest): All features work
+- [ ] **Edge** (latest): All features work
+
+**How to test**:
+1. Open index.html in each browser
+2. Run through Quick Test checklist
+3. Note any differences or issues
+
+**Expected**: Consistent experience across all browsers
+
+---
+
+### 9. JavaScript Disabled Test
+
+**Test**: Page works without JavaScript
+
+1. Disable JavaScript in browser settings:
+   - Chrome: Settings → Privacy → Site Settings → JavaScript → Blocked
+   - Firefox: about:config → javascript.enabled → false
+2. Refresh page
+
+- [ ] All static content visible
+- [ ] ASCII art displays
+- [ ] Event information readable
+- [ ] Countdown shows fallback message: "Enable JavaScript for live countdown"
+- [ ] No broken functionality
+
+**Expected**: Progressive enhancement - core content accessible without JS
+
+---
+
+### 10. HTML5 Validation
+
+**Test**: Valid HTML5 markup
+
+1. Go to https://validator.w3.org/
+2. Upload index.html OR paste URL
+3. Run validation
+
+- [ ] Zero errors
+- [ ] Zero warnings (or only acceptable warnings)
+- [ ] Passes HTML5 validation
+
+**Common acceptable warnings**:
+- Data URI favicon warnings (browser-specific)
+- Emoji in content (some validators flag these)
+
+**Expected**: Clean validation with no critical errors
+
+---
+
+## Edge Case Testing
+
+### Edge Case 1: Countdown Reaches Zero
+
+**Setup**: Set system time to Oct 31 2025 18:00 GMT+8 (or use dev tools)
+
+**Test**:
+- [ ] Countdown disappears
+- [ ] Message displays: "🎃 EVENT STARTING NOW! 🎃"
+- [ ] No errors in console
+
+---
+
+### Edge Case 2: After Event Ends
+
+**Setup**: Set system time to after Oct 31 2025 21:00 GMT+8
+
+**Test**:
+- [ ] Countdown disappears
+- [ ] Message displays: "👻 EVENT COMPLETED - Thanks for joining! 👻"
+- [ ] No errors in console
+
+---
+
+### Edge Case 3: Very Long Content
+
+**Test**: Ensure page handles overflow properly
+- [ ] Long ASCII art doesn't break layout
+- [ ] Long text content wraps appropriately
+- [ ] No horizontal scroll on any screen size
+
+---
+
+### Edge Case 4: Slow Network
+
+**Test**: Page loads correctly on slow connection
+
+1. Open DevTools → Network tab
+2. Throttle to "Slow 3G"
+3. Hard refresh
+
+- [ ] Page still loads under 3 seconds
+- [ ] No broken elements
+- [ ] Countdown starts once JS loads
+
+---
+
+## Validation Tools
+
+**Contrast Checker**: https://webaim.org/resources/contrastchecker/
+**HTML Validator**: https://validator.w3.org/
+**CSS Validator**: https://jigsaw.w3.org/css-validator/
+**WCAG Checker**: https://wave.webaim.org/
+**Performance**: Chrome DevTools Lighthouse
+
+---
+
+## Success Criteria
+
+**✅ Page is ready for deployment if**:
+- All visual checks pass (terminal aesthetic)
+- All content is present and correct
+- Bilingual display works properly
+- Countdown timer functions correctly
+- Responsive on all screen sizes
+- WCAG 2.1 AA compliant
+- File size < 50KB
+- Load time < 1 second
+- Works in all target browsers
+- HTML5 valid
+
+**❌ Page needs fixes if**:
+- Any visual element breaks terminal aesthetic
+- Content is missing or incorrect
+- Countdown doesn't update or shows errors
+- Not responsive (horizontal scroll on mobile)
+- Contrast ratios fail WCAG AA
+- File size exceeds 50KB
+- Load time exceeds 1 second
+- Validation errors exist
+
+---
+
+## Troubleshooting
+
+**Problem**: Countdown doesn't update
+- Check JavaScript console for errors
+- Verify system date/time is correct
+- Check JavaScript is enabled
+
+**Problem**: ASCII art looks broken
+- Verify monospace font is loading
+- Check character encoding is UTF-8
+- Test different browsers
+
+**Problem**: Colors look wrong
+- Check color hex values in CSS
+- Verify no browser extensions affecting colors
+- Test in incognito mode
+
+**Problem**: Page not responsive
+- Check viewport meta tag exists
+- Verify media queries are working
+- Test in different browsers
+
+**Problem**: File size too large
+- Check ASCII art for excessive whitespace
+- Minify CSS/JS if needed
+- Remove any unused code
+
+---
+
+## Next Steps
+
+After passing all tests:
+1. ✅ Mark quickstart.md checklist complete
+2. ✅ Document any issues found and fixed
+3. ✅ Update CHANGELOG.md with v1.0.0 release
+4. ✅ Prepare for deployment
+5. ✅ Share with stakeholders (Jessi Pan)
+
+---
+
+**Test Date**: _____________
+**Tested By**: _____________
+**Status**: ⬜ Pass | ⬜ Fail | ⬜ Needs Fixes
+**Notes**: _________________________________________________