Content refresh

.claude/CLAUDE.md

@@ -34,6 +34,41 @@
 - Use broadly applicable examples rather than overly specific business cases
 - Lead with context when helpful - explain what something is before diving into implementation details
 
+### Style preferences (learned from content refresh project)
+#### Headings and formatting
+- Use sentence case for all headings ("Getting started", not "Getting Started")
+- Use "Properties" instead of "Props" for component documentation
+- Use sentence case for code block titles ("Expandable example", not "Expandable Example")
+
+#### Component introductions
+- Start with action-oriented language: "Use [component] to..." rather than "The [component] component..."
+- Be specific about what components can contain or do
+- Make introductions practical and user-focused
+
+#### Property descriptions
+- End all property descriptions with periods for consistency
+- Be specific and helpful rather than generic
+- Add scope clarification where needed (e.g., "For Font Awesome icons only:")
+- Use proper technical terminology ("boolean" not "bool")
+
+#### Language and tone
+- Prefer active voice and direct language
+- Remove unnecessary words while maintaining clarity
+- Use "you complete" over "completing" for more direct communication
+- Break complex instructions into clear numbered steps
+- Make language more precise and contextual
+
+#### Code examples
+- Keep examples simple and practical
+- Use consistent formatting and naming
+- Provide clear, actionable examples rather than showing multiple options when one will do
+
+#### Content organization
+- Structure content in the order users need it
+- Combine related information to reduce redundancy
+- Use specific links (direct to relevant pages rather than generic dashboards)
+- Put most commonly needed information first
+
 ## Git workflow
 - NEVER use --no-verify when committing
 - Ask how to handle uncommitted changes before starting

components/cards.mdx

@@ -1,131 +1,141 @@
 ---
 title: "Cards"
-description: "Highlight main points or links with customizable icons"
-icon: 'square-mouse-pointer'
+description: "Highlight main points or links with customizable layouts and icons"
+icon: "square-mouse-pointer"
 ---
 
-<Card title="Card Title" icon="text" href="/components/columns">
+Use cards to create visual containers for content. Cards are flexible containers that can include text, icons, images, and links.
+
+## Basic card
+
+<Card title="Card title" icon="text" href="/components/columns">
   This is how you use a card with an icon and a link. Clicking on this card
   brings you to the Columns page.
 </Card>
 
-<RequestExample>
-  ```mdx Card Example
-  <Card title="Click on me" icon="text" href="/components/columns">
-    This is how you use a card with an icon and a link. Clicking on this card
-    brings you to the Columns page.
-  </Card>
-  ```
-
-```mdx Image Card Example
-<Card title="Image Card" img="/images/card-with-image.png">
-  Here is an example of a card with an image
+```mdx Card example
+<Card title="Card title" icon="text" href="/components/columns">
+  This is how you use a card with an icon and a link. Clicking on this card
+  brings you to the Columns page.
 </Card>
 ```
 
-</RequestExample>
+## Card variations
 
-## Horizontal card
+Cards support several layout and styling options to fit different content needs.
 
-Add a `horizontal` property to display cards horizontally.
+### Horizontal layout
 
-<Card title="Horizontal Card" icon="text" horizontal>
-  Here is an example of a horizontal card
+Add the `horizontal` property to display cards in a more compact, horizontal layout.
+
+<Card title="Horizontal card" icon="text" horizontal>
+  This is an example of a horizontal card.
 </Card>
 
-## Image card
+```mdx Horizontal card example
+<Card title="Horizontal card" icon="text" horizontal>
+  This is an example of a horizontal card.
+</Card>
+```
+
+### Image cards
 
-Add an `img` property to display an image on the top of the card.
+Add an `img` property to display an image at the top of the card.
 
-<Card title="Image Card" img="https://mintlify-assets.b-cdn.net/yosemite.jpg">
-  Here is an example of a card with an image
+<Card title="Image card" img="https://mintlify-assets.b-cdn.net/yosemite.jpg">
+  This is an example of a card with an image.
 </Card>
 
-## Link card
+```mdx Image card example
+<Card title="Image card" img="/images/card-with-image.png">
+  This is an example of a card with an image.
+</Card>
+```
 
-You can customize the CTA and whether or not to display the arrow on the card. By default, the arrow will only show for external links.
+### Link cards with custom CTAs
+
+You can customize the call-to-action text and control whether an arrow appears. By default, arrows only show for external links.
+
+<Card title="Link card" icon="link" href="/components/columns" arrow="true" cta="Click here">
+  This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
+</Card>
 
+```mdx Link card example
 <Card
   title="Link card"
   icon="link"
   href="/components/columns"
   arrow="true"
   cta="Click here"
 >
