@ntatoud/styra 0.1.0 → 0.2.0

package/README.md

@@ -36,6 +36,14 @@ const btn = styra("btn")
   .compound([{ disabled: { not: "yes" }, class: "hover:opacity-80" }]);
 ```
 
+## AI Agent Support
+
+If you use an AI agent (Claude Code, Cursor, Copilot, etc.), run the following to install styra's intent skills:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
 ## Development
 
 - Install dependencies:

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 //#region src/types.d.ts
 type MergeFn = (...classes: string[]) => string;
+/** A clsx-compatible class value: string, number, boolean, null, undefined, array, or object map. */
+type ClassValue = string | number | boolean | null | undefined | ClassValue[] | Record<string, unknown>;
 /**
  * A map of variant keys to their possible values and classes.
  * Values can be a `Record<string, string>` (explicit map) or a plain `string`
@@ -26,14 +28,14 @@ type CompoundRule<V extends VariantMap> = CompoundCondition<V> & {
  * - Variants without a default → required
  */
 type InferProps<V extends VariantMap, D extends DefaultsOf<V>> = { [K in keyof V as K extends keyof D ? never : K]: PropTypeOf<V[K]> } & { [K in keyof V as K extends keyof D ? K : never]?: PropTypeOf<V[K]> } & {
-  class?: string;
-  className?: string | ((...args: never[]) => string | undefined);
+  class?: ClassValue;
+  className?: ClassValue | ((...args: never[]) => ClassValue);
 };
 /** A callable builder that also exposes `.variants()`, `.defaults()`, `.compound()`. */
 interface StyraBuilder<V extends VariantMap, D extends DefaultsOf<V>> {
   (props: keyof V extends never ? {
-    class?: string;
-    className?: string | ((...args: never[]) => string | undefined);
+    class?: ClassValue;
+    className?: ClassValue | ((...args: never[]) => ClassValue);
   } : InferProps<V, D>): string;
   /**
    * Define variant keys and their class mappings.
@@ -70,13 +72,14 @@ type VariantProps<T extends (...args: never[]) => string> = Omit<Parameters<T>[0
  * import { createStyra } from 'styra'
  * import { twMerge } from 'tailwind-merge'
  *
- * export const { styra } = createStyra({ merge: twMerge })
+ * export const { styra, cn } = createStyra({ merge: twMerge })
  * ```
  */
 declare function createStyra(options?: StyraOptions): {
   styra: (base: string) => StyraBuilder<Record<never, never>, Record<never, never>>;
+  cn: (...args: ClassValue[]) => string;
 };
 /** Default `styra` instance with no custom merge function. */
-declare const styra: (base: string) => StyraBuilder<Record<never, never>, Record<never, never>>;
+declare const styra: (base: string) => StyraBuilder<Record<never, never>, Record<never, never>>, cn: (...args: ClassValue[]) => string;
 //#endregion
-export { type CompoundRule, type InferProps, type StyraBuilder, type StyraOptions, type VariantMap, type VariantProps, createStyra, styra };
+export { type ClassValue, type CompoundRule, type InferProps, type StyraBuilder, type StyraOptions, type VariantMap, type VariantProps, cn, createStyra, styra };

package/dist/index.mjs

@@ -10,10 +10,30 @@ function matchesCompound(rule, resolved) {
 	}
 	return true;
 }
