From e30d7925b5a2a05ec54a9e414e7e47ec10a74df3 Mon Sep 17 00:00:00 2001
From: natxocc <natxocc@gmail.com>
Date: Sat, 4 Apr 2026 19:42:16 +0200
Subject: [PATCH] Improve tags info

---
 docs/api/quick.md | 20 +++++++++++++++--
 docs/api/tags.md  | 56 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/docs/api/quick.md b/docs/api/quick.md
index a4a56f1..e6472da 100644
--- a/docs/api/quick.md
+++ b/docs/api/quick.md
@@ -2,6 +2,22 @@
 
 SigPro is a high-performance micro-framework that updates the **Real DOM** surgically. No Virtual DOM, no unnecessary re-renders, and built-in **Cleanup** (memory cleanup).
 
+<div class="text-center my-8">
+  <div class="flex justify-center gap-2 flex-wrap mb-4">
+    <span class="badge badge-primary badge-lg font-mono text-lg">$-$$</span>
+    <span class="badge badge-secondary badge-lg font-mono text-lg">$watch</span>
+    <span class="badge badge-accent badge-lg font-mono text-lg">$html</span>
+    <span class="badge badge-info badge-lg font-mono text-lg">$if</span>
+    <span class="badge badge-success badge-lg font-mono text-lg">$for</span>
+    <span class="badge badge-warning badge-lg font-mono text-lg">$router</span>
+    <span class="badge badge-error badge-lg font-mono text-lg">$mount</span>
+  </div>
+  <h1 class="text-5xl font-black bg-gradient-to-r from-primary via-secondary to-accent bg-clip-text text-transparent">
+    ⚡ All the power! ⚡
+  </h1>
+  <p class="text-xl opacity-70 mt-2">6 functions that will change the way you code</p>
+</div>
+
 ## Core Functions
 
 Explore the reactive building blocks of SigPro.
@@ -73,8 +89,8 @@ SigPro provides **PascalCase** wrappers for all standard HTML5 tags (e.g., `Div`
 
 ### Syntax Pattern
 
-<div class="mockup-code bg-base-300 text-base-content my-6">
-  <pre data-prefix=">"><code>Tag({ attributes }, [children])</code></pre>
+<div class="mockup-code bg-base-300 text-base-content">
+  <pre data-prefix=""><code>Tag({ attributes }, [children])</code></pre>
 </div>
 
 ### Special Attributes & Routing
diff --git a/docs/api/tags.md b/docs/api/tags.md
index a5db97c..1a139e8 100644
--- a/docs/api/tags.md
+++ b/docs/api/tags.md
@@ -126,6 +126,62 @@ const UserStatus = (name, online) => (
 );
 ```
 
+---
+
+## 6. Custom Tags with `$html`
+
+Create reusable components using `$html`. All reactivity auto-cleans itself.
+
+### Basic Example
+
+```javascript
+const UserCard = (props, children) => 
+  $html('div', { class: 'card p-4', 'data-id': props.id }, children);
+
+UserCard({ id: 123 }, [H3("John Doe"), P("john@example.com")]);
+```
+
+### Reactive Component (Auto-Cleaned)
+
+```javascript
+const Counter = (initial = 0) => {
+  const count = $(initial);
+  return $html('div', { class: 'flex gap-2' }, [
+    Button({ onclick: () => count(count() - 1) }, '-'),
+    Span(() => count()),
+    Button({ onclick: () => count(count() + 1) }, '+')
+  ]);
+};
+```
+
+### When Manual Cleanup is Needed
+
+Only for external resources (intervals, sockets, third-party libs):
+
+```javascript
+const Timer = () => {
+  const time = $(new Date().toLocaleTimeString());
+  const el = $html('span', {}, () => time());
+  
+  const interval = setInterval(() => time(new Date().toLocaleTimeString()), 1000);
+  el._cleanups.add(() => clearInterval(interval)); // Manual cleanup
+  
+  return el;
+};
+```
+
+### `$html` vs Tag Helpers
+
+| Use | Recommendation |
+|:---|:---|
+| Standard tags (`div`, `span`) | `Div()`, `Span()` helpers |
+| Reusable components | Function returning `$html` |
+| Dynamic tag names | `$html(tagName, props, children)` |
+
+> **Auto-cleanup**: `$html` automatically destroys watchers, events, and nested components. Only add to `_cleanups` for external resources.
+
+---
+
 | State (`online`) | Rendered HTML | Memory Management |
 | :--- | :--- | :--- |
 | **`true`** | `<div class="flex..."><span class="w-3..."></span><p class="text-bold">John</p></div>` | Watcher active |