Créer un thème Tailwind CSS

• Utilisation en ligne
• Créer un thème FormKit configurable
  • Initialiser une copie du thème de démarrage
  • L'anatomie du thème de démarrage
  • Travailler avec des variables
  • Variables avec échelles
  • Variables avec des valeurs contrôlables par l'utilisateur
  • Définir min et max pour les variables contrôlables par l'utilisateur
  • Création de contraintes min et max ponctuelles
  • Remplacement des échelles par défaut de l'éditeur
• Publication de votre thème
• Installer un thème tiers publié
• Personnaliser les variables d'un thème publié
• Soumettre votre thème à themes.formkit.com
• Obtenir de l'aide

Dans ce guide, nous allons parcourir le processus de création d'un thème Tailwind personnalisé pour vos formulaires et champs. Tailwind s'est imposé comme l'une des bibliothèques de classes utilitaires CSS les plus en vue, et FormKit a été conçu en tenant compte de ses capacités. Commençons !

Utilisation en ligne

Dans le contexte d'un fichier .vue qui représente un composant, il est possible de créer un thème Tailwind en utilisant les props de classe section-key ou la prop classes fournie par FormKit.

Si votre composant représente l'intégralité de votre formulaire et que votre projet ne nécessite qu'un seul formulaire, cela peut être tout ce dont vous avez besoin. Voici un exemple d'application des mêmes classes Tailwind à un champ text de FormKit en utilisant à la fois les props section-key et la prop classes :

C'est une manière simple d'appliquer les styles Tailwind à vos formulaires FormKit, mais que faire si vous avez plusieurs formulaires — ou si vous devez gérer une grande variété de champs ? Copier-coller des listes de classes entre les composants n'est pas idéal et conduira à des variations involontaires de style dans votre projet au fil du temps.

Explorons comment nous pouvons créer un thème Tailwind — avec des options configurables — qui peut couvrir tous les champs de votre projet à un niveau global.

Créer un thème FormKit configurable

En suivant les instructions ci-dessous, nous allons créer un thème comme ceux disponibles sur https://themes.formkit.com. Cela inclut le support pour des variables configurables par l'utilisateur si vous choisissez de les fournir.

Thèmes FormKit

Des thèmes Tailwind polyvalents, configurables et sous licence MIT pour une utilisation dans vos projets. Passez moins de temps à styliser — plus de temps à construire.

Une fois votre thème terminé, vous pouvez soumettre votre thème pour qu'il soit inclus sur https://themes.formkit.com en ouvrant une PR contre le dépôt du site. Une fois approuvé, il deviendra disponible pour que quiconque puisse l'utiliser dans son projet via la CLI ou l'interface web.

Initialiser une copie du thème de démarrage

FormKit fournit un thème de démarrage — qui vient avec des styles structurels et de nombreux commentaires — qui est destiné à aider les nouveaux auteurs à créer leurs propres thèmes.

Pour commencer, exécutez la commande suivante dans votre terminal :

npx formkit create-theme

Cela téléchargera une copie propre du thème de démarrage sur laquelle vous pourrez travailler. Le thème de démarrage est une application Vite entièrement fonctionnelle qui comprend un "Kitchen Sink" pour vous aider à voir comment vos classes affectent chaque entrée FormKit disponible.

Ensuite, vous devrez vous connecter sur https://pro.formkit.com et créer une nouvelle clé de développement (gratuite) pour FormKit Pro. Cette clé vous permettra de rendre les éléments FormKit Pro qui sont inclus dans le Kitchen Sink.

Ajoutez votre clé FormKit Pro à un fichier .env à la racine de votre projet

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

Une fois que vous avez ajouté votre clé pro, exécutez les commandes suivantes pour commencer à travailler sur votre thème :

# ou npm ou yarn
pnpm install
pnpm dev

L'anatomie du thème de démarrage

Le répertoire src dans le thème de démarrage contient les fichiers et répertoires importants suivants :

• theme.ts : C'est le point d'entrée de votre thème. C'est là que vous configurerez les métadonnées de votre thème, les variables, et importerez les listes de classes CSS de votre thème pour chaque entrée.
  • meta : Les informations méta telles que le nom du thème, les entrées prises en charge, et les déclarations pour le support des modes clair et sombre.
  • variables : Les variables qui seront utilisées dans les listes de classes CSS de votre thème — les variables qui se voient attribuer un 'éditeur' exposeront des contrôles d'interface utilisateur pour les utilisateurs du thème dans l'éditeur de thème. Plus de détails ci-dessous.
  • inputs : Un objet de noms d'entrée mappé chacun à un objet de noms de sections et de listes de classes. Par défaut, les listes de classes pour chaque entrée sont faites comme des importations séparées.
