@thorprovider/create-storefront 0.1.1

package/skills/nextjs-shadcn/references/shadcn-platform.md

@@ -0,0 +1,258 @@
+# shadcn Platform
+
+The parts of shadcn that are not individual components: which primitive base to
+build on, the CLI verbs worth knowing, and the CSS-level systems (typeset,
+shimmer, scroll-fade).
+
+## Choosing a base (do this first)
+
+shadcn components ship on three primitive libraries: Base UI, Radix, and React
+Aria. **Base UI is the default.** The choice is per-project and set at `init` —
+components installed later inherit it.
+
+```bash
+bunx --bun shadcn@latest init --template next --base base   # Base UI (default)
+bunx --bun shadcn@latest init --template next --base radix  # Radix (legacy projects)
+bunx --bun shadcn@latest init --template next --base aria   # React Aria
+```
+
+| Base | Pick it when |
+|------|-------------|
+| `base` | New projects. Default since July 2026, most actively developed, gets new components first. |
+| `radix` | Existing codebase already on Radix, or a dependency expects Radix primitives. |
+| `aria` | Accessibility/interaction requirements beyond the defaults — React Aria's behavior hooks. |
+
+**Why this matters for generated code:** the same component name has different
+props and sub-components per base. Docs are base-scoped too —
+`ui.shadcn.com/docs/components/base/sidebar` vs `.../radix/sidebar`. Never write
+component code from memory without knowing the project's base.
+
+The difference that bites most often: **Base UI composes through a `render`
+prop, Radix through `asChild`.**
+
+```tsx
+// Base UI (default) — element goes in render, children stay as children
+<SidebarMenuButton render={<Link href="/inbox" />}>
+  <Inbox />
+  <span>Inbox</span>
+</SidebarMenuButton>
+
+// Radix — element wraps the children
+<SidebarMenuButton asChild>
+  <Link href="/inbox">
+    <Inbox />
+    <span>Inbox</span>
+  </Link>
+</SidebarMenuButton>
+```
+
+Read the base from `components.json` (or `shadcn info --json`) before editing an
+existing project.
+
+`migrate radix` does **not** switch a project from Radix to Base UI — it rewrites
+`@radix-ui/react-*` imports to the single `radix-ui` package. Radix → Base UI is
+a component-at-a-time migration driven by the official shadcn skill:
+
+```bash
+bunx --bun skills add shadcn/ui
+# then ask the agent: "migrate accordion to base-ui"
+```
+
+Both libraries stay installed while you work, each component lands in its own
+commit, and every run writes a report to `.migration/<component>.md`.
+
+## CLI verbs beyond `add`
+
+`add` and `init` are the familiar ones. These four are what make the CLI useful
+to an agent:
+
+```bash
+shadcn info --json              # project config: framework, base, tailwind, aliases, installed components
+shadcn docs button              # API reference for a component, resolved to THIS project's base
+shadcn docs button --json       # machine-readable, for piping into context
+shadcn view button card         # inspect registry item source before installing
+shadcn search @shadcn -q chart  # search a registry namespace
+```
+
+**Prefer `shadcn docs <component>` over recalling props from memory or fetching
+`llms.txt`** — it resolves against the project's actual base and version. Use
+`shadcn view` before `add` when you are unsure what a registry item pulls in.
+
+Other verbs: `add <component> --diff` (upstream changes to an installed
+component — the standalone `diff` command is deprecated), `apply <preset>`
+(apply a preset to an existing project; `--only theme,font` for just those
+parts), `preset decode|resolve|url|open` (inspect a preset code), `build`
+(generate registry JSON), `migrate` (`icons`, `rtl`, `radix`), `eject` (inline
+`shadcn/tailwind.css` and drop the `shadcn` dependency).
+
+### `migrate icons`
+
+Swapping icon libraries across a whole project is a single command:
+
+```bash
+bunx --bun shadcn@latest migrate icons --from lucide --to phosphor
+```
+
+## The official shadcn skill
+
+shadcn publishes its own agent skill, which injects live project config
+(`shadcn info --json`) plus the full CLI and registry reference:
+
+```bash
+bunx --bun skills add shadcn/ui
+```
+
+It activates when the project has a `components.json`. It covers CLI mechanics
+and registry authoring — **this skill covers project conventions, architecture,
+and Next.js integration instead.** Install both; don't duplicate CLI reference
+material here.
+
+There is also an MCP server for registry search and install from within the
+editor — wire it into Claude Code with
+`bunx --bun shadcn@latest mcp init --client claude`.
+
+## Typeset — styling rendered markdown
+
+One CSS file you own that styles headings, paragraphs, lists, tables and code
+inside a wrapper class. Replaces hand-written `prose`-style overrides and
+per-context markdown CSS.
+
+**Use it for:** chat message bodies, docs pages, blog posts, LLM-streamed
+markdown — anywhere you render HTML you did not author.
+
+Typeset is **not** part of `init` and has no `add` command. Generate the file in
+the builder at [ui.shadcn.com/typeset](https://ui.shadcn.com/typeset), drop it
+next to your main CSS, and import it after Tailwind:
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "./typeset.css";
+```
+
+Three variables drive the whole rhythm; everything else derives from them:
+
+```css
+.typeset {
+  --typeset-font-body: inherit;
+  --typeset-font-heading: var(--font-heading);
+  --typeset-font-mono: var(--font-mono);
+  --typeset-size: 1em;      /* base text size */
+  --typeset-leading: 1.75;  /* line-height */
+  --typeset-flow: 1.25em;   /* space between blocks */
+}
+```
+
+Define one preset per context and apply both classes:
+
+```css
+.typeset-docs {
+  --typeset-size: 15px;
+  --typeset-leading: 1.75;
+  --typeset-flow: 1.25em;
+}
+
+.typeset-chat {
+  --typeset-leading: 1.6;
+  --typeset-flow: 1em;   /* tighter — chat bubbles are short */
+}
+```
+
+```tsx
+<div className="typeset typeset-chat">
+  <Response>{message}</Response>
+</div>
+```
+
+It is container-aware (sizes to its container, not just the viewport) and
+**streaming-stable**: appending a new block does not restyle blocks already
+rendered above it. That property is the reason to prefer it over ad-hoc CSS in
+streaming chat UIs.
+
+## Shimmer — loading and processing text
+
+CSS-only animated sweep across text. No component, no JS.
+
+```tsx
+<p className="shimmer text-muted-foreground">Generating response…</p>
+```
+
+| Class | Effect |
+|-------|--------|
+| `shimmer-color-<color>` | Highlight color, e.g. `shimmer-color-blue-500/60` |
+| `shimmer-duration-<ms>` | Sweep speed (default 2000) |
+| `shimmer-spread-<n>` | Width of the highlight band |
+| `shimmer-angle-<deg>` | Tilt (default 20) |
+| `shimmer-once` | Single sweep instead of looping |
+| `shimmer-reverse` | Reverse direction |
+
+Adapts to the element's text color, brightens in dark mode, respects
+`prefers-reduced-motion` and RTL automatically.
+
+**Use shimmer for indeterminate text states** ("Thinking…", "Searching…") and
+`Skeleton` for layout placeholders with known shape. Don't stack both.
+
+## Scroll-fade — soft scroll container edges
+
+Masks the content itself at the edges of a scroll container rather than
+overlaying a gradient, so it works on any background.
+
+```tsx
+<div className="scroll-fade overflow-y-auto">{/* content */}</div>
+```
+
+| Class | Effect |
+|-------|--------|
+| `scroll-fade` / `scroll-fade-y` | Vertical |
+| `scroll-fade-x` | Horizontal |
+| `scroll-fade-t` / `-b` / `-l` / `-r` | Single edge |
+| `scroll-fade-s` / `-e` | Start/end edge (RTL-aware) |
+| `scroll-fade-<n>` | Fade depth on the spacing scale |
+| `scroll-fade-none` | Disable |
+
+Scroll-aware: the top edge stays crisp until you scroll away from it.
+
+Both `shimmer` and `scroll-fade` come from `shadcn/tailwind.css`, which `init`
+wires up. In a project that skipped it:
+
+```css
+@import "tailwindcss";
+@import "shadcn/tailwind.css";
+```
+
+## RTL support
+
+Sidebar and the CSS utilities are RTL-aware. Opt in at init with `--rtl`,
+retrofit an existing project with `migrate rtl`, and pass `dir` on the `Sidebar`
+component. Prefer logical utilities (`ms-`/`me-`, `scroll-fade-s/-e`)
+over physical ones (`ml-`/`mr-`) in any project that might need it.
+
+## Package imports (alias alternative)
+
+Projects may use Node package imports instead of `tsconfig.json` paths:
+
+```json
+// package.json
+{ "imports": { "#components/*": "./src/components/*.tsx", "#lib/*": "./src/lib/*.ts" } }
+```
+
+```tsx
+import { Button } from "#components/ui/button";
+import { cn } from "#lib/utils";
+```
+
+Requires `moduleResolution: "bundler"` and `resolvePackageJsonImports: true`, and
+the matching `aliases` block in `components.json`. The CLI rewrites imports to
+whichever alias style is configured.
+
+**Default to `@/` for new projects.** In an existing project, read
+`components.json` and follow what is already there — never mix both styles.
+
+## Registries
+
+Beyond `@shadcn`, the CLI resolves namespaced registries (`@acme/button`),
+including private and GitHub-hosted ones. If you author a registry with more
+than a few hundred items, implement
+[dynamic search](https://ui.shadcn.com/docs/registry/dynamic-search) so
+`shadcn search` filters server-side instead of downloading the whole catalog.
+Not needed for consuming registries.

package/skills/nextjs-shadcn/references/sidebar.md

@@ -0,0 +1,274 @@
+# Sidebar
+
+shadcn/ui sidebar with nested layouts for dashboard applications.
+
+## Start from a block, not from scratch
+
+Before hand-writing an `AppSidebar`, check whether a block already matches the
+shape you need. A block installs a complete, working sidebar you then edit —
+faster and less error-prone than assembling sub-components by hand.
+
+```bash
+bunx --bun shadcn@latest add sidebar-07
+```
+
+| Block | Shape |
+|-------|-------|
+| `sidebar-01` | Navigation grouped by section (simplest) |
+| `sidebar-02` | Collapsible sections |
+| `sidebar-03` | Submenus |
+| `sidebar-04` | Floating sidebar with submenus |
+| `sidebar-05` | Collapsible submenus |
+| `sidebar-06` | Submenus as dropdowns |
+| `sidebar-07` | Collapses to icons — the common dashboard default |
+| `sidebar-08` | Inset sidebar with secondary navigation |
+| `sidebar-09` | Collapsible nested sidebars |
+| `sidebar-10` | Sidebar in a popover |
+| `sidebar-11` | Collapsible file tree |
+| `sidebar-12` | Sidebar with a calendar |
+| `sidebar-13` | Sidebar in a dialog |
+| `sidebar-14` | Sidebar on the right |
+| `sidebar-15` | Left and right sidebar |
+| `sidebar-16` | Sticky site header |
+
+Preview them at [ui.shadcn.com/blocks/sidebar](https://ui.shadcn.com/blocks/sidebar).
+Use `shadcn view sidebar-07` to read the source before installing.
+
+The patterns below are for when no block fits, or when adapting one.
+
+## Installation
+
+```bash
+bunx --bun shadcn@latest add sidebar
+```
+
+The sidebar API differs between Base UI, Radix and React Aria. Check the
+project's base (`shadcn info --json`) and read
+`shadcn docs sidebar` rather than assuming — the examples below target Base UI,
+the current default. The difference that shows up in every example: Base UI
+composes through a `render` prop (`<SidebarMenuButton render={<Link href="/" />}>`
+with the icon and label as children), where Radix wraps the children in `asChild`.
+
+## Layout Pattern
+
+Use nested layouts with SidebarProvider for persistent sidebar state:
+
+```
+app/
+├── (dashboard)/           # Route group for sidebar pages
+│   ├── layout.tsx         # SidebarProvider + AppSidebar
+│   ├── page.tsx           # Dashboard home
+│   ├── settings/
+│   │   └── page.tsx
+│   └── components/        # Route-specific components
+├── (public)/              # Public routes (no sidebar)
+│   └── login/
+└── layout.tsx             # Root layout
+```
+
+### Dashboard Layout
+
+```tsx
+// app/(dashboard)/layout.tsx
+import { AppSidebar } from "@/components/layout/app-sidebar"
+import {
+  SidebarInset,
+  SidebarProvider,
+} from "@/components/ui/sidebar"
+
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <SidebarProvider>
+      <AppSidebar />
+      <SidebarInset>{children}</SidebarInset>
+    </SidebarProvider>
+  )
+}
+```
+
+### Page Component
+
+Keep pages clean - content only, no layout chrome:
+
+```tsx
+// app/(dashboard)/page.tsx
+import { DocumentWorkspace } from "@/components/workspace/document-workspace"
+import { Suspense } from "react"
+
+export default function DashboardPage() {
+  return (
+    <Suspense fallback={<DashboardSkeleton />}>
+      <DocumentWorkspace />
+    </Suspense>
+  )
+}
+```
+
+## AppSidebar Component
+
+```tsx
+// components/layout/app-sidebar.tsx
+import Link from "next/link"
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+  SidebarSeparator,
+} from "@/components/ui/sidebar"
+import { NAV_GROUPS, FOOTER_NAV_ITEMS } from "./nav"
+
+export function AppSidebar() {
+  return (
+    <Sidebar variant="inset" collapsible="icon">
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              size="lg"
+              render={<Link href="/" className="flex items-center gap-3" />}
+            >
+              <Logo className="size-8" />
+              <span className="text-base font-semibold">App Name</span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+
+      <SidebarContent>
+        {NAV_GROUPS.map((group, index) => (
+          <div key={group.title}>
+            <SidebarGroup>
+              <SidebarGroupLabel>{group.title}</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  {group.items.map((item) => (
+                    <SidebarMenuItem key={item.title}>
+                      <SidebarMenuButton render={<Link href={item.href} />}>
+                        <item.icon />
+                        <span>{item.title}</span>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  ))}
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+            {index < NAV_GROUPS.length - 1 && <SidebarSeparator />}
+          </div>
+        ))}
+      </SidebarContent>
+
+      <SidebarFooter>
+        <SidebarSeparator />
+        <SidebarMenu>
+          {FOOTER_NAV_ITEMS.map((item) => (
+            <SidebarMenuItem key={item.title}>
+              <SidebarMenuButton render={<Link href={item.href} />}>
+                <item.icon />
+                <span>{item.title}</span>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarFooter>
+
+      <SidebarRail />
+    </Sidebar>
+  )
+}
+```
+
+## Navigation Config
+
+Separate navigation data from component:
+
+```tsx
+// components/layout/nav.ts
+import { Home, Settings, Users, HelpCircle } from "lucide-react"
+import type { LucideIcon } from "lucide-react"
+
+interface NavItem {
+  title: string
+  href: string
+  icon: LucideIcon
+}
+
+interface NavGroup {
+  title: string
+  items: NavItem[]
+}
+
+export const NAV_GROUPS: NavGroup[] = [
+  {
+    title: "Main",
+    items: [
+      { title: "Dashboard", href: "/", icon: Home },
+      { title: "Users", href: "/users", icon: Users },
+    ],
+  },
+]
+
+export const FOOTER_NAV_ITEMS: NavItem[] = [
+  { title: "Settings", href: "/settings", icon: Settings },
+  { title: "Help", href: "/help", icon: HelpCircle },
+]
+```
+
+## Sidebar Variants
+
+| Variant | Description |
+|---------|-------------|
+| `sidebar` | Standard sidebar (default) |
+| `inset` | Sidebar with padding, content area has rounded corners |
+| `floating` | Sidebar floats over content |
+
+```tsx
+<Sidebar variant="inset" collapsible="icon">
+```
+
+## Collapsible Options
+
+| Option | Behavior |
+|--------|----------|
+| `icon` | Collapses to icon-only rail |
+| `offcanvas` | Slides completely off-screen |
+| `none` | Not collapsible |
+
+## RTL
+
+`Sidebar` takes a `dir` prop and positions via `data-side` attributes, so
+right-to-left layouts work without JS conditionals — `SidebarTrigger` flips its
+icon automatically. Opt in project-wide at `init` with `--rtl`, or retrofit with
+`shadcn migrate rtl`. In any project that might need RTL, use logical utilities
+(`ms-`/`me-`, `ps-`/`pe-`) instead of `ml-`/`mr-` in sidebar markup.
+
+## Persisting open state
+
+`SidebarProvider` takes `defaultOpen` (uncontrolled) or `open` / `onOpenChange`
+(controlled); width comes from the `--sidebar-width` CSS variable. To keep the
+sidebar's state across reloads without a hydration mismatch, read a cookie in the
+layout Server Component and pass it to `defaultOpen` — don't read it client-side
+in an effect.
+
+For custom triggers, `useSidebar()` exposes `toggleSidebar`, `isMobile`, and the
+mobile-specific `openMobile` / `setOpenMobile`.
+
+## File Structure
+
+```
+components/
+└── layout/
+    ├── app-sidebar.tsx    # Sidebar component
+    └── nav.ts             # Navigation config
+```