Fix IntelliSense override in Space type by refining Pixel

[Gavriel-M]

🛠️ Fix: Improve Type IntelliSense by Refining Pixel Definition

Issue:

The current Pixel type is defined as string | number, which causes IntelliSense to prioritize raw values over theme tokens (e.g., 'sm', 'md', etc.) when used in union types like Space = ThemeSpace | Pixel.

Solution:

Redefine Pixel as (string & {}) | (number & {}), which maintains compatibility with raw values at runtime but defers IntelliSense suggestions in favor of theme tokens.

// Before
export type Pixel = string | number;

// After
export type Pixel = (string & {}) | (number & {});

This enables cleaner developer experience with proper token autocompletion while retaining full runtime flexibility.

[Gavriel-M]

@quantizor Do you think that's something we can merge?
I'm working with custom space tokens (ie. 'space0', 'space2', 'space4' and so on) and I cannot get intellisense for them.

[agriffis]

I don't have sufficient knowledge of TypeScript for this, and I'm not currently in the business of merging xstyled PR's anyway, but I have one request: This sort of non-obvious code should always include internal documentation to explain it and preferably point to reference documentation.

[Gavriel-M]

@agriffis Thanks for the note!
This behavior is due to a well-known TypeScript issue where string | number overrides IntelliSense for more specific union types like theme tokens.

I’ll add a comment above the type definition explaining the reasoning and linking to that issue.

Curious — do you have a preferred way of documenting this kind of subtle or non-obvious type behavior? Always happy to align with your expectations.

[agriffis]

Internal documentation seems to be a lost art in the modern era...

Something like this:

// This syntax enables Intellisense to prioritize theme tokens over raw values.
// See https://github.com/microsoft/TypeScript/issues/29729

[Gavriel-M]

Haha, it really is. I keep hearing “your code should document itself!” — but sometimes it needs a little help.

Just pushed a clear inline comment to document the intention. Thanks again for the suggestion!

[Gavriel-M]

@agriffis For better reference, here’s the IntelliSense improvement in action:

It's a super minimal change, but it makes a big impact on developer experience.
Merging this would help a lot — right now I’m having to override the type just to restore proper suggestions.

[agriffis]

LGTM

[agriffis]

@quantizor I contributed a review and some comments here, but I won't step on your toes by merging it directly. Assume you'll do that when you're ready.

[galangel]

+1

[galangel]

👋🏻 @gregberge WDYT?

[gregberge]

👋🏻 @gregberge WDYT?

Hey, I am no longer maintaining xstyled. If you use it you should migrate to Tailwind CSS 😌