create-win-project 1.3.0 → 2.0.0

package/playbooks/styling/css-modules-extensions.md

@@ -1,267 +0,0 @@
-# Styling: CSS Modules — Extensions
-
-Extends your existing CSS Modules playbook with missing patterns.
-
----
-
-## Dark Mode with CSS Variables
-```css
-/* styles/tokens.css — single source of truth */
-:root {
-  /* Colors */
-  --color-background: #ffffff;
-  --color-foreground: #0a0a0a;
-  --color-primary: #1a1a2e;
-  --color-primary-foreground: #f0f0f0;
-  --color-muted: #f5f5f5;
-  --color-muted-foreground: #737373;
-  --color-border: #e5e5e5;
-  --color-error: #dc2626;
-  --color-success: #16a34a;
-
-  /* Typography */
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-
-  /* Spacing */
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-6: 1.5rem;
-  --space-8: 2rem;
-
-  /* Radius */
-  --radius-sm: 0.25rem;
-  --radius-md: 0.375rem;
-  --radius-lg: 0.5rem;
-
-  /* Transitions */
-  --transition-fast: 100ms ease;
-  --transition-base: 200ms ease;
-  --transition-slow: 500ms ease;
-}
-
-[data-theme="dark"] {
-  --color-background: #0a0a0a;
-  --color-foreground: #f0f0f0;
-  --color-primary: #e0e0f0;
-  --color-primary-foreground: #1a1a2e;
-  --color-muted: #1a1a1a;
-  --color-muted-foreground: #a3a3a3;
-  --color-border: #262626;
-}
-```
-
-```typescript
-// app/providers.tsx — apply theme to root
-import { useEffect, useState } from 'react'
-
-export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<'light' | 'dark'>('light')
-
-  useEffect(() => {
-    document.documentElement.setAttribute('data-theme', theme)
-  }, [theme])
-
-  return <>{children}</>
-}
-```
-
----
-
-## Component Pattern with Tokens
-```css
-/* components/ui/Button/Button.module.css */
-.button {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: var(--space-2) var(--space-4);
-  font-size: var(--font-size-base);
-  border-radius: var(--radius-md);
-  transition: background-color var(--transition-base);
-  cursor: pointer;
-}
-
-.primary {
-  background-color: var(--color-primary);
-  color: var(--color-primary-foreground);
-}
-
-.primary:hover {
-  opacity: 0.9;
-}
-
-.ghost {
-  background-color: transparent;
-  color: var(--color-foreground);
-  border: 1px solid var(--color-border);
-}
-
-.ghost:hover {
-  background-color: var(--color-muted);
-}
-
-.disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-  pointer-events: none;
-}
-```
-
----
-
-## clsx for Class Composition
-```typescript
-// Install: npm install clsx
-import clsx from 'clsx'
-import styles from './Button.module.css'
-
-export function Button({ variant = 'primary', disabled, className }: ButtonProps) {
-  return (
-    <button
-      className={clsx(
-        styles.button,
-        styles[variant],
-        disabled && styles.disabled,
-        className   // allow external class override
-      )}
-      disabled={disabled}
-    >
-      {children}
-    </button>
-  )
-}
-```
-
----
-
-## Responsive in Module File
-```css
-/* UserCard.module.css */
-.card {
-  display: flex;
-  flex-direction: column;
-  padding: var(--space-4);
-}
-
-/* Responsive stays in the component's own module file */
-@media (min-width: 768px) {
-  .card {
-    flex-direction: row;
-    padding: var(--space-6);
-  }
-}
-
-@media (min-width: 1024px) {
-  .card {
-    max-width: 800px;
-  }
-}
-```
-
----
-
-## Animation
-```css
-/* Define @keyframes in component module if component-specific */
-/* Define in global.css if reused across components */
-
-/* Component-specific */
-@keyframes fadeIn {
-  from { opacity: 0; transform: translateY(-8px); }
-  to   { opacity: 1; transform: translateY(0); }
-}
-
-.dropdown {
-  animation: fadeIn var(--transition-base);
-}
-
-/* Reused animation → globals.css */
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-```
-
----
-
-## Never Mix Tailwind + CSS Modules on Same Element
-```typescript
-// ❌ mixing both on same element
-<div className={clsx(styles.card, 'flex items-center')} />
-
-// ✅ pick one strategy per project (defined at init)
-// CSS Modules project → all styling via modules
-<div className={styles.card} />
-
-// Tailwind project → all styling via Tailwind
-<div className="flex items-center gap-4 rounded-md" />
-```
-
----
-
-## Global Styles Structure
-```
-src/styles/
-  tokens.css      → CSS variables (colors, space, type, radius)
-  globals.css     → reset, base elements, @import tokens
-  animations.css  → reusable @keyframes (optional)
-```
-
-```css
-/* globals.css */
-@import './tokens.css';
-
-*, *::before, *::after {
-  box-sizing: border-box;
-  margin: 0;
-  padding: 0;
-}
-
-body {
-  background-color: var(--color-background);
-  color: var(--color-foreground);
-  font-size: var(--font-size-base);
-  line-height: 1.5;
-}
-
-a {
-  color: inherit;
-  text-decoration: none;
-}
-```
-
----
-
-## Agent Quick Reference (Extended)
-```
-Dark mode?
-  → [data-theme="dark"] on html element
-  → CSS variables in tokens.css, overrides in [data-theme="dark"]
-  → Toggle via data-theme attribute, not class swap
-
-Conditional classes?
-  → clsx(styles.base, condition && styles.variant)
-  → Never string template literals
-
-Responsive?
-  → @media queries in component's own .module.css
-  → Mobile styles first (no query), then @media (min-width: ...)
-
-Animation?
-  → Component-specific: @keyframes in component module
-  → Reused: @keyframes in globals.css or animations.css
-  → Duration: always use --transition-* tokens
-
-New token needed?
-  → Add to tokens.css under correct section
-  → Never hardcode values in component modules
-
-External class override allowed?
-  → Accept className prop, pass to clsx as last arg
-  → Allows parent to extend without modifying component
-```

