digisystem-ui

Design System de componentes UI para os projetos FGD (Angular). Este repositório é uma biblioteca (não um app) publicada no npm como digisystem-ui.

O nome do repositório é fgd-design-system, mas o pacote publicado — e o caminho de import — é digisystem-ui.

Stack

• Angular (library) + Angular CLI + ng-packagr
• Storybook (documentação e playground)
• Vitest (testes unitários)
• SCSS com BEM por componente e tokens em CSS custom properties

Instalação no projeto consumidor

npm i digisystem-ui@latest

Peer dependencies esperadas no consumidor:

| Pacote | Faixa | |---|---| | @angular/core | >=17 <22 | | @angular/common | >=17 <22 | | @angular/forms | >=17 <22 (opcional: só para os componentes de formulário; ds-spreadsheet não precisa) | | rxjs | >=7.5 <8 |

1. Registre os tokens (recomendado)

// angular.json → architect.build.options.styles
"styles": [
  "node_modules/digisystem-ui/styles/ds-tokens.css",
  "src/styles.scss"
]

Sem esse import os componentes continuam funcionando com os valores padrão, porque cada token é consumido com fallback. Com ele, você passa a poder tematizar:

:root {
  --ds-color-primary: #0b5cab;
  --ds-radius-lg: 12px;
  --ds-control-height-md: 38px;
}

2. Use os componentes (standalone)

import { DsButtonComponent, DsInputComponent } from 'digisystem-ui';

@Component({
  imports: [DsButtonComponent, DsInputComponent],
  // ...
})
export class ExampleComponent {}

<ds-input label="E-mail" type="email" size="md" [(value)]="email" />

<ds-button variant="primary" [fullWidth]="false" [loading]="salvando" (dsClick)="salvar()">
  Acessar
</ds-button>

Planilha editável (revisão e correção de dados importados):

<ds-spreadsheet #planilha [columns]="columns" [value]="rows" [validator]="validator" (errorsChange)="errors = $event" />
<ds-button [fullWidth]="false" [disabled]="errors.length > 0" (dsClick)="enviar(planilha.getValue())">Enviar</ds-button>

A referência completa de API está em design.md.

Desenvolvimento

npm install
npm run build            # gera dist/fgd-design-system (pacote digisystem-ui)
npm run watch            # build incremental
npm test                 # Vitest
npm run storybook        # playground em http://localhost:6006
npm run build-storybook

Windows / PowerShell (erro de Execution Policy)

Se aparecer "a execução de scripts foi desabilitada", use npm.cmd install ou ajuste a policy no escopo do usuário:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Estrutura

| Caminho | Conteúdo | |---|---| | src/components/ | Um diretório por componente (.ts, .html, .scss, .stories.ts, .spec.ts) | | src/components/shared/ | Tipos compartilhados entre componentes | | src/styles/_control.scss | Mixin de geometria usado por ds-input e ds-select | | styles/ds-tokens.css | Tokens publicados para o consumidor | | src/public-api.ts | API pública (exports) |

Convenções

• Componentes genéricos, orientados a API (inputs/outputs), sem lógica de negócio do consumidor.
• BEM por componente, com estilos encapsulados:
  • Block: ds-<componente> (ex.: ds-button)
  • Element: __ (ex.: ds-button__icon)
  • Modifier: -- (ex.: ds-button--primary)
• Tokens antes de literais. Nenhuma cor, raio ou sombra hardcoded: use var(--ds-*, <fallback>), sempre com o valor padrão como fallback.
• ds-input e ds-select compartilham geometria. Os dois derivam altura, padding e tipografia dos mesmos tokens --ds-control-* via o mixin size-vars. Ao mexer em tamanho, mexa no mixin ou nos tokens — nunca em um componente só.
• Acessibilidade: elementos nativos primeiro; manter foco visível, navegação por teclado e estados ARIA.
• Compatibilidade: renomear um input público exige manter o nome antigo como alias depreciado. Breaking changes só em major (SemVer).
• Storybook e testes no mesmo change set da alteração do componente.

Publicação

npm test
npm run build
cd dist/fgd-design-system
npm publish

O token de publicação fica em .npmrc, que não é versionado (está no .gitignore). Prefira mantê-lo no .npmrc global do usuário ($env:USERPROFILE\.npmrc).

O histórico de mudanças está em CHANGELOG.md.

Documentação

O Storybook é a fonte de verdade de variações e estados:

npm run storybook