@zigrivers/scaffold 3.5.3 → 3.7.0

package/content/knowledge/web-app/web-app-ux-patterns.md

@@ -0,0 +1,162 @@
+---
+name: web-app-ux-patterns
+description: Responsive design, loading states, error boundaries, offline patterns, optimistic updates, and accessibility (WCAG) for web apps
+topics: [web-app, ux, responsive-design, loading-states, error-handling, accessibility, wcag, offline, optimistic-updates]
+---
+
+UX patterns are the difference between an app that users trust and one they abandon. The patterns covered here are not visual design choices — they are engineering decisions about how the app communicates state, handles failure, and responds to interaction. Implement them consistently across the entire app or they create a fragmented user experience that signals poor quality.
+
+## Summary
+
+UX patterns cover responsive mobile-first design, loading states (skeletons, progressive loading, optimistic updates), error boundaries at meaningful granularity, offline patterns for PWAs, and accessibility compliance. Implement these consistently across the entire app. Loading states for sub-100ms operations make the app feel slower; omit them.
+
+## Deep Guidance
+
+### Responsive Design: Mobile-First
+
+Design and implement for mobile first, then add complexity for larger screens. This discipline prevents the "desktop first, mobile afterthought" failure mode:
+
+```css
+/* Mobile default: full width stack */
+.product-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--sp-4);
+}
+
+/* Tablet: 2 columns */
+@media (min-width: 768px) {
+  .product-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+/* Desktop: 3 columns */
+@media (min-width: 1024px) {
+  .product-grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+```
+
+Touch targets must be at least 44 x 44 px (Apple HIG) or 48 x 48 px (Material Design). Smaller tap targets on mobile cause accidental taps and user frustration. This is both a UX and accessibility requirement.
+
+Viewport-relative units (`vw`, `vh`, `svh`, `dvh`) handle mobile browser chrome (address bars, bottom navigation) correctly. Use `dvh` for full-height layouts on mobile — `100vh` overflows when the browser chrome is visible.
+
+### Loading States
+
+Never show a blank screen or unresponsive UI during data fetching. Use the appropriate loading pattern for the context:
+
+- **Skeleton screens**: Render a content-shaped placeholder that mirrors the final layout. Reduces perceived load time and prevents layout shift when content arrives. Preferred over spinners for content that has a predictable layout.
+- **Progressive loading**: Render low-quality or partial content immediately, replace with full content as it loads. Image blur-up (blur-hash placeholder to full image) is a common example.
+- **Inline spinners**: For user-triggered actions (button submit, form save) where a skeleton does not make sense. Keep spinners small and contextual — a full-page spinner on a button press is jarring.
+- **Optimistic updates**: Show the result immediately, apply it to the server in the background (see below). Best perceived performance.
+
+Never show a loading state for actions that complete under 100 ms. Adding a spinner to fast operations makes the app feel slower.
+
+### Error Boundaries
+
+React error boundaries prevent a single component crash from destroying the entire page:
+
+```tsx
+// components/ErrorBoundary.tsx
+class ErrorBoundary extends React.Component<
+  { fallback: ReactNode; children: ReactNode },
+  { hasError: boolean }
+> {
+  state = { hasError: false };
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    reportError(error, info);  // Send to Sentry, Datadog, etc.
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback;
+    return this.props.children;
+  }
+}
+```
+
+Place error boundaries at meaningful granularity: one per major page section, not one per component (too granular) and not one per app (too coarse). When the sidebar crashes, the main content should still work.
+
+Provide actionable fallback UIs: "Something went wrong" with a Retry button, not a blank space. Log errors to your monitoring service with full context (user ID, route, component stack) so you can fix them.
+
+### Offline Patterns
+
+If the app targets users who may lose connectivity (mobile users, field workers, PWA), design for it explicitly:
+
+- **Detect connectivity**: `navigator.onLine` and the `online`/`offline` events. React Query and SWR automatically pause requests while offline and retry on reconnect.
+- **Cache reads**: Service worker with a cache-first or stale-while-revalidate strategy for read operations. Users see the last known state instead of an error page.
+- **Queue writes**: Store mutations locally (IndexedDB via Dexie, or background sync API) and replay them when connectivity restores. Essential for field apps where users must be able to submit forms offline.
+- **Communicate status**: Show a banner when offline. Tell users which data may be stale. Do not silently fail mutations — tell the user the action is queued.
+
+Implementing offline support adds significant complexity. Scope it to the specific user journeys that need it, not the entire app.
+
+### Optimistic Updates
+
+Optimistic updates apply the result of a mutation to the UI immediately, before server confirmation:
+
+```typescript
+// React Query optimistic update pattern
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ["todos"] });
+    const previousTodos = queryClient.getQueryData(["todos"]);
+    queryClient.setQueryData(["todos"], (old) =>
+      old.map((t) => t.id === newTodo.id ? { ...t, ...newTodo } : t)
+    );
+    return { previousTodos };
+  },
+  onError: (error, variables, context) => {
+    queryClient.setQueryData(["todos"], context.previousTodos);
+    showError("Failed to save changes.");
+  },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
+});
+```
+
+Use optimistic updates for: toggling checkboxes, likes/favorites, reordering, simple field edits. Do not use for: payments, irreversible actions, or anything where showing a false success state is harmful.
+
+### Accessibility Implementation
+
+WCAG compliance is a legal requirement in many jurisdictions (ADA, EN 301 549, AODA) and a quality signal for all users:
+
+**Keyboard navigation:**
+- Every interactive element reachable by Tab key in logical order
+- Focus styles visible and high-contrast (never `outline: none` without a replacement)
+- Modal dialogs trap focus; Escape closes them
+- Custom interactive components (dropdowns, sliders, date pickers) implement ARIA keyboard patterns from the WAI-ARIA Authoring Practices Guide
+
+**Screen reader support:**
+- Semantic HTML first: `<button>` not `<div onClick>`, `<nav>` not `<div class="nav">`, `<h1>`–`<h6>` for heading hierarchy
+- `alt` text on all meaningful images; `alt=""` for decorative images
+- `aria-label` or `aria-labelledby` for elements whose text content does not describe their purpose
+- Live regions (`aria-live="polite"`) for dynamic content updates (error messages, notifications)
+- Test with VoiceOver (macOS/iOS) and NVDA (Windows) — automated tools miss 60–70% of real issues
+
+**Color and contrast:**
+- Minimum 4.5:1 contrast ratio for normal text, 3:1 for large text (WCAG AA)
+- Do not rely on color alone to convey meaning — add icons, patterns, or text labels
+
+### Form UX Patterns
+
+Forms are the highest-friction interaction in most apps. Apply these patterns:
+
+- **Inline validation**: Validate on blur (not on keystroke) to avoid distracting errors as users type. Show success states to confirm correct input.
+- **Error placement**: Show field-level errors directly below the field, not in a summary banner. Users must not hunt to find which field has an error.
+- **Label positioning**: Labels above inputs, not placeholders-as-labels. Placeholder text disappears when the user types and fails accessibility requirements.
+- **Disabled submit vs. validation feedback**: Do not disable the submit button with no explanation. Instead, allow submission and show validation errors. Disabled buttons with no label are inaccessible and frustrating.
+
+### Toast / Notification Patterns
+
+Notifications must not interrupt user flow or require dismissal for low-priority information:
+
+- **Success toasts**: Auto-dismiss after 4–5 seconds. No action required.
+- **Error toasts**: Persist until dismissed or action taken. User must be able to act on the error.
+- **Placement**: Bottom-right (desktop) or bottom-center (mobile) to avoid covering primary content.
+- **Screen reader**: Announce via `aria-live="polite"` for non-critical messages, `aria-live="assertive"` only for critical errors. Assertive announcements interrupt screen reader narration — use sparingly.

