Guida al miglioramento dello stile

Questa guida documenta i token del sistema di design e le classi dei componenti implementati in styles/custom.css. Costituisce un riferimento per i token di bordo, superficie, ombra, raggio, pulsante, gradiente, transizione, focus e tipografia utilizzati nell’intero tema.

Stato: Tutti i token di design e le classi dei componenti descritti di seguito sono implementati e disponibili per l’uso.

Come leggere questa guida

Ogni sezione documenta una categoria di token:

1. Definizioni dei token — proprietà CSS personalizzate con valori per modalità chiara/scura
2. Mappatura dei componenti — quali componenti del tema utilizzano ciascun token
3. Note di implementazione — indicazioni d’uso e considerazioni sull’accessibilità

Le tabelle dei token sono suddivise per modalità chiara e modalità scura quando i valori differiscono.

---

1. Sistema colori

Bordi con trasparenza alpha

Il tema utilizza bordi con trasparenza alpha invece di colori grigi solidi. Ciò consente ai bordi di adattarsi naturalmente a qualsiasi sfondo.

/* Pattern bordo con trasparenza alpha */
border: 1px solid var(--f5-border-default);  /* neutral at 20% alpha */

Token bordo

/* Light mode */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 at 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 at 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 at 40% */
}

/* Dark mode */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 at 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 at 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 at 40% */
}

Casi d’uso dei bordi

Token	Opacità	Caso d’uso
--f5-border-faint	10%	Separatori sottili, righe di tabella
--f5-border-default	20%	Bordi predefiniti, contorni card
--f5-border-strong	40%	Bordi enfatizzati, stati attivi

Stato: Completato — implementato in styles/custom.css.

Colori superficie interattiva

Token semantici di superficie per stati hover e attivi.

Superfici in modalità chiara

Token	Valore	Scopo
--f5-white	#ffffff	Sfondi principali
--f5-white-1	#faf9f7	Barra laterale, aree sottili
--f5-white-2	#f5f5f5	Superfici elevate
--f5-surface-hover	var(--f5-white-2)	Riempimento hover
--f5-surface-active	var(--f5-white-3)	Riempimento premuto/attivo

Superfici in modalità scura

Token	Valore	Scopo
--f5-black	#000000	Sfondi principali
--f5-black-4	#222222	Barra laterale, aree sottili
--f5-surface-hover	var(--f5-black-3)	Riempimento hover
--f5-surface-active	var(--f5-black-2)	Riempimento premuto/attivo

Definizioni dei token di superficie

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

Stato: Completato — implementato in styles/custom.css.

---

2. Sistema di elevazione e ombra

Scala delle ombre

Il tema utilizza ombre alpha con tinta neutra con valori a doppio strato per una profondità naturale. La modalità chiara usa --f5-black-3 (#343434) come base di tinta; la modalità scura usa #cccccc.

Ombre in modalità chiara

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

Ombre in modalità scura

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

Mappatura delle ombre sui componenti

Componente	Livello ombra
.swatch, .icon-card	--f5-shadow-low (a riposo)
.starlight-aside	--f5-shadow-low
.expressive-code .frame	--f5-shadow-mid
.mermaid-container	--f5-shadow-mid
Card al hover	--f5-shadow-mid
Dropdown, popover	--f5-shadow-high
Modal	--f5-shadow-higher

Stato: Completato — tutti i livelli di ombra (inset, low, mid, high, higher) implementati in styles/custom.css.

---

3. Scala del raggio del bordo

Token raggio

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — badge, tag */
  --f5-radius-sm: 0.3125rem;   /* 5px — elementi di navigazione, controlli piccoli */
  --f5-radius-md: 0.375rem;    /* 6px — card, blocchi di codice */
  --f5-radius-lg: 0.5rem;      /* 8px — modal, contenitori grandi */
  --f5-radius-full: 999px;     /* pills, arrotondamento completo */
}

Mappatura del raggio sui componenti

Componente	Token raggio
.swatch	--f5-radius-md (6px)
.icon-card	--f5-radius-md (6px)
.starlight-aside	--f5-radius-md (6px)
.expressive-code .frame	--f5-radius-md (6px)
.mermaid-container	--f5-radius-lg (8px)
.edit-link	--f5-radius-full (pill)
Elementi di navigazione barra laterale	--f5-radius-sm (5px)
Badge	--f5-radius-xs (3px)

Stato: Completato — scala del raggio (xs, sm, md, lg, full) implementata in styles/custom.css.

---

4. Stile della navigazione nella barra laterale

Stili degli elementi della barra laterale

/* Elementi di navigazione barra laterale */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* Hover in modalità chiara */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* Hover in modalità scura */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* Indicatore pagina attiva */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 light */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → adjust for readability */
}

Indicatore accent a sinistra

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* compensate for border */
}

Stato: Completato — hover, stato attivo e indicatore accent della barra laterale implementati in styles/custom.css.

---

5. Sistema dei pulsanti

Varianti pulsante

/* Primario — utilizza F5 Red come azione brand */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* Secondario — stile con contorno */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* Terziario — ghost/solo testo */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

Scala dimensioni pulsante

Dimensione	Padding	Dimensione font	Altezza minima
Piccolo	0.375rem 0.75rem	0.8125rem (13px)	32px
Medio (predefinito)	0.625rem 1rem	0.875rem (14px)	40px
Grande	0.75rem 1.5rem	1rem (16px)	48px

Stato: Completato — tutte le varianti pulsante (primary, secondary, tertiary, critical) e la scala dimensioni (sm, predefinito, lg) implementate in styles/custom.css.

---

6. Sfondi hero e intestazione

