How to Deploy & Use bendc/frontend-guidelines

# Frontend Guidelines - Deployment and Usage Guide

This repository contains HTML, CSS, and JavaScript best practices. As a documentation-only project, it requires no build process, but this guide covers accessing the guidelines locally and applying them to your own projects.

## 1. Prerequisites

- **Git** (to clone the repository)
- **Modern web browser** (Chrome, Firefox, Safari, or Edge)
- **Text editor** (VS Code, Sublime Text, or similar with Markdown support)
- **Optional**: Python 3.x or Node.js (for local static file serving)

## 2. Installation

Clone the repository to access the guidelines locally:

```bash
git clone https://github.com/bendc/frontend-guidelines.git
cd frontend-guidelines

No package installation or dependency management is required—this repository contains static documentation and code examples only.

3. Configuration

This project requires no configuration files. However, when applying these guidelines to your own HTML projects, ensure these document-level configurations:

Required in every HTML file:

<!doctype html>
<html lang=en>
  <meta charset=utf-8>
  <title>Your Page Title</title>

Always declare lang on the root element (adjust en to your content language)
Always declare charset=utf-8 within the first 1024 bytes of the document
Omit type=text/css and type=text/javascript (unnecessary in HTML5)

4. Build & Run

Viewing the Guidelines Locally

Since this is a Markdown documentation repository, there is no build step. Choose one of the following methods:

Option A: Direct file access Open README.md in your text editor or Markdown previewer.

Option B: Local HTTP server (for browser preview)

# Using Python 3
python3 -m http.server 8000

# Using Node.js (if installed)
npx serve .

Then navigate to http://localhost:8000 and view the README.

Implementing the Guidelines in a New Project

To create a project following these standards:

Create index.html using semantic HTML5 elements (<main>, <article>, <header>, etc.)
Create style.css with global box model normalization:
```
* { box-sizing: border-box; }
```
Structure CSS to minimize specificity (avoid IDs and !important)
Place scripts at the end of the document or use defer to avoid blocking rendering

5. Deployment

Deploying This Documentation

Host this repository on any static site platform:

GitHub Pages:

Push repository to GitHub
Go to Settings > Pages
Select source branch (main or master)
Access at https://[username].github.io/frontend-guidelines

Netlify/Vercel:

Connect repository to platform
Build command: (leave empty)
Publish directory: / (root)

Deploying Projects Using These Guidelines

When deploying frontend projects that implement these guidelines:

Performance Requirements:

Ensure <meta charset=utf-8> is present in the first 1024 bytes
Defer non-critical scripts (place before closing </html> or use defer attribute)
If CSS is heavy, split into critical (above-fold) and non-critical files
Maintain semantic HTML structure for accessibility

Platform Recommendations:

GitHub Pages: Ideal for simple static sites following these guidelines
Netlify/Vercel: Supports atomic deploys and CDN distribution for optimal performance
Traditional hosting: Ensure server sends Content-Type: text/html; charset=utf-8 header

6. Troubleshooting

Character Encoding Issues

Symptom: Special characters display as or mojibake
Solution: Verify <meta charset=utf-8> appears before <title> and within the first 1024 bytes. Do not use the legacy http-equiv form.

CSS Specificity Conflicts

Symptom: Styles won't override despite correct selectors
Solution: Avoid using id selectors and !important. Instead, use class combinations as shown in the guidelines:

/* Instead of !important */
.foo.bar {
  color: green;
}
.foo {
  color: red;
}

Box Model Calculation Errors

Symptom: Elements exceed container widths with padding/borders
Solution: Apply * { box-sizing: border-box; } globally rather than changing box models on specific elements. Do not mix content-box and border-box within the same component.

Layout Flow Disruption

Symptom: Elements positioned incorrectly or removed from document flow unexpectedly
Solution: Avoid position: absolute for layout. Use modern alternatives:

Flexbox for one-dimensional layouts (navigation, centering)
Grid for two-dimensional layouts (page structures)
Use margin-left: auto instead of position: absolute; right: 0 for pushing elements right

Slow Initial Page Render

Symptom: Blank page while scripts load
Solution: Move <script> tags to the end of the document (before closing </html>) or use the defer attribute. Never place blocking scripts in the <head> unless absolutely necessary.

Accessibility Warnings

Symptom: Screen readers not interpreting content correctly
Solution:

Replace <div class=button> with actual <button> elements
Ensure images have descriptive alt attributes (not just "Logo" but "Company Name")
Use <time datetime=YYYY-MM-DD> for dates, not just text