From 83b5ee5bd613bfdd6e3ec67f20aabd8c516c4ce5 Mon Sep 17 00:00:00 2001
From: Matteo Bruni <176620+matteobruni@users.noreply.github.com>
Date: Wed, 8 Apr 2026 21:10:23 +0200
Subject: [PATCH] docs: updated docs

---
 markdown/Options.md                   |  3 ++-
 markdown/Options/Particles.md         |  8 ++++----
 markdown/Options/Particles/Palette.md | 23 ++++++++++++++++++++++-
 markdown/Pages/index.md               |  4 ++--
 markdown/Plugins.md                   |  2 +-
 5 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/markdown/Options.md b/markdown/Options.md
index aa74f86462c..fcafdfa2093 100644
--- a/markdown/Options.md
+++ b/markdown/Options.md
@@ -121,7 +121,8 @@ Use it to choose where to start, then jump to the detailed guides for each optio
 ## Recommended starting sources
 
 - Config objects: <https://github.com/tsparticles/tsparticles/blob/main/utils/configs/README.md>
-- Official presets and palettes: <https://github.com/tsparticles/presets>
+- Official presets: <https://github.com/tsparticles/presets>
+- Official palettes: <https://github.com/tsparticles/palettes>
 - Main getting-started guide: [Pages/index](./Pages/index.md)
 
 ## Common pitfalls
diff --git a/markdown/Options/Particles.md b/markdown/Options/Particles.md
index ededccb2e26..11c46dd7ed8 100644
--- a/markdown/Options/Particles.md
+++ b/markdown/Options/Particles.md
@@ -102,9 +102,9 @@ Particle groups let you define subsets of particles with different configs appli
 
 When a palette is found, tsParticles imports these defaults:
 
-- `fill`: enabled/disabled according to palette settings
-- `fill.color.value`: palette color list when fill mode is enabled
-- `stroke`: one stroke per palette color when fill mode is disabled
+- `paint.fill`: imported from palette `colors.*.fill`
+- `paint.stroke`: imported from palette `colors.*.stroke`
+- `paint`: becomes an array when the palette declares multiple color variants
 - `blend`: enabled with the palette blend mode
 
 ```json
@@ -118,7 +118,7 @@ When a palette is found, tsParticles imports these defaults:
 }
 ```
 
-If you set `fill`, `stroke`, or `blend` explicitly after `palette`, those values override imported defaults.
+If you set `paint.fill`, `paint.stroke`, or `blend` explicitly after `palette`, those values override imported defaults.
 
 ## reduceDuplicates
 
diff --git a/markdown/Options/Particles/Palette.md b/markdown/Options/Particles/Palette.md
index 08964481446..dc63b453959 100644
--- a/markdown/Options/Particles/Palette.md
+++ b/markdown/Options/Particles/Palette.md
@@ -12,10 +12,31 @@ When a matching palette is registered, the engine imports particle defaults:
 
 - `paint.fill.enable`: copied from the palette settings
 - `paint.fill.color.value`: set to palette colors when fill is enabled
-- `paint.stroke`: generated from palette colors when fill is disabled
+- `paint.stroke`: imported from palette stroke settings when present
+- `paint`: can be a single object or an array when the palette defines multiple variants
 - `blend.enable`: set to `true`
 - `blend.mode`: copied from palette blend mode
 
+## Palette data format (for custom palette authors)
+
+Registered palettes use the `IPalette` structure:
+
+```ts
+{
+  name: "My Palette",
+  background: "#0b1020",
+  blendMode: "screen",
+  colors: {
+    fill: {
+      enable: true,
+      value: ["#6ee7ff", "#8b5cf6", "#f472b6"],
+    },
+  },
+}
+```
+
+`colors` can also be an array of variants mixing `fill` and/or `stroke` blocks.
+
 ## Example
 
 ```json
diff --git a/markdown/Pages/index.md b/markdown/Pages/index.md
index 0c942001bc9..412764c9fe9 100644
--- a/markdown/Pages/index.md
+++ b/markdown/Pages/index.md
@@ -111,8 +111,8 @@ Main preset catalog:
 
 Use palettes when you already have the behavior you want and only need a reusable color direction.
 
-- Repository directory: <https://github.com/tsparticles/presets/tree/main/palettes>
-- Palette-based demos: <https://particles.js.org/samples/presets/>
+- Repository directory: <https://github.com/tsparticles/palettes/tree/main/palettes>
+- Palette-based demos: <https://particles.js.org/samples/palettes/>
 
 ## Bundle choice
 
diff --git a/markdown/Plugins.md b/markdown/Plugins.md
index 95f015f7081..93a63f20b25 100644
--- a/markdown/Plugins.md
+++ b/markdown/Plugins.md
@@ -127,7 +127,7 @@ Preset usage:
 ## Related resources
 
 - Official presets: <https://github.com/tsparticles/presets>
-- Official palettes: <https://github.com/tsparticles/presets/tree/main/palettes>
+- Official palettes: <https://github.com/tsparticles/palettes/tree/main/palettes>
 - Demo configs: <https://github.com/tsparticles/tsparticles/blob/main/utils/configs/README.md>
 - Root options: [Options](./Options.md)
 - Docs introduction: [Pages/index](./Pages/index.md)