# Sistema de Design USWDS

## Prévia da interface do sistema de design USWDS

Pesquise e filtre registros fictícios, recupere-se de buscas sem resultados e expanda os painéis nativos de requisitos.

## Referência de design do sistema de design USWDS

Distribuição nativa de componentes do sistema de design USWDS 3.14.0. Tokens padrão da documentação oficial; substituições tipográficas da prévia são escolhas locais explícitas.

### Unidades de espaçamento

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| 0.5 / 05 | 4px | Escala de espaçamento em meios incrementos e utilitários |
| 1 | 8px | Unidade base de espaçamento |
| 1.5 / 105 | 12px | Espaçamento intermediário |
| 2 | 16px | Preenchimento interno compacto |
| 3 | 24px | Espaçamento entre conteúdos relacionados |
| 4 | 32px | Espaçamento entre seções |
| 5 | 40px | Separação maior |
| 6 | 48px | Espaçamento amplo |
| tablet | 640px | Token de largura nomeado |
| desktop | 1024px | Token de largura nomeado |
### Mapeamento tipográfico padrão

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| sans | source-sans-pro | Token de família tipográfica por função |
| serif | merriweather | Token de família tipográfica por função |
| body / ui | sans | Mapeamento por função |
| heading | serif | Mapeamento por função |
| code | mono → roboto-mono | Mapeamento da função de código |
### Cores padrão do tema

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| primary | blue-60v / #005ea2 | Alias principal |
| primary-lighter | blue-10 / #d9e8f6 | Tonalidade de apoio da cor principal |
| primary-dark | blue-warm-70v / #1a4480 | Alias da cor principal escura |
| ink | gray-90 / #1b1b1b | Alias da cor do texto principal |
### Contratos dos componentes

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| aria-controls | Panel ID | Conecta cada botão de acordeão ao conteúdo correspondente. |
| aria-expanded | true / false | O JS nativo mantém o estado de abertura. |
| data-allow-multiple | Accordion root attribute | Permite abrir painéis de forma independente. |
| usa-accordion--bordered | Root modifier | Fornece a variante com borda. |
## Guia completo do sistema de design USWDS

Um guia prático para escolher, aplicar e avaliar este sistema em uma interface real.

Orientações completas, um ponto de partida para a implementação e links para o código-fonte.

## Sistema de Design USWDS — Um Foundation configurável

### Os tokens padrão são um ponto de partida para a configuração

> USWDS separa tokens do sistema, configurações de tema do projeto, classes utilitárias e componentes. A referência abaixo registra as escolhas de tema padrão da documentação atual. Um programa federal pode configurar outras funções tipográficas ou aliases de cores sem substituir todos os componentes.

A prévia é uma comparação independente de oportunidades de pesquisa que usa CSS 3.14.0 e JavaScript de acordeão. Ela omite o banner governamental e as marcas de identidade. Os nomes dos programas e suas etapas são fictícios, e a filtragem acontece inteiramente no navegador.

Consulte a especificação de apoio

## Sistema de Design USWDS — Tokens de espaçamento e tema

### Considere a unidade, não o numeral

Uma unidade de espaçamento USWDS equivale a 8px: units(2) significa 16px, enquanto units(3) significa 24px. Os tokens de meio incremento permitem intervalos menores, e a notação utilitária usa 05 para meio incremento. Um utilitário margin-2 não significa uma margem de dois pixels.

A escala também inclui larguras nomeadas, como tablet e desktop. Esses nomes são tokens reutilizáveis, não uma exigência para redesenhar cada página em cada largura. A comparação usa grid-container em torno do conteúdo e uma área focada, com rolagem, para a tabela.

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

Referência de código

Consulte a especificação de apoio

## Sistema de Design USWDS — Tipos e funções tipográficas

### Uma função pode mudar sem que os componentes sejam renomeados

Por padrão, o token sans corresponde a Source Sans Pro e serif a Merriweather. As funções body e UI correspondem a sans; heading corresponde a serif. A função family("body") resolve essa cadeia. Ao documentar um projeto, diferencie a função semântica da família tipográfica final.

A prévia local usa explicitamente Helvetica/Arial para o corpo do texto e Georgia para os títulos, sem exigir o download de fontes. Essa substituição para estudo não corresponde à identidade tipográfica padrão de USWDS. Em uma compilação de produção, configure essas funções pelas definições de uswds-core ou copie os arquivos de fontes distribuídos.

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

Referência de código

Consulte a especificação de apoio

