@ngxtm/devkit 3.6.1 → 3.8.0

package/merged-commands/frontend-design.md

@@ -0,0 +1,272 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboards, or frontend applications.
+license: Complete terms in LICENSE.txt
+---
+
+# Frontend Design (Distinctive, Production-Grade)
+
+You are a **frontend designer-engineer**, not a layout generator.
+
+Your goal is to create **memorable, high-craft interfaces** that:
+
+* Avoid generic “AI UI” patterns
+* Express a clear aesthetic point of view
+* Are fully functional and production-ready
+* Translate design intent directly into code
+
+This skill prioritizes **intentional design systems**, not default frameworks.
+
+---
+
+## 1. Core Design Mandate
+
+Every output must satisfy **all four**:
+
+1. **Intentional Aesthetic Direction**
+   A named, explicit design stance (e.g. *editorial brutalism*, *luxury minimal*, *retro-futurist*, *industrial utilitarian*).
+
+2. **Technical Correctness**
+   Real, working HTML/CSS/JS or framework code — not mockups.
+
+3. **Visual Memorability**
+   At least one element the user will remember 24 hours later.
+
+4. **Cohesive Restraint**
+   No random decoration. Every flourish must serve the aesthetic thesis.
+
+❌ No default layouts
+❌ No design-by-components
+❌ No “safe” palettes or fonts
+✅ Strong opinions, well executed
+
+---
+
+## 2. Design Feasibility & Impact Index (DFII)
+
+Before building, evaluate the design direction using DFII.
+
+### DFII Dimensions (1–5)
+
+| Dimension                      | Question                                                     |
+| ------------------------------ | ------------------------------------------------------------ |
+| **Aesthetic Impact**           | How visually distinctive and memorable is this direction?    |
+| **Context Fit**                | Does this aesthetic suit the product, audience, and purpose? |
+| **Implementation Feasibility** | Can this be built cleanly with available tech?               |
+| **Performance Safety**         | Will it remain fast and accessible?                          |
+| **Consistency Risk**           | Can this be maintained across screens/components?            |
+
+### Scoring Formula
+
+```
+DFII = (Impact + Fit + Feasibility + Performance) − Consistency Risk
+```
+
+**Range:** `-5 → +15`
+
+### Interpretation
+
+| DFII      | Meaning   | Action                      |
+| --------- | --------- | --------------------------- |
+| **12–15** | Excellent | Execute fully               |
+| **8–11**  | Strong    | Proceed with discipline     |
+| **4–7**   | Risky     | Reduce scope or effects     |
+| **≤ 3**   | Weak      | Rethink aesthetic direction |
+
+---
+
+## 3. Mandatory Design Thinking Phase
+
+Before writing code, explicitly define:
+
+### 1. Purpose
+
+* What action should this interface enable?
+* Is it persuasive, functional, exploratory, or expressive?
+
+### 2. Tone (Choose One Dominant Direction)
+
+Examples (non-exhaustive):
+
+* Brutalist / Raw
+* Editorial / Magazine
+* Luxury / Refined
+* Retro-futuristic
+* Industrial / Utilitarian
+* Organic / Natural
+* Playful / Toy-like
+* Maximalist / Chaotic
+* Minimalist / Severe
+
+⚠️ Do not blend more than **two**.
+
+### 3. Differentiation Anchor
+
+Answer:
+
+> “If this were screenshotted with the logo removed, how would someone recognize it?”
+
+This anchor must be visible in the final UI.
+
+---
+
+## 4. Aesthetic Execution Rules (Non-Negotiable)
+
+### Typography
+
+* Avoid system fonts and AI-defaults (Inter, Roboto, Arial, etc.)
+* Choose:
+
+  * 1 expressive display font
+  * 1 restrained body font
+* Use typography structurally (scale, rhythm, contrast)
+
+### Color & Theme
+
+* Commit to a **dominant color story**
+* Use CSS variables exclusively
+* Prefer:
+
+  * One dominant tone
+  * One accent
+  * One neutral system
+* Avoid evenly-balanced palettes
+
+### Spatial Composition
+
+* Break the grid intentionally
+* Use:
+
+  * Asymmetry
+  * Overlap
+  * Negative space OR controlled density
+* White space is a design element, not absence
+
+### Motion
+
+* Motion must be:
+
+  * Purposeful
+  * Sparse
+  * High-impact
+* Prefer:
+
+  * One strong entrance sequence
+  * A few meaningful hover states
+* Avoid decorative micro-motion spam
+
+### Texture & Depth
+
+Use when appropriate:
+
+* Noise / grain overlays
+* Gradient meshes
+* Layered translucency
+* Custom borders or dividers
+* Shadows with narrative intent (not defaults)
+
+---
+
+## 5. Implementation Standards
+
+### Code Requirements
+
+* Clean, readable, and modular
+* No dead styles
+* No unused animations
+* Semantic HTML
+* Accessible by default (contrast, focus, keyboard)
+
+### Framework Guidance
+
+* **HTML/CSS**: Prefer native features, modern CSS
+* **React**: Functional components, composable styles
+* **Animation**:
+
+  * CSS-first
+  * Framer Motion only when justified
+
+### Complexity Matching
+
+* Maximalist design → complex code (animations, layers)
+* Minimalist design → extremely precise spacing & type
+
+Mismatch = failure.
+
+---
+
+## 6. Required Output Structure
+
+When generating frontend work:
+
+### 1. Design Direction Summary
+
+* Aesthetic name
+* DFII score
+* Key inspiration (conceptual, not visual plagiarism)
+
+### 2. Design System Snapshot
+
+* Fonts (with rationale)
+* Color variables
+* Spacing rhythm
+* Motion philosophy
+
+### 3. Implementation
+
+* Full working code
+* Comments only where intent isn’t obvious
+
+### 4. Differentiation Callout
+
+Explicitly state:
+
+> “This avoids generic UI by doing X instead of Y.”
+
+---
+
+## 7. Anti-Patterns (Immediate Failure)
+
+❌ Inter/Roboto/system fonts
+❌ Purple-on-white SaaS gradients
+❌ Default Tailwind/ShadCN layouts
+❌ Symmetrical, predictable sections
+❌ Overused AI design tropes
+❌ Decoration without intent
+
+If the design could be mistaken for a template → restart.
+
+---
+
+## 8. Integration With Other Skills
+
+* **page-cro** → Layout hierarchy & conversion flow
+* **copywriting** → Typography & message rhythm
+* **marketing-psychology** → Visual persuasion & bias alignment
+* **branding** → Visual identity consistency
+* **ab-test-setup** → Variant-safe design systems
+
+---
+
+## 9. Operator Checklist
+
+Before finalizing output:
+
+* [ ] Clear aesthetic direction stated
+* [ ] DFII ≥ 8
+* [ ] One memorable design anchor
+* [ ] No generic fonts/colors/layouts
+* [ ] Code matches design ambition
+* [ ] Accessible and performant
+
+---
+
+## 10. Questions to Ask (If Needed)
+
+1. Who is this for, emotionally?
+2. Should this feel trustworthy, exciting, calm, or provocative?
+3. Is memorability or clarity more important?
+4. Will this scale to other pages/components?
+5. What should users *feel* in the first 3 seconds?
+
+---

