feat/specify cardstack tags order and colour

docs/userGuide/syntax/cardstacks.md

@@ -135,6 +135,113 @@ In the example given below, a Card Stack is used to show a list of questions and
 
 The example above also illustrates how to use the `keywords` attribute to specify additional search terms for a card.
 
+### Custom Tag Order and Colors
+
+You can customize the order and colors of tags by using a `<tags>` element inside the `cardstack`:
+
+<include src="codeAndOutputSeparate.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<cardstack searchable>
+  <tags>
+    <tag name="Success" color="#28a745" />
+    <tag name="Perseverance" color="#17a2b8" />
+    <tag name="Motivation" color="#ffc107" />
+    <tag name="Hard Work" color="#dc3545" />
+    <tag name="Happiness" color="#6f42c1" />
+    <tag name="Mindset" color="#fd7e14" />
+  </tags>
+  <card header="**Winston Churchill**" tag="Success, Perseverance">
+    Success is not final, failure is not fatal: it is the courage to continue that counts
+  </card>
+  <card header="**Albert Einstein**" tag="Success, Perseverance">
+    In the middle of every difficulty lies opportunity
+  </card>
+  <card header="**Theodore Roosevelt**" tag="Motivation, Hard Work">
+    Do what you can, with what you have, where you are
+  </card>
+  <card header="**Steve Jobs**" tag="Happiness, Mindset">
+    Your time is limited, so don't waste it living someone else's life
+  </card>
+</cardstack>
+</variable>
+<variable name="output">
+<cardstack searchable>
+  <tags>
+    <tag name="Success" color="#28a745" />
+    <tag name="Perseverance" color="#17a2b8" />
+    <tag name="Motivation" color="#ffc107" />
+    <tag name="Hard Work" color="#dc3545" />
+    <tag name="Happiness" color="#6f42c1" />
+    <tag name="Mindset" color="#fd7e14" />
+  </tags>
+  <card header="**Winston Churchill**" tag="Success, Perseverance">
+    Success is not final, failure is not fatal: it is the courage to continue that counts
+  </card>
+  <card header="**Albert Einstein**" tag="Success, Perseverance">
+    In the middle of every difficulty lies opportunity
+  </card>
+  <card header="**Theodore Roosevelt**" tag="Motivation, Hard Work">
+    Do what you can, with what you have, where you are
+  </card>
+  <card header="**Steve Jobs**" tag="Happiness, Mindset">
+    Your time is limited, so don't waste it living someone else's life
+  </card>
+</cardstack>
+</variable>
+</include>
+
+You can also use Bootstrap color names instead of hex colors:
+
+<include src="codeAndOutputSeparate.md" boilerplate >
+<variable name="highlightStyle">html</variable>
+<variable name="code">
+<cardstack searchable>
+  <tags>
+    <tag name="Success" color="success" />
+    <tag name="Perseverance" color="info" />
+    <tag name="Motivation" color="warning" />
+    <tag name="Hard Work" color="danger" />
+  </tags>
+  <card header="**Winston Churchill**" tag="Success, Perseverance">
+    Success is not final, failure is not fatal: it is the courage to continue that counts
+  </card>
+  <card header="**Albert Einstein**" tag="Success, Perseverance">
+    In the middle of every difficulty lies opportunity
+  </card>
+  <card header="**Theodore Roosevelt**" tag="Motivation, Hard Work">
+    Do what you can, with what you have, where you are
+  </card>
+</cardstack>
+</variable>
+<variable name="output">
+<cardstack searchable>
+  <tags>
+    <tag name="Success" color="success" />
+    <tag name="Perseverance" color="info" />
+    <tag name="Motivation" color="warning" />
+    <tag name="Hard Work" color="danger" />
+  </tags>
+  <card header="**Winston Churchill**" tag="Success, Perseverance">
+    Success is not final, failure is not fatal: it is the courage to continue that counts
+  </card>
+  <card header="**Albert Einstein**" tag="Success, Perseverance">
+    In the middle of every difficulty lies opportunity
+  </card>
+  <card header="**Theodore Roosevelt**" tag="Motivation, Hard Work">
+    Do what you can, with what you have, where you are
+  </card>
+</cardstack>
+</variable>
+</include>
+
+The `<tags>` element allows you to:
+- Specify the order in which tags appear in the filter badges
+- Assign custom colors to each tag using either:
+  - Hex format (e.g., `#28a745`)
+  - Bootstrap color names (e.g., `success`, `danger`, `primary`, `warning`, `info`, `secondary`, `light`, `dark`)
+- Any tags used in cards but not defined in `<tags>` will appear after the defined tags with default colors
+
 ****Options****
 
 `cardstack`:
@@ -143,6 +250,15 @@ Name | Type | Default | Description
 blocks | `String` | `2` | Number of `card` columns per row.<br> Supports: `1`, `2`, `3`, `4`, `6`
 searchable | `Boolean` | `false` | Whether the card stack is searchable.
 
+`tags` (optional):
+A container element inside `cardstack` to define tag ordering and colors.
+
+`tag` (inside `tags` element):
+Name | Type | Default | Description
+--- | --- | --- | ---
+name | `String` | (required) | The name of the tag (must match tags used in cards).
+color | `String` | (auto) | Custom color for the tag.<br>Supports hex format (e.g., `#28a745`) or Bootstrap color names (e.g., `success`, `danger`, `primary`).<br>If not specified, uses default Bootstrap color scheme.
+
 `card`:
 Name | Type | Default | Description
 --- | --- | --- | ---