bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/experiment/biome.json

@@ -0,0 +1,250 @@
+{
+  "root": false,
+  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "css": {
+    "formatter": {
+      "enabled": true
+    },
+    "linter": {
+      "enabled": true
+    },
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!node_modules",
+      "!**/.next",
+      "!**/dist",
+      "!**/public",
+      "!.github",
+      "!.vercel",
+      "!pnpm-lock.yaml",
+      "!bun.lock",
+      "!**/*.md",
+      "!**/*.mdx",
+      "!**/tailwind.css",
+      "!**/root.css",
+      "!**/*.grit"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 80
+  },
+  "javascript": {
+    "formatter": {
+      "enabled": true,
+      "quoteStyle": "double",
+      "semicolons": "asNeeded",
+      "trailingCommas": "es5"
+    }
+  },
+  "json": {
+    "parser": {
+      "allowComments": true
+    }
+  },
+  "linter": {
+    "domains": {
+      "next": "recommended",
+      "react": "recommended"
+    },
+    "enabled": true,
+    "rules": {
+      "a11y": {
+        "noAriaUnsupportedElements": "error",
+        "noAutofocus": "warn",
+        "noDistractingElements": "error",
+        "noRedundantAlt": "error",
+        "useAltText": "error",
+        "useButtonType": "error",
+        "useKeyWithClickEvents": "warn",
+        "useSemanticElements": "warn",
+        "useValidAnchor": "warn",
+        "useValidAriaProps": "error",
+        "useValidAriaRole": "error",
+        "useValidAriaValues": "error"
+      },
+      "complexity": {
+        "noForEach": "off",
+        "useFlatMap": "warn",
+        "useSimplifiedLogicExpression": "warn"
+      },
+      "correctness": {
+        "noInvalidUseBeforeDeclaration": "error",
+        "noUnknownMediaFeatureName": "off",
+        "noUnusedFunctionParameters": "warn",
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "useExhaustiveDependencies": "warn"
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "warn",
+          "options": {
+            "attributes": ["class", "className"],
+            "functions": ["cn", "cva"]
+          }
+        }
+      },
+      "performance": {
+        "noImgElement": "error"
+      },
+      "recommended": true,
+      "security": {
+        "noDangerouslySetInnerHtml": "warn",
+        "noDangerouslySetInnerHtmlWithChildren": "error",
+        "noGlobalEval": "error"
+      },
+      "style": {
+        "noInferrableTypes": "error",
+        "noNestedTernary": "error",
+        "noNonNullAssertion": "off",
+        "noParameterAssign": "error",
+        "noUnusedTemplateLiteral": "off",
+        "noUselessElse": "error",
+        "useAsConstAssertion": "error",
+        "useCollapsedElseIf": "warn",
+        "useConsistentArrayType": "error",
+        "useConsistentBuiltinInstantiation": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useExponentiationOperator": "error",
+        "useFilenamingConvention": {
+          "level": "warn",
+          "options": {
+            "filenameCases": ["kebab-case", "camelCase"],
+            "strictCase": false
+          }
+        },
+        "useForOf": "warn",
+        "useNumberNamespace": "error",
+        "useSelfClosingElements": "error",
+        "useShorthandAssign": "error",
+        "useSingleVarDeclarator": "error",
+        "useTemplate": "warn"
+      },
+      "suspicious": {
+        "noDebugger": "warn",
+        "noDoubleEquals": "error",
+        "noEmptyBlockStatements": "warn",
+        "noExplicitAny": "error",
+        "noGlobalIsFinite": "error",
+        "noGlobalIsNan": "error",
+        "noMisleadingCharacterClass": "error",
+        "noPrototypeBuiltins": "warn",
+        "noSelfCompare": "error",
+        "noSparseArray": "error",
+        "useAwait": "off"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.css"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUnknownFunction": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/*.tsx", "**/*.jsx"],
+      "linter": {
+        "rules": {
+          "a11y": {
+            "useKeyWithClickEvents": "error",
+            "useKeyWithMouseEvents": "error",
+            "useValidAnchor": "error"
+          },
+          "correctness": {
+            "useJsxKeyInIterable": "error"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/*.ts", "**/*.tsx"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUndeclaredVariables": "off"
+          },
+          "style": {
+            "useConsistentArrayType": "error",
+            "useExportType": "error",
+            "useImportType": "error"
+          }
+        }
+      }
+    },
+    {
+      "includes": [
+        "app/**/*.tsx",
+        "app/**/*.ts",
+        "app/**/*.jsx",
+        "app/**/*.js"
+      ],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off"
+          },
+          "suspicious": {
+            "useAwait": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/*.module.css"],
+      "linter": {
+        "rules": {
+          "correctness": {
+            "noUnknownProperty": "off"
+          },
+          "style": {
+            "noDescendingSpecificity": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["lib/styles/css/root.css"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noDuplicateCustomProperties": "off"
+          }
+        }
+      }
+    }
+  ],
+  "plugins": [
+    "./.biome/plugins/no-anchor-element.grit",
+    "./.biome/plugins/no-unnecessary-forwardref.grit",
+    "./.biome/plugins/no-relative-parent-imports.grit"
+  ],
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

package/packages/create-basement-app/templates/experiment/components/basement.svg

@@ -0,0 +1 @@
+<svg width="123" height="18" viewBox="0 0 123 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M4.43626 6.76458V.252441H.381348V17.1671H4.33011v-3.0447c.40337 2.1989 1.78331 3.2984 4.13983 3.2984 3.96996 0 4.86166-.9515 4.86166-5.6664V9.91493c0-4.7361-.8704-5.66641-4.64937-5.66641-2.54758 0-3.77892.54973-4.24597 2.51606Zm.02123 5.94122V9.42863c.10615-1.14174.84919-1.69146 2.29282-1.69146 1.95315 0 2.31406.42286 2.31406 2.30463v1.628c0 1.8395-.36091 2.2623-2.31406 2.2623-1.4224 0-2.16544-.4228-2.29282-1.2263Zm10.23281.8035c0 3.4252.7643 4.0384 4.9253 3.9115 1.9956-.0211 3.418-.8035 3.97-2.4949v2.2412h4.0337V8.62519c0-3.70008-.8917-4.37667-5.6259-4.37667h-.9766c-4.9678 0-5.9019.65544-5.9019 4.14409v.50744h4.0337c-.0425-1.45889.3184-1.71261 2.314-1.71261 1.7833 0 2.123.25372 2.123 1.71261v.71887l-4.0337.02114c-4.0973 0-4.8616.61314-4.8616 3.86924Zm4.246.0423c0-.7823.2123-.9303 1.3162-.9303l3.3331-.0212v.5497c0 .9938-.6793 1.3744-2.4627 1.4166h-.2122c-1.656 0-1.9744-.1691-1.9744-1.0148Zm10.0417-.3383c0 3.5309.8917 4.2075 5.5622 4.2075h.9766c5.3499 0 6.3265-.592 6.3265-3.6367 0-1.9451-.4883-3.108-2.5051-3.7-1.104-.31718-2.0805-.5709-4.1611-.90919-1.3799-.21143-1.762-.46515-1.762-.99373 0-.78231.4246-.99374 1.9956-.99374 1.6347 0 2.0805.29601 2.0805 1.33203v.38058h4.0337v-.38058c0-3.61551-.8917-4.27095-5.6259-4.27095h-.9766c-4.8192 0-5.7533.57087-5.7533 3.8058 0 1.69146.4458 2.64288 2.1867 3.31948 1.2738.4863 3.2057.7823 3.9487.9303 1.8682.3383 2.3141.6766 2.3141 1.184 0 .7612-.4883.9726-2.3141.9726-1.9744 0-2.5051-.2748-2.5051-1.2474v-.2749H28.978v.2749Zm14.0967-2.3681c0 5.5396.9765 6.5756 6.1779 6.5756h.9765c5.1589 0 6.1142-.6766 6.1142-4.271h-4.2459c0 1.0784-.3609 1.3109-2.3353 1.3109-2.0593 0-2.4415-.3594-2.4415-2.1989v-.0634h9.1289v-1.9875c0-5.03207-.9766-5.96238-6.2204-5.96238h-.9765c-5.2014 0-6.1779 1.01488-6.1779 6.59668Zm4.2459-1.628v-.06343c0-1.64918.3822-1.96633 2.4415-1.96633 1.9956 0 2.4202.31715 2.4414 2.02976h-4.8829Zm10.9122 7.9499h4.0337V9.83035c0-1.48003.7006-2.22004 2.1017-2.22004 1.6135 0 1.932.31715 1.932 1.96632v7.59047h4.0124l-.0212-7.46361c.0424-1.39546.743-2.09318 2.1017-2.09318 1.6135 0 1.8895.31715 1.8895 1.96632v7.59047h4.0337l-.0212-8.20362c0-3.97494-.7219-4.71496-4.6069-4.71496-2.1443 0-3.4393.90916-3.9063 2.91778-.1699-2.41034-.8705-2.91778-4.0974-2.91778-1.8895 0-2.9722.76116-3.418 2.66406V4.50224h-4.0337V17.1671Zm21.6545-6.3219c0 5.5396.9766 6.5756 6.1991 6.5756h.9766c5.1164 0 6.0717-.6766 6.0717-4.271H88.91c0 1.0784-.3609 1.3109-2.3141 1.3109-2.1017 0-2.4839-.3594-2.4839-2.1989v-.0634h9.1289v-1.9875c0-5.03207-.9766-5.96238-6.1779-5.96238h-.9766c-5.2225 0-6.1991 1.01488-6.1991 6.59668Zm4.2247-1.628v-.06343c0-1.64918.3822-1.96633 2.4839-1.96633 1.9744 0 2.399.31715 2.4202 2.02976H84.112Zm10.891 7.9499h4.0337V9.61892c.0212-1.35317.7642-2.00861 2.2293-2.00861 1.868 0 2.208.35943 2.208 2.30462v7.25217h4.033l-.021-8.20362c0-3.97494-.7-4.71496-4.394-4.71496-2.336 0-3.5671.76116-4.0553 2.81206V4.50224H95.003V17.1671Zm13.545-9.30307h1.252v5.05327c0 3.5732.828 4.2498 5.095 4.2498h2.76v-3.5944h-2.335c-1.253 0-1.486-.2114-1.486-1.2686V7.86403h3.63V4.50224h-3.63V1.77476h-3.821v2.72748h-1.465v3.36179Zm10.636 9.30307h3.63v-3.5944h-3.63v3.5944Z" fill="#EFEFEF"/></svg>

package/packages/create-basement-app/templates/experiment/components/layout/footer/index.tsx

@@ -0,0 +1,27 @@
+import Logo from "@/components/basement.svg"
+import { Link } from "@/components/ui/link"
+
+export function Footer() {
+  return (
+    <footer className="flex flex-col items-center justify-between p-safe font-mono uppercase 2xl:flex-row 2xl:items-end">
+      <Link href="https://basement.studio/" className="link">
+        <Logo className="w-148 text-secondary" />
+      </Link>
+      <div>
+        <Link
+          href="https://github.com/basementstudio/next-starter/generate"
+          className="link"
+        >
+          use this template
+        </Link>
+        {" / "}
+        <Link
+          href="https://github.com/basementstudio/next-starter"
+          className="link"
+        >
+          github
+        </Link>
+      </div>
+    </footer>
+  )
+}

package/packages/create-basement-app/templates/experiment/components/layout/header/index.tsx

@@ -0,0 +1,58 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { Link } from "@/components/ui/link"
+import EXPERIMENTS from "@/lib/constants"
+import { cn } from "@/lib/styles/cn"
+import {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+} from "../navigation-menu"
+
+export const Header = () => {
+  const pathname = usePathname()
+
+  return (
+    <nav className="fixed top-0 z-50 w-full py-2">
+      <div className="mx-auto flex items-center justify-between px-4">
+        <Link href="/" className="flex items-center gap-2 font-bold text-xl">
+          Basement Experiments Starter
+        </Link>
+        <NavigationMenu>
+          <NavigationMenuList>
+            <NavigationMenuItem>
+              <NavigationMenuTrigger className="px-8 py-6 font-medium text-sm">
+                Experiments
+              </NavigationMenuTrigger>
+              <NavigationMenuContent>
+                <ul className="grid w-48 gap-1 bg-indigo-950/70 p-2 text-white backdrop-blur-3xl">
+                  {EXPERIMENTS.map((experiment) => (
+                    <li key={experiment.path}>
+                      <NavigationMenuLink asChild>
+                        <Link
+                          href={experiment.path}
+                          className={cn(
+                            "block rounded-sm px-2 py-2 font-medium text-sm transition-colors duration-200",
+                            pathname === experiment.path
+                              ? "bg-purple-600 text-white"
+                              : "text-white hover:bg-purple-500/20"
+                          )}
+                        >
+                          {experiment.name}
+                        </Link>
+                      </NavigationMenuLink>
+                    </li>
+                  ))}
+                </ul>
+              </NavigationMenuContent>
+            </NavigationMenuItem>
+          </NavigationMenuList>
+        </NavigationMenu>
+      </div>
+    </nav>
+  )
+}

package/packages/create-basement-app/templates/experiment/components/layout/navigation-menu.tsx

@@ -0,0 +1,127 @@
+import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu"
+import { cva } from "class-variance-authority"
+import { ChevronDown } from "lucide-react"
+
+import { cn } from "@/lib/styles/cn"
+
+function NavigationMenu({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Root>) {
+  return (
+    <NavigationMenuPrimitive.Root
+      className={cn(
+        "relative z-10 flex max-w-max flex-1 items-center justify-center",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <NavigationMenuViewport />
+    </NavigationMenuPrimitive.Root>
+  )
+}
+
+function NavigationMenuList({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.List>) {
+  return (
+    <NavigationMenuPrimitive.List
+      className={cn(
+        "group flex flex-1 list-none items-center justify-center space-x-1",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const NavigationMenuItem = NavigationMenuPrimitive.Item
+
+const navigationMenuTriggerStyle = cva(
+  "group inline-flex h-9 w-max cursor-pointer items-center justify-center rounded-md border border-purple-400/50 bg-indigo-950/30 px-4 py-2 font-medium text-sm text-white backdrop-blur-3xl transition-colors hover:bg-purple-800/50 hover:text-white focus:bg-purple-800/50 focus:text-white focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[state=open]:bg-indigo-900/70 data-[state=open]:text-white data-[state=open]:focus:bg-purple-800/50 data-[state=open]:hover:bg-purple-800/50"
+)
+
+function NavigationMenuTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>) {
+  return (
+    <NavigationMenuPrimitive.Trigger
+      className={cn(navigationMenuTriggerStyle(), "group", className)}
+      {...props}
+    >
+      {children}{" "}
+      <ChevronDown
+        className="relative top-[1px] ml-1 h-3 w-3 transition duration-300 group-data-[state=open]:rotate-180"
+        aria-hidden="true"
+      />
+    </NavigationMenuPrimitive.Trigger>
+  )
+}
+
+function NavigationMenuContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>) {
+  return (
+    <NavigationMenuPrimitive.Content
+      className={cn(
+        "data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 top-0 left-0 w-full data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out md:absolute md:w-auto",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const NavigationMenuLink = NavigationMenuPrimitive.Link
+
+function NavigationMenuViewport({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>) {
+  return (
+    <div className={cn("absolute top-full left-0 flex justify-center")}>
+      <NavigationMenuPrimitive.Viewport
+        className={cn(
+          "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)] w-full origin-top-center overflow-hidden rounded-md border border-purple-400/50 bg-indigo-950/70 text-white shadow data-[state=closed]:animate-out data-[state=open]:animate-in md:w-[var(--radix-navigation-menu-viewport-width)]",
+          className
+        )}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function NavigationMenuIndicator({
+  className,
+  ...props
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>) {
+  return (
+    <NavigationMenuPrimitive.Indicator
+      className={cn(
+        "data-[state=hidden]:fade-out data-[state=visible]:fade-in top-full z-[1] flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-out data-[state=visible]:animate-in",
+        className
+      )}
+      {...props}
+    >
+      <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-purple-400 shadow-md" />
+    </NavigationMenuPrimitive.Indicator>
+  )
+}
+
+export {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuIndicator,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+  navigationMenuTriggerStyle,
+  NavigationMenuViewport,
+}

package/packages/create-basement-app/templates/experiment/components/layout/theme/index.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { createContext, useContext, useEffect, useState } from "react"
+import type { Themes } from "@/lib/styles/colors"
+import { type ThemeName, themes } from "@/lib/styles/config"
+
+export const ThemeContext = createContext<{
+  name: ThemeName
+  theme: Themes[ThemeName]
+  setThemeName: (theme: ThemeName) => void
+}>({
+  name: "light",
+  theme: themes.light,
+  setThemeName: () => {
+    void 0
+  },
+})
+
+export function useTheme() {
+  return useContext(ThemeContext)
+}
+
+export function Theme({
+  children,
+  theme,
+  global,
+}: {
+  children: React.ReactNode
+  theme: ThemeName
+  global?: boolean
+}) {
+  const pathname = usePathname()
+
+  const [currentTheme, setCurrentTheme] = useState(theme)
+
+  useEffect(() => {
+    setCurrentTheme(theme)
+  }, [theme])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: we need to trigger on path change
+  useEffect(() => {
+    if (global) {
+      document.documentElement.setAttribute("data-theme", currentTheme)
+    }
+  }, [pathname, currentTheme, global])
+
+  return (
+    <>
+      {global && (
+        <script>
+          {`document.documentElement.setAttribute('data-theme', '${currentTheme}');`}
+        </script>
+      )}
+      <ThemeContext.Provider
+        value={{
+          name: currentTheme,
+          theme: themes[currentTheme],
+          setThemeName: setCurrentTheme,
+        }}
+      >
+        {children}
+      </ThemeContext.Provider>
+    </>
+  )
+}

package/packages/create-basement-app/templates/experiment/components/layout/wrapper/index.tsx

@@ -0,0 +1,65 @@
+/**
+ * Main page wrapper providing theme, smooth scrolling, and WebGL context.
+ *
+ * Customize the Header and Footer components for your project needs.
+ */
+"use client"
+
+import cn from "clsx"
+import { Footer } from "@/components/layout/footer"
+import { Header } from "@/components/layout/header"
+import { Theme } from "@/components/layout/theme"
+import type { ThemeName } from "@/lib/styles/config"
+
+/**
+ * Props for the Wrapper component.
+ */
+interface WrapperProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Theme to apply ('dark' | 'light'). Defaults to 'dark'. */
+  theme?: ThemeName
+}
+
+/**
+ * Main page wrapper component providing theme.
+ *
+ * This component serves as the root container for pages, automatically handling
+ * theme application and layout structure.
+ * It includes navigation and footer.
+ *
+ * @param props - Component props
+ * @param props.theme - Color theme to apply to the page
+ * @param props.children - Page content
+ * @param props.className - Additional CSS classes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with theme
+ * export default function Page() {
+ *   return (
+ *     <Wrapper theme="dark">
+ *       <section>My page content</section>
+ *     </Wrapper>
+ *   )
+ * }
+ * ```
+ */
+export function Wrapper({
+  children,
+  theme = "dark",
+  className,
+  ...props
+}: WrapperProps) {
+  return (
+    <Theme theme={theme} global>
+      <Header />
+      <main
+        id="main-content"
+        className={cn("relative flex grow flex-col", className)}
+        {...props}
+      >
+        {children}
+      </main>
+      <Footer />
+    </Theme>
+  )
+}

package/packages/create-basement-app/templates/experiment/components/ui/README.md

@@ -0,0 +1,77 @@
+# Components
+
+UI components organized by purpose.
+
+```
+components/
+├── ui/        → Primitives (reusable across projects)
+├── layout/    → Site chrome (customize per project)
+└── magic/   → Animation & visual enhancements
+```
+
+## Direct Imports (Recommended)
+
+```tsx
+// UI Components - import directly for better clarity
+import { Image } from '@/components/ui/image'
+import { Link } from '@/components/ui/link'
+
+// Layout Components
+import { Wrapper } from '@/components/layout/wrapper'
+import { Header } from '@/components/layout/header' 
+import { Footer } from '@/components/layout/footer'
+
+// Magic Components
+import { Marquee } from '@/components/magic/marquee'
+```
+
+## UI Components
+
+| Component | Purpose |
+|-----------|---------|
+| `image/` | Optimized images (always use this, never `next/image`) |
+| `link/` | Smart navigation (auto-detects external) |
+
+## Layout Components
+
+| Component | Purpose |
+|-----------|---------|
+| `wrapper/` | Page wrapper (theme, WebGL, Lenis) |
+| `header/` | Site header/navigation |
+| `footer/` | Site footer |
+| `lenis/` | Smooth scrolling |
+
+```tsx
+<Wrapper theme="dark" webgl lenis>
+  <section>Your content</section>
+</Wrapper>
+```
+
+## Effects Components
+
+| Component | Purpose |
+|-----------|---------|
+| `marquee/` | Infinite scrolling text |
+
+## Best Practices
+
+```tsx
+// ✅ Always use custom Image
+import { Image } from '@/components/ui/image'
+<Image src="/photo.jpg" alt="Photo" aspectRatio={16/9} />
+
+// ✅ Always use custom Link
+import { Link } from '@/components/ui/link'
+<Link href="/about">Internal</Link>
+<Link href="https://example.com">External</Link>
+
+// ✅ CSS Modules + Tailwind
+import s from './component.module.css'
+<div className={cn(s.wrapper, 'flex items-center')} />
+```
+
+## Related
+
+- [Image docs](ui/image/README.md)
+- [Real Viewport docs](ui/real-viewport/README.md)
+- [WebGL Components](../lib/webgl/README.md)