AgentSkillsCN

wiggum-stack

Wiggum 项目组件库——在编写 UI 代码前,请务必阅读!

SKILL.md
--- frontmatter
name: wiggum-stack
description: Component library for Wiggum projects - READ BEFORE WRITING UI CODE
when_to_use: Building any UI, forms, layouts, or user-facing components

@wiggum/stack

Theme-agnostic React component library with 53 components built on Radix primitives.

RULES (Non-Negotiable)

  1. Always React - Never create standalone HTML files. Every UI is a React app.
  2. Always use stack components - No raw <button>, <input>, <div onClick>, etc.
  3. File organization:
    • Max 200 lines per file
    • Split pages into sections/ directory
    • One exported component per file
  4. Import from stack - Never recreate existing components

Component Mapping (CRITICAL)

Use @wiggum/stack components, not raw HTML elements.

Want ThisImport ThisExample
ButtonButton<Button onClick={fn}>Click</Button>
Text inputInput<Input placeholder="Email" />
Multi-lineTextarea<Textarea rows={4} />
DropdownSelect<Select>...</Select>
CheckboxCheckbox<Checkbox checked={val} />
ToggleSwitch<Switch checked={val} />
ModalDialog<Dialog>...</Dialog>
Side panelSheet<Sheet>...</Sheet>
TabsTabs<Tabs>...</Tabs>
TooltipTooltip<Tooltip>...</Tooltip>
LoadingSpinner<Spinner />

Required Skills

Before writing UI code, you MUST also follow:

  • react-best-practices - Performance patterns (waterfalls, bundle size)
  • web-design-guidelines - Accessibility & UX rules

Import Pattern

tsx
// Components
import { Button, Card, Input, Dialog } from '@wiggum/stack'

// Utilities
import { cn } from '@wiggum/stack'

// Hooks
import { useDebounce, useDisclosure } from '@wiggum/stack'

Project Structure (REQUIRED)

code
src/
├── main.tsx              # Entry point - DO NOT MODIFY
├── App.tsx               # Root composition only (no business logic)
├── sections/             # Page sections (Hero, Features, etc.)
│   ├── HeroSection.tsx
│   ├── FeaturesSection.tsx
│   └── CTASection.tsx
├── components/           # Project-specific components
└── pages/               # Route pages (if multi-page)

Available Components (53)

Layout

ComponentParts
CardCard, CardHeader, CardTitle, CardContent, CardFooter
DialogDialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle
SheetSheet, SheetTrigger, SheetContent, SheetHeader
TabsTabs, TabsList, TabsTrigger, TabsContent
AccordionAccordion, AccordionItem, AccordionTrigger, AccordionContent
CollapsibleCollapsible, CollapsibleTrigger, CollapsibleContent

Form Controls

ComponentVariants/Notes
Buttondefault, destructive, outline, secondary, ghost, link
InputText input with theme-aware styling
TextareaMulti-line text
SelectSelect, SelectTrigger, SelectValue, SelectContent, SelectItem
CheckboxRadix checkbox
RadioGroupRadioGroup, RadioGroupItem
SwitchToggle switch
SliderRange slider
LabelForm labels (always use with inputs)

Feedback

ComponentUse Case
BadgeStatus indicators
AlertAlertTitle, AlertDescription
AlertDialogConfirmation dialogs
ProgressProgress bar
SkeletonLoading placeholders
SpinnerLoading indicator
toast (Sonner)Toast notifications

Navigation

ComponentUse Case
DropdownMenuMenus, actions
ContextMenuRight-click menus
NavigationMenuMain navigation
BreadcrumbPath navigation
PaginationPage navigation

Data Display

ComponentUse Case
TableTableHeader, TableBody, TableRow, TableHead, TableCell
AvatarAvatarImage, AvatarFallback
TooltipHover information
HoverCardRich hover previews
PopoverClick-triggered overlays

Utility

ComponentPurpose
ScrollAreaCustom scrollbars
SeparatorVisual divider
AspectRatioMaintain ratios
KbdKeyboard shortcuts

Theming

Components are theme-agnostic - they consume CSS variables like var(--primary). Define your visual style in src/index.css. See the theming skill for:

  • Complete variable reference
  • Ready-to-use theme examples
  • Tips for choosing colors

Example: Landing Page Section

tsx
// src/sections/HeroSection.tsx
import { Button } from '@wiggum/stack'

export function HeroSection() {
  return (
    <section className="py-20 px-4 text-center">
      <h1 className="text-4xl font-bold mb-4">
        Build Faster with Wiggum
      </h1>
      <p className="text-muted-foreground mb-8 max-w-2xl mx-auto">
        A browser IDE designed for AI agents, not retrofitted for them.
      </p>
      <div className="flex gap-4 justify-center">
        <Button>Get Started</Button>
        <Button variant="outline">Learn More</Button>
      </div>
    </section>
  )
}

Example: Form with Validation

tsx
import { Button, Input, Label, Card, CardHeader, CardTitle, CardContent } from '@wiggum/stack'

export function LoginForm() {
  return (
    <Card className="w-[400px]">
      <CardHeader>
        <CardTitle>Sign In</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="space-y-2">
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="you@example.com" />
        </div>
        <div className="space-y-2">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" />
        </div>
        <Button className="w-full">Sign In</Button>
      </CardContent>
    </Card>
  )
}

Anti-Patterns (NEVER DO)

tsx
// ❌ BAD: Raw HTML elements
<button onClick={...}>Click</button>
<input type="text" />
<div onClick={...}>Clickable</div>

// ✅ GOOD: Stack components
<Button onClick={...}>Click</Button>
<Input type="text" />
<Button variant="ghost" onClick={...}>Clickable</Button>

// ❌ BAD: Inline styles
<div style={{ display: 'flex', gap: '1rem' }}>

// ✅ GOOD: Tailwind classes
<div className="flex gap-4">

// ❌ BAD: Everything in one file
// App.tsx with 500+ lines

// ✅ GOOD: Split into sections
// App.tsx imports HeroSection, FeaturesSection, etc.

Lucide React Icons

Icons come from lucide-react. Common valid icons:

CategoryValid Icons
TerminalTerminal, TerminalSquare
FilesFile, FileText, FileCode, FileCode2, Folder, FolderOpen
ArrowsArrowRight, ArrowLeft, ArrowUp, ArrowDown, ChevronRight, ChevronLeft, ChevronUp, ChevronDown
StatusCheck, CheckCircle, CheckCircle2, X, XCircle, AlertCircle, AlertTriangle, Info
UISun, Moon, Menu, Search, Settings, Plus, Minus, MoreHorizontal, MoreVertical
SocialGithub, Twitter, Linkedin, Mail, ExternalLink, Link
MediaPlay, Pause, Volume2, VolumeX, Image, Camera
ActionsEdit, Trash2, Copy, Download, Upload, Save, RefreshCw

Common Mistakes

WrongCorrect
Terminal2Terminal or TerminalSquare
CloseX
CheckmarkCheck
ErrorAlertCircle or XCircle
WarningAlertTriangle

If unsure, check https://lucide.dev/icons for the exact name.

External Resources

Fonts

Do NOT use @import url() in CSS - esbuild cannot process external URLs.

Wrong:

css
@import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');

Correct: Add to index.html <head>:

html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter&display=swap" rel="stylesheet">

Or use Tailwind's default font stack (no external fonts needed).

CDN Assets

Don't import external CSS/JS via @import. If needed, add <link> or <script> tags to index.html.