# Sistema di progettazione USWDS

## Anteprima dell’interfaccia del sistema di progettazione sistema di design USWDS

Cerca e filtra record fittizi, gestisci l’assenza di risultati ed espandi i pannelli nativi dei requisiti.

## Riferimento di progettazione del sistema di progettazione sistema di design USWDS

Distribuzione nativa dei componenti USWDS 3.14.0. Token predefiniti dalla documentazione ufficiale; le sostituzioni dei font nell’anteprima sono scelte locali esplicite.

### Unità di spaziatura

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| 0.5 / 05 | 4px | Spaziatura a mezze unità e modulo utility |
| 1 | 8px | Unità di spaziatura di base |
| 1.5 / 105 | 12px | Spaziatura intermedia |
| 2 | 16px | Padding interno compatto |
| 3 | 24px | Spazio tra contenuti correlati |
| 4 | 32px | Spaziatura tra sezioni |
| 5 | 40px | Distanza maggiore |
| 6 | 48px | Spaziatura ampia |
| tablet | 640px | Token di larghezza con nome |
| desktop | 1024px | Token di larghezza con nome |
### Mappatura tipografica predefinita

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| sans | source-sans-pro | Token della famiglia basato sul tipo |
| serif | merriweather | Token della famiglia basato sul tipo |
| body / ui | sans | Mappatura basata sui ruoli |
| heading | serif | Mappatura basata sui ruoli |
| code | mono → roboto-mono | Mappatura del ruolo del codice |
### Colori predefiniti del tema

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| primary | blue-60v / #005ea2 | Alias primario |
| primary-lighter | blue-10 / #d9e8f6 | Tinta di supporto del primario |
| primary-dark | blue-warm-70v / #1a4480 | Alias primario più scuro |
| ink | gray-90 / #1b1b1b | Alias del testo principale |
### Contratti dei componenti

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| aria-controls | Panel ID | Collega ogni pulsante dell’accordion al relativo contenuto. |
| aria-expanded | true / false | Il JavaScript nativo mantiene lo stato di apertura. |
| data-allow-multiple | Accordion root attribute | Consente di mantenere aperti più pannelli indipendentemente. |
| usa-accordion--bordered | Root modifier | Fornisce la variante con bordo. |
## USWDS: guida completa al sistema di design

Una guida pratica per scegliere, applicare e valutare questo sistema in un’interfaccia reale.

Indicazioni complete, un punto di partenza per l’implementazione e link alle fonti.

## USWDS: un sistema di design configurabile Foundation

### I token predefiniti sono una configurazione di partenza

> USWDS distingue i token del sistema, le impostazioni del tema del progetto, le classi di utilità e i componenti. Il riferimento seguente riporta le scelte predefinite per il tema indicate nella documentazione attuale. Un programma federale può configurare ruoli tipografici o alias di colore diversi senza sostituire ogni componente.

L’anteprima è un confronto indipendente tra opportunità di ricerca, basato su 3.14.0 CSS e su accordion JavaScript. Non include il banner governativo né i marchi istituzionali. I nomi e le fasi dei programmi sono fittizi e il filtraggio avviene interamente nel browser.

Leggi la specifica di supporto

## USWDS: spaziatura e token del tema del sistema di design

### Leggi l’unità, non il numero

Un’unità di spaziatura USWDS corrisponde a 8px: units(2) significa 16px, mentre units(3) significa 24px. I token di mezza unità consentono spazi più ridotti e la notazione delle classi di utilità usa 05 per indicare mezza unità. La classe margin-2 non indica un margine di due pixel.

La scala include anche larghezze con nome, come tablet e desktop. Questi nomi sono token riutilizzabili, non l’obbligo di riprogettare ogni pagina per ogni larghezza. Il confronto usa grid-container intorno ai contenuti e un’area scorrevole dedicata alla tabella.

```
@use "uswds-core" as *;
.opportunity-meta {
  padding: units(2);
  margin-bottom: units(3);
}
```

Riferimento del codice

Leggi la specifica di supporto

## USWDS: famiglie e ruoli tipografici del sistema di design

### Un ruolo può cambiare senza rinominare i componenti

Il token sans predefinito corrisponde a Source Sans Pro e serif a Merriweather. I ruoli body e UI corrispondono a sans; il ruolo heading corrisponde a serif. La funzione family("body") risolve questa catena. Quando documenti un progetto, distingui il ruolo semantico dalla famiglia di font finale.

L’anteprima locale usa esplicitamente Helvetica/Arial per il testo e Georgia per i titoli, così non è necessario scaricare font. Si tratta di una sostituzione a scopo di studio, non dell’identità tipografica standard di USWDS. Per una build di produzione, configura questi ruoli tramite le impostazioni uswds-core oppure copia i file dei font distribuiti.