## Sistema de Design USWDS — Aliases de cores do tema

### Mantenha os aliases vinculados às suas funções

Por padrão, o alias principal corresponde a blue-60v, #005ea2. Primary-dark corresponde a blue-warm-70v, #1a4480; ink corresponde a gray-90, #1b1b1b. Esses são valores de tema, não uma afirmação de que todos os sites USWDS devam usar a mesma cor de marca.

Use o alias semântico para uma ação ou para o estilo de um título, e um token de cor do sistema somente quando essa for a decisão de design. Substituir um alias principal nas configurações oferece mais controle do que trocar todas as strings hexadecimais correspondentes no código compilado de CSS.

Consulte a especificação de apoio

## Sistema de Design USWDS — Linhas de comparação de oportunidades

### Mantenha a semântica da tabela

O exemplo usa uma legenda, cabeçalhos de coluna com scope="col" e o nome de uma oportunidade com scope="row". É uma tabela porque os leitores comparam os mesmos campos de tema e etapa entre registros. Essas relações continuam disponíveis quando a região é rolada.

O contêiner rolável tem tabindex="0" para que usuários de teclado possam acessá-lo. Ele mantém os dados largos nessa região, em vez de ampliar todo o documento. A visualização contém células de texto comuns; dados ausentes do programa exigiriam um estado de conteúdo explícito, e não um número inventado.

Consulte a especificação de apoio

### A classificação é um aprimoramento separado

USWDS oferece cabeçalhos classificáveis por meio de data-sortable. Uma tabela classificável também precisa de um usa-table__announcement-region com aria-live="polite". Exibições numéricas talvez precisem de data-sort-value para que um valor formatado seja classificado como número, e não em ordem alfabética. A comparação atual não ativa a classificação porque o filtro de tema com três linhas é a demonstração pretendida.

Consulte a especificação de apoio

## Requisitos de sistema de design USWDS como painéis expansíveis

### Associe os IDs do botão e do painel

Cada usa-accordion__button tem um aria-controls que aponta para o usa-accordion__content associado. O JavaScript nativo atualiza aria-expanded e a visibilidade. O modificador bordered altera o contêiner; data-allow-multiple permite que várias seções permaneçam abertas.

Um título contém o botão para que a estrutura do conteúdo continue compreensível. Requisitos necessários para decidir se um programa é relevante devem permanecer visíveis acima do painel expansível. Aqui, os painéis contêm notas complementares de preparação e uma explicação do conjunto de dados fictício.

- O título descreve o tema do painel.

- O botão contém o estado de expansão e o ID de destino.

- O painel mantém o mesmo ID quando sua visibilidade muda.

Consulte a especificação de apoio

## Instale toda a árvore de recursos do sistema de design USWDS

### Preserve os caminhos usados pelo CSS compilado

Instale @uswds/uswds@3.14.0 e copie o diretório dist sem reunir css, js, img e fonts em uma única pasta. A folha de estilos usa caminhos relativos para ícones e fontes. Caso contrário, uma página pode parecer parcialmente correta, mas não exibir símbolos de painéis expansíveis ou fontes.

Carregue uswds-init.min.js no head, a folha de estilos em seguida e uswds.min.js após a marcação do body. A biblioteca incluída aprimora o acordeão. O campo de pesquisa e o filtro de tema abaixo usam lógica personalizada da aplicação; não consultam um serviço de pesquisa remoto.

Consulte a especificação de apoio

## Filtros e recuperação no sistema de design USWDS

### Uma consulta precisa mostrar o resultado

Os estilos nativos de label, input, select e button fornecem os controles; a aplicação compara a consulta e o tema selecionado com os três registros fictícios. A contagem de resultados é uma região dinâmica educada. Quando não há correspondências, são exibidas uma explicação e uma ação para redefinir os filtros, sem apagar a consulta digitada.

A demonstração distingue intencionalmente descobrir uma oportunidade de se candidatar. Abrir o conteúdo de preparação não cria um rascunho nem marca um requisito como concluído. Uma candidatura real a financiamento precisaria de políticas próprias do programa, autenticação e estado persistente da transação.

1. Filtre por Meio ambiente e confira a oportunidade restante.

2. Pesquise uma expressão sem correspondências e use Limpar filtros.

3. Abra os dois painéis de preparação e confira se cada um mantém seu próprio estado de expansão.

Consulte a especificação de apoio

## Exemplos de componentes do sistema de design USWDS

### Acordeão de preparação complementar

Um painel nativo de USWDS, com uma relação explícita entre o botão e o painel.

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

