semmet-angular

Interfaces Angular acessíveis como código do seu projeto.

Agentes de IA: antes de gerar ou editar código com o Semmet, leia o guia de uso com IA. Ele explica como mapear padrões do Figma para comandos, o que pode ser personalizado com segurança e quais contratos de acessibilidade devem ser preservados.

Semmet Angular ajuda você a criar componentes acessíveis, fluxos financeiros e estruturas para organizar, testar e publicar aplicações Angular.

Escolha o recurso de que precisa, gere os arquivos e personalize o resultado de acordo com o design, o conteúdo e as regras de negócio do seu produto. Você também pode usar o Semmet em fluxos com Figma e agentes de IA para transformar padrões visuais em uma base Angular acessível.

O que você pode criar

O Semmet oferece pontos de partida acessíveis para interfaces e tarefas comuns de um projeto Angular. O resultado pode receber o layout, as cores, a tipografia e os comportamentos específicos da sua aplicação.

Use componentes isolados para criar interfaces de aplicação precisas e blocos iniciais opcionais para estruturas editáveis de seções comuns.

Na prática, você pode:

• gerar interfaces Angular acessíveis com mais rapidez;
• testar o comportamento gerado com testes unitários e testes de ponta a ponta opcionais do Playwright;
• verificar a aplicação com scripts npm comuns;
• empacotar e implantar com arquivos padrão do Angular, integração contínua, Docker e hospedagem.

Início rápido

Instale a coleção na raiz de um workspace Angular:

ng add semmet-angular

Em seguida, gere o menor componente que representa o padrão da interface:

ng generate semmet-angular:button save-button

O comando cria arquivos Angular standalone que passam a pertencer à aplicação:

save-button.ts
save-button.html
save-button.css
save-button.spec.ts

Fluxo de trabalho do Figma assistido por IA

Use o Semmet como base de acessibilidade e entrega em um processo de implementação orientado pelo Figma.

Ciclo recomendado:

1. Copie uma seleção do Figma ou descreva a tela desejada.
2. Peça a um agente de IA para identificar campos de formulário, navegação, caixas de diálogo, tabelas, listas, abas, cartões, botões, estados de feedback e outros padrões de interface.
3. Mapeie cada padrão para o menor schematic útil do Semmet.
4. Gere os componentes ou as diretivas sem estilo visual obrigatório com ng generate.
5. Monte a página na aplicação Angular consumidora.
6. Substitua o conteúdo provisório e edite o HTML/CSS localmente para corresponder ao design real do Figma.
7. Preserve rótulos, relações ARIA, gerenciamento de foco, comportamento de teclado e controles nativos durante os ajustes visuais.
8. Execute a compilação e os testes; depois, adicione estruturas de testes de ponta a ponta, integração contínua, Docker ou implantação quando o projeto estiver pronto.

O agente deve tratar a saída do Semmet como código da aplicação: editável, legível e seguro para reformulação visual, mantendo intacto o contrato de acessibilidade. Para obter um prompt pronto para copiar e colar e uma lista de verificação de mapeamento, consulte AI_USAGE_GUIDE.md.

Exemplos de geração

ng add semmet-angular
ng generate semmet-angular:button cta-button
ng generate semmet-angular:list-group feature-list
ng generate semmet-angular:currency-input transfer-amount
ng generate semmet-angular:transaction-list account-activity
ng generate semmet-angular:account-selector source-account
ng generate semmet-angular:beneficiary-form new-beneficiary
ng generate semmet-angular:pix-payment pix-transfer
ng generate semmet-angular:authorization-queue approval-queue
ng generate semmet-angular:confirmation-summary transfer-review
ng generate semmet-angular:transaction-detail transaction-receipt
ng generate semmet-angular:block section-card
ng generate semmet-angular:feature payments
ng generate semmet-angular:api-resource payments --path src/app/payments
ng generate semmet-angular:adapter-resource payments --entity payment --sources stripe --sources paypal --path src/app/features
ng generate semmet-angular:facade-resource checkout --steps inventory --steps discount --steps notification --path src/app/features
ng generate semmet-angular:strategy-resource shipping --strategies economy --strategies express --strategies free --path src/app/features
ng generate semmet-angular:e2e
ng generate semmet-angular:ci
ng generate semmet-angular:docker
ng generate semmet-angular:deploy

Os testes de ponta a ponta do Playwright são opcionais:

ng generate semmet-angular:button cta-button --e2e

Use --e2e somente quando a aplicação consumidora tiver o Playwright configurado. Caso contrário, execute primeiro ng generate semmet-angular:e2e. O comando ng add semmet-angular mantém a instalação leve e não configura o Playwright por padrão.

Componentes versus blocos iniciais

Componentes

