create-win-project 1.3.0

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

@@ -0,0 +1,267 @@
+# 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

@@ -0,0 +1,11 @@
+{
+  "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/styling/native-styles.manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "native-styles",
+  "kind": "styling",
+  "label": "React Native StyleSheet",
+  "file": "styling/native-styles.md",
+  "required": false,
+  "folders": [],
+  "concerns": []
+}

package/playbooks/styling/native-styles.md

@@ -0,0 +1,29 @@
+# React Native StyleSheet
+
+## Default
+
+Use React Native's built-in `StyleSheet` for the starter. It runs without a CSS compiler, Babel plugin, or platform-specific setup and keeps the generated Expo project immediately runnable.
+
+```tsx
+import { StyleSheet, Text, View } from 'react-native'
+
+export function EmptyState() {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Nothing here yet</Text>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: { padding: 24 },
+  title: { fontSize: 20, fontWeight: '600' },
+})
+```
+
+## Rules
+
+- Keep styles next to a component until several components share the same design primitive.
+- Use theme tokens for repeated colors, spacing, radius, and typography; do not create a global stylesheet of screen-specific rules.
+- Test layout on Android, iOS, and web before assuming platform behavior is identical.
+- Add NativeWind or another styling system only as an explicit project decision, including its complete Expo configuration and build verification.

package/playbooks/styling/tailwind-extensions.md

