@tamagui/cli 2.7.7 → 3.0.0-beta.1097.1

package/src/generate-prompt.ts

@@ -2,22 +2,20 @@ import { join } from 'node:path'
 import * as FS from 'fs-extra'
 import type { CLIResolvedOptions } from '@tamagui/types'
 
-interface GeneratePromptOptions extends CLIResolvedOptions {
+export interface GeneratePromptOptions extends CLIResolvedOptions {
   output?: string
+  styleValueSyntax?: 'string' | 'object' | 'both'
 }
 
 export async function generatePrompt(options: GeneratePromptOptions) {
   const { paths, output } = options
 
-  // Regenerate the config first
+  // regenerate the config first
   const { loadTamagui } = require('@tamagui/static/loadTamagui')
   process.env.TAMAGUI_KEEP_THEMES = '1'
-  await loadTamagui({
-    ...options.tamaguiOptions,
-    platform: 'web',
-  })
+  await loadTamagui({ ...options.tamaguiOptions, platform: 'web' }, true)
 
-  // Read the generated config
+  // read the generated config
   const configPath = join(paths.dotDir, 'tamagui.config.json')
 
   if (!FS.existsSync(configPath)) {
@@ -28,349 +26,257 @@ export async function generatePrompt(options: GeneratePromptOptions) {
 
   const config = await FS.readJSON(configPath)
 
-  // Generate markdown
-  const markdown = generateMarkdown(config)
+  // resolve styleValueSyntax: options -> env -> config setting -> interactive prompt if tty / default 'both'
+  const configSetting = config.tamaguiConfig?.settings?.styleValueSyntax
+  const explicitChoice =
+    options.styleValueSyntax ||
+    (process.env.TAMAGUI_STYLE_VALUE_SYNTAX as any) ||
+    configSetting
+  const { resolveStyleValueSyntax } = require('./setup-prompt')
+  const resolvedSyntax = await resolveStyleValueSyntax(explicitChoice)
+
+  // generate markdown
+  const markdown = generateMarkdown(config, { styleValueSyntax: resolvedSyntax })
 
-  // Write to file
+  // write to file
   const outputPath = output || join(process.cwd(), 'tamagui-prompt.md')
   await FS.writeFile(outputPath, markdown, 'utf-8')
 
   console.info(`\n  ✓ Generated prompt file at ${outputPath}\n`)
 }
 
-function generateMarkdown(config: any): string {
+export interface GenerateMarkdownOptions {
+  styleValueSyntax?: 'string' | 'object' | 'both'
+}
+
+export function generateMarkdown(config: any, options?: GenerateMarkdownOptions): string {
   const sections: string[] = []
 
-  // Header
+  // header
   sections.push('# Tamagui Configuration\n\n')
   sections.push(
     'This document provides an overview of the Tamagui configuration for this project.\n\n'
   )
 
-  // Get shorthands for use throughout the document
+  // get shorthands for use throughout the document
   const shorthands = config.tamaguiConfig?.shorthands || {}
   const reverseShorthands: Record<string, string> = {}
   for (const [short, full] of Object.entries(shorthands)) {
     reverseShorthands[full as string] = short
   }
 
-  // Helper function to get the correct property name based on settings
+  // helper function to get the correct property name based on settings
   const getPropName = (fullProp: string): string => {
     const settings = config.tamaguiConfig?.settings || {}
-    if (settings.onlyAllowShorthands && reverseShorthands[fullProp]) {
-      return reverseShorthands[fullProp]
+    if (settings.onlyAllowShorthands) {
+      if (reverseShorthands[fullProp]) return reverseShorthands[fullProp]
+      if (fullProp === 'backgroundColor' && reverseShorthands['background']) {
+        return reverseShorthands['background']
+      }
     }
     return fullProp
   }
 
-  // Settings (moved to top)
   const settings = config.tamaguiConfig?.settings || {}
-  if (Object.keys(settings).length > 0) {
-    sections.push('## Configuration Settings\n\n')
-    sections.push(
-      '**IMPORTANT:** These settings affect how you write Tamagui code in this project.\n\n'
-    )
+  const syntaxChoice = options?.styleValueSyntax || settings.styleValueSyntax || 'both'
 
-    if (settings.defaultFont) {
-      sections.push(`### Default Font: \`${settings.defaultFont}\`\n\n`)
-      sections.push(
-        `All text components will use the "${settings.defaultFont}" font family by default.\n\n`
-      )
-    }
+  // configuration settings
+  sections.push('## Configuration Settings\n\n')
+  sections.push(
+    '**IMPORTANT:** These settings affect how you write Tamagui code in this project.\n\n'
+  )
 
-    if (settings.onlyAllowShorthands !== undefined) {
-      sections.push(`### Only Allow Shorthands: \`${settings.onlyAllowShorthands}\`\n\n`)
-      if (settings.onlyAllowShorthands) {
-        sections.push('**You MUST use shorthand properties in this project.**\n\n')
-        sections.push('Full property names are not allowed. For example:\n')
-        sections.push('- ✅ `<View w="$10" />` (correct)\n')
-        sections.push('- ❌ `<View width="$10" />` (will error)\n\n')
-        sections.push(
-          'See the Shorthand Properties section below for all available shorthands.\n\n'
-        )
-      } else {
-        sections.push('You can use either shorthand or full property names.\n\n')
-      }
-    }
+  if (settings.defaultFont) {
+    sections.push(`### Default Font: \`${settings.defaultFont}\`\n\n`)
+    sections.push(
+      `All text components will use the "${settings.defaultFont}" font family by default.\n\n`
+    )
+  }
 
-    if (settings.themeClassNameOnRoot !== undefined) {
+  if (settings.onlyAllowShorthands !== undefined) {
+    sections.push(`### Only Allow Shorthands: \`${settings.onlyAllowShorthands}\`\n\n`)
+    if (settings.onlyAllowShorthands) {
+      sections.push('**You MUST use shorthand properties in this project.**\n\n')
+      sections.push('Full property names are not allowed. For example:\n')
+      sections.push('- ✅ `<View w="10" />` (correct)\n')
+      sections.push('- ❌ `<View width="10" />` (will error)\n\n')
       sections.push(
-        `### Theme Class Name on Root: \`${settings.themeClassNameOnRoot}\`\n\n`
+        'See the Shorthand Properties section below for all available shorthands.\n\n'
       )
-      if (settings.themeClassNameOnRoot) {
-        sections.push('Theme classes are applied to the root HTML element.\n\n')
-      }
-    }
-
-    // Check for platform-specific settings
-    const platform = settings.platform || settings.defaultProps?.platform
-    if (platform) {
-      sections.push(`### Platform Mode: \`${platform}\`\n\n`)
-
-      if (platform === 'web') {
-        sections.push('This project is configured for **web only**.\n\n')
-      } else if (platform === 'native') {
-        sections.push('This project is configured for **React Native only**.\n\n')
-      }
-    }
-
-    // Check for web-specific optimizations
-    if (settings.webContainerType) {
-      sections.push(`### Web Container Type: \`${settings.webContainerType}\`\n\n`)
-      sections.push('Enables web-specific container query optimizations.\n\n')
-    }
-
-    // Check for strictness settings (common patterns)
-    const configString = JSON.stringify(config.tamaguiConfig)
-    if (configString.includes('semi-strict-web')) {
-      sections.push('### Mode: `semi-strict-web`\n\n')
-      sections.push('This configuration uses semi-strict-web mode, which:\n')
-      sections.push('- Optimizes for web performance\n')
-      sections.push('- May have limited React Native API support\n')
-      sections.push('- Focuses on web-first development\n\n')
+    } else {
+      sections.push('You can use either shorthand or full property names.\n\n')
     }
   }
 
-  // Store components section for later (will be output at the end)
-  const componentsSection: string[] = []
-
-  const allComponents: string[] = []
-  for (const componentModule of config.components) {
-    const componentNames = Object.keys(componentModule.nameToInfo)
-    allComponents.push(...componentNames)
-  }
-
-  // Group components by prefix (e.g., Dialog, DialogClose -> Dialog.Close)
-  // Strategy: Find potential base components and check if others follow the pattern
-  const componentGroups = new Map<string, Set<string>>()
-  const processed = new Set<string>()
-
-  // Sort components to process shorter names first (potential base components)
-  const sortedComponents = [...allComponents].sort((a, b) => a.length - b.length)
-
-  for (const name of sortedComponents) {
-    if (processed.has(name)) continue
-
-    // Check if other components start with this name followed by an uppercase letter
-    const children = allComponents.filter(
-      (other) =>
-        other !== name && other.startsWith(name) && other[name.length]?.match(/[A-Z]/)
+  // style value syntax section
+  if (syntaxChoice === 'string') {
+    sections.push('### Style value syntax: `string`\n\n')
+    sections.push(
+      'Only the string form is allowed in this project (e.g. `bg="red hover:blue"`).\n\n'
     )
+  } else if (syntaxChoice === 'object') {
+    sections.push('### Style value syntax: `object`\n\n')
+    sections.push(
+      "Only the object form is allowed in this project (e.g. `bg={{ default: 'red', hover: 'blue' }}`).\n\n"
+    )
+  } else {
+    sections.push('### Style value syntax\n\n')
+    sections.push('Both string and object style value syntax are allowed.\n\n')
+  }
 
-    if (children.length > 0) {
-      // This is a base component with children
-      componentGroups.set(name, new Set(children))
-      processed.add(name)
-      children.forEach((child) => processed.add(child))
+  if (settings.addThemeClassName !== undefined) {
+    sections.push(`### Theme Class Name: \`${settings.addThemeClassName}\`\n\n`)
+    if (settings.addThemeClassName === 'html') {
+      sections.push('Theme classes are applied to the root HTML element.\n\n')
     }
   }
 
-  // Collect standalone components (not part of any group)
-  const standaloneComponents = allComponents.filter((name) => !processed.has(name))
-
-  componentsSection.push('## Components\n\n')
-  componentsSection.push('The following components are available:\n\n')
+  if (settings.allowedStyleValues) {
+    sections.push('### Allowed Style Values\n\n')
+    sections.push(
+      `Type validation: \`${JSON.stringify(settings.allowedStyleValues)}\`.\n\n`
+    )
+    sections.push(
+      'Single-token values are type-checked. Run `tamagui check --strict` to also validate conditional payloads.\n\n'
+    )
+  }
 
-  // Combine and sort all base components (both standalone and those with children)
-  const allBaseComponents = [
-    ...standaloneComponents,
-    ...Array.from(componentGroups.keys()),
-  ].sort()
+  // flat value grammar section
+  sections.push('## Flat Value Grammar\n\n')
+  sections.push('Conditional style values follow this grammar:\n\n')
+  sections.push('```txt\n')
+  sections.push('value  := base? clause*\n')
+  sections.push('clause := modifier(:modifier)*:payload\n')
+  sections.push('```\n\n')
+  sections.push(
+    '- No `$` sigils: bare token names (`bg="background"`, not `bg="$background"`).\n'
+  )
+  sections.push(
+    '- Kebab-case theme names: `background-hover`, `border-color`, `shadow-color`.\n'
+  )
+  sections.push('- Numbers are px: `p={4}` is 4px, while `p="4"` is space token 4.\n')
+  sections.push(
+    '- Specificity precedence: platform (`ios:` > `native:` > bare) > condition count > category (media < container < theme < group < state).\n\n'
+  )
 
-  // Output components
-  for (const name of allBaseComponents) {
-    componentsSection.push(`- ${name}\n`)
+  const bgProp = getPropName('background')
+  const pProp = getPropName('padding')
 
-    // If this component has children, output them
-    if (componentGroups.has(name)) {
-      const children = Array.from(componentGroups.get(name)!).sort()
-      for (const child of children) {
-        const suffix = child.slice(name.length)
-        componentsSection.push(`  - ${name}.${suffix}\n`)
-      }
-    }
+  if (syntaxChoice === 'string') {
+    sections.push('**String form:**\n\n')
+    sections.push('```tsx\n')
+    sections.push(
+      `<View ${bgProp}="background hover:background-hover dark:blue-500" ${pProp}="4 sm:6 max-sm:2" />\n`
+    )
+    sections.push('```\n\n')
+  } else if (syntaxChoice === 'object') {
+    sections.push('**Object form:**\n\n')
+    sections.push('```tsx\n')
+    sections.push(
+      `<View ${bgProp}={{ default: 'background', hover: 'background-hover', dark: 'blue-500' }} ${pProp}={{ default: '4', sm: '6', 'max-sm': '2' }} />\n`
+    )
+    sections.push('```\n\n')
+  } else {
+    sections.push('Both forms are allowed:\n\n')
+    sections.push('```tsx\n')
+    sections.push('// string form\n')
+    sections.push(
+      `<View ${bgProp}="background hover:background-hover dark:blue-500" ${pProp}="4 sm:6 max-sm:2" />\n\n`
+    )
+    sections.push('// object form\n')
+    sections.push(
+      `<View ${bgProp}={{ default: 'background', hover: 'background-hover', dark: 'blue-500' }} ${pProp}={{ default: '4', sm: '6', 'max-sm': '2' }} />\n`
+    )
+    sections.push('```\n\n')
   }
 
-  componentsSection.push('\n')
-
-  // Shorthands
+  // shorthands
   sections.push('## Shorthand Properties\n\n')
   sections.push('These shorthand properties are available for styling:\n\n')
-
   const shorthandEntries = Object.entries(shorthands).sort(([a], [b]) =>
     a.localeCompare(b)
   )
-
   sections.push(
     shorthandEntries.map(([short, full]) => `- \`${short}\` → \`${full}\``).join('\n')
   )
   sections.push('\n\n')
 
-  // Themes
-  sections.push('## Themes\n\n')
-
-  const themes = config.tamaguiConfig?.themes || {}
-  const themeNames = Object.keys(themes).sort()
-
-  // Parse and hierarchically organize themes
-  interface ThemeHierarchy {
-    level1: Set<string> // light/dark
-    level2: Set<string> // color names (blue, red, etc)
-    level3: Set<string> // variants (alt1, alt2, etc)
-    components: Set<string> // Component names
-  }
-
-  const hierarchy: ThemeHierarchy = {
-    level1: new Set(),
-    level2: new Set(),
-    level3: new Set(),
-    components: new Set(),
-  }
-
-  for (const themeName of themeNames) {
-    const parts = themeName.split('_')
-
-    // Level 1: light/dark
-    if (parts[0] === 'light' || parts[0] === 'dark') {
-      hierarchy.level1.add(parts[0])
-
-      // Level 2: color names (blue, red, green, etc.)
-      if (
-        parts.length > 1 &&
-        parts[1] &&
-        !parts[1].startsWith('alt') &&
-        parts[1] !== 'active'
-      ) {
-        // Check if it's not a component by looking if it starts with uppercase
-        if (parts[1][0] === parts[1][0].toLowerCase()) {
-          hierarchy.level2.add(parts[1])
-        }
-      }
-
-      // Level 3: variants (alt1, alt2, etc.)
-      for (const part of parts) {
-        if (part.startsWith('alt') || part === 'active') {
-          hierarchy.level3.add(part)
-        }
-      }
-
-      // Components: parts that start with uppercase
-      for (const part of parts) {
-        if (
-          part[0] &&
-          part[0] === part[0].toUpperCase() &&
-          part[0] !== part[0].toLowerCase()
-        ) {
-          hierarchy.components.add(part)
-        }
-      }
-    } else {
-      // Base theme without light/dark prefix
-      if (parts.length === 1) {
-        hierarchy.level1.add(themeName)
-      }
+  // named control sizes table
+  const sizes = config.tamaguiConfig?.sizes
+  if (sizes && typeof sizes === 'object') {
+    sections.push('## Named Control Sizes\n\n')
+    sections.push(
+      `Control components (Button, Input, etc.) use the configured names below. Default is \`${sizes.default ?? 'md'}\`.\n\n`
+    )
+    sections.push('| Size | Configuration |\n')
+    sections.push('|---|---|\n')
+    for (const [sizeKey, val] of Object.entries(sizes)) {
+      if (sizeKey === 'default') continue
+      const valStr =
+        typeof val === 'object' && val !== null ? JSON.stringify(val) : String(val)
+      const isDefault = sizes.default === sizeKey ? ' (default)' : ''
+      sections.push(`| \`${sizeKey}\`${isDefault} | ${valStr} |\n`)
     }
+    sections.push('\n')
   }
 
-  sections.push('Themes are organized hierarchically and can be combined:\n\n')
+  // themes
+  sections.push('## Themes\n\n')
+  const themes = config.tamaguiConfig?.themes || {}
+  const themeNames = Object.keys(themes).sort()
 
-  if (hierarchy.level1.size > 0) {
-    sections.push('**Level 1 (Base):**\n\n')
+  sections.push(themeNames.map((name) => `- \`${name}\``).join('\n'))
+  sections.push(
+    '\n\nTheme names above are exact configured names. Nested themes resolve relative to their parent. Use an explicit theme boundary in a component skin.\n\n'
+  )
+  if (themeNames.length) {
+    sections.push('### Theme Usage\n\n')
     sections.push(
-      Array.from(hierarchy.level1)
-        .sort()
-        .map((name) => `- ${name}`)
-        .join('\n')
+      `\`\`\`tsx\n<Theme name=${JSON.stringify(themeNames[0])}>\n  <Button>Uses this theme</Button>\n</Theme>\n\`\`\`\n\n`
     )
-    sections.push('\n\n')
   }
 
-  if (hierarchy.level2.size > 0) {
-    sections.push('**Level 2 (Color Schemes):**\n\n')
+  sections.push('**Accessing theme values:**\n\n')
+  sections.push('Components access theme values by their bare names:\n\n')
+  const colorProp = getPropName('color')
+  if (syntaxChoice === 'string') {
+    sections.push('```tsx\n')
     sections.push(
-      Array.from(hierarchy.level2)
-        .sort()
-        .map((name) => `- ${name}`)
-        .join('\n')
+      `<View ${bgProp}="background hover:background-hover" ${colorProp}="color" />\n`
     )
-    sections.push('\n\n')
-  }
-
-  if (hierarchy.level3.size > 0) {
-    sections.push('**Level 3 (Variants):**\n\n')
+    sections.push('```\n\n')
+  } else if (syntaxChoice === 'object') {
+    sections.push('```tsx\n')
     sections.push(
-      Array.from(hierarchy.level3)
-        .sort()
-        .map((name) => `- ${name}`)
-        .join('\n')
+      `<View ${bgProp}={{ default: 'background', hover: 'background-hover' }} ${colorProp}={{ default: 'color' }} />\n`
     )
-    sections.push('\n\n')
-  }
-
-  if (hierarchy.components.size > 0) {
-    sections.push('**Component Themes:**\n\n')
+    sections.push('```\n\n')
+  } else {
+    sections.push('```tsx\n')
+    sections.push('// string form\n')
     sections.push(
-      Array.from(hierarchy.components)
-        .sort()
-        .map((name) => `- ${name}`)
-        .join('\n')
+      `<View ${bgProp}="background hover:background-hover" ${colorProp}="color" />\n\n`
     )
-    sections.push('\n\n')
+    sections.push('// object form\n')
+    sections.push(
+      `<View ${bgProp}={{ default: 'background', hover: 'background-hover' }} ${colorProp}={{ default: 'color' }} />\n`
+    )
+    sections.push('```\n\n')
   }
 
-  // Add usage documentation
-  sections.push('### Theme Usage\n\n')
-  sections.push(
-    'Themes are combined hierarchically. For example, `light_blue_alt1_Button` combines:\n'
-  )
-  sections.push('- Base: `light`\n')
-  sections.push('- Color: `blue`\n')
-  sections.push('- Variant: `alt1`\n')
-  sections.push('- Component: `Button`\n\n')
-
-  sections.push('**Basic usage:**\n\n')
-  sections.push('```tsx\n')
-  sections.push('// Apply a theme to components\n')
-  sections.push('export default () => (\n')
-  sections.push('  <Theme name="dark">\n')
-  sections.push("    <Button>I'm a dark button</Button>\n")
-  sections.push('  </Theme>\n')
-  sections.push(')\n\n')
-  sections.push('// Themes nest and combine automatically\n')
-  sections.push('export default () => (\n')
-  sections.push('  <Theme name="dark">\n')
-  sections.push('    <Theme name="blue">\n')
-  sections.push('      <Button>Uses dark_blue theme</Button>\n')
-  sections.push('    </Theme>\n')
-  sections.push('  </Theme>\n')
-  sections.push(')\n')
-  sections.push('```\n\n')
-
-  sections.push('**Accessing theme values:**\n\n')
-  sections.push('Components can access theme values using `$` token syntax:\n\n')
-  sections.push('```tsx\n')
-  sections.push(
-    `<View ${getPropName('backgroundColor')}="$background" ${getPropName('color')}="$color" />\n`
-  )
-  sections.push('```\n\n')
-
   sections.push('**Special props:**\n\n')
-  sections.push('- `inverse`: Automatically swaps light ↔ dark themes\n')
-  sections.push('- `reset`: Reverts to grandparent theme\n\n')
+  sections.push('- `theme="inverse"`: Uses the opposite light or dark sub-theme\n')
 
-  // Tokens
+  // tokens
   sections.push('## Tokens\n\n')
-  sections.push(
-    'Tokens are design system values that can be referenced using the `$` prefix.\n\n'
-  )
+  sections.push('Tokens are design system values referenced by their bare names.\n\n')
 
   const tokens = config.tamaguiConfig?.tokens || {}
 
-  // Space tokens
-  if (tokens.space) {
+  // space tokens (only if present and non-empty)
+  if (tokens.space && Object.keys(tokens.space).length > 0) {
     sections.push('### Space Tokens\n\n')
     const spaceTokens = Object.entries(tokens.space).sort(([a], [b]) => {
-      // Sort numerically where possible
       const numA = parseFloat(a)
       const numB = parseFloat(b)
       if (!isNaN(numA) && !isNaN(numB)) {
@@ -386,8 +292,8 @@ function generateMarkdown(config: any): string {
     sections.push('\n\n')
   }
 
-  // Size tokens
-  if (tokens.size) {
+  // size tokens (only if present and non-empty)
+  if (tokens.size && Object.keys(tokens.size).length > 0) {
     sections.push('### Size Tokens\n\n')
     const sizeTokens = Object.entries(tokens.size).sort(([a], [b]) => {
       const numA = parseFloat(a)
@@ -405,8 +311,8 @@ function generateMarkdown(config: any): string {
     sections.push('\n\n')
   }
 
-  // Radius tokens
-  if (tokens.radius) {
+  // radius tokens (only if present and non-empty)
+  if (tokens.radius && Object.keys(tokens.radius).length > 0) {
     sections.push('### Radius Tokens\n\n')
     const radiusTokens = Object.entries(tokens.radius).sort(([a], [b]) => {
       const numA = parseFloat(a)
@@ -424,8 +330,8 @@ function generateMarkdown(config: any): string {
     sections.push('\n\n')
   }
 
-  // zIndex tokens
-  if (tokens.zIndex) {
+  // zIndex tokens (only if present and non-empty)
+  if (tokens.zIndex && Object.keys(tokens.zIndex).length > 0) {
     sections.push('### Z-Index Tokens\n\n')
     const zIndexTokens = Object.entries(tokens.zIndex).sort(([a], [b]) => {
       const numA = parseFloat(a)
@@ -443,41 +349,124 @@ function generateMarkdown(config: any): string {
     sections.push('\n\n')
   }
 
-  // Color tokens
-  if (tokens.color) {
+  // color tokens (only if present and non-empty; summarized if large palette set)
+  let sampleColorBg = 'blue-500'
+  let sampleColorText = 'color'
+  if (tokens.color && Object.keys(tokens.color).length > 0) {
     sections.push('### Color Tokens\n\n')
-    const colorTokens = Object.entries(tokens.color).sort(([a], [b]) =>
-      a.localeCompare(b)
+    const colorKeys = Object.keys(tokens.color).sort()
+
+    // detect tailwind style palette keys: <palette>-<step>
+    const paletteMap = new Map<string, Set<string>>()
+    const standaloneColors: Array<[string, any]> = []
+
+    for (const key of colorKeys) {
+      const match = key.match(/^([a-z]+)-(\d+)$/)
+      if (match) {
+        const [, palette, step] = match
+        if (!paletteMap.has(palette)) {
+          paletteMap.set(palette, new Set())
+        }
+        paletteMap.get(palette)!.add(step)
+      } else {
+        standaloneColors.push([key, tokens.color[key]])
+      }
+    }
+
+    if (paletteMap.size >= 4) {
+      // summarize palettes compactly instead of 300+ line dump
+      const palettes = Array.from(paletteMap.keys()).sort().join(', ')
+      sections.push(`**Tailwind Palettes (\`<name>-<50..950>\`):** ${palettes}\n\n`)
+      if (standaloneColors.length > 0) {
+        sections.push('**Named Colors:**\n\n')
+        sections.push(
+          standaloneColors
+            .map(([k, v]) => `- \`${k}\`: ${formatTokenValue(v)}`)
+            .join('\n')
+        )
+        sections.push('\n\n')
+      }
+      sampleColorBg = colorKeys.find((k) => k.startsWith('blue-')) || colorKeys[0]
+      sampleColorText =
+        colorKeys.find((k) => k.startsWith('gray-') || k.startsWith('zinc-')) ||
+        colorKeys[1] ||
+        'color'
+    } else {
+      sections.push(
+        colorKeys
+          .map((key) => `- \`${key}\`: ${formatTokenValue(tokens.color[key])}`)
+          .join('\n')
+      )
+      sections.push('\n\n')
+      sampleColorBg = colorKeys[0] || 'background'
+      sampleColorText = colorKeys[1] || 'color'
+    }
+  } else {
+    sampleColorBg = 'background'
+    sampleColorText = 'color'
+  }
+
+  // token usage examples
+  sections.push('### Token Usage\n\n')
+  sections.push('Tokens can be used in component props by their bare names:\n\n')
+
+  const paddingProp = getPropName('padding')
+  const gapProp = getPropName('gap')
+  const marginProp = getPropName('margin')
+  const widthProp = getPropName('width')
+  const heightProp = getPropName('height')
+  const radiusProp = getPropName('borderRadius')
+  const sampleRadius = tokens.radius?.md
+    ? 'md'
+    : Object.keys(tokens.radius || {})[0] || '0px'
+
+  if (syntaxChoice === 'string') {
+    sections.push('```tsx\n')
+    sections.push(
+      `// Space tokens - for margin, padding, gap\n<View ${paddingProp}="4 sm:6" ${gapProp}="2" ${marginProp}="3" />\n\n`
     )
     sections.push(
-      colorTokens
-        .map(([key, value]) => `- \`${key}\`: ${formatTokenValue(value)}`)
-        .join('\n')
+      `// Size tokens - for width, height, dimensions\n<View ${widthProp}="10 sm:12" ${heightProp}="6" />\n\n`
     )
-    sections.push('\n\n')
+    sections.push(
+      `// Color tokens - for colors and backgrounds\n<View ${bgProp}="${sampleColorBg} hover:${sampleColorBg}" ${colorProp}="${sampleColorText}" />\n\n`
+    )
+    sections.push(
+      `// Radius tokens - for border-radius\n<View ${radiusProp}="${sampleRadius}" />\n`
+    )
+    sections.push('```\n\n')
+  } else if (syntaxChoice === 'object') {
+    sections.push('```tsx\n')
+    sections.push(
+      `// Space tokens - for margin, padding, gap\n<View ${paddingProp}={{ default: '4', sm: '6' }} ${gapProp}="2" ${marginProp}="3" />\n\n`
+    )
+    sections.push(
+      `// Size tokens - for width, height, dimensions\n<View ${widthProp}={{ default: '10', sm: '12' }} ${heightProp}="6" />\n\n`
+    )
+    sections.push(
+      `// Color tokens - for colors and backgrounds\n<View ${bgProp}={{ default: '${sampleColorBg}', hover: '${sampleColorBg}' }} ${colorProp}={{ default: '${sampleColorText}' }} />\n\n`
+    )
+    sections.push(
+      `// Radius tokens - for border-radius\n<View ${radiusProp}="${sampleRadius}" />\n`
+    )
+    sections.push('```\n\n')
+  } else {
+    sections.push('```tsx\n')
+    sections.push('// String form\n')
+    sections.push(
+      `<View ${paddingProp}="4 sm:6" ${widthProp}="10 sm:12" ${bgProp}="${sampleColorBg}" />\n\n`
+    )
+    sections.push('// Object form\n')
+    sections.push(
+      `<View ${paddingProp}={{ default: '4', sm: '6' }} ${widthProp}={{ default: '10', sm: '12' }} ${bgProp}={{ default: '${sampleColorBg}' }} />\n\n`
+    )
+    sections.push(
+      `// Space and radius tokens\n<View ${gapProp}="2" ${marginProp}="3" ${heightProp}="6" ${radiusProp}="${sampleRadius}" />\n`
+    )
+    sections.push('```\n\n')
   }
 
-  // Token usage examples
-  sections.push('### Token Usage\n\n')
-  sections.push('Tokens can be used in component props with the `$` prefix:\n\n')
-  sections.push('```tsx\n')
-  sections.push('// Space tokens - for margin, padding, gap\n')
-  sections.push(
-    `<View ${getPropName('padding')}="$4" ${getPropName('gap')}="$2" ${getPropName('margin')}="$3" />\n\n`
-  )
-  sections.push('// Size tokens - for width, height, dimensions\n')
-  sections.push(
-    `<View ${getPropName('width')}="$10" ${getPropName('height')}="$6" />\n\n`
-  )
-  sections.push('// Color tokens - for colors and backgrounds\n')
-  sections.push(
-    `<View ${getPropName('backgroundColor')}="$blue5" ${getPropName('color')}="$gray12" />\n\n`
-  )
-  sections.push('// Radius tokens - for border-radius\n')
-  sections.push(`<View ${getPropName('borderRadius')}="$4" />\n`)
-  sections.push('```\n\n')
-
-  // Media queries
+  // media queries
   if (config.tamaguiConfig?.media) {
     sections.push('## Media Queries\n\n')
     sections.push('Available responsive breakpoints:\n\n')
@@ -486,7 +475,7 @@ function generateMarkdown(config: any): string {
     const mediaEntries = Object.entries(media).sort(([a], [b]) => a.localeCompare(b))
 
     for (const [name, query] of mediaEntries) {
-      sections.push(`- **${name}**: ${JSON.stringify(query)}\n`)
+      sections.push(`- **${name}**: ${formatMediaQuery(query)}\n`)
     }
     sections.push('\n')
 
@@ -494,43 +483,59 @@ function generateMarkdown(config: any): string {
     sections.push(
       'Media queries can be used as style props or with the `useMedia` hook:\n\n'
     )
-    sections.push('```tsx\n')
-    sections.push('// As style props (prefix with $)\n')
 
-    // Get first media query name as example
-    const firstMediaName = mediaEntries[0]?.[0]
-    if (firstMediaName) {
-      sections.push(
-        `<View ${getPropName('width')}="100%" $${firstMediaName}={{ ${getPropName('width')}: "50%" }} />\n\n`
-      )
-    }
+    // pick a representative media query (prefer sm or md over height-*)
+    const representative =
+      mediaEntries.find(([n]) => n === 'sm' || n === 'md')?.[0] ||
+      mediaEntries.find(([n]) => !n.includes('-'))?.[0] ||
+      mediaEntries[0]?.[0]
+
+    if (representative) {
+      const isIdentifier = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(representative)
+      const mediaAccess = isIdentifier
+        ? `media.${representative}`
+        : `media['${representative}']`
+
+      sections.push('```tsx\n')
+      if (syntaxChoice === 'string') {
+        sections.push('// As a clause in the same style value\n')
+        sections.push(`<View ${widthProp}="100% ${representative}:50%" />\n\n`)
+      } else if (syntaxChoice === 'object') {
+        sections.push('// Using the object form\n')
+        sections.push(
+          `<View ${widthProp}={{ default: '100%', '${representative}': '50%' }} />\n\n`
+        )
+      } else {
+        sections.push('// String form and object form\n')
+        sections.push(`<View ${widthProp}="100% ${representative}:50%" />\n`)
+        sections.push(
+          `<View ${widthProp}={{ default: '100%', '${representative}': '50%' }} />\n\n`
+        )
+      }
 
-    sections.push('// Using the useMedia hook\n')
-    sections.push('const media = useMedia()\n')
-    if (firstMediaName) {
-      sections.push(`if (media.${firstMediaName}) {\n`)
+      sections.push('// Using the useMedia hook\n')
+      sections.push('const media = useMedia()\n')
+      sections.push(`if (${mediaAccess}) {\n`)
       sections.push('  // Render for this breakpoint\n')
       sections.push('}\n')
+      sections.push('```\n\n')
     }
-    sections.push('```\n\n')
   }
 
-  // Fonts
+  // fonts
   if (config.tamaguiConfig?.fonts) {
     sections.push('## Fonts\n\n')
     sections.push('Available font families:\n\n')
-
     const fonts = config.tamaguiConfig.fonts
     const fontNames = Object.keys(fonts).sort()
     sections.push(fontNames.map((name) => `- ${name}`).join('\n'))
     sections.push('\n\n')
   }
 
-  // Animations
+  // animations
   if (config.tamaguiConfig?.animations) {
     sections.push('## Animations\n\n')
     sections.push('Available animation presets:\n\n')
-
     const animations = config.tamaguiConfig.animations
     if (animations.animations) {
       const animationNames = Object.keys(animations.animations).sort()
@@ -539,17 +544,111 @@ function generateMarkdown(config: any): string {
     }
   }
 
-  // Add components section at the end
-  sections.push(...componentsSection)
+  // components section: emit barrel's public import surface
+  const componentsSection: string[] = []
+  const componentSet = new Set<string>()
+
+  // try loading public exports from tamagui or candidate modules
+  let barrelExported = false
+  const candidateModules = [
+    'tamagui',
+    ...(config.components || []).map((c: any) => c.moduleName),
+  ]
+  for (const modName of candidateModules) {
+    if (!modName) continue
+    try {
+      const mod = require(modName)
+      for (const [key, val] of Object.entries(mod)) {
+        if (
+          /^[A-Z]/.test(key) &&
+          (typeof val === 'function' || (typeof val === 'object' && val !== null))
+        ) {
+          if (
+            !key.endsWith('Context') &&
+            !key.endsWith('Provider') &&
+            key !== 'Fragment'
+          ) {
+            componentSet.add(key)
+            barrelExported = true
+          }
+        }
+      }
+      if (barrelExported) break
+    } catch {
+      // fallback to config.components below
+    }
+  }
+
+  if (!barrelExported && config.components) {
+    for (const componentModule of config.components) {
+      for (const name of Object.keys(componentModule.nameToInfo || {})) {
+        componentSet.add(name)
+      }
+    }
+  }
+
+  // filter internal frames ending with Frame when parent or part exists
+  const allComponents = Array.from(componentSet).filter((name) => {
+    if (name.endsWith('Frame')) {
+      const base = name.replace(/Frame$/, '')
+      if (
+        componentSet.has(base) ||
+        name.startsWith('Popper') ||
+        name.startsWith('DialogPortal') ||
+        name.startsWith('SelectScrollButton')
+      ) {
+        return false
+      }
+    }
+    return true
+  })
+
+  componentsSection.push('## Components\n\n')
+  componentsSection.push('Available named exports (import these names directly):\n\n')
+  for (const name of allComponents.sort()) {
+    componentsSection.push(`- ${name}\n`)
+  }
+  componentsSection.push('\n')
 
+  sections.push(...componentsSection)
   return sections.join('')
 }
 
 function formatTokenValue(value: any): string {
-  // If it's an object with a 'val' property (token object), extract the value
   if (typeof value === 'object' && value !== null && 'val' in value) {
     return String(value.val)
   }
-  // Otherwise, stringify it
   return String(value)
 }
+
+function formatMediaQuery(query: any): string {
+  if (typeof query !== 'object' || query === null) {
+    return String(query)
+  }
+  const parts: string[] = []
+  if (query.minWidth !== undefined) {
+    parts.push(`min-width: ${query.minWidth}px (screens >= ${query.minWidth}px wide)`)
+  }
+  if (query.maxWidth !== undefined) {
+    parts.push(`max-width: ${query.maxWidth}px (screens <= ${query.maxWidth}px wide)`)
+  }
+  if (query.minHeight !== undefined) {
+    parts.push(`min-height: ${query.minHeight}px (screens >= ${query.minHeight}px tall)`)
+  }
+  if (query.maxHeight !== undefined) {
+    parts.push(`max-height: ${query.maxHeight}px (screens <= ${query.maxHeight}px tall)`)
+  }
+  if (query.hover !== undefined) {
+    parts.push(`pointer: hover (${query.hover})`)
+  }
+  if (query.pointer !== undefined) {
+    parts.push(`pointer: ${query.pointer}`)
+  }
+  if (query.prefersReducedMotion !== undefined) {
+    parts.push(`prefers-reduced-motion: ${query.prefersReducedMotion}`)
+  }
+  if (parts.length === 0) {
+    return JSON.stringify(query)
+  }
+  return parts.join(', ')
+}