Componentes e diretivas são o núcleo do Semmet Angular. Eles são a melhor escolha quando a aplicação consumidora precisa de controle preciso sobre marcação, layout e design visual.

Eles fornecem o contrato de acessibilidade e deixam o layout e o design visual a cargo da aplicação:

• elementos raiz semânticos nos casos em que o elemento nativo é importante;
• diretivas sem estilo visual obrigatório nos casos em que a acessibilidade resulta das relações entre os elementos;
• atributos ARIA e nomes/descrições acessíveis;
• comportamento de teclado e foco;
• estado baseado em signals;
• projeção de conteúdo rico por meio de ng-template, quando necessário;
• entradas visuais abertas, como variant e size, do tipo string, em vez de uniões visuais fechadas.

Exemplos:

ng generate semmet-angular:button save-button
ng generate semmet-angular:card testimonial-card
ng generate semmet-angular:input-group search-box
ng generate semmet-angular:list-group feature-list
ng generate semmet-angular:tabs settings-tabs

Blocos iniciais

Os blocos são estruturas opcionais de seções. Eles são úteis para criar rapidamente os primeiros rascunhos, seções comuns de marketing/produto e a estrutura inicial da aplicação.

Eles não são uma API pública de interface e não se destinam a preservar um layout do Semmet. Um bloco gerado é código local da aplicação. Se a interface desejada precisar de outra estrutura, substitua a marcação do bloco ou use componentes isolados.

ng generate semmet-angular:block hero
ng generate semmet-angular:block section-card
ng generate semmet-angular:block section-pricing
ng generate semmet-angular:block section-table
ng generate semmet-angular:block section-form
ng generate semmet-angular:block section-tabs
ng generate semmet-angular:block section-list-group
ng generate semmet-angular:block header-navbar
ng generate semmet-angular:block footer-navigation

O HTML do bloco gerado inclui um comentário em linha para lembrar aos desenvolvedores que a estrutura pode ser editada e substituída.

CSS funcional mínimo

O CSS gerado é intencionalmente enxuto.

Mantenha o CSS somente quando ele contribuir para a estrutura, o comportamento ou a acessibilidade:

• estado aberto/fechado;
• posicionamento de sobreposições;
• foco visível;
• conteúdo oculto;
• herança de controles nativos;
• comportamento básico de caixa necessário ao componente.

Não trate o CSS gerado como um tema. Tipografia, cores, raios de borda, sombras, bordas decorativas, estados visuais de interação, ritmo de espaçamento e layout final pertencem ao projeto consumidor.

Conteúdo projetado

O conteúdo rico usa padrões de projeção do Angular em vez de APIs limitadas a strings.

Exemplo após gerar search-box:

<app-search-box label="Pesquisar" type="search" [(value)]="query">
  <ng-template searchBoxPrefix>
    <app-search-icon aria-hidden="true" />
  </ng-template>

  <ng-template searchBoxSuffix> {{ query().length }} </ng-template>
</app-search-box>

Exemplo após gerar testimonial-card:

<app-testimonial-card>
  <h3 testimonialCardHeading>Depoimento de cliente</h3>
  <p>
    O Semmet fornece a estrutura de acessibilidade; esta aplicação é responsável
    pelo conteúdo e pelo layout.
  </p>
</app-testimonial-card>

Exemplo após gerar feature-list:

<ul featureList label="Recursos dos planos" [(activeId)]="activeFeature">
  @for (item of features; track item.id) {
  <li
    featureListItem
    [value]="item.id"
    #featureItem="featureListItem"
    [class.active]="featureItem.active()"
  >
    <span>{{ item.label }}</span>
    <strong>{{ item.value }}</strong>
  </li>
  }
</ul>

Schematics de entrega

ng generate semmet-angular:e2e
ng generate semmet-angular:ci
ng generate semmet-angular:docker
ng generate semmet-angular:deploy

Os schematics de entrega são explícitos e opcionais:

• e2e configura o Playwright e o axe-core (dependências, scripts npm e playwright.config.ts), cria uma base determinística de harness em src/app/semmet-e2e, falha quando há testes ignorados e incorpora npm run e2e a um script verify existente.
• Os componentes gerados posteriormente com --e2e recebem um host pertencente ao projeto, uma rota filha determinística e cobertura automática do axe. Conecte SEMMET_E2E_ROUTES sob a rota pai /__semmet-e2e na configuração de rotas de teste/local da aplicação consumidora; mantenha essa rota pai fora da produção.
• Use ng generate semmet-angular:e2e --register-route para registrar essa rota pai em um app.routes.ts reconhecido. Isso continua opcional, e o shell da aplicação deve renderizar um RouterOutlet.
• ci gera um fluxo de trabalho do GitHub Actions a partir dos scripts existentes no pacote.
• docker gera arquivos de empacotamento Docker/Nginx para uma SPA Angular.
• deploy gera uma configuração mínima de implantação para as plataformas compatíveis.

