Htmx/templates/docs/index.html

{% extends "base.html" %}

{% block title %}Design System Wiki - Stick{% endblock %}

{% block content %}
<div class="grow max-w-7xl mx-auto w-full px-4 sm:px-6 lg:px-8 py-10 flex flex-col lg:flex-row gap-8">
    
    <!-- Left Floating Sidebar Navigation -->
    {% include "docs/sidebar.html" %}

    <!-- Main Content Area -->
    <div class="flex-1 space-y-10">
        
        <!-- Intro Header -->
        <div class="pb-6 border-b border-border">
            <span class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-full text-xs font-medium bg-indigo-500/10 text-indigo-400 border border-indigo-500/20 mb-3 animate-pulse">
                Stick Design System Wiki
            </span>
            <h1 class="text-3xl font-extrabold text-slate-100 tracking-tight">Component Reference Manual</h1>
            <p class="text-muted-foreground text-sm mt-2 leading-relaxed">
                Welcome to the Stick design system Wiki. This documentation serves as a living blueprint detailing HTML structures, Tailwind CSS custom variables, and JavaScript trigger hooks required to build premium, high-fidelity interactive elements using the Shadcn aesthetic.
            </p>
        </div>

        <!-- Architecture & Concept -->
        <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
            <div class="border border-border bg-secondary/10 rounded-2xl p-6 space-y-3">
                <div class="w-10 h-10 rounded-xl bg-sky-500/10 border border-sky-500/20 flex items-center justify-center">
                    <svg class="h-5 w-5 text-sky-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
                        <path stroke-linecap="round" stroke-linejoin="round" d="M4 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2V6zM14 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V6zM4 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2v-2zM14 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z"/>
                    </svg>
                </div>
                <h3 class="text-sm font-bold text-slate-200">Vertical Feature Architecture</h3>
                <p class="text-xs text-muted-foreground/90 leading-relaxed">
                    The backend routes and documentation handlers are located under <code>src/docs/</code>. Shared components reside in <code>templates/components/</code>. The rest of the application is packaged inside clean vertical feature directories (e.g. <code>src/auth/</code>, <code>src/tasks/</code>, <code>src/audit/</code>).
                </p>
            </div>
            
            <div class="border border-border bg-secondary/10 rounded-2xl p-6 space-y-3">
                <div class="w-10 h-10 rounded-xl bg-emerald-500/10 border border-emerald-500/20 flex items-center justify-center">
                    <svg class="h-5 w-5 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
                        <path stroke-linecap="round" stroke-linejoin="round" d="M13 10V3L4 14h7v7l9-11h-7z"/>
                    </svg>
                </div>
                <h3 class="text-sm font-bold text-slate-200">Lightweight & Dependency-Free</h3>
                <p class="text-xs text-muted-foreground/90 leading-relaxed">
                    Designed to minimize heavy JS bundles. Using vanilla JavaScript with document-level event delegation (e.g. for Modals, Sheets, Accordions, and Tabs) keeping the interactive shell fast and responsive.
                </p>
            </div>
        </div>

        <!-- Custom Styling tokens -->
        <div class="space-y-4">
            <h2 class="text-lg font-bold text-slate-250">Global HSL Tokens</h2>
            <p class="text-xs text-muted-foreground">
                The layout relies on standard Tailwind themes mapped onto raw HSL variables, allowing instant utility customization.
            </p>
            
            <div class="border border-border bg-card/50 rounded-2xl p-5 overflow-x-auto">
                <table class="w-full border-collapse text-left text-xs">
                    <thead>
                        <tr class="border-b border-border text-muted-foreground font-bold">
                            <th class="pb-2.5">Variable</th>
                            <th class="pb-2.5">Raw HSL Mapping</th>
                            <th class="pb-2.5">Render Example</th>
                        </tr>
                    </thead>
                    <tbody class="divide-y divide-border/40 text-muted-foreground font-mono text-[11px]">
                        <tr>
                            <td class="py-2 text-muted-foreground font-sans font-semibold">--background</td>
                            <td class="py-2">224 71% 4%</td>
                            <td class="py-2">
                                <div class="w-4 h-4 rounded bg-[#030712] border border-border"></div>
                            </td>
                        </tr>
                        <tr>
                            <td class="py-2 text-muted-foreground font-sans font-semibold">--primary</td>
                            <td class="py-2">210 40% 98%</td>
                            <td class="py-2">
                                <div class="w-4 h-4 rounded bg-[#f8fafc]"></div>
                            </td>
                        </tr>
                        <tr>
                            <td class="py-2 text-muted-foreground font-sans font-semibold">--border / --input</td>
                            <td class="py-2">216 34% 17%</td>
                            <td class="py-2">
                                <div class="w-4 h-4 rounded bg-[#1e293b]"></div>
                            </td>
                        </tr>
                        <tr>
                            <td class="py-2 text-muted-foreground font-sans font-semibold">--ring</td>
                            <td class="py-2">216 12.2% 83.9%</td>
                            <td class="py-2">
                                <div class="w-4 h-4 rounded ring-2 ring-slate-400"></div>
                            </td>
                        </tr>
                    </tbody>
                </table>
            </div>
        </div>

        <!-- Architecture & Contract Philosophy -->
        <div class="space-y-4 border-t border-border/60 pt-8">
            <h2 class="text-lg font-bold text-slate-200">Understanding the JS Binding Architecture</h2>
            <p class="text-xs text-muted-foreground leading-relaxed">
                Rather than attaching active event listeners to every individual DOM node, the design system utilizes <strong>document-level event delegation</strong> and <strong>global query selector hooks</strong>. This keeps page loads incredibly fast and handles dynamically rendered components automatically.
            </p>
            
            <div class="rounded-2xl border border-indigo-500/20 bg-indigo-500/5 p-5 text-xs space-y-4">
                <div>
                    <span class="font-bold text-indigo-400 block mb-1">🔗 The Core Binding Contract</span>
                    <p class="text-slate-400 leading-normal">
                        To make components interactive, they must contain specific functional CSS classes or attributes (e.g., <code>.modal-dialog</code>, <code>[data-modal-target]</code>, <code>.custom-select</code>) that the Javascript file uses to query the DOM. If these functional hooks are missing or renamed, the interactivity will fail.
                    </p>
                </div>
                
                <div>
                    <span class="font-bold text-indigo-400 block mb-1">🎨 What is Customizable vs. Fixed?</span>
                    <ul class="list-disc pl-5 space-y-1.5 text-slate-400 leading-normal">
                        <li>
                            <strong class="text-slate-200">Fixed (Functional) Hooks:</strong> Standard semantic class names (like <code>.modal-dialog</code>, <code>.modal-content</code>, <code>.modal-backdrop</code>, <code>.modal-close</code>, <code>.select-trigger</code>, and <code>.select-item</code>) are required structure hooks. These must remain unchanged because our JavaScript code expects them to animate opacity, visibility, translation transform stages, and handle keydown events.
                        </li>
                        <li>
                            <strong class="text-slate-200">Customizable (Styling) Rules:</strong> Any Tailwind visual classes (like colors e.g. <code>bg-slate-900</code>, padding/margin <code>p-6 mt-2</code>, border-radius <code>rounded-3xl</code>, drop shadows <code>shadow-xl</code>, borders <code>border-border</code>, and custom fonts) can be modified, replaced, or completely restyled. As long as you maintain the core HTML nesting hierarchy and functional selector names, the component will work perfectly.
                        </li>
                    </ul>
                </div>
                <div>
                    <span class="font-bold text-indigo-400 block mb-1">📱 Mobile-First Responsive Layout</span>
                    <p class="text-slate-400 leading-normal">
                        The navigation elements use responsive design classes to ensure compatibility across screen sizes:
                    </p>
                    <ul class="list-disc pl-5 mt-1.5 space-y-1.5 text-slate-400 leading-normal">
                        <li>
                            <strong class="text-slate-200">Responsive App Navbar:</strong> The master header navigation switches from a horizontal desktop layout (<code>hidden md:flex</code>) to a mobile hamburger menu button (<code>flex md:hidden</code>). The button targets a sliding navigation drawer (<code>#mobile-nav-sheet</code>) that transitions in from the right.
                        </li>
                        <li>
                            <strong class="text-slate-200">Collapsible Wiki Directory:</strong> On documentation views, the large guides sidebar is hidden on mobile devices (<code>hidden lg:block</code>) and replaced with an inline trigger bar (<code>Explore Guides</code>). Clicking this trigger transitions the guides directory drawer (<code>#wiki-sidebar-sheet</code>) from the left.
                        </li>
                    </ul>
                </div>
            </div>
        </div>

    </div>
</div>
{% endblock %}