package/content/methodology/backend-overlay.yml

@@ -0,0 +1,73 @@
+# methodology/backend-overlay.yml
+name: backend
+description: >
+  Backend service overlay — injects backend domain knowledge into existing
+  pipeline steps for API design, data modeling, authentication, async
+  processing, and deployment patterns.
+project-type: backend
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Map backend knowledge entries into existing pipeline steps so that backend
+# domain expertise is injected during prompt assembly.
+knowledge-overrides:
+  # Foundational
+  create-prd:
+    append: [backend-requirements]
+  user-stories:
+    append: [backend-requirements]
+  coding-standards:
+    append: [backend-conventions]
+  project-structure:
+    append: [backend-project-structure]
+  dev-env-setup:
+    append: [backend-dev-environment]
+  git-workflow:
+    append: [backend-deployment]
+
+  # Architecture & Design
+  system-architecture:
+    append: [backend-architecture, backend-async-patterns, backend-worker-patterns]
+  tech-stack:
+    append: [backend-architecture, backend-api-design, backend-auth-patterns]
+  adrs:
+    append: [backend-architecture]
+  domain-modeling:
+    append: [backend-data-modeling]
+  database-schema:
+    append: [backend-data-modeling]
+  api-contracts:
+    append: [backend-api-design]
+  security:
+    append: [backend-auth-patterns, backend-security]
+  operations:
+    append: [backend-deployment, backend-observability, backend-async-patterns, backend-worker-patterns]
+
+  # Testing
+  tdd:
+    append: [backend-testing]
+  add-e2e-testing:
+    append: [backend-testing]
+  create-evals:
+    append: [backend-testing]
+  story-tests:
+    append: [backend-testing]
+
+  # Reviews (mirror authoring steps)
+  review-architecture:
+    append: [backend-architecture, backend-async-patterns, backend-worker-patterns]
+  review-api:
+    append: [backend-api-design]
+  review-database:
+    append: [backend-data-modeling]
+  review-security:
+    append: [backend-auth-patterns, backend-security]
+  review-operations:
+    append: [backend-deployment, backend-observability, backend-async-patterns, backend-worker-patterns]
+  review-testing:
+    append: [backend-testing]
+
+  # Planning
+  implementation-plan:
+    append: [backend-architecture]

