();
+
+for (const entry of registry) {
+ nameMap.set(entry.name, entry);
+ for (const alias of entry.altnames) {
+ aliasMap.set(alias.toLowerCase(), entry.name);
+ }
+}
+
+/**
+ * Get the devicon class name for a tag.
+ *
+ * @param name - Tag name (case-insensitive, aliases supported)
+ * @param colored - Whether to use brand colours (default: true)
+ * @returns Class string like "devicon-react-original colored" or null if not found
+ *
+ * @example
+ * getDeviconClassName("react") // "devicon-react-original colored"
+ * getDeviconClassName("js") // "devicon-javascript-plain colored"
+ * getDeviconClassName("react", false) // "devicon-react-original" (monotone)
+ * getDeviconClassName("unknown") // null
+ */
+export function getDeviconClassName(
+ name: string,
+ colored = true,
+): string | null {
+ const normalised = name.toLowerCase().trim();
+
+ // Try direct name lookup first, then alias lookup
+ const resolvedName = nameMap.has(normalised)
+ ? normalised
+ : aliasMap.get(normalised);
+
+ if (!resolvedName) return null;
+
+ const entry = nameMap.get(resolvedName);
+ if (!entry) return null;
+
+ const fontStyles = entry.versions.font;
+ if (!fontStyles || fontStyles.length === 0) return null;
+
+ // Select style by preference order, fallback to first available
+ const style =
+ STYLE_PREFERENCE.find((s) => fontStyles.includes(s)) ?? fontStyles[0];
+
+ return `devicon-${resolvedName}-${style}${colored ? " colored" : ""}`;
+}
diff --git a/x_docs/mine/2025-12-14-eval-auth-ui-customise.md b/x_docs/DONE/2025-12-14-eval-auth-ui-customise.md
similarity index 100%
rename from x_docs/mine/2025-12-14-eval-auth-ui-customise.md
rename to x_docs/DONE/2025-12-14-eval-auth-ui-customise.md
diff --git a/x_docs/mine/2025-12-17-make-mobile-nav.md b/x_docs/DONE/2025-12-17-make-mobile-nav.md
similarity index 100%
rename from x_docs/mine/2025-12-17-make-mobile-nav.md
rename to x_docs/DONE/2025-12-17-make-mobile-nav.md
diff --git a/x_docs/mine/2025-12-17-page-spacing.md b/x_docs/DONE/2025-12-17-page-spacing.md
similarity index 100%
rename from x_docs/mine/2025-12-17-page-spacing.md
rename to x_docs/DONE/2025-12-17-page-spacing.md
diff --git a/x_docs/mine/2025-12-25-layout-refactor.md b/x_docs/DONE/2025-12-25-layout-refactor.md
similarity index 100%
rename from x_docs/mine/2025-12-25-layout-refactor.md
rename to x_docs/DONE/2025-12-25-layout-refactor.md
diff --git a/x_docs/mine/2026-01-01-right-sidebar/current.jpg b/x_docs/DONE/2026-01-01-right-sidebar/current.jpg
similarity index 100%
rename from x_docs/mine/2026-01-01-right-sidebar/current.jpg
rename to x_docs/DONE/2026-01-01-right-sidebar/current.jpg
diff --git a/x_docs/DONE/2026-01-01-right-sidebar/devicon-readme.md b/x_docs/DONE/2026-01-01-right-sidebar/devicon-readme.md
new file mode 100644
index 0000000..e070409
--- /dev/null
+++ b/x_docs/DONE/2026-01-01-right-sidebar/devicon-readme.md
@@ -0,0 +1,319 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+TL;DR
+
+```html
+
+Table of Contents
+
+ About the Project Getting Started Requesting Icon Contributing Discord Community develop vs masterStale Pull Requests Building Devicon
+
+About the Project
+
+ Devicon aims to gather all logos representing development languages and tools.
+ Each icon comes in several versions: font/SVG, original/plain/line, colored/not colored, wordmark/no wordmark.
+ Devicon has 150+ icons. And it's growing!
+
+ See the devicon.json or our website for complete and up to date reference of
+ all available icons.
+
+
+
+ Thanks to all our contributors and the IcoMoon app . Devicon would not be possible without you.
+
+
+
+ All product names, logos, and brands are property of their respective owners. All company, product and service
+ names used in this website are for identification purposes only. Use of these names, logos, and brands does not
+ imply endorsement. Usage of these logos should be done according to the company/brand/service's brand policy.
+
+
+Getting Started
+
+ For a super fast setup, go check devicon.dev .raw SVG icons, our Devicon font (which is
+ also available via CDN ), or by building Devicon yourself.
+
+
+Use the devicon font (recommended)
+
+ You can install devicon as a dependency to your project either with npm or yarn:
+
+
+```bash
+npm install --save devicon
+yarn add devicon
+```
+
+
+ If you don't want to use a package manager, you can also download
+ and include devicon.min.css next to the font files to your project.
+ See devicon.dev for details about how to add Devicon to your project via
+ a CDN.
+
+
+ After setting up you just have to include the stylesheet in your header
+ to get started:
+
+
+```html
+Start using icons with <i>-tag:
+
+```html
+
+
+ An alternate way to use devicon is by copy/pasting the raw SVG code
+ to your project.
+
+
+
+```html
+
+You can also use the img tag and reference an SVG directly from the repository:
+
+```html
+Requesting an icon
+
+ When you want to request an icon please feel free to create an issue. Check out our Wiki for more information.
+
+
+Contributing
+
+ We are happy with every contribution, whether it's new icons, features, or maintainers. Please have a look at our Wiki to see how you can contribute to this project.
+
+
+
+
+We have a Discord community for Devicons. You can easily request icons, discuss, and have a good time talking with the community members! Join the official Discord Server here!
+
+
+develop vs master
+All official releases shall be in master. Any updates in between (icons, features, etc.) will be kept in develop.
+
+develop contains:
+
+ Latest SVGs (non-optimized).
+
+
+ No icons for the latest SVGs. These will be built at every release.Building Devicon
+
+ Experimental changes.
+
+
+master contains:
+
+ Latest official release, which contains all the SVGs and icons.
+
+
+ Official, tested changes.
+
+
+
+Stale Pull Requests
+
+After a pull request has been open for over 30 days with no activity or response from the author, it'll be automatically marked as stale. We might fork your changes and merge the changes ourselves. Since GitHub tracks contributions by commits, you will be credited.
+
+
+Building Devicon
+
+Follow these steps to build the website and icons either locally or using Gitpod.io .
+
+
+Table of contents
+
+ Using Gitpod to build Local Installation
+ Install dependencies Build the icons Build the CSS stylesheet Setting up the web server
+
+
+Using Gitpod.io
+By using Gitpod.io , you can easily build the icons and install the
+
+>
+
+> **Note**
+> In case some of the commands are not properly ran, you can\
+> follow the steps below and run the same commands on Gitpod.io
+
+Local Installation
+
+Install dependencies
+
+ Fork the repository and clone the forked repository.
+
+```bash
+git clone https://github.com//devicon.git
+```
+
+> **Note**
+> In case you don't have Git installed, check the official guide to install Git on your operating system.
+
+Install all the necessary NPM dependencies
+
+```bash
+npm install
+```
+
+> **Note**
+> In case you don't have NPM installed, check this >ultimate guide on installing Node.js and NPM. These tools are required in order to build Devicon properly.
+
+Install Firefox
+https://www.mozilla.org/en-US/firefox/new/
+
+Install Python 3.8
+https://www.python.org/downloads/
+
+> **Note**
+> Make sure your Python install includes [pip](https://pypi.org/project/pip/)
+
+Install Dependencies
+
+```bash
+python -m pip install -r ./.github/scripts/requirements.txt
+```
+
+Build the new icons
+
+Once all the dependencies are installed, you can proceed to build the newest icons.
+
+```bash
+npm run build-icons
+```
+
+The process might take a while, depending on your operating system's speed and the amount of icons.
+If there are any errors shown, please let us know by creating an issue or contacting us on our Discord community .
+
+Build the CSS stylesheet
+
+Run the following command to build the new CSS stylesheet.
+
+```bash
+npm run build-css
+```
+
+Setting up the web server
+
+Run the following command to start the web server with Python.
+
+```bash
+npm run dev # Will run on port 8000
+```
+
+Or this command, which does exactly the same, but the port can be customized.
+
+```bash
+python -m http.server
+```
+
+You're done now! :tada: Your build of Devicons should be available at https://localhost:8000 (or the desired port).
+
+
+
+
+
+
+## Technical Context
+
+Devicon is a **font-based** icon library. Icons render using `` elements with class names:
+
+```html
+` element) and TagLink is currently the only consumer. Can be extracted later if icons appear elsewhere.
+
+## Fallback Strategy
+
+When `showIcon` is enabled, tags without a matching devicon fall back to Lucide React's ``, ``) with custom wrapper components for branding, whilst Clerk handles all authentication logic, session management, and OAuth flows.
+
+---
+
+## Environment Variables
+
+Required in `.env.local`:
+
+```
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
+CLERK_SECRET_KEY=sk_...
+
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
+NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
+```
+
+The `NEXT_PUBLIC_CLERK_*_URL` variables tell Clerk where to redirect users. The fallback URLs determine where users land after authentication.
+
+---
+
+## Architecture
+
+### Provider Hierarchy
+
+The provider setup in `app/layout.tsx`:
+
+```
+ClerkProvider (authentication context)
+ βββ html
+ βββ body
+ βββ ThemeProvider (next-themes)
+ βββ {children}
+```
+
+`ClerkProvider` must wrap the entire app (including ``) because Clerk needs to inject authentication context before any rendering occurs. The custom wrapper at `components/providers/clerk-provider.tsx` applies global theming and localisation defaults.
+
+### Proxy (Route Protection)
+
+`proxy.ts` (renamed from middleware.ts in Next.js 16) runs Clerk's middleware on every request:
+
+```ts
+import { clerkMiddleware } from "@clerk/nextjs/server";
+export default clerkMiddleware();
+```
+
+The matcher config excludes static files and includes API routes. By default, `clerkMiddleware()` makes authentication available on all routes without blocking unauthenticated users. To protect specific routes, you would add route matchers or use `auth().protect()` in route handlers.
+
+### Auth Routes
+
+Clerk uses catch-all routes to handle its multi-step authentication flows:
+
+- `app/(auth)/sign-in/[[...sign-in]]/page.tsx`
+- `app/(auth)/sign-up/[[...sign-up]]/page.tsx`
+
+The `[[...slug]]` pattern captures all sub-paths (e.g., `/sign-in/factor-one`, `/sign-in/sso-callback`), allowing Clerk to manage its internal routing.
+
+Both pages render custom wrapper components (`ClerkSignIn`, `ClerkSignUp`) that wrap Clerk's `` and `` components with appearance customisations.
+
+### Auth Layout
+
+`app/(auth)/layout.tsx` provides a centred, full-screen background for auth pages using theme-aware CSS variables (`--auth-bg`).
+
+---
+
+## Custom Wrapper Components
+
+### Sign In (`components/auth/clerk-signin.tsx`)
+
+A **client component** that uses `useTheme()` from next-themes to detect the current theme and pass the appropriate logo URL to Clerk. This is necessary because Clerk's `logoImageUrl` prop requires a static URL string and cannot use CSS variables.
+
+The component also customises header alignment (left-aligned rather than centred).
+
+### Sign Up (`components/auth/clerk-signup.tsx`)
+
+A **server component** with a static logo. Theme detection isn't needed here because the icon-only logo (`site-logo.svg`) works on both light and dark backgrounds.
+
+---
+
+## UI Customisation
+
+Clerk's appearance is customised at two levels:
+
+### Global (ClerkProvider)
+
+`components/providers/clerk-provider.tsx` applies defaults to all Clerk components:
+
+- **Theme**: Uses `@clerk/themes/shadcn` for shadcn/ui visual consistency
+- **CSS Layer**: `cssLayerName: "clerk"` ensures Tailwind utilities override Clerk styles
+- **Font**: References the app's Inter font via CSS variable
+- **Button styling**: Primary buttons use the brand gradient (`--gradient-primary`)
+- **Localisation**: Custom text for sign-in/sign-up titles, subtitles, and OAuth button labels
+
+### Per-Component
+
+Individual wrapper components can override globals via the `appearance` prop. For example, `ClerkSignIn` sets a theme-aware logo and left-aligned header.
+
+### CSS Layer Integration
+
+To ensure Tailwind utilities can override Clerk's styles without `!important`:
+
+1. **Declare layer order** at the top of `globals.css`:
+
+ ```css
+ @layer theme, base, clerk, components, utilities;
+ ```
+
+2. **Import Clerk's styles** after the layer declaration:
+
+ ```css
+ @import "@clerk/themes/shadcn.css";
+ ```
+
+3. **Set `cssLayerName`** in ClerkProvider to place Clerk styles in the `clerk` layer.
+
+This ordering ensures utilities (highest priority) can override Clerk styles cleanly.
+
+### Theme-Aware Assets
+
+CSS variables in `globals.css` provide theme-aware URLs:
+
+```css
+:root {
+ --logo-full-themed: url("/images/logo-light.svg");
+ --auth-bg: url("/images/auth-bg-light.webp");
+}
+.dark {
+ --logo-full-themed: url("/images/logo-dark.svg");
+ --auth-bg: url("/images/auth-bg-dark.webp");
+}
+```
+
+These variables are used directly in Tailwind classes via arbitrary value syntax: `bg-(image:--auth-bg)`.
+
+For Clerk components specifically, JavaScript theme detection (`useTheme()`) is required because Clerk's API accepts only static URL strings.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `proxy.ts` | Route protection via `clerkMiddleware()` |
+| `app/layout.tsx` | ClerkProvider wrapping the app |
+| `components/providers/clerk-provider.tsx` | Global Clerk theming and localisation |
+| `app/(auth)/layout.tsx` | Auth page layout with background |
+| `app/(auth)/sign-in/[[...sign-in]]/page.tsx` | Sign-in route |
+| `app/(auth)/sign-up/[[...sign-up]]/page.tsx` | Sign-up route |
+| `components/auth/clerk-signin.tsx` | Custom sign-in wrapper (theme-aware logo) |
+| `components/auth/clerk-signup.tsx` | Custom sign-up wrapper (static logo) |
+| `app/globals.css` | CSS layer order and theme-aware asset variables |
+
+---
+
+## Notes
+
+- The `await connection()` call in auth pages forces dynamic rendering at request time. This may be unnecessary since Clerk components are client-side, but it ensures no caching issues with authentication state.
+- Clerk's localisation API allows customising any text string. The `{{provider|titleize}}` template formats OAuth provider names (e.g., "GitHub" instead of "Continue with GitHub").
diff --git a/x_docs/DONE/navigation.md b/x_docs/DONE/navigation.md
new file mode 100644
index 0000000..60741bb
--- /dev/null
+++ b/x_docs/DONE/navigation.md
@@ -0,0 +1,265 @@
+# Navigation Architecture: Mobile & Sidebar
+
+Last updated: 2026-02-02
+
+This document explains how the navigation system works across breakpoints, component structure, and the distinction between navigation and content discovery.
+
+---
+
+## Overview
+
+The app has **two navigation contexts** that share the same nav items but render differently:
+
+| Context | Breakpoint | Container | Implementation |
+|---------|------------|-----------|----------------|
+| Mobile Nav | `` | shadcn/ui Sidebar with `collapsible="icon"` |
+
+The Left Sidebar can collapse to icon-only mode, persisted via cookie.
+
+---
+
+## Visual Breakdown
+
+```text
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β MOBILE (<640px) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β MobileTopBar: [Logo] [Theme] [Hamburger] β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β Hamburger β Sheet slides in from left (max 320px) β
+β ββββββββββββββββββββ β
+β β [Logo] β β
+β β Home β β
+β β Community β β
+β β Collections β β
+β β Find Jobs β β
+β β Tags β β
+β β Ask a question β β
+β β β β
+β β [Auth buttons] β β SignedOut: Sign in + Sign up β
+β β [UserButton] β β SignedIn: avatar β
+β ββββββββββββββββββββ β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β DESKTOP (β₯640px) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β DesktopTopBar: [Search placeholder] [Theme] [Auth] β
+ββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββ€
+βSidebar β β
+β 13rem β Main Content β
+β β β
+β Home β β Expanded: icon + label β
+β Comm. β β Collapsed: icon only (3rem width) β
+β Coll. β β
+β Jobs β β
+β Tags β β
+β Ask β β
+β β β
+β[User] β β UserButton (SignedIn only) β
+β[Toggle]β β Collapse/expand toggle β
+ββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββ
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β XL DESKTOP (β₯1280px) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β DesktopTopBar β
+ββββββββββ¬βββββββββββββββββββββββββββββββ¬ββββββββββββββββββ€
+βSidebar β Main Content β RightSidebar β
+β β β (22rem) β
+β β β β
+β β β Top Questions β
+β β β Popular Tags β
+β β β β
+ββββββββββ΄βββββββββββββββββββββββββββββββ΄ββββββββββββββββββ
+```
+
+---
+
+## Authentication UI
+
+Auth controls appear in different locations based on screen size and auth state:
+
+| Context | Unauthenticated | Authenticated |
+|---------|-----------------|---------------|
+| **DesktopTopBar** | Sign in + Sign up buttons | Nothing |
+| **LeftSidebar** | Nothing | UserButton at bottom |
+| **MobileNav** | Sign in + Sign up buttons | UserButton |
+
+---
+
+## Navigation vs Content Discovery
+
+The application has two types of sidebars with different purposes:
+
+| Sidebar | Purpose | Content | Visibility |
+|---------|---------|---------|------------|
+| **LeftSidebar** | Navigation | Route links (Home, Community, etc.) | `β₯sm` (640px+) |
+| **RightSidebar** | Content discovery | Top Questions, Popular Tags | `β₯xl` (1280px+) |
+
+The LeftSidebar and MobileNav are **navigation components** β they help users move between routes.
+
+The RightSidebar is a **content discovery component** β it surfaces related content to encourage exploration but doesn't provide primary navigation.
+
+---
+
+## Component Architecture
+
+### Key Insight
+
+Navigation links are implemented differently for mobile and desktop, but share the same data source and styling utilities:
+
+- **MobileNav**: Uses `MobileNavLink` component in a Sheet overlay
+- **LeftSidebar**: Uses shadcn/ui `SidebarMenuButton` with collapsible behaviour
+
+Both consume the `NAV_LINKS` constant and use shared utilities for active state detection.
+
+```text
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β SAME data source, DIFFERENT rendering: β
+β β
+β MobileNav (Sheet) LeftSidebar (shadcn/ui) β
+β βββββββββββββββββββ βββββββββββββββββββ β
+β β β β β β β β
+β βββββββββββββββββββ βββββββββββββββββββ β
+β β β β
+β ββββββββββββ¬ββββββββββββββββββββ β
+β β β
+β NAV_LINKS constant β
+β Shared styling utilities β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Shared Utilities (`lib/utils.ts`)
+
+```typescript
+// Check if route is active (exact or nested)
+isRouteActive(pathname: string, route: string): boolean
+
+// Active state classes
+NAV_LINK_ACTIVE_CLASSES = "bg-(image:--gradient-primary) font-bold text-primary-foreground"
+NAV_LINK_INACTIVE_CLASSES = "font-medium"
+
+// Icon inversion for theme compatibility
+getNavIconInvertClasses(isActive: boolean): string
+```
+
+---
+
+## File Structure
+
+```text
+components/navigation/
+βββ nav-links.constants.ts β NAV_LINKS array (shared data)
+βββ desktop-topbar.tsx β Desktop top bar (β₯sm)
+βββ mobile-topbar.tsx β Mobile top bar (
- {children}
-
-```
-
----
-
-## Q1: What Are Flexboxes?
-
-Flexbox (Flexible Box Layout) is a CSS layout system designed to arrange items in a **single direction** β either as a row (horizontal) or a column (vertical). Think of it as laying items out along a line, with powerful controls for spacing, alignment, and distribution.
-
-### The Mental Model
-
-Imagine a bookshelf. You can arrange books:
-
-- Left to right (row)
-- Stacked top to bottom (column)
-- Spread evenly across the shelf
-- Pushed to one end
-- Centred in the middle
-
-Flexbox gives you all these controls.
-
-### ASCII Diagram: Flex Row vs Flex Column
-
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-β FLEX ROW (default: flex-direction: row) β
-β β
-β βββββββββ βββββββββ βββββββββ β
-β β Item β β Item β β Item β ββββββββΊ β
-β β 1 β β 2 β β 3 β Main Axis β
-β βββββββββ βββββββββ βββββββββ β
-β β β β β
-β βΌ Cross Axis β
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-β FLEX COLUMN (flex-direction: column) β
-β β
-β β β
-β βΌ Main Axis β
-β βββββββββββββββββββββ β
-β β Item 1 β β
-β βββββββββββββββββββββ β
-β βββββββββββββββββββββ β
-β β Item 2 β β
-β βββββββββββββββββββββ β
-β βββββββββββββββββββββ β
-β β Item 3 β ββββββββΊ Cross Axis β
-β βββββββββββββββββββββ β
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
-### Why Flexbox for the Auth Layout?
-
-We used flexbox because we needed to **centre one thing** (the login form) both horizontally and vertically within a container. This is flexbox's sweet spot:
-
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β β
-β βββββββββββββββ β
-β β Login β β
-β β Form β βββ children β
-β βββββββββββββββ β
-β β
-β β
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
- Screen (min-h-screen)
-```
-
-The combination `flex items-center justify-center` achieves this perfectly.
-
----
-
-## Q2: When to Use Flexbox vs Grid?
-
-Both are CSS layout systems, but they solve different problems.
-
-### π Comparison Table
-
-| Aspect | π Flexbox | π² Grid |
-|--------|-----------|---------|
-| **Dimension** | One-dimensional (row OR column) | Two-dimensional (rows AND columns) |
-| **Best for** | Aligning items along a line | Creating structured layouts |
-| **Content-driven** | β
Yes β items determine their size | β No β grid defines the structure |
-| **Layout-driven** | β No | β
Yes β you define rows/columns first |
-| **Simple centering** | β
Perfect | β οΈ Works but overkill |
-| **Complex layouts** | β οΈ Hacky | β
Designed for this |
-| **Navigation bars** | β
Ideal | β οΈ Unnecessary |
-| **Photo galleries** | β οΈ Difficult | β
Ideal |
-| **Card grids** | β οΈ Requires wrapping | β
Natural fit |
-
-### When to Choose Each
-
-| Use Case | Choose | Why |
-|----------|--------|-----|
-| π― Centre a single element | Flexbox | Two lines of code |
-| π± Navigation bar | Flexbox | Items in a row with spacing |
-| π Form fields in a column | Flexbox | Items stacked vertically |
-| πΌοΈ Image gallery | Grid | Rows and columns together |
-| π° Magazine-style layout | Grid | Complex 2D positioning |
-| π Dashboard with widgets | Grid | Named areas, spanning cells |
-| βοΈ Space items evenly | Flexbox | `justify-between` or `space-evenly` |
-
-### ASCII Diagram: The Difference
-
-```
-FLEXBOX: Thinks in ONE direction at a time
-ββββββββββββββββββββββββββββββββββββββββββ
- βββββ βββββ βββββββ βββββ
- β A β β B β β C β β D β βββ Items flow, sizes vary
- βββββ βββββ βββββββ βββββ
-
-
-GRID: Thinks in ROWS and COLUMNS together
-ββββββββββββββββββββββββββββββββββββββββββ
- βββββββββββ¬ββββββββββ¬ββββββββββ
- β A β B β C β βββ Row 1
- βββββββββββΌββββββββββΌββββββββββ€
- β D β E β F β βββ Row 2
- βββββββββββΌββββββββββΌββββββββββ€
- β G β H β I β βββ Row 3
- βββββββββββ΄ββββββββββ΄ββββββββββ
- β² β² β²
- Col 1 Col 2 Col 3
-```
-
-**For our auth layout:** We chose flexbox because we only needed to position one child element. Grid would work but adds unnecessary complexity for such a simple requirement.
-
----
-
-## Q3: Why Are "Layout" and "Flexbox & Grid" Separate in Tailwind Docs?
-
-The Tailwind documentation organises utilities by the CSS concepts they control. Here's why they're separate:
-
-### ποΈ Category Breakdown
-
-| Category | What It Controls | Examples |
-|----------|------------------|----------|
-| π **Layout** | How elements participate in document flow | `display`, `position`, `float`, `z-index`, `overflow` |
-| π **Flexbox & Grid** | How children are arranged within a flex/grid container | `flex-direction`, `justify-content`, `align-items`, `grid-template-columns` |
-
-### The Key Distinction
-
-**Layout** answers: *"How does this element exist in the page?"*
-
-- Is it `block` or `inline`?
-- Is it `fixed` to the viewport?
-- Is it `absolute` and pulled out of normal flow?
-- What's its `z-index` (stacking order)?
-
-**Flexbox & Grid** answers: *"How are this element's children arranged?"*
-
-- Should children be in a row or column?
-- How should space be distributed?
-- How should children align?
-
-### Visual Example
-
-```
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β β
-β ββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β position: fixed βββ LAYOUT β β
-β ββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β
-β ββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β display: flex βββ LAYOUT β β
-β β β β
-β β ββββββ ββββββ ββββββ β β
-β β β A β β B β β C β β β
-β β ββββββ ββββββ ββββββ β β
-β β β² β β
-β β βββ justify-center βββ FLEXBOX β β
-β ββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
-In our auth layout:
-
-- `flex` is technically a **Layout** utility (it sets `display: flex`)
-- `items-center` and `justify-center` are **Flexbox** utilities (they control child alignment)
-
-They work together but control different aspects.
-
----
-
-## Q4: Is Flexbox a CSS Concept or Tailwind-Specific?
-
-**Flexbox is a native CSS standard.** Tailwind simply provides utility classes that map to the underlying CSS properties.
-
-### π The Relationship
-
-| What You Write (Tailwind) | What CSS Gets Applied | CSS Property |
-|---------------------------|----------------------|--------------|
-| `flex` | `display: flex;` | Native CSS |
-| `items-center` | `align-items: center;` | Native CSS |
-| `justify-center` | `justify-content: center;` | Native CSS |
-| `flex-col` | `flex-direction: column;` | Native CSS |
-| `gap-4` | `gap: 1rem;` | Native CSS |
-
-### The Same Thing, Two Ways
-
-```css
-/* Pure CSS */
-.container {
- display: flex;
- align-items: center;
- justify-content: center;
- min-height: 100vh;
-}
-
-/* Tailwind utility classes */
-
-```
-
-Both produce identical results. Tailwind is a **convenience layer** that:
-
-1. Provides short, memorable class names
-2. Ensures consistent spacing/sizing scales
-3. Enables responsive design with prefixes (`md:flex-row`)
-4. Enables state variants (`hover:items-start`)
-
-**The underlying concepts (flexbox, grid, etc.) are all standard CSS** that works in every modern browser, with or without Tailwind.
-
----
-
-## Q5: Utility Class Breakdown
-
-Here's every utility class used in the auth layout, explained:
-
-### π Complete Class Reference
-
-| Tailwind Class | CSS Property | Purpose | Impact |
-|----------------|--------------|---------|--------|
-| π `flex` | `display: flex;` | Enables flexbox on the container | Children can now be positioned using flex properties |
-| π `min-h-screen` | `min-height: 100vh;` | Container is at least full viewport height | Ensures the background covers the entire screen |
-| βοΈ `items-center` | `align-items: center;` | Centres children on the cross-axis (vertically for row) | Login form is vertically centred |
-| βοΈ `justify-center` | `justify-content: center;` | Centres children on the main-axis (horizontally for row) | Login form is horizontally centred |
-| πΌοΈ `bg-cover` | `background-size: cover;` | Image scales to cover entire container | No empty space, image may crop |
-| π― `bg-center` | `background-position: center;` | Image is centred within container | Cropping happens equally from edges |
-| π« `bg-no-repeat` | `background-repeat: no-repeat;` | Image displays once, not tiled | Prevents image from repeating if container is larger |
-| π
bg-β[url('β¦')] | `background-image: url(β¦);` | Sets the background image | Displays the light-mode background |
-| π dark:βbg-β[url('β¦')] | `background-image: url(β¦);` (when `.dark` class present) | Sets dark-mode background | Switches image when theme is dark |
-
-### π¨ Visual Impact Diagram
-
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β min-h-screen: Container fills viewport height β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β β β
-β β bg-cover + bg-center + bg-no-repeat: β β
-β β Background image fills and centres β β
-β β β β
-β β flex + items-center + justify-center: β β
-β β β β β
-β β βΌ β β
-β β βββββββββββββββ β β
-β β β Login β β β
-β β β Form β βββ children β β
-β β β (centred) β β β
-β β βββββββββββββββ β β
-β β β β
-β β bg-[url('/images/auth-bg-light.webp')] β β
-β β dark:bg-[url('/images/auth-bg-dark.webp')] β β
-β β β² β β
-β β βββ Theme-aware background switching β β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
-### How the Classes Work Together
-
-1. **`flex`** β Enables the flexbox layout model on `
`
-2. **`items-center`** β Tells flex to centre children vertically
-3. **`justify-center`** β Tells flex to centre children horizontally
-4. **`min-h-screen`** β Ensures there's vertical space to centre within
-5. **`bg-*` classes** β Handle the decorative background independently of the layout
-
-The layout (centering) and decoration (background) are separate concerns that combine to create the final result.
-
----
-
-## Background Image: Did We Use the Documentation?
-
-Yes! We used the bg-β[url(β¦)] syntax documented in the Tailwind background-image reference.
-
-### What the Docs Show
-
-From the documentation:
-
-```txt
-
-```
-
-This is the **arbitrary value syntax** β square brackets `[]` let you use any CSS value directly.
-
-### What We Implemented
-
-```html
-
-```
-
-### π Features We Used from the Docs
-
-| Feature | From Docs | Our Usage |
-|---------|-----------|-----------|
-| β
Arbitrary URL syntax | bg-β[url(β¦)] | `bg-[url('/images/auth-bg-light.webp')]` |
-| β
Dark mode variant | Via `dark:` prefix (covered in variants docs) | `dark:bg-[url('/images/auth-bg-dark.webp')]` |
-
-### Features We Did NOT Use
-
-The documentation also covers gradients, colour stops, and interpolation modes β none of which we needed for a simple image background:
-
-- `bg-linear-to-r` β Linear gradients
-- `from-indigo-500 via-purple-500 to-pink-500` β Colour stops
-- `bg-radial`, `bg-conic` β Other gradient types
-
-These are available if you want to add gradient overlays or effects in the future.
-
----
-
-## Summary
-
-| Concept | Key Takeaway |
-|---------|--------------|
-| π **Flexbox** | One-dimensional layout for arranging items in a row or column. Perfect for centering and distributing space. |
-| π² **Grid** | Two-dimensional layout for complex row/column structures. Ideal for galleries and dashboards. |
-| π **Layout vs Flex/Grid** | Layout controls *how an element exists* in the page. Flexbox/Grid control *how its children are arranged*. |
-| π¨ **CSS vs Tailwind** | Flexbox is native CSS. Tailwind provides convenient utility classes that compile to standard CSS. |
-| πΌοΈ **Background Images** | Use bg-β[url(β¦)] for arbitrary images. Combine with `dark:` for theme-aware switching. |
-
----
-
-*Document created to explain the auth layout implementation in DevFlow.*
diff --git a/x_docs/mine/globals-compare.md b/x_docs/mine/globals-compare.md
deleted file mode 100644
index 352a2ad..0000000
--- a/x_docs/mine/globals-compare.md
+++ /dev/null
@@ -1,983 +0,0 @@
-# Tailwind Theming Comparison: `globals-old.css` vs My Modern Approach `globals.css`
-
-This document compares the light/dark mode approach from an old file (`globals-old.css`) with the modern Tailwind v4 approach (`globals.css`), and categorises all configuration patterns with explanations.
-
----
-
-## Light/Dark Mode Comparison
-
-| Aspect | Old File (globals-old.css) | Your File (globals.css) |
-|--------|-------------------------------|-------------------------|
-| **Approach** | Composite utility classes with `dark:` variant | CSS custom properties + `@theme inline` |
-| **Colour Format** | Named scales (light-850, dark-100) | OKLCH (perceptually uniform) |
-| **Theme Switching** | Class-based via Tailwind `dark:` | CSS variables that swap at runtime |
-| **Naming** | Arbitrary (light-850, dark-400) | Semantic (primary, muted, accent) |
-| **Tailwind Version** | v3 patterns | v4 native patterns |
-
-### Verdict: The modern globals.css approach is significantly better
-
-**Why the modern approach wins:**
-
-1. **Runtime theme switching** β CSS variables can be changed via JavaScript without recompiling CSS. This enables features like system preference detection, user preference persistence, and instant theme toggling.
-
-2. **OKLCH colour space** β A modern, perceptually uniform colour space. Unlike HSL or RGB, OKLCH ensures that colours with the same lightness value actually *appear* equally light to human eyes. This produces better gradients and more accessible colour combinations.
-
-3. **Semantic naming** β `bg-primary` communicates intent; `bg-light-850` is meaningless without context. Semantic names make code self-documenting and easier to maintain.
-
-4. **shadcn/ui compatible** β The CSS variable pattern is the standard for shadcn/ui components, Radix UI, and most modern React component libraries. Your setup works out of the box.
-
-5. **DRY (Don't Repeat Yourself)** β Change one variable in `:root` or `.dark`, and all usages update automatically. The old file has 50+ hardcoded light/dark combinations that must be updated individually.
-
-6. **No `!important` spam** β The old file uses `!important` 20+ times, which is a code smell indicating specificity problems. The modern approach avoids this entirely through proper CSS layering.
-
----
-
-## Old File Categories Explained
-
-The old file contains various utility patterns. Below, each category is explained with context on what it does, why it exists, and what you would need in a modern setup.
-
----
-
-### 1. Base Settings
-
-```css
-body { font-family: "Inter", sans-serif; }
-:root { --radius: 8px; }
-```
-
-**What it does:**
-Sets the global font family and defines a CSS variable for border radius that can be used throughout the application.
-
-**Why it exists:**
-Centralising design tokens like border radius allows for consistent UI and easy global changes.
-
-**What you'd need:**
-Already handled in your file. Your setup is more sophisticated:
-
-- `--radius` is defined in `:root` and mapped via `@theme inline` to generate `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl` utilities
-- Fonts are defined as CSS variables (`--font-display`, `--font-serif`, `--font-mono`) that integrate with Next.js font optimisation
-
----
-
-### 2. Background Theme Utilities (17 classes)
-
-```css
-.background-light850_dark100 { @apply bg-light-850 dark:bg-dark-100; }
-.background-light900_dark200 { @apply bg-light-900 dark:bg-dark-200; }
-.background-light900_dark300 { @apply bg-light-900 dark:bg-dark-300; }
-/* ... 14 more variations */
-```
-
-**What it does:**
-Pre-composed utility classes that apply different background colours depending on whether light or dark mode is active. The naming convention `light850_dark100` indicates "use light-850 in light mode, dark-100 in dark mode".
-
-**Why it exists:**
-In Tailwind v3, this was a common pattern to avoid writing `bg-light-850 dark:bg-dark-100` repeatedly in JSX. It keeps component markup cleaner.
-
-**Problems with this approach:**
-
-- Creates dozens of single-purpose classes
-- Arbitrary numbers (850, 100) have no semantic meaning
-- Must create a new class for every light/dark combination needed
-- Tightly couples colour values to class names
-
-**What you'd need:**
-Nothing. Use semantic classes instead:
-
-```html
-
-
-
-
-
-
-```
-
-The modern approach uses semantic names that describe *purpose* (card, muted, secondary) rather than *appearance* (light-900, dark-200).
-
----
-
-### 3. Text Theme Utilities (16 classes)
-
-```css
-.text-dark100_light900 { @apply text-dark-100 dark:text-light-900 !important; }
-.text-dark200_light800 { @apply text-dark-200 dark:text-light-800 !important; }
-.text-dark300_light700 { @apply text-dark-300 dark:text-light-700; }
-/* ... 13 more variations */
-```
-
-**What it does:**
-Pre-composed text colour classes for light/dark mode. Note that many use `!important` to force specificity.
-
-**Why it exists:**
-Same rationale as background utilities β reduces repetition in markup.
-
-**Problems with this approach:**
-
-- Heavy use of `!important` indicates specificity battles
-- Arbitrary colour values make it hard to understand visual hierarchy
-- No indication of what each colour combination is *for*
-
-**What you'd need:**
-Nothing. Use semantic text colours:
-
-```html
-
-
Secondary text
-
-
-
Secondary text
-```
-
-Common semantic text colours in your setup:
-
-- `text-foreground` β Primary text
-- `text-muted-foreground` β Secondary/subdued text
-- `text-primary` β Brand/accent text
-- `text-destructive` β Error/warning text
-
----
-
-### 4. Border Utilities
-
-```css
-.light-border { @apply border-light-800 dark:border-dark-300; }
-.light-border-2 { @apply border-light-700 dark:border-dark-400 !important; }
-```
-
-**What it does:**
-Consistent border colours that adapt to light/dark mode.
-
-**Why it exists:**
-Borders often need different opacity/colour in dark mode to remain visible without being too harsh.
-
-**What you'd need:**
-Already handled. Your `@layer base` includes:
-
-```css
-* {
- @apply border-border outline-ring/50;
-}
-```
-
-This sets a default border colour on all elements using the `--border` CSS variable, which automatically changes between light and dark mode. Simply use the `border` class:
-
-```html
-
-```
-
----
-
-### 5. Typography Scale (16 classes)
-
-```css
-.h1-bold { @apply text-[30px] font-bold leading-[42px] tracking-tighter; }
-.h2-bold { @apply text-[24px] font-bold leading-[31.2px]; }
-.h2-semibold { @apply text-[24px] font-semibold leading-[31.2px]; }
-.h3-bold { @apply text-[20px] font-bold leading-[26px]; }
-.h3-semibold { @apply text-[20px] font-semibold leading-[24.8px]; }
-.base-medium { @apply text-[18px] font-medium leading-[25.2px]; }
-.base-semibold { @apply text-[18px] font-semibold leading-[25.2px]; }
-.base-bold { @apply text-[18px] font-bold leading-[140%]; }
-.paragraph-regular { @apply text-[16px] font-normal leading-[22.4px]; }
-.paragraph-medium { @apply text-[16px] font-medium leading-[22.4px]; }
-.paragraph-semibold { @apply text-[16px] font-semibold leading-[20.8px]; }
-.body-regular { @apply text-[14px] font-normal leading-[19.6px]; }
-.body-medium { @apply text-[14px] font-medium leading-[18.2px]; }
-.body-semibold { @apply text-[14px] font-semibold leading-[18.2px]; }
-.body-bold { @apply text-[14px] font-bold leading-[18.2px]; }
-.small-regular { @apply text-[12px] font-normal leading-[15.6px]; }
-.small-medium { @apply text-[12px] font-medium leading-[15.6px]; }
-.small-semibold { @apply text-[12px] font-semibold leading-[15.6px]; }
-.subtle-medium { @apply text-[10px] font-medium leading-[13px] !important; }
-.subtle-regular { @apply text-[10px] font-normal leading-[13px]; }
-```
-
-**What it does:**
-A comprehensive type scale combining font size, weight, and line height into single utility classes. The naming convention is `{size}-{weight}`.
-
-**Why it exists:**
-Typography often requires coordinated changes to size, weight, and line-height. These utilities ensure consistent combinations across the app.
-
-**Analysis:**
-This is actually a reasonable pattern, though the arbitrary pixel values (`text-[30px]`, `leading-[42px]`) could be replaced with Tailwind's built-in scale for better maintainability.
-
-**What you'd need:**
-Your file already has base styles for `h1`β`h6` in `@layer base`. For additional utility combinations, you could add:
-
-```css
-@layer utilities {
- /* Using Tailwind's built-in scale instead of arbitrary values */
- .h1-bold { @apply text-5xl font-bold tracking-tight; }
- .h2-bold { @apply text-4xl font-bold; }
- .h2-semibold { @apply text-4xl font-semibold; }
- .h3-bold { @apply text-3xl font-bold; }
-
- .body-medium { @apply text-sm font-medium; }
- .body-semibold { @apply text-sm font-semibold; }
-
- .small-medium { @apply text-xs font-medium; }
- .caption { @apply text-xs text-muted-foreground; }
-}
-```
-
-Alternatively, just compose Tailwind utilities directly in your JSX β `text-sm font-medium` is clear and doesn't require custom classes.
-
----
-
-### 6. Placeholder Styles
-
-```css
-.placeholder { @apply placeholder:text-light-400 dark:placeholder:text-light-500; }
-```
-
-**What it does:**
-Sets consistent placeholder text colour in form inputs across light/dark modes.
-
-**Why it exists:**
-Placeholder text should be visually distinct from actual input text, but still readable. The colour often needs adjustment in dark mode.
-
-**What you'd need:**
-Add to your base layer for global application:
-
-```css
-@layer base {
- input::placeholder,
- textarea::placeholder {
- @apply text-muted-foreground;
- }
-}
-```
-
-Or apply per-component using Tailwind's placeholder modifier: `placeholder:text-muted-foreground`.
-
----
-
-### 7. Visual Effects
-
-```css
-.invert-colors { @apply invert dark:invert-0; }
-.shadow-light100_dark100 { @apply shadow-light-100 dark:shadow-dark-100; }
-.shadow-light100_darknone { @apply shadow-light-100 dark:shadow-none; }
-```
-
-**What it does:**
-
-- `invert-colors`: Inverts an element's colours in light mode, restores in dark mode. Useful for black icons that need to be white in dark mode.
-- Shadow utilities: Apply different shadow styles per theme. Shadows often look too harsh in dark mode and need to be softer or removed.
-
-**Why it exists:**
-Icons and shadows frequently need theme-specific treatment that simple colour changes don't address.
-
-**What you'd need:**
-If using icons that need inversion (e.g., black SVGs):
-
-```css
-@layer utilities {
- .invert-on-light { @apply invert dark:invert-0; }
- .invert-on-dark { @apply dark:invert; }
-}
-```
-
-For shadows, consider defining shadow values in your theme that work across modes, or use:
-
-```css
-@layer utilities {
- .shadow-theme {
- @apply shadow-md dark:shadow-none dark:ring-1 dark:ring-border;
- }
-}
-```
-
----
-
-### 8. Gradients
-
-```css
-.primary-gradient {
- background: linear-gradient(129deg, #ff7000 0%, #e2995f 100%);
-}
-
-.dark-gradient {
- background: linear-gradient(
- 232deg,
- rgba(23, 28, 35, 0.41) 0%,
- rgba(19, 22, 28, 0.7) 100%
- );
-}
-
-.light-gradient {
- background: linear-gradient(
- 132deg,
- rgba(247, 249, 255, 0.5) 0%,
- rgba(229, 237, 255, 0.25) 100%
- );
-}
-
-.primary-text-gradient {
- background: linear-gradient(129deg, #ff7000 0%, #e2995f 100%);
- background-clip: text;
- -webkit-background-clip: text;
- -webkit-text-fill-color: transparent;
-}
-```
-
-**What it does:**
-
-- `primary-gradient`: Brand gradient for buttons, CTAs, highlights (orange tones)
-- `dark-gradient`: Subtle overlay gradient for dark mode cards/surfaces
-- `light-gradient`: Subtle overlay gradient for light mode
-- `primary-text-gradient`: Applies gradient as text colour (the background shows through transparent text)
-
-**Why it exists:**
-Gradients add visual interest and depth. Brand gradients reinforce identity. The text gradient technique creates eye-catching headings.
-
-**What you'd need:**
-First, define brand colours as CSS variables, then create gradient utilities:
-
-```css
-:root {
- --brand-orange: #ff7000;
- --brand-gold: #e2995f;
-}
-
-@layer utilities {
- .bg-gradient-primary {
- background: linear-gradient(135deg, var(--brand-orange) 0%, var(--brand-gold) 100%);
- }
-
- .bg-gradient-surface {
- @apply bg-gradient-to-br from-background to-muted/50;
- }
-
- .text-gradient-primary {
- background: linear-gradient(135deg, var(--brand-orange) 0%, var(--brand-gold) 100%);
- -webkit-background-clip: text;
- -webkit-text-fill-color: transparent;
- background-clip: text;
- }
-}
-```
-
----
-
-### 9. Layout Utilities
-
-```css
-.flex-center { @apply flex justify-center items-center; }
-.flex-between { @apply flex justify-between items-center; }
-.flex-start { @apply flex justify-start items-center; }
-```
-
-**What it does:**
-Shorthand utilities for common flexbox patterns:
-
-- `flex-center`: Centre children both horizontally and vertically
-- `flex-between`: Space children to opposite ends, vertically centred
-- `flex-start`: Align children to start, vertically centred
-
-**Why it exists:**
-These three-class combinations (`flex justify-center items-center`) are extremely common. Single utilities reduce markup verbosity.
-
-**What you'd need:**
-These are genuinely useful shortcuts. Add if you find yourself writing these combinations frequently:
-
-```css
-@layer utilities {
- .flex-center { @apply flex items-center justify-center; }
- .flex-between { @apply flex items-center justify-between; }
- .flex-start { @apply flex items-center justify-start; }
- .flex-end { @apply flex items-center justify-end; }
-
- /* Inline variant (horizontal only) */
- .inline-center { @apply inline-flex items-center justify-center; }
-}
-```
-
----
-
-### 10. Component Utilities
-
-```css
-.card-wrapper {
- @apply bg-light-900 dark:dark-gradient shadow-light-100 dark:shadow-dark-100;
-}
-
-.btn { @apply bg-light-800 dark:bg-dark-300 !important; }
-.btn-secondary { @apply bg-light-800 dark:bg-dark-400 !important; }
-.btn-tertiary { @apply bg-light-700 dark:bg-dark-300 !important; }
-
-.tab {
- @apply min-h-full dark:bg-dark-400 bg-light-800 text-light-500
- dark:data-[state=active]:bg-dark-300 data-[state=active]:bg-primary-100
- data-[state=active]:text-primary-500 !important;
-}
-```
-
-**What it does:**
-Pre-styled component utilities for cards, buttons, and tabs.
-
-**Why it exists:**
-When not using a component library, these utilities provide consistent component styling without writing full CSS classes for each component.
-
-**Problems with this approach:**
-
-- Heavy use of `!important` to override other styles
-- Tightly coupled to specific colour values
-- Doesn't scale well β you end up with `.btn`, `.btn-secondary`, `.btn-tertiary`, `.btn-ghost`, `.btn-outline`...
-- State management (`:hover`, `:active`, `:disabled`) becomes complex
-
-**What you'd need:**
-With shadcn/ui or similar component libraries, you get actual React components (`
`, ``, ``) that:
-
-- Read from your CSS variables automatically
-- Handle all states (hover, focus, disabled, active)
-- Support variants via props (``)
-- Are fully accessible
-
-If building custom components without a library, define styles within the component file rather than in globals.
-
----
-
-### 11. Focus Utilities
-
-```css
-.no-focus {
- @apply focus-visible:ring-0 focus-visible:ring-transparent focus-visible:ring-offset-0 !important;
-}
-```
-
-**What it does:**
-Completely removes the focus ring from an element.
-
-**Why it exists:**
-Sometimes designers want to remove browser focus indicators for aesthetic reasons.
-
-**Accessibility warning:**
-Focus indicators are essential for keyboard navigation. Removing them makes your site inaccessible to keyboard users. This utility should be used sparingly, if at all, and only when a custom focus indicator is provided instead.
-
-**What you'd need:**
-If you must use this pattern, provide an alternative focus indicator:
-
-```css
-@layer utilities {
- .focus-custom {
- @apply focus-visible:ring-0 focus-visible:ring-offset-0
- focus-visible:outline-2 focus-visible:outline-primary;
- }
-}
-```
-
----
-
-### 12. Prose/Markdown Styles
-
-```css
-.markdown {
- @apply max-w-full prose dark:prose-p:text-light-700 dark:prose-ol:text-light-700
- dark:prose-ul:text-light-500 dark:prose-strong:text-white
- dark:prose-headings:text-white prose-headings:text-dark-400
- prose-h1:text-dark-300 prose-h2:text-dark-300 prose-p:text-dark-500
- prose-ul:text-dark-500 prose-ol:text-dark-500;
-}
-
-.markdown-editor {
- @apply prose max-w-full prose-p:m-0 dark:prose-headings:text-white
- prose-headings:text-dark-400 prose-p:text-dark-500 dark:prose-p:text-light-700
- prose-ul:text-dark-500 dark:prose-ul:text-light-700 prose-ol:text-dark-500
- dark:prose-ol:text-light-700 dark:prose-strong:text-white
- prose-blockquote:text-dark-500 dark:prose-blockquote:text-light-700;
-}
-```
-
-**What it does:**
-Customises the Tailwind Typography plugin (`@tailwindcss/typography`) for rendered markdown content. The `prose` class styles semantic HTML (headings, paragraphs, lists, etc.) and these utilities override specific elements for light/dark mode.
-
-**Why it exists:**
-User-generated content (blog posts, comments, documentation) often comes as HTML/Markdown that needs consistent styling without adding classes to every element.
-
-**What you'd need:**
-
-1. Install the typography plugin: `npm install @tailwindcss/typography`
-2. Add customised prose utilities:
-
-```css
-@layer utilities {
- .prose-custom {
- @apply prose prose-slate dark:prose-invert max-w-none
- prose-headings:font-display
- prose-a:text-primary prose-a:no-underline hover:prose-a:underline
- prose-code:before:content-none prose-code:after:content-none;
- }
-}
-```
-
-The `dark:prose-invert` modifier handles most light/dark adjustments automatically.
-
----
-
-### 13. Scrollbar Customisation
-
-```css
-.custom-scrollbar::-webkit-scrollbar {
- width: 3px;
- height: 3px;
- border-radius: 2px;
-}
-
-.custom-scrollbar::-webkit-scrollbar-track {
- background: #ffffff;
-}
-
-.custom-scrollbar::-webkit-scrollbar-thumb {
- background: #888;
- border-radius: 50px;
-}
-
-.custom-scrollbar::-webkit-scrollbar-thumb:hover {
- background: #555;
-}
-
-.no-scrollbar::-webkit-scrollbar {
- display: none;
-}
-
-.no-scrollbar {
- -ms-overflow-style: none;
- scrollbar-width: none;
-}
-```
-
-**What it does:**
-
-- `custom-scrollbar`: Thin, styled scrollbar for webkit browsers (Chrome, Safari, Edge)
-- `no-scrollbar`: Hides scrollbar while maintaining scroll functionality
-
-**Why it exists:**
-Default browser scrollbars can be visually heavy. Thin or hidden scrollbars create a cleaner UI, especially in sidebars, modals, and horizontally-scrolling containers.
-
-**Browser support note:**
-
-- `::-webkit-scrollbar` works in Chrome, Safari, Edge
-- `scrollbar-width` is the Firefox standard
-- `scrollbar-gutter` is a newer property for reserving scrollbar space
-
-**What you'd need:**
-Copy and adapt with CSS variables for theme awareness:
-
-```css
-.scrollbar-thin::-webkit-scrollbar {
- width: 6px;
- height: 6px;
-}
-
-.scrollbar-thin::-webkit-scrollbar-track {
- @apply bg-transparent;
-}
-
-.scrollbar-thin::-webkit-scrollbar-thumb {
- @apply rounded-full bg-border hover:bg-muted-foreground;
-}
-
-.scrollbar-thin {
- scrollbar-width: thin;
- scrollbar-color: var(--border) transparent;
-}
-
-.scrollbar-none {
- scrollbar-width: none;
- -ms-overflow-style: none;
-}
-
-.scrollbar-none::-webkit-scrollbar {
- display: none;
-}
-```
-
----
-
-### 14. Theme/Active State Utilities
-
-```css
-.active-theme {
- filter: invert(53%) sepia(98%) saturate(3332%) hue-rotate(0deg)
- brightness(104%) contrast(106%) !important;
-}
-
-.hash-span {
- margin-top: -140px;
- padding-bottom: 140px;
- display: block;
-}
-```
-
-**What it does:**
-
-- `active-theme`: Applies a colour filter to indicate active/selected state (makes elements orange)
-- `hash-span`: Offset anchor for hash links, accounting for fixed header height
-
-**Why it exists:**
-
-- `active-theme`: Colouring icons/elements to match brand colour when selected
-- `hash-span`: When navigating to `#section`, the browser scrolls the element to the top. With a fixed header, this hides the content. The negative margin + padding trick positions the anchor above the visible content.
-
-**What you'd need:**
-For active states, prefer Tailwind's state modifiers or CSS variables:
-
-```css
-@layer utilities {
- .active-brand {
- @apply text-primary;
- filter: none; /* Avoid filter hacks when possible */
- }
-}
-```
-
-For scroll offset with fixed headers, modern CSS has `scroll-margin-top`:
-
-```css
-@layer base {
- [id] {
- scroll-margin-top: 5rem; /* Adjust to your header height */
- }
-}
-```
-
----
-
-### 15. Third-Party Component Overrides
-
-```css
-.mdxeditor-toolbar {
- background: #ffffff !important;
-}
-
-.dark .mdxeditor-toolbar {
- background: #151821 !important;
-}
-
-.dark .mdxeditor-toolbar button svg {
- color: #858ead !important;
-}
-
-.dark .mdxeditor-toolbar button:hover svg {
- color: #000 !important;
-}
-
-.dark .mdxeditor-toolbar [role="separator"] {
- border-color: #555 !important;
-}
-
-[data-lexical-editor="true"] {
- height: 350px !important;
- overflow-y: auto !important;
-}
-
-.markdown a {
- color: #1da1f2;
-}
-
-.markdown pre {
- display: grid;
- width: 100%;
-}
-```
-
-**What it does:**
-Overrides default styles of third-party libraries (MDXEditor, Lexical) to match the application's theme.
-
-**Why it exists:**
-Third-party components come with their own styles that often don't match your design system. Overrides are necessary for visual consistency.
-
-**Problems with this approach:**
-
-- Fragile β breaks when libraries update their class names
-- Heavy use of `!important` to win specificity battles
-- Hardcoded colour values instead of CSS variables
-
-**What you'd need:**
-Only add when you install these specific libraries. Better approach:
-
-```css
-/* Use CSS variables so overrides follow your theme */
-.mdxeditor-toolbar {
- background: var(--background) !important;
-}
-
-.dark .mdxeditor-toolbar button svg {
- color: var(--muted-foreground) !important;
-}
-
-/* Consider keeping third-party overrides in a separate file */
-/* e.g., styles/vendor-overrides.css */
-```
-
----
-
-## Summary: What to Add to Your Modern Setup
-
-| Category | Recommendation | Priority |
-|----------|----------------|----------|
-| Theme colours | Already handled via CSS variables | N/A |
-| Typography base | Already in `@layer base` for h1βh6 | N/A |
-| Typography utilities | Add only if you need specific combos frequently | Low |
-| Gradients | Add when you define brand colours | Medium |
-| Flex shortcuts | Optional convenience utilities | Low |
-| Placeholder styles | Add to base layer | Low |
-| Scrollbar styles | Add when needed for specific UI | Low |
-| Prose/Markdown | Add when implementing markdown rendering | Medium |
-| Component utilities | Use shadcn components instead | N/A |
-| `!important` utilities | Avoid β indicates architecture issues | N/A |
-| Focus removal | Avoid β accessibility concern | N/A |
-| Third-party overrides | Add only when installing those libraries | As needed |
-
----
-
-## Key Takeaways
-
-1. **Prefer CSS variables over composite utility classes** β They're more flexible, maintainable, and work with runtime theme switching.
-
-2. **Use semantic naming** β `bg-primary`, `text-muted-foreground` communicate intent better than `bg-light-850`, `text-dark-400`.
-
-3. **Avoid `!important`** β If you need it frequently, your CSS architecture has problems. Use proper layering (`@layer base`, `@layer components`, `@layer utilities`).
-
-4. **Don't pre-optimise** β Add utilities as you need them, not upfront. You may never need half of the old file's utilities.
-
-5. **Leverage your component library** β With shadcn/ui, you get buttons, cards, tabs, etc. that already work with your CSS variables. Don't recreate them as utility classes.
-
----
-
-## Appendix: Which File is Superior for Tailwind v4 Theming?
-
-**Winner: `globals.css` (your current file)**
-
-The modern `globals.css` is unequivocally superior for centralised theming with Tailwind v4. Here's an educational breakdown of why.
-
----
-
-### The Core Principle: Single Source of Truth
-
-Good theming follows a fundamental principle: **define once, use everywhere**. Let's compare how each file handles this.
-
-#### Old File Approach (globals-old.css)
-
-```css
-/* Colour is defined inline, repeated for every combination */
-.background-light900_dark200 { @apply bg-light-900 dark:bg-dark-200; }
-.background-light900_dark300 { @apply bg-light-900 dark:bg-dark-300; }
-.text-dark400_light700 { @apply text-dark-400 dark:text-light-700; }
-.text-dark400_light800 { @apply text-dark-400 dark:text-light-800; }
-/* ... 50+ more classes */
-```
-
-**Problems:**
-
-- To change a colour, you must find and update every class that uses it
-- No single place defines what "the background colour" is
-- Adding a new theme (e.g., high contrast) requires duplicating all classes
-
-#### Modern Approach (globals.css)
-
-```css
-/* Define once */
-:root {
- --background: oklch(1 0 0);
- --card: oklch(1 0 0);
-}
-
-.dark {
- --background: oklch(0.129 0.042 264.695);
- --card: oklch(0.208 0.042 265.755);
-}
-
-/* Map to Tailwind */
-@theme inline {
- --color-background: var(--background);
- --color-card: var(--card);
-}
-```
-
-**Benefits:**
-
-- Change `--background` in one place, entire app updates
-- Adding a new theme is just another class (`.high-contrast { --background: ... }`)
-- Clear, auditable list of all theme colours in one location
-
----
-
-### Understanding the Tailwind v4 Architecture
-
-Tailwind v4 introduced a new theming system. Here's how the layers work together:
-
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β :root / .dark β
-β βββββββββββββββββ β
-β Raw CSS variables. These store values but don't generate β
-β any Tailwind utilities. They're just data. β
-β β
-β --background: oklch(1 0 0); β
-β --primary: oklch(0.208 0.042 265.755); β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- β
- βΌ
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β @theme inline β
-β βββββββββββββββββ β
-β Maps CSS variables to Tailwind's theme system. β
-β This is where utilities get generated. β
-β β
-β --color-background: var(--background); β
-β β Generates: bg-background, text-background, border-background, etc. β
-β β
-β --color-primary: var(--primary); β
-β β Generates: bg-primary, text-primary, border-primary, etc.β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- β
- βΌ
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β @layer base β
-β βββββββββββββββββ β
-β Applies default styles to HTML elements. β
-β Lowest specificity β easily overridden. β
-β β
-β body { @apply bg-background text-foreground; } β
-β h1 { @apply text-5xl font-bold; } β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- β
- βΌ
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β @layer utilities β
-β βββββββββββββββββ β
-β Custom utility classes. Highest specificity. β
-β Use sparingly β for patterns not covered by Tailwind. β
-β β
-β .flex-center { @apply flex items-center justify-center; } β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
-The old file skips the first two layers entirely, jumping straight to utilities. This breaks the architecture.
-
----
-
-### Why `@custom-variant dark` Matters
-
-Your file includes this critical line:
-
-```css
-@custom-variant dark (&:where(.dark, .dark *));
-```
-
-**What it does:**
-
-This tells Tailwind v4 how to apply `dark:` variants. When you write `dark:bg-card`, Tailwind generates:
-
-```css
-.dark .dark\:bg-card, .dark.dark\:bg-card {
- background-color: var(--color-card);
-}
-```
-
-**Why `:where()` is used:**
-
-The `:where()` pseudo-class has zero specificity. This means:
-
-- `dark:` variants don't accidentally override other styles
-- You can still override dark styles with regular utilities if needed
-- Specificity remains predictable
-
-The old file relies on Tailwind v3's built-in `dark:` handling, which doesn't integrate with CSS variables in the same way.
-
----
-
-### The OKLCH Advantage
-
-Your file uses OKLCH colour space:
-
-```css
---primary: oklch(0.208 0.042 265.755);
-```
-
-The old file uses named colour scales that reference hex/rgb values defined elsewhere.
-
-**Why OKLCH is superior for theming:**
-
-1. **Perceptual uniformity** β Equal changes in lightness value produce equal *perceived* lightness changes. HSL doesn't guarantee this (yellow looks brighter than blue at the same L value).
-
-2. **Predictable colour manipulation** β You can programmatically generate colour scales:
-
- ```css
- --primary-50: oklch(0.95 0.042 265.755); /* Same chroma/hue, lighter */
- --primary-100: oklch(0.90 0.042 265.755);
- --primary-200: oklch(0.80 0.042 265.755);
- /* etc. */
- ```
-
-3. **Better gradients** β Gradients through OKLCH don't have the muddy middle tones that RGB gradients produce.
-
-4. **Accessibility calculations** β WCAG contrast calculations align better with OKLCH lightness than HSL.
-
----
-
-### Centralisation Score
-
-Let's quantify "centralisation" β how many places must change to update the theme:
-
-| Change | Old File | Modern File |
-|--------|-------------|-------------|
-| Update primary brand colour | ~15 classes + config | 2 lines (`:root` + `.dark`) |
-| Add high-contrast theme | Duplicate all 50+ classes | Add `.high-contrast { }` block |
-| Change all card backgrounds | Find/replace across classes | Change `--card` variable |
-| Adjust dark mode specifically | Edit every `dark:` variant | Edit `.dark { }` block only |
-| Update border colour globally | Edit multiple `.light-border-*` classes | Change `--border` variable |
-
-**Old file centralisation score: 2/10**
-**Modern file centralisation score: 9/10**
-
----
-
-### Runtime Theme Switching
-
-A key capability the modern approach enables:
-
-```typescript
-// With CSS variables (modern approach)
-function setTheme(theme: 'light' | 'dark' | 'system') {
- document.documentElement.classList.remove('light', 'dark');
- if (theme === 'system') {
- const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
- document.documentElement.classList.add(prefersDark ? 'dark' : 'light');
- } else {
- document.documentElement.classList.add(theme);
- }
-}
-// Theme switches instantly β CSS variables update, no recompilation
-```
-
-The old file approach requires the same class toggle, but the theme values are baked into utility classes at build time. The modern approach stores values in variables that the browser evaluates at runtime, enabling:
-
-- Instant theme switching without flash
-- System preference detection
-- Per-component theme overrides (nested `.dark` contexts)
-- CSS-only theme transitions
-
----
-
-### Conclusion
-
-The modern `globals.css` implements **proper separation of concerns**:
-
-1. **Data layer** (`:root`, `.dark`) β Stores theme values
-2. **Mapping layer** (`@theme inline`) β Connects values to Tailwind
-3. **Application layer** (`@layer base`) β Applies defaults to elements
-4. **Extension layer** (`@layer utilities`) β Custom utilities when needed
-
-The old file conflates all these into a single utilities layer, resulting in:
-
-- 50+ tightly-coupled utility classes
-- No single source of truth
-- Difficult theme modifications
-- Heavy `!important` usage to fight specificity
-- No runtime theme capabilities
-
-**For any Tailwind v4 project, use the CSS variable + `@theme inline` pattern.** It's the architecture Tailwind v4 was designed around, and it's what shadcn/ui, Radix, and other modern tooling expect.
diff --git a/x_docs/mine/nav_mobile_sidebar-and-rail.md b/x_docs/mine/nav_mobile_sidebar-and-rail.md
deleted file mode 100644
index 6455e39..0000000
--- a/x_docs/mine/nav_mobile_sidebar-and-rail.md
+++ /dev/null
@@ -1,255 +0,0 @@
-# Navigation Architecture: Mobile, Sidebar & Rail
-
-This document explains how the navigation system works across breakpoints, and how components are structured for reusability.
-
----
-
-## Overview
-
-The app has **three navigation contexts** that share the same nav items but render differently:
-
-| Context | Breakpoint | Container | NavLink Variant |
-| --------- | ------------ | ----------- | ----------------- |
-| Mobile Nav | `` | `rail` (icon-only) |
-| Left Sidebar | `β₯lg` (1024px+) | Persistent `` | `rail` (icon + label) |
-
----
-
-## Visual Breakdown
-
-```text
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β MOBILE (<640px) β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β Navbar: [Logo] [Theme] [Hamburger] β β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β β β
-β β When hamburger tapped β Sheet slides in from left β β
-β β β β
-β β ββββββββββββββββββββ β β
-β β β Sheet (overlay) β β β
-β β β ββββββββββββββββ β β β
-β β β β π Home β β β NavLink (mobile) β β
-β β β β π₯ Community β β β NavLink (mobile) β β
-β β β β β Collectionsβ β β NavLink (mobile) β β
-β β β β πΌ Find Jobs β β β NavLink (mobile) β β
-β β β β π·οΈ Tags β β β NavLink (mobile) β β
-β β β β β Ask β β β NavLink (mobile) β β
-β β β ββββββββββββββββ β β β
-β β β β β β
-β β β ββββββββββββββββ β β SignedOut: auth buttons β β
-β β β β [Sign in] β β β SignedIn: UserButton avatar β β
-β β β β [Sign up] β β β β
-β β β ββββββββββββββββ β β β
-β β ββββββββββββββββββββ β β
-β β β β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β TABLET (640px - 1023px) - Icon-only Rail β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β Navbar: [Logo] [Search] [Theme] [Auth] (SignedOut) β β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β ββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β Rail β β β
-β β ~64px β Main Content β β
-β β β β β
-β β π β β NavLink (rail) icon-only β β
-β β π₯ β β β
-β β β β β β
-β β πΌ β β β
-β β π·οΈ β β β
-β β β β β β
-β β β β β
-β β π€ β β UserButton (SignedIn only) β β
-β ββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β DESKTOP (β₯1024px) - Full Sidebar β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β Navbar: [Logo] [Search] [Theme] [Auth] (SignedOut) β β
-β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
-β ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β Sidebar ~220px β β β
-β β β Main Content β β
-β β π Home β β β
-β β π₯ Community β β NavLink (rail) with labels at lg+ β β
-β β β Collections β β β
-β β πΌ Find Jobs β β β
-β β π·οΈ Tags β β β
-β β β Ask β β β
-β β β β β
-β β π€ UserButton β β UserButton (SignedIn only) β β
-β ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββ β
-β β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
----
-
-## Authentication UI
-
-Auth controls appear in different locations based on screen size and auth state:
-
-| Context | Unauthenticated | Authenticated |
-| --------- | ----------------- | --------------- |
-| **Navbar** | Sign in + Sign up buttons (sm+ only) | Nothing (avatar in sidebar) |
-| **LeftSidebar** | Nothing | UserButton avatar at bottom |
-| **MobileNav** | Sign in + Sign up buttons | UserButton avatar |
-
-```text
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β Auth UI Flow: β
-β β
-β SignedOut (unauthenticated) SignedIn (authenticated) β
-β ββββββββββββββββββββββββββ ββββββββββββββββββββββββββ β
-β β Navbar: [Sign in/up] β β Navbar: [nothing] β β
-β β Sidebar: [nothing] β β Sidebar: [UserButton] β β
-β β Mobile: [Sign in/up] β β Mobile: [UserButton] β β
-β ββββββββββββββββββββββββββ ββββββββββββββββββββββββββ β
-β β
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
----
-
-## Component Architecture
-
-### Key Insight
-
-**NavLink doesn't know what container it's in.** It just renders itself with either:
-
-- `mobile` variant (default): icon + label, generous padding for touch
-- `rail` variant: responsive β icon-only at sm-lg, full at lg+
-
-The **parent component** determines the context (Sheet vs persistent sidebar).
-
-```text
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β SAME NavLink component, DIFFERENT containers & variants: β
-β β
-β MobileNav (Sheet) LeftSidebar (persistent) β
-β βββββββββββββββββββ βββββββββββββββββββ β
-β β β β β β
-β β β β β β
-β βββββββββββββββββββ βββββββββββββββββββ β
-β β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
-### Containers & Components
-
-| Component | Container Type | When Visible | NavLink Variant | Auth Section |
-| :--------- | :-------------- | :------------ | :--------------- | :------------- |
-| MobileNav | Sheet (overlay) | ` | β₯sm | `rail` (responsive) | SignedIn only (UserButton) |
-
-### Variants
-
-Two variants, but `"rail"` is **responsive** β it handles its own breakpoint transformation internally via Tailwind classes.
-
-```text
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β β
-β NavLink variants: β
-β β
-β 1. "mobile" (default) 2. "rail" (responsive) β
-β ββββββββββββββββββββ βββββββββββ ββββββββββββββββββββ β
-β β π Home β β π β β β π Home β β
-β ββββββββββββββββββββ βββββββββββ ββββββββββββββββββββ β
-β Always icon + label sm-lg: icon lg+: icon + label β
-β Generous padding (py-3) Compact (40px) Tight padding (p-2) β
-β β
-β Used in: Used in: β
-β β’ Mobile sheet β’ LeftSidebar (handles both states) β
-β β
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-```
-
----
-
-## File Structure
-
-```text
-components/navigation/
-βββ nav-links.constants.ts β NAV_LINKS array (shared data)
-βββ navbar.tsx β Top bar with logo, search, auth
-βββ mobile-nav.tsx β Sheet drawer for mobile (> $GITHUB_OUTPUT
-
-- name: Cache Playwright browsers
- uses: actions/cache@
- id: playwright-cache
- with:
- path: ~/.cache/ms-playwright
- key: playwright-browsers-${{ steps.playwright-version.outputs.PLAYWRIGHT_VERSION }}-${{ runner.os }}
-
-- name: Install Playwright Browsers
- if: steps.playwright-cache.outputs.cache-hit != 'true'
- run: npx playwright install chromium firefox webkit --with-deps
-```
-
-**Impact:** 30-60s faster E2E workflow, reduced bandwidth costs. **Effort:** 5 minutes.
-**Source:** eval.github-actions.md (Recommendation #2)
-
----
diff --git a/x_docs/textbook/url-state.md b/x_docs/textbook/url-state.md
new file mode 100644
index 0000000..c92801a
--- /dev/null
+++ b/x_docs/textbook/url-state.md
@@ -0,0 +1,38 @@
+# State Management Notes
+
+## Typtes of State Management
+
+1. **State management defined**: It's how you track and organize data in your app (scores, user info, UI states) so your application knows what's happening and can react accordingly.
+
+2. **Local state** is contained within a single component, managed with hooks like `useState`. Other components can't access it unless you explicitly pass it down as props.
+
+3. **Global state** is stored in a centralized location (like a context or store) and can be accessed by any component in the appβsolving the "prop drilling" problem where you'd otherwise have to pass data through many layers of components.
+
+4. **Context API** is React's built-in solution for global state. The pattern is: create a context β wrap your app in a Provider β access the state anywhere using a custom hook (like `useCounter`). Good enough for simple cases β passing down a theme, user auth, or locale works great
+
+5. **Other popular options** exist beyond Context API, each with tradeoffs:
+ - **Redux** β structured approach with actions/reducers (more boilerplate, good for complex apps)
+ - **Zustand** β lightweight, hook-based (simpler API)
+ - **Recoil** β atom-based state (fine-grained updates)
+ - **MobX** β reactive/observable pattern (minimal setup)
+
+The core concept to internalize: *local state for component-specific data, global state for data that multiple components need to share*.
+
+**Rule of thumb:**
+
+- Use **Context API** for infrequently changing, app-wide data (auth, theme, language)
+- Use **Zustand** (or Redux, etc.) when state changes often or you need fine-grained control over re-renders
+
+## URL State Management
+
+Here are the 5 key points reframed for instructing Claude Code effectively:
+
+1. **The problem with traditional state libraries in Next.js**: Redux, Zustand, and Context API all require hooks, which force components to become client-side. This undermines Next.js's server-rendering benefits. When instructing Claude Code, you can say things like "keep this as a server component" or "avoid client-side state here."
+
+2. **URL state management** is the server-friendly alternative. Instead of storing data in React state, you store it in the URL's query parameters (e.g., `?sort=price&page=2`). Key terms: "query parameters," "searchParams," "URL state." You can tell Claude Code: "use URL state management instead of useState" or "store the filter selection in searchParams."
+
+3. **Reading URL data**: In page components, you access `params` (dynamic route segments like `/books/[id]`) and `searchParams` (query string values like `?page=2`) as props. In nested components, you'd use the `useSearchParams` hook. Useful phrase: "pass searchParams down as props to avoid making this a client component."
+
+4. **Writing/updating URL state**: The main approaches are ` 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+```
+
+
alt="Open in Gitpod">
+ 
+