create-inox-app 0.1.0

package/dist/templates/claude-config/app/.agents/skills/building-components/references/registry.mdx

@@ -0,0 +1,169 @@
+---
+title: Registry
+description: Understand the concept of component registries, how they work, and why they're revolutionizing how developers share and discover UI components.
+type: conceptual
+summary: What component registries are, their source-code distribution model, and how to create one using the shadcn ecosystem.
+related:
+  - /npm
+  - /marketplaces
+  - /docs
+---
+
+Component registries are a way to share and discover UI components. Popularized by [shadcn/ui](https://ui.shadcn.com), they allow you to discover and copy components directly into your projects.
+
+Registries represent a fundamental shift in how developers share and discover UI components. Unlike traditional npm packages, registries rely on an open source model and work through downloading the source code to your project.
+
+## What Makes a Registry?
+
+### 1. Source Code Distribution
+
+Unlike npm packages that distribute compiled code, registries distribute source code:
+
+```typescript
+// Traditional npm package
+import { Button } from "some-ui-library";
+
+// Registry-based component
+// Copy source from registry into your project
+// src/components/ui/button.tsx contains the full source
+import { Button } from "@/components/ui/button";
+```
+
+### 2. Metadata and Configuration
+
+Good registries include rich metadata about components like the name, description, dependencies, and category.
+
+```json
+{
+  "name": "announcement",
+  "type": "registry:component",
+  "description": "A compound badge component designed to display announcements with theming support",
+  "dependencies": ["class-variance-authority", "lucide-react"],
+  "registryDependencies": ["badge"],
+  "files": [
+    {
+      "type": "registry:component",
+      "content": "..."
+    }
+  ],
+  "category": "ui"
+}
+```
+
+### 3. Preview and Documentation
+
+While not downloaded, registry websites typically provide:
+
+- Live component previews
+- Interactive examples
+- Detailed documentation
+- Code snippets ready to copy
+
+## Registry Architecture Benefits
+
+Component registries offer significant advantages for both authors and users, streamlining the process of sharing and adopting UI components.
+
+### For Authors
+
+For component authors, registries make distribution remarkably simple. Once a component is created, it can be added to the registry, making it instantly accessible to users without the need for complex publishing steps. This ease of distribution accelerates the feedback loop and encourages rapid iteration.
+
+Version control is another key benefit. Registries typically track component versions, changelogs, and compatibility information. For example, a component entry might specify its current version, highlight recent changes such as improved accessibility or new features, and indicate which versions of shadcn/ui it supports. This transparency helps maintainers communicate updates and ensures users can select components that fit their project requirements.
+
+Community engagement is also enhanced through registries. Authors can receive direct feedback from users, who are able to report issues, request features, and contribute to collaborative improvements. This fosters a more interactive and responsive development environment, benefiting both creators and consumers.
+
+### For Consumers
+
+From the perspective of component users, registries greatly improve the discovery process. Users can browse components by category, utilize search functionality, view popularity metrics, and explore related components, making it easier to find exactly what they need for their projects.
+
+Before integrating a component, users can preview it in action, experiment with different variants, and review its behavior and code quality. This ability to evaluate components beforehand reduces risk and increases confidence in adoption.
+
+Perhaps most importantly, registries empower users with true ownership. Instead of being locked into a dependency, users copy the source code directly into their projects. This means they can modify components as needed, avoid dependency management headaches, and retain full control over their codebase.
+
+## Creating a Registry
+
+You can create a simple registry quite quickly. Practically speaking, you only need 3 core elements:
+
+### 1. Components
+
+Create a component, or set of components, that you want to share. Make sure you have the source code for the components, and that they are well-documented and easy to understand.
+
+Consider adding things like Markdown documentation, example implementations, and a way to preview the component.
+
+### 2. A public endpoint
+
+Create a public endpoint that serves the components. This can be a simple JSON file, or a more complex website. As long as it is public and accessible, you can use any endpoint you want.
+
+### 3. CLI
+
+Create a CLI that allows you to install the components into your project. This can be as simple as a single command, like `npx myregistry add button`, or a more complex command with options and flags.
+
+## Using the shadcn Registry
+
+Building your own registry is a fantastic way to share your components with the community, but it requires a lot of effort and maintenance. If you just want to share a component or two, you can use the shadcn/ui ecosystem - registry, CLI and variables.
+
+Let's see how we can publish a `MetricCard` component live in less than 5 minutes using [Vercel](https://vercel.com)'s static hosting.
+
+### Step 1: Create a Folder
+
+Make a folder with this structure:
+
+```
+my-component/
+├── public/
+│   └── metric-card.json
+└── vercel.json
+```
+
+Put your registry item JSON (e.g. `metric-card.json`) in the `public/` folder.
+
+### Step 2: Add a `vercel.json`
+
+Create a `vercel.json` file next to `public/` with the following:
+
+```json title="vercel.json"
+{
+  "headers": [
+    {
+      "source": "/(.*).json",
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "*"
+        },
+        {
+          "key": "Content-Type",
+          "value": "application/json"
+        }
+      ]
+    }
+  ]
+}
+```
+
+This ensures your JSON is served with the correct CORS and content headers.
+
+### Step 3: Deploy to Vercel
+
+From the root of your folder, run:
+
+```bash
+vercel --prod
+```
+
+and answer the prompts to deploy your project.
+
+When it's done, your file will be live at something like:
+
+```
+https://your-project-name.vercel.app/metric-card.json
+```
+
+### Step 4: Install the Component
+
+Anyone can now run:
+
+```bash
+npx shadcn@latest add https://your-project-name.vercel.app/metric-card.json
+```
+
+No npm package, no build step, no complexity.

package/dist/templates/claude-config/app/.agents/skills/building-components/references/state.mdx

@@ -0,0 +1,99 @@
+---
+title: State
+description: How to manage state in a component, as well as merging controllable and uncontrolled state.
+type: reference
+summary: Controlled vs uncontrolled state patterns and merging both modes with useControllableState from Radix UI.
+prerequisites:
+  - /composition
+  - /types
+related:
+  - /as-child
+---
+
+Building flexible components that work in both controlled and uncontrolled modes is a hallmark of professional components.
+
+## Uncontrolled State
+
+Uncontrolled state is when the component manages its own state internally. This is the default usage pattern for most components.
+
+For example, here's a simple `Stepper` component that manages its own state internally:
+
+```tsx title="stepper.tsx"
+import { useState } from "react";
+
+export const Stepper = () => {
+  const [value, setValue] = useState(0);
+
+  return (
+    <div>
+      <p>{value}</p>
+      <button onClick={() => setValue(value + 1)}>Increment</button>
+    </div>
+  );
+};
+```
+
+## Controlled State
+
+Controlled state is when the component's state is managed by the parent component. Rather than keeping track of the state internally, we delegate this responsibility to the parent component.
+
+Let's rework the `Stepper` component to be controlled by the parent component:
+
+```tsx title="stepper.tsx"
+type StepperProps = {
+  value: number;
+  setValue: (value: number) => void;
+};
+
+export const Stepper = ({ value, setValue }: StepperProps) => (
+  <div>
+    <p>{value}</p>
+    <button onClick={() => setValue(value + 1)}>Increment</button>
+  </div>
+);
+```
+
+## Merging states
+
+The best components support both controlled and uncontrolled state. This allows the component to be used in a variety of scenarios, and to be easily customized.
+
+[Radix UI](https://www.radix-ui.com/) maintain an internal utility for merging controllable and uncontrolled state called [`use-controllable-state`](https://github.com/radix-ui/primitives/tree/main/packages/react/use-controllable-state). While not intended for public use, registries like [Kibo UI](https://www.kibo-ui.com) have implemented this utility to build their own Radix-like components.
+
+Let's install the hook:
+
+```package-install
+npm install @radix-ui/react-use-controllable-state
+```
+
+This lightweight hook gives you the same state management patterns used internally by Radix UI's component library, ensuring your components behave consistently with industry standards.
+
+The hook accepts three main parameters and returns a tuple with the current value and setter. Let's use it to merge the controlled and uncontrolled state of the `Stepper` component:
+
+```tsx title="stepper.tsx"
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+
+type StepperProps = {
+  value: number;
+  defaultValue: number;
+  onValueChange: (value: number) => void;
+};
+
+export const Stepper = ({
+  value: controlledValue,
+  defaultValue,
+  onValueChange,
+}: StepperProps) => {
+  const [value, setValue] = useControllableState({
+    prop: controlledValue, // The controlled value prop
+    defaultProp: defaultValue, // Default value for uncontrolled mode
+    onChange: onValueChange, // Called when value changes
+  });
+
+  return (
+    <div>
+      <p>{value}</p>
+      <button onClick={() => setValue(value + 1)}>Increment</button>
+    </div>
+  );
+};
+```

package/dist/templates/claude-config/app/.agents/skills/building-components/references/styling.mdx

@@ -0,0 +1,286 @@
+---
+title: Styling
+description: Conditional and composable styling with Tailwind classes.
+type: guide
+summary: Using tailwind-merge, clsx, the cn utility, and Class Variance Authority for conditional and composable component styling.
+prerequisites:
+  - /composition
+related:
+  - /design-tokens
+  - /data-attributes
+---
+
+Modern component libraries need flexible styling systems that can handle complex requirements without sacrificing developer experience. The combination of Tailwind CSS with intelligent class merging has emerged as a powerful pattern for building customizable components.
+
+This approach solves the fundamental tension between providing sensible defaults and allowing complete customization - a challenge that has plagued component libraries for years.
+
+## The problem with traditional styling
+
+Traditional CSS approaches often lead to specificity wars, style conflicts, and unpredictable overrides. When you pass `className="bg-blue-500"` to a component that already has `bg-red-500`, which one wins?
+
+Without proper handling, both classes apply and the result depends on a lot of factors - CSS source order, the specificity of the classes, the bundler's class merging algorithm, etc.
+
+## Merging classes intelligently
+
+The `tailwind-merge` library solves this by understanding Tailwind's class structure and intelligently resolving conflicts. When two classes target the same CSS property, it keeps only the last one.
+
+```tsx title="Without tailwind-merge"
+// Both bg-red-500 and bg-blue-500 apply - unpredictable result
+<Button className="bg-blue-500" />
+// Renders: className="bg-red-500 bg-blue-500"
+```
+
+```tsx title="With tailwind-merge"
+import { twMerge } from "tailwind-merge";
+
+// bg-blue-500 wins as it comes last
+const className = twMerge("bg-red-500", "bg-blue-500");
+// Returns: "bg-blue-500"
+```
+
+This works for all Tailwind utilities:
+
+```tsx
+twMerge("px-4 py-2", "px-8"); // Returns: "py-2 px-8"
+twMerge("text-sm", "text-lg"); // Returns: "text-lg"
+twMerge("hover:bg-red-500", "hover:bg-blue-500"); // Returns: "hover:bg-blue-500"
+```
+
+The library understands Tailwind's modifier system too:
+
+```tsx
+// Modifiers are handled correctly
+twMerge("hover:bg-red-500 focus:bg-red-500", "hover:bg-blue-500");
+// Returns: "focus:bg-red-500 hover:bg-blue-500"
+```
+
+## Conditional classes
+
+Often you need to apply classes conditionally based on props or state. The `clsx` library provides a clean API for this:
+
+```tsx title="Using clsx"
+import clsx from "clsx";
+
+// Basic conditionals
+clsx("base", isActive && "active");
+// Returns: "base active" (if isActive is true)
+
+// Object syntax
+clsx("base", {
+  active: isActive,
+  disabled: isDisabled,
+});
+
+// Arrays
+clsx(["base", isLarge ? "text-lg" : "text-sm"]);
+
+// Mixed
+clsx(
+  "base",
+  ["array-item"],
+  { "object-conditional": true },
+  isActive && "conditional",
+);
+```
+
+A common pattern is to merge a default set of classes with incoming props, as well as any custom logic we have:
+
+```tsx title="component.tsx"
+const Component = ({ className, ...props }: ComponentProps) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border bg-white shadow-sm",
+        isOpen && "bg-blue-500",
+        className,
+      )}
+      {...props}
+    />
+  );
+};
+```
+
+## The `cn` utility function
+
+The `cn` function, popularized by [shadcn/ui](https://ui.shadcn.com/), combines `clsx` and `tailwind-merge` to give you both conditional logic and intelligent merging:
+
+```tsx title="lib/utils.ts"
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+The power comes from the ordering - base styles first, conditionals second, user overrides last. This ensures predictable behavior while maintaining full customization.
+
+## Class Variance Authority (CVA)
+
+For complex components with many variants, manually managing conditional classes becomes unwieldy. [Class Variance Authority (CVA)](https://cva.style/docs) provides a declarative API for defining component variants.
+
+For example, here's an extract from the [Button](https://ui.shadcn.com/docs/components/button) component from shadcn/ui:
+
+```tsx title="@/components/ui/button.tsx"
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+```
+
+## Best practices
+
+### 1. Order matters
+
+Always apply classes in this order:
+
+1. Base styles (always applied)
+2. Variant styles (based on props)
+3. Conditional styles (based on state)
+4. User overrides (className prop)
+
+```tsx
+className={cn(
+  'base-styles',            // 1. Base
+  variant && variantStyles, // 2. Variants
+  isActive && 'active',     // 3. Conditionals
+  className                 // 4. User overrides
+)}
+```
+
+### 2. Document your variants
+
+Use TypeScript and JSDoc to document what each variant does:
+
+```tsx
+type ButtonProps = {
+  /**
+   * The visual style of the button
+   * @default "primary"
+   */
+  variant?: "primary" | "secondary" | "destructive" | "ghost";
+
+  /**
+   * The size of the button
+   * @default "md"
+   */
+  size?: "sm" | "md" | "lg";
+};
+```
+
+### 3. Extract repeated patterns
+
+If you find yourself writing the same conditional logic repeatedly, extract it:
+
+```tsx title="utils/styles.ts"
+export const focusRing = 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500';
+export const disabled = 'disabled:pointer-events-none disabled:opacity-50';
+
+// Use in components
+className={cn(focusRing, disabled, className)}
+```
+
+## Migration guide
+
+If you're migrating from a different styling approach, here's how to adapt common patterns:
+
+### From CSS Modules
+
+```tsx title="Before - CSS Modules"
+import styles from "./Button.module.css";
+
+<button className={`${styles.button} ${styles[variant]} ${className}`} />;
+```
+
+```tsx title="After - cn + Tailwind"
+import { cn } from "@/lib/utils";
+
+<button
+  className={cn(
+    "px-4 py-2 rounded-lg",
+    variant === "primary" && "bg-blue-500 text-white",
+    className,
+  )}
+/>;
+```
+
+### From styled-components
+
+```tsx title="Before - styled-components"
+const Button = styled.button<{ $primary?: boolean }>`
+  padding: 8px 16px;
+  background: ${(props) => (props.$primary ? "blue" : "gray")};
+`;
+```
+
+```tsx title="After - cn + Tailwind"
+function Button({ primary, className, ...props }) {
+  return (
+    <button
+      className={cn(
+        "px-4 py-2",
+        primary ? "bg-blue-500" : "bg-gray-500",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## Performance considerations
+
+Both `clsx` and `tailwind-merge` are highly optimized, but keep these tips in mind:
+
+1. **Define variants outside components** - CVA variants should be defined outside the component to avoid recreation on every render.
+
+2. **Memoize complex computations** - If you have expensive conditional logic, consider memoizing:
+
+```tsx
+const className = useMemo(
+  () => cn(baseStyles, expensiveComputation(props), className),
+  [props, className],
+);
+```
+
+3. **Use CSS variables for dynamic values** - Instead of generating classes dynamically, use CSS variables:
+
+```tsx title="Prefer CSS variables"
+// Good
+<div
+  className="bg-[var(--color)]"
+  style={{ '--color': dynamicColor } as React.CSSProperties}
+/>
+
+// Avoid
+<div className={`bg-[${dynamicColor}]`} />
+```
+
+The combination of Tailwind CSS, intelligent class merging, and variant APIs provides a robust foundation for component styling. This approach scales from simple buttons to complex design systems while maintaining predictability and developer experience.