package/content/methodology/cli-overlay.yml

@@ -0,0 +1,69 @@
+# methodology/cli-overlay.yml
+name: cli
+description: >
+  CLI tool overlay — injects CLI domain knowledge into existing pipeline
+  steps for command parsing, distribution, interactive prompts, output
+  formatting, and shell integration patterns.
+project-type: cli
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Map CLI knowledge entries into existing pipeline steps so that CLI tool
+# domain expertise is injected during prompt assembly.
+knowledge-overrides:
+  # Foundational
+  create-prd:
+    append: [cli-requirements]
+  user-stories:
+    append: [cli-requirements]
+  coding-standards:
+    append: [cli-conventions]
+  project-structure:
+    append: [cli-project-structure]
+  dev-env-setup:
+    append: [cli-dev-environment, cli-shell-integration]
+  git-workflow:
+    append: [cli-distribution-patterns]
+
+  # Architecture & Design
+  system-architecture:
+    append: [cli-architecture, cli-interactivity-patterns]
+  tech-stack:
+    append: [cli-architecture, cli-distribution-patterns]
+  adrs:
+    append: [cli-architecture]
+  domain-modeling:
+    append: [cli-architecture]
+  api-contracts:
+    append: [cli-output-patterns]
+  security:
+    append: [cli-conventions]
+  operations:
+    append: [cli-distribution-patterns, cli-shell-integration]
+
+  # Testing
+  tdd:
+    append: [cli-testing]
+  add-e2e-testing:
+    append: [cli-testing]
+  create-evals:
+    append: [cli-testing]
+  story-tests:
+    append: [cli-testing]
+
+  # Reviews (mirror authoring steps)
+  review-architecture:
+    append: [cli-architecture, cli-interactivity-patterns]
+  review-api:
+    append: [cli-output-patterns]
+  review-security:
+    append: [cli-conventions]
+  review-operations:
+    append: [cli-distribution-patterns, cli-shell-integration]
+  review-testing:
+    append: [cli-testing]
+
+  # Planning
+  implementation-plan:
+    append: [cli-architecture]

