Makuco UI

Introdução

Bem-vindo ao Makuco UI — o design system da DB1 Group construído sobre Web Components nativos.

O que é o Makuco UI?

O Makuco UI é o design system oficial do DB1 Group. Ele fornece uma biblioteca de componentes de interface prontos para produção, construídos com Stencil.js e distribuídos como Web Components nativos.

A premissa central é simples: escreva uma vez, use em qualquer lugar. Os mesmos componentes funcionam em React, Angular ou com HTML puro — sem adaptações, sem reescritas, sem dependências de runtime proprietário.

Princípios fundamentais

Web Components nativos

Construídos sobre a plataforma web padrão (Custom Elements v1, Shadow DOM). Funcionam em qualquer framework ou com HTML puro, sem wrapper obrigatório.

Acessibilidade por padrão

Todos os componentes são desenvolvidos para atender WCAG 2.1 AA. Atributos ARIA, navegação por teclado e suporte a leitores de tela são requisitos, não opcionais.

Design Tokens semânticos

Sistema de tokens com prefixo --db1-* para cores, tipografia, espaçamento, sombras e motion. Nenhum valor é hardcodado — tudo é rastreável e substituível.

TypeScript first

APIs completamente tipadas com interfaces e tipos exportados. Autocompletar e verificação estática em todo o projeto, para React e Angular.

Acessibilidade

O Makuco UI adota o padrão WCAG 2.1 nível AA como linha de base para todos os componentes. Isso significa que cada componente entregue:

  • Expõe roles, states e properties via atributos ARIA corretos
  • Suporta navegação completa por teclado (Tab, Enter, Escape, setas)
  • Mantém contraste mínimo de 4.5:1 para texto normal e 3:1 para texto grande
  • É anunciado corretamente por leitores de tela (NVDA, VoiceOver, JAWS)
  • Respeita a preferência de movimento reduzido (prefers-reduced-motion)

Compromisso contínuo

A conformidade com WCAG é verificada em cada pull request. Componentes que não atendem o critério AA não são aceitos no repositório.

Design Tokens

Os tokens são a linguagem visual do Makuco UI. Em vez de hardcodar valores como #0055CC ou 16px, todo estilo referencia uma variável semântica:

/* ✅ Correto — rastreável, substituível */
color: var(--db1-text-color-neutral-900);
padding: var(--db1-spacing-4);
border-radius: var(--db1-radius-md);

/* ❌ Evitar — valores mágicos */
color: #1a1a1a;
padding: 16px;

Os tokens são organizados em duas camadas:

Primitivos

Valores brutos da paleta: --color-basics-blue-500, --color-basics-gray-100. Não devem ser usados diretamente nos componentes.

Semânticos

Tokens com intenção: --db1-text-color-neutral-900, --db1-stroke-color-neutral-700. São esses que os componentes e aplicações devem consumir.

Frameworks suportados

FrameworkPacoteStatus
Web Components / HTML@db1/makuco-ui-core✅ Estável
React@db1/makuco-ui-react✅ Estável
Angular@db1/makuco-ui-angular✅ Estável
Vue—🔜 Planejado

Instalação rápida

1. Instale os pacotes:

npm install @db1/makuco-ui-core @db1/makuco-ui-react

2. Importe o CSS global:

// app/layout.tsx ou index.tsx
import '@db1/makuco-ui-core/styles';

3. Use os componentes:

import { MkButton } from '@db1/makuco-ui-react';

export function App() {
  return <MkButton variant="filled">Olá, Makuco!</MkButton>;
}

1. Instale os pacotes:

npm install @db1/makuco-ui-core @db1/makuco-ui-angular

2. Importe o CSS global:

/* styles.css */
@import '@db1/makuco-ui-core/styles';

3. Importe os componentes diretamente no @Component:

import { Component } from '@angular/core';
import { MkButtonComponent, MkInputComponent } from '@db1/makuco-ui-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MkButtonComponent, MkInputComponent],
  template: `
    <mk-button variant="filled">Olá, Makuco!</mk-button>
    <mk-input label="Nome" placeholder="Digite seu nome" />
  `,
})
export class AppComponent {}

4. Integração com Angular Forms:

Para usar componentes com ngModel ou ReactiveFormsModule, importe o Module correspondente em vez do Component. Os Modules já incluem as diretivas de ControlValueAccessor necessárias:

import { ReactiveFormsModule } from '@angular/forms';
import { MkInputModule, MkSelectModule, MkCheckboxModule } from '@db1/makuco-ui-angular';

@Component({
  standalone: true,
  imports: [ReactiveFormsModule, MkInputModule, MkSelectModule, MkCheckboxModule],
  template: `
    <mk-input label="E-mail" [formControl]="email" />
    <mk-select label="Perfil" [formControl]="role" />
    <mk-checkbox label="Aceito os termos" [formControl]="terms" />
  `,
})
export class FormComponent {
  email = new FormControl('');
  role = new FormControl('');
  terms = new FormControl(false);
}

Component vs Module

Use MkInputComponent para renderização simples. Use MkInputModule quando o campo precisar de binding com ngModel ou FormControl — o Module inclui o ControlValueAccessor que conecta o web component ao sistema de formulários do Angular.

Via CDN:

<link rel="stylesheet" href="https://unpkg.com/@db1/makuco-ui-core/dist/makuco/makuco.css" />
<script type="module" src="https://unpkg.com/@db1/makuco-ui-core/dist/makuco/makuco.esm.js"></script>

<mk-button variant="filled">Olá, Makuco!</mk-button>

Próximos passos

Ver componentes

Explore a biblioteca completa de componentes com exemplos interativos e documentação de props.

Design Tokens

Referência completa de todos os tokens semânticos disponíveis no sistema.

Contribuir

O Makuco UI é open source. Veja como reportar bugs, sugerir componentes e contribuir com código.

On this page

O que é o Makuco UI?Princípios fundamentaisAcessibilidadeDesign TokensFrameworks suportadosInstalação rápidaPróximos passos