ORGANISATION-KA-INTERNATIONALE/oki-foundation
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs+fix: nettoyage post-migration et conformité svelte-autofixer

Browse Source 
- CONTRIBUTING.md et SEO.md réécrits pour la structure SvelteKit
- README : section documents de référence (charte, recette, AGENTS.md, guides Svelte 5)
- Liens internes via resolve()/asset() de $app/paths, externes en rel="external"
- Seo.svelte : JSON-LD construits dans le script (</script> échappé)
- Titres de sections : {' '} remplacé par &#32;
- Renommage svelte_core_bestpractices.md
- Passe svelte-autofixer : 0 issue restante hors {@html} first-party assumés
This commit is contained in:
sucupira
2026-07-21 08:41:55 -04:00
parent d0d80a105e
commit 30858926fa
28 changed files with 217 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+65 -100
View File
@@ -2,11 +2,15 @@
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/_data/i18n/fr/services.json` (et la version `en/`) :
Éditez `src/lib/i18n/fr/services.json` (et `en/`) :
```json
{
@@ -18,122 +22,85 @@ Merci de votre intérêt pour contribuer au site de l'ORGANISATION KA INTERNATIO
}
```
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/_data/i18n/fr/projects.json` (et la version `en/`) :
```json
{
"name": "NOM.PROJET",
"icon": "📱",
"domain": "nom.projet",
"description": "Description du projet",
"url": "https://nom.projet/"
}
```
É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
Pour les logos, privilégiez une image locale dans `src/assets/images/` et utilisez le filtre `| cdn` dans les templates. Les URLs distantes fonctionnent mais ne passent pas par le CDN.
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/_data/i18n/fr/values.json` (et la version `en/`) :
```json
{
"icon": "🌟",
"title": "Titre",
"description": "Description de la 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/_data/i18n/fr/navigation.json` (et la version `en/`) :
Éditez `src/lib/i18n/fr/navigation.json` (et `en/`) :
```json
{
"text": "Texte du lien",
"url": "#section",
"external": false
}
{ "text": "Texte du lien", "url": "/#ancre", "external": false }
```
Pour un lien externe, mettez `"external": true`.
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 par section dans `src/_data/i18n/fr/contact.json` (et la version `en/`). L'icône affichée est déterminée automatiquement à partir du texte du lien (`whatsapp`, `telegram`, `discord`, `labola`, `kontak`/`mail`).
```json
{
"title": "💬 Communauté",
"links": [
{ "text": "Discord", "url": "https://discord.gg/DPvUCA8dD" }
]
}
```
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
Les styles sont dans `src/assets/css/styles.css`.
### Variables CSS principales
```css
--or-oki: #E8A625;
--noir-oki: #000000;
--vert-oki: #00A854;
--rouge-oki: #ED1C4C;
--blanc-creme: #F7F7F2;
--noir-profond: #1A1A1A;
--gris-sombre: #2A2A2A;
--or-clair: #F5BD4F;
--vert-clair: #00C569;
--rouge-clair: #FF2D5F;
```
- **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 un fichier `.njk` dans `src/` :
1. Créez `src/routes/ma-page/+page.svelte` (et sa contrepartie `src/routes/en/my-page/+page.svelte` si bilingue) :
```njk
---
layout: layouts/base.njk
title: Titre de la page
description: Description pour le SEO
---
```svelte
<script lang="ts">
import Seo from '$lib/components/Seo.svelte';
import { getBundle } from '$lib/i18n';
<section>
<h1>{{ title }}</h1>
<p>Contenu de votre page</p>
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 le lien dans `src/_data/i18n/fr/navigation.json` (et `en/`) si nécessaire.
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`.
3. Mettez à jour `src/sitemap.xml`.
## Modifier un composant
4. Reconstruisez le site : `npm run build`.
- Sections de l'accueil : `src/lib/components/sections/`
- Layout : `Nav.svelte`, `Footer.svelte`, `Seo.svelte`
- Motion : `src/lib/components/motion/` (KineticText, ScrollProgressBar)
- Icônes : sprite `static/icons.svg` (set OKI, charte §4) et `src/lib/components/icons/BrandIcon.svelte` (logos de marques)
## Modifier un partial
Après toute modification d'un composant, passez l'autofixer (voir `svelte-5_code_writer.md`) :
Les partials sont dans `src/_includes/partials/` :
- `nav.njk` - Navigation
- `hero.njk` - Section hero (accueil)
- `services.njk` - Services hébergés
- `projects.njk` - Projets web
- `mission.njk` - Mission et valeurs
- `hosting.njk` - Services d'hébergement
- `support.njk` - Section dons
- `clients.njk` - Clients / organisations ayant fait confiance
- `partners.njk` - Partenaires
- `faq.njk` - Questions fréquentes
- `engagement.njk` - Appels à l'action
- `contact.njk` - Informations de contact
- `footer.njk` - Pied de page
```bash
npx @sveltejs/mcp svelte-autofixer ./src/lib/components/sections/MonComposant.svelte
```
## Workflow de développement
@@ -146,12 +113,12 @@ Les partials sont dans `src/_includes/partials/` :
3. Testez localement :
```bash
npm start
npm run dev
```
4. Buildez pour vérifier :
4. Vérifiez types, accessibilité et build :
```bash
npm run build
npm run check && npm run build && npm run preview
```
5. Commitez vos changements :
@@ -167,24 +134,22 @@ Les partials sont dans `src/_includes/partials/` :
## Standards de code
### HTML/Nunjucks
- Indentation : 4 espaces
- Toujours fermer les balises
- Attributs entre guillemets doubles
### 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 : 4 espaces
- Utiliser les variables CSS quand possible
- Mobile-first pour le responsive
- Indentation : tabulations (convention du projet)
- Variables des tokens quand possible, mobile-first
- Angles nets : `border-radius` ≤ `var(--radius-md)` (6 px)
### JavaScript
- Indentation : 4 espaces
- Vanilla JS (pas de framework)
- Commentaires en français
- Gestion des erreurs
### 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 scripts inline sans ajuster la CSP dans `src/.htaccess`.
- 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 ?