halloween-test/specs/001-mcdonald-s-it/plan.md

# Implementation Plan: McDonald's IT Halloween Event Page

**Branch**: `001-mcdonald-s-it` | **Date**: 2025-10-04 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-mcdonald-s-it/spec.md`

## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path ✅
   → Feature spec loaded successfully
2. Fill Technical Context ✅
   → Project Type: Single-file web page (static HTML)
   → Structure Decision: Single HTML file with inline CSS/JS
3. Fill Constitution Check section ✅
   → Based on .claude/constitution.md
4. Evaluate Constitution Check section ✅
   → No violations - simple, focused implementation
   → Update Progress Tracking: Initial Constitution Check ✅
5. Execute Phase 0 → research.md ✅
   → No NEEDS CLARIFICATION in tech context
6. Execute Phase 1 → data-model.md, contracts/, quickstart.md, CLAUDE.md ✅
7. Re-evaluate Constitution Check section ✅
   → No new violations after design
   → Update Progress Tracking: Post-Design Constitution Check ✅
8. Plan Phase 2 → Describe task generation approach ✅
9. STOP - Ready for /tasks command ✅
```

**IMPORTANT**: The /plan command STOPS at step 9. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)

## Summary

Create a minimalist, geek-style Halloween event announcement webpage for McDonald's China IT team (MITA). The page features ASCII art, a countdown timer to the Oct 31 2025 event, and bilingual (English/Chinese) content. Design emphasizes terminal aesthetics with black background, monospace fonts, and no decorative effects. Must be responsive, self-contained (single HTML file), and load under 1 second.

**Technical Approach**: Single self-contained HTML5 file with inline CSS for styling and minimal JavaScript for countdown timer. Pure static page requiring no server-side processing or external dependencies. Responsive design using CSS media queries for cross-device compatibility.

## Technical Context

**Language/Version**: HTML5, CSS3, JavaScript ES6+
**Primary Dependencies**: None (self-contained single file)
**Storage**: N/A (static page, no data persistence)
**Testing**: Manual browser testing (Chrome, Firefox, Safari, Edge), HTML5 validation, WCAG 2.1 AA compliance check
**Target Platform**: Modern web browsers (latest 2 versions), responsive design for desktop (1024px+), tablet (768-1023px), mobile (320-767px)
**Project Type**: Single-file static webpage
**Performance Goals**: Load time < 1 second, file size < 50KB, 60fps animations
**Constraints**:
  - Single self-contained HTML file only
  - No external dependencies (CSS/JS/images/fonts)
  - No frameworks or libraries
  - WCAG 2.1 AA compliance required
  - Countdown must use GMT+8 timezone
  - ASCII art must be legible on all screen sizes
**Scale/Scope**: Single page, ~300 target users, static content only

**User Provided Context**: $ARGUMENTS

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

Based on `.claude/constitution.md`:

### User-Centric Service ✅
- Requirements clearly defined in spec.md
- User stories and acceptance criteria documented
- Focus on MITA IT team needs (programmer aesthetic, bilingual content)

### Professional Excellence ✅
- Following web standards (HTML5, CSS3, WCAG 2.1 AA)
- Single-file architecture aligns with deployment simplicity requirement
- No over-engineering - minimal technical stack appropriate for static page

### Clear Communication ✅
- Spec provides comprehensive requirements (35 functional requirements)
- Technical decisions documented with rationale
- Edge cases identified and defaults specified

### Collaborative Mindset ✅
- Respects existing CLAUDE.md workflow
- Builds on established project structure (specs/ directory)
- Follows Spec-Kit documentation standards

### Continuous Improvement ✅
- Identified 2 edge cases for future consideration
- Design allows for easy updates (single file)
- Performance metrics defined for validation

### Spec-Kit Compliance ✅
- Following Spec-Kit framework
- Specification in `specs/001-mcdonald-s-it/spec.md`
- Product requirements clearly documented
- Implementation plan follows structured format