@@ -0,0 +1,182 @@
+# Styling: Tailwind CSS — Extensions
+
+Extends your existing tailwind playbook with missing patterns.
+
+---
+
+## Optional cn() Utility for Conditional Classes
+
+The starter does not install these packages. Add `clsx` and `tailwind-merge` before using this optional helper.
+```typescript
+// lib/utils.ts
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+```typescript
+// Usage — conditional classes
+<div className={cn(
+  'base-class other-class',
+  isActive && 'active-class',
+  isDisabled && 'opacity-50 cursor-not-allowed',
+  variant === 'primary' ? 'bg-blue-500' : 'bg-gray-500'
+)} />
+
+// Never string concatenate
+// ❌ `base ${isActive ? 'active' : ''}`
+// ✅ cn('base', isActive && 'active')
+```
+
+---
+
+## Optional shadcn/ui Integration
+
+shadcn/ui is not part of the generated starter. If the project deliberately adopts it:
+- Components live in `components/ui/` — you own the code
+- Install via CLI: `npx shadcn@latest add [component]`
+- Prefer wrapping generated primitives when adding application-specific behavior
+- Use shadcn variants as-is or override in your wrapper
+
+```typescript
+// components/ui/button.tsx — generated by shadcn CLI, don't hand-write
+// components/shared/SubmitButton.tsx — your wrapper that extends it
+import { Button } from '@/components/ui/button'
+
+export function SubmitButton({ isLoading, children }: SubmitButtonProps) {
+  return (
+    <Button type="submit" disabled={isLoading}>
+      {isLoading ? <Spinner /> : children}
+    </Button>
+  )
+}
+```
+
+---
+
+## Dark Mode
+```typescript
+// tailwind.config.ts
+export default {
+  darkMode: 'class',   // controlled by next-themes or manual class toggle
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        // semantic tokens — use these, not raw colors
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+      },
+    },
+  },
+}
+```
+
+```css
+/* globals.css */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --muted: 210 40% 96%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --muted: 217.2 32.6% 17.5%;
+    --muted-foreground: 215 20.2% 65.1%;
+  }
+}
+```
+
+---
+
+## Responsive — Mobile First Always
+```typescript
+// ✅ mobile-first (correct)
+<div className="flex-col sm:flex-row md:gap-8 lg:max-w-7xl" />
+
+// ❌ never reverse-breakpoint
+<div className="flex-row lg:flex-col" />  // only acceptable in specific override cases
+```
+
+---
+
+## Animation Rules
+```typescript
+// ✅ use Tailwind transition classes
+<button className="transition-colors duration-200 hover:bg-primary/90" />
+
+// ✅ define durations in config — not arbitrary
+// tailwind.config.ts
+transitionDuration: {
+  DEFAULT: '200ms',
+  fast: '100ms',
+  slow: '500ms',
+}
+
+// ❌ arbitrary duration values
+<div className="duration-[347ms]" />   // use config token instead
+```
+
+---
+
+## Color Rules
+```typescript
+// ✅ use semantic tokens
+<div className="bg-background text-foreground" />
+<button className="bg-primary text-primary-foreground" />
+
+// ❌ hardcoded color values
+<div className="bg-[#1a1a2e]" />
+<div className="text-[#f0f0f0]" />
+
+// ❌ raw Tailwind colors for brand elements (grey-to-blue shifts on upgrade)
+<div className="bg-blue-600" />   // use 'bg-primary' instead
+```
+
+---
+
+## Agent Quick Reference (Extended)
+```
+Conditional classes?
+  → cn() from lib/utils.ts always
+  → Never string template literals for class composition
+
+shadcn component needed?
+  → npx shadcn@latest add [component-name]
+  → Component lands in components/ui/
+  → Wrap in components/shared/ if you add business logic
+
+Dark mode colors?
+  → Use CSS variable tokens in tailwind.config.ts
+  → Define :root and .dark in globals.css
+  → Apply via 'bg-background', 'text-foreground' classes
+
+Responsive?
+  → Mobile styles first (no prefix)
+  → Tablet: sm: or md:
+  → Desktop: lg: or xl:
+
+Animation?
+  → transition-[property] duration-[token] ease-[type]
+  → Custom durations in tailwind.config.ts
+  → No arbitrary duration values
+```

package/playbooks/styling/tailwind.manifest.json

@@ -0,0 +1,11 @@
+{
+  "id": "tailwind",
+  "kind": "styling",
+  "label": "Tailwind CSS",
+  "file": "styling/tailwind-extensions.md",
+  "required": false,
+  "folders": [],
+  "concerns": [
+    { "id": "styling", "required": true, "sections": ["Responsive"] }
+  ]
+}

package/playbooks/universal/accessibility.manifest.json

@@ -0,0 +1,11 @@
+{
+  "id": "accessibility-baseline",
+  "kind": "universal",
+  "label": "Accessibility Baseline",
+  "required": true,
+  "folders": [],
+  "concerns": [
+    { "id": "accessibility", "required": true, "sections": ["Semantic Structure", "Keyboard and Focus", "Forms and Authentication", "Accessibility Testing"] }
+  ]
+}
+

package/playbooks/universal/accessibility.md

@@ -0,0 +1,45 @@
+# Accessibility Baseline
+
+> Target WCAG 2.2 AA for web interfaces. Mobile interfaces follow the same perceivable, operable, understandable, and robust principles using platform accessibility APIs.
+
+## Semantic Structure
+
+- Use native elements and controls before recreating behavior with generic containers.
+- Give each page one descriptive primary heading and a logical heading hierarchy.
+- Every control has an accessible name. Every form field has a persistent label and associated error/help text.
+- Images need meaningful alternative text or an explicit decorative treatment.
+
+## Keyboard and Focus
+
+- All interactive behavior works from the keyboard without a trap.
+- Focus order follows visual and reading order.
+- Dialogs move focus inside, contain it while open, close with Escape when appropriate, and restore focus to the trigger.
+- Route changes, validation failures, and asynchronous updates move or announce focus only when it helps the user understand the change.
+- Visible focus indicators must not be removed or obscured.
+
+## Visual and Motion
+
+- Do not use color alone to communicate state.
+- Meet WCAG contrast requirements for text, controls, states, and focus indicators.
+- Layout must support zoom, text resizing, narrow screens, and content reflow without hiding essential actions.
+- Respect `prefers-reduced-motion`; avoid flashing and unnecessary autoplay.
+- Touch targets must be large enough and not depend on precision dragging alone.
+
+## Forms and Authentication
+
+- Identify errors in text, associate them with fields, and preserve entered values after failed validation.
+- Allow password managers and paste. Do not block autocomplete or require users to transcribe credentials unnecessarily.
+- Provide accessible alternatives to cognitive-function authentication tests where required by WCAG 2.2.
+- Loading and disabled states remain perceivable to assistive technology.
+
+## Accessibility Testing
+
+- Prefer role, label, and visible-name queries in component and end-to-end tests.
+- Add automated axe checks for common violations, but do not treat automation as complete coverage.
+- Manually test keyboard navigation, focus, zoom/reflow, reduced motion, and at least one screen reader for critical flows.
+- Include authentication, errors, dialogs, navigation, and the core user journey in manual coverage.
+
+## Primary Reference
+
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+

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

@@ -0,0 +1,12 @@
+{
+  "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"] }
+  ]
+}