Add style guide

.claude/CLAUDE.md

@@ -15,7 +15,7 @@ You are an experienced, pragmatic technical writer with robust content strategy
 
 - Use direct tool calls (Read, Glob, Grep) instead of sub-agents when you know file paths or can search for specific terms
 - Only use the Explore agent for genuinely open-ended codebase searches
-- Example: If asked to "update the accordion component docs", read `/content/components/accordions.mdx` directly rather than spawning an agent to find it
+- Example: If asked to "update the accordion component docs", read `components/accordions.mdx` directly rather than spawning an agent to find it
 
 ### Workflow for complex tasks
 
@@ -29,87 +29,21 @@ For major documentation restructuring or complex multi-page changes:
 - Config: docs.json for navigation, theme, settings
   - See the docs.json schema: https://mintlify.com/docs.json
 - Use Mintlify components. If you ever need to learn how a component works, search in the docs/components/ dir
-- Only update English language content. All translations are handled automatically after a PR merges into the docs repo. This includes languages other than English in the docs.json navigation.
 
-## Content strategy
-- We document just enough so that users are successful. Too much content makes it hard to find what people are looking for. Too little makes it too challenging to accomplish users' goals.
-- Prioritize accuracy and usability of information
-- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
-- Check existing patterns for consistency
-- Start by making the smallest reasonable changes
-- When creating new pages, include them in the navigation group related to the user journey. For example, new content on customizing a site would go in the "Customize" group and information about adding a second deployment would go in "Deploy"
+## Style guide
 
-## Frontmatter requirements for pages
-- title: Clear, descriptive page title
-- description: Concise summary for SEO/navigation
-- keywords: relevant keywords for search and SEO
+Before you write or edit content, read `style-guide/README.md` and the style guide files relevant to your change. The style guide is the source of truth for audience, voice and tone, terminology, formatting, component usage, content strategy, and localization. It overrides the Google developer documentation style guide where they differ. Don't restate its rules here; update the style guide instead.
 
