Criar um tema Tailwind CSS

• Uso inline
• Criando um tema FormKit configurável
  • Inicialize uma cópia do tema inicial
  • A anatomia do tema inicial
  • Trabalhando com variáveis
  • Variáveis com escalas
  • Variáveis com valores controláveis pelo usuário
  • Definindo min e max para variáveis controláveis pelo usuário
  • Criando restrições únicas de mínimo e máximo
  • Substituindo as escalas padrão do editor
• Publicando seu tema
• Instalando um tema de terceiros publicado
• Personalizando as variáveis de um tema publicado
• Enviando o seu tema para themes.formkit.com
• Obtendo ajuda

Neste guia, vamos percorrer o processo de criação de um tema Tailwind personalizado para seus formulários e campos. O Tailwind se destacou como uma das principais bibliotecas de classes utilitárias de CSS, e o FormKit foi desenvolvido tendo em mente suas capacidades. Vamos começar!

Uso inline

No contexto de um arquivo .vue que representa um componente, é possível criar um tema Tailwind usando as props de classe section-key ou a prop classes fornecida pelo FormKit.

Se o seu componente representa todo o seu formulário e seu projeto requer apenas um único formulário, isso pode ser tudo o que você precisa. Aqui está um exemplo de aplicação das mesmas classes Tailwind a um campo de texto do FormKit usando tanto as props section-key quanto a prop classes:

Esta é uma maneira de baixa barreira para aplicar estilos Tailwind aos seus formulários FormKit, mas e se você tiver vários formulários — ou precisar lidar com uma grande variedade de campos? Copiar e colar listas de classes entre componentes não é o ideal e levará a variações involuntárias de estilo em seu projeto ao longo do tempo.

Vamos explorar como podemos criar um tema Tailwind — com opções configuráveis — que possa cobrir todos os campos em seu projeto em um nível global.

Criando um tema FormKit configurável

Seguindo as instruções abaixo, criaremos um tema como os disponíveis em https://themes.formkit.com. Isso inclui suporte para variáveis configuráveis pelo usuário, caso você escolha fornecê-las.

Temas FormKit

Temas Tailwind versáteis, configuráveis e licenciados pelo MIT para uso em seus projetos. Gaste menos tempo estilizando — mais tempo construindo.

Uma vez que seu tema esteja completo, você pode enviar seu tema para ser incluído em https://themes.formkit.com abrindo um PR contra o repositório do site. Uma vez aprovado, ele estará disponível para qualquer outra pessoa usar em seu projeto via CLI ou interface web.

Inicialize uma cópia do tema inicial

O FormKit fornece um tema inicial — que vem com estilos estruturais e comentários abundantes — que tem a intenção de ajudar novos autores a criarem seus próprios temas.

Para começar, execute o seguinte comando no seu terminal:

npx formkit create-theme

Isso fará o download de uma cópia limpa do tema inicial para você começar a trabalhar. O tema inicial é uma aplicação Vite totalmente funcional que inclui um "Kitchen Sink" para ajudá-lo a ver como suas classes afetam cada entrada disponível do FormKit.

Em seguida, você precisará fazer login em https://pro.formkit.com e criar uma nova chave de desenvolvimento (gratuita) para o FormKit Pro. Esta chave permitirá que você renderize os elementos do FormKit Pro que estão incluídos no Kitchen Sink.

Adicione sua chave do FormKit Pro a um arquivo .env na raiz do seu projeto

FORMKIT_PRO_KEY=fk-**********

Depois de adicionar sua chave pro, execute os seguintes comandos para começar a trabalhar no seu tema:

# ou npm ou yarn
pnpm install
pnpm dev

A anatomia do tema inicial

O diretório src no tema inicial contém os seguintes arquivos e diretórios importantes:

• theme.ts: Este é o ponto de entrada para o seu tema. É onde você configurará os metadados do seu tema, variáveis e importará as listas de classes CSS do seu tema para cada entrada.
  • meta: As informações meta como o nome do tema, entradas suportadas e declarações para suporte a modo claro e modo escuro.
  • variables: As variáveis que serão usadas nas listas de classes CSS do seu tema — variáveis que são atribuídas a um 'editor' exporão controles de UI para os usuários do tema no editor de temas. Mais sobre isso abaixo.
  • inputs: Um objeto de nomes de entradas mapeado a um objeto de nomes de seções e listas de classes. Por padrão, as listas de classes para cada entrada são feitas como importações separadas.
