@devmunna/agent-skillkit 0.1.0

package/skills/tailwind-css/references/components.md

@@ -0,0 +1,340 @@
+# Component Patterns Reference
+
+---
+
+## cn() — Class Merging Helper
+
+**Always create this file. Every component depends on it.**
+
+```ts
+// src/lib/utils.ts
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge }               from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+`clsx` handles conditional class logic. `twMerge` resolves Tailwind conflicts so caller-provided classes always win:
+```tsx
+// Without cn: "rounded-md rounded-full" — broken, both apply
+// With cn:    "rounded-full"            — tailwind-merge picks the last/winner
+<Button className="rounded-full" />
+```
+
+---
+
+## Button — CVA Pattern
+
+```ts
+// src/components/ui/Button.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const buttonVariants = cva(
+  // Base styles — always applied
+  [
+    'inline-flex items-center justify-center gap-2 rounded-md font-medium',
+    'transition-colors select-none',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ],
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-white hover:bg-primary/90 focus-visible:ring-primary',
+        outline:     'border border-current bg-transparent hover:bg-primary/10 text-primary',
+        ghost:       'hover:bg-primary/10 hover:text-primary',
+        destructive: 'bg-danger text-white hover:bg-danger/90 focus-visible:ring-danger',
+        link:        'text-primary underline-offset-4 hover:underline p-0 h-auto',
+      },
+      size: {
+        sm:   'h-8  px-3 text-sm',
+        md:   'h-10 px-4',
+        lg:   'h-12 px-6 text-base',
+        icon: 'size-10 shrink-0',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size:    'md',
+    },
+  },
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  isLoading?: boolean;
+}
+
+export function Button({
+  className,
+  variant,
+  size,
+  isLoading,
+  children,
+  disabled,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size }), className)}
+      disabled={disabled || isLoading}
+      {...props}
+    >
+      {isLoading && (
+        <svg className="size-4 animate-spin" viewBox="0 0 24 24" fill="none">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8v8z" />
+        </svg>
+      )}
+      {children}
+    </button>
+  );
+}
+```
+
+Usage:
+```tsx
+<Button>Default</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="destructive" size="sm">Delete</Button>
+<Button variant="ghost" size="icon"><TrashIcon /></Button>
+<Button isLoading>Saving...</Button>
+<Button className="w-full">Full Width</Button>  {/* className always wins */}
+```
+
+---
+
+## Card
+
+```tsx
+// src/components/ui/Card.tsx
+import { cn } from '@/lib/utils';
+
+type DivProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function Card({ className, ...props }: DivProps) {
+  return (
+    <div
+      className={cn('rounded-xl border border-border-col bg-card shadow-card', className)}
+      {...props}
+    />
+  );
+}
+
+export function CardHeader({ className, ...props }: DivProps) {
+  return (
+    <div
+      className={cn('flex flex-col gap-1.5 border-b border-border-col px-6 py-4', className)}
+      {...props}
+    />
+  );
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return (
+    <h3
+      className={cn('text-lg font-semibold leading-none tracking-tight text-fg', className)}
+      {...props}
+    />
+  );
+}
+
+export function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return (
+    <p className={cn('text-sm text-muted', className)} {...props} />
+  );
+}
+
+export function CardContent({ className, ...props }: DivProps) {
+  return <div className={cn('px-6 py-4', className)} {...props} />;
+}
+
+export function CardFooter({ className, ...props }: DivProps) {
+  return (
+    <div
+      className={cn('flex items-center border-t border-border-col px-6 py-4', className)}
+      {...props}
+    />
+  );
+}
+```
+
+Usage:
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Users</CardTitle>
+    <CardDescription>Manage your team members</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <UserList users={users} />
+  </CardContent>
+  <CardFooter className="justify-end gap-2">
+    <Button variant="outline">Cancel</Button>
+    <Button>Save</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Input
+
+```tsx
+// src/components/ui/Input.tsx
+import { cn } from '@/lib/utils';
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: string;
+  label?: string;
+}
+
+export function Input({ className, error, label, id, ...props }: InputProps) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      {label && (
+        <label htmlFor={id} className="text-sm font-medium text-fg">
+          {label}
+        </label>
+      )}
+      <input
+        id={id}
+        className={cn(
+          'flex h-10 w-full rounded-md border bg-bg px-3 py-2 text-sm',
+          'placeholder:text-muted',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          error
+            ? 'border-danger focus-visible:ring-danger'
+            : 'border-border-col',
+          className,
+        )}
+        {...props}
+      />
+      {error && <p className="text-xs text-danger">{error}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## Badge
+
+```tsx
+// src/components/ui/Badge.tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const badgeVariants = cva(
+  'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium transition-colors',
+  {
+    variants: {
+      variant: {
+        default:     'bg-primary text-white',
+        secondary:   'bg-primary/10 text-primary',
+        outline:     'border border-current text-fg',
+        success:     'bg-success/10 text-success',
+        warning:     'bg-warning/10 text-warning',
+        destructive: 'bg-danger/10 text-danger',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+);
+
+interface BadgeProps
+  extends React.HTMLAttributes<HTMLSpanElement>,
+    VariantProps<typeof badgeVariants> {}
+
+export function Badge({ className, variant, ...props }: BadgeProps) {
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
+}
+```
+
+---
+
+## Skeleton (Loading Placeholder)
+
+```tsx
+// src/components/ui/Skeleton.tsx
+import { cn } from '@/lib/utils';
+
+export function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('animate-pulse rounded-md bg-border-col', className)}
+      {...props}
+    />
+  );
+}
+
+// Usage patterns
+export function UserCardSkeleton() {
+  return (
+    <div className="flex items-center gap-3 p-4">
+      <Skeleton className="size-10 rounded-full" />
+      <div className="flex flex-col gap-2">
+        <Skeleton className="h-4 w-32" />
+        <Skeleton className="h-3 w-24" />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Modal / Dialog
+
+```tsx
+// src/components/ui/Modal.tsx
+'use client'; // if Next.js
+
+import { useEffect } from 'react';
+import { cn }        from '@/lib/utils';
+
+interface ModalProps {
+  isOpen:    boolean;
+  onClose:   () => void;
+  children:  React.ReactNode;
+  className?: string;
+}
+
+export function Modal({ isOpen, onClose, children, className }: ModalProps) {
+  // Close on Escape key
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 bg-black/50 backdrop-blur-sm"
+        onClick={onClose}
+      />
+      {/* Content */}
+      <div
+        className={cn(
+          'relative z-10 w-full max-w-md rounded-xl bg-bg p-6 shadow-lg',
+          'animate-scale-in',
+          className,
+        )}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+```

package/skills/tailwind-css/references/design-tokens.md

@@ -0,0 +1,230 @@
+# Design Tokens Reference — @theme
+
+All custom tokens go in `@theme` in your global CSS file. Tailwind generates utility classes automatically from the variable names.
+
+---
+
+## Colors — OKLCH (Preferred in v4)
+
+OKLCH provides perceptually uniform lightness, making it easy to create consistent color scales.  
+Format: `oklch(lightness saturation hue)` — lightness 0–1, saturation 0–0.4, hue 0–360.
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Primary brand color + scale */
+  --color-primary:      oklch(0.55 0.25 262);
+  --color-primary-50:   oklch(0.97 0.02 262);
+  --color-primary-100:  oklch(0.93 0.05 262);
+  --color-primary-500:  oklch(0.55 0.25 262);
+  --color-primary-600:  oklch(0.48 0.25 262);
+  --color-primary-900:  oklch(0.25 0.15 262);
+
+  /* Semantic colors */
+  --color-success:  oklch(0.65 0.15 142);
+  --color-warning:  oklch(0.75 0.17 80);
+  --color-danger:   oklch(0.55 0.25 27);
+  --color-info:     oklch(0.60 0.20 230);
+
+  /* Neutral surface colors — works well with dark mode */
+  --color-surface:        white;
+  --color-surface-raised: oklch(0.98 0 0);
+  --color-border:         oklch(0.90 0 0);
+  --color-muted:          oklch(0.55 0 0);
+}
+```
+
+Generated utilities: `bg-primary`, `bg-primary-500`, `text-danger`, `border-success`, `text-muted`, etc.
+
+---
+
+## Dark Mode Color Tokens
+
+Define light/dark values with CSS custom properties, then reference them in `@theme`:
+
+```css
+@import "tailwindcss";
+
+/* Light mode defaults */
+:root {
+  --bg:         white;
+  --fg:         oklch(0.15 0 0);
+  --border-col: oklch(0.88 0 0);
+  --muted-col:  oklch(0.55 0 0);
+  --card-col:   oklch(0.97 0 0);
+}
+
+/* Dark mode overrides */
+.dark {
+  --bg:         oklch(0.12 0 0);
+  --fg:         oklch(0.95 0 0);
+  --border-col: oklch(0.25 0 0);
+  --muted-col:  oklch(0.55 0 0);
+  --card-col:   oklch(0.16 0 0);
+}
+
+/* Expose to Tailwind */
+@theme {
+  --color-bg:     var(--bg);
+  --color-fg:     var(--fg);
+  --color-border-col: var(--border-col);
+  --color-muted:  var(--muted-col);
+  --color-card:   var(--card-col);
+}
+```
+
+Usage:
+```html
+<div class="bg-bg text-fg border border-border-col">
+  <div class="bg-card rounded-lg p-4">Card content</div>
+</div>
+```
+
+---
+
+## Typography Tokens
+
+```css
+@theme {
+  --font-sans:    'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-serif:   'Playfair Display', ui-serif, Georgia, serif;
+  --font-mono:    'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace;
+
+  /* Font sizes with paired line-heights */
+  --text-xs:   0.75rem / 1rem;
+  --text-sm:   0.875rem / 1.25rem;
+  --text-base: 1rem / 1.5rem;
+  --text-lg:   1.125rem / 1.75rem;
+  --text-xl:   1.25rem / 1.75rem;
+  --text-2xl:  1.5rem / 2rem;
+  --text-3xl:  1.875rem / 2.25rem;
+  --text-4xl:  2.25rem / 2.5rem;
+}
+```
+
+Generated utilities: `font-sans`, `font-serif`, `font-mono`, `text-xs` through `text-4xl`.
+
+---
+
+## Spacing Tokens
+
+Spacing tokens affect: `p-*`, `m-*`, `gap-*`, `w-*`, `h-*`, `top-*`, `left-*`, etc.
+
+```css
+@theme {
+  /* Semantic spacing (for consistent page layout) */
+  --spacing-page:    2rem;     /* px-page */
+  --spacing-section: 4rem;     /* py-section */
+  --spacing-card:    1.5rem;   /* p-card */
+}
+```
+
+---
+
+## Border Radius Tokens
+
+```css
+@theme {
+  --radius-sm:   0.25rem;    /* rounded-sm */
+  --radius-md:   0.5rem;     /* rounded-md */
+  --radius-lg:   0.75rem;    /* rounded-lg */
+  --radius-xl:   1rem;       /* rounded-xl */
+  --radius-card: 0.75rem;    /* rounded-card */
+  --radius-pill: 9999px;     /* rounded-pill */
+}
+```
+
+---
+
+## Shadow Tokens
+
+```css
+@theme {
+  --shadow-sm:  0 1px 2px 0 oklch(0 0 0 / 0.05);
+  --shadow-md:  0 4px 6px -1px oklch(0 0 0 / 0.1), 0 2px 4px -2px oklch(0 0 0 / 0.1);
+  --shadow-lg:  0 10px 15px -3px oklch(0 0 0 / 0.1), 0 4px 6px -4px oklch(0 0 0 / 0.1);
+  --shadow-card: 0 2px 8px oklch(0 0 0 / 0.08);
+}
+```
+
+---
+
+## Animation Tokens
+
+```css
+@theme {
+  --animate-fade-in:    fade-in 0.2s ease-out;
+  --animate-slide-up:   slide-up 0.3s ease-out;
+  --animate-slide-down: slide-down 0.3s ease-out;
+  --animate-scale-in:   scale-in 0.2s ease-out;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes slide-up {
+  from { transform: translateY(0.5rem); opacity: 0; }
+  to   { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes slide-down {
+  from { transform: translateY(-0.5rem); opacity: 0; }
+  to   { transform: translateY(0); opacity: 1; }
+}
+
+@keyframes scale-in {
+  from { transform: scale(0.95); opacity: 0; }
+  to   { transform: scale(1); opacity: 1; }
+}
+```
+
+Generated utilities: `animate-fade-in`, `animate-slide-up`, `animate-slide-down`, `animate-scale-in`.
+
+---
+
+## Custom Utilities — @utility
+
+```css
+/* Static utility */
+@utility center-flex {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Truncate with line clamp */
+@utility truncate-2 {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+Usage: `<div class="center-flex truncate-2">`.
+
+---
+
+## Custom Variants — @custom-variant
+
+```css
+/* Hover on mobile (touch devices long-press) */
+@custom-variant touch-hover {
+  @media (hover: none) {
+    &:active;
+  }
+}
+
+/* Group peer variants are built-in; this shows the pattern */
+@custom-variant data-active {
+  &[data-active="true"];
+}
+```
+
+Usage:
+```html
+<button class="data-active:bg-primary" data-active="true">Active</button>
+```