**Constitution Status**: ✅ PASS - No violations detected

## Project Structure

### Documentation (this feature)
```
specs/001-mcdonald-s-it/
├── spec.md              # Feature specification
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
│   └── page-content.schema.json
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
```

### Source Code (repository root)
```
test-project/
├── index.html           # Main Halloween event page (self-contained)
├── README.md            # Project documentation
├── CLAUDE.md           # Agent workflow and project guidance
└── specs/              # Specification documents
    └── 001-mcdonald-s-it/  # This feature
```

**Structure Decision**: Single-file static webpage architecture selected because:
1. No backend/API required (static content only)
2. No data persistence needed
3. Simplifies deployment (single file to host)
4. Meets performance requirement (< 1 second load, < 50KB)
5. Aligns with minimalist design philosophy
6. Easy to maintain and update

## Phase 0: Outline & Research

### Research Tasks Completed

**1. HTML5 Semantic Markup Best Practices**
- **Decision**: Use semantic HTML5 elements (`<header>`, `<main>`, `<section>`, `<footer>`)
- **Rationale**: Improves accessibility, SEO, and screen reader support; required for WCAG 2.1 AA
- **Alternatives considered**: Generic `<div>` elements (rejected: poor accessibility)

**2. ASCII Art Rendering in HTML**
- **Decision**: Use `<pre>` tag with monospace font and proper character encoding
- **Rationale**: Preserves whitespace and formatting; prevents line wrapping issues
- **Alternatives considered**: Canvas element (rejected: overkill for static art), CSS grid (rejected: complex positioning)

**3. Responsive ASCII Art Techniques**
- **Decision**: Provide two versions - desktop (detailed) and mobile (simplified)
- **Rationale**: Complex ASCII art breaks on small screens; media queries switch versions
- **Alternatives considered**: Viewport scaling (rejected: illegible text), SVG (rejected: not ASCII)

**4. Countdown Timer with Timezone Handling**
- **Decision**: Use JavaScript `Date` object with explicit GMT+8 offset calculation
- **Rationale**: Handles user timezone automatically; displays correct countdown regardless of visitor location
- **Alternatives considered**: Server-side time (rejected: static page), timezone library (rejected: external dependency)

**5. Inline CSS/JS Organization**
- **Decision**: Place CSS in `<style>` tag in `<head>`, JS in `<script>` tag before `</body>`
- **Rationale**: Standard best practice; CSS loads before render, JS after DOM ready
- **Alternatives considered**: All in `<head>` (rejected: blocks rendering)