• globals.ts : Ce fichier contient des classes globales pour les entrées. Tout nom de section correspondant (par exemple, 'outer') sera appliqué à chaque entrée FormKit. Un gain de temps, mais à utiliser avec prudence.
• familes/*.ts : Un degré de spécificité plus élevé que les classes globales, ces fichiers contiennent des listes de classes pour chaque famille d'entrée. Les familles sont des groupements d'entrées similaires où le partage de styles a du sens — par exemple, la famille 'text' comprend plus de 16 entrées prises en charge dans FormKit. Chaque fichier de famille contient un commentaire en haut avec une liste des entrées qui sont incluses dans cette famille.
• inputs/*.ts : Les listes de classes les plus spécifiques pour chaque entrée. Ces classes s'appliquent uniquement à l'entrée indiquée par le nom du fichier (en supposant que vous les avez correctement assignées dans votre theme.ts, ce qui est fait pour vous par défaut). Lorsque cela est applicable, ces fichiers incluent un commentaire indiquant de quelle famille ils héritent des classes.

Les autres fichiers dans le thème de démarrage peuvent être ignorés (mais pas supprimés) car ils constituent l'échafaudage de l'application Vite incluse et du Kitchen Sink. Ils n'auront aucun effet matériel sur votre thème publié.

Travailler avec des variables

Les variables sont un moyen puissant de réutiliser des valeurs dans votre thème et de permettre aux utilisateurs de personnaliser votre thème selon leurs préférences. Les variables sont utilisées dans les listes de classes de vos entrées via la syntaxe suivante :

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

Le thème de démarrage est livré avec de nombreuses variables prédéfinies.

Variables de base

Les variables suivantes sont définies pour la commodité dans le thème de démarrage mais ne pas exposent aucune interface utilisateur pour les utilisateurs du thème :

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

Le thème de démarrage est également livré avec les variables suivantes qui exposent des contrôles d'interface utilisateur pour les utilisateurs du thème :

• radius,
• spacing,
• scale

Vous pouvez créer vos propres variables de base non configurables par l'utilisateur en fournissant une nouvelle paire clé/valeur dans l'objet variables :

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

Les variables peuvent être utilisées dans les listes de classes de vos entrées en utilisant la syntaxe suivante :

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

Mettre des valeurs communes partagées dans des variables permet aux auteurs de thèmes d'ajuster rapidement les valeurs dans toutes les listes de classes de leur thème à partir d'un seul emplacement.

Variables avec échelles

L'un des meilleurs aspects de Tailwind est que toutes les valeurs fonctionnent sur des échelles prévisibles. Cela signifie que nous pouvons fournir une "gamme" pour une variable et ensuite monter ou descendre dans l'échelle selon les besoins dans notre thème.

Par exemple, une variable spacing pourrait fonctionner en utilisant l'échelle Tailwind suivante (0, px, 0.5, 1, 1.5, 2, 2.5, 3, etc). En fournissant une scale et une value par défaut, nous pouvons nous donner la capacité de monter et descendre dans l'échelle à volonté.

spacing: {
  value: "2",
  // Nous pouvons définir une échelle que nous pouvons parcourir.
  // La valeur par défaut sera utilisée comme point de départ.
  // Comme nous définissons l'échelle, nous pouvons omettre les valeurs
  // par défaut de Tailwind comme '0' et 'px' si elles n'ont pas de sens
  // pour notre cas d'utilisation.
  scale: ["0.5", "1", "1.5", "2", "2.5", "3", "4", "6"]
},

Avec la variable ci-dessus définie, nous pouvons maintenant monter et descendre dynamiquement dans l'échelle dans nos listes de classes avec la syntaxe suivante :

// globals.ts
export default {
  // devient 'mb-3' — deux crans au-dessus de notre échelle
  outer: 'mb-$spacing(2)',
  // devient 'mb-2' — notre valeur d'échelle par défaut
  label: 'mb-$spacing',
  // devient 'mb-1 — deux crans en dessous de notre échelle'
  help: 'mb-$spacing(-2)'
  // un mélange de plusieurs valeurs utilisant la même variable
  // devient 'mb-1 px-3 py-2'
  inner: 'mb-$spacing(-2) px-$spacing(2) py-$spacing'
}

Les variables ne peuvent jamais dépasser les limites de leurs échelles, donc mb-$spacing(100) deviendrait mb-6 car c'est la limite supérieure de notre échelle fournie.

Variables avec des valeurs contrôlables par l'utilisateur

Les variables sont cool — mais la vraie puissance vient du fait d'exposer les variables aux utilisateurs finaux de notre thème et de leur permettre de configurer les valeurs selon leurs préférences.

Pour ce faire, nous fournissons une valeur editor pour notre variable. L'editor détermine quel contrôle d'interface utilisateur est exposé dans le panneau de personnalisation du thème. Les valeurs editor disponibles sont les suivantes :

• buttons : Un ensemble de boutons dans un groupe utilisé pour sélectionner une valeur. Les auteurs de thème doivent fournir leur propre échelle.
• color : Un ensemble de nuanciers représentant chacun une couleur par défaut de Tailwind. Inclut par défaut une échelle des 22 couleurs Tailwind disponibles.
• fontSize : Un ensemble de boutons avec la lettre A en différentes tailles. Inclut par défaut une échelle de xs à 9xl.
• radius : Un ensemble de boutons représentant chacun une intensité différente de rayon de bordure. Inclut par défaut une échelle de rounded-none à rounded-full.
• shadow : Un sélecteur avec une représentation du niveau d'ombre sélectionné. Inclut par défaut une échelle de shadow-none à shadow-2xl.
• spacing : Un curseur avec une gamme de valeurs représentant un espacement plus serré au début et plus large à la fin. Inclut par défaut une échelle de 0 à 96.
• select : Une liste de sélection HTML standard qui peut contenir n'importe quel nombre de valeurs. Les auteurs de thème doivent fournir leur propre échelle.

Vous pouvez voir un exemple de chacune de ces valeurs d'éditeur en consultant l'interface utilisateur de l'éditeur pour le thème Regenesis ici.

Nous pouvons mettre à jour notre variable spacing pour utiliser un éditeur approprié :

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

Nous verrons maintenant un nouveau contrôle dans l'éditeur de thème pour notre variable spacing avec un curseur qui nous permet de passer de 0 à 96 en suivant l'échelle par défaut de Tailwind.

Définir min et max pour les variables contrôlables par l'utilisateur

Dans la plupart des cas, il est logique de contraindre l'échelle disponible pour une variable configurable par l'utilisateur. Permettre à nos utilisateurs d'ajuster spacing est excellent, mais nous ne voulons probablement pas qu'ils puissent augmenter la valeur jusqu'à 96 ou la diminuer jusqu'à 0. Nous pouvons contraindre la plage de l'échelle qui est disponible pour un utilisateur en utilisant les propriétés min et max sur notre variable.

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

Cela signifie que notre variable spacing ne permettra désormais que les valeurs 1, 1.5, 2, 2.5 et 3 d'être sélectionnées via l'interface utilisateur du personnalisateur.

Création de contraintes min et max ponctuelles

Parfois, en tant qu'auteur de thème, vous devez limiter ou étendre les valeurs disponibles au-delà de ce qui est défini dans la définition par défaut min et max d'une variable. Vous pouvez le faire en passant des arguments min et max supplémentaires aux instances en ligne d'une variable.

Les valeurs fournies pour min et max doivent être des valeurs ou des variables associées à l'échelle — que ce soit une échelle par défaut pour un éditeur ou une échelle personnalisée définie par l'auteur du thème.

Vous pouvez également fournir un symbole générique * comme 2ème argument pour autoriser toute valeur valide sur l'échelle associée.

// globals.ts
export default {
  // monte de 5 crans sur l'échelle.
  // définit la valeur min à 3
  // et la valeur max à 8
  outer: 'mb-$spacing(5, 3, 8)',
  // descend de 2 crans sur l'échelle
  // définit la valeur minimale à 1
  // et la valeur max à 2
  label: 'mb-$spacing(-2, 1, 2)',
  // descend de 2 crans sur l'échelle
  // autorise toute valeur valide sur l'échelle
  help: 'mb-$spacing(-2,*)'
}

Remplacement des échelles par défaut de l'éditeur

Certains types d'éditeur comme scale ou color viennent avec des échelles par défaut. Cependant, nous pouvons remplacer les valeurs par défaut en fournissant une propriété scale personnalisée.

accentColor: {
  editor: "color",
  value: "blue",
  // exclut toutes les couleurs "grises"
  // de l'échelle par défaut
  scale: [
    "red",
    "orange",
    "amber",
    "yellow",
    "lime",
    "green",
    "emerald",
    "teal",
    "cyan",
    "sky",
    "blue",
    "indigo",
    "violet",
    "purple",
    "fuchsia",
    "pink",
    "rose",
  ],
},

Vous pouvez même combiner des échelles personnalisées avec les propriétés min et max pour créer des échelles entièrement nouvelles au-delà des valeurs disponibles dans les échelles par défaut de Tailwind.

scale: {
  editor: "fontSize",
  value: "base",
  scale: [
    // une taille personnalisée et une hauteur de ligne
    // personnalisée pour cette taille.
    "[11px] [line-height:1em]",

    // valeurs par défaut de Tailwind
    // dans une plage que nous trouvons sensée.
    "xs",
    "sm",
    "base",
    "lg",
    "xl",
    "2xl",
  ],
  min: "sm",
  max: "lg",
},

Il y a beaucoup plus de commentaires dans le thème @formkit/theme-starter lui-même pour vous aider dans votre travail.

Publication de votre thème

Lorsque vous avez terminé de créer votre thème, vous pouvez utiliser le script de publication inclus pour construire et publier votre thème sur npm.

Tout d'abord, assurez-vous d'avoir modifié le contenu de la clé meta de votre thème et du fichier package.json pour refléter avec précision le nom, la description, la version et les informations de l'auteur de votre thème.

Lorsque vous êtes prêt, exécutez la commande suivante dans votre terminal

#pnpm fortement recommandé
pnpm release

Cette commande construit votre thème, exécute un linter pour s'assurer que votre package.json est valide, exécute un script pour augmenter la version de votre thème (et crée automatiquement des notes de version si vous utilisez des messages de commit sémantiques), puis publie votre thème sur npm sous le nom de package que vous avez fourni.

Installer un thème tiers publié

Pour utiliser un thème tiers que vous ou quelqu'un d'autre a publié sur npm, installez-le d'abord comme une dépendance de développement dans votre projet :

pnpm add -D formkit-theme-my-theme

pnpm add -D formkit

Une fois le thème installé comme dépendance, vous pouvez construire votre thème avec la commande theme de la CLI formkit.

# résoudra à partir de votre local node_modules
npx formkit@latest theme --theme=formkit-theme-my-theme

Cette commande produira un fichier formkit.theme.(mjs|ts) dans le répertoire racine de votre projet. Pour compléter la configuration, vous devrez faire les deux choses suivantes :

• Importer la fonction rootClasses de votre thème construit dans votre fichier formkit.config
• Ajouter le fichier formkit.theme à l'array content de votre fichier 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" // <-- ajoutez votre fichier de thème
  ]
}

Personnaliser les variables d'un thème publié

Besoin de changer certaines des variables disponibles dans votre thème ? Cela peut être fait en important et en surchargeant votre thème dans un fichier intermédiaire, puis en passant ce fichier intermédiaire à la CLI formkit. Pour cet exemple, créons un fichier appelé formkit.theme.config.ts à la racine de notre projet. Dans ce fichier, nous importerons notre thème et le réexporterons en passant des surcharges de variables.

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

export default myTheme({
  // modifiez toutes les variables qui sont disponibles dans votre thème
  radius: 'rounded-full',
  spacing: '2.5',
  accentColor: 'violet'
})

Maintenant, vous pouvez utiliser la CLI formkit pour construire votre thème avec vos personnalisations appliquées.

# générera votre thème avec vos surcharges de variables
npx formkit@latest theme --theme=formkit.theme.config.ts

Installez le fichier résultant formkit.theme.(mjs|ts) en suivant les mêmes instructions que dans la section ci-dessus — en ajoutant les rootClasses à votre fichier formkit.config et en incluant le fichier formkit.theme.(mjs|ts) dans le tableau de contenu de votre fichier tailwind.config.

Soumettre votre thème à themes.formkit.com

Fier de votre thème ? Vous proposez quelque chose d'unique que les autres utilisateurs de FormKit apprécieraient d'utiliser ?

Ouvrez une pull request contre le dépôt themes.formkit.com et soumettez votre thème ! Une fois approuvé, il sera répertorié dans la galerie de thèmes et disponible pour que quiconque l'utilise dans son projet aussi facilement que les thèmes FormKit fournis par la première partie.

# installable directement par nom depuis themes.formkit.com une fois fusionné
npx formkit@latest theme --theme=my-theme

Obtenir de l'aide

Écrire un thème FormKit complet est une grande entreprise. Si vous êtes bloqué, avez besoin d'idées ou souhaitez simplement parler de la création de thèmes pour FormKit, assurez-vous de nous rejoindre dans notre communauté Discord officielle. Nous sommes là pour aider !