package/playbooks/styling/css-modules.manifest.json

@@ -1,11 +0,0 @@
-{
-  "id": "css-modules",
-  "kind": "styling",
-  "label": "CSS Modules",
-  "file": "styling/css-modules-extensions.md",
-  "required": false,
-  "folders": [],
-  "concerns": [
-    { "id": "styling", "required": true, "sections": ["Dark Mode with CSS Variables", "Responsive in Module File"] }
-  ]
-}

package/playbooks/universal/coding-rules.manifest.json

@@ -1,12 +0,0 @@
-{
-  "id": "coding-rules",
-  "kind": "universal",
-  "label": "Coding Rules",
-  "required": true,
-  "folders": [],
-  "devDeps": ["prettier"],
-  "concerns": [
-    { "id": "naming", "required": true, "sections": ["Naming", "Functions", "Imports", "Constants"] },
-    { "id": "no-debug", "required": true, "sections": ["No Debug Code in Commits", "One Thing Per File"] }
-  ]
-}

package/playbooks/universal/coding-rules.md

@@ -1,281 +0,0 @@
-# Coding Rules (Universal)
-
-Applies to every project regardless of stack.
-
----
-
-## Core Principle
-```
-simple + explicit + consistent
-over
-complex + abstract + theoretically pure
-```
-
-Complexity must earn abstraction. Start simple. Add layers only when justified.
-
----
-
-## Naming
-
-### Files
-```
-React components:   PascalCase    UserCard.tsx
-Hooks:              camelCase     useUserData.ts
-Utilities:          camelCase     formatDate.ts
-Constants:          camelCase     apiEndpoints.ts
-Types:              camelCase     userTypes.ts
-CSS Modules:        PascalCase    UserCard.module.css
-Java classes:       PascalCase    UserService.java
-SQL migrations:     snake_case    V1__create_users_table.sql
-```
-
-### Variables and Functions
-```
-Variables:          camelCase     userName, isLoading, hasError
-Functions:          camelCase     getUser(), createOrder(), formatDate()
-Constants:          SCREAMING     MAX_RETRIES, API_BASE_URL
-React components:   PascalCase    UserCard, LoginForm
-Types/Interfaces:   PascalCase    UserResponse, ApiError
-Enums:              PascalCase    UserRole, OrderStatus
-```
-
-### Name for what it does, not what it is
-```
-❌ getData(), handleThing(), doStuff(), temp, x
-✅ getUserById(), handleLoginSubmit(), formatCurrency()
-```
-
-### Boolean naming
-```
-❌ user, loading, error
-✅ isLoading, hasError, isAuthenticated, canEdit
-```
-
----
-
-## Functions
-- One responsibility per function
-- Max 3 parameters — if more, use an options object
-- Return early to avoid deep nesting
-
-```typescript
-// ❌
-function processUser(user, role, permissions, sendEmail, notify) { ... }
-
-// ✅
-function processUser(user: User, options: ProcessUserOptions) { ... }
-
-// ❌ deep nesting
-function getUser(id) {
-  if (id) {
-    if (isValid(id)) {
-      // logic
-    }
-  }
-}
-
-// ✅ early return
-function getUser(id) {
-  if (!id) return null
-  if (!isValid(id)) return null
-  // logic
-}
-```
-
----
-
-## Imports
-
-### Frontend
-- Always use absolute imports with `@/` prefix
-- Never use relative `../../` imports
-- Barrel exports (`index.ts`) for public API of a feature only
-
-```typescript
-// ❌
-import { UserCard } from '../../../components/ui/UserCard'
-
-// ✅
-import { UserCard } from '@/components/ui/UserCard'
-```
-
-### Import Order (enforced by ESLint)
-```
-1. External libraries
-2. Internal absolute (@/)
-3. Types
-4. Styles / assets
-```
-
----
-
-## Constants
-- No magic numbers or strings in logic
-- All constants in `src/constants/index.ts` or feature-level constants file
-
-```typescript
-// ❌
-if (role === 'ADMIN') { ... }
-setTimeout(fn, 900000)
-
-// ✅
-import { ROLES, TOKEN_EXPIRY } from '@/constants'
-if (role === ROLES.ADMIN) { ... }
-setTimeout(fn, TOKEN_EXPIRY.ACCESS)
-```
-
----
-
-## Async / Error Handling
-
-### Frontend
-- Always async/await — never `.then()` chains
-- Always handle errors at the hook level, not component level
-- Never swallow errors silently
-
-```typescript
-// ❌
-fetchUser().then(data => setUser(data)).catch(e => console.log(e))
-
-// ✅
-try {
-  const user = await fetchUser()
-  setUser(user)
-} catch (error) {
-  logger.error('fetchUser failed:', error)
-  throw error
-}
-```
-
-### Backend
-- Always throw `AppException` — never raw `RuntimeException`
-- Never expose stack traces in API responses
-- Always catch at the `GlobalExceptionHandler` level
-
-```java
-// ❌
-throw new RuntimeException("User not found");
-
-// ✅
-throw new AppException("USER_NOT_FOUND", HttpStatus.NOT_FOUND);
-```
-
----
-
-## Logging
-- NEVER use `console.log` directly
-- Always use `lib/logger.ts` on frontend
-- Always use SLF4J logger on backend
-
-```typescript
-// ❌
-console.log('user:', user)
-console.error('error:', error)
-
-// ✅
-import { logger } from '@/lib/logger'
-logger.info('user fetched:', user)
-logger.error('fetch failed:', error)
-```
-
-```java
-// ❌
-System.out.println("user: " + user);
-
-// ✅
-private static final Logger log = LoggerFactory.getLogger(UserService.class);
-log.info("user fetched: {}", userId);
-log.error("fetch failed for userId: {}", userId, e);
-```
-
----
-
-## Comments
-- Comment WHY, not WHAT
-- Code should be readable enough to not need WHAT comments
-- Remove all debug/TODO comments before committing
-
-```typescript
-// ❌ explains what (obvious from code)
-// increment counter
-count++
-
-// ✅ explains why (not obvious from code)
-// Retry once — server returns 503 on cold start for ~200ms
-await retry(fetchUser, { times: 1, delay: 300 })
-```
-
----
-
-## No Debug Code in Commits
-```
-❌ console.log
-❌ debugger
-❌ TODO comments
-❌ hardcoded test values
-❌ commented-out code blocks
-```
-
-ESLint and Husky enforce this — build fails if present.
-
----
-
-## One Thing Per File
-```
-❌ UserCardAndForm.tsx — two components in one file
-❌ userUtils.ts — 30 unrelated utility functions
-
-✅ UserCard.tsx
-✅ UserForm.tsx
-✅ formatDate.ts
-✅ formatCurrency.ts
-```
-
-Exception: small helper types or constants directly related to the file.
-
----
-
-## Exports
-
-### Frontend
-- Named exports everywhere except page/route components
-- Page components use default export (Next.js / React Router requirement)
-
-```typescript
-// ❌ default export for reusable components
-export default function UserCard() { ... }
-
-// ✅ named export
-export function UserCard() { ... }
-
-// ✅ default export for pages only
-export default function UserPage() { ... }
-```
-
-### Backend
-- Spring-managed beans: `@Service`, `@Repository`, `@RestController` — Spring handles export
-- Utility classes: `public static` methods
-
----
-
-## Agent Rules
-```
-Before writing any code:
-  1. Check if the functionality already exists
-  2. Check which layer owns this responsibility
-  3. Choose the simplest correct implementation
-  4. Follow existing patterns in the codebase — don't introduce new ones
-
-Before creating a new file:
-  1. Check if an existing file should be extended instead
-  2. Follow the selected stack's structure playbook and current feature ownership
-
-Before adding a dependency:
-  1. Check if existing tools already solve it
-  2. Prefer what the playbook recommends over personal preference
-
-Naming:
-  1. Name things for what they do
-  2. Booleans start with is/has/can
-  3. No abbreviations unless universally understood (id, url, dto)
-```

package/playbooks/universal/git-conventions.manifest.json

@@ -1,10 +0,0 @@
-{
-  "id": "git-conventions",
-  "kind": "universal",
-  "label": "Git Conventions",
-  "required": true,
-  "folders": [],
-  "concerns": [
-    { "id": "git", "required": true, "sections": ["Branch Structure", "Commit Convention", "Daily Workflow"] }
-  ]
-}