Limite opcional de funcionalidade

Os comandos existentes de componentes e blocos permanecem independentes. Use feature somente quando o projeto consumidor se beneficiar de uma pequena estrutura inicial fornecida pelo Semmet:

ng generate semmet-angular:feature payments

Por padrão, são gerados somente um shell de página standalone e rotas preparadas para carregamento lazy:

src/app/payments/
├── payments-page/
│   ├── payments-page.ts
│   ├── payments-page.html
│   ├── payments-page.css
│   └── payments-page.spec.ts
└── payments.routes.ts

Não são gerados interface de pagamento, acesso à API, estado ou modelos, e a rota pai não é registrada, a menos que isso seja solicitado explicitamente. Gere as partes acessíveis de forma independente e coloque-as onde a arquitetura da aplicação exigir:

ng generate semmet-angular:currency-input amount --path src/app/payments
ng generate semmet-angular:confirmation-summary review --path src/app/payments
ng generate semmet-angular:feature reports --register-route

Use --page=false ou --routing=false para obter um limite menor. Presets expandidos de funcionalidades e a composição de API/estado estão reservados para fases futuras do roadmap e, no momento, falham com uma mensagem clara em vez de gerar silenciosamente uma arquitetura incompleta.

Recursos HTTP tipados

api-resource é independente de feature. Ele gera código HTTP Angular editável, com contratos separados de transporte/aplicação, mapeamento puro e testes de requisição:

ng generate semmet-angular:api-resource payments \
  --entity payment \
  --operations list \
  --operations get \
  --operations create \
  --path src/app/payments

As opções de array do Angular CLI devem ser repetidas uma vez para cada valor; um valor separado por vírgulas, como --operations list,get,create, é tratado como uma única operação inválida.

Arquivos gerados:

payments-api.ts
payments-api.spec.ts
payment.dto.ts
payment.model.ts
payment.mapper.ts

O serviço usa inject(HttpClient), e o teste usa provideHttpClient() seguido de provideHttpClientTesting(). Ele não adiciona autenticação, não faz inscrições internamente, não oculta erros nem tenta adivinhar os campos do backend. Substitua os contratos iniciais, que contêm apenas id, pelo contrato real da API ou use um cliente gerado por OpenAPI quando houver um disponível.

Adapter por feature

adapter-resource gera uma estrutura local de Adapter dentro de uma feature. Use quando uma tela ou service precisar consumir dados de fontes externas com formatos diferentes e expor um modelo único para a aplicação:

ng generate semmet-angular:adapter-resource payments \
  --entity payment \
  --sources stripe \
  --sources paypal \
  --path src/app/features

Arquivos gerados:

payments/
  adapters/
    payment.adapter.ts
    stripe-payment.adapter.ts
    paypal-payment.adapter.ts
  models/
    payment.model.ts
    stripe-payment.dto.ts
    paypal-payment.dto.ts
  services/
    payments.service.ts

Uso em um componente Angular:

import { Component, inject } from '@angular/core';
import { PaymentsService } from '../../services/payments.service';

@Component({
  selector: 'app-payment-history',
  templateUrl: './payment-history.component.html',
})
export class PaymentHistoryComponent {
  private readonly paymentHistory = inject(PaymentsService);
  protected readonly payments = this.paymentHistory.getItems();
}

As opções de array do Angular CLI devem ser repetidas uma vez para cada fonte. O service é opcional com --service=false.

Facade por feature

facade-resource gera uma estrutura local de Facade para fluxos que coordenam vários services internos:

ng generate semmet-angular:facade-resource checkout \
  --steps inventory \
  --steps discount \
  --steps notification \
  --path src/app/features

Uso em um componente Angular:

import { Component, inject } from '@angular/core';
import { CheckoutFacade } from '../../facades/checkout.facade';

@Component({
  selector: 'app-checkout-summary',
  templateUrl: './checkout-summary.component.html',
})
export class CheckoutSummaryComponent {
  private readonly checkout = inject(CheckoutFacade);
  protected readonly summary = this.checkout.execute();
}

Strategy por feature

strategy-resource gera contrato, modos, strategies concretas e um service seletor para trocar algoritmos por modo:

ng generate semmet-angular:strategy-resource shipping \
  --strategies economy \
  --strategies express \
  --strategies free \
  --path src/app/features

Uso em um componente Angular:

import { Component, computed, inject, signal } from '@angular/core';
import { ShippingMode } from '../../models/shipping-mode.model';
import { ShippingCalculatorService } from '../../services/shipping-calculator.service';