-/** Resolve a className prop that may be a string or a render-prop function. */
+/** Recursively resolve a clsx-like value to a string. */
+function toVal(mix) {
+	let str = "";
+	if (typeof mix === "string" || typeof mix === "number") str += mix;
+	else if (Array.isArray(mix)) {
+		for (let k = 0; k < mix.length; k++) if (mix[k]) {
+			const y = toVal(mix[k]);
+			if (y) {
+				str && (str += " ");
+				str += y;
+			}
+		}
+	} else if (mix !== null && typeof mix === "object") {
+		for (const y in mix) if (mix[y]) {
+			str && (str += " ");
+			str += y;
+		}
+	}
+	return str;
+}
+/** Resolve a className prop that may be a clsx-like value or a render-prop function. */
 function resolveClassName(v) {
-	if (typeof v === "string") return v || void 0;
-	if (typeof v === "function") return v() || void 0;
+	if (typeof v === "function") return toVal(v()) || void 0;
+	return toVal(v) || void 0;
 }
 /** Coerce a prop value to its string key for map lookup (handles booleans from boolean shorthand). */
 function toKey(v) {
@@ -117,7 +137,7 @@ function makeBuilder(base, variantMap, defaultMap, compoundRules, customMerge, v
 * import { createStyra } from 'styra'
 * import { twMerge } from 'tailwind-merge'
 *
-* export const { styra } = createStyra({ merge: twMerge })
+* export const { styra, cn } = createStyra({ merge: twMerge })
 * ```
 */
 function createStyra(options) {
@@ -125,9 +145,23 @@ function createStyra(options) {
 	function styra(base) {
 		return makeBuilder(base, {}, {}, [], customMerge, false);
 	}
-	return { styra };
+	function cn(...args) {
+		let str = "";
+		for (let i = 0; i < args.length; i++) {
+			const val = toVal(args[i]);
+			if (val) {
+				str && (str += " ");
+				str += val;
+			}
+		}
+		return customMerge ? customMerge(str) : str;
+	}
+	return {
+		styra,
+		cn
+	};
 }
 /** Default `styra` instance with no custom merge function. */
-const { styra } = createStyra();
+const { styra, cn } = createStyra();
 //#endregion
-export { createStyra, styra };
+export { cn, createStyra, styra };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ntatoud/styra",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Type-safe class variance builder — a maintained, boosted CVA replacement.",
   "keywords": [
     "class-variance-authority",
     "cva",
     "tailwind",
+    "tanstack-intent",
     "typescript",
     "variants"
   ],
@@ -19,7 +20,8 @@
     "url": "git+https://github.com/ntatoud/styra.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
   "exports": {
@@ -34,6 +36,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "catalog:",
+    "@tanstack/intent": "catalog:",
     "@types/node": "^25.5.0",
     "typescript": "^6.0.2",
     "vite-plus": "catalog:",

package/skills/styra-compound-variants/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: styra-compound-variants
+description: >
+  Compound variant rules for @ntatoud/styra v0.1.0 — .compound([rules]) syntax,
+  exact-match conditions (all keys must match for rule to fire), Not<T> negation
+  ({ variantKey: { not: value } } — fires when variant is NOT that value),
+  multiple independent rules (additive), boolean shorthand coercion ("true"/"false"
+  string keys in negation). Exports: CompoundRule, Not.
+  Preempts: { not: true } instead of { not: "true" } for boolean props,
+  missing class key in rule, compoundVariants CVA migration pitfall.
+type: core
+library: "@ntatoud/styra"
+library_version: "0.1.0"
+requires:
+  - styra-define-variants
+sources:
+  - "ntatoud/styra:packages/styra/src/index.ts"
+  - "ntatoud/styra:packages/styra/src/types.ts"
+---
+
+# Compound Variants
+
+This skill builds on styra-define-variants. Read it first for foundational concepts.
+
+## 1. Setup
+
+Minimum viable example — exact-match rule and negation rule:
+
+```ts
+import { styra, type CompoundRule, type Not } from "@ntatoud/styra";
+
+// Exact-match: ring-red only when size=sm AND color=red
+const button = styra("btn")
+  .variants({
+    size: { sm: "text-sm", md: "text-base", lg: "text-lg" },
+    color: { red: "bg-red-500", blue: "bg-blue-500" },
+  })
+  .compound([{ size: "sm", color: "red", class: "ring-2 ring-red-300" }]);
+
+button({ size: "sm", color: "red" });
+// → "btn text-sm bg-red-500 ring-2 ring-red-300"
+
+button({ size: "md", color: "red" });
+// → "btn text-base bg-red-500"  (size is md, rule doesn't fire)
+```
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+// Negation: hover:opacity-80 on everything EXCEPT when size=sm
+const button = styra("btn")
+  .variants({
+    size: { sm: "text-sm", md: "text-base", lg: "text-lg" },
+    color: { red: "bg-red-500", blue: "bg-blue-500" },
+  })
+  .compound([{ size: { not: "sm" }, color: "red", class: "hover:opacity-80" }]);
+
+button({ size: "md", color: "red" });
+// → "btn text-base bg-red-500 hover:opacity-80"
+
+button({ size: "sm", color: "red" });
+// → "btn text-sm bg-red-500"  (negation blocks the rule)
+```
+
+---
+
+## 2. Core Patterns
+
+### Pattern 1 — Multiple independent rules (additive)
+
+All rules are evaluated independently. Every matching rule contributes its class.
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const badge = styra("badge")
+  .variants({
+    size: { sm: "text-sm", lg: "text-lg" },
+    color: { red: "bg-red-500", blue: "bg-blue-500" },
+    outlined: "border-2",
+  })
+  .compound([
+    { size: "sm", color: "red", class: "ring-red-300" },
+    { outlined: "true", color: "red", class: "border-red-500" },
+  ]);
+
+badge({ size: "sm", color: "red", outlined: true });
+// → "badge text-sm bg-red-500 border-2 ring-red-300 border-red-500"
+// Both rules matched — both classes applied.
+
+badge({ size: "lg", color: "red", outlined: true });
+// → "badge text-lg bg-red-500 border-2 border-red-500"
+// Only second rule matched — ring not applied.
+```
+
+### Pattern 2 — Negation with Not<T>
+
+`{ not: value }` makes a condition fire when the variant is anything other than `value`.
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({
+    size: { sm: "text-sm", md: "text-base", lg: "text-lg" },
+  })
+  .compound([
+    // Apply hover effect on md and lg, but not sm
+    { size: { not: "sm" }, class: "hover:brightness-110" },
+  ]);
+
+button({ size: "md" });
+// → "btn text-base hover:brightness-110"
+
+button({ size: "lg" });
+// → "btn text-lg hover:brightness-110"
+
+button({ size: "sm" });
+// → "btn text-sm"
+```
+
+### Pattern 3 — Boolean shorthand with negation
+
+Boolean shorthand variants store their state as the string `"true"` or `"false"` internally. Negation must use the string form.
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({
+    size: { sm: "text-sm", lg: "text-lg" },
+    disabled: "opacity-50 cursor-not-allowed",
+  })
+  .compound([
+    // hover effect applies only when disabled is falsy
+    { disabled: { not: "true" }, class: "hover:opacity-80" },
+  ]);
+
+button({ size: "sm" });
+// → "btn text-sm hover:opacity-80"  (disabled not set → rule fires)
+
+button({ size: "sm", disabled: false });
+// → "btn text-sm hover:opacity-80"  (disabled=false → "false", not "true" → rule fires)
+
+button({ size: "sm", disabled: true });
+// → "btn text-sm opacity-50 cursor-not-allowed"  (disabled=true → "true" → negation blocks rule)
+```
+
+### Pattern 4 — Using CompoundRule and Not for typed rule arrays
+
+When building rules outside the builder call, use the exported generic types.
+
+```ts
+import { styra, type CompoundRule, type Not } from "@ntatoud/styra";
+import type { VariantProps } from "@ntatoud/styra";
+
+const button = styra("btn").variants({
+  size: { sm: "text-sm", md: "text-base", lg: "text-lg" },
+  color: { red: "bg-red-500", blue: "bg-blue-500" },
+});
+
+type V = Parameters<typeof button>[0];
+
+// CompoundRule<V> enforces that all keys match variant names and class is present
+const rules: CompoundRule<{
+  size: { sm: string; md: string; lg: string };
+  color: { red: string; blue: string };
+}>[] = [
+  { size: "sm", color: "red", class: "ring-red-300" },
+  { size: { not: "lg" }, class: "shadow-sm" },
+];
+
+const styledButton = button.compound(rules);
+
+styledButton({ size: "sm", color: "red" });
+// → "btn text-sm bg-red-500 ring-red-300 shadow-sm"
+```
+
+---
+
+## 3. Common Mistakes
+
+### [CRITICAL] Using boolean `true` instead of string `"true"` in negation
+
+**Wrong**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({ disabled: "opacity-50" })
+  .compound([
+    { disabled: { not: true }, class: "hover:opacity-80" }, // not: true — boolean, never matches
+  ]);
+
+button({ disabled: true });
+// → "btn opacity-50 hover:opacity-80"  (unexpected — hover should NOT apply)
+```
+
+**Correct**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({ disabled: "opacity-50" })
+  .compound([
+    { disabled: { not: "true" }, class: "hover:opacity-80" }, // not: "true" — string key
+  ]);
+
+button({ disabled: true });
+// → "btn opacity-50"  (hover correctly blocked)
+```
+
+Boolean shorthand variants coerce `true`/`false` props to the string keys `"true"`/`"false"` internally. The negation value must match the stored string key, not the JavaScript boolean. Source: `ntatoud/styra:packages/styra/src/index.ts`
+
+---
+
+### [HIGH] Omitting the `class` key in a compound rule
+
+**Wrong**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({ size: { sm: "text-sm", lg: "text-lg" }, color: { red: "bg-red-500" } })
+  .compound([
+    { size: "sm", color: "red" }, // TypeScript error: missing 'class' property
+  ]);
+```
+
+**Correct**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({ size: { sm: "text-sm", lg: "text-lg" }, color: { red: "bg-red-500" } })
+  .compound([{ size: "sm", color: "red", class: "ring-red-300" }]);
+```
+
+`CompoundRule<V>` requires `class: string`. TypeScript will catch the omission at compile time; at runtime the rule is silently skipped because there is no class to apply. Always include the `class` key. Source: `ntatoud/styra:packages/styra/src/types.ts`
+
+---
+
+### [HIGH] CVA migration: compoundVariants array instead of .compound()
+
+**Wrong**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+// CVA-style API — does not exist in styra
+const button = styra("btn", {
+  variants: { size: { sm: "text-sm", lg: "text-lg" } },
+  compoundVariants: [{ size: "sm", class: "ring-sm" }], // ignored — not a valid option
+});
+```
+
+**Correct**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const button = styra("btn")
+  .variants({ size: { sm: "text-sm", lg: "text-lg" } })
+  .compound([{ size: "sm", class: "ring-sm" }]);
+```
+
+Styra uses a builder chain, not a config object. Compound rules are attached via `.compound([...])` on the builder, not a `compoundVariants` key. Source: `ntatoud/styra:packages/styra/src/index.ts`
+
+---
+
+### [MEDIUM] Writing a compound rule when a default or boolean variant is simpler
+
+**Wrong**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+// Using compound just to apply a class when a single variant has a specific value
+const button = styra("btn")
+  .variants({ intent: { primary: "bg-blue-600", danger: "bg-red-600" } })
+  .compound([
+    { intent: "primary", class: "text-white" },
+    { intent: "danger", class: "text-white" },
+  ]);
+```
+
+**Correct**
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+// Just include the class in the variant map
+const button = styra("btn").variants({
+  intent: {
+    primary: "bg-blue-600 text-white",
+    danger: "bg-red-600 text-white",
+  },
+});
+```
+
+`.compound()` is for cases where a class depends on the intersection of two or more variant values simultaneously. Single-variant class assignments belong directly in the variant map. Source: `ntatoud/styra:packages/styra/src/index.ts`

package/skills/styra-define-variants/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: styra-define-variants
+description: >
+  Define typed variant maps (size, color, state flags) on a styra builder using
+  .variants(), boolean shorthand, .defaults(), and VariantProps. Covers
+  class/className ClassValue inputs, optional vs required variant inference, and
+  compound-rule key coercion.
+type: core
+library: "@ntatoud/styra"
+library_version: "0.1.0"
+requires:
+  - styra-getting-started
+sources:
+  - "ntatoud/styra:packages/styra/src/types.ts"
+  - "ntatoud/styra:packages/styra/src/index.ts"
+---
+
+This skill builds on styra-getting-started. Read it first for foundational concepts.
+
+## Setup
+
+```ts
+import { styra, type VariantProps, type ClassValue } from "@ntatoud/styra";
+
+const buttonVariants = styra("btn")
+  .variants({
+    size: { sm: "text-sm px-2 py-1", md: "text-base px-4 py-2", lg: "text-lg px-6 py-3" },
+    color: { primary: "bg-blue-600 text-white", danger: "bg-red-600 text-white" },
+    disabled: "opacity-50 pointer-events-none",
+  })
+  .defaults({ size: "md" });
+
+type ButtonProps = VariantProps<typeof buttonVariants>;
+// → { size?: "sm" | "md" | "lg"; color: "primary" | "danger"; disabled?: boolean }
+```
+
+## Core Patterns
+
+### Standard variant map
+
+Pass an object of string keys to string values. Each key becomes a prop; each value becomes the class applied when that key is selected.
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const badge = styra("badge").variants({
+  size: {
+    sm: "text-xs px-1",
+    md: "text-sm px-2",
+    lg: "text-base px-3",
+  },
+  color: {
+    gray: "bg-gray-100 text-gray-800",
+    blue: "bg-blue-100 text-blue-800",
+  },
+});
+
+badge({ size: "sm", color: "blue" }); // "badge text-xs px-1 bg-blue-100 text-blue-800"
+```
+
+All variant keys are required unless covered by `.defaults()`.
+
+### Boolean shorthand
+
+When a variant value is a plain string instead of an object, the prop becomes `boolean`. The string is applied when the prop is `true`; nothing is applied when it is `false` or `undefined`.
+
+```ts
+import { styra } from "@ntatoud/styra";
+
+const btn = styra("btn").variants({
+  disabled: "opacity-50 pointer-events-none",
+  active: "ring-2 ring-offset-2",
+});
+
+btn({ disabled: true, active: false }); // "btn opacity-50 pointer-events-none"
+btn({ disabled: false, active: true }); // "btn ring-2 ring-offset-2"
+btn({ disabled: false, active: false }); // "btn"
+```
+
+Internally the shorthand `"opacity-50 pointer-events-none"` is stored as `{ true: "opacity-50 pointer-events-none", false: "" }`. The boolean prop value is coerced to the string `"true"` or `"false"` for map lookup.
+
+### Making variants optional with `.defaults()`
+
+Call `.defaults()` with a partial map of variant keys to their default values. Variants covered by a default become optional in the inferred props type; uncovered variants remain required.
+
+```ts
+import { styra, type VariantProps } from "@ntatoud/styra";
+
+const chip = styra("chip")
+  .variants({
+    size: { sm: "text-xs", md: "text-sm", lg: "text-base" },
+    color: { blue: "bg-blue-100", green: "bg-green-100" },
+  })
+  .defaults({ size: "md" });
+
+// size is optional (has default); color is required (no default)
+type ChipProps = VariantProps<typeof chip>;
+// → { size?: "sm" | "md" | "lg"; color: "blue" | "green" }
+
+chip({ color: "blue" }); // "chip text-sm bg-blue-100"
+chip({ size: "lg", color: "green" }); // "chip text-base bg-green-100"
+```
+
+### `class` and `className` ClassValue inputs
+
+Both `class` and `className` props accept a `ClassValue`: a string, number, boolean, null, undefined, an array of `ClassValue`, or a `Record<string, unknown>` where truthy values include the key as a class. `className` also accepts a render-prop function returning `ClassValue`.
+
+```ts
+import { styra, type ClassValue } from "@ntatoud/styra";
+
+const btn = styra("btn").variants({ disabled: "opacity-50" });
+
+// String
+btn({ disabled: false, class: "mt-4" }); // "btn mt-4"
+
+// Array
+btn({ disabled: true, class: ["mt-4", "px-2"] }); // "btn opacity-50 mt-4 px-2"
+
+// Object map — truthy values include the key
+btn({ disabled: false, class: { "mt-4": true, "px-2": false } }); // "btn mt-4"
+
+// Mixed array
+btn({ disabled: false, class: ["mt-4", { "px-2": true, "py-1": false }] }); // "btn mt-4 px-2"
+
+// className render-prop (Base UI / headless pattern)
+btn({
+  disabled: true,
+  className: (state: { disabled: boolean }) => (state.disabled ? "cursor-not-allowed" : undefined),
+});
+```
+
+`VariantProps<T>` strips both `class` and `className` from the inferred type so component prop interfaces stay clean.
+
+## Common Mistakes
+
+### [CRITICAL] Omitting a required variant silently produces no class
+
+Without a default, a missing variant resolves to `undefined`, which maps to no class. TypeScript catches this, but only when `VariantProps` is used for the component's prop type.
+
+```ts
+// Wrong — size has no default and is not passed; TypeScript error is suppressed by `as any`
+const card = styra("card").variants({ size: { sm: "p-2", lg: "p-6" } });
+(card as any)({}); // "card" — size class is silently dropped
+```
+
+```ts
+// Correct — either pass the variant or add a default
+const card = styra("card")
+  .variants({ size: { sm: "p-2", lg: "p-6" } })
+  .defaults({ size: "sm" });
+
+card({}); // "card p-2"
+```
+
+Always use `VariantProps<typeof yourVariants>` as your component's prop type so TypeScript enforces required variants at call sites. Source: `packages/styra/src/types.ts` — `InferProps`.
+
+### [HIGH] Using `{ true: "...", false: "" }` when boolean shorthand is available
+
+Explicit two-key objects are verbose and error-prone. Boolean shorthand produces the same runtime behavior with less code.
+
+```ts
+// Wrong — verbose, no benefit over shorthand
+const btn = styra("btn").variants({
+  disabled: { true: "opacity-50 pointer-events-none", false: "" },
+});
+```
+
+```ts
+// Correct — boolean shorthand
+const btn = styra("btn").variants({
+  disabled: "opacity-50 pointer-events-none",
+});
+```
+
+The implementation converts the plain string to `{ true: raw, false: "" }` internally. Source: `packages/styra/src/index.ts` — `makeBuilder`.
+
+### [HIGH] Passing a boolean key in a compound rule when the stored key is the string `"true"`
+
+Boolean shorthand stores the value under the string key `"true"`, not the JavaScript boolean `true`. Compound rules that reference boolean variants must use the string `"true"`.
+
+```ts
+// Wrong — boolean true is not a valid key in a compound rule
+const btn = styra("btn")
+  .variants({ disabled: "opacity-50", color: { red: "bg-red-500", blue: "bg-blue-500" } })
+  .compounds([{ disabled: true, color: "red", class: "border-red-700" }]); // runtime miss
+```
+
+```ts
+// Correct — use the string "true" as the key value
+const btn = styra("btn")
+  .variants({ disabled: "opacity-50", color: { red: "bg-red-500", blue: "bg-blue-500" } })
+  .compounds([{ disabled: "true", color: "red", class: "border-red-700" }]);
+```
+
+The `toKey` coercion applies only to incoming prop values, not to the keys written in compound rule objects. Source: `packages/styra/src/index.ts` — `toKey`.
+
+### [MEDIUM] Expecting `VariantProps` to include `class` or `className`
+
+`VariantProps<T>` deliberately omits `class` and `className`. Use the full `Parameters<T>[0]` type if you need to forward those props, or spread them separately.
+
+```ts
+// Wrong — class is stripped from VariantProps
+import { type VariantProps } from "@ntatoud/styra";
+
+const btn = styra("btn").variants({ size: { sm: "text-sm", md: "text-md" } });
+type BtnProps = VariantProps<typeof btn> & { onClick: () => void };
+// BtnProps has no `class` or `className` — passing class from the parent is a TypeScript error
+```
+
+```ts
+// Correct — add ClassValue explicitly when the component needs to accept extra classes
+import { styra, type VariantProps, type ClassValue } from "@ntatoud/styra";
+
+const btn = styra("btn").variants({ size: { sm: "text-sm", md: "text-md" } });
+type BtnProps = VariantProps<typeof btn> & { class?: ClassValue; onClick: () => void };
+```
+
+Source: `packages/styra/src/types.ts` — `VariantProps`.