🍵 Matcha Palette

CLI para gerar paletas de cores em SCSS e JSON seguindo os padrões do Material Design

A biblioteca matcha-palette é uma ferramenta de linha de comando que gera automaticamente paletas de cores completas baseadas em uma cor principal, seguindo as diretrizes do Material Design para contraste e variações tonais.

📦 Instalação

npm install matcha-palette

🚀 Uso Rápido

Comando básico

npx build-palette ff7500

Este comando gera um arquivo _palette.scss no diretório atual com uma paleta completa baseada na cor laranja #ff7500.

📋 Sintaxe Completa

npx build-palette <cor1> [cor2] [cor3] ... [--format <formato>]

Parâmetros

• <cor>: Cor em formato hexadecimal (sem o #)
• --format: Formato de saída (opcional)

🎨 Formatos de Saída

| Formato | Descrição | Arquivo Gerado | |---------|-----------|----------------| | scss | Arquivo SCSS (padrão) | _palette.scss | | json | Arquivo JSON | _palette.json | | both | Ambos os formatos | _palette.scss + _palette.json | | json-merged | JSON único com múltiplas paletas | _palettes-merged.json |

💡 Exemplos Práticos

1. Paleta simples em SCSS

npx build-palette ff7500

Resultado: _palette.scss

2. Paleta em formato JSON

npx build-palette 3498db --format json

Resultado: _palette.json

3. Múltiplas paletas

npx build-palette ff7500 3498db e74c3c

Resultado:

• _palette.scss (laranja)
• _palette2.scss (azul)
• _palette3.scss (vermelho)

4. Múltiplas paletas em JSON

npx build-palette ff7500 3498db --format json

Resultado:

• _palette.json
• _palette2.json

5. Paletas em ambos os formatos

npx build-palette 2ecc71 --format both

Resultado:

• _palette.scss
• _palette.json

6. Paleta mesclada (múltiplas cores em um arquivo)

npx build-palette ff7500 3498db e74c3c --format json-merged

Resultado: _palettes-merged.json

📁 Estrutura dos Arquivos Gerados

Arquivo SCSS (_palette.scss)

$palette: (
	50: #fff3e0,
	100: #ffe0b2,
	200: #ffcc80,
	300: #ffb74d,
	400: #ffa726,
	500: #ff9800,
	600: #fb8c00,
	700: #f57c00,
	800: #ef6c00,
	900: #e65100,
	contrast: (
		50: #000000,
		100: #000000,
		200: #000000,
		300: #000000,
		400: #000000,
		500: #000000,
		600: #ffffff,
		700: #ffffff,
		800: #ffffff,
		900: #ffffff,
	)
);

Arquivo JSON (_palette.json)

{
  "palette": {
    "50": "#fff3e0",
    "100": "#ffe0b2",
    "200": "#ffcc80",
    "300": "#ffb74d",
    "400": "#ffa726",
    "500": "#ff9800",
    "600": "#fb8c00",
    "700": "#f57c00",
    "800": "#ef6c00",
    "900": "#e65100",
    "contrast": {
      "50": "#000000",
      "100": "#000000",
      "200": "#000000",
      "300": "#000000",
      "400": "#000000",
      "500": "#000000",
      "600": "#ffffff",
      "700": "#ffffff",
      "800": "#ffffff",
      "900": "#ffffff"
    }
  }
}

Arquivo JSON Mesclado (_palettes-merged.json)

{
  "colors": {
    "color1": {
      "50": "#fff3e0",
      "100": "#ffe0b2",
      // ... mais variações da primeira cor
    },
    "color2": {
      "50": "#e3f2fd",
      "100": "#bbdefb",
      // ... mais variações da segunda cor
    }
  }
}

🎯 Casos de Uso

1. Desenvolvimento de Temas

# Gerar paleta principal do tema
npx build-palette 1976d2 --format both

# Gerar paletas de apoio
npx build-palette 388e3c f57c00 --format scss

2. Design System

# Gerar todas as paletas do design system em um arquivo
npx build-palette 1976d2 388e3c f57c00 ff5722 9c27b0 --format json-merged

3. Prototipagem Rápida

# Testar diferentes variações de uma cor
npx build-palette 2196f3 21f396 f32196 --format json

📂 Localização dos Arquivos

Os arquivos são gerados no diretório atual onde você executa o comando.

# Verificar diretório atual
pwd

# Executar comando
npx build-palette ff7500

# Arquivo será criado em: ./pasta-atual/_palette.scss

Organizando em Pastas

# Criar pasta para paletas
mkdir src/styles/palettes
cd src/styles/palettes

# Gerar paletas na pasta específica
npx build-palette ff7500 3498db

🛠️ Integração com Projetos

Angular/Ionic

// src/theme/variables.scss
@import 'palettes/_palette.scss';

:root {
  --ion-color-primary: #{map-get($palette, 500)};
  --ion-color-primary-shade: #{map-get($palette, 700)};
  --ion-color-primary-tint: #{map-get($palette, 300)};
}

React/Vue

// Importar paleta JSON
import palette from './palettes/_palette.json';

const theme = {
  primary: palette.palette['500'],
  primaryLight: palette.palette['300'],
  primaryDark: palette.palette['700'],
};

CSS Customizado

@import '_palette.scss';

.btn-primary {
  background-color: map-get($palette, 500);
  border-color: map-get($palette, 600);

  &:hover {
    background-color: map-get($palette, 600);
  }

  &:active {
    background-color: map-get($palette, 700);
  }
}

🎨 Teoria das Cores

A biblioteca segue os padrões do Material Design:

• 50-100: Tons muito claros
• 200-300: Tons claros
• 400-500: Tons médios (500 é a cor base)
• 600-700: Tons escuros
• 800-900: Tons muito escuros

Contraste Automático

• Cores claras (50-500): texto preto (#000000)
• Cores escuras (600-900): texto branco (#ffffff)

🔧 Solução de Problemas

Erro: "Comando não encontrado"

# Verificar se o pacote está instalado
npm list matcha-palette

# Reinstalar se necessário
npm install matcha-palette

Erro: "Cor inválida"

# ✅ Correto
npx build-palette ff7500

# ❌ Incorreto
npx build-palette #ff7500  # Não usar #
npx build-palette orange   # Não usar nomes de cores

Arquivo não gerado

# Verificar permissões de escrita no diretório
ls -la

# Verificar se o diretório existe
pwd

📚 Referências

• Material Design Color System
• Material Design Palette Generator

📄 Licença

MIT © Wallace Anjos

🤝 Contribuição

Contribuições são bem-vindas! Para contribuir:

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Desenvolvido com 💚 para facilitar a criação de paletas de cores consistentes e acessíveis.