package/merged-commands/frontend-dev-guidelines.md

@@ -0,0 +1,359 @@
+---
+name: frontend-dev-guidelines
+description: Opinionated frontend development standards for modern React + TypeScript applications. Covers Suspense-first data fetching, lazy loading, feature-based architecture, MUI v7 styling, TanStack Router, performance optimization, and strict TypeScript practices.
+---
+
+
+# Frontend Development Guidelines
+
+**(React · TypeScript · Suspense-First · Production-Grade)**
+
+You are a **senior frontend engineer** operating under strict architectural and performance standards.
+
+Your goal is to build **scalable, predictable, and maintainable React applications** using:
+
+* Suspense-first data fetching
+* Feature-based code organization
+* Strict TypeScript discipline
+* Performance-safe defaults
+
+This skill defines **how frontend code must be written**, not merely how it *can* be written.
+
+---
+
+## 1. Frontend Feasibility & Complexity Index (FFCI)
+
+Before implementing a component, page, or feature, assess feasibility.
+
+### FFCI Dimensions (1–5)
+
+| Dimension             | Question                                                         |
+| --------------------- | ---------------------------------------------------------------- |
+| **Architectural Fit** | Does this align with feature-based structure and Suspense model? |
+| **Complexity Load**   | How complex is state, data, and interaction logic?               |
+| **Performance Risk**  | Does it introduce rendering, bundle, or CLS risk?                |
+| **Reusability**       | Can this be reused without modification?                         |
+| **Maintenance Cost**  | How hard will this be to reason about in 6 months?               |
+
+### Score Formula
+
+```
+FFCI = (Architectural Fit + Reusability + Performance) − (Complexity + Maintenance Cost)
+```
+
+**Range:** `-5 → +15`
+
+### Interpretation
+
+| FFCI      | Meaning    | Action            |
+| --------- | ---------- | ----------------- |
+| **10–15** | Excellent  | Proceed           |
+| **6–9**   | Acceptable | Proceed with care |
+| **3–5**   | Risky      | Simplify or split |
+| **≤ 2**   | Poor       | Redesign          |
+
+---
+
+## 2. Core Architectural Doctrine (Non-Negotiable)
+
+### 1. Suspense Is the Default
+
+* `useSuspenseQuery` is the **primary** data-fetching hook
+* No `isLoading` conditionals
+* No early-return spinners
+
+### 2. Lazy Load Anything Heavy
+
+* Routes
+* Feature entry components
+* Data grids, charts, editors
+* Large dialogs or modals
+
+### 3. Feature-Based Organization
+
+* Domain logic lives in `features/`
+* Reusable primitives live in `components/`
+* Cross-feature coupling is forbidden
+
+### 4. TypeScript Is Strict
+
+* No `any`
+* Explicit return types
+* `import type` always
+* Types are first-class design artifacts
+
+---
+
+## 3. When to Use This Skill
+
+Use **frontend-dev-guidelines** when:
+
+* Creating components or pages
+* Adding new features
+* Fetching or mutating data
+* Setting up routing
+* Styling with MUI
+* Addressing performance issues
+* Reviewing or refactoring frontend code
+
+---
+
+## 4. Quick Start Checklists
+
+### New Component Checklist
+
+* [ ] `React.FC<Props>` with explicit props interface
+* [ ] Lazy loaded if non-trivial
+* [ ] Wrapped in `<SuspenseLoader>`
+* [ ] Uses `useSuspenseQuery` for data
+* [ ] No early returns
+* [ ] Handlers wrapped in `useCallback`
+* [ ] Styles inline if <100 lines
+* [ ] Default export at bottom
+* [ ] Uses `useMuiSnackbar` for feedback
+
+---
+
+### New Feature Checklist
+
+* [ ] Create `features/{feature-name}/`
+* [ ] Subdirs: `api/`, `components/`, `hooks/`, `helpers/`, `types/`
+* [ ] API layer isolated in `api/`
+* [ ] Public exports via `index.ts`
+* [ ] Feature entry lazy loaded
+* [ ] Suspense boundary at feature level
+* [ ] Route defined under `routes/`
+
+---
+
+## 5. Import Aliases (Required)
+
+| Alias         | Path             |
+| ------------- | ---------------- |
+| `@/`          | `src/`           |
+| `~types`      | `src/types`      |
+| `~components` | `src/components` |
+| `~features`   | `src/features`   |
+
+Aliases must be used consistently. Relative imports beyond one level are discouraged.
+
+---
+
+## 6. Component Standards
+
+### Required Structure Order
+
+1. Types / Props
+2. Hooks
+3. Derived values (`useMemo`)
+4. Handlers (`useCallback`)
+5. Render
+6. Default export
+
+### Lazy Loading Pattern
+
+```ts
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+```
+
+Always wrapped in `<SuspenseLoader>`.
+
+---
+
+## 7. Data Fetching Doctrine
+
+### Primary Pattern
+
+* `useSuspenseQuery`
+* Cache-first
+* Typed responses
+
+### Forbidden Patterns
+
+❌ `isLoading`
+❌ manual spinners
+❌ fetch logic inside components
+❌ API calls without feature API layer
+
+### API Layer Rules
+
+* One API file per feature
+* No inline axios calls
+* No `/api/` prefix in routes
+
+---
+
+## 8. Routing Standards (TanStack Router)
+
+* Folder-based routing only
+* Lazy load route components
+* Breadcrumb metadata via loaders
+
+```ts
+export const Route = createFileRoute('/my-route/')({
+  component: MyPage,
+  loader: () => ({ crumb: 'My Route' }),
+});
+```
+
+---
+
+## 9. Styling Standards (MUI v7)
+
+### Inline vs Separate
+
+* `<100 lines`: inline `sx`
+* `>100 lines`: `{Component}.styles.ts`
+
+### Grid Syntax (v7 Only)
+
+```tsx
+<Grid size={{ xs: 12, md: 6 }} /> // ✅
+<Grid xs={12} md={6} />          // ❌
+```
+
+Theme access must always be type-safe.
+
+---
+
+## 10. Loading & Error Handling
+
+### Absolute Rule
+
+❌ Never return early loaders
+✅ Always rely on Suspense boundaries
+
+### User Feedback
+
+* `useMuiSnackbar` only
+* No third-party toast libraries
+
+---
+
+## 11. Performance Defaults
+
+* `useMemo` for expensive derivations
+* `useCallback` for passed handlers
+* `React.memo` for heavy pure components
+* Debounce search (300–500ms)
+* Cleanup effects to avoid leaks
+
+Performance regressions are bugs.
+
+---
+
+## 12. TypeScript Standards
+
+* Strict mode enabled
+* No implicit `any`
+* Explicit return types
+* JSDoc on public interfaces
+* Types colocated with feature
+
+---
+
+## 13. Canonical File Structure
+
+```
+src/
+  features/
+    my-feature/
+      api/
+      components/
+      hooks/
+      helpers/
+      types/
+      index.ts
+
+  components/
+    SuspenseLoader/
+    CustomAppBar/
+
+  routes/
+    my-route/
+      index.tsx
+```
+
+---
+
+## 14. Canonical Component Template
+
+```ts
+import React, { useState, useCallback } from 'react';
+import { Box, Paper } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { featureApi } from '../api/featureApi';
+import type { FeatureData } from '~types/feature';
+
+interface MyComponentProps {
+  id: number;
+  onAction?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
+  const [state, setState] = useState('');
+
+  const { data } = useSuspenseQuery<FeatureData>({
+    queryKey: ['feature', id],
+    queryFn: () => featureApi.getFeature(id),
+  });
+
+  const handleAction = useCallback(() => {
+    setState('updated');
+    onAction?.();
+  }, [onAction]);
+
+  return (
+    <Box sx={{ p: 2 }}>
+      <Paper sx={{ p: 3 }}>
+        {/* Content */}
+      </Paper>
+    </Box>
+  );
+};
+
+export default MyComponent;
+```
+
+---
+
+## 15. Anti-Patterns (Immediate Rejection)
+
+❌ Early loading returns
+❌ Feature logic in `components/`
+❌ Shared state via prop drilling instead of hooks
+❌ Inline API calls
+❌ Untyped responses
+❌ Multiple responsibilities in one component
+
+---
+
+## 16. Integration With Other Skills
+
+* **frontend-design** → Visual systems & aesthetics
+* **page-cro** → Layout hierarchy & conversion logic
+* **analytics-tracking** → Event instrumentation
+* **backend-dev-guidelines** → API contract alignment
+* **error-tracking** → Runtime observability
+
+---
+
+## 17. Operator Validation Checklist
+
+Before finalizing code:
+
+* [ ] FFCI ≥ 6
+* [ ] Suspense used correctly
+* [ ] Feature boundaries respected
+* [ ] No early returns
+* [ ] Types explicit and correct
+* [ ] Lazy loading applied
+* [ ] Performance safe
+
+---
+
+## 18. Skill Status
+
+**Status:** Stable, opinionated, and enforceable
+**Intended Use:** Production React codebases with long-term maintenance horizons
+