Gradienti hero

Utilizzo della palette brand F5:

/* Gradiente hero primario — River blue */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* Sfumatura di pagina tenue — tono caldo sottile */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* Variante Eggplant per pagine di funzionalità */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* Variante brand Red per annunci */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

Tecniche di overlay gradiente

/* Vignettatura radiale per profondità */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* Dissolvenza in basso verso lo sfondo della pagina */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

Stato: Completato — gradienti hero (primary, eggplant, red, faint) e overlay (hero-fade, hero-vignette) implementati in styles/custom.css.

---

7. Effetti hover e transizioni

Token di transizione

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

Token	Durata	Easing	Caso d’uso
--f5-transition-fast	0.15s	ease	La maggior parte degli stati hover, cambi di colore
--f5-transition-base	0.2s	ease	Riempimenti di sfondo, cambi di bordo
--f5-transition-bounce	0.2s	cubic-bezier(0.68, -0.2, 0.265, 1.15)	Switch, toggle
--f5-transition-decelerate	0.6s	cubic-bezier(0.5, 1, 0.89, 1)	Indicatori tab, pannelli scorrevoli
--f5-transition-spring	0.2s	cubic-bezier(0.54, 1.5, 0.38, 1.11)	Tooltip, ingresso popover

Cosa animare

Proprietà	Sicuro da animare	Note
background-color	Sì	Standard per riempimenti hover
color	Sì	Cambi di colore del testo
border-color	Sì	Enfasi del bordo al hover
box-shadow	Sì	Cambi di elevazione (usare will-change in caso di scatti)
transform	Sì	Scala, traslazione per feedback
opacity	Sì	Dissolvenza in entrata/uscita
width, height	Evitare	Causa ricalcolo del layout
padding, margin	Evitare	Causa ricalcolo del layout

Mappatura delle transizioni sui componenti

/* Elementi di navigazione barra laterale */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* Card — sollevamento ombra al hover */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* Pulsanti */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* Link */
a {
  transition: color var(--f5-transition-fast);
}

Stato: Completato — tutti e cinque i token di transizione (fast, base, bounce, decelerate, spring) e le transizioni dei componenti implementati in styles/custom.css.

---

8. Sistema degli anelli di focus

Token anello di focus

Il tema utilizza un pattern a doppio anello con un anello interno inset e un alone esterno:

/* Focus azione — utilizzo di F5 River blue */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* Applicare agli elementi interattivi */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* Variante critica per pulsanti distruttivi */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

Note sull’accessibilità

• Il pattern a doppio anello soddisfa i requisiti di WCAG 2.2 Focus Appearance (contorno a contrasto minimo di 2px)
• L’utilizzo di box-shadow invece di outline consente di rispettare il border-radius
• :focus-visible garantisce che l’anello appaia solo per la navigazione da tastiera, non per i clic del mouse

Stato: Completato — pattern di focus a doppio anello (action, critical) e stili :focus-visible implementati in styles/custom.css.

---

9. Tipografia

Stack di font

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

Scala tipografica

Scala	Dimensione	Altezza riga	Utilizzo
Display 500	1.875rem (30px)	1.267	--sl-text-h1
Display 400	1.5rem (24px)	1.333	--sl-text-h2
Display 300	1.125rem (18px)	1.333	--sl-text-h3
Display 200	1rem (16px)	1.5	--sl-text-h4
Display 100	0.8125rem (13px)	1.385	Testo overline
Body 300	1rem (16px)	1.5	Corpo principale
Body 200	0.875rem (14px)	1.429	Testo barra laterale, didascalie
Body 100	0.8125rem (13px)	1.385	Testo in piccolo

Caratteristiche principali

Aspetto	Valore	Note
Altezza riga intestazione	1.1	Intestazioni compatte per impatto brand; considerare 1.2 per leggibilità
Altezza riga corpo	1.5 (predefinito Starlight)	Ben adatta alla lettura
Famiglia di font	Font brand personalizzati	proximaNova (corpo), neusaNextProWide (intestazioni)
Peso intestazioni	h1-h2: 700, h3: 500, h4-h6: 700 uppercase	Opinionato per coerenza brand

Priorità: Nessuna modifica necessaria. La tipografia attuale è ben definita e appropriata al brand. Una piccola correzione all’altezza riga delle intestazioni (da 1.1 a 1.2) è opzionale.

---

10. Registro delle modifiche all’implementazione

Tutti i token di design sono stati implementati in cinque sprint:

Sprint	Ambito	Token aggiunti
1. Fondamenta	Ombre + raggio bordo	--f5-shadow-* (5 livelli), --f5-radius-* (5 livelli)
2. Barra laterale + Superfici	Navigazione + token interattivi	--f5-surface-hover, --f5-surface-active, --f5-border-* (3 livelli), --f5-transition-fast
3. Pulsanti	Sistema di componenti	.btn-primary, .btn-secondary, .btn-tertiary, .btn-critical, varianti dimensione
4. Gradienti hero	Utility di sfondo	.hero-gradient-primary, -eggplant, -red, -faint, .hero-vignette, .hero-fade
5. Focus + Transizioni	Accessibilità + rifinitura	--f5-focus-action, --f5-focus-critical, --f5-transition-* (5 token), effetti hover card

---

Riferimento rapido: riepilogo dei token

Tutte le proprietà personalizzate

:root {
  /* Scala raggio bordo */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* Timing transizioni */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* Anelli di focus */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* Ombre modalità scura (predefinito) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* Bordi modalità scura */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* Superfici modalità scura */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* Ombre modalità chiara */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* Bordi modalità chiara */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* Superfici modalità chiara */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}