diff --git a/apps/docs/features/docs/Reference.mdx.tsx b/apps/docs/features/docs/Reference.mdx.tsx
index 1e63f8adb3d..2f3f846c9f9 100644
--- a/apps/docs/features/docs/Reference.mdx.tsx
+++ b/apps/docs/features/docs/Reference.mdx.tsx
@@ -41,14 +41,17 @@ const getRefMarkdown = cache_fullProcess_withDevCacheBust(
 
 interface MDXRemoteRefsProps {
   source: string
+  codeBlockProps?: Partial<ComponentProps<typeof CodeBlock>>
 }
 
-function MDXRemoteRefs({ source }: MDXRemoteRefsProps) {
+function MDXRemoteRefs({ source, codeBlockProps }: MDXRemoteRefsProps) {
   const refComponents = {
     ...components,
     // Override the CodeBlock used for normal guides to skip type generation
     // because it is too resource-intensive
-    pre: (props: ComponentProps<typeof CodeBlock>) => <CodeBlock {...props} skipTypeGeneration />,
+    pre: (props: ComponentProps<typeof CodeBlock>) => (
+      <CodeBlock {...props} {...codeBlockProps} skipTypeGeneration />
+    ),
     RefSubLayout,
     CliGlobalFlagsHandler,
   }
diff --git a/apps/docs/features/docs/Reference.sections.tsx b/apps/docs/features/docs/Reference.sections.tsx
index cbced0f844c..a95baa199b0 100644
--- a/apps/docs/features/docs/Reference.sections.tsx
+++ b/apps/docs/features/docs/Reference.sections.tsx
@@ -548,7 +548,15 @@ async function FunctionSection({
               </TabsList>
               {examples.map((example) => (
                 <TabsContent key={example.id} value={example.id}>
-                  <MDXRemoteRefs source={example.code} />
+                  <div
+                    className={cn(
+                      'prose wrap-break-word max-w-none',
+                      '[&_.shiki]:!my-0 [&_.shiki:not(:last-child)]:!mb-4',
+                      '[&_p]:!whitespace-normal'
+                    )}
+                  >
+                    <MDXRemoteRefs source={example.code} />
+                  </div>
                   <div className="flex flex-col gap-2 mt-2">
                     {'data' in example && !!example.data?.sql && (
                       <CollapsibleDetails title="Data source" content={example.data.sql} />
diff --git a/apps/docs/features/docs/Reference.ui.tsx b/apps/docs/features/docs/Reference.ui.tsx
index 42c984a41e6..441976c8d35 100644
--- a/apps/docs/features/docs/Reference.ui.tsx
+++ b/apps/docs/features/docs/Reference.ui.tsx
@@ -12,6 +12,7 @@ import { ReferenceSectionWrapper } from '~/features/docs/Reference.ui.client'
 import { normalizeMarkdown } from '~/features/docs/Reference.utils'
 import { isEqual } from 'lodash-es'
 import { ChevronRight, XCircle } from 'lucide-react'
+import { fromMarkdown } from 'mdast-util-from-markdown'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
 import ReactMarkdown from 'react-markdown'
 import { Badge, cn, Collapsible, CollapsibleContent, CollapsibleTrigger } from 'ui'
@@ -115,32 +116,57 @@ export function StickyHeader({ title, monoFont = false, className }: StickyHeade
 }
 
 export function CollapsibleDetails({ title, content }: { title: string; content: string }) {
+  const blocks = fromMarkdown(content).children
+  const isCodeOnly = blocks.length === 1 && blocks[0].type === 'code'
+
   return (
-    <Collapsible>
+    <Collapsible
+      className={cn(
+        'overflow-hidden',
+        'border border-default rounded-lg bg-surface-100',
+        'has-[:focus-visible]:outline-solid has-[:focus-visible]:outline-2',
+        'has-[:focus-visible]:outline-offset-[-2px] has-[:focus-visible]:outline-[var(--ring)]'
+      )}
+    >
       <CollapsibleTrigger
         className={cn(
-          'group',
-          'w-full h-8',
-          'border bg-surface-100 rounded-sm',
-          'px-5',
-          'flex items-center gap-3',
+          'group/trigger',
+          'w-full min-h-8',
+          'px-2 py-1.5',
+          'flex items-center gap-2',
           'text-xs text-foreground-light',
-          'data-open:bg-surface-200',
-          'data-open:rounded-b-none data-open:border-b-0',
-          'transition motion-reduce:duration-1 ease-out'
+          'cursor-pointer hover:bg-surface-200 hover:text-foreground',
+          'focus-visible:outline-none',
+          'transition-[background-color,color] duration-150 ease-out'
         )}
       >
-        <ChevronRight size={12} className="group-data-open:rotate-90 transition-transform" />
         {title}
+        <ChevronRight
+          size={12}
+          strokeWidth={2}
+          aria-hidden
+          className="ms-auto shrink-0 text-foreground-muted group-data-open/trigger:rotate-90 transition-transform duration-200 ease-out motion-reduce:transition-none"
+        />
       </CollapsibleTrigger>
       <CollapsibleContent
         className={cn(
-          'border border-default bg-surface-100 rounded-b',
-          'px-5 py-2',
-          'prose max-w-none text-sm'
+          'overflow-hidden',
+          'data-open:animate-collapsible-down data-closed:animate-collapsible-up',
+          'motion-reduce:animate-none'
         )}
       >
-        <MDXRemoteRefs source={content} />
+        <div
+          className={cn(
+            'border-t border-default',
+            'prose max-w-none text-sm',
+            !isCodeOnly && 'px-4 py-3 [&_:where(p,li)]:text-sm [&_:where(p,li)]:leading-6'
+          )}
+        >
+          <MDXRemoteRefs
+            source={content}
+            codeBlockProps={isCodeOnly ? { compact: true } : undefined}
+          />
+        </div>
       </CollapsibleContent>
     </Collapsible>
   )
diff --git a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
index 4ecafb77f33..1d1c4d3268d 100644
--- a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
+++ b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
@@ -27,6 +27,7 @@ export async function CodeBlock({
   children,
   skipTypeGeneration,
   hideControls = false,
+  compact = false,
 }: PropsWithChildren<{
   className?: string
   lang?: string
@@ -34,6 +35,7 @@ export async function CodeBlock({
   contents?: string
   skipTypeGeneration?: boolean
   hideControls?: boolean
+  compact?: boolean
 }>) {
   let code = (contents || extractCode(children)).trim()
   const lang = tryToBundledLanguage(langSetting || '') || extractLang(children)
@@ -63,8 +65,8 @@ export async function CodeBlock({
         'relative',
         'not-prose',
         'w-full',
-        'border border-default rounded-lg',
-        'bg-200 shadow-codeblock',
+        compact ? 'border-0 my-0!' : 'border border-default rounded-lg shadow-codeblock',
+        'bg-200',
         'text-sm',
         className
       )}
@@ -72,7 +74,8 @@ export async function CodeBlock({
       <div
         className={cn(
           'code-scroll',
-          'w-full overflow-x-auto overscroll-x-none rounded-lg',
+          'w-full overflow-x-auto overscroll-x-none',
+          !compact && 'rounded-lg',
           'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring'
         )}
         role="group"