# Créer un Outil HTML
Ce guide vous accompagne dans la création d'un outil HTML standalone pour Playlab42.
## Objectif
Créer un outil simple et autonome qui sera intégré au catalogue du portail.
**Caractéristiques d'un outil :**
- Un seul fichier HTML (tout inclus : CSS + JS)
- Utilise `lib/theme.css` pour les styles et thèmes
- Utilise `lib/dom.js` pour les utilitaires DOM
- Utile et pratique
- Style cohérent avec la plateforme (dark/light)
## Prérequis
- Connaissances de base en HTML, CSS, JavaScript
- Docker installé (`make serve` pour tester)
## Structure d'un outil
Un outil Playlab42 se compose de :
```
tools/
├── mon-outil.html # L'outil (fichier unique)
└── mon-outil.json # Métadonnées (optionnel)
```
## Étapes
### 1. Créer le fichier HTML
Créez un fichier `tools/mon-outil.html` avec la structure suivante :
```html
Mon Outil - Playlab42
```
### 2. Utiliser les variables CSS du thème
Importez `lib/theme.css` pour avoir accès aux variables de design :
```css
/* Variables disponibles */
--color-bg /* Fond principal */
--color-bg-secondary /* Fond secondaire */
--color-bg-card /* Fond des cartes */
--color-text /* Texte principal */
--color-text-muted /* Texte secondaire */
--color-accent /* Couleur d'accent */
--color-accent-hover /* Accent au survol */
--color-success /* Succès */
--color-error /* Erreur */
--color-border /* Bordures */
--space-sm/md/lg/xl /* Espacements */
--radius-sm/md/lg /* Rayons de bordure */
--transition-normal /* Transitions */
--font-family /* Police système */
--font-mono /* Police monospace */
```
Le thème (dark/light) est géré automatiquement via `lib/theme.js`.
### 3. Créer le manifest (optionnel mais recommandé)
Créez `tools/mon-outil.json` :
```json
{
"id": "mon-outil",
"name": "Mon Outil",
"description": "Description courte de l'outil",
"tags": ["utility", "dev"],
"author": "Votre nom",
"icon": "🔧",
"version": "1.0.0"
}
```
**Champs du manifest :**
| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| `id` | Oui | Identifiant unique (kebab-case) |
| `name` | Oui | Nom affiché |
| `description` | Oui | Description courte |
| `tags` | Non | Tags pour filtrage |
| `author` | Non | Auteur |
| `icon` | Non | Emoji pour la vignette |
| `version` | Non | Version de l'outil |
### 4. Régénérer le catalogue
```bash
make npm CMD="run build:catalogue"
```
### 5. Tester
```bash
make serve
# Ouvrir http://localhost:3000
```
## Exemple complet : Compteur de mots
Voici un outil simple qui compte les mots et caractères d'un texte.
### `tools/word-counter.html`
```html
Compteur de mots - Playlab42
📝 Compteur de mots
0
Mots
0
Caractères
0
Sans espaces
0
Lignes
```
### `tools/word-counter.json`
```json
{
"id": "word-counter",
"name": "Compteur de mots",
"description": "Compte les mots, caractères et lignes d'un texte",
"tags": ["utility", "text"],
"author": "Playlab42",
"icon": "📝",
"version": "1.0.0"
}
```
## Bonnes pratiques
### Structure du code
1. **Un seul fichier** : Tout le CSS et JS dans le HTML
2. **Imports** : Utilisez `lib/theme.css`, `lib/dom.js`, `lib/theme.js`
3. **Responsive** : Fonctionne sur mobile et desktop
### Style
1. **Variables CSS** : Utilisez `var(--color-bg)`, etc. depuis theme.css
2. **Support thèmes** : Les variables s'adaptent automatiquement dark/light
3. **Transitions** : Ajoutez `transition: background-color var(--transition-normal)` pour une transition fluide
4. **Cohérence** : Header avec titre, main, footer
5. **Accessibilité** : Labels, placeholders, contraste
### JavaScript
1. **Utilitaires DOM** : Utilisez `$()`, `on()`, `escapeHtml()` depuis lib/dom.js
2. **Sécurité XSS** : Toujours `escapeHtml()` sur les entrées utilisateur
3. **Commentaires** : En français
4. **Fonctions pures** : Faciles à tester
### Performance
1. **Debounce** : Pour les événements fréquents (input)
2. **Pas de boucles infinies** : Attention aux watchers
3. **Léger** : Pas de bibliothèques lourdes
## Pour aller plus loin
### Ajouter des raccourcis clavier
```javascript
document.addEventListener('keydown', (e) => {
if (e.ctrlKey && e.key === 's') {
e.preventDefault();
saveData();
}
});
```
### Sauvegarder dans localStorage
```javascript
// Sauvegarder
localStorage.setItem('mon-outil-data', JSON.stringify(data));
// Charger
const saved = localStorage.getItem('mon-outil-data');
if (saved) {
data = JSON.parse(saved);
}
```
### Charger depuis l'URL
```javascript
const params = new URLSearchParams(window.location.search);
const value = params.get('data');
if (value) {
inputEl.value = decodeURIComponent(value);
}
```
## Voir aussi
- [Architecture](architecture.md) - Vue d'ensemble
- [JSON Formatter](../../tools/json-formatter.html) - Exemple réel
- [Spec Manifests](../../openspec/specs/manifests/spec.md) - Format des manifests