package/content/methodology/web-app-overlay.yml

@@ -0,0 +1,79 @@
+# methodology/web-app-overlay.yml
+name: web-app
+description: >
+  Web application overlay — injects web-app domain knowledge into existing
+  pipeline steps for SSR/SPA architecture, deployment, authentication, and
+  real-time patterns.
+project-type: web-app
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Map web-app knowledge entries into existing pipeline steps so that web-app
+# domain expertise is injected during prompt assembly.
+knowledge-overrides:
+  # Foundational
+  create-prd:
+    append: [web-app-requirements]
+  user-stories:
+    append: [web-app-requirements]
+  coding-standards:
+    append: [web-app-conventions]
+  project-structure:
+    append: [web-app-project-structure]
+  dev-env-setup:
+    append: [web-app-dev-environment]
+  git-workflow:
+    append: [web-app-deployment-workflow]
+
+  # Architecture & Design
+  system-architecture:
+    append: [web-app-architecture, web-app-deployment]
+  tech-stack:
+    append: [web-app-rendering-strategies, web-app-deployment, web-app-auth-patterns]
+  adrs:
+    append: [web-app-architecture]
+  ux-spec:
+    append: [web-app-ux-patterns]
+  design-system:
+    append: [web-app-design-system]
+  domain-modeling:
+    append: [web-app-session-patterns]
+  database-schema:
+    append: [web-app-data-patterns]
+  api-contracts:
+    append: [web-app-api-patterns]
+  security:
+    append: [web-app-auth-patterns, web-app-security]
+  operations:
+    append: [web-app-deployment, web-app-observability]
+
+  # Testing
+  tdd:
+    append: [web-app-testing]
+  add-e2e-testing:
+    append: [web-app-testing]
+  create-evals:
+    append: [web-app-testing]
+  story-tests:
+    append: [web-app-testing]
+
+  # Reviews (mirror authoring steps)
+  review-architecture:
+    append: [web-app-architecture, web-app-deployment]
+  review-ux:
+    append: [web-app-ux-patterns]
+  review-api:
+    append: [web-app-api-patterns]
+  review-database:
+    append: [web-app-data-patterns]
+  review-security:
+    append: [web-app-auth-patterns, web-app-security]
+  review-operations:
+    append: [web-app-deployment, web-app-observability]
+  review-testing:
+    append: [web-app-testing]
+
+  # Planning
+  implementation-plan:
+    append: [web-app-architecture]

package/dist/cli/commands/init.d.ts

@@ -8,6 +8,32 @@ interface InitArgs {
     idea?: string;
     methodology?: string;
     'project-type'?: string;
+    depth?: number;
+    adapters?: string[];
+    traits?: string[];
+    engine?: string;
+    multiplayer?: string;
+    'target-platforms'?: string[];
+    'online-services'?: string[];
+    'content-structure'?: string;
+    economy?: string;
+    narrative?: string;
+    locales?: string[];
+    'npc-ai'?: string;
+    modding?: boolean;
+    persistence?: string;
+    'web-rendering'?: string;
+    'web-deploy-target'?: string;
+    'web-realtime'?: string;
+    'web-auth-flow'?: string;
+    'backend-api-style'?: string;
+    'backend-data-store'?: string[];
+    'backend-auth'?: string;
+    'backend-messaging'?: string;
+    'backend-deploy-target'?: string;
+    'cli-interactivity'?: string;
+    'cli-distribution'?: string[];
+    'cli-structured-output'?: boolean;
 }
 declare const initCommand: CommandModule<Record<string, unknown>, InitArgs>;
 export default initCommand;

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,OAAO,CAAA;AAOhD,UAAU,QAAQ;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,QAAA,MAAM,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CA6EjE,CAAA;AAED,eAAe,WAAW,CAAA"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,OAAO,CAAA;AA6BhD,UAAU,QAAQ;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAEhC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,QAAA,MAAM,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CA4bjE,CAAA;AAED,eAAe,WAAW,CAAA"}