-  This is how you use a card with an icon and a link. Clicking on this card
-  brings you to the Columns page.
+  This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
 </Card>
-
-<RequestExample>
-  ```mdx Card Example
-  <Card
-    title="Link card"
-    icon="link"
-    href="/components/columns"
-    arrow="true"
-    cta="Click here"
-  >
-    This is how you use a card with an icon and a link. Clicking on this card
-    brings you to the Columns page.
-  </Card>
-  ```
-</RequestExample>
+```
 
 ## Grouping cards
 
-You can group cards in [columns](/components/columns).
+Use the [Columns component](/components/columns) to organize multiple cards side by side.
 
 <Columns cols={2}>
-  <Card title="First Card" icon="panel-left-close">
+  <Card title="First card" icon="panel-left-close">
     This is the first card.
   </Card>
-  <Card title="Second Card" icon="panel-right-close">
+  <Card title="Second card" icon="panel-right-close">
     This is the second card.
   </Card>
 </Columns>
 
-## Props
+```mdx Columns example
+<Columns cols={2}>
+  <Card title="First card" icon="panel-left-close">
+    This is the first card.
+  </Card>
+  <Card title="Second card" icon="panel-right-close">
+    This is the second card.
+  </Card>
+</Columns>
+```
+
+## Properties
 
 <ResponseField name="title" type="string" required>
-  The title of the card
+  The title displayed on the card
 </ResponseField>
 
 <ResponseField name="icon" type="string or svg">
-  A [Font Awesome icon](https://fontawesome.com/icons), [Lucide
-  icon](https://lucide.dev/icons), or JSX compatible SVG code in `icon={}`.
-
-  To generate JSX compatible SVG code:
-
+  Icon to display on the card. Use a [Font Awesome icon](https://fontawesome.com/icons) name, [Lucide icon](https://lucide.dev/icons) name, or JSX-compatible SVG code wrapped in `icon={}`.
+
+  For custom SVG icons:
   1. Use the [SVGR converter](https://react-svgr.com/playground/).
   2. Copy the code inside the `<svg/>` tag.
-  3. Paste the code into your card. Make sure to only copy and paste the code inside the `<svg/>` tag.
-  4. You may need to decrease the height and width to make the image fit.
+  3. Paste the code into your card.
+  4. Adjust height and width as needed.
 </ResponseField>
 
 <ResponseField name="iconType" type="string">
-  One of `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`
+  Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, or `brands`.
 </ResponseField>
 
 <ResponseField name="color" type="string">
-  The color of the icon as a hex code
+  Icon color as a hex code (e.g., `#FF6B6B`).
 </ResponseField>
 
 <ResponseField name="href" type="string">
-  The url that clicking on the card would navigate the user to
+  URL to navigate to when the card is clicked.
 </ResponseField>
 
 <ResponseField name="horizontal" type="boolean">
-  Makes the card more compact and horizontal
+  Display the card in a compact horizontal layout.
 </ResponseField>
 
 <ResponseField name="img" type="string">
-  The url or local path to an image to display on the top of the card
+  URL or local path to an image displayed at the top of the card.
 </ResponseField>
 
 <ResponseField name="cta" type="string">
-  Label for the action button
+  Custom text for the action button.
 </ResponseField>
 
 <ResponseField name="arrow" type="boolean">
-  Enable or disable the link arrow icon
+  Show or hide the link arrow icon.
 </ResponseField>

components/expandables.mdx

@@ -1,9 +1,11 @@
 ---
 title: "Expandables"
-description: "Toggle to display nested properties."
-icon: 'list-tree'
+description: "Toggle to display nested properties"
+icon: "list-tree"
 ---
 
+Use expandables to show and hide nested content within response fields. Expandables are particularly useful for displaying complex object properties in API documentation.
+
 <ResponseField name="user" type="User Object">
   <Expandable title="properties">
 
@@ -18,9 +20,7 @@
   </Expandable>
 </ResponseField>
 
-<RequestExample>
-
-```mdx Expandable Example
+```mdx Expandable example
 <ResponseField name="user" type="User Object">
   <Expandable title="properties">
     <ResponseField name="full_name" type="string">
@@ -34,15 +34,12 @@
 </ResponseField>
 ```
 
-</RequestExample>
-
-## Props
+## Properties
 
 <ResponseField name="title" type="string">
-  The name of the object you are showing. Used to generate the "Show NAME" and
-  "Hide NAME" text.
+  The name of the object you are showing.
 </ResponseField>
 
 <ResponseField name="defaultOpen" type="boolean" default="false">
-  Set to true to show the component as open when the page loads.
+  Set to `true` for the expandable to open when the page loads
 </ResponseField>