Enhance documentation for performance, persistence, and state management

- Updated performance.html to include detailed explanations on unnecessary re-renders, selector patterns, and performance tips.
- Expanded persistence.html with comprehensive guidance on auto-saving state, session vs local storage, configuration examples, and best practices.
- Revamped state-management.html to cover advanced patterns, derived state, optimistic updates, state composition, and best practices for organizing state.

Author: mashrulhaque

docs-site/api-reference.html

@@ -586,6 +586,133 @@ li {
   margin-bottom: 1rem;
 }
 
+/* Lead paragraph */
+.lead {
+  font-size: 1.25rem;
+  color: var(--text-secondary);
+  margin-bottom: 2rem;
+}
+
+/* Flow Diagram */
+.flow-diagram {
+  margin: 2rem 0;
+  padding: 2rem;
+  background-color: var(--surface);
+  border-radius: 0.5rem;
+}
+
+.flow-step {
+  display: flex;
+  gap: 1.5rem;
+  margin: 1.5rem 0;
+  padding: 1.5rem;
+  background-color: var(--background);
+  border-radius: 0.5rem;
+  border: 1px solid var(--border);
+}
+
+.flow-step-number {
+  flex-shrink: 0;
+  width: 3rem;
+  height: 3rem;
+  background: linear-gradient(135deg, var(--primary), var(--primary-light));
+  color: white;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 1.5rem;
+  box-shadow: 0 4px 6px rgba(99, 102, 241, 0.2);
+}
+
+.flow-step-content {
+  flex: 1;
+}
+
+.flow-step-content h3 {
+  margin-top: 0;
+  margin-bottom: 0.5rem;
+  color: var(--primary);
+}
+
+.flow-step-content p {
+  margin-bottom: 0.5rem;
+}
+
+.flow-step-content .code-block {
+  margin-top: 1rem;
+  margin-bottom: 0;
+}
+
+.flow-step-content .alert {
+  margin-top: 1rem;
+  margin-bottom: 0;
+}
+
+.flow-arrow {
+  text-align: center;
+  font-size: 2rem;
+  color: var(--primary);
+  margin: 0.5rem 0;
+  font-weight: bold;
+}
+
+/* Principle Cards */
+.principle-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 2rem;
+  margin: 2rem 0;
+}
+
+.principle-card {
+  padding: 1.5rem;
+  border-radius: 0.5rem;
+  border: 2px solid;
+}
+
+.principle-card h3 {
+  margin-top: 0;
+  margin-bottom: 1rem;
+  font-size: 1.25rem;
+}
+
+.principle-card ul {
+  margin: 0;
+  padding-left: 1.5rem;
+}
+
+.principle-card li {
+  margin-bottom: 0.75rem;
+}
+
+.principle-do {
+  background-color: #d1fae5;
+  border-color: var(--success);
+}
+
+.principle-do h3 {
+  color: #065f46;
+}
+
+.principle-do li {
+  color: #047857;
+}
+
+.principle-dont {
+  background-color: #fee2e2;
+  border-color: var(--error);
+}
+
+.principle-dont h3 {
+  color: #991b1b;
+}
+
+.principle-dont li {
+  color: #b91c1c;
+}
+
 /* ========================================
    Scrollbar
    ======================================== */
@@ -710,6 +837,20 @@ li {
   .stat-value {
     font-size: 2rem;
   }
+
+  .flow-step {
+    flex-direction: column;
+  }
+
+  .flow-step-number {
+    width: 2.5rem;
+    height: 2.5rem;
+    font-size: 1.25rem;
+  }
+
+  .principle-cards {
+    grid-template-columns: 1fr;
+  }
 }
 
 @media (max-width: 480px) {