oki-foundation/CONTRIBUTING.md

# Guide de contribution

Merci de votre intérêt pour contribuer au site de l'ORGANISATION KA INTERNATIONALE !

Le site est une application **SvelteKit + Svelte 5 (runes) + TypeScript**, entièrement pré-rendue en statique. Avant de contribuer, lisez `charte-oki-design-system.md` (marque) et `svelte_core_bestpractices.md` (conventions Svelte 5).

## Ajouter du contenu

Le contenu éditorial vit dans les bundles i18n : `src/lib/i18n/fr/*.json` et `src/lib/i18n/en/*.json` — **toujours modifier les deux locales**.

### Ajouter un service hébergé

Éditez `src/lib/i18n/fr/services.json` (et `en/`) :

```json
{
  "name": "NOM_DU_SERVICE",
  "platform": "Nom de la plateforme",
  "description": "Description du service",
  "url": "https://service.o-k-i.net/",
  "linkText": "Accéder à SERVICE"
}
```

Le service apparaîtra automatiquement dans la grille de fallback du village (`HostingVillage.svelte`). Pour qu'il ait aussi son bâtiment dans la scène SVG, voir « Modifier un composant ».

### Ajouter un projet web

Éditez `src/lib/i18n/fr/projects.json` (et `en/`). Le champ `icon` attend un emoji legacy qui sera remplacé au rendu par un picto du sprite — voir le mapping dans `src/lib/components/sections/pictos.ts` et choisissez-en un qui y figure.

### Ajouter un client ou partenaire

Placez le logo dans `src/lib/assets/images/` (et `clients/` pour les clients), puis importez-le dans le composant de section concerné via vite-imagetools :

```ts
import logo from '$lib/assets/images/mon-logo.png?format=avif;webp;png&w=320;640&as=picture';
```

et affichez-le avec `<ResponsiveImage picture={logo} alt="…" />`. Ne jamais référencer une image distante : tout asset est self-hébergé (doctrine souveraineté + CSP).

### Ajouter une valeur

Éditez `src/lib/i18n/fr/values.json` (et `en/`). Le champ `icon` suit le même mapping que les projets (`pictos.ts`).

### Modifier la navigation

Éditez `src/lib/i18n/fr/navigation.json` (et `en/`) :

```json
{ "text": "Texte du lien", "url": "/#ancre", "external": false }
```

Pour un lien externe, mettez `"external": true`. Les URLs de la version EN doivent pointer sous `/en/`.

### Modifier les informations de contact

Les liens de contact sont regroupés dans `src/lib/i18n/fr/contact.json` (et `en/`). L'icône de chaque lien est déduite de son libellé (`whatsapp`, `telegram`, `discord`, `labola`, `kontak`/`mail`). Les emojis en tête des titres de groupes sont convertis en pictos du sprite (`pictos.ts`).

## Modifier les styles

- **Tokens (couleurs, typo, espacements, motion)** : `src/lib/styles/oki-tokens.css` — ne jamais recopier une valeur de la charte à la main, utiliser les variables.
- **Primitives partagées** (boutons, cartes, tags, flag-bar, gate reduced-motion) : `src/lib/styles/base.css`.
- **Styles d'une section** : dans le `<style>` scopé de son composant (`src/lib/components/sections/`).
- Durées et courbes d'animation : toujours via les tokens (`--dur-tanbou`, `--ease-ka`…), jamais en dur. On n'anime que `transform` et `opacity`.
- Le thème clair est géré par surcharge des tokens (`html.light-theme`) — ne pas écrire de sélecteur `html.light-theme` par composant.

## Créer une nouvelle page

1. Créez `src/routes/ma-page/+page.svelte` (et sa contrepartie `src/routes/en/my-page/+page.svelte` si bilingue) :

```svelte
<script lang="ts">
	import Seo from '$lib/components/Seo.svelte';
	import { getBundle } from '$lib/i18n';

	const t = getBundle('fr');
</script>

<Seo title="Titre de la page" description="Description pour le SEO" path="/ma-page/" locale="fr" />

<section class="section">
	<div class="container">
		<h1>Titre de la page</h1>
	</div>
</section>
```

2. Ajoutez la correspondance FR↔EN dans `PATH_PAIRS` (`src/lib/i18n/index.ts`) pour l'hreflang et la bascule de langue.
3. Ajoutez l'URL dans `static/sitemap.xml` et, si nécessaire, dans `navigation.json`.
4. Vérifiez : `npm run check && npm run build`.

## Modifier un composant

- Sections de l'accueil : `src/lib/components/sections/`
- Layout : `Nav.svelte`, `Footer.svelte`, `Seo.svelte`
- Motion : `src/lib/components/motion/` (KineticText, ScrollProgressBar)
- Icônes : `@lucide/svelte` via `src/lib/components/icons/Icon.svelte` (mapping sémantique dans `lucide-map.ts`) et `src/lib/components/icons/BrandIcon.svelte` (logos de marques non disponibles dans Lucide)

Après toute modification d'un composant, passez l'autofixer (voir `svelte-5_code_writer.md`) :

```bash
npx @sveltejs/mcp svelte-autofixer ./src/lib/components/sections/MonComposant.svelte
```

## Workflow de développement

1. Créez une branche pour votre fonctionnalité :
   ```bash
   git checkout -b feature/ma-fonctionnalite
   ```

2. Faites vos modifications.

3. Testez localement :
   ```bash
   npm run dev
   ```

4. Vérifiez types, accessibilité et build :
   ```bash
   npm run check && npm run build && npm run preview
   ```

5. Commitez vos changements :
   ```bash
   git add .
   git commit -m "Description de vos changements"
   ```

6. Poussez et créez une merge request :
   ```bash
   git push origin feature/ma-fonctionnalite
   ```

## Standards de code

### Svelte / TypeScript
- Svelte 5 runes uniquement (`$state`, `$derived`, `$props`…) — voir `svelte_core_bestpractices.md`
- TypeScript strict, props typées
- `onclick={...}` (jamais `on:click`), blocs `{#each}` à clé unique
- `svelte-autofixer` propre sur tout composant modifié, `npm run check` à zéro warning

### CSS
- Indentation : tabulations (convention du projet)
- Variables des tokens quand possible, mobile-first
- Angles nets : `border-radius` ≤ `var(--radius-md)` (6 px)

### JavaScript (fichiers statiques)
- Vanilla JS, commentaires en français, aucun script inline dans le HTML (CSP `script-src 'self'`)

### Sécurité
- Ne pas ajouter de ressource externe (font, CDN, script) : tout se self-héberge. Si une exception est indispensable, ajuster la CSP dans `static/.htaccess` **et** `static/_headers`.
- Conserver les headers de sécurité lors d'une modification du serveur.

## Questions ?

Contactez-nous à kontak@o-k-i.net ou ouvrez une issue sur [Labola](https://labola.o-k-i.net/ORGANISATION-KA-INTERNATIONALE/o-k-i.net).