Typesafe useCSSVariable: accept only real vars and return correct value types

[salemkode]

Hey team 👋

Uniwind markets “resolve CSS variables directly in JavaScript,” which is awesome for DX. I’d love to propose a small typing upgrade that makes this experience fully typesafe:

What I’m proposing

• Constrain inputs: useCSSVariable should only accept actual CSS variable names present in our tokens (e.g. '--color-primary'). Passing a non‑existent var should be a type error.
• Typed outputs: Return the correct value type based on the variable (Color, Length, Percent, Duration, number, etc.), so downstream components get precise types instead of string | number.

Why this helps

• Catch typos at compile time ('--colo-primary' → error).
• Stronger autocomplete for all variables.
• Safer composition in styles (e.g. lengths vs colors).
• Encourages a single source of truth for design tokens across web and native.

Proposed API surface

export interface CSSVariableMap {
  '--color-primary': Color;
  '--color-secondary': Color;
  '--text-opacity': Percent;
  '--spacing-2': Length;
  '--radius-lg': Length;
  '--elevation': number;
  '--transition-fast': Duration;
  // ...auto-generated from tokens
}

export function useCSSVariable<K extends keyof CSSVariableMap>(
  name: K
): CSSVariableMap[K];

// Optional runtime escape hatch
export function useCSSVariable(
  name: string,
  fallback?: unknown
): unknown;

Usage

const primary = useCSSVariable('--color-primary'); // Color
const spacing = useCSSVariable('--spacing-2');     // Length
// const bad = useCSSVariable('--not-a-real-var'); // TS error

Keeping it maintainable (codegen)

• Add a small script that parses our :root { --var: value; } tokens (or tailwind config) and emits CSSVariableMap.
• Simple heuristics infer types from values (hex/rgb → Color, px/rem/em → Length, % → Percent, ms/s → Duration, plain number → number). This can be refined over time.
• Run in CI/prebuild so types stay in sync with tokens.

Example codegen outline

// scripts/generate-css-var-types.ts
// 1) read tokens.css
// 2) extract --vars
// 3) infer types
// 4) emit types/uniwind-css-vars.d.ts with CSSVariableMap and shared aliases

Implementation notes

• Length includes both unit strings and number to fit RN/Uniwind style expectations. We can narrow further per property if/when the hook is used in typed style helpers.
• For teams with a design token pipeline, the generator can consume JSON tokens instead of raw CSS.

If this approach aligns with Uniwind’s goals, I’m happy to contribute a PR with:

1. the generator script,
2. the CSSVariableMap typing,
3. useCSSVariable signature updates (with tests).

Thanks for considering!

[Brentlok]

Hi, thanks for kind words. We've actually considered this but we're still not sure if we want to make this change. On the web every CSS variable is just a string, we're not parsing it inside useCSSVariable. Limited input type gives a better intellisense and typesafety, but it can be limiting factor for creating your own hooks / components. For now I believe that runtime warning on dev mode is enough for now.

[salemkode]

No one should say no for more typesafe 😅, it's all about that. More strict and show errors before happening. Also we can only have same type but with check if variable is available or not.

[salemkode]

Also I hate how I get colors

[Brentlok]

While we see the value in stricter typing, we've decided to keep this flexible for now. Since the updateCSSVariables API allows developers to add new variables at runtime (with arbitrary values), strict typing on this hook would actually limit that dynamic functionality.

As uniwind grows, we are still learning the most popular usage patterns. We want to prioritize flexibility to accommodate different workflows, even if it means trading off a bit of type safety in the short term.

We are definitely open to revisiting this in the future as usage patterns stabilize, but for the time being, we will keep the types as they are.

[wcastand]

other issue with the way it is right now
we use uniwind pro for web and native.

i calculate the paddingTop and i need to do custom because p-safe doesn't take into account the expo-router header height.

const headerHeight = useHeaderHeight()
	const offsetTop = useCSSVariable("--spacing-4") as number
	const paddingTop = headerHeight + offsetTop
	const [refreshing, setRefreshing] = useState(false)
	console.log(headerHeight, offsetTop)

issue is, that fucks on web because it return a string on web but a number on native. i feel like it's a really bad thing for the api to not be consistent over platform in the output type.

i don't even see a way currently to get the variable as a number on web to do this outside of doing a parsing myself :/