pixel-plus

CLI e biblioteca de componentes para acelerar a criação de Design Systems em Vue 3 + Tailwind CSS.

O pixel-plus ajuda você a:

• Gerar configuração base de design system e Tailwind
• Instalar e copiar componentes prontos (ex.: Button, Select)
• Padronizar tokens (cores, tipografia, espaçamentos, radii, etc.)
• Trabalhar com um fluxo simples via npx (sem precisar instalar globalmente)

Requisitos

• Node.js >= 18
• npm >= 9 (ou pnpm/yarn se preferir)

Instalação

Use via npx (recomendado):

npx pixel-plus@latest --help

Ou instale localmente no seu projeto:

npm install -D pixel-plus
# ou
yarn add -D pixel-plus
# ou
pnpm add -D pixel-plus

Instalação Global (opcional)

Se preferir rodar o CLI globalmente:

npm install -g pixel-plus
# ou
yarn global add pixel-plus
# ou
pnpm add -g pixel-plus

# então use diretamente
pixel-plus --help
pixel-plus init
pixel-plus add Button

Como começar (Quickstart)

1. Crie um projeto Vue 3 (Vite recomendado):

npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install

2. Inicialize o design system e a configuração do Tailwind com o pixel-plus:

npx pixel-plus init

O comando init:

• Cria/atualiza tailwind.config.js com presets e tokens
• Cria postcss.config.js (se necessário)
• Gera um arquivo de design system em pixel-plus/design-system.ts
• Opcionalmente adiciona estilos globais e paths recomendados

Comandos

init

Inicializa o projeto com a configuração base de Design System e Tailwind.

npx pixel-plus init

Flags comuns:

• --yes executa no modo não interativo (usa defaults)
• --overwrite permite sobrescrever arquivos existentes

add <Component>

Copia componentes prontos para sua codebase (ex.: Button, Select).

npx pixel-plus add Button
npx pixel-plus add Select

O comando adiciona os arquivos em um diretório de componentes (por padrão src/components/ui/). Você pode editar depois como quiser.

list

Lista os componentes disponíveis para instalação.

npx pixel-plus list

version

Exibe a versão do CLI.

npx pixel-plus version

Estrutura gerada (padrão)

Após rodar init e add, você deve ver algo como:

src/
  components/
    ui/
      Button.vue
      Select.vue
pixel-plus/
  design-system.ts
tailwind.config.js
postcss.config.js

Configuração do Tailwind

O pixel-plus gera automaticamente um tailwind.config.js com tokens do design system:

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
  content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        primary: {
          default: "#3b82f6",
          light: "#60a5fa",
          dark: "#1d4ed8",
        },
        secondary: {
          default: "#64748b",
          light: "#94a3b8",
          dark: "#475569",
        },
        texture: {
          light: "#f1f5f9",
          default: "#334155",
          dark: "#0f172a",
        },
        accent: "#f59e0b",
        neutral: "#6b7280",
        success: "#10b981",
        warning: "#f59e0b",
        error: "#ef4444",
        info: "#3b82f6",
      },
      fontFamily: {
        sans: ["Inter", "ui-sans-serif", "system-ui", "sans-serif"],
        serif: ["ui-serif", "Georgia", "serif"],
        mono: ["ui-monospace", "SFMono-Regular", "monospace"],
      },
      borderRadius: {
        none: "0px",
        sm: "0.125rem",
        base: "0.25rem",
        md: "0.375rem",
        lg: "0.5rem",
        xl: "0.75rem",
        "2xl": "1rem",
        "3xl": "1.5rem",
        full: "9999px",
      },
      boxShadow: {
        sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)",
        base: "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
        md: "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
        lg: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
        xl: "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)",
        "2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)",
        inner: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)",
        none: "0 0 #0000",
      },
    },
  },
  plugins: [],
};

Usando com Nuxt 3

O pixel-plus funciona muito bem em projetos Nuxt 3.

1. Instale as dependências necessárias:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
npm install pixel-plus

2. Ative o módulo do Tailwind no Nuxt e configure os globs de conteúdo:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxtjs/tailwindcss"],
  css: ["~/assets/css/tailwind.css"],
  tailwindcss: {
    viewer: false,
  },
});

3. Conteúdo do tailwind.config.js (use os globs do Nuxt):

// tailwind.config.js
import { designSystem } from "./pixel-plus/design-system";

export default {
  content: [
    "./app.vue",
    "./components/**/*.{vue,js,ts}",
    "./layouts/**/*.{vue,js,ts}",
    "./pages/**/*.{vue,js,ts}",
    "./plugins/**/*.{js,ts}",
    "./nuxt.config.{js,ts}",
  ],
  theme: {
    extend: {
      // mapeamento dos tokens conforme exemplo acima
      colors: {
        primary: {
          DEFAULT: designSystem.colors.primary.default,
          light: designSystem.colors.primary.light,
          dark: designSystem.colors.primary.dark,
        },
      },
    },
  },
  plugins: [],
};

4. Inicialize e adicione componentes (opcional, via CLI):

npx pixel-plus init
npx pixel-plus add Button
npx pixel-plus add Select

5. Use normalmente dentro de páginas/slots do Nuxt:

<!-- pages/index.vue -->
<template>
  <div class="p-6 space-y-4">
    <Button>Enviar</Button>
    <Select :options="options" v-model="value" />
  </div>
</template>

<script setup lang="ts">
import Button from "@/components/ui/Button.vue";
import Select from "@/components/ui/Select.vue";
const options = [
  { value: "1", label: "Option 1" },
  { value: "2", label: "Option 2" },
];
const value = ref("");
</script>

Usando os componentes

Depois de adicionar um componente, importe e use normalmente:

<template>
  <div class="space-y-4">
    <Button variant="primary">Enviar</Button>
    <Select :options="options" v-model="value" />
  </div>
</template>

<script setup lang="ts">
import Button from "@/components/ui/Button.vue";
import Select from "@/components/ui/Select.vue";
import { ref } from "vue";

const value = ref("");
const options = [
  { value: "1", label: "Option 1" },
  { value: "2", label: "Option 2" },
];
</script>

Arquivos/Utilitários do pacote

O pacote expõe utilitários internos (uso pelo CLI), por exemplo:

• src/commands/* – comandos do CLI (init, add, list, version)
• src/config/design-system.ts – geração e tipagem do design system
• src/utils/tailwind-config-generator.ts – gerador do tailwind.config.js

Você não precisa importar esses utilitários diretamente no app; eles são usados quando você roda os comandos do CLI.

Dicas & Boas práticas

• Mantenha tokens (cores, spacing, radius, fontes) no design system
• Evite editar diretamente o dist/ (é gerado pelo build)
• Prefira componentes desacoplados e reutilizáveis

Troubleshooting

• "classes Tailwind não aplicam": verifique content no tailwind.config.js
• "componentes não aparecem": confirme o caminho de import e a extensão .vue
• "erro ao copiar componentes": rode com --overwrite se existir conflito

Scripts (desenvolvimento do pacote)

Se estiver contribuindo com o pacote:

# gerar build do CLI (arquivo dist/index.js)
npm run build

# executar CLI local (após build)
node dist/index.js --help

Licença

MIT © Pixel Plus