ORGANISATION-KA-INTERNATIONALE/oki-foundation

Fork 0

Files

T

cedric c37c9f1600

typo: replace o-k-i.net by oki-foundation.org

2026-08-10 10:33:52 +04:00

6.1 KiB

Raw Blame History

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

É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

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>

Ajoutez la correspondance FR↔EN dans PATH_PAIRS (src/lib/i18n/index.ts) pour l'hreflang et la bascule de langue.
Ajoutez l'URL dans static/sitemap.xml et, si nécessaire, dans navigation.json.
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

Créez une branche pour votre fonctionnalité :
```
git checkout -b feature/ma-fonctionnalite
```
Faites vos modifications.
Testez localement :
```
npm run dev
```

Vérifiez types, accessibilité et build :

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

Commitez vos changements :

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

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@oki-foundation.org ou ouvrez une issue sur Labola.

6.1 KiB Raw Blame History