docs(frontend): autonomous architectural standardization for frontend docs

frontend/qwik/readme.md

@@ -29,19 +29,19 @@ last_updated: 2026-03-22
 
 ## 🚀 I. Basics & Popular
 
-## 1. Passing Closures as Props
+### 1. Passing Closures as Props
 **Context:** Component Props
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```tsx
 const Component = ({ onClick }) => <button onClick={onClick}>Click</button>;
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Closures cannot be serialized natively by Qwik, breaking resumability and throwing an error.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```tsx
 const Component = component$(({ onClick$ }: { onClick$: PropFunction<() => void> }) => (
   <button onClick$={onClick$}>Click</button>
 ));
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use the `$` suffix (`onClick$`) to mark the prop as a `PropFunction`, allowing Qwik to serialize the closure and load it lazily.

frontend/react/performance.md

@@ -1,14 +1,10 @@
 ---
 description: Vibe coding guidelines and architectural constraints for React Performance within the frontend domain.
-tags: [react, performance, use, react-compiler, best-practices, architecture, clean-code]
-topic: React Performance
-complexity: Architect
-last_evolution: 2026-03-22
-vibe_coding_ready: true
 technology: React
 domain: frontend
 level: Senior/Architect
 version: "19+"
+tags: [react, performance, use, react-compiler, best-practices, architecture, clean-code]
 ai_role: Senior React Performance Expert
 last_updated: 2026-03-22
 ---

frontend/react/readme.md

@@ -1,14 +1,10 @@
 ---
 description: Vibe coding guidelines and architectural constraints for React within the frontend domain.
-tags: [react, best-practices, architecture, clean-code, scalable-code, modern-react, server-components]
-topic: React
-complexity: Architect
-last_evolution: 2026-03-22
-vibe_coding_ready: true
 technology: React
 domain: frontend
 level: Senior/Architect
 version: "19+"
+tags: [react, best-practices, architecture, clean-code, scalable-code, modern-react, server-components]
 ai_role: Senior React Expert
 last_updated: 2026-03-22
 ---

frontend/solidjs/readme.md

@@ -29,17 +29,17 @@ last_updated: 2026-03-22
 
 ## 🚀 I. Basics & Popular
 
-## 1. Using JSX Map for Lists
+### 1. Using JSX Map for Lists
 **Context:** Rendering Lists
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```tsx
 return <ul>{items().map(item => <li>{item.name}</li>)}</ul>;
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Using `.map` creates the DOM nodes once and does not react to array changes optimally, leading to unnecessary re-renders or lost reactivity.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```tsx
 return <ul><For each={items()}>{item => <li>{item.name}</li>}</For></ul>;
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use the `<For>` component. It caches DOM elements and handles granular updates when the array changes.

frontend/typescript/readme.md

@@ -15,144 +15,144 @@ last_updated: 2026-03-22
 
 ## 🚀 I. Fundamentals (1-10)
 
-## ⚡ 1. `any` vs `unknown`
+### ⚡ 1. `any` vs `unknown`
 **Context:** Handling data of an uncertain type. `any` disables all type-checking, while `unknown` forces safety.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 function process(data: any) {
     console.log(data.name); // No error, but might crash at runtime
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 `any` is a "get out of jail free" card that propagates through the codebase, effectively turning off TypeScript's benefits and hiding potential runtime exceptions.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 function process(data: unknown) {
     if (data && typeof data === 'object' && 'name' in data) {
         console.log((data as { name: string }).name);
     }
 }
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use `unknown` for values whose type is not yet determined. It requires a type check or assertion before usage, ensuring the developer acknowledges the data's structure.
 
 ---
 
