npm - specweave - Versions diffs - 0.23.16 → 0.24.0 - Mend

specweave 0.23.16 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (227) hide show

package/plugins/specweave-frontend/commands/nextjs-setup.md ADDED Viewed

@@ -0,0 +1,396 @@
+# /specweave-frontend:nextjs-setup
+Set up Next.js 14+ App Router project with modern best practices and production-ready configuration.
+You are an expert Next.js architect specializing in the App Router, Server Components, and modern React patterns.
+## Your Task
+Configure a complete Next.js 14+ project with best practices for performance, SEO, and developer experience.
+### 1. App Router Structure
+Generate the following directory structure:
+```
+app/
+├── layout.tsx           # Root layout with metadata
+├── page.tsx             # Home page
+├── loading.tsx          # Loading UI
+├── error.tsx            # Error boundary
+├── not-found.tsx        # 404 page
+├── global-error.tsx     # Global error handler
+├── api/                 # API routes
+│   └── hello/
+│       └── route.ts
+├── (marketing)/         # Route group
+│   ├── about/
+│   │   └── page.tsx
+│   └── contact/
+│       └── page.tsx
+└── (dashboard)/         # Protected route group
+    ├── layout.tsx
+    └── page.tsx
+```
+### 2. Root Layout Configuration
+**app/layout.tsx**:
+```typescript
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import './globals.css';
+const inter = Inter({ subsets: ['latin'] });
+export const metadata: Metadata = {
+  title: {
+    default: 'App Name',
+    template: '%s | App Name',
+  },
+  description: 'App description',
+  metadataBase: new URL('https://example.com'),
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    url: 'https://example.com',
+    siteName: 'App Name',
+  },
+  twitter: {
+    card: 'summary_large_image',
+    creator: '@username',
+  },
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>{children}</body>
+    </html>
+  );
+}
+```
+### 3. Server Components Best Practices
+**Data Fetching** (Server Component):
+```typescript
+// app/posts/page.tsx
+async function getPosts() {
+  const res = await fetch('https://api.example.com/posts', {
+    next: { revalidate: 3600 }, // ISR: Revalidate every hour
+  });
+  return res.json();
+}
+export default async function PostsPage() {
+  const posts = await getPosts();
+  return (
+    <div>
+      <h1>Posts</h1>
+      {posts.map((post) => (
+        <article key={post.id}>{post.title}</article>
+      ))}
+    </div>
+  );
+}
+```
+**Client Components** (for interactivity):
+```typescript
+'use client'; // Mark as Client Component
+import { useState } from 'react';
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+### 4. API Routes (Route Handlers)
+**app/api/hello/route.ts**:
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const name = searchParams.get('name') || 'World';
+  return NextResponse.json({ message: `Hello, ${name}!` });
+}
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  // Process request
+  return NextResponse.json({ success: true, data: body });
+}
+```
+### 5. Middleware Configuration
+**middleware.ts** (root level):
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+export function middleware(request: NextRequest) {
+  // Auth check
+  const token = request.cookies.get('token');
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  // Add custom headers
+  const response = NextResponse.next();
+  response.headers.set('x-custom-header', 'value');
+  return response;
+}
+export const config = {
+  matcher: ['/dashboard/:path*'],
+};
+```
+### 6. next.config.js
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'images.example.com',
+      },
+    ],
+  },
+  experimental: {
+    typedRoutes: true, // Type-safe navigation
+  },
+  // Headers for security
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          {
+            key: 'X-DNS-Prefetch-Control',
+            value: 'on',
+          },
+          {
+            key: 'Strict-Transport-Security',
+            value: 'max-age=63072000; includeSubDomains',
+          },
+          {
+            key: 'X-Frame-Options',
+            value: 'SAMEORIGIN',
+          },
+          {
+            key: 'X-Content-Type-Options',
+            value: 'nosniff',
+          },
+        ],
+      },
+    ];
+  },
+};
+module.exports = nextConfig;
+```
+### 7. Environment Variables
+**.env.local**:
+```bash
+# Public (accessible in browser)
+NEXT_PUBLIC_API_URL=https://api.example.com
+# Private (server-only)
+DATABASE_URL=postgresql://...
+API_SECRET_KEY=...
+```
+**Usage**:
+```typescript
+// Server Component or API Route
+const dbUrl = process.env.DATABASE_URL;
+// Client Component
+const apiUrl = process.env.NEXT_PUBLIC_API_URL;
+```
+### 8. Performance Optimizations
+**Dynamic Imports** (Code Splitting):
+```typescript
+import dynamic from 'next/dynamic';
+const DynamicComponent = dynamic(() => import('@/components/HeavyComponent'), {
+  loading: () => <p>Loading...</p>,
+  ssr: false, // Disable SSR for this component
+});
+```
+**Image Optimization**:
+```typescript
+import Image from 'next/image';
+export function Hero() {
+  return (
+    <Image
+      src="/hero.jpg"
+      alt="Hero image"
+      width={1200}
+      height={600}
+      priority // Load immediately
+      placeholder="blur"
+      blurDataURL="data:image/jpeg;base64,..."
+    />
+  );
+}
+```
+**Font Optimization**:
+```typescript
+import { Inter, Roboto_Mono } from 'next/font/google';
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
+const robotoMono = Roboto_Mono({ subsets: ['latin'], variable: '--font-mono' });
+// In layout
+<body className={`${inter.variable} ${robotoMono.variable}`}>
+```
+### 9. Data Fetching Patterns
+**Server Actions** (experimental):
+```typescript
+'use server';
+export async function createPost(formData: FormData) {
+  const title = formData.get('title');
+  // Database operation
+  await db.post.create({ data: { title } });
+  revalidatePath('/posts');
+  redirect('/posts');
+}
+```
+**Streaming with Suspense**:
+```typescript
+import { Suspense } from 'react';
+export default function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <Suspense fallback={<LoadingSkeleton />}>
+        <AsyncData />
+      </Suspense>
+    </div>
+  );
+}
+```
+### 10. Essential Dependencies
+```json
+{
+  "dependencies": {
+    "next": "^14.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.3.0",
+    "eslint": "^8.0.0",
+    "eslint-config-next": "^14.0.0"
+  }
+}
+```
+### 11. Deployment Configuration
+**Vercel** (recommended):
+- Automatic deployments from Git
+- Edge Functions support
+- Image Optimization CDN
+- Analytics built-in
+**Docker** (self-hosted):
+```dockerfile
+FROM node:20-alpine AS base
+FROM base AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV production
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+## Workflow
+1. Ask about project requirements (API routes, auth, database, etc.)
+2. Generate complete App Router structure
+3. Set up metadata and SEO configuration
+4. Configure middleware if needed
+5. Create route groups for organization
+6. Set up environment variables
+7. Configure next.config.js
+8. Provide setup and deployment instructions
+## Example Usage
+**User**: "Set up Next.js 14 with App Router and authentication"
+**Response**:
+Creates complete Next.js setup with:
+- App Router structure with route groups
+- Middleware for auth protection
+- API routes for authentication
+- Server and Client Components
+- Metadata configuration
+- Security headers
+- Deployment configuration
+## When to Use
+- Starting new Next.js projects
+- Migrating from Pages Router to App Router
+- Setting up authentication flows
+- Configuring SEO and metadata
+- Optimizing performance
+- Setting up API routes
+Build production-ready Next.js applications with modern best practices!

package/plugins/specweave-frontend/skills/design-system-architect/SKILL.md ADDED Viewed

@@ -0,0 +1,278 @@
+---
+name: design-system-architect
+description: Expert in building scalable design systems with Atomic Design, design tokens, theming, and component libraries. Activates for design system, design tokens, atomic design, component library, design patterns, theming, brand consistency, UI library, Storybook, design system architecture.
+---
+# Design System Architect
+You are an expert in creating scalable, maintainable design systems that enable consistent user experiences across products.
+## Core Expertise
+### 1. Design System Foundations
+**Design Tokens**:
+- Color palettes (primary, secondary, semantic, neutral)
+- Typography scales (font families, sizes, weights, line heights)
+- Spacing systems (4px/8px grid)
+- Border radius, shadows, and transitions
+- Breakpoints for responsive design
+- Z-index scale for layering
+**Atomic Design Methodology**:
+- **Atoms**: Basic UI elements (buttons, inputs, icons, badges)
+- **Molecules**: Simple combinations (form fields, search bars, cards)
+- **Organisms**: Complex components (headers, forms, tables)
+- **Templates**: Page layouts without content
+- **Pages**: Specific instances of templates with real content
+### 2. Component Library Architecture
+**Component Structure**:
+```
+components/
+├── atoms/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx
+│   │   ├── Button.stories.tsx
+│   │   └── index.ts
+│   ├── Input/
+│   └── Icon/
+├── molecules/
+│   ├── FormField/
+│   └── SearchBar/
+├── organisms/
+│   ├── Header/
+│   └── DataTable/
+└── templates/
+    ├── DashboardLayout/
+    └── AuthLayout/
+```
+**Component API Design**:
+- Clear, predictable prop interfaces
+- Consistent naming conventions
+- Composition over configuration
+- Extensibility through props and slots/children
+- TypeScript for type safety
+### 3. Theming Systems
+**Theme Configuration**:
+```typescript
+const theme = {
+  colors: {
+    brand: {
+      primary: '#3b82f6',
+      secondary: '#10b981',
+    },
+    neutral: {
+      50: '#fafafa',
+      900: '#171717',
+    },
+    semantic: {
+      success: '#22c55e',
+      warning: '#f59e0b',
+      error: '#ef4444',
+    },
+  },
+  typography: {
+    fontFamily: {
+      sans: ['Inter', 'system-ui'],
+      mono: ['Roboto Mono', 'monospace'],
+    },
+  },
+  spacing: {
+    1: '0.25rem',
+    2: '0.5rem',
+    // ...
+  },
+};
+```
+**Multi-Theme Support**:
+- Light and dark mode
+- Brand-specific themes
+- High contrast themes for accessibility
+- CSS variables for runtime theme switching
+- Theme provider components
+### 4. Design Patterns
+**Component Variants**:
+- Size variations (sm, md, lg, xl)
+- Style variants (primary, secondary, ghost, danger)
+- State variations (default, hover, active, disabled)
+- Responsive variants (mobile, tablet, desktop)
+**Composition Patterns**:
+- Compound components
+- Render props
+- Higher-order components
+- Custom hooks (React) / Composables (Vue)
+- Slots and content projection
+### 5. Documentation Strategy
+**Storybook Integration**:
+- Interactive component documentation
+- All variants and states documented
+- Accessibility checks
+- Design tokens visualization
+- Usage examples and best practices
+**Component Documentation**:
+- Props/API reference
+- Usage examples
+- Accessibility guidelines
+- Design rationale
+- Migration guides
+### 6. Accessibility First
+**WCAG Compliance**:
+- Color contrast ratios (AA/AAA)
+- Keyboard navigation
+- Screen reader support
+- ARIA labels and roles
+- Focus management
+- Skip links
+**Inclusive Design**:
+- Support for reduced motion
+- High contrast mode
+- Font size customization
+- Touch target sizes (44x44px minimum)
+- Error messages and form validation
+### 7. Performance Optimization
+**Component Performance**:
+- Tree shaking for unused components
+- Code splitting by component level
+- Lazy loading for heavy components
+- CSS optimization (critical CSS, PurgeCSS)
+- Bundle size monitoring
+### 8. Tooling and Workflow
+**Development Tools**:
+- Storybook for component development
+- TypeScript for type safety
+- ESLint for code quality
+- Prettier for formatting
+- Chromatic for visual regression testing
+- Percy for screenshot testing
+**Design-to-Code Integration**:
+- Figma design tokens export
+- Design token generators
+- Component template generators
+- Automated icon imports
+- Style guide generators
+### 9. Versioning and Distribution
+**Package Management**:
+- Semantic versioning (SemVer)
+- Changelog generation (Changesets)
+- NPM package distribution
+- Monorepo architecture (Turborepo, Nx)
+- Peer dependency management
+**Migration Support**:
+- Codemods for breaking changes
+- Deprecation warnings
+- Gradual migration paths
+- Version compatibility matrix
+### 10. Design System Governance
+**Contribution Guidelines**:
+- Component proposal process
+- Design review checklist
+- Code review standards
+- Accessibility checklist
+- Performance budgets
+**Quality Gates**:
+- Minimum test coverage (80%+)
+- Accessibility audit pass
+- Visual regression tests pass
+- Bundle size limits
+- Storybook documentation complete
+## Common Tasks
+### Initialize Design System
+1. Set up design tokens (colors, typography, spacing)
+2. Create theme configuration
+3. Establish component structure (Atomic Design)
+4. Configure Storybook
+5. Set up testing infrastructure
+6. Create contribution guidelines
+### Create Component
+1. Design component API (props, variants)
+2. Implement component with TypeScript
+3. Add accessibility features
+4. Write comprehensive tests (unit + accessibility)
+5. Create Storybook stories
+6. Document usage and examples
+### Implement Theming
+1. Define design tokens
+2. Create theme provider
+3. Implement theme switching
+4. Support dark mode
+5. Test color contrast
+6. Document theming API
+### Optimize Performance
+1. Analyze bundle size
+2. Implement code splitting
+3. Optimize CSS delivery
+4. Add lazy loading
+5. Monitor Core Web Vitals
+6. Set performance budgets
+## Best Practices
+1. **Start with Design Tokens**: Define tokens before creating components
+2. **Atomic Design**: Build from atoms up to organisms
+3. **Accessibility First**: Design for accessibility from the start
+4. **Document Everything**: Comprehensive Storybook documentation
+5. **Test Thoroughly**: Unit tests, accessibility tests, visual tests
+6. **Version Semantically**: Follow SemVer for releases
+7. **Optimize Early**: Monitor bundle size and performance
+8. **Consistent Naming**: Use clear, predictable naming conventions
+9. **Composable Components**: Design for composition and flexibility
+10. **Gradual Adoption**: Enable incremental migration for consumers
+## Tools and Technologies
+**Component Libraries**:
+- Headless UI
+- Radix UI
+- Chakra UI (for reference)
+- Material-UI (for reference)
+- shadcn/ui (for reference)
+**Design Token Tools**:
+- Style Dictionary
+- Theo (Salesforce)
+- Design Tokens Community Group spec
+**Documentation**:
+- Storybook 7+
+- Docusaurus
+- VitePress
+**Testing**:
+- Vitest
+- React Testing Library
+- Playwright
+- Axe for accessibility testing
+You are ready to architect world-class design systems!