This skill defines the authoritative standards for building and extending the **Nexus UI Primitive Layer**. Every core component in `core/src/components/ui/` MUST strictly adhere to these patterns to ...
This skill defines the authoritative standards for building and extending the Nexus UI Primitive Layer. Every core component in core/src/components/ui/ MUST strictly adhere to these patterns to ensure accessibility, extensibility, and consistent styling across the modular monolith.
All container-based UI primitives (e.g., Button, Label, Card) MUST support the asChild pattern using @radix-ui/react-slot. This allows consumers to swap the underlying DOM element while maintaining all styles and behaviors. Void elements (e.g., Input, Textarea, Img) are exempt from this requirement.
const Comp = asChild ? Slot : 'button'; (or appropriate element).<Button asChild><a href="...">Link</a></Button>) without DOM nesting issues.Component styles and variants MUST be managed using class-variance-authority (CVA).
const componentVariants = cva(...) and export it alongside the component.cn utility to merge base classes, variants, and incoming className.btn-default, btn-ghost) that are defined in @layer components CSS files rather than raw utility strings.Every primitive MUST include explicit data attributes for identification and state-based styling.
data-slot="{component-name}" on the root element.data-variant={variant}, data-size={size}).data-testid separation) and allows CSS-based styling overrides without class collision.All UI primitives MUST use React.forwardRef to ensure they can be used with focus management and third-party libraries (like Tooltips or Popovers).
displayName matching the component name.All UI primitives MUST use Named Exports to ensure better tree-shaking and explicit importing. Default exports are reserved for lazy-loaded pages or registry components.
export { ComponentName, componentVariants };export default ComponentName; for core primitives.import * as React from 'react';
import { Slot } from '@radix-ui/react-slot';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const primitiveVariants = cva(
'primitive-base', // Semantic base class - refer to @layer components
{
variants: {
variant: {
default: 'primitive-default', // Semantic class
destructive: 'primitive-destructive',
},
size: {
default: 'h-9 px-4 py-2',
sm: 'h-8 rounded-md px-3 text-xs',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
},
);
export interface PrimitiveProps
extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof primitiveVariants> {
asChild?: boolean;
}
const Primitive = React.forwardRef<HTMLButtonElement, PrimitiveProps>(
({ className, variant, size, asChild = false, ...props }, ref) => {
const Comp = asChild ? Slot : 'button';
return (
<Comp
className={cn(primitiveVariants({ variant, size, className }))}
ref={ref}
data-slot="primitive"
data-variant={variant}
data-size={size}
{...props}
/>
);
},
);
Primitive.displayName = 'Primitive';
export { Primitive, primitiveVariants };
core/.skills/use-ui-primitives/templates/primitive.tsx.templatecore/.skills/use-ui-primitives/examples/button-primitive.tsxcore/.skills/use-ui-primitives/examples/input-primitive.tsxcore/CODE.md Section 4 (Styling & CSS).