standardize intro sentences

Author: devalog

.vale/styles/FernStyles/Acronyms.yml

@@ -88,3 +88,4 @@ exceptions:
   - JPEG
   - RPG
   - MIME
+  - PNG

.vale/styles/FernStyles/Headings.yml

@@ -115,3 +115,4 @@ exceptions:
   - YAML
   - fern.config.json
   - Font Awesome
+  - Card Group

fern/products/docs/pages/component-library/default-components/accordions.mdx

@@ -3,7 +3,7 @@ title: Accordions
 description: Display expandable/collapsible options with browser search functionality
 ---
 
-The Accordion component creates expandable sections with searchable, SEO-friendly content that remains accessible even when collapsed. 
+The Accordion component creates expandable sections with searchable, SEO-friendly content that remains accessible even when collapsed. Use accordions for FAQs, documentation sections, settings panels, or any content where progressive disclosure improves readability.
 
 <div className="highlight-frame">
 <AccordionGroup>
@@ -55,14 +55,14 @@ Within each Accordion, you can embed images, videos, and other components (Callo
 
 <Accordion title="Nested components">
 <Note>
-  Here's a callout nested in an Accordion
+  Here's a Callout nested in an Accordion
 </Note>
 </Accordion>
 
 ```jsx
 <Accordion title="Nested components">
 <Note>
-  Here's a callout nested in an Accordion
+  Here's a Callout nested in an Accordion
 </Note>
 </Accordion>
 ```

fern/products/docs/pages/component-library/default-components/anchor.mdx

@@ -3,7 +3,7 @@ title: Anchor
 description: Create linkable anchors for paragraphs, tables, and other content without headings
 ---
 
-The Anchor component creates links to specific paragraphs, tables, and other sections of content that don't have headings. 
+The Anchor component creates direct links to specific content like paragraphs, tables, and code blocks. Use anchors when you need to reference non-heading content that doesn't automatically generate its own link.
 
 <Note>
   Headings automatically generate anchor links based on their text content, so you don't need to use the `<Anchor>` component for headings.

fern/products/docs/pages/component-library/default-components/button.mdx

@@ -3,7 +3,7 @@ title: 'Button'
 description: 'Interactive button component with multiple variants and intents'
 ---
 
-The `Button` component creates a flexible way to create interactive buttons with various styles, sizes, and intents.
+The Button component renders interactive buttons with various styles, sizes, and intents.
 
 ## Usage
 

fern/products/docs/pages/component-library/default-components/callouts.mdx

@@ -3,7 +3,7 @@ title: 'Callouts'
 description: 'Highlight important information, warnings, or tips in your documentation.'
 ---
 
-Callouts help highlight important information, warnings, or tips in your documentation. They provide visual emphasis through distinct styling and icons to make key messages stand out to readers. 
+Callouts highlight important information, warnings, or tips in your documentation. Use Callouts to emphasize critical details that readers shouldn't miss, such as breaking changes, prerequisites, or helpful best practices.
 
 To display very short pieces of information like status indicators and version numbers, use the [Badges component](/docs/writing-content/components/badges).
 

fern/products/docs/pages/component-library/default-components/cards.mdx

@@ -3,9 +3,9 @@ title: 'Cards'
 description: 'Use cards to display content in a box'
 ---
 
-Cards are container components that group related content and actions together. They provide a flexible way to present information with optional elements like icons, titles, and links in a visually distinct box. 
+Cards are container components that group related content and actions in a visually distinct box. Optional elements include icons, titles, and links.
 
-You can use individual cards or arrange multiple cards in a responsive grid layout using the use the `CardGroup` component. Groups of cards are useful for organizing related content like feature lists, navigation options, or step-by-step guides.
+You can use individual cards or arrange multiple cards in a responsive grid layout using the `CardGroup` component. Card groups are useful for organizing feature lists, navigation options, or step-by-step guides.
 
 ## Usage
 

fern/products/docs/pages/component-library/default-components/code-blocks.mdx

@@ -4,7 +4,7 @@ description: 'Learn how to enhance your documentation with customizable code blo
 max-toc-depth: 2
 ---
 
-Use code blocks to showcase code examples with syntax highlighting powered by [Shiki](https://shiki.matsu.io/). Code blocks support features like line highlighting, focusing, titles, and deep linking to make your code examples more readable and interactive.
+The Code Block component displays code examples with syntax highlighting powered by [Shiki](https://shiki.matsu.io/). Code Blocks support line highlighting, focusing, titles, and deep linking to make your code examples more readable and interactive.
 
 ## Usage
 

fern/products/docs/pages/component-library/default-components/embed.mdx

@@ -3,7 +3,7 @@ title: "Embedded assets and files"
 description: "Embed local assets like PDFs, videos, and more in your documentation"
 ---
 
-Use native HTML5 tags to embed local assets like PDFs, videos, and more in your documentation.
+Embed local assets like PDFs, videos, and other media directly in your documentation using native HTML5 tags. This allows you to include rich content without relying on external hosting.
 
 <Info title="Supported tags">
   Fern supports using the `<embed src="..." />` tag to embed [external content](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed) and the `<source src="..." />` tag to embed [media or image sources](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source).

fern/products/docs/pages/component-library/default-components/endpoint-schema-snippet.mdx

@@ -3,13 +3,11 @@ title: 'Endpoint Schema Snippet'
 description: 'Reference an endpoint schema from your API Reference'
 ---
 
-Use the `EndpointSchemaSnippet` component to reference an endpoint's schema from 
-your API Reference.
-
-Passing no selector will render the entire schema. If you want to reference a particular piece of the schema, you can use the optional `selector` prop
-to specify the path to the schema you want to reference. The available selectors are: `request`,
-`request.path`, `request.query`, `request.body`, `response`, and `response.body`.
+The EndpointSchemaSnippet component displays endpoint schemas from your API Reference. By default, it renders the complete schema, or you can use the `selector` prop to display specific parts like request body, response, path parameters, or query parameters.
 
+<Note>
+  Markdown-rich field descriptions aren't yet supported and will display as plain text. See the [Request path](#request-path) example below.
+</Note>
 
 ## Usage
 
@@ -73,9 +71,3 @@ Passing `response` as the selector will only render the response schema.
 ```jsx Markdown
 <EndpointSchemaSnippet endpoint="POST /chat/{domain}" selector="response.body" />
 ```
-
-<Warning>
-  The EndpointSchemaSnippet component doesn't yet support rendering markdown-rich field descriptions.
-  
-  See [request.endpoint.path](/learn/docs/writing-content/components/schema-snippet#request.endpoint.path) above for an example of a markdown-rich description that does not yet render as markdown.
-</Warning>