diff --git a/.cursor/rules/host-resources-locally.mdc b/.cursor/rules/host-resources-locally.mdc new file mode 100644 index 0000000..fc1ee84 --- /dev/null +++ b/.cursor/rules/host-resources-locally.mdc @@ -0,0 +1,78 @@ +--- +description: Host all resources locally - avoid CDN dependencies +alwaysApply: true +--- + +# Host All Resources Locally + +## Principle + +**All external resources (CSS, JavaScript, fonts, images) must be hosted locally** within the repository. Do not use CDN links or external dependencies. + +## Rationale + +- **Privacy & Security**: No external requests, better user privacy +- **Reliability**: No dependency on external CDN availability +- **Offline Support**: Site works without internet connection +- **Version Control**: All dependencies tracked in git +- **Performance**: No DNS lookups or external network latency +- **Compliance**: Better for strict security policies + +## Implementation Guidelines + +### CSS Frameworks +- Download and commit CSS files to `/lib/` directory +- Example: Bootstrap should be in `/lib/bootstrap/` not from CDN +- Use versioned directories if needed: `/lib/bootstrap-5.3.8/` + +### JavaScript Libraries +- Download and commit JS files to `/lib/` directory +- Example: `/lib/lightbox.js` (already implemented) +- No external script tags from CDN + +### Fonts +- Host font files in `/lib/fonts/` or `/css/fonts/` +- Use `@font-face` with local paths +- No Google Fonts or other external font services + +### Images +- All images in `/img/` directory +- No external image hosting + +## Current Status + +⚠️ **Bootstrap is currently loaded from CDN** (`cdn.jsdelivr.net`) +- Should be downloaded and hosted in `/lib/bootstrap/` +- Update `_includes/header.html` to use local path + +## Examples + +### ❌ BAD - Using CDN +```html + + +``` + +### ✅ GOOD - Hosting Locally +```html + + +``` + +## When Adding New Dependencies + +1. Download the resource file(s) +2. Place in appropriate `/lib/` subdirectory +3. Reference with local path (`/lib/...`) +4. Commit to repository +5. Update `.gitignore` if needed (but generally commit all lib files) + +## Migration Checklist + +When migrating from CDN to local: +- [ ] Download resource files +- [ ] Place in `/lib/` directory structure +- [ ] Update HTML references to local paths +- [ ] Test build and verify resources load +- [ ] Update CSP headers if needed (remove CDN domains) +- [ ] Commit changes diff --git a/.cursor/rules/minimal-code-max-reuse.mdc b/.cursor/rules/minimal-code-max-reuse.mdc new file mode 100644 index 0000000..410631a --- /dev/null +++ b/.cursor/rules/minimal-code-max-reuse.mdc @@ -0,0 +1,209 @@ +--- +description: Minimal code philosophy - less is more, maximize reuse +alwaysApply: true +--- + +# Minimal Code, Maximum Reuse + +## Principle + +**Less code is more.** Write minimal, reusable CSS with maximum definition reuse. Consolidate duplicate properties, group selectors, and eliminate redundancy. + +## Rationale + +- **Maintainability**: Less code means fewer places to update +- **Performance**: Smaller CSS files load faster +- **Consistency**: Shared definitions ensure uniform styling +- **Readability**: Consolidated code is easier to understand +- **DRY Principle**: Don't Repeat Yourself + +## Implementation Guidelines + +### CSS Consolidation + +1. **Group Selectors**: Combine selectors that share properties + ```css + /* ❌ BAD - Duplicate properties */ + h1 { font-size: 2rem; font-weight: 400; } + h2 { font-size: 1.75rem; font-weight: 400; } + + /* ✅ GOOD - Shared properties grouped */ + h1, h2 { font-weight: 400; } + h1 { font-size: 2rem; } + h2 { font-size: 1.75rem; } + ``` + +2. **Reuse Base Definitions**: Use base element styles, avoid subpage-specific overrides + ```css + /* ❌ BAD - Redundant subpage definitions */ + #summary h1 { font-size: 2rem; } + #content h1 { font-size: 2rem; } + + /* ✅ GOOD - Single base definition */ + h1 { font-size: 2rem; } + ``` + +3. **Consolidate Repeated Values**: Group selectors with identical properties + ```css + /* ❌ BAD - Repeated properties */ + footer { font-size: 0.875rem !important; color: #fff !important; } + .copyright { font-size: 0.875rem !important; color: #fff !important; } + + /* ✅ GOOD - Consolidated */ + footer, .copyright { font-size: 0.875rem !important; color: #fff !important; } + ``` + +4. **Remove Unnecessary Specificity**: Don't create separate definitions for minor differences + ```css + /* ❌ BAD - Unnecessary specificity */ + ul.contact { list-style: none; margin: 0.625rem; } + ul.quicklinks { list-style: none; margin: 0.625rem; } + + /* ✅ GOOD - Use base ul styles or group if truly needed */ + ul.quicklinks { list-style: none; margin: 0.625rem; } + /* ul.contact uses base ul styles */ + ``` + +5. **Single Font Family Definition**: Define font-family once, inherit everywhere + ```css + /* ❌ BAD - Repeated font-family */ + html { font-family: "Ubuntu", sans-serif; } + h1 { font-family: "Ubuntu", sans-serif; } + footer { font-family: "Ubuntu", sans-serif !important; } + + /* ✅ GOOD - Define once */ + html { font-family: "Ubuntu", sans-serif; } + /* All elements inherit */ + ``` + +### Code Minimization + +1. **Remove Redundant Comments**: Don't comment obvious things + ```css + /* ❌ BAD - Obvious comment */ + h1 { font-size: 2rem; /* 32px */ } + + /* ✅ GOOD - No redundant comment */ + h1 { font-size: 2rem; } + ``` + +2. **Eliminate Duplicate Rules**: Consolidate identical definitions + ```css + /* ❌ BAD - Duplicate rules */ + .copyright a { text-decoration: none !important; } + /* ... later in file ... */ + .copyright a { text-decoration: none !important; } + + /* ✅ GOOD - Single definition */ + .copyright a { text-decoration: none !important; } + ``` + +3. **Use Shorthand Properties**: Combine related properties + ```css + /* ❌ BAD - Verbose */ + margin-top: 1.25rem; + margin-bottom: 1.25rem; + + /* ✅ GOOD - Shorthand */ + margin: 1.25rem 0; + ``` + +4. **Remove Unused Styles**: Delete CSS that isn't used + ```css + /* ❌ BAD - Unused style */ + .old-class { /* not used anywhere */ } + + /* ✅ GOOD - Removed */ + ``` + +### Formatting Reuse + +1. **Consolidate Similar Components**: Group related styles + ```css + /* ❌ BAD - Separate definitions */ + .carousel-container { width: 100%; position: relative; } + .screenshot-carousel { width: 100%; position: relative; } + + /* ✅ GOOD - Shared properties */ + .carousel-container, + .screenshot-carousel { width: 100%; position: relative; } + ``` + +2. **Reuse Common Patterns**: Extract repeated patterns + ```css + /* ❌ BAD - Repeated pattern */ + .btn { text-decoration: none; } + ul.quicklinks li a { text-decoration: none; } + .copyright a { text-decoration: none; } + + /* ✅ GOOD - Grouped */ + .btn, + ul.quicklinks li a, + .copyright a { text-decoration: none; } + ``` + +## When to Create Separate Definitions + +Only create separate definitions when: +- **Significant visual difference** that can't be achieved with base styles +- **Layout-specific needs** (e.g., carousel positioning) +- **Component-specific behavior** (e.g., hover states for navigation) + +## Examples + +### ✅ GOOD - Maximum Reuse +```css +h1, h2 { + font-weight: 400; + line-height: 1.3; + margin: 1.25rem 0 0.9375rem 0; +} + +h1 { font-size: 2rem; } +h2 { font-size: 1.75rem; } + +footer, +footer a, +.copyright, +.copyright a { + font-size: 0.875rem !important; + font-weight: 300 !important; + color: #fff !important; +} +``` + +### ❌ BAD - Excessive Duplication +```css +h1 { + font-size: 2rem; + font-weight: 400; + line-height: 1.3; + margin: 1.25rem 0 0.9375rem 0; +} + +h2 { + font-size: 1.75rem; + font-weight: 400; + line-height: 1.3; + margin: 1.25rem 0 0.9375rem 0; +} + +footer { font-size: 0.875rem !important; color: #fff !important; } +.copyright { font-size: 0.875rem !important; color: #fff !important; } +``` + +## Checklist + +When writing or modifying CSS: +- [ ] Are there duplicate properties that can be grouped? +- [ ] Can subpage-specific definitions be removed in favor of base styles? +- [ ] Are there repeated values that can be consolidated? +- [ ] Can similar components share common properties? +- [ ] Is the font-family defined only once? +- [ ] Are there redundant comments that can be removed? +- [ ] Can shorthand properties be used? +- [ ] Are there unused styles that can be deleted? + +## Goal + +**Aim for the smallest possible CSS file that maintains all functionality.** Every line should serve a purpose, and every property should be reused wherever possible. diff --git a/.cursor/rules/prefer-html5-over-js.mdc b/.cursor/rules/prefer-html5-over-js.mdc new file mode 100644 index 0000000..aac7549 --- /dev/null +++ b/.cursor/rules/prefer-html5-over-js.mdc @@ -0,0 +1,220 @@ +--- +description: Prefer HTML5 native features over JavaScript implementations +alwaysApply: true +--- + +# Prefer HTML5 Over JavaScript + +## Principle + +**Use native HTML5 features and semantic elements instead of JavaScript implementations** whenever possible. This improves performance, accessibility, and maintainability. + +## Rationale + +- **Performance**: Native browser features are faster than JS implementations +- **Accessibility**: HTML5 semantic elements have built-in ARIA support +- **Progressive Enhancement**: Works without JavaScript enabled +- **Maintainability**: Less code to maintain, fewer bugs +- **SEO**: Search engines better understand semantic HTML +- **Mobile**: Better touch support and native mobile features + +## Guidelines + +### Forms & Input + +#### ❌ BAD - JavaScript validation +```html + + +``` + +#### ✅ GOOD - HTML5 native validation +```html + +``` + +### Navigation & Links + +#### ❌ BAD - JavaScript navigation +```html +
Go to page
+``` + +#### ✅ GOOD - Native anchor tag +```html +Go to page +``` + +### Modals & Dialogs + +#### ❌ BAD - Custom JavaScript modal +```html + + +``` + +#### ✅ GOOD - HTML5 `` element +```html + +

Modal content

+
+ +
+
+ +``` + +### Details & Accordions + +#### ❌ BAD - JavaScript accordion +```html +
Header
+
Content
+``` + +#### ✅ GOOD - HTML5 `
` element +```html +
+ Header +

Content

+
+``` + +### Images & Media + +#### ❌ BAD - JavaScript lazy loading +```html + + +``` + +#### ✅ GOOD - Native lazy loading +```html +Description +``` + +### Video & Audio + +#### ❌ BAD - Custom video controls +```html +