-## ⚡ 2. `null` vs `undefined` in APIs
+### ⚡ 2. `null` vs `undefined` in APIs
 **Context:** Distinguishing between "value not provided" and "value is empty."
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 interface UserResponse {
     bio: string | null | undefined;
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Using both creates ambiguity. In JSON, `undefined` properties are often stripped, while `null` is preserved. Mixing them increases complexity in conditional checks.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 interface UserResponse {
     bio?: string | null; // Optional if missing, null if explicitly empty
 }
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Standardize: use `undefined` (optional properties) for missing keys and `null` for intentional absence of value. Avoid using both for the same field unless strictly required by a legacy API.
 
 ---
 
-## ⚡ 3. `Array<T>` vs `T[]`
+### ⚡ 3. `Array<T>` vs `T[]`
 **Context:** Visual consistency in array declarations.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 const users: Array<User> = [];
 const complex: Array<string | number> = [];
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 `Array<T>` is more verbose and can be confused with other generic types. It is harder to scan in complex signatures.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 const users: User[] = [];
 const complex: (string | number)[] = [];
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Prefer the shorthand `T[]`. It is idiomatic, more readable, and clearly distinguishes arrays from other generic containers like `Record` or `Promise`.
 
 ---
 
-## ⚡ 4. `interface` vs `type`
+### ⚡ 4. `interface` vs `type`
 **Context:** Defining object structures and aliases.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 interface Point { x: number; y: number; }
 interface ID extends string {} // Error: Interface can only extend objects
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 `interface` is limited to objects and allows "declaration merging," which can lead to accidental property overrides in global scopes.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 type Point = { x: number; y: number; };
 type ID = string;
 type Union = 'A' | 'B';
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use `type` for almost everything (unions, primitives, intersections). Use `interface` only when you specifically need declaration merging or for public library APIs where consumers might need to extend types.
 
 ---
 
-## ⚡ 5. Function Overloads vs Union Types
+### ⚡ 5. Function Overloads vs Union Types
 **Context:** Handling functions with different input/output combinations.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 function format(input: string): string;
 function format(input: number): string;
 function format(input: any): string {
     return String(input);
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Overloads are verbose and can be harder to implement correctly. They often require `any` or complex type-casting in the implementation body.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 function format(input: string | number): string {
     return String(input);
 }
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Prefer Union types when the implementation logic is identical for all types. Reserve overloads only for cases where the return type strictly depends on the input type and cannot be expressed via generics.
 
 ---
 
-## 🎯 6. Global Scope Pollution (Legacy Namespaces)
+### 🎯 6. Global Scope Pollution (Legacy Namespaces)
 **Context:** Organizing code in the ES Module era.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 namespace Utils {
     export const log = (msg: string) => console.log(msg);
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Namespaces are a legacy TypeScript feature. They don't play well with modern bundlers (Tree Shaking), are harder to test, and can lead to naming collisions in the global scope.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 // utils.ts
 export const log = (msg: string) => console.log(msg);
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use ES Modules (`export`/`import`). They are the industry standard, supported by all modern environments, and allow for better static analysis.
 
 ---
 
-## ⚡ 7. `enum` vs `const object`
+### ⚡ 7. `enum` vs `const object`
 **Context:** Grouping related constants.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 enum Status {
     Active,
     Inactive
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Enums generate extra runtime code and have "reverse mapping" behavior that can lead to bugs (e.g., `Status[0]` returns "Active"). They also don't align with "TypeScript as a type-only layer."
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 const STATUS = {
     ACTIVE: 'active',
@@ -161,43 +161,43 @@ const STATUS = {
 
 type Status = typeof STATUS[keyof typeof STATUS];
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use `const` objects with `as const` and a derived union type. This is more predictable, emits cleaner code, and is easier to iterate over.
 
 ---
 
-## ⚡ 8. Explicit `any` in Parameters
+### ⚡ 8. Explicit `any` in Parameters
 **Context:** Enforcing strict type safety.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 function save(data) { // Implicit any if strict: false
     db.push(data);
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Implicit `any` bypasses the compiler's ability to verify data flow, leading to "undefined is not a function" errors that TypeScript was designed to prevent.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 function save(data: UserData) {
     db.push(data);
 }
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Enable `noImplicitAny: true` in `tsconfig.json`. Always define specific types or use `unknown` if the type is truly dynamic.
 
 ---
 
-## ⚡ 9. Manual Type Guards vs Type Predicates
+### ⚡ 9. Manual Type Guards vs Type Predicates
 **Context:** Narrowing types inside conditional blocks.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 if (typeof input === 'object' && input !== null && 'admin' in input) {
     const isAdmin = (input as any).admin;
 }
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Repeating complex checks is error-prone and requires manual casting (`as any`) which breaks safety.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 function isAdmin(user: unknown): user is Admin {
     return !!user && typeof user === 'object' && 'admin' in user;
@@ -207,24 +207,24 @@ if (isAdmin(input)) {
     console.log(input.admin); // input is automatically narrowed to Admin
 }
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use Type Predicates (`arg is Type`) to create reusable, safe narrowing functions.
 
 ---
 
-## ⚡ 10. Triple-Slash Directives
+### ⚡ 10. Triple-Slash Directives
 **Context:** Referencing types or files.
-### ❌ Bad Practice
+#### ❌ Bad Practice
 ```typescript
 /// <reference path="./types.d.ts" />
 ```
-### ⚠️ Problem
+#### ⚠️ Problem
 Triple-slash directives are legacy syntax. They make dependencies implicit and can lead to compilation order issues.
-### ✅ Best Practice
+#### ✅ Best Practice
 ```typescript
 import { MyType } from './types';
 ```
-### 🚀 Solution
+#### 🚀 Solution
 Use standard ES `import` statements. Manage global types via `tsconfig.json` `types` array if necessary.
 
 ---