@thorprovider/storefront 0.3.1

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

@@ -0,0 +1,555 @@
+# Styling
+
+## Theme System
+
+### globals.css Structure
+
+shadcn generates base variables automatically based on your chosen preset. Customize for your project:
+
+```css
+@import "tailwindcss";
+
+/* Note: Tailwind v3 projects use @tailwind base; @tailwind components; @tailwind utilities; instead */
+
+/* :root and .dark live OUTSIDE @layer base and hold full color values (OKLCH preferred) */
+:root {
+  /* shadcn base variables come from preset */
+  --background: ...;
+  --foreground: ...;
+  --primary: ...;
+  --secondary: ...;
+  /* etc. */
+
+  /* Add your own variables as needed */
+  --brand: oklch(0.55 0.2 260);
+}
+
+.dark {
+  --brand: oklch(0.7 0.18 260);
+}
+
+@theme inline {
+  --color-brand: var(--brand);
+}
+```
+
+The `@theme inline` mapping is what makes the `bg-brand` / `text-brand` utilities work — a variable without it generates no utility.
+
+**Choose preset**: Use [ui.shadcn.com/create](https://ui.shadcn.com/create) to select named style (vega, nova, maia, lyra, mira, luma, sera, rhea), base color, font, icon library, and radius. The customizer outputs a single preset code that encodes all choices.
+
+### Theme Customization
+
+Quick customizations in `globals.css`:
+
+```css
+:root {
+  /* Typography - change fonts */
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-serif: Georgia, serif;
+  --font-mono: "Fira Code", ui-monospace, monospace;
+
+  /* Border radius - affects all rounded corners */
+  --radius: 0.5rem;       /* Default */
+  /* --radius: 0.25rem;   /* Sharp */
+  /* --radius: 0.75rem;   /* More rounded */
+  /* --radius: 1rem;      /* Very rounded */
+  /* --radius: 1.3rem;    /* Pill-like buttons */
+}
+```
+
+| Variable | Effect |
+|----------|--------|
+| `--font-sans` | Body text, buttons, inputs |
+| `--font-mono` | Code blocks, technical content |
+| `--radius` | All rounded corners (buttons, cards, inputs) |
+
+**Tip**: Larger `--radius` values (1rem+) give a softer, more modern look. Smaller values (0.25rem) feel sharper and technical.
+
+### Using Theme Colors
+
+```tsx
+// ✅ Use CSS variables
+<div className="bg-primary text-primary-foreground" />
+<div className="border-border" />
+<div className="text-muted-foreground" />
+
+// ❌ Never hardcode colors
+<div className="bg-blue-500" />
+<div className="text-[#1a1a1a]" />
+```
+
+## shadcn/ui Presets
+
+Available styles at ui.shadcn.com/create:
+
+| Preset | Character |
+|--------|-----------|
+| vega | Classic shadcn/ui look. Clean, neutral, familiar |
+| nova | Reduced padding and margins for compact layouts |
+| maia | Soft and rounded, with generous spacing |
+| lyra | Boxy and sharp. Pairs well with mono fonts |
+| mira | Compact. Made for dense interfaces |
+| luma | Newer official style — see ui.shadcn.com/create |
+| sera | Newer official style — see ui.shadcn.com/create |
+| rhea | A more compact Luma. Tighter spacing, smaller controls, denser surfaces — built for focused product interfaces |
+
+### Fonts
+
+Body/mono fonts the preset builder offers (these ids are what the preset code
+encodes — `shadcn preset decode <code>` prints them back):
+
+| Font | Type | Character |
+|------|------|-----------|
+| geist | Sans | Vercel's modern geometric sans |
+| inter | Sans | Clean, versatile (classic default) |
+| figtree | Sans | Friendly, geometric |
+| dm-sans | Sans | Compact geometric with character |
+| outfit | Sans | Modern, soft |
+| noto-sans | Sans | Universal language support |
+| nunito-sans | Sans | Rounded, approachable |
+| roboto | Sans | Google's versatile sans |
+| raleway | Sans | Elegant, thin-weight display |
+| public-sans | Sans | US government standard, neutral |
+| jetbrains-mono | Mono | Developer-focused monospace |
+| geist-mono | Mono | Vercel's monospace |
+
+Heading fonts (`fontHeading`) are a separate, longer list — lora, merriweather,
+playfair-display, noto-serif, roboto-slab, oxanium, manrope, space-grotesk,
+montserrat, ibm-plex-sans, source-sans-3, instrument-sans, eb-garamond,
+instrument-serif. It defaults to `inherit` (same face as the body).
+
+## Icon Libraries
+
+Priority order (use first available). The names below are the CLI's library ids —
+pass them verbatim to `shadcn migrate icons --from <id> --to <id>`:
+
+1. **lucide** (default) - `yarn add lucide-react`
+2. **tabler** - `yarn add @tabler/icons-react`
+3. **hugeicons** - `yarn add @hugeicons/react @hugeicons/core-free-icons` (the old `hugeicons-react` package is deprecated)
+4. **phosphor** - `yarn add @phosphor-icons/react`
+5. **remixicon** - `yarn add @remixicon/react`
+
+```tsx
+// lucide example
+import { ChevronRight, Menu, X } from "lucide-react"
+
+<Button>
+  Next <ChevronRight data-icon="inline-end" />
+</Button>
+```
+
+## Animations
+
+### CSS Page Transitions
+
+Add to `globals.css`:
+
+```css
+@keyframes page-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@layer utilities {
+  .animate-page-in {
+    animation: page-in 0.6s ease-out both;
+  }
+}
+```
+
+Usage in layout or template:
+
+```tsx
+// template.tsx - animates on every navigation
+export default function Template({ children }: { children: React.ReactNode }) {
+  return <main className="animate-page-in">{children}</main>
+}
+```
+
+### View Transitions API
+
+No config needed. View transitions work in the App Router out of the box — it
+runs React canary releases, which ship `ViewTransition`. The old
+`experimental.viewTransition` flag is gone from Next.js 16's config type; adding
+it now is a type error, not a no-op.
+
+Wrap what should animate in React's `<ViewTransition>` — no extra install.
+Without browser support it degrades gracefully: no animation, app still works.
+
+```tsx
+import { ViewTransition } from "react"
+```
+
+`<ViewTransition>` animations fire on Transitions, `<Suspense>`, and
+`useDeferredValue`. Route navigations are Transitions, so they activate
+automatically on navigation; plain `setState` does not trigger them.
+
+| Pattern | Communicates | Key API |
+|---------|--------------|---------|
+| Shared-element morph | "Same thing, going deeper" | Same `name` on both elements |
+| Suspense reveal | "Data loaded" | `enter`/`exit` on fallback + content, `default="none"` |
+| Directional slide | "Forward / back" | `<Link transitionTypes={["nav-forward"]}>` + `enter`/`exit` keyed by type |
+| Same-route crossfade | "Same place, different content" | `key={slug}` + `share="auto"` `enter="auto"` |
+
+Shared-element morph is the most common and works with zero CSS — wrap both the
+source and destination element with the same `name`:
+
+```tsx
+// grid thumbnail
+<ViewTransition name={`photo-${photo.id}`}>
+  <Image src={photo.src} alt={photo.title} />
+</ViewTransition>
+
+// detail page hero — same name
+<ViewTransition name={`photo-${photo.id}`}>
+  <Image src={photo.src} alt={photo.title} fill />
+</ViewTransition>
+```
+
+React matches the names across the old/new route and animates size and
+position. Customize with `share="morph"` and `::view-transition-group(.morph)`
+CSS. Respect `prefers-reduced-motion` by zeroing animation durations on the
+`::view-transition-*` pseudo-elements.
+
+Patterns 2–4 (CSS keyframes, directional/Suspense examples):
+[Designing view transitions](https://nextjs.org/docs/app/guides/view-transitions).
+
+### Motion Library
+
+For complex animations:
+
+```bash
+yarn add motion
+```
+
+```tsx
+"use client"
+
+import { motion, HTMLMotionProps } from "motion/react"
+
+interface FadeInProps extends HTMLMotionProps<"div"> {
+  delay?: number
+  duration?: number
+  direction?: "up" | "down" | "left" | "right" | "none"
+}
+
+export function FadeIn({
+  children,
+  className,
+  delay = 0,
+  duration = 0.5,
+  direction = "up",
+  ...props
+}: FadeInProps) {
+  const directions = {
+    up: { y: 20, x: 0 },
+    down: { y: -20, x: 0 },
+    left: { x: 20, y: 0 },
+    right: { x: -20, y: 0 },
+    none: { x: 0, y: 0 },
+  }
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, ...directions[direction] }}
+      whileInView={{ opacity: 1, x: 0, y: 0 }}
+      viewport={{ once: true, margin: "-50px" }}
+      transition={{ duration, delay, ease: "easeOut" }}
+      className={className}
+      {...props}
+    >
+      {children}
+    </motion.div>
+  )
+}
+```
+
+### GSAP
+
+For scroll-triggered and complex sequences:
+
+```bash
+yarn add gsap @gsap/react
+```
+
+```tsx
+"use client"
+
+import { useRef } from "react"
+import { useGSAP } from "@gsap/react"
+import gsap from "gsap"
+import { ScrollTrigger } from "gsap/ScrollTrigger"
+
+gsap.registerPlugin(ScrollTrigger)
+
+export function ScrollReveal({ children }) {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  useGSAP(() => {
+    gsap.from(containerRef.current, {
+      opacity: 0,
+      y: 50,
+      scrollTrigger: {
+        trigger: containerRef.current,
+        start: "top 80%",
+      },
+    })
+  }, [])
+
+  return <div ref={containerRef}>{children}</div>
+}
+```
+
+## Animation Decision Tree
+
+```text
+Simple fade/slide on mount?
+├── Yes → CSS animation in globals.css
+└── No ↓
+
+Page/route transitions?
+├── Yes → View Transitions API or template.tsx
+└── No ↓
+
+Interactive hover/tap states?
+├── Yes → Tailwind transitions + Motion
+└── No ↓
+
+Scroll-triggered sequences?
+├── Yes → GSAP + ScrollTrigger
+└── No → Evaluate if animation needed
+```
+
+## Performance Tips
+
+1. **Prefer CSS** - GPU-accelerated, no JS bundle
+2. **Use `will-change` sparingly** - Only for known animations
+3. **Avoid layout thrashing** - Animate `transform` and `opacity`
+4. **Lazy load Motion/GSAP** - Dynamic imports for non-critical animations
+
+```tsx
+// Lazy load animation library
+const MotionDiv = dynamic(
+  () => import("motion/react").then((mod) => mod.motion.div),
+  { ssr: false }
+)
+```
+
+## Decorative Backgrounds
+
+Reusable patterns for visual atmosphere and section hierarchy.
+
+### Grid Pattern
+
+```tsx
+import { cn } from "@/lib/utils"
+
+export function GridBackground({
+  children,
+  className,
+  size = 20
+}: {
+  children: React.ReactNode
+  className?: string
+  size?: number
+}) {
+  return (
+    <div className={cn("relative", className)}>
+      <div
+        className={cn(
+          "absolute inset-0 -z-10",
+          "[background-image:linear-gradient(to_right,var(--border)_1px,transparent_1px),linear-gradient(to_bottom,var(--border)_1px,transparent_1px)]"
+        )}
+        style={{ backgroundSize: `${size}px ${size}px` }}
+      />
+      {children}
+    </div>
+  )
+}
+```
+
+### Dot Pattern
+
+```tsx
+export function DotBackground({
+  children,
+  className
+}: {
+  children: React.ReactNode
+  className?: string
+}) {
+  return (
+    <div className={cn("relative", className)}>
+      <div
+        className={cn(
+          "absolute inset-0 -z-10",
+          "[background-size:20px_20px]",
+          "[background-image:radial-gradient(color-mix(in_oklab,var(--muted-foreground)_30%,transparent)_1px,transparent_1px)]"
+        )}
+      />
+      {children}
+    </div>
+  )
+}
+```
+
+### Radial Gradient Hero
+
+```tsx
+export function GradientHero({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="relative min-h-screen">
+      <div
+        aria-hidden
+        className="fixed inset-0 -z-10"
+        style={{
+          background: "radial-gradient(125% 125% at 50% 10%, var(--background) 40%, var(--primary) 100%)"
+        }}
+      />
+      {children}
+    </div>
+  )
+}
+```
+
+### Faded Edge Effect
+
+Combine with grid/dot for vignette:
+
+```tsx
+<div className="relative">
+  <GridBackground className="absolute inset-0" />
+  <div className="pointer-events-none absolute inset-0 bg-background [mask-image:radial-gradient(ellipse_at_center,transparent_20%,black)]" />
+  {/* Content */}
+</div>
+```
+
+### Animated Spotlight
+
+For premium hero sections. Requires `motion`:
+
+```tsx
+"use client"
+
+import { motion } from "motion/react"
+import { cn } from "@/lib/utils"
+
+export function Spotlight({ className }: { className?: string }) {
+  return (
+    <motion.div
+      className={cn(
+        "pointer-events-none fixed inset-0 -z-10 overflow-hidden",
+        className
+      )}
+      aria-hidden
+    >
+      <motion.div
+        className="absolute top-0 left-1/2 h-[60vh] w-[80vw] -translate-x-1/2 rounded-full opacity-20 blur-3xl"
+        style={{
+          background:
+            "radial-gradient(ellipse, color-mix(in oklab, var(--primary) 30%, transparent), transparent 70%)",
+        }}
+        animate={{ x: ["-10%", "10%", "-10%"] }}
+        transition={{ duration: 8, repeat: Infinity, ease: "easeInOut" }}
+      />
+    </motion.div>
+  )
+}
+```
+
+Combine with DotBackground for depth:
+
+```tsx
+<div className="relative min-h-screen bg-background dark:bg-black">
+  <Spotlight />
+  <DotBackground className="absolute inset-0 opacity-30" />
+  <div className="relative z-10">{children}</div>
+</div>
+```
+
+For more creative direction (custom textures, particles, dramatic effects), apply `/frontend-design` thinking.
+
+### Section Wrapper
+
+For sections that need different theme context:
+
+```tsx
+type SectionProps = {
+  children: React.ReactNode
+  variant?: "default" | "muted" | "inverted"
+  className?: string
+}
+
+export function Section({ children, variant = "default", className }: SectionProps) {
+  return (
+    <section
+      className={cn(
+        "relative py-24",
+        variant === "muted" && "bg-muted",
+        variant === "inverted" && "bg-foreground text-background [&_*]:border-background/20",
+        className
+      )}
+    >
+      {children}
+    </section>
+  )
+}
+```
+
+### Background Decision Tree
+
+```text
+Full-page ambient effect?
+├── Static → Fixed radial gradient (GradientHero)
+├── Animated → Spotlight + DotBackground
+├── Premium → Apply /frontend-design thinking
+└── No ↓
+
+Subtle texture for depth?
+├── Grid → Technical/dashboard feel
+├── Dots → Softer/organic feel
+└── No ↓
+
+Section contrast needed?
+├── Yes → Section wrapper with variant
+└── No → Standard bg-background
+```
+
+### File Organization
+
+```text
+components/
+├── ui/           # shadcn primitives
+├── backgrounds/  # Grid, Dot, Gradient patterns
+└── animations/   # FadeIn, ScrollReveal
+```
+
+## Optional Utilities
+
+### Scrollbar Hide
+
+`shadcn/tailwind.css` already ships a `no-scrollbar` utility, so a shadcn project
+needs no extra package:
+
+```tsx
+<div className="overflow-y-auto no-scrollbar">
+  {/* Scrollable content without visible scrollbar */}
+</div>
+```
+
+Only reach for a package in a project that doesn't import `shadcn/tailwind.css`:
+
+```bash
+yarn add tailwind-scrollbar-hide
+```
+
+```css
+/* globals.css (Tailwind v4 — no config file needed) */
+@import "tailwind-scrollbar-hide/v4";
+```

package/skills/sf-theme-gen/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sf-theme-gen
+description: Customize a Thor Commerce storefront's OKLCH color tokens (light/dark), typography, and identity/SEO metadata
+---
+
+# sf-theme-gen
+
+Customize a storefront's theme and identity. This skill ships with everything it needs: it uses the vendored theming skill alongside it. When a choice is not resolved by those files, ask the user.
+
+## Source of truth
+
+The workflow uses only the assets in this skill directory and the vendored `../shadcn-theming/` skill next to it. When a required choice is not determined there, ask the user.
+
+## Inputs (the only target-project facts this skill reads)
+
+- the existence of the target project's `package.json`
+- the existence of `lib/<name>/`
+- the existence of the project's `.opencode/`
+- the values returned by the wizard (which area to customize, and its value)
+
+## Outputs (what this skill produces)
+
+- generated files: `app/globals.css` and `app/layout.tsx`
+- declared setup commands: the dev server and typecheck commands it reports
+- a summary listing every file edited and every command run
+
+## Scope
+
+| Area | File |
+|---|---|
+| Design tokens (shadcn) | `app/globals.css` |
+| Typography + metadata | `app/layout.tsx` |
+
+## Vendored skill
+Follow `../shadcn-theming/SKILL.md` for OKLCH pair rules and contrast. Paths are relative to this `SKILL.md`.
+
+## Color rules
+- Colors are CSS variables, never raw Tailwind color utilities.
+- OKLCH only; define complete background/foreground pairs.
+- Lightness rule: bg `L < 0.55` → fg `L >= 0.93`; bg `L >= 0.55` → fg `L <= 0.20`.
+- Named accents can use `accentColorToOklch(name)` from `@thorprovider/runtime/render-core/theme`.
+
+## Workflow
+
+1. Use the `question` tool to ask what to customize: colors, typography, identity, SEO, Open Graph.
+2. **Colors**: follow `../shadcn-theming/SKILL.md`; update BOTH `:root` (light) and `.dark` blocks in `app/globals.css`, keeping the `@theme inline` mapping intact.
+3. **Pairs**: every changed color gets its foreground pair in both modes; verify the lightness rule.
+4. **Typography**: load the font with `next/font` in `app/layout.tsx`; point `--font-sans` in `globals.css` at the new variable; keep body >= 1rem / line-height 1.5.
+5. **Identity**: update the `metadata` object in `app/layout.tsx` (title, description) and add Open Graph + Twitter Card fields. Research the current Next.js Metadata API before writing.
+6. **Verify**: run the dev server; confirm both color modes, font, and head metadata. `yarn typecheck` passes.
+
+## Error handling
+- Invalid color input → re-prompt (accept `<name>`, `#hex`, `oklch(...)`).
+- No `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
+- Unknown token key → check `themeTokenKeys` in `@thorprovider/runtime/contracts` first.
+
+## Generation headers
+```
+// Themed by @thorprovider/storefront (sf-theme-gen)
+```
+Never remove existing tokens; only override values.