agent-skill-kit 3.9.135

package/.agent/skills/tailwind-kit/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: tailwind-kit
+description: >-
+  Tailwind CSS v4 utility classes, @theme configuration, responsive patterns, and v3→v4 migration.
+  Use when styling with Tailwind, configuring themes, or writing utility-first CSS.
+  NOT for design decisions (use design-system) or vanilla CSS projects.
+category: frontend-styling
+triggers: ["Tailwind", "CSS", "styling", "utility classes", "oklch"]
+coordinates_with: ["frontend-specialist", "nextjs-pro", "design-system"]
+success_metrics: ["Component Consistency", "DOM Optimization", "Responsive Robustness"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Tailwind Kit — Tailwind CSS v4 Patterns
+
+> CSS-first `@theme`. OKLCH colors. Container queries. Mobile-first responsive.
+
+---
+
+## 5 Must-Ask Questions (Socratic Gate)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Project Stack? | Next.js / React+Vite / Angular / Vanilla HTML |
+| 2 | Tailwind Version? | v4 / Migrating from v3 |
+| 3 | Design System Context? | Strict / Loose / Arbitrary Values Allowed |
+| 4 | Responsive Need? | Mobile-first / Desktop-heavy |
+| 5 | Specific Component? | Button / Card / Input / Generic Layout |
+
+---
+
+## When to Use
+
+| Situation | Approach |
+|-----------|----------|
+| Styling components | Use utility classes |
+| Theme setup | CSS-first `@theme` |
+| Dark mode | Use `dark:` prefix |
+| Responsive | Mobile-first breakpoints |
+| Migrating v3 → v4 | Check migration table |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Tailwind class recommendations | Design theory (→ design-system) |
+| @theme configuration (OKLCH) | Next.js integration (→ nextjs-pro) |
+| v3 → v4 migration paths | AI design (→ studio) |
+| Layout + responsive patterns | CSS processing pipeline |
+
+**Expert decision skill:** Produces class recommendations. Does not write files.
+
+---
+
+## v3 → v4 Migration (3 Breaking Changes)
+
+| v3 (Legacy) | v4 (Current) |
+|-------------|-------------|
+| `tailwind.config.js` | CSS-based `@theme` |
+| PostCSS plugin | Oxide engine (10× faster) |
+| JIT mode | Native, always-on |
+
+---
+
+## Core Patterns (4 — Fixed)
+
+### Theme (CSS-First)
+```css
+@theme {
+  --color-primary: oklch(0.7 0.15 250);
+  --color-surface: oklch(0.98 0 0);
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
+```
+
+### Responsive vs Container
+| Prefix | Responds To |
+|--------|-------------|
+| `md:` | Viewport width |
+| `@md:` | Parent container width |
+
+### Dark Mode
+```html
+<div class="bg-white dark:bg-zinc-900 text-zinc-900 dark:text-white">
+```
+
+---
+
+## Layout Patterns (4 — Deterministic)
+
+| Pattern | Classes |
+|---------|---------|
+| Center both | `flex items-center justify-center` |
+| Vertical stack | `flex flex-col gap-4` |
+| Space between | `flex justify-between items-center` |
+| Auto-fit grid | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
+
+---
+
+## OKLCH Color System (3 Layers)
+
+| Layer | Example | Purpose |
+|-------|---------|---------|
+| Primitive | `--blue-500` | Raw values |
+| Semantic | `--color-primary` | Purpose-based |
+| Component | `--button-bg` | Component-specific |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_UNKNOWN_LAYOUT` | Yes | Layout type not one of 4 |
+| `ERR_UNKNOWN_COLOR_LAYER` | Yes | Color layer not one of 3 |
+| `ERR_VERSION_MISMATCH` | Yes | Mixing v3 config with v4 |
+
+**Zero internal retries.** Same use case = same class recommendation.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Arbitrary values everywhere | Use design system scale |
+| `!important` | Fix specificity |
+| Inline `style=` | Use utilities |
+| Heavy `@apply` | Prefer components |
+| Mix v3 config with v4 | Migrate fully |
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `css_class_recommended` | `{"component": "button", "pattern": "variants"}` | `INFO` |
+| `layout_pattern_generated` | `{"type": "auto-grid", "responsive": true}` | `INFO` |
+| `v3_v4_migration_started` | `{"legacy_theme_keys": 4}` | `INFO` |
+
+All tailwind-kit outputs MUST emit `css_class_recommended` and `layout_pattern_generated` events when applicable.
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [v4-config.md](rules/v4-config.md) | Full v4 configuration | New project setup |
+| [responsive.md](rules/responsive.md) | Breakpoints + container queries | Responsive design |
+| [components.md](rules/components.md) | Component extraction | Component patterns |
+| [engineering-spec.md](rules/engineering-spec.md) | Full spec | Architecture review |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `design-system` | Skill | Design patterns |
+| `nextjs-pro` | Skill | Next.js styling |
+| `studio` | Skill | AI design |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/tailwind-kit/rules/_sections.md

@@ -0,0 +1,20 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. General (general)
+
+**Impact:** MEDIUM  
+**Description:** General patterns and best practices.
+
+## 2. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/tailwind-kit/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/tailwind-kit/rules/components.md

@@ -0,0 +1,232 @@
+---
+name: components
+description: Tailwind CSS v4 component patterns — cva variants, cn() utility, Button/Card/Input extraction, class ordering, TypeScript props
+title: "Component Extraction"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: components
+---
+
+# Component Extraction
+
+> React components first. @apply only for truly static patterns. Use cva for variants.
+
+---
+
+## When to Extract
+
+| Signal | Action |
+|--------|--------|
+| Same class combo 3+ times | Extract component |
+| Complex state variants | Use `cva` for variant map |
+| Design system element | Extract + document + type |
+
+---
+
+## cn() Utility (Essential)
+
+```typescript
+// lib/utils.ts — merge Tailwind classes safely
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+// Usage — last class wins, no conflicts
+cn('px-4 py-2', 'px-6')        // → 'py-2 px-6'
+cn('text-red-500', false && 'hidden')  // → 'text-red-500'
+```
+
+---
+
+## Button (cva + TypeScript)
+
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+  // Base classes (always applied)
+  'inline-flex items-center justify-center rounded-md font-medium transition-colors duration-150 focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary:   'bg-primary text-white hover:bg-primary/90',
+        secondary: 'bg-surface border border-zinc-200 hover:bg-zinc-50',
+        ghost:     'hover:bg-zinc-100 dark:hover:bg-zinc-800',
+        danger:    'bg-red-600 text-white hover:bg-red-700',
+      },
+      size: {
+        sm: 'h-8 px-3 text-sm',
+        md: 'h-10 px-4 text-sm',
+        lg: 'h-12 px-6 text-base',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      size: 'md',
+    },
+  }
+)
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button className={cn(buttonVariants({ variant, size }), className)} {...props} />
+  )
+}
+
+// Usage
+<Button variant="primary" size="lg">Save</Button>
+<Button variant="ghost">Cancel</Button>
+<Button variant="danger" disabled>Delete</Button>
+```
+
+---
+
+## Card
+
+```tsx
+import { cn } from '@/lib/utils'
+
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+export function Card({ className, ...props }: CardProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-xl border border-zinc-200 bg-white shadow-sm',
+        'dark:border-zinc-800 dark:bg-zinc-950',
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+export function CardHeader({ className, ...props }: CardProps) {
+  return <div className={cn('p-6 pb-0', className)} {...props} />
+}
+
+export function CardContent({ className, ...props }: CardProps) {
+  return <div className={cn('p-6', className)} {...props} />
+}
+
+// Usage
+<Card>
+  <CardHeader><h3>Title</h3></CardHeader>
+  <CardContent><p>Content</p></CardContent>
+</Card>
+```
+
+---
+
+## Input
+
+```tsx
+import { cn } from '@/lib/utils'
+
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  label?: string
+  error?: string
+}
+
+export function Input({ label, error, className, id, ...props }: InputProps) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      {label && (
+        <label htmlFor={id} className="text-sm font-medium text-zinc-700 dark:text-zinc-300">
+          {label}
+        </label>
+      )}
+      <input
+        id={id}
+        className={cn(
+          'h-10 w-full rounded-md border px-3 text-sm',
+          'bg-white dark:bg-zinc-950',
+          'border-zinc-200 dark:border-zinc-800',
+          'placeholder:text-zinc-400',
+          'focus:outline-none focus:ring-2 focus:ring-primary/50',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          error && 'border-red-500 focus:ring-red-500/50',
+          className,
+        )}
+        {...props}
+      />
+      {error && <p className="text-sm text-red-500">{error}</p>}
+    </div>
+  )
+}
+
+// Usage
+<Input label="Email" type="email" placeholder="you@example.com" />
+<Input label="Password" error="Required" />
+```
+
+---
+
+## @apply (Static Only — Use Sparingly)
+
+```css
+/* Only for patterns that never need props or state */
+.prose-content h2 {
+  @apply text-2xl font-bold mt-8 mb-4 text-zinc-900 dark:text-white;
+}
+
+.prose-content p {
+  @apply text-base leading-relaxed text-zinc-600 dark:text-zinc-400;
+}
+```
+
+> ⚠️ **Avoid heavy @apply.** If it needs variants, props, or state → use React component + cva.
+
+---
+
+## Class Ordering Convention
+
+```html
+<div class="
+  /* 1. Layout */     flex items-center justify-between
+  /* 2. Sizing */     w-full h-12
+  /* 3. Spacing */    px-4 py-2 gap-4
+  /* 4. Typography */ text-sm font-medium
+  /* 5. Colors */     bg-white text-zinc-900
+  /* 6. Borders */    border border-zinc-200 rounded-lg
+  /* 7. Effects */    shadow-sm
+  /* 8. Transitions */transition-all duration-200
+  /* 9. States */     hover:bg-zinc-50 focus:ring-2
+  /* 10. Dark */      dark:bg-zinc-900 dark:text-white
+  /* 11. Responsive */md:flex-row md:text-base
+">
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| String concat for variants | `cva` + variant map |
+| `className={condition ? 'a' : 'b'}` | `cn()` with conditional |
+| Heavy @apply for everything | React component + cva |
+| Skip TypeScript on props | Type all component props |
+| Duplicate class sets | Extract shared component |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [responsive.md](responsive.md) | Responsive patterns |
+| [v4-config.md](v4-config.md) | @theme setup |
+| [SKILL.md](../SKILL.md) | Patterns overview |
+
+---
+
+⚡ PikaKit v3.9.134