` for event details and countdown - Use `
` for logical content groups - Use `
` for McDonald's IT Academy attribution --- ### 2. ASCII Art Rendering in HTML **Question**: What's the best way to display ASCII art in HTML while preserving formatting? **Decision**: Use `
` tag with monospace font and UTF-8 encoding

**Rationale**:
- `` preserves all whitespace and line breaks
- Prevents browser from collapsing spaces
- Works reliably across all browsers
- Simple and performant

**Alternatives Considered**:
- Canvas element: Rejected as overkill for static ASCII art; accessibility issues
- CSS Grid: Rejected due to complexity of positioning each character
- `white-space: pre` on div: Works but `` is semantically correct

**Implementation Notes**:
```html
[ASCII art here]

```

---

### 3. Responsive ASCII Art Techniques

**Question**: How to make ASCII art legible on mobile devices?

**Decision**: Provide two versions - desktop (detailed) and mobile (simplified), switched via CSS media queries

**Rationale**:
- Complex ASCII art becomes illegible when viewport narrows
- Different art for different breakpoints maintains aesthetic
- CSS `display: none` to hide inappropriate version
- No JavaScript required for switching

**Alternatives Considered**:
- Viewport scaling: Rejected as text becomes too small to read
- SVG conversion: Rejected as it's not true ASCII art
- Single responsive design: Not feasible with ASCII art constraints

**Implementation Notes**:
```css
.ascii-desktop { display: block; }
.ascii-mobile { display: none; }

@media (max-width: 767px) {
  .ascii-desktop { display: none; }
  .ascii-mobile { display: block; }
}
```

---

### 4. Countdown Timer with Timezone Handling

**Question**: How to show countdown in GMT+8 for users in any timezone?

**Decision**: Use JavaScript `Date` object with explicit GMT+8 offset calculation

**Rationale**:
- JavaScript Date handles timezone conversion automatically
- Calculate target time as GMT+8, compare with user's local time
- User sees accurate countdown regardless of their timezone
- No external library needed

**Alternatives Considered**:
- Server-side time: Rejected as this is a static page
- Timezone library (e.g., moment-timezone): Rejected due to no external dependencies constraint
- Fixed GMT+8 display: Rejected as confusing for users in other timezones

**Implementation Notes**:
```javascript
// Target: Oct 31 2025 18:00 GMT+8 = Oct 31 2025 10:00 UTC
const targetDate = new Date('2025-10-31T10:00:00Z');
const now = new Date();
const diff = targetDate - now;
// Calculate days, hours, minutes, seconds from diff
```

---

### 5. Inline CSS/JS Organization

**Question**: Where to place CSS and JavaScript in a single HTML file?

**Decision**: CSS in `


  
  

```

---

### 6. WCAG 2.1 AA Compliance for Dark Themes

**Question**: Do terminal colors (#00FF00, #FFBF00) on black meet WCAG contrast requirements?

**Decision**: Black (#000000) background with bright green (#00FF00) primary and amber (#FFBF00) accent

**Rationale**:
- Green on black: Contrast ratio 21:1 (exceeds WCAG AAA 7:1 requirement)
- Amber on black: Contrast ratio 12:1 (exceeds WCAG AA 4.5:1 requirement)
- High contrast essential for accessibility
- Maintains authentic terminal aesthetic

**Alternatives Considered**:
- Dark gray (#1a1a1a) background: Rejected as reduces contrast and less terminal-like
- Lighter green (#00cc00): Not needed as #00FF00 already compliant
- White text: Rejected as breaks terminal aesthetic

**Implementation Notes**:
- Use online contrast checker to verify ratios
- Test with screen reader (VoiceOver, NVDA)
- Ensure color is not the only way to convey information

---

### 7. Bilingual Content Display

**Question**: How to display English and Chinese content clearly?

**Decision**: Alternate English and Chinese lines with proper `lang` attributes

**Rationale**:
- Visual pattern is easy to scan (English, then Chinese translation)
- `lang` attributes help screen readers pronounce correctly
- No JavaScript state management needed
- Mobile-friendly (vertical layout)

**Alternatives Considered**:
- Side-by-side columns: Rejected as breaks on mobile, causes horizontal scroll
- Toggle button: Rejected as requires JS state, hides content
- Tooltip on hover: Rejected as inaccessible on mobile

**Implementation Notes**:
```html
Date: October 31, 2025
日期：2025年10月31日
```

---

### 8. Blinking Cursor Animation

**Question**: How to create a blinking cursor effect for "i'm lovin' IT" tagline?

**Decision**: CSS `@keyframes` animation with `opacity` toggle

**Rationale**:
- Pure CSS solution (no JS needed)
- Performant (GPU accelerated)
- Respects `prefers-reduced-motion` for accessibility
- Simple to implement

**Alternatives Considered**:
- JavaScript setInterval: Rejected as unnecessary complexity and JS dependency
- CSS `visibility` toggle: Works but `opacity` is smoother
- Underscore character: Static, no animation

**Implementation Notes**:
```css
.cursor {
  animation: blink 1s step-end infinite;
}