```
@use "uswds-core" with (
  $theme-font-type-sans: "helvetica",
  $theme-font-type-serif: "georgia",
  $theme-font-role-body: "sans",
  $theme-font-role-heading: "serif"
);
```

Riferimento del codice

Leggi la specifica di supporto

## USWDS: alias dei colori del tema del sistema di design

### Mantieni gli alias associati ai rispettivi ruoli

L’alias primary predefinito corrisponde a blue-60v, #005ea2. primary-dark corrisponde a blue-warm-70v, #1a4480; ink corrisponde a gray-90, #1b1b1b. Sono valori del tema, non l’affermazione che ogni sito USWDS debba usare lo stesso colore del marchio.

Usa l’alias semantico per un’azione o lo stile di un titolo e un token di colore del sistema solo quando questa è la scelta progettuale effettiva. Sostituire un alias primary nelle impostazioni è più controllato che sostituire ogni stringa esadecimale corrispondente in CSS compilato.

Leggi la specifica di supporto

## USWDS: righe di confronto tra opportunità del sistema di design

### Mantieni la semantica della tabella

L’esempio usa una didascalia, intestazioni di colonna con scope="col" e il nome di un’opportunità con scope="row". È una tabella perché chi legge confronta gli stessi campi relativi all’argomento e alla fase tra diversi record. Queste relazioni restano accessibili anche quando l’area scorre.

Il contenitore scorrevole ha tabindex="0", così chi usa la tastiera può raggiungerlo. In questo modo i dati più larghi restano confinati nell’area dedicata senza allargare l’intero documento. L’anteprima contiene normali celle di testo; se mancassero dati sul programma, servirebbe uno stato esplicito del contenuto, non un numero inventato.

Leggi la specifica di supporto

### L’ordinamento è un miglioramento distinto

USWDS supporta le intestazioni ordinabili tramite data-sortable. Una tabella ordinabile richiede anche un usa-table__announcement-region con aria-live="polite". Per i valori numerici può essere necessario data-sort-value, così un importo formattato viene ordinato come valore e non alfabeticamente. Il confronto attuale non abilita l’ordinamento perché il filtro per argomento su tre righe è la dimostrazione prevista.

Leggi la specifica di supporto

## USWDS: requisiti presentati come disclosure del sistema di design

### Collega gli ID del pulsante e del pannello

Ogni usa-accordion__button ha un aria-controls che punta al usa-accordion__content corrispondente. Il comportamento nativo di JavaScript aggiorna aria-expanded e la visibilità. Il modificatore bordered cambia il contenitore; data-allow-multiple consente di lasciare aperte più sezioni.

Un’intestazione contiene il pulsante, così la struttura del contenuto resta comprensibile. I requisiti necessari per stabilire se un programma è pertinente devono rimanere visibili sopra la disclosure. In questo caso, i pannelli contengono note supplementari per la preparazione e una spiegazione del set di dati fittizio.

- L’intestazione descrive l’argomento del pannello.

- Il pulsante indica lo stato di espansione e l’ID di destinazione.

- Il pannello mantiene lo stesso ID quando cambia la sua visibilità.

Leggi la specifica di supporto

## USWDS: installa l’intero albero delle risorse del sistema di design

### Mantieni i percorsi usati da CSS compilato

Installa @uswds/uswds@3.14.0 e copia la directory dist senza riunire css, js, img e fonts in un’unica cartella. Il foglio di stile usa percorsi relativi per icone e font. In caso contrario, una pagina potrebbe sembrare in parte corretta, pur senza i simboli delle disclosure o i caratteri tipografici.

Carica uswds-init.min.js nell’head, poi il foglio di stile e infine uswds.min.js dopo il markup del body. La libreria inclusa aggiunge le funzionalità all’accordion. Il campo di ricerca e il filtro per argomento qui sotto usano logica applicativa personalizzata; non chiamano un servizio di ricerca remoto.

Leggi la specifica di supporto

## USWDS: filtri e gestione dei risultati vuoti nel sistema di design

### La ricerca deve mostrare il risultato

Gli stili nativi per label, input, select e button forniscono i controlli; l’applicazione confronta la query e l’argomento selezionato con i tre record fittizi. Il conteggio dei risultati è un’area live con annuncio discreto. Se non ci sono corrispondenze, vengono mostrati una spiegazione e un’azione di ripristino, mantenendo la query inserita.

La dimostrazione distingue intenzionalmente la scoperta di un’opportunità dalla presentazione di una domanda. Aprire i contenuti di preparazione non crea una bozza né segna un requisito come completato. Una vera domanda di finanziamento richiederebbe una propria policy di programma, l’autenticazione e uno stato persistente della transazione.

1. Filtra per Ambiente e controlla l’opportunità rimasta.

2. Cerca una frase senza corrispondenze e seleziona Cancella filtri.