@Component({
  selector: 'app-shipping-calculator',
  templateUrl: './shipping-calculator.component.html',
})
export class ShippingCalculatorComponent {
  private readonly shipping = inject(ShippingCalculatorService);
  protected readonly selectedMode = signal<ShippingMode>('economy');
  protected readonly context = { amount: 100 };

  protected readonly total = computed(() =>
    this.shipping.calculate(this.selectedMode(), this.context),
  );
}

Interceptadores HTTP funcionais

Gere um HttpInterceptorFn Angular testado a partir de uma receita explícita:

ng generate semmet-angular:interceptor correlation-id
ng generate semmet-angular:interceptor problem-details
ng generate semmet-angular:interceptor auth-token
ng generate semmet-angular:interceptor logging

Por padrão, o comando cria apenas o interceptador e seu teste HTTP isolado em src/app/http/<recipe>. O registro é explícito:

ng generate semmet-angular:interceptor correlation-id --register

--register atualiza um app.config.ts reconhecido com provideHttpClient(withInterceptors([...])). Quando a configuração existente não pode ser editada com segurança, o schematic a preserva e exibe o trecho para registro manual.

A receita auth-token usa uma fonte abstrata de token, permite credenciais somente para a mesma origem ou para origens explicitamente confiáveis e exclui os prefixos de URLs públicas configurados. Ela não impõe localStorage, filas de renovação de token, comportamento de logout ou um modelo de autenticação específico de uma empresa. A receita logging expõe hooks apenas para metadados e exclui intencionalmente cabeçalhos, corpos e parâmetros de consulta.

Contrato de transporte do token de autenticação

O template interceptor/auth-token anexa Authorization: Bearer <token> apenas em origens explicitamente permitidas (AUTH_ALLOWED_ORIGINS) e nunca lê nem escreve cookie. Essa é uma decisão deliberada, não uma omissão: enquanto o token viaja só pelo header, a proteção XSRF embutida do HttpClient (baseada em cookie) é irrelevante para esta biblioteca, e nenhum app.config.ts gerado precisa de withXsrfConfiguration().

Esse contrato é compartilhado com o backend de referência semmet-spring-boot-cli — o JwtAuthenticationFilter gerado lá também só lê o token do header Authorization, nunca de cookie. Os dois lados concordam hoje, mas por convenção, não por um contrato imposto em código.

Se um projeto migrar o token para um cookie httpOnly (reduz a superfície de exfiltração via XSS, ao custo de reintroduzir CSRF), a mudança precisa ser feita nos dois lados ao mesmo tempo: reativar csrf no SecurityConfig do Spring e configurar withXsrfConfiguration() aqui. Fazer só de um lado quebra a autenticação ou reabre uma vulnerabilidade que o outro lado já tinha fechado. Veja SECURITY_ROADMAP.md para o estado atual desse acompanhamento.

Comandos de componentes disponíveis

O catálogo de componentes está dividido em duas famílias práticas:

• componentes genéricos de aplicação para padrões comuns de interface, como botões, caixas de diálogo, abas, formulários, campos de entrada, navegação, tabelas, feedback, sobreposições e estrutura de layout;
• componentes financeiros e bancários para fluxos específicos do domínio, como Pix, boletos, seleção de contas, gerenciamento de beneficiários, aprovações, controles de cartões, gerenciamento de limites, simulação de empréstimos, avisos de conformidade, extratos, comprovantes e transferências.

Sobreposições e conteúdo expansível:

• accordion
• alert-dialog
• dialog
• disclosure
• menu-button
• offcanvas
• popover
• tooltip

Navegação e estrutura:

• breadcrumb
• card
• landmarks
• list-group
• navbar
• navigation-menu
• pagination
• skip-link
• tabs
• toolbar
• tree-view

Formulários e campos de entrada:

• checkbox
• combobox
• currency-input
• form
• input
• input-group
• listbox
• meter
• progress-bar
• radio-group
• select
• slider
• spinbutton
• switch
• textarea

Financeiros e bancários:

• account-selector
• account-summary
• authorization-queue
• beneficiary-form
• beneficiary-list
• card-controls
• compliance-alert
• confirmation-summary
• currency-input
• limit-manager
• loan-simulator
• otp-input
• payment-card
• payment-slip
• pix-payment
• scheduled-payment
• secure-code-input
• transaction-detail
• transaction-filter
• transaction-list
• transfer-form

Feedback, mídia e exibição:

• alert
• avatar
• badge
• button
• button-group
• carousel
• close-button
• rating
• skeleton
• spinner
• steps
• table
• toast

Opções

Opções comuns dos componentes:

• name: obrigatório e posicional.
• project: projeto Angular de destino.
• path: diretório de destino.
• e2e: booleano opcional. Gera um teste do Playwright somente quando solicitado explicitamente.

Licença

MIT