- Overview
- File Structure
- How Commands Work
- Available Commands
- Workflow Examples
- Understanding Component Decomposition
- Context Loading Strategy
- Tech Stack Reference
- Security & Quality Guardrails
- File Organization
- Common Issues & Solutions
- Tips & Best Practices
- Extending Commands
- Getting Help
- Summary
This project uses custom Claude commands to streamline the development workflow. Commands are organized into two main categories:
- Super Design - For creating UI/UX mockups and designs
- Implement - For transforming mockups into production Next.js code
.claude/
├── instructions.md # Claude Code CLI entry point (redirects to CLAUDE.md)
├── commands/
│ ├── implement/
│ │ ├── command.md # Implementation workflow
│ │ ├── tech-stack.md # Tech stack reference
│ │ ├── patterns.md # Code conventions
│ │ ├── security.md # Security checklist
│ │ └── component-guide.md # Component hierarchy guide
│ └── superdesign/
│ ├── command.md # Super Design slash commands
│ ├── style-taxonomy.json # 35+ design styles database
│ └── (other Super Design files)
├── context/
│ └── folder-structure.md # Project structure reference
└── (Claude instructions directory)
CLAUDE.md # Main instructions (desktop app + reference)
README-CLAUDE-COMMANDS.md # This file
What gets loaded automatically:
CLAUDE.md- Main instructions.claude/instructions.md- CLI instructions (if using Claude Code)
How to use commands:
Since the desktop app doesn't support native slash commands, use natural language triggers:
You: "implement hero_landing_1.html as a landing page"
Claude: [Reads CLAUDE.md → Sees "implement" trigger → Loads command.md → Executes workflow]
You: "create a design mockup for a landing page"
Claude: [Reads CLAUDE.md → Sees design trigger → Loads superdesign commands → Guides through process]
What gets loaded automatically:
.claude/instructions.md- Entry point (redirects to CLAUDE.md)- All commands in
.claude/commands/are available as slash commands
How to use commands:
# In your terminal
claude-code
# Use slash commands directly
/superdesign-start
/implement hero_landing_1.html --route=/landing --testThese commands help you create UI/UX mockups before implementation.
Full guided workflow with step-by-step confirmations
/superdesign-startProcess:
- Layout (ASCII wireframes) → [User approval]
- Theme (CSS with style matching) → [User approval]
- Animation (micro-syntax specs) → [User approval]
- Build (final HTML) → Complete
Use when: You want a complete, guided design process from scratch
Output:
- ASCII wireframes
- CSS theme file (
.superdesign/design_iterations/theme_N.css) - Animation specifications
- Final HTML (
.superdesign/design_iterations/design_name_N.html)
Generate ASCII wireframe layouts
/superdesign-layoutUse when: You need to visualize layout structure before styling
Output: Text-based ASCII wireframes showing component hierarchy
Generate CSS theme with design system
/superdesign-themeProcess:
- Reads
style-taxonomy.json(35+ design styles) - Matches your description to 2-3 relevant styles
- Generates complete CSS with OKLCH colors, fonts, spacing, shadows
- Saves to
.superdesign/design_iterations/theme_N.css
Use when: You need a complete design system/theme
Example:
You: "Create a theme that feels modern and tech-forward but also calm"
Claude: [Matches "tech-modern" + "calm-serene" styles → Generates theme]
Design animation specifications
/superdesign-animateOutput: Animation specs in micro-syntax format:
element: duration easing [properties] +delay
hero-title: 0.8s easeOut [opacity, translateY] +0.2s
Use when: You need animation strategy before implementation
Generate final production-ready HTML
/superdesign-buildOutput:
- Complete single-file HTML with all scripts, styles, and content
- References theme CSS from previous step
- Implements animations
- Includes Tailwind, Flowbite, Lucide icons
- Saved to
.superdesign/design_iterations/{design_name}_N.html
Use when: Ready to generate the final design file
Modify existing designs
/superdesign-iterateProcess:
- Reads existing design files
- Makes targeted changes
- Creates new iteration:
{original_name}_{iteration}.html
Use when: You want to modify/improve an existing design
Explore and match design styles
/superdesign-analyze-styleOutput:
- Analyzes your description
- Identifies 3-5 matching styles with reasoning
- Suggests top 2-3 styles to combine
- Flags conflicting styles to avoid
Use when: You want to explore style options before committing
These commands transform Super Design mockups into production Next.js code.
Transform mockup into production Next.js code
/implement [design-file] [--route=/path] [--type=page|component] [--test]Examples:
# Basic implementation
/implement hero_landing_1.html --route=/landing
# With tests
/implement dashboard_analytics.html --route=/dashboard/analytics --test
# Component only (no full page)
/implement button_variants.html --type=component
# Preview decomposition plan without generating
/implement pricing_page.html --previewProcess:
Phase 1: Analysis & Decomposition
- Reads Super Design HTML file from
.superdesign/design_iterations/ - Analyzes structure and identifies all UI patterns
- Maps to component hierarchy (primitives → blocks → layouts → containers)
- Checks for existing components (reuses, doesn't duplicate)
- Presents decomposition plan for approval
Phase 2: Generation
- Generates primitives (base UI elements)
- Generates blocks (composed patterns)
- Generates layouts (structure components)
- Generates containers (smart components with data)
- Generates page (orchestrates everything)
- Generates tests (if --test flag)
Phase 3: Validation
- Applies security guardrails
- Ensures accessibility (WCAG AAA)
- Optimizes performance
- Validates TypeScript types
Example Output:
📋 Component Decomposition Plan
Analyzing: hero_landing_1.html
Found Components:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRIMITIVES (3 new + 2 existing)
✓ Button → Use shadcn
✓ Input → Use shadcn
+ VideoPlayer.tsx → NEW
+ GradientBadge.tsx → NEW
+ IconCard.tsx → NEW
BLOCKS (8 new)
+ Navigation.tsx → NEW
+ HeroSection.tsx → NEW
+ FeatureCard.tsx → NEW
+ TestimonialCard.tsx → NEW
+ Carousel.tsx → NEW
+ PricingCard.tsx → NEW
+ FAQItem.tsx → NEW
+ NewsletterForm.tsx → NEW
LAYOUTS (2 new)
+ FeatureGrid.tsx → NEW
+ SectionWrapper.tsx → NEW
CONTAINERS (1 new)
+ LandingPageContainer.tsx → NEW
PAGE (1 new)
+ app/landing/page.tsx → NEW
TOTAL: 15 new files + 2 existing components
Proceed with generation? [y/n]
Flags:
--route=/path- Target route in app directory (e.g.,/landing,/dashboard/analytics)--type=page|component- Generate full page or reusable component (default:page)--test- Generate test files (Vitest + React Testing Library)--preview- Show decomposition plan without generating files--approve-all- Skip approval step, generate all files immediately
Step 1: Design Phase
# Desktop App:
You: "Create a modern landing page design with hero, features, and pricing"
# Claude Code CLI:
/superdesign-startClaude guides you through:
- Layout wireframes → You approve
- Theme generation → You approve
- Animation specs → You approve
- Final HTML build → Complete
Output: .superdesign/design_iterations/landing_modern_1.html
Step 2: Implementation Phase
# Desktop App:
You: "Implement landing_modern_1.html as a landing page with tests"
# Claude Code CLI:
/implement landing_modern_1.html --route=/landing --testClaude:
- Shows decomposition plan (15+ components)
- You approve
- Generates all files:
src/components/primitives/(3 files)src/components/blocks/(8 files)src/components/layouts/(2 files)src/components/containers/(1 file)src/app/landing/page.tsx(1 file)- Test files (if --test)
# Desktop App:
You: "Iterate on landing_modern_1.html - make the CTA more prominent and add social proof"
# Claude Code CLI:
/superdesign-iterateClaude:
- Reads existing
landing_modern_1.html - Makes targeted changes
- Creates
landing_modern_1_2.html(new iteration)
Then re-implement:
/implement landing_modern_1_2.html --route=/landing --approve-all# Create button variants mockup
/superdesign-build
# Implement as reusable component
/implement button_variants.html --type=componentOutput: Just the button component in src/components/primitives/
Design Phase:
/superdesign-start
# Create dashboard with charts, tables, filtersImplementation Phase:
/implement dashboard_analytics.html --route=/dashboard/analytics --test --previewClaude shows:
📋 Component Decomposition Plan
Found Components: 25 files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRIMITIVES (6)
+ MetricDisplay.tsx
+ Badge.tsx (custom variant)
...
BLOCKS (12)
+ DashboardHeader.tsx
+ KPICard.tsx
+ LineChart.tsx
+ BarChart.tsx
+ DataTable.tsx
+ FilterPanel.tsx
...
LAYOUTS (3)
+ DashboardLayout.tsx
+ ChartGrid.tsx
...
CONTAINERS (2)
+ AnalyticsView.tsx
+ ReportsContainer.tsx
SERVER (2)
+ server/services/analytics.service.ts
+ server/actions/analytics.actions.ts
Estimated generation time: 3-5 minutes
You approve → Claude generates all 25 files
When Claude analyzes a Super Design mockup, it categorizes components into layers:
Purpose: Single-responsibility UI atoms
Characteristics:
- Reusable base elements
- No business logic
- No data fetching
- Fully typed props
- Variants via class-variance-authority
Examples: Button, Input, Card, Badge, Avatar, Icon, Text, Link
Creation rule:
- Check shadcn/ui first
- Only create if not available or needs customization
Purpose: Composed UI patterns
Characteristics:
- Composed from primitives
- Can have local state (useState)
- Event handlers
- Form logic
- No API calls
Examples: SearchBar, UserCard, NotificationItem, FeatureCard, PricingCard, Carousel, FAQItem
Purpose: Page structure and positioning
Characteristics:
- CSS Grid / Flexbox structures
- Responsive breakpoints
- Slot-based composition
- No business logic
Examples: Grid, Flex, Stack, Container, Section, Sidebar, Header, Footer, DashboardLayout
Purpose: Smart components with data/logic
Characteristics:
- Data fetching (Server Components or hooks)
- Business logic
- Orchestrates blocks
- Error boundaries
- Loading states
Examples: UserProfileContainer, DashboardView, ShoppingCartContainer, MessageListContainer
Purpose: Route endpoints
Characteristics:
- Server Components by default
- Metadata for SEO
- Composes containers
- Minimal logic
Commands are designed to load context progressively to avoid bloating the context window.
CLAUDE.md- Core instructions (~500 tokens).claude/instructions.md- CLI redirect (~100 tokens)
.claude/commands/implement/command.md- When implementing.claude/commands/implement/tech-stack.md- When needed.claude/commands/implement/patterns.md- When needed.claude/commands/implement/security.md- When needed.claude/commands/implement/component-guide.md- When needed.claude/commands/superdesign/*- When designing
Benefits:
- ✅ Minimal initial context (~600 tokens)
- ✅ Context loaded only when needed
- ✅ More room for actual work
- ✅ Faster responses
Commands automatically apply these technologies:
- Framework: Next.js 15+ (App Router)
- Runtime: React 19+ (Server Components + Client Components)
- Language: TypeScript 5+ (strict mode)
- Styling: Tailwind CSS v4
- Backend: Hono (Node runtime)
- Database: PostgreSQL
- Build: Vite
- Components: shadcn/ui (Radix primitives)
- Icons: Lucide React
- Forms: React Hook Form + Zod
- Testing: Vitest + React Testing Library + Playwright
- Deployment: Docker via Dokploy
All /implement commands automatically apply:
- Authentication checks in Server Actions/API routes
- Input validation with Zod
- Environment variable protection
- Secure cookies (HttpOnly, Secure, SameSite)
- Security headers (CSP, X-Frame-Options, etc.)
- Rate limiting on sensitive routes
- SSRF prevention
- File upload validation
- Semantic HTML
- ARIA labels
- Keyboard navigation
- Focus management
- Skip links
- WCAG AAA compliance where possible
- Next.js Image optimization
- Code splitting (dynamic imports)
- Font optimization
- Server Components by default
- Lean bundle sizes
- TypeScript strict mode
- No
anywithout justification - Proper error handling
- Consistent naming conventions
- ESLint + Prettier compliance
Generated files follow this structure:
src/
├── app/
│ ├── (auth)/
│ │ └── signin/page.tsx
│ ├── (marketing)/
│ │ └── landing/page.tsx ← Generated by /implement
│ └── (dashboard)/
│ └── dashboard/page.tsx
├── components/
│ ├── primitives/ ← Generated primitives
│ │ ├── Button.tsx
│ │ └── VideoPlayer.tsx
│ ├── blocks/ ← Generated blocks
│ │ ├── HeroSection.tsx
│ │ └── FeatureCard.tsx
│ ├── layouts/ ← Generated layouts
│ │ └── FeatureGrid.tsx
│ └── containers/ ← Generated containers
│ └── LandingPageContainer.tsx
├── server/
│ ├── actions/ ← Generated server actions
│ │ └── newsletter.actions.ts
│ └── services/
│ └── analytics.service.ts
└── types/
└── landing.types.ts ← Generated types
In Desktop App:
- Slash commands don't work natively
- Use natural language: "implement hero_landing_1.html as a landing page"
In Claude Code CLI:
- Make sure you're in the project directory
- Verify
.claude/commands/folder exists - Check command file names match exactly
Solution: Use --preview flag first
/implement complex_design.html --previewReview the decomposition plan, then proceed if acceptable.
Claude automatically checks for existing components and reuses them. If you want to regenerate:
# Desktop App:
You: "Regenerate the HeroSection component from landing_modern_1.html"
# CLI:
/implement landing_modern_1.html --type=component --approve-allAfter generation, Claude lists required dependencies:
Dependencies Added:
• embla-carousel-react
• react-hook-form
• zod
Install: npm install embla-carousel-react react-hook-form zod
Run the install command before testing.
/implement complex_design.html --previewReview the decomposition plan before generating 20+ files.
# Instead of regenerating everything:
/superdesign-iterate
# Make small changes, then:
/implement design_v2.html --approve-all/implement design.html --route=/landing --testEasier than adding tests later.
Before running /implement, check if similar components already exist in your codebase. Claude will reuse them, but it's good to know what you have.
# For full pages:
/implement design.html --type=page
# For reusable components only:
/implement button_variants.html --type=componentWhen using Super Design theme generation:
You: "Create a theme that feels luxurious but not overly formal, with a touch of playfulness"
Claude: [Analyzes → Matches "luxury" + "playful" styles → Generates cohesive theme]
The style taxonomy has 35+ styles to mix and match intelligently.
Want to add more commands? Follow this pattern:
.claude/commands/your-command/command.md
### Your Command
**Trigger**: "your-command [args]"
**Process**:
1. Read `.claude/commands/your-command/command.md`
2. Follow the workflowYou: "your-command with arguments"
Claude: [Executes workflow]
You: "How do I implement a design mockup?"
Claude: [Explains /implement workflow]
# Commands are documented in their command.md files
# Just ask Claude to explain:
/implement --helpSuper Design Commands → Create mockups
/superdesign-start- Full guided workflow/superdesign-theme- Generate CSS themes/superdesign-build- Build HTML/superdesign-iterate- Modify designs
Implementation Commands → Transform to production code
/implement- Full implementation workflow- Generates 10-30+ files per mockup
- Applies security, accessibility, performance guardrails
- Creates proper component hierarchy
Key Philosophy:
- Progressive context loading (stay lean)
- Component decomposition (not monolithic)
- Security & accessibility by default
- Production-ready from the start
Ready to build? Start with /superdesign-start to create a mockup, then /implement to bring it to life!