3. Apri entrambi i pannelli di preparazione e verifica che abbiano stati di espansione indipendenti.

Leggi la specifica di supporto

## USWDS: esempi di componenti del sistema di design

### Accordion per la preparazione supplementare

Disclosure nativa di USWDS con una relazione esplicita tra pulsante e pannello.

```
<div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
</div>
```

Riferimento del codice

### Tabella di confronto delle opportunità

La didascalia e le intestazioni di riga e colonna mantengono le relazioni del confronto.

```
<div class="usa-table-container--scrollable" tabindex="0">
  <table class="usa-table usa-table--borderless">
    <caption>Illustrative research opportunities</caption>
    <thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead>
    <tbody><tr><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr></tbody>
  </table>
</div>
```

Riferimento del codice

### Esempio autonomo completo

Il documento completo include layout, controlli e inizializzazione. Estrai l’archivio di esempio collegato per ottenere gli esatti asset vendor relativi, quindi avvialo tramite HTTP.

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Research opportunities — OpenDesign study</title><script src="vendor/uswds-3.14.0/uswds-init.min.js"></script><link rel="stylesheet" href="vendor/uswds-3.14.0/css/uswds.min.css"><style>body,body *,body *:before,body *:after{font-family:Helvetica,Arial,sans-serif!important}h1,h2{font-family:Georgia,serif!important}body{color:#1b1b1b;margin:0}[hidden]{display:none!important}.study-head{background:#d9e8f6;padding:16px 0;border-bottom:4px solid #005ea2}.study-head p{margin:0}.study-form{display:flex;gap:24px;align-items:end;flex-wrap:wrap}.study-form>div{flex:1;min-width:200px}.study-form .usa-input,.study-form .usa-select{max-width:none}.usa-table{width:100%}.study-main{padding-top:32px;padding-bottom:48px}.usa-table th{min-width:120px}#count{margin-top:24px}.study-note{border-top:1px solid #a9aeb1;margin-top:32px;padding-top:16px;line-height:1.5}</style></head><body><header class="study-head"><div class="grid-container"><p><strong>OpenDesign · USWDS component study</strong><br>Fictional research records. No application is submitted.</p></div></header><main class="grid-container study-main"><h1>Research opportunities</h1><p class="usa-intro">Compare topics and read the preparation notes.</p><form class="study-form" id="filters"><div><label class="usa-label" for="query">Search opportunity names</label><input class="usa-input" id="query" type="search"></div><div><label class="usa-label" for="topic">Topic</label><select class="usa-select" id="topic"><option value="">All topics</option><option>Environment</option><option>Transport</option><option>Education</option></select></div><button type="submit" class="usa-button">Apply filters</button><button type="button" class="usa-button usa-button--outline" id="clear">Clear filters</button></form><p id="count" aria-live="polite">3 opportunities</p><div class="usa-table-container--scrollable" tabindex="0"><table class="usa-table usa-table--borderless"><caption>Illustrative research opportunities</caption><thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead><tbody><tr data-topic="Environment"><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr><tr data-topic="Transport"><th scope="row">Accessible transport research</th><td>Transport</td><td>Example review</td></tr><tr data-topic="Education"><th scope="row">Local skills survey</th><td>Education</td><td>Example draft</td></tr></tbody></table></div><p id="empty" hidden>No matching opportunities. Broaden the topic or clear the filters.</p><h2>Preparation notes</h2><div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
<h3 class="usa-accordion__heading"><button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="scope">What the example data means</button></h3><div id="scope" class="usa-accordion__content usa-prose" hidden><p>Draft and review are demonstration stages. They do not indicate an actual funding programme or eligibility decision.</p></div>
</div><p class="study-note">USWDS 3.14.0 native accordion and styles, with local Helvetica/Georgia font overrides. Filters are original application code. <a href="vendor/uswds-3.14.0/LICENSE.md">Distribution licence</a>.</p></main><script src="vendor/uswds-3.14.0/uswds.min.js"></script><script>const rows=[...document.querySelectorAll('tbody tr')],q=document.getElementById('query'),t=document.getElementById('topic');function filter(){let n=0;for(const row of rows){const show=(!t.value||row.dataset.topic===t.value)&&row.firstElementChild.textContent.toLowerCase().includes(q.value.trim().toLowerCase());row.hidden=!show;if(show)n++}document.getElementById('count').textContent=n+' '+(n===1?'opportunity':'opportunities');document.getElementById('empty').hidden=n!==0;}document.getElementById('filters').addEventListener('submit',e=>{e.preventDefault();filter()});document.getElementById('clear').addEventListener('click',()=>{q.value='';t.value='';filter();q.focus()});</script></body></html>
```

Riferimento del codice

- Scarica l’esempio completo dalla sezione Fonti. Il README indica il comando esatto per avviarlo in locale.

- Mantieni i percorsi vendor relativi a questo documento; l’archivio include tutti gli asset usati da questa anteprima.

## USWDS: configurazione dell’agente per il sistema di design

### Punto di partenza per l’implementazione

Mantieni la struttura della directory dist, così CSS può trovare font e icone. Questo è il percorso con distribuzione precompilata; per personalizzare il tema è necessaria una build Sass. Il file ZIP dell’esempio completo e funzionante, disponibile in Sources, include anche le dipendenze esatte dell’anteprima e il documento completo. Estrailo, esegui python3 -m http.server 8080 in quella directory, quindi apri http://localhost:8080/uswds.html. Non aprire con file:// gli esempi basati su moduli.

```
npm install @uswds/uswds@3.14.0
mkdir -p public/assets/uswds
cp -R node_modules/@uswds/uswds/dist public/assets/uswds/

<!-- HTML head -->
<script src="/assets/uswds/dist/js/uswds-init.min.js"></script>
<link rel="stylesheet" href="/assets/uswds/dist/css/uswds.min.css">
<!-- After the component markup, before closing body -->
<script src="/assets/uswds/dist/js/uswds.min.js"></script>
```

### Un prompt per il tuo progetto

```
Crea un confronto fittizio tra opportunità di ricerca usando USWDS 3.14.0. Carica l’intero albero delle risorse dist, lo script di inizializzazione, il foglio di stile dei componenti e JavaScript. Presenta record confrontabili in una tabella semantica con didascalia e intestazioni di colonna; fornisci una ricerca etichettata e un filtro per categoria, un conteggio dei risultati, uno stato utile in assenza di corrispondenze e un’azione di ripristino. Usa gli accordion nativi per i requisiti di supporto, mantenendo visibili le informazioni essenziali per il confronto. Rispetta le unità di spaziatura documentate e le mappature dei ruoli del tema; indica esplicitamente la sostituzione dei font di sistema. Non trasformare questa directory in un flusso di invio di domande né lasciare intendere che esistano requisiti di ammissibilità o impegni di finanziamento reali.
```

## USWDS: fonti e ambito del sistema di design

Studio indipendente dei componenti di USWDS 3.14.0. I record delle opportunità sono fittizi; non si dichiara alcuna affiliazione federale e non è presente alcun endpoint per le domande. Helvetica/Arial e Georgia sono sostituzioni locali dei font, non i file di font predefiniti di USWDS.

- Unità di spaziatura Unità numeriche e larghezze con nome.

- Ruoli delle famiglie di font Risoluzione dei token tipografici e dei ruoli.

- Colori del tema Alias e impostazioni predefiniti.

- Tabella Confronto semantico e scorrimento.

- Accordion Stati e markup dei pannelli.

- Configurazione per sviluppatori Distribuzione e percorsi delle risorse.

- Scarica l’esempio completo e funzionante ZIP con HTML completo, dipendenze locali CSS/JavaScript, licenze fornite e istruzioni esatte per l’avvio. Non è necessario alcun passaggio di compilazione.

## USWDS: risorse correlate al sistema di design

### VA sistema di design

Crea percorsi di servizio chiari con i token semantici e il Process List nativo di VA: spiegazioni visibili delle fasi, etichette di stato significative e dettagli supplementari che mantengono leggibile il percorso principale.

### W3C sistema di design

Crea interfacce di lettura flessibili con tipografia fluida, ruoli semantici dei colori e contenuti comprimibili nativi, sempre leggibili anche senza JavaScript.

### Codex

Usa la struttura effettiva di SearchInput di Codex, la gerarchia delle azioni e i token pensati per la lettura. Cerca in un indice locale di articoli, esamina un risultato e torna alla stessa posizione di lettura.


- [Riferimento per l’implementazione](https://designsystem.digital.gov/components/accordion/)
- [Fonte](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Fonte](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Fonte](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [Fonte](https://designsystem.digital.gov/components/accordion/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/documentation/developers/)
- [Riferimento del codice](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Riferimento del codice](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/components/table/)
- [Leggi la specifica di supporto](https://designsystem.digital.gov/components/accordion/)
- [Riferimento del codice](https://designsystem.digital.gov/components/accordion/)
- [Riferimento del codice](https://designsystem.digital.gov/components/table/)
- [Unità di spaziatura Unità numeriche e larghezze con nome.](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Ruoli delle famiglie di font Risoluzione dei token tipografici e dei ruoli.](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Colori del tema Alias e impostazioni predefiniti.](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [Tabella Confronto semantico e scorrimento.](https://designsystem.digital.gov/components/table/)
- [Accordion Stati e markup dei pannelli.](https://designsystem.digital.gov/components/accordion/)
- [Configurazione per sviluppatori Distribuzione e percorsi delle risorse.](https://designsystem.digital.gov/documentation/developers/)