fix: update README.md for proper style override

README.md

@@ -19,23 +19,52 @@ yarn add @mintlify/components
 
 - Node.js >= 20.0.0
 - React ^18.0.0 or ^19.0.0
+- Tailwind CSS v3 or v4
+
+## Setup
+
+### Tailwind v4
+
+Import the styles at the **top** of your main CSS file, **before** `@import "tailwindcss"`:
+
+```css
+@import "@mintlify/components/styles.css";
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #your-color;
+}
+```
+
+### Tailwind v3
+
+Import the styles at the **top** of your main CSS file:
+
+```css
+@import "@mintlify/components/styles.css";
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Override theme values in `tailwind.config.js`.
+
+> **Note:** Importing styles before Tailwind ensures your custom theme values take precedence over the component defaults.
 
 ## Usage
 
-Import components and styles in your project:
+Import components in your React files:
 
 ```tsx
 import { Accordion, Callout, CodeBlock, Tabs } from '@mintlify/components';
-import '@mintlify/components/styles.css';
 ```
 
 ### Example
 
 ```tsx
 import { Callout } from '@mintlify/components';
-import '@mintlify/components/styles.css';
 
-function App() {
+const App = () => {
   return (
     <Callout type="info" title="Note">
       This is an informational callout.

packages/components/.storybook/preview.tsx

@@ -65,7 +65,7 @@ const preview: Preview = {
                 `}
               </style>
               <div
-                className={`relative p-8 text-gray-500 antialiased dark:bg-zinc-950 dark:text-gray-400 ${inter.variable} ${jetbrainsMono.variable}`}
+                className={`relative p-8 text-stone-500 antialiased dark:bg-stone-950 dark:text-stone-400 ${inter.variable} ${jetbrainsMono.variable}`}
               >
                 <Story />
               </div>

packages/components/src/code.css

@@ -164,8 +164,9 @@ html:not(.dark) .codeblock-light {
 }
 
 /* Lines of code outside code blocks. Generated when you use single ticks: `example` */
+/* biome-ignore lint/style/noDescendingSpecificity: TODO */
 :not(pre) > code {
-  @apply break-words rounded-md px-2 py-0.5 text-gray-600 dark:text-gray-200 dark:border-gray-800 bg-gray-100/50 dark:bg-white/5;
+  @apply wrap-break-word rounded-md px-2 py-0.5 text-stone-600 dark:text-stone-200 dark:border-stone-800 bg-stone-100/50 dark:bg-white/5;
 }
 
 :not(pre) > code:before,
@@ -208,6 +209,7 @@ html:not(.dark) .codeblock-light {
 
 /* line highlighting (without line numbers) */
 [data-component-part="code-block-root"]:not(.has-line-numbers) {
+  /* biome-ignore lint/style/noDescendingSpecificity: TODO */
   .line-highlight {
     background: color-mix(
       in srgb,
@@ -325,15 +327,18 @@ html:not(.dark) .codeblock-light {
 }
 
 /* line numbers + highlighting */
+/* biome-ignore lint/style/noDescendingSpecificity: TODO */
 .has-line-numbers .line-highlight {
   width: 100%;
   display: inline-block;
   position: relative;
 
+  /* biome-ignore lint/style/noDescendingSpecificity: TODO */
   &::before {
     display: none;
   }
 
+  /* biome-ignore lint/style/noDescendingSpecificity: TODO */
   &::after {
     content: "";
     position: absolute;
@@ -351,6 +356,7 @@ html:not(.dark) .codeblock-light {
   }
 }
 
+/* biome-ignore lint/style/noDescendingSpecificity: TODO */
 .has-line-numbers .line-diff {
   width: 100%;
   display: inline-block;

packages/components/src/components/accordion/accordion-cover.tsx

@@ -25,15 +25,15 @@ const AccordionCover = ({
     <summary
       aria-controls={`${id}-accordion-children`}
       aria-expanded={open}
-      className="not-prose relative flex w-full cursor-pointer list-none flex-row content-center items-center space-x-2 rounded-t-xl px-5 py-4 hover:bg-gray-100 hover:dark:bg-gray-800 [&::-webkit-details-marker]:hidden"
+      className="not-prose relative flex w-full cursor-pointer list-none flex-row content-center items-center space-x-2 rounded-t-xl px-5 py-4 hover:bg-stone-100 hover:dark:bg-stone-800 [&::-webkit-details-marker]:hidden"
       data-component-part="accordion-button"
       id={`${id}-label`}
     >
       <div className={cn("absolute", topOffset)} id={id} />
       <div className="mr-2" data-component-part="accordion-caret-right">
         <Icon
           className={cn(
-            "bg-gray-700 transition dark:bg-gray-400",
+            "bg-stone-700 transition dark:bg-stone-400",
             open && "-mt-1 rotate-90 duration-200",
             !open && "duration-75"
           )}
@@ -44,7 +44,7 @@ const AccordionCover = ({
       </div>
       {!!icon && (
         <div
-          className="flex size-4 items-center justify-center fill-gray-800 text-gray-800 dark:fill-gray-100 dark:text-gray-100"
+          className="flex size-4 items-center justify-center fill-stone-800 text-stone-800 dark:fill-stone-100 dark:text-stone-100"
           data-component-part="accordion-icon"
         >
           {icon}
@@ -56,14 +56,14 @@ const AccordionCover = ({
         data-component-part="accordion-title-container"
       >
         <p
-          className="m-0 font-medium text-gray-900 dark:text-gray-200"
+          className="m-0 font-medium text-stone-900 dark:text-stone-200"
           data-component-part="accordion-title"
         >
           {title}
         </p>
         {!!description && (
           <p
-            className="m-0 text-gray-900 dark:text-gray-200"
+            className="m-0 text-stone-900 dark:text-stone-200"
             data-component-part="accordion-description"
           >
             {description}

packages/components/src/components/accordion/accordion-group.tsx

@@ -13,7 +13,7 @@ const AccordionGroup = ({ children, className }: AccordionGroupProps) => {
     <div
       className={cn(
         Classes.AccordionGroup,
-        "prose prose-gray dark:prose-invert mt-0 mb-3 overflow-hidden rounded-xl border border-gray-200/70 dark:border-white/10 [&>details+details]:border-t [&>details+details]:border-t-gray-200/70 dark:[&>details+details]:border-t-white/10 [&>details>summary]:rounded-none [&>details]:mb-0 [&>details]:rounded-none [&>details]:border-0",
+        "prose prose-stone dark:prose-invert mt-0 mb-3 overflow-hidden rounded-xl border border-stone-200/70 dark:border-white/10 [&>details+details]:border-t [&>details+details]:border-t-stone-200/70 dark:[&>details+details]:border-t-white/10 [&>details>summary]:rounded-none [&>details]:mb-0 [&>details]:rounded-none [&>details]:border-0",
         className
       )}
       data-component-part="accordion-group"

packages/components/src/components/accordion/accordion.stories.tsx

@@ -60,7 +60,7 @@ export const WithDescription: Story = {
         title="Installation"
       >
         <p>Run the following command to install Mintlify:</p>
-        <pre className="rounded bg-gray-800 p-3">npm install -g mintlify</pre>
+        <pre className="rounded bg-stone-800 p-3">npm install -g mintlify</pre>
       </Accordion>
       <Accordion
         defaultOpen={false}
@@ -71,7 +71,7 @@ export const WithDescription: Story = {
           Create a mint.json file in your project root with the following
           structure:
         </p>
-        <pre className="rounded bg-gray-800 p-3">
+        <pre className="rounded bg-stone-800 p-3">
           {`{
   "name": "My Documentation",
   "navigation": []
@@ -259,20 +259,20 @@ export const WithURLManagement: Story = {
 
     return (
       <div className="max-w-2xl space-y-3">
-        <div className="mb-4 rounded-lg bg-gray-100 p-3 dark:bg-gray-800">
-          <p className="mb-2 text-gray-500 text-xs dark:text-gray-400">
+        <div className="mb-4 rounded-lg bg-stone-100 p-3 dark:bg-stone-800">
+          <p className="mb-2 text-stone-500 text-xs dark:text-stone-400">
             Current URL (Storybook iframe):
           </p>
-          <code className="break-all text-gray-700 text-xs dark:text-gray-300">
+          <code className="break-all text-stone-700 text-xs dark:text-stone-300">
             {currentUrl}
           </code>
         </div>
-        <p className="mb-4 text-gray-600 text-sm dark:text-gray-400">
+        <p className="mb-4 text-sm text-stone-600 dark:text-stone-400">
           These accordions sync with the URL hash. Open an accordion and watch
           the URL update above. The URL is also copied to your clipboard
           automatically!
         </p>
-        <p className="mb-4 text-gray-500 text-xs dark:text-gray-400">
+        <p className="mb-4 text-stone-500 text-xs dark:text-stone-400">
           <strong>Note:</strong> In Storybook's iframe environment, URL changes
           aren't visible in the browser's address bar, but the feature works in
           production. The simulated URL display above shows what's happening.
@@ -320,7 +320,7 @@ export const WithURLManagement: Story = {
 export const WithCallbacks: Story = {
   render: () => (
     <div className="max-w-2xl space-y-3">
-      <p className="mb-4 text-gray-600 text-sm dark:text-gray-400">
+      <p className="mb-4 text-sm text-stone-600 dark:text-stone-400">
         Open the browser console to see the callback logs.
       </p>
       <Accordion
@@ -370,7 +370,7 @@ export const AllFeaturesCombined: Story = {
               <li>Open/close tracking callbacks</li>
               <li>Mount lifecycle callback</li>
             </ul>
-            <p className="mt-3 text-gray-600 text-sm dark:text-gray-400">
+            <p className="mt-3 text-sm text-stone-600 dark:text-stone-400">
               Check the browser console to see callback logs, and notice how the
               URL updates when you toggle this accordion!
             </p>
@@ -392,7 +392,7 @@ export const RichContent: Story = {
       >
         <div>
           <p className="mb-3">Here's how to use the Accordion component:</p>
-          <pre className="overflow-x-auto rounded bg-gray-800 p-4 text-sm">
+          <pre className="overflow-x-auto rounded bg-stone-800 p-4 text-sm">
             {`<Accordion
   title="My Accordion"
   defaultOpen={false}
@@ -412,24 +412,24 @@ export const RichContent: Story = {
           <h4 className="mb-2 font-semibold">Available Props:</h4>
           <table className="min-w-full text-sm">
             <thead>
-              <tr className="border-b dark:border-gray-700">
+              <tr className="border-b dark:border-stone-700">
                 <th className="py-2 pr-4 text-left">Prop</th>
                 <th className="py-2 pr-4 text-left">Type</th>
                 <th className="py-2 text-left">Required</th>
               </tr>
             </thead>
             <tbody>
-              <tr className="border-b dark:border-gray-700">
+              <tr className="border-b dark:border-stone-700">
                 <td className="py-2 pr-4">title</td>
                 <td className="py-2 pr-4">string</td>
                 <td className="py-2">Yes</td>
               </tr>
-              <tr className="border-b dark:border-gray-700">
+              <tr className="border-b dark:border-stone-700">
                 <td className="py-2 pr-4">defaultOpen</td>
                 <td className="py-2 pr-4">boolean</td>
                 <td className="py-2">Yes</td>
               </tr>
-              <tr className="border-b dark:border-gray-700">
+              <tr className="border-b dark:border-stone-700">
                 <td className="py-2 pr-4">description</td>
                 <td className="py-2 pr-4">string</td>
                 <td className="py-2">No</td>
@@ -448,8 +448,8 @@ export const RichContent: Story = {
           <p className="mb-3">
             Accordions can contain any type of content, including images:
           </p>
-          <div className="flex h-32 items-center justify-center rounded bg-gray-200 dark:bg-gray-700">
-            <span className="text-gray-500 dark:text-gray-400">
+          <div className="flex h-32 items-center justify-center rounded bg-stone-200 dark:bg-stone-700">
+            <span className="text-stone-500 dark:text-stone-400">
               Image placeholder
             </span>
           </div>
@@ -574,7 +574,7 @@ export const AccordionGroupWithRichContent: Story = {
           <p className="mb-3">
             Install the package using your preferred package manager:
           </p>
-          <pre className="overflow-x-auto rounded bg-gray-800 p-3 text-sm">
+          <pre className="overflow-x-auto rounded bg-stone-800 p-3 text-sm">
             npm install @mintlify/components
           </pre>
         </Accordion>
@@ -585,7 +585,7 @@ export const AccordionGroupWithRichContent: Story = {
           title="Configuration"
         >
           <p className="mb-3">Create a configuration file:</p>
-          <pre className="overflow-x-auto rounded bg-gray-800 p-3 text-sm">
+          <pre className="overflow-x-auto rounded bg-stone-800 p-3 text-sm">
             {`{
   "theme": "light",
   "components": ["accordion", "badge"]
@@ -599,7 +599,7 @@ export const AccordionGroupWithRichContent: Story = {
           title="Usage"
         >
           <p className="mb-3">Import and use the components:</p>
-          <pre className="overflow-x-auto rounded bg-gray-800 p-3 text-sm">
+          <pre className="overflow-x-auto rounded bg-stone-800 p-3 text-sm">
             {`import { Accordion } from '@mintlify/components';
 
 <Accordion title="Hello">
@@ -634,7 +634,7 @@ export const MultipleAccordionGroups: Story = {
   render: () => (
     <div className="max-w-2xl space-y-4">
       <div>
-        <h3 className="mb-2 font-semibold text-gray-900 text-lg dark:text-gray-100">
+        <h3 className="mb-2 font-semibold text-lg text-stone-900 dark:text-stone-100">
           Documentation
         </h3>
         <Accordion.Group>
@@ -666,7 +666,7 @@ export const MultipleAccordionGroups: Story = {
       </div>
 
       <div>
-        <h3 className="mb-2 font-semibold text-gray-900 text-lg dark:text-gray-100">
+        <h3 className="mb-2 font-semibold text-lg text-stone-900 dark:text-stone-100">
           Support
         </h3>
         <Accordion.Group>

packages/components/src/components/accordion/accordion.tsx

@@ -187,7 +187,7 @@ const GenericAccordion = ({
       <details
         className={cn(
           Classes.Accordion,
-          "mb-3 cursor-default overflow-hidden rounded-2xl border border-gray-200/70 bg-white dark:border-white/10 dark:bg-[#0b0c0e]",
+          "mb-3 cursor-default overflow-hidden rounded-2xl border border-stone-200/70 bg-white dark:border-white/10 dark:bg-[#0b0c0e]",
           className
         )}
         data-component-part="accordion"
@@ -211,7 +211,7 @@ const GenericAccordion = ({
         {/** biome-ignore lint/a11y/useSemanticElements: TODO */}
         <div
           aria-labelledby={`${id}-label`}
-          className="prose prose-gray dark:prose-invert mx-6 mt-2 mb-4 cursor-default overflow-x-auto"
+          className="prose prose-stone dark:prose-invert mx-6 mt-2 mb-4 cursor-default overflow-x-auto"
           data-component-part="accordion-content"
           id={`${id}-accordion-children`}
           role="region"