Robots/agency-skills-suite
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agency-skills-suite/agency-shared-references/references/html_semantics.md
AgentePotente b289d87033 Conversione references in skill condivisa agency-shared-references 
- 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
2026-03-11 00:11:03 +01:00

9.7 KiB
Raw Blame History

HTML Semantics — Best Practices

Guida per costruire HTML semantico, accessibile e SEO-friendly.

Document Structure

Base Template

<!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

<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

<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

<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>&copy; 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

<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

<!-- 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

/* 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;
}

<body>
  <a href="#main-content" class="skip-link">Vai al contenuto principale</a>
  <header>...</header>
  <main id="main-content">...</main>
</body>

Images

Best Practices

<!-- 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

<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

<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)

<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