• globals.ts: Este arquivo contém classes globais para as entradas. Qualquer nome de seção correspondente (por exemplo, 'outer') será aplicado a todas as entradas do FormKit. Uma economia de tempo, mas use com cautela.
• familes/*.ts: Um passo acima em especificidade do que as classes globais, estes arquivos contêm listas de classes para cada família de entrada. Famílias são agrupamentos de entradas similares onde o compartilhamento de estilos faz sentido — por exemplo, a família 'text' inclui mais de 16 entradas suportadas no FormKit. Cada arquivo de família contém um comentário no topo com uma lista de entradas que estão incluídas nessa família.
• inputs/*.ts: As listas de classes mais específicas para cada entrada. Estas classes se aplicam apenas à entrada indicada pelo nome do arquivo (assumindo que você as tenha atribuído corretamente no seu theme.ts, o que é feito para você por padrão). Quando aplicável, estes arquivos incluem um comentário indicando de qual família eles herdam classes.

Os demais arquivos no tema inicial podem ser ignorados (mas não removidos) pois são a estrutura para a aplicação Vite incluída e o Kitchen Sink. Eles não terão efeito material no seu tema publicado.

Trabalhando com variáveis

Variáveis são uma forma poderosa de reutilizar valores em todo o seu tema e permitir que os usuários do tema personalizem o seu tema de acordo com suas preferências. Variáveis são usadas nas listas de classes dos seus inputs através da seguinte sintaxe:

// global.ts
export default {
  outer: `$myVariable`
}

O tema inicial vem com muitas variáveis pré-definidas.

Variáveis básicas

As seguintes variáveis são definidas por conveniência no tema inicial, mas não expõem nenhuma interface de usuário para os usuários do tema:

• accentColor
• accentColorStrength
• accentColorStrengthDark
• colorTemperature
• colorTemperatureStrength
• colorTemperatureStrengthDark
• inputMaxWidth

O tema inicial também vem com as seguintes variáveis que expõem controles de interface de usuário para os usuários do tema:

• radius,
• spacing,
• scale

Você pode criar suas próprias variáveis básicas não configuráveis pelo usuário fornecendo um novo par chave/valor no objeto de variáveis:

export default createTheme({
  ...
  variables: {
    ...
    textSize: 'lg'
  }
})

Variáveis podem ser usadas nas listas de classes dos seus inputs usando a seguinte sintaxe:

// globals.ts
export default {
  // se torna 'text-lg'
  label: 'text-$textSize'
}

Colocar valores comuns compartilhados em variáveis permite que os autores de temas ajustem rapidamente valores em todas as listas de classes do seu tema a partir de um único local.

Variáveis com escalas

Um dos melhores aspectos do Tailwind é que todos os valores operam em escalas previsíveis. Isso significa que podemos fornecer um "intervalo" para uma variável e então subir e descer na escala conforme necessário dentro do nosso tema.

Por exemplo, uma variável spacing pode operar usando a seguinte escala do Tailwind (0, px, 0.5, 1, 1.5, 2, 2.5, 3 etc). Fornecendo uma scale e um value padrão, podemos nos dar a habilidade de subir e descer na escala à vontade.

spacing: {
  value: "2",
  // Podemos definir uma escala pela qual podemos avançar.
  // O valor padrão será usado como ponto de partida.
  // Como estamos definindo a escala, podemos omitir valores
  // padrão do Tailwind como '0' e 'px' se eles não fizerem
  // sentido para o nosso caso de uso.
  scale: ["0.5", "1", "1.5", "2", "2.5", "3", "4", "6"]
},

Com a variável acima definida, agora podemos dinamicamente subir e descer na escala em nossas listas de classes com a seguinte sintaxe:

// globals.ts
export default {
  // se torna 'mb-3' — dois passos acima na nossa escala
  outer: 'mb-$spacing(2)',
  // se torna 'mb-2' — nosso valor padrão da escala
  label: 'mb-$spacing',
  // se torna 'mb-1 — dois passos abaixo na nossa escala'
  help: 'mb-$spacing(-2)'
  // uma mistura de múltiplos valores usando a mesma variável
  // se torna 'mb-1 px-3 py-2'
  inner: 'mb-$spacing(-2) px-$spacing(2) py-$spacing'
}

Variáveis nunca podem exceder os limites de suas escalas, então mb-$spacing(100) se tornaria mb-6, já que esse é o limite superior da nossa escala fornecida.

Variáveis com valores controláveis pelo usuário

Variáveis são legais — mas o verdadeiro poder vem de expor variáveis para os usuários finais do nosso tema e permitir que eles configurem os valores de acordo com suas preferências.

Para fazer isso, fornecemos um valor editor para nossa variável. O editor determina qual controle de interface do usuário é exposto no painel de personalização do tema. Os valores de editor disponíveis são os seguintes:

• buttons: Um conjunto de botões em grupo usado para selecionar um valor. Os autores do tema devem fornecer sua própria escala.
• color: Um conjunto de amostras, cada uma representando uma cor padrão do Tailwind. Por padrão inclui uma escala de todas as 22 cores disponíveis do Tailwind.
• fontSize: Um conjunto de botões com a letra A em diferentes tamanhos. Por padrão inclui uma escala de xs a 9xl.
• radius: Um conjunto de botões, cada um representando uma intensidade diferente de raio de borda. Por padrão inclui uma escala de rounded-none a rounded-full.
• shadow: Um passo a passo com uma representação do nível de sombra selecionado. Por padrão inclui uma escala de shadow-none a shadow-2xl.
• spacing: Um controle deslizante com uma gama de valores com representações de espaçamento mais apertado no início e mais amplo no final. Por padrão inclui uma escala de 0 a 96.
• select: Uma lista de seleção HTML padrão que pode conter qualquer número de valores. Os autores do tema devem fornecer sua própria escala.

Você pode ver um exemplo de cada um desses valores de editor visualizando a interface do editor para o tema Regenesis aqui.

Podemos atualizar nossa variável spacing para usar um editor apropriado:

spacing: {
  editor: "spacing",
  value: "2"
}

Agora veremos um novo controle no editor de temas para nossa variável spacing com um controle deslizante que nos permite ir de 0 a 96 à medida que avançamos pela escala padrão do Tailwind.

Definindo min e max para variáveis controláveis pelo usuário

Na maioria dos casos, faz sentido restringir a escala disponível para uma variável configurável pelo usuário. Permitir que nossos usuários ajustem o spacing é ótimo, mas provavelmente não queremos que eles possam aumentar o valor até 96 ou reduzi-lo para 0. Podemos restringir o intervalo da escala que está disponível para um usuário usando as propriedades min e max em nossa variável.

spacing: {
  editor: "spacing",
  value: "2",
  min: "1",
  max: "3"
}

Isso significa que nossa variável spacing agora só permitirá que os valores 1, 1.5, 2, 2.5 e 3 sejam selecionados por meio da interface do personalizador.

Criando restrições únicas de mínimo e máximo

Às vezes, como autor de um tema, você precisa limitar ou expandir os valores disponíveis além do que é definido na definição padrão de min e max de uma variável. Você pode fazer isso passando argumentos adicionais de min e max para instâncias inline de uma variável.

Os valores fornecidos para min e max devem ser valores ou da escala associada à variável — seja essa uma escala padrão para um editor ou uma escala personalizada definida pelo autor do tema.

Você também pode fornecer um símbolo curinga * como o 2º argumento para permitir qualquer valor válido na escala associada.

// globals.ts
export default {
  // aumenta 5 passos na escala.
  // define o valor mínimo para 3
  // e o valor máximo para 8
  outer: 'mb-$spacing(5, 3, 8)',
  // diminui 2 passos na escala
  // define o valor mínimo para 1
  // e o valor máximo para 2
  label: 'mb-$spacing(-2, 1, 2)',
  // diminui 2 passos na escala
  // permite qualquer valor válido na escala
  help: 'mb-$spacing(-2,*)'
}

Substituindo as escalas padrão do editor

Alguns tipos de editor, como scale ou color, vêm com escalas padrão. No entanto, podemos substituir os padrões fornecendo uma propriedade scale personalizada.

accentColor: {
  editor: "color",
  value: "blue",
  // exclui todas as cores "gray"
  // da escala padrão
  scale: [
    "red",
    "orange",
    "amber",
    "yellow",
    "lime",
    "green",
    "emerald",
    "teal",
    "cyan",
    "sky",
    "blue",
    "indigo",
    "violet",
    "purple",
    "fuchsia",
    "pink",
    "rose",
  ],
},

Você pode até combinar escalas personalizadas com propriedades min e max para criar escalas inteiramente novas além dos valores disponíveis nas escalas padrão do Tailwind.

scale: {
  editor: "fontSize",
  value: "base",
  scale: [
    // um tamanho personalizado e a altura de linha
    // correspondente para o tamanho.
    "[11px] [line-height:1em]",

    // valores padrão do Tailwind
    // em uma faixa que consideramos sensata.
    "xs",
    "sm",
    "base",
    "lg",
    "xl",
    "2xl",
  ],
  min: "sm",
  max: "lg",
},

Há muitos mais comentários no tema @formkit/theme-starter em si para ajudá-lo em seu caminho enquanto você trabalha.

Publicando seu tema

Quando você terminar de criar seu tema, você pode usar o script de publicação incluso para construir e publicar seu tema no npm.

Primeiro, certifique-se de que você modificou o conteúdo da chave meta do seu tema e do arquivo package.json para refletir com precisão o nome, a descrição, a versão e as informações do autor do seu tema.

Quando estiver pronto, execute o seguinte comando no seu terminal

# pnpm altamente recomendado
pnpm release

Este comando constrói o seu tema, executa um linter para garantir que o seu package.json é válido, executa um script para aumentar a versão do seu tema (e cria notas de lançamento automaticamente se você estiver usando mensagens de commit semânticas), e então publica o seu tema no npm sob o nome do pacote fornecido.

Instalando um tema de terceiros publicado

Para usar um tema de terceiros que você ou outra pessoa publicou no npm, primeiro instale-o como uma dependência de desenvolvimento no seu projeto:

pnpm add -D formkit-theme-my-theme

pnpm add -D formkit

Uma vez que o tema tenha sido instalado como dependência, você pode construir o seu tema com o comando theme do CLI formkit.

# irá resolver a partir do seu local node_modules
npx formkit@latest theme --theme=formkit-theme-my-theme

Este comando irá produzir um arquivo formkit.theme.(mjs|ts) no diretório raiz do seu projeto. Para completar a configuração, você precisará fazer as seguintes duas coisas:

• Importar a função rootClasses do seu tema construído para o seu arquivo formkit.config
• Adicionar o arquivo formkit.theme ao array content do seu arquivo tailwind.config.

// formkit.config.ts
import { defaultConfig } from '@formkit/vue'
import { rootClasses } from './formkit.theme'

export default defaultConfig({
  ...
  config: {
    rootClasses,
  },
})

// tailwind.config.js
module.exports = {
  ...
  content: [
    "./app.vue",
    "./formkit.theme.ts" // <-- adicione o arquivo do seu tema
  ]
}

Personalizando as variáveis de um tema publicado

Precisa alterar algumas das variáveis disponíveis no seu tema? Isso pode ser feito importando e sobrescrevendo o seu tema em um arquivo intermediário e, em seguida, passando esse arquivo intermediário para o CLI formkit. Para este exemplo, vamos criar um arquivo chamado formkit.theme.config.ts na raiz do nosso projeto. Neste arquivo, vamos importar o nosso tema e reexportá-lo passando as substituições de variáveis.

// formkit.theme.config.ts
import myTheme from 'formkit-theme-my-theme'

export default myTheme({
  // modifique quaisquer variáveis que estejam disponíveis no seu tema
  radius: 'rounded-full',
  spacing: '2.5',
  accentColor: 'violet'
})

Agora você pode usar o CLI formkit para construir o seu tema com as suas personalizações aplicadas.

# irá gerar o seu tema com as suas variáveis sobrescritas
npx formkit@latest theme --theme=formkit.theme.config.ts

Instale o arquivo resultante formkit.theme.(mjs|ts) seguindo as mesmas instruções da seção acima — adicionando as rootClasses ao seu arquivo formkit.config e incluindo o arquivo formkit.theme.(mjs|ts) no array de conteúdo do seu arquivo tailwind.config.

Enviando o seu tema para themes.formkit.com

Orgulhoso do seu tema? Oferecendo algo único que outros usuários do FormKit gostariam de usar?

Abra um pull request contra o repositório themes.formkit.com e submeta o seu tema! Uma vez aprovado, ele será listado na galeria de temas e estará disponível para qualquer pessoa usar em seu projeto tão facilmente quanto os temas de primeira parte fornecidos pelo FormKit.

# instalável diretamente pelo nome de themes.formkit.com uma vez mesclado
npx formkit@latest theme --theme=my-theme

Obtendo ajuda

Escrever um tema completo para o FormKit é uma grande empreitada. Se você ficar preso, precisar de ideias ou quiser conversar sobre a criação de temas para o FormKit, certifique-se de se juntar a nós em nossa comunidade oficial do Discord. Estamos felizes em ajudar!