diff --git a/apps/web/src/components/Markdown.tsx b/apps/web/src/components/Markdown.tsx
index a6bc1cc..e77655d 100644
--- a/apps/web/src/components/Markdown.tsx
+++ b/apps/web/src/components/Markdown.tsx
@@ -16,28 +16,28 @@ interface MarkdownProps {
 /**
  * Markdown renderer component
  * Safely renders markdown content with GitHub Flavored Markdown support
- * Styled to match npm.com's beautiful README rendering
+ * Styled with theme-aware semantic tokens for proper light/dark mode support
  */
 export function Markdown({ content, className = '' }: MarkdownProps): React.ReactElement {
   return (
     <div
       className={`prose prose-slate dark:prose-invert max-w-none prose-lg
-        prose-headings:font-semibold prose-headings:tracking-tight prose-headings:text-zinc-900 dark:prose-headings:text-zinc-100
-        prose-h1:text-4xl prose-h1:mb-6 prose-h1:mt-8 prose-h1:pb-3 prose-h1:border-b prose-h1:border-zinc-200 dark:prose-h1:border-zinc-700
-        prose-h2:text-3xl prose-h2:mb-5 prose-h2:mt-10 prose-h2:pb-2 prose-h2:border-b prose-h2:border-zinc-200 dark:prose-h2:border-zinc-700
+        prose-headings:font-semibold prose-headings:tracking-tight prose-headings:text-foreground
+        prose-h1:text-4xl prose-h1:mb-6 prose-h1:mt-8 prose-h1:pb-3 prose-h1:border-b prose-h1:border-border
+        prose-h2:text-3xl prose-h2:mb-5 prose-h2:mt-10 prose-h2:pb-2 prose-h2:border-b prose-h2:border-border
         prose-h3:text-2xl prose-h3:mb-4 prose-h3:mt-8
         prose-h4:text-xl prose-h4:mb-3 prose-h4:mt-6
-        prose-p:text-base prose-p:leading-relaxed prose-p:mb-4 prose-p:text-zinc-700 dark:prose-p:text-zinc-300
+        prose-p:text-base prose-p:leading-relaxed prose-p:mb-4 prose-p:text-foreground-secondary
         prose-a:text-blue-600 dark:prose-a:text-blue-400 prose-a:no-underline hover:prose-a:underline prose-a:font-medium prose-a:transition-colors
         prose-code:text-sm prose-code:font-mono prose-code:before:content-none prose-code:after:content-none
         prose-pre:p-0 prose-pre:m-0 prose-pre:bg-transparent prose-pre:border-0
-        prose-blockquote:border-l-4 prose-blockquote:border-blue-500 dark:prose-blockquote:border-blue-400 prose-blockquote:pl-5 prose-blockquote:py-2 prose-blockquote:italic prose-blockquote:text-zinc-700 dark:prose-blockquote:text-zinc-300 prose-blockquote:bg-blue-50 dark:prose-blockquote:bg-blue-950/20 prose-blockquote:my-6 prose-blockquote:rounded-r
+        prose-blockquote:border-l-4 prose-blockquote:border-blue-500 dark:prose-blockquote:border-blue-400 prose-blockquote:pl-5 prose-blockquote:py-2 prose-blockquote:italic prose-blockquote:text-foreground-secondary prose-blockquote:bg-blue-50 dark:prose-blockquote:bg-blue-950/20 prose-blockquote:my-6 prose-blockquote:rounded-r
         prose-ul:list-disc prose-ul:pl-6 prose-ul:my-5 prose-ul:space-y-2
         prose-ol:list-decimal prose-ol:pl-6 prose-ol:my-5 prose-ol:space-y-2
-        prose-li:text-base prose-li:leading-relaxed prose-li:text-zinc-700 dark:prose-li:text-zinc-300
-        prose-img:rounded-lg prose-img:shadow-lg prose-img:my-8 prose-img:border prose-img:border-zinc-200 dark:prose-img:border-zinc-700
-        prose-hr:border-zinc-300 dark:prose-hr:border-zinc-700 prose-hr:my-10
-        prose-strong:font-semibold prose-strong:text-zinc-900 dark:prose-strong:text-zinc-100
+        prose-li:text-base prose-li:leading-relaxed prose-li:text-foreground-secondary
+        prose-img:rounded-lg prose-img:shadow-lg prose-img:my-8 prose-img:border prose-img:border-border
+        prose-hr:border-border prose-hr:my-10
+        prose-strong:font-semibold prose-strong:text-foreground
         ${className}`}
     >
       <ReactMarkdown
@@ -83,7 +83,7 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           // Pre wrapper for code blocks (SyntaxHighlighter handles its own styling)
           pre: ({ children, ...props }) => {
             return (
-              <div className="my-6 overflow-hidden rounded-lg shadow-md border border-zinc-200 dark:border-zinc-700">
+              <div className="my-6 overflow-hidden rounded-lg shadow-md border border-border">
                 <pre {...props}>{children}</pre>
               </div>
             );
@@ -106,11 +106,8 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           // Better table styling with improved readability
           table: ({ children, ...props }) => {
             return (
-              <div className="overflow-x-auto my-8 rounded-lg border border-zinc-300 dark:border-zinc-700 shadow-sm">
-                <table
-                  className="min-w-full divide-y divide-zinc-300 dark:divide-zinc-700"
-                  {...props}
-                >
+              <div className="overflow-x-auto my-8 rounded-lg border border-border shadow-sm">
+                <table className="min-w-full divide-y divide-border" {...props}>
                   {children}
                 </table>
               </div>
@@ -119,7 +116,7 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           // Table header with better styling
           thead: ({ children, ...props }) => {
             return (
-              <thead className="bg-zinc-100 dark:bg-zinc-800" {...props}>
+              <thead className="bg-surface-secondary" {...props}>
                 {children}
               </thead>
             );
@@ -128,7 +125,7 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           th: ({ children, ...props }) => {
             return (
               <th
-                className="px-6 py-3 text-left text-xs font-semibold text-zinc-700 dark:text-zinc-300 uppercase tracking-wider"
+                className="px-6 py-3 text-left text-xs font-semibold text-foreground-secondary uppercase tracking-wider"
                 {...props}
               >
                 {children}
@@ -138,7 +135,7 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           // Table data cells with better spacing
           td: ({ children, ...props }) => {
             return (
-              <td className="px-6 py-4 text-sm text-zinc-900 dark:text-zinc-100" {...props}>
+              <td className="px-6 py-4 text-sm text-foreground" {...props}>
                 {children}
               </td>
             );
@@ -147,7 +144,7 @@ export function Markdown({ content, className = '' }: MarkdownProps): React.Reac
           tr: ({ children, ...props }) => {
             return (
               <tr
-                className="border-b border-zinc-200 dark:border-zinc-800 last:border-b-0 hover:bg-zinc-50 dark:hover:bg-zinc-800/50 transition-colors"
+                className="border-b border-border last:border-b-0 hover:bg-surface-secondary/50 transition-colors"
                 {...props}
               >
                 {children}