Robots/agency-skills-suite
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Conversione references in skill condivisa agency-shared-references

Browse source 
- 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
This commit is contained in:
AgentePotente 2026-03-11 00:11:03 +01:00
parent c496db151c
commit b289d87033
55 changed files with 288 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

418
agency-web-developer/references/html_semantics.md
View file

@ -1,418 +0,0 @@
# 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>&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
```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_