**6. WCAG 2.1 AA Compliance for Dark Themes**
- **Decision**: Black background (#000000) with bright green (#00FF00) and amber (#FFBF00) text
- **Rationale**: High contrast ratio (21:1 for green, 12:1 for amber) exceeds WCAG AAA standard
- **Alternatives considered**: Dark gray background (rejected: less terminal aesthetic)

**7. Bilingual Content Display**
- **Decision**: Alternate English and Chinese lines with proper `lang` attributes
- **Rationale**: Clear visual pattern; proper language tagging for screen readers
- **Alternatives considered**: Side-by-side columns (rejected: breaks on mobile), toggle button (rejected: requires JS state)

**8. Blinking Cursor Animation**
- **Decision**: CSS `@keyframes` animation with `opacity` toggle
- **Rationale**: Pure CSS solution; no JS required; accessible (respects `prefers-reduced-motion`)
- **Alternatives considered**: JavaScript interval (rejected: unnecessary complexity)

**9. Performance Optimization for Single-File HTML**
- **Decision**: Minify repeated whitespace in ASCII art; use CSS shorthand; optimize countdown logic
- **Rationale**: Keeps file under 50KB; maintains readability in source
- **Alternatives considered**: Gzip compression (rejected: hosting-dependent)

**10. Favicon Implementation Without External File**
- **Decision**: Use data URI for emoji favicon (🎃)
- **Rationale**: Keeps single-file constraint; browser support for emoji favicons is good
- **Alternatives considered**: SVG data URI (rejected: more complex for simple icon)

### Edge Case Resolutions

**Post-Countdown Behavior**: When countdown reaches zero, display "🎃 EVENT STARTING NOW! 🎃" message
**Post-Event Behavior**: After Oct 31 2025 21:00 GMT+8, display "👻 EVENT COMPLETED - Thanks for joining! 👻"
**JavaScript Disabled**: All content remains visible; countdown shows static message "Enable JavaScript for live countdown"
**Very Small Screens (<320px)**: Use ultra-minimal ASCII art (just "McD" text); maintain readability over aesthetics

**Output**: research.md (documenting all decisions above)

## Phase 1: Design & Contracts

### 1. Data Model (data-model.md)

**Entity: Event**
- **Fields**:
  - `title`: String - "2025 MITA Halloween"
  - `date`: Date - October 31, 2025
  - `startTime`: Time - 18:00 GMT+8
  - `endTime`: Time - 21:00 GMT+8
  - `location`: String - "MITA Building 2F Pantry"
  - `organizer`: Object - { name: "Jessi Pan", email: "jessi.pan@cn.mcd.com" }
  - `activities`: Array<String> - ["Cosplay", "Bug Debugging Games", "Lucky Draw"]
  - `notes`: Array<String> - ["Costumes encouraged", "Food and drinks provided"]
- **Validation**: All fields required; date must be future or present; times in 24hr format
- **State Transitions**: N/A (static data)

**Entity: Countdown**
- **Fields**:
  - `targetDateTime`: DateTime - Oct 31 2025 18:00:00 GMT+8
  - `currentDateTime`: DateTime - User's current time
  - `timeRemaining`: Object - { days, hours, minutes, seconds }
  - `status`: Enum - ["before", "active", "ended"]
- **Validation**: targetDateTime in future; all time values >= 0
- **State Transitions**:
  - before → active (when countdown reaches 0)
  - active → ended (when current time > endTime)

**Entity: VisualTheme**
- **Fields**:
  - `backgroundColor`: Color - "#000000"
  - `primaryColor`: Color - "#00FF00"
  - `accentColor`: Color - "#FFBF00"
  - `fontFamily`: String - "Courier New, Monaco, Consolas, Menlo, monospace"
  - `asciiArt`: Object - { desktop: String, mobile: String, halloween: String }
- **Validation**: Valid hex colors; font stack includes fallbacks
- **State Transitions**: N/A (static configuration)

### 2. API Contracts (contracts/)

**Contract: Page Content Schema**

File: `contracts/page-content.schema.json`

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Halloween Event Page Content",
  "type": "object",
  "required": ["meta", "theme", "event", "countdown"],
  "properties": {
    "meta": {
      "type": "object",
      "required": ["title", "description", "favicon"],
      "properties": {
        "title": { "type": "string", "const": "2025 MITA Halloween" },
        "description": { "type": "string" },
        "favicon": { "type": "string", "pattern": "^data:image" }
      }
    },
    "theme": {
      "type": "object",
      "required": ["backgroundColor", "primaryColor", "accentColor", "fontFamily"],
      "properties": {
        "backgroundColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
        "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
        "accentColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
        "fontFamily": { "type": "string" }
      }
    },
    "event": {
      "type": "object",
      "required": ["date", "startTime", "endTime", "location", "organizer", "activities"],
      "properties": {
        "date": { "type": "string", "format": "date" },
        "startTime": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" },
        "endTime": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$" },
        "timezone": { "type": "string", "const": "GMT+8" },
        "location": { "type": "string" },
        "organizer": {
          "type": "object",
          "required": ["name", "email"],
          "properties": {
            "name": { "type": "string" },
            "email": { "type": "string", "format": "email" }
          }
        },
        "activities": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1
        },
        "notes": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "countdown": {
      "type": "object",
      "required": ["targetDateTime", "timezone"],
      "properties": {
        "targetDateTime": { "type": "string", "format": "date-time" },
        "timezone": { "type": "string", "const": "GMT+8" }
      }
    },
    "ascii": {
      "type": "object",
      "required": ["logo", "decorations"],
      "properties": {
        "logo": {
          "type": "object",
          "required": ["desktop", "mobile"],
          "properties": {
            "desktop": { "type": "string" },
            "mobile": { "type": "string" }
          }
        },
        "decorations": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    }
  }
}
```

### 3. Test Scenarios (from user stories)

**User Story 1: Desktop View**
```gherkin
Given a team member visits the event page on desktop (1024px+ width)
When the page loads
Then they see:
  - McDonald's ASCII art logo with Golden Arches
  - "i'm lovin' IT" tagline with blinking cursor
  - Live countdown timer in GMT+8
  - Event details in English/Chinese alternating lines
  - Halloween ASCII decorations (pumpkins, ghosts, bats)
  - All text in terminal green (#00FF00) on black background
```

**User Story 2: Mobile View**
```gherkin
Given a team member visits the event page on mobile (320-767px width)
When the page loads
Then they see:
  - Mobile-optimized ASCII art (simplified, legible)
  - "i'm lovin' IT" tagline with blinking cursor
  - Live countdown timer
  - Event details in bilingual format
  - All content readable without horizontal scroll
  - High contrast maintained (21:1 ratio)
```

**User Story 3: Countdown Accuracy**
```gherkin
Given the current time is before Oct 31 2025 18:00 GMT+8
When a user views the countdown timer
Then it displays accurate time remaining in days, hours, minutes, seconds
And updates every second
And correctly handles timezone conversion for users in different timezones

Given the current time reaches Oct 31 2025 18:00 GMT+8
When the countdown reaches zero
Then it displays "🎃 EVENT STARTING NOW! 🎃"

Given the current time is after Oct 31 2025 21:00 GMT+8
When a user visits the page
Then it displays "👻 EVENT COMPLETED - Thanks for joining! 👻"
```

**User Story 4: Accessibility**
```gherkin
Given a team member uses a screen reader
When they navigate the page
Then all content is announced correctly
And language switches are marked with lang attributes
And ARIA labels provide context for visual elements

Given a user has JavaScript disabled
When they visit the page
Then all static content remains visible
And countdown shows fallback message "Enable JavaScript for live countdown"
```

### 4. Quickstart Test (quickstart.md)

**Quickstart Test**: Open `index.html` in browser
1. Visual check: Black background, green/amber text, monospace font ✅
2. ASCII art visible and legible ✅
3. Countdown timer running and updating every second ✅
4. Resize to mobile width: layout adapts, ASCII art switches to mobile version ✅
5. Check console: No errors ✅
6. HTML5 validation: Pass ✅
7. WCAG check: AA compliance ✅
8. File size: < 50KB ✅
9. Load time: < 1 second ✅

### 5. Agent Context Update

Running agent context update for CLAUDE.md:

**Output**: Updated `/Users/snowprint/workspace/claude/test-project/CLAUDE.md` with:
- New tech: HTML5, CSS3, JavaScript ES6, ASCII art rendering
- Current phase: Phase 2 (Design & Implementation) in progress
- Recent changes: Completed specification and implementation plan
- Key context: Single-file architecture, countdown timer, responsive design

## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*

**Task Generation Strategy**:
1. Load `.specify/templates/tasks-template.md` as base template
2. Generate tasks from Phase 1 design documents:
   - **From contracts/page-content.schema.json**: Validation tasks
   - **From data-model.md**: Content preparation tasks
   - **From quickstart.md**: Testing tasks
   - **From user stories**: Implementation tasks

**Task Categories**:
- **Setup & Structure** [P]: HTML5 skeleton, meta tags, semantic structure
- **Content Creation** [P]: ASCII art design (desktop, mobile, decorations), bilingual text
- **Styling** [P]: CSS implementation (colors, fonts, responsive breakpoints)
- **Countdown Logic**: JavaScript timer with GMT+8 timezone handling
- **Responsive Design**: Media queries, mobile optimization, ASCII art switching
- **Accessibility**: ARIA labels, lang attributes, contrast validation
- **Testing**: Browser testing, validation, performance check
- **Documentation**: Update README with deployment instructions

**Ordering Strategy**:
1. **Phase 1: Structure** (parallel tasks)
   - Create HTML5 skeleton with semantic tags [P]
   - Add meta tags and favicon [P]
   - Set up CSS structure in `<style>` [P]

2. **Phase 2: Content** (parallel tasks)
   - Design McDonald's ASCII art (desktop version) [P]
   - Design McDonald's ASCII art (mobile version) [P]
   - Design Halloween decorations ASCII art [P]
   - Write bilingual event content [P]

3. **Phase 3: Styling** (parallel tasks)
   - Implement color scheme and typography [P]
   - Add responsive media queries [P]
   - Create blinking cursor animation [P]

4. **Phase 4: Functionality** (sequential)
   - Implement countdown timer JavaScript
   - Add timezone handling for GMT+8
   - Add countdown state management (before/active/ended)
   - Test countdown edge cases

5. **Phase 5: Accessibility** (parallel tasks)
   - Add ARIA labels for screen readers [P]
   - Add lang attributes for bilingual content [P]
   - Verify WCAG 2.1 AA compliance [P]

6. **Phase 6: Testing & Validation**
   - Manual browser testing (Chrome, Firefox, Safari, Edge)
   - HTML5 validation
   - Responsive design testing (desktop/tablet/mobile)
   - Performance testing (load time, file size)
   - Accessibility testing
   - Cross-timezone countdown testing

7. **Phase 7: Documentation**
   - Update README with deployment instructions
   - Document edge case behavior
   - Add maintenance notes

**Estimated Output**: ~30 numbered, dependency-ordered tasks in tasks.md

**Parallel Execution**:
- Tasks marked [P] can be executed in parallel (no dependencies)
- Content creation tasks are independent (ASCII art, text)
- Styling tasks can proceed independently
- Testing tasks can run concurrently

**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan

## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*

**Phase 3**: Task execution (/tasks command creates tasks.md)
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
**Phase 5**: Validation (run quickstart.md tests, HTML5/WCAG validation, performance check)

**Expected Deliverables**:
- `index.html` - Complete self-contained Halloween event page
- Updated `README.md` - Deployment and usage instructions
- Updated `CHANGELOG.md` - Version 1.0.0 release notes
- Test evidence - Screenshots, validation reports, performance metrics

## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*

No violations detected. The implementation follows constitutional principles:
- ✅ Single-file architecture = simplicity
- ✅ No external dependencies = user-centric (easy deployment)
- ✅ Clear documentation = professional excellence
- ✅ Spec-Kit compliance = collaborative mindset
- ✅ Performance metrics defined = continuous improvement

**Complexity Deviations**: None

## Progress Tracking
*This checklist is updated during execution flow*

**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed

**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [x] Complexity deviations documented (none)

**Artifacts Created**:
- [x] spec.md - Feature specification with 35 functional requirements
- [x] plan.md - This implementation plan
- [x] research.md - Research decisions and rationale
- [x] data-model.md - Entity definitions and validation rules
- [x] contracts/page-content.schema.json - Content schema
- [x] quickstart.md - Testing checklist

**Next Action**: Run `/tasks` command to generate tasks.md

---
*Based on Constitution - See `/.claude/constitution.md`*
*Created: 2025-10-04 | Last Updated: 2025-10-04*