Generate JSDoc TypeScript definitions from Token description field

[shaunrfox]

Description

I'd like to be able to enable TypeScript IntelliSense to show token documentation on hover. The existing description property on tokens seems like it could be used to generate JSDoc comments in the generated .d.ts files.

Problem Statement/Justification

Design systems often have dozens or hundreds of tokens (sizes, spacing, colors, etc.) where the key name alone doesn't convey the actual value.

For example:

• "2xs" → What size is this? (16rem / 256px)
• "xl" → Which xl? (36rem / 576px)
• "prose" → What does this mean? (65ch)

Currently, the description field is documented as "useful for autogenerated documentation" but provides no benefit during active development.

Developers must:

1. Leave their editor to check documentation
2. Memorize token values
3. Guess and verify via browser devtools

This friction slows development and increases errors, especially for teams onboarding new developers or working with large token sets.

TypeScript IntelliSense is where developers spend most of their time — surfacing descriptions there would provide immediate, contextual help exactly when needed.

Proposed Solution or API

Token definition (no change needed):

export default defineConfig({
  theme: {
    tokens: {
      sizes: {
        '2xs': {
          value: '16rem',
          description: '16rem (256px)'
        },
        xs: {
          value: '20rem',
          description: '20rem (320px)'
        },
        prose: {
          value: '65ch',
          description: 'Optimal reading width (~65 characters)'
        },
      }
    }
  }
})

Current generated tokens.d.ts:

export type SizeToken = "2xs" | "xs" | "prose"

Proposed generated tokens.d.ts:

export type SizeToken =
  | /** 16rem (256px) */ "2xs"
  | /** 20rem (320px) */ "xs"
  | /** Optimal reading width (~65 characters) */ "prose"

This would enable hover hints in any IDE with TypeScript support.

Backwards compatible: Tokens without description would generate as they do today.

Alternatives

1. JSDoc comments above token definitions - These don't propagate through Panda's codegen to the generated types
2. Post-processing the generated .d.ts files - Requires custom scripting, must re-run after every codegen, and is fragile if Panda's output format changes
3. Maintaining a separate reference file - Duplicates information, becomes stale, and isn't integrated with Panda's type system
4. Using the deprecated field for hints - This works for IntelliSense (strikethrough + message) but semantically incorrect and visually confusing

Additional Information

• TypeScript supports JSDoc on string literal union members: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
• Similar pattern used by other design systems (e.g., Chakra UI's token documentation)
• This would make the existing description field more valuable without any breaking changes

[storchk]

I'd love to see this feature in Panda ❤️