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/) :

{
  "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 :

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/) :

{ "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) :

<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) :

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

Workflow de développement

1. Créez une branche pour votre fonctionnalité :

   git checkout -b feature/ma-fonctionnalite
   

2. Faites vos modifications.

3. Testez localement :

   npm run dev
   

4. Vérifiez types, accessibilité et build :

   npm run check && npm run build && npm run preview
   

5. Commitez vos changements :

   git add .
   git commit -m "Description de vos changements"
   

6. Poussez et créez une merge request :

   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.