b289d87033
- Creata nuova skill agency-shared-references con 24 references centralizzate - Spostate tutte le references da cartelle sparse (references/, agency-web-developer/, agency-archivist/) in un'unica posizione - Aggiornati tutti i symlink delle 14 skills per puntare a ../agency-shared-references/references - Aggiornati tutti i riferimenti nei SKILL.md (percorsi coerenti) - README.md aggiornato con nuova struttura e istruzioni generiche - INSTALL.sh semplificato con istruzioni platform-agnostic - Eliminata cartella references/ dal root (ora centralizzata) - Struttura più pulita e mantenibile, facile da installare su qualsiasi piattaforma
418 lines
9.7 KiB
Markdown
418 lines
9.7 KiB
Markdown
# HTML Semantics — Best Practices
|
||
|
||
Guida per costruire HTML semantico, accessibile e SEO-friendly.
|
||
|
||
---
|
||
|
||
## Document Structure
|
||
|
||
### Base Template
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html lang="it">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="description" content="{descrizione pagina}">
|
||
<title>{Titolo pagina} | {Brand}</title>
|
||
|
||
<!-- CSS -->
|
||
<link rel="stylesheet" href="css/main.css">
|
||
|
||
<!-- Favicon -->
|
||
<link rel="icon" href="assets/img/favicon.ico" type="image/x-icon">
|
||
</head>
|
||
<body>
|
||
<header>{Navigation}</header>
|
||
<main>{Contenuto principale}</main>
|
||
<footer>{Footer}</footer>
|
||
|
||
<!-- JS -->
|
||
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
|
||
<script src="js/main.js"></script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
---
|
||
|
||
## Semantic Elements
|
||
|
||
### Header
|
||
|
||
```html
|
||
<header>
|
||
<nav aria-label="Main navigation">
|
||
<a href="/" class="logo">
|
||
<img src="assets/img/logo.svg" alt="{Brand Name}">
|
||
</a>
|
||
<ul class="nav-menu">
|
||
<li><a href="/">Home</a></li>
|
||
<li><a href="/pages/services.html">Servizi</a></li>
|
||
<li><a href="/pages/about.html">Chi Siamo</a></li>
|
||
<li><a href="/pages/contact.html">Contatti</a></li>
|
||
</ul>
|
||
<button class="mobile-menu-toggle" aria-label="Toggle menu">
|
||
<span></span>
|
||
<span></span>
|
||
<span></span>
|
||
</button>
|
||
</nav>
|
||
</header>
|
||
```
|
||
|
||
### Main Content
|
||
|
||
```html
|
||
<main>
|
||
<!-- Hero Section -->
|
||
<section class="hero" aria-labelledby="hero-title">
|
||
<h1 id="hero-title">Headline principale</h1>
|
||
<p class="hero-sub">Subcopy di supporto</p>
|
||
<a href="#cta" class="btn btn-primary">Call to Action</a>
|
||
</section>
|
||
|
||
<!-- Services Section -->
|
||
<section class="services" aria-labelledby="services-title">
|
||
<h2 id="services-title">I Nostri Servizi</h2>
|
||
<div class="services-grid">
|
||
<article class="service-card">
|
||
<h3>Servizio 1</h3>
|
||
<p>Descrizione servizio</p>
|
||
<a href="#">Scopri di più</a>
|
||
</article>
|
||
<!-- Altre card -->
|
||
</div>
|
||
</section>
|
||
|
||
<!-- Testimonial Section -->
|
||
<section class="testimonials" aria-labelledby="testimonials-title">
|
||
<h2 id="testimonials-title">Dicono di Noi</h2>
|
||
<article class="testimonial">
|
||
<blockquote>
|
||
<p>"Testimonial text"</p>
|
||
</blockquote>
|
||
<cite>— Nome Cliente, Azienda</cite>
|
||
</article>
|
||
</section>
|
||
|
||
<!-- FAQ Section -->
|
||
<section class="faq" aria-labelledby="faq-title">
|
||
<h2 id="faq-title">Domande Frequenti</h2>
|
||
<div class="faq-list">
|
||
<article class="faq-item">
|
||
<h3>
|
||
<button class="faq-question" aria-expanded="false">
|
||
Domanda 1
|
||
</button>
|
||
</h3>
|
||
<div class="faq-answer">
|
||
<p>Risposta alla domanda</p>
|
||
</div>
|
||
</article>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- CTA Section -->
|
||
<section class="cta" aria-labelledby="cta-title">
|
||
<h2 id="cta-title">Pronto a Iniziare?</h2>
|
||
<a href="/pages/contact.html" class="btn btn-primary" id="cta">Contattaci</a>
|
||
</section>
|
||
</main>
|
||
```
|
||
|
||
### Footer
|
||
|
||
```html
|
||
<footer>
|
||
<div class="footer-content">
|
||
<div class="footer-brand">
|
||
<img src="assets/img/logo.svg" alt="{Brand Name}">
|
||
<p>Descrizione breve del brand</p>
|
||
</div>
|
||
<nav aria-label="Footer navigation">
|
||
<ul>
|
||
<li><a href="/">Home</a></li>
|
||
<li><a href="/pages/services.html">Servizi</a></li>
|
||
<li><a href="/pages/about.html">Chi Siamo</a></li>
|
||
<li><a href="/pages/contact.html">Contatti</a></li>
|
||
</ul>
|
||
</nav>
|
||
<div class="footer-contact">
|
||
<p>Email: info@example.com</p>
|
||
<p>Tel: +39 123 456 7890</p>
|
||
</div>
|
||
<div class="footer-social">
|
||
<a href="#" aria-label="Facebook">FB</a>
|
||
<a href="#" aria-label="Instagram">IG</a>
|
||
<a href="#" aria-label="LinkedIn">LI</a>
|
||
</div>
|
||
</div>
|
||
<div class="footer-bottom">
|
||
<p>© 2024 {Brand Name}. Tutti i diritti riservati.</p>
|
||
<nav aria-label="Legal navigation">
|
||
<a href="/pages/privacy.html">Privacy Policy</a>
|
||
<a href="/pages/cookie.html">Cookie Policy</a>
|
||
</nav>
|
||
</div>
|
||
</footer>
|
||
```
|
||
|
||
---
|
||
|
||
## Heading Hierarchy
|
||
|
||
### Regole
|
||
|
||
1. **Un solo H1 per pagina** (di solito nella hero)
|
||
2. **Mai saltare livelli** (H2 → H3 → H4, non H2 → H4)
|
||
3. **Heading descrittivi** (non "Section 1", ma "I Nostri Servizi")
|
||
4. **Keyword rilevanti** (SEO-friendly ma naturale)
|
||
|
||
### Esempio Corretto
|
||
|
||
```html
|
||
<h1>Consulenza Marketing Digitale</h1>
|
||
|
||
<section>
|
||
<h2>I Nostri Servizi</h2>
|
||
|
||
<article>
|
||
<h3>SEO Optimization</h3>
|
||
<p>...</p>
|
||
</article>
|
||
|
||
<article>
|
||
<h3>Social Media Management</h3>
|
||
<p>...</p>
|
||
</article>
|
||
</section>
|
||
|
||
<section>
|
||
<h2>Perché Sceglierci</h2>
|
||
<h3>Esperienza Decennale</h3>
|
||
<h3>Team Certificato</h3>
|
||
</section>
|
||
```
|
||
|
||
---
|
||
|
||
## Accessibility
|
||
|
||
### ARIA Labels
|
||
|
||
```html
|
||
<!-- Navigation -->
|
||
<nav aria-label="Main navigation">...</nav>
|
||
<nav aria-label="Footer navigation">...</nav>
|
||
|
||
<!-- Sections -->
|
||
<section aria-labelledby="services-title">
|
||
<h2 id="services-title">Servizi</h2>
|
||
</section>
|
||
|
||
<!-- Buttons -->
|
||
<button aria-label="Close menu" class="close-btn">×</button>
|
||
<button aria-label="Toggle FAQ" aria-expanded="false" class="faq-question">
|
||
Domanda
|
||
</button>
|
||
|
||
<!-- Forms -->
|
||
<label for="email">Email</label>
|
||
<input type="email" id="email" name="email" required aria-required="true">
|
||
|
||
<!-- Images -->
|
||
<img src="team-photo.jpg" alt="Team di 5 persone in ufficio">
|
||
<img src="decorative-pattern.svg" alt="" role="presentation">
|
||
```
|
||
|
||
### Focus States
|
||
|
||
```css
|
||
/* Assicurati che tutti gli elementi focusabili abbiano visible focus */
|
||
a:focus,
|
||
button:focus,
|
||
input:focus,
|
||
select:focus,
|
||
textarea:focus {
|
||
outline: 2px solid #005fcc;
|
||
outline-offset: 2px;
|
||
}
|
||
|
||
/* Skip link per keyboard navigation */
|
||
.skip-link {
|
||
position: absolute;
|
||
top: -40px;
|
||
left: 0;
|
||
background: #005fcc;
|
||
color: white;
|
||
padding: 8px;
|
||
z-index: 100;
|
||
}
|
||
|
||
.skip-link:focus {
|
||
top: 0;
|
||
}
|
||
```
|
||
|
||
```html
|
||
<body>
|
||
<a href="#main-content" class="skip-link">Vai al contenuto principale</a>
|
||
<header>...</header>
|
||
<main id="main-content">...</main>
|
||
</body>
|
||
```
|
||
|
||
---
|
||
|
||
## Images
|
||
|
||
### Best Practices
|
||
|
||
```html
|
||
<!-- Immagine con descrizione -->
|
||
<img src="team.jpg" alt="Team di 5 persone sorridenti in ufficio moderno">
|
||
|
||
<!-- Immagine decorativa (no alt text) -->
|
||
<img src="pattern.svg" alt="" role="presentation">
|
||
|
||
<!-- Immagine responsive -->
|
||
<img
|
||
src="hero-mobile.jpg"
|
||
srcset="hero-mobile.jpg 480w, hero-tablet.jpg 768w, hero-desktop.jpg 1200w"
|
||
sizes="(max-width: 480px) 100vw, (max-width: 768px) 100vw, 100vw"
|
||
alt="Hero image"
|
||
>
|
||
|
||
<!-- Lazy loading -->
|
||
<img src="placeholder.jpg" data-src="actual-image.jpg" loading="lazy" alt="Descrizione">
|
||
```
|
||
|
||
---
|
||
|
||
## Forms
|
||
|
||
### Contact Form
|
||
|
||
```html
|
||
<form action="https://formspree.io/f/{id}" method="POST" class="contact-form">
|
||
<div class="form-group">
|
||
<label for="name">Nome Completo</label>
|
||
<input
|
||
type="text"
|
||
id="name"
|
||
name="name"
|
||
required
|
||
aria-required="true"
|
||
autocomplete="name"
|
||
>
|
||
</div>
|
||
|
||
<div class="form-group">
|
||
<label for="email">Email</label>
|
||
<input
|
||
type="email"
|
||
id="email"
|
||
name="email"
|
||
required
|
||
aria-required="true"
|
||
autocomplete="email"
|
||
>
|
||
</div>
|
||
|
||
<div class="form-group">
|
||
<label for="message">Messaggio</label>
|
||
<textarea
|
||
id="message"
|
||
name="message"
|
||
rows="5"
|
||
required
|
||
aria-required="true"
|
||
></textarea>
|
||
</div>
|
||
|
||
<button type="submit" class="btn btn-primary">Invia Messaggio</button>
|
||
|
||
<p class="form-note">
|
||
<small>Inviando questo form accetti la nostra
|
||
<a href="/pages/privacy.html">privacy policy</a>.</small>
|
||
</p>
|
||
</form>
|
||
```
|
||
|
||
---
|
||
|
||
## SEO On-Page
|
||
|
||
### Meta Tags
|
||
|
||
```html
|
||
<head>
|
||
<!-- Required -->
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>{Keyword Primaria} | {Brand Name}</title>
|
||
<meta name="description" content="{150-160 caratteri con keyword}">
|
||
|
||
<!-- Open Graph (social sharing) -->
|
||
<meta property="og:title" content="{Titolo pagina}">
|
||
<meta property="og:description" content="{Descrizione}">
|
||
<meta property="og:image" content="https://example.com/assets/img/og-image.jpg">
|
||
<meta property="og:url" content="https://example.com/pagina.html">
|
||
<meta property="og:type" content="website">
|
||
|
||
<!-- Twitter Card -->
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:title" content="{Titolo}">
|
||
<meta name="twitter:description" content="{Descrizione}">
|
||
<meta name="twitter:image" content="https://example.com/assets/img/twitter-image.jpg">
|
||
|
||
<!-- Canonical URL -->
|
||
<link rel="canonical" href="https://example.com/pagina.html">
|
||
</head>
|
||
```
|
||
|
||
### Structured Data (JSON-LD)
|
||
|
||
```html
|
||
<script type="application/ld+json">
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": "LocalBusiness",
|
||
"name": "{Brand Name}",
|
||
"image": "https://example.com/assets/img/logo.png",
|
||
"description": "{Descrizione business}",
|
||
"address": {
|
||
"@type": "PostalAddress",
|
||
"streetAddress": "Via Roma 123",
|
||
"addressLocality": "Milano",
|
||
"postalCode": "20100",
|
||
"addressCountry": "IT"
|
||
},
|
||
"telephone": "+391234567890",
|
||
"url": "https://example.com"
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
## Checklist Semantica
|
||
|
||
- [ ] Un solo H1 per pagina
|
||
- [ ] Heading hierarchy corretta (no salti)
|
||
- [ ] Tag semantici usati (`<header>`, `<main>`, `<footer>`, `<section>`, `<article>`, `<nav>`)
|
||
- [ ] ARIA labels dove necessario
|
||
- [ ] Alt text su tutte le immagini (o vuoto per decorative)
|
||
- [ ] Form label associati correttamente
|
||
- [ ] Focus states visibili
|
||
- [ ] Skip link per keyboard navigation
|
||
- [ ] Meta title + description unici per pagina
|
||
- [ ] Canonical URL impostata
|
||
- [ ] Open Graph tags per social sharing
|
||
|
||
---
|
||
|
||
_References per agency-web-developer skill_
|