-## Audience
-- The Mintlify audience is varied. Some people are highly technical and others are not
-- We need to support users who prefer to work locally with the CLI and are comfortable with Git and people who use the web editor and prefer Git to be abstracted away
-
-## Writing standards
-- Second-person voice ("you")
-- Prerequisites at start of procedural and tutorial content
-- Match style and formatting of existing pages
-- All code blocks must have language tags
-- All images and media must have descriptive alt text
-- Use root-relative paths for internal links like `/components/accordions`
-- Lead with context when helpful - explain what something is before diving into implementation details
-- Use sentence case for all headings ("Getting started", not "Getting Started")
-- Use sentence case for code block titles ("Expandable example", not "Expandable Example")
-- Use active voice and direct language
-- Remove unnecessary words while maintaining clarity
-- Break complex instructions into clear numbered steps
-- Use [Lucide](https://lucide.dev) icon library
-- Use kebab-case for file naming
-
-### Language and tone standards
-- **Avoid promotional language**: Never use phrases like "rich heritage," "breathtaking," "captivates," "stands as a testament," "plays a vital role," or similar marketing language in technical documentation
-- **Reduce conjunction overuse**: Limit use of "moreover," "furthermore," "additionally," "on the other hand" - favor direct, clear statements
-- **Avoid editorializing**: Remove phrases like "it's important to note," "this article will," "in conclusion," or personal interpretations
-- **No undue emphasis**: Avoid overstating importance or significance of routine technical concepts
-
-### Technical accuracy standards
-- **Verify all links**: Every internal link and external reference must be tested and functional before publication
-- **Use precise citations**: Replace vague references with specific documentation, version numbers, and accurate sources
-- **Maintain consistency**: Use consistent terminology, formatting, and language variety throughout all documentation
-- **Valid technical references**: Ensure all code examples, API references, and technical specifications are current and accurate
-
-### Formatting discipline
-
-- **Purposeful formatting**: Use bold, italics, and emphasis only when it serves the user's understanding, not for visual appeal
-- **Clean structure**: Avoid excessive formatting or decorative elements that don't add functional value. Never use emoji
-- **Minimal markup**: Keep formatting clean and functional, avoiding unnecessary markdown or styling
-
-### 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 for actual use cases rather than generic
-- Add scope clarification where needed (for example, "For Font Awesome icons only:")
-- Use proper technical terminology ("boolean" not "bool")
-
-### 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 with most commonly needed information first and most specific information last
-- Combine related information to reduce redundancy
+Beyond the style guide:
+- Never lie, guess, or make up information. Verify links, code examples, and technical claims before you publish them.
+- Check existing pages for patterns and match them.
 
 ## Before submitting work
 - [ ] Run `mint broken-links` to check internal links
 - [ ] Run `mint a11y` to check for accessibility issues
 - [ ] Manually test external links don't 404
 - [ ] Run `vale $(git diff --name-only main)` to check style and spelling
-- [ ] Verify all code blocks have language tags
-- [ ] Confirm frontmatter includes title, description, keywords
-- [ ] Check formatting matches similar existing pages
+- [ ] Check changes against the style guide, not only Vale
 - [ ] Read changes aloud to catch awkward phrasing
 - [ ] List any uncertain areas that need extra review
 
@@ -120,8 +54,3 @@ Provide a structured summary:
 - **Rationale**: Why these changes solve the problem
 - **Alternatives considered**: Other approaches evaluated
 - **Areas of uncertainty**: What needs extra review
-
-## Do not
-- Skip frontmatter on any MDX file
-- Use absolute URLs for internal links
-- Include untested code examples

.cursor/rules/component-reference.mdc

@@ -5,33 +5,30 @@ alwaysApply: true
 ---
 # Mintlify component reference
 
+Syntax examples for Mintlify components. For when to use each component, and for all other writing and formatting rules, follow `style-guide/formatting-and-components.md`.
+
 docs.json schema: https://mintlify.com/docs.json
 
 ### Callout components
 
-#### Note - Additional helpful information
 <Note>
-Supplementary information that supports the main content without interrupting flow. Use for helpful context, related concepts, or non-critical details.
+Useful information the reader can skip without failing.
 </Note>
 
-#### Tip - Best practices and pro tips
 <Tip>
-Expert advice, shortcuts, or best practices that enhance user success. Use for optimization suggestions, time-savers, or friendly recommendations.
+A best practice or optional way to do something.
 </Tip>
 
-#### Warning - Important cautions
 <Warning>
-Critical information about potential issues, breaking changes, or destructive actions. Use sparingly and only for genuine risks.
+Risk of data loss, security issues, or irreversible actions.
 </Warning>
 
-#### Info - Neutral contextual information
 <Info>
-Background information, context, or neutral announcements. Use for prerequisites, permissions, or required setup information.
+FEATURE requires a [Pro or Enterprise plan](https://mintlify.com/pricing?ref=FEATURE).
 </Info>
 
-#### Check - Success confirmations
 <Check>
-Positive confirmations, successful completions, or achievement indicators. Use to verify steps were completed correctly.
+Your site is deployed.
 </Check>
 
 ### Code components
@@ -227,7 +224,6 @@ Complete walkthrough from installation to your first API call in under 10 minute
 ### Media and advanced components
 
 #### Frames for images
-Wrap all images in frames with descriptive alt text.
 
 <Frame>
 <img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
@@ -251,79 +247,3 @@ API
 - Fixed pagination issue with large datasets
 - Resolved authentication timeout problems
 </Update>
-
-## Required page structure
-
-Every documentation page must begin with YAML frontmatter:
-
-```yaml
----
-title: "Clear, specific, keyword-rich title"
-description: "Concise description explaining page purpose and value"
----
-```
-
-## Content quality standards
-
-### Code examples requirements
-- Always include complete, runnable examples that users can copy and execute
-- Show proper error handling and edge case management
-- Use realistic data instead of placeholder values (you can use `minty`, `wintergreen`, `spearmint` or similar for Mintlify examples)
-- Include expected outputs and results for verification
-- Test all code examples thoroughly before publishing
-- Specify language and include filename when relevant
-- Add explanatory comments for complex logic
-- Never include real API keys or sensitive credentials
-
-### API documentation requirements
-- Document all parameters including optional ones with clear descriptions
-- Show both success and error response examples with realistic data
-- Include rate limiting information with specific limits
-- Provide authentication examples showing proper format
-- Explain all HTTP status codes and error handling
-- Cover complete request/response cycles
-- Include pagination details when applicable
-
-### Accessibility requirements
-- Include descriptive alt text for all images and diagrams
-- Use specific, actionable link text instead of "click here"
-- Ensure proper heading hierarchy starting with H2
-- Provide keyboard navigation considerations
-- Use sufficient color contrast in examples and visuals
-- Structure content for easy scanning with headers and lists
-- Use semantic HTML elements appropriately
-
-## Component selection logic
-
-### When to use each component
-- **Steps**: Procedures, tutorials, setup guides, and sequential instructions
-- **Tabs**: Platform-specific content, alternative approaches, or multiple installation methods
-- **CodeGroup**: Same concept demonstrated in multiple programming languages
-- **Accordions**: Supplementary information that might interrupt main flow
-- **Cards/CardGroup**: Navigation, feature overviews, and related resources
-- **Frame**: Wrap all images with descriptive captions when helpful
-- **RequestExample/ResponseExample**: Specifically for API endpoint documentation
-- **Expandable**: Nested object properties or hierarchical information
-- **ParamField**: API parameters with types and requirements
-- **ResponseField**: API response documentation with clear descriptions
-
-### Callout selection guidelines
-- **Note**: Extra relevant information that supports main content (not crucial to task completion)
-- **Warning**: Potentially destructive actions, breaking changes, or critical cautions
-- **Info**: Required information, permissions, prerequisites, neutral announcements, background context
-- **Tip**: Opinionated best practices, expert advice, shortcuts, or friendly recommendations
-- **Check**: Success confirmations, positive completions, achievement indicators
-- Don't stack callouts - separate with content between them
-
-## Component selection decision trees
-
-### For procedures:
-- Use ordered lists when: Sequential simple tasks. For example "Navigate to the dashboard" or "Click Configurations"
-- Use <Steps> when: Sequential complex tasks that require subtasks to complete
-- Use <Tabs> when: Platform-specific alternatives
-- Use <AccordionGroup> when: Optional supplementary info
-
-### For code examples:
-- Use single ``` when: One language, simple example
-- Use <CodeGroup> when: Same concept in multiple languages
-- Use <RequestExample>/<ResponseExample> when: API documentation