@keyframes blink {
  50% { opacity: 0; }
}

@media (prefers-reduced-motion: reduce) {
  .cursor { animation: none; opacity: 1; }
}
```

---

### 9. Performance Optimization for Single-File HTML

**Question**: How to keep file size under 50KB and load time under 1 second?

**Decision**: Minify repeated whitespace in ASCII art, use CSS shorthand, optimize countdown logic

**Rationale**:
- ASCII art is the largest contributor to file size
- Removing unnecessary spaces in art while maintaining structure
- CSS shorthand reduces bytes (e.g., `margin: 0 auto` vs separate properties)
- Efficient countdown calculation (no repeated string operations)

**Alternatives Considered**:
- Gzip compression: Rejected as hosting-dependent, not in our control
- Base64 encode ASCII: Rejected as increases size and reduces readability
- External CSS/JS: Rejected due to single-file constraint

**Implementation Notes**:
- Keep ASCII art minimal but recognizable
- Use CSS shorthand: `margin`, `padding`, `font`
- Cache DOM selectors in JS
- Use template literals efficiently

---

### 10. Favicon Implementation Without External File

**Question**: How to add a favicon while maintaining single-file constraint?

**Decision**: Use data URI for emoji favicon (🎃)

**Rationale**:
- Data URI embeds image directly in HTML
- Emoji favicons widely supported in modern browsers
- Keeps single-file architecture intact
- Pumpkin emoji perfect for Halloween theme

**Alternatives Considered**:
- SVG data URI: Rejected as more complex for simple icon
- No favicon: Rejected as reduces professional appearance
- External .ico file: Rejected due to single-file requirement

**Implementation Notes**:
```html

```

---

## Edge Case Decisions

### Post-Countdown Behavior

**Question**: What should display when countdown reaches zero?

**Decision**: Show "🎃 EVENT STARTING NOW! 🎃" message

**Rationale**: Clear indication event has begun, maintains festive theme

---

### Post-Event Behavior

**Question**: What should happen after Oct 31 2025 21:00 GMT+8?

**Decision**: Display "👻 EVENT COMPLETED - Thanks for joining! 👻"

**Rationale**: Graceful post-event message, acknowledges participants

---

### JavaScript Disabled

**Question**: What if user has JavaScript disabled?

**Decision**: All content remains visible; countdown shows "Enable JavaScript for live countdown"

**Rationale**: Progressive enhancement - core content accessible without JS

---

### Very Small Screens (<320px)

**Question**: How to handle screens smaller than 320px?

**Decision**: Ultra-minimal ASCII art (just "McD" text), prioritize readability

**Rationale**: Maintain functionality over aesthetics on extreme constraints

---

## Technology Stack Confirmation

**Language/Version**: HTML5, CSS3, JavaScript ES6+
**Dependencies**: None (fully self-contained)
**Browser Targets**: Chrome, Firefox, Safari, Edge (latest 2 versions)
**Performance Targets**: < 1 second load, < 50KB file size
**Accessibility Target**: WCAG 2.1 AA compliance

## Next Steps

All technical unknowns resolved. Ready for Phase 1: Design & Contracts.

**Outputs**:
- data-model.md (entity definitions)
- contracts/ (JSON schema)
- quickstart.md (testing checklist)
- CLAUDE.md updates (agent context)