Referência de código

### Tabela de comparação de oportunidades

A legenda e os cabeçalhos de linha e coluna preservam as relações da comparação.

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

Referência de código

### Exemplo completo independente

O documento completo inclui layout, controles e inicialização. Extraia o arquivo de exemplo indicado para obter os recursos do fornecedor no caminho relativo exato e, em seguida, disponibilize-o por 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>
```

Referência de código

- Baixe o exemplo completo em Fontes. O README informa o comando exato para iniciá-lo localmente.

- Mantenha os caminhos do fornecedor relativos a este documento; o arquivo inclui todos os recursos usados nesta prévia.

## Configuração de agente do sistema de design USWDS

### Ponto de partida para implementação

Preserve a estrutura do diretório dist para que o CSS encontre fontes e ícones. Esta é a opção de distribuição pré-compilada; a personalização do tema requer uma compilação de Sass. O ZIP do exemplo completo de trabalho em Sources também inclui as dependências exatas da visualização e o documento completo. Extraia-o, execute python3 -m http.server 8080 nesse diretório e abra http://localhost:8080/uswds.html. Não abra exemplos baseados em módulos usando file://.

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

### Um prompt para seu projeto

```
Crie uma comparação fictícia de oportunidades de pesquisa usando USWDS 3.14.0. Carregue a árvore completa de recursos dist, o script de inicialização, a folha de estilos dos componentes e JavaScript. Apresente registros comparáveis em uma tabela semântica com legenda e cabeçalhos de coluna; ofereça pesquisa rotulada e filtragem por categoria, contagem de resultados, um estado útil para ausência de correspondências e uma opção para redefinir os filtros. Use acordeões nativos para os requisitos complementares e mantenha visíveis as informações essenciais para a comparação. Preserve as unidades de espaçamento documentadas e os mapeamentos de funções do tema; identifique a substituição das fontes do sistema. Não transforme este diretório em um fluxo de envio de candidaturas nem sugira compromissos reais de elegibilidade ou concessão de recursos.
```

## Fontes e escopo do sistema de design USWDS

Estudo independente de componentes do USWDS 3.14.0. Registros fictícios de oportunidades, sem alegação de identidade federal ou endpoint de candidatura. Helvetica/Arial e Georgia são substituições de fontes locais, não os recursos de fonte padrão do USWDS.

- Unidades de espaçamento Unidades numéricas e larguras nomeadas.

- Funções das famílias tipográficas Resolução de tokens de tipografia e funções.

- Cores do tema Aliases e configurações padrão.

- Tabela Comparação semântica e rolagem.

- Acordeão Estados e marcação dos painéis.

- Configuração para desenvolvedores Distribuição e caminhos dos recursos.

- Baixar o exemplo completo funcional ZIP com HTML completo, dependências locais CSS/JavaScript, licenças incluídas e instruções exatas de inicialização. Não é necessário executar uma etapa de compilação.

## Recursos relacionados ao sistema de design USWDS

### VA sistema de design

Crie jornadas de serviço claras com os tokens semânticos e a Process List nativa da VA: explicações visíveis das etapas, rótulos de status significativos e detalhes complementares que mantêm o fluxo principal legível.

### W3C sistema de design

Crie interfaces de leitura resilientes com tipografia fluida, papéis semânticos de cores e conteúdo expansível nativo que continua legível sem JavaScript.

### Codex

Use a anatomia real do SearchInput, a hierarquia de ações e os tokens voltados à leitura de Codex. Pesquise um índice local de artigos, consulte um resultado e retorne à mesma posição de leitura.


- [Referência de implementação](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/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/documentation/developers/)
- [Referência de código](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Referência de código](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/components/table/)
- [Consulte a especificação de apoio](https://designsystem.digital.gov/components/accordion/)
- [Referência de código](https://designsystem.digital.gov/components/accordion/)
- [Referência de código](https://designsystem.digital.gov/components/table/)
- [Unidades de espaçamento Unidades numéricas e larguras nomeadas.](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [Funções das famílias tipográficas Resolução de tokens de tipografia e funções.](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [Cores do tema Aliases e configurações padrão.](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [Tabela Comparação semântica e rolagem.](https://designsystem.digital.gov/components/table/)
- [Acordeão Estados e marcação dos painéis.](https://designsystem.digital.gov/components/accordion/)
- [Configuração para desenvolvedores Distribuição e caminhos dos recursos.](https://designsystem.digital.gov/documentation/developers/)