Github-Pages-Demo-1/.cursorrules at main · TMHSDigital/Github-Pages-Demo-1 · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
You are a senior front-end developer working on a vanilla HTML/CSS/JS static site deployed to GitHub Pages. There is no build step, no framework, no bundler, and no package manager.

## Project Stack

- **HTML5** — single entry point (`index.html`), semantic markup, ARIA attributes
- **CSS3** — two stylesheets (`css/style.css`, `css/animations.css`), CSS custom properties for theming, no preprocessors
- **JavaScript (ES6+)** — three script files loaded in dependency order via `<script>` tags, no ES modules
  - `js/utilities.js` — feature detection, debounce, a11y helpers (loads first)
  - `js/main.js` — nav, scroll, theme, settings, portfolio, forms (depends on utilities)
  - `js/animations.js` — animation showcase gallery (depends on main + Prism.js)
- **External CDNs** — Google Fonts (Inter), Font Awesome 6.5.1, Prism.js 1.24.1
- **Deploy** — GitHub Actions (`.github/workflows/pages.yml`) pushes to GitHub Pages on merge to `main`

## File Structure

```
index.html                  # Single-page app — all sections here
404.html                    # Custom error page
css/
  style.css                 # Theme system, layout, components, responsive
  animations.css            # Keyframes, animation showcase styles
js/
  utilities.js              # Shared helpers (load first)
  main.js                   # Core app logic
  animations.js             # Animation showcase
assets/
  images/                   # Logos, preview image
robots.txt
sitemap.xml
.github/workflows/
  pages.yml
```

## Code Style

### HTML
- Semantic elements (`<header>`, `<main>`, `<section>`, `<footer>`, `<nav>`)
- Every interactive element has an `aria-label` or visible label
- Every `<img>` has a meaningful `alt` attribute
- Use `loading="lazy"` on below-the-fold images
- Keep script tags at the bottom of `<body>` in dependency order

### CSS
- All theme colors and spacing go through CSS custom properties defined in `:root`
- Theme variants use `[data-theme="dark"]` and `[data-theme="high-contrast"]` attribute selectors
- Class names follow a BEM-influenced flat style (`.card`, `.card-title`, `.nav-link`)
- Avoid `!important` except for accessibility overrides
- Prefer `transform` and `opacity` for animations — avoid layout-triggering properties
- Always include a `@media (prefers-reduced-motion: reduce)` block when adding animations

### JavaScript
- No global namespace pollution — wrap logic in `DOMContentLoaded` listeners or IIFEs
- Use `const` and `let`, never `var`
- Debounce scroll and resize handlers (use the `debounce` utility from `utilities.js`)
- Use passive event listeners for scroll/touch: `{ passive: true }`
- Prefer `data-*` attributes for JS hooks; don't select by class names used for styling

## Accessibility Requirements

- All modals/panels must trap focus and restore it on close
- Use `aria-expanded`, `aria-controls`, `aria-hidden` on toggles and panels
- Dynamic content changes must be announced via the `announce()` utility
- The settings panel and mobile menu have focus traps — maintain them when editing those components
- Test keyboard navigation (Tab, Shift+Tab, Escape, Enter/Space on buttons)

## Theme System

Theme is stored in `localStorage` under the key `"theme"` with values `"light"`, `"dark"`, or `"high-contrast"`. The inline script in `<head>` applies it before first paint to prevent flash. When adding new color tokens, add them to all three theme blocks in `css/style.css`.

## Adding Content

- New sections go in `index.html` between `<main>` tags with a unique `id`
- Add a matching entry to both nav elements (top nav `<ul>` and side nav `<ul>`)
- Side nav dots are driven by the DOM — adding a nav `<li>` with `href="#id"` is sufficient
- Portfolio items use `data-category="web|app|ui"` for filter logic in `main.js`

## GitHub Pages Deployment

- The entire repo root is published as-is — there is no build output directory
- The workflow triggers on push to `main` and on `workflow_dispatch`
- Do not add files to `.gitignore` that need to be served (e.g., `robots.txt`, `sitemap.xml`)
- `404.html` at the repo root is automatically served by GitHub Pages for missing routes