agentic-team-templates 0.3.0

package/templates/web-frontend/.cursorrules/state-management.md

@@ -0,0 +1,227 @@
+# State Management
+
+Guidelines for managing state in frontend applications.
+
+## State Categories
+
+### Local State
+State that belongs to a single component.
+- Form input values
+- UI toggles (open/closed)
+- Temporary data
+
+### Shared State
+State needed by multiple components.
+- User authentication
+- Theme/preferences
+- Shopping cart
+
+### Server State
+Data from external sources.
+- API responses
+- Cached data
+- Real-time updates
+
+## Principles
+
+### 1. Lift State Only When Necessary
+
+Keep state as close to where it's used as possible.
+
+```tsx
+// Good: State where it's needed
+const SearchBox = () => {
+  const [query, setQuery] = useState('');
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+};
+
+// Only lift when siblings need it
+const SearchPage = () => {
+  const [query, setQuery] = useState('');
+  return (
+    <>
+      <SearchBox query={query} onChange={setQuery} />
+      <SearchResults query={query} />
+    </>
+  );
+};
+```
+
+### 2. Derive Don't Duplicate
+
+Calculate values from existing state instead of storing duplicates.
+
+```tsx
+// Good: Derived state
+const Cart = ({ items }: { items: CartItem[] }) => {
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+  const itemCount = items.length;
+  // ...
+};
+
+// Bad: Duplicate state
+const Cart = ({ items }: { items: CartItem[] }) => {
+  const [total, setTotal] = useState(0);
+  const [itemCount, setItemCount] = useState(0);
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0));
+    setItemCount(items.length);
+  }, [items]);  // Now you have to keep these in sync
+};
+```
+
+### 3. Immutable Updates
+
+Never mutate state directly.
+
+```tsx
+// Good: Immutable update
+setItems(items => [...items, newItem]);
+setUser(user => ({ ...user, name: newName }));
+
+// Bad: Mutation
+items.push(newItem);
+setItems(items);
+```
+
+## Local State Patterns
+
+### useState for Simple Values
+
+```tsx
+const [count, setCount] = useState(0);
+const [isOpen, setIsOpen] = useState(false);
+```
+
+### useReducer for Complex State
+
+```tsx
+type State = { count: number; step: number };
+type Action =
+  | { type: 'increment' }
+  | { type: 'decrement' }
+  | { type: 'setStep'; step: number };
+
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case 'increment':
+      return { ...state, count: state.count + state.step };
+    case 'decrement':
+      return { ...state, count: state.count - state.step };
+    case 'setStep':
+      return { ...state, step: action.step };
+  }
+};
+
+const Counter = () => {
+  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
+  // ...
+};
+```
+
+## Shared State Patterns
+
+### Context for Theme/Auth/Global UI
+
+```tsx
+const ThemeContext = createContext<Theme>('light');
+
+const ThemeProvider = ({ children }: { children: React.ReactNode }) => {
+  const [theme, setTheme] = useState<Theme>('light');
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+};
+
+const useTheme = () => useContext(ThemeContext);
+```
+
+### State Libraries for Complex Apps
+
+Consider dedicated state management libraries when:
+- Many components need the same state
+- Complex update logic
+- Need for devtools/debugging
+- Time-travel debugging needed
+
+## Server State Patterns
+
+### Separate Server State from UI State
+
+```tsx
+// Good: Dedicated server state handling
+const { data: users, isLoading, error } = useQuery('users', fetchUsers);
+
+// Use data in UI state
+const [selectedUserId, setSelectedUserId] = useState<string | null>(null);
+const selectedUser = users?.find(u => u.id === selectedUserId);
+```
+
+### Handle Loading & Error States
+
+```tsx
+const UserList = () => {
+  const { data, isLoading, error } = useQuery('users', fetchUsers);
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  if (!data?.length) return <Empty message="No users found" />;
+
+  return <ul>{data.map(user => <UserItem key={user.id} user={user} />)}</ul>;
+};
+```
+
+## Anti-Patterns
+
+### Prop Drilling
+
+❌ Passing props through many layers:
+```tsx
+<App user={user}>
+  <Layout user={user}>
+    <Sidebar user={user}>
+      <UserMenu user={user} />
+    </Sidebar>
+  </Layout>
+</App>
+```
+
+✅ Use context or composition:
+```tsx
+<UserProvider user={user}>
+  <App>
+    <Layout>
+      <Sidebar>
+        <UserMenu /> {/* Uses useUser() hook */}
+      </Sidebar>
+    </Layout>
+  </App>
+</UserProvider>
+```
+
+### Over-Centralization
+
+❌ Putting everything in global state
+✅ Keep local state local, only share what's needed
+
+### Stale Closures
+
+❌ Using outdated values in callbacks:
+```tsx
+const [count, setCount] = useState(0);
+const handleClick = () => {
+  setTimeout(() => console.log(count), 1000);  // Might be stale
+};
+```
+
+✅ Use refs or functional updates:
+```tsx
+const countRef = useRef(count);
+countRef.current = count;
+const handleClick = () => {
+  setTimeout(() => console.log(countRef.current), 1000);
+};
+```

package/templates/web-frontend/.cursorrules/styling.md

@@ -0,0 +1,271 @@
+# Styling Guidelines
+
+Best practices for styling frontend applications.
+
+## Principles
+
+### 1. Consistency
+Use a design system or consistent conventions throughout the application.
+
+### 2. Maintainability
+Styles should be easy to find, understand, and modify.
+
+### 3. Performance
+Minimize CSS bundle size and avoid layout thrashing.
+
+### 4. Responsiveness
+Design for all screen sizes from the start.
+
+## CSS Organization
+
+### Component-Scoped Styles
+
+Keep styles close to their components.
+
+```
+components/
+├── Button/
+│   ├── Button.tsx
+│   ├── Button.styles.css  # or .module.css
+│   └── Button.test.tsx
+```
+
+### Naming Conventions
+
+Use clear, consistent naming:
+
+```css
+/* BEM-style (Block Element Modifier) */
+.card { }
+.card__header { }
+.card__body { }
+.card--featured { }
+
+/* Utility-based */
+.flex .items-center .gap-4 .p-2
+```
+
+## Responsive Design
+
+### Mobile-First
+
+Start with mobile styles, add complexity for larger screens.
+
+```css
+/* Base: Mobile */
+.container {
+  padding: 1rem;
+}
+
+/* Tablet and up */
+@media (min-width: 768px) {
+  .container {
+    padding: 2rem;
+  }
+}
+
+/* Desktop */
+@media (min-width: 1024px) {
+  .container {
+    padding: 3rem;
+    max-width: 1200px;
+  }
+}
+```
+
+### Flexible Units
+
+Prefer relative units for flexibility.
+
+```css
+/* Good: Flexible */
+.container {
+  max-width: 80rem;      /* 1280px at default font size */
+  padding: 1rem;
+  font-size: 1rem;
+  line-height: 1.5;
+}
+
+/* Avoid: Fixed pixels for text/spacing */
+.container {
+  max-width: 1280px;
+  padding: 16px;
+  font-size: 16px;
+}
+```
+
+## Layout
+
+### Modern Layout Tools
+
+Use Flexbox and Grid for layout.
+
+```css
+/* Flexbox for 1D layouts */
+.nav {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+/* Grid for 2D layouts */
+.dashboard {
+  display: grid;
+  grid-template-columns: 250px 1fr;
+  grid-template-rows: auto 1fr auto;
+  gap: 1rem;
+}
+```
+
+### Avoid Layout Hacks
+
+❌ Don't use floats for layout
+❌ Don't use tables for layout
+❌ Avoid excessive negative margins
+
+## Theming
+
+### CSS Custom Properties
+
+Use CSS variables for theming.
+
+```css
+:root {
+  --color-primary: #3b82f6;
+  --color-secondary: #64748b;
+  --color-background: #ffffff;
+  --color-text: #1e293b;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 2rem;
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+}
+
+[data-theme="dark"] {
+  --color-background: #0f172a;
+  --color-text: #f1f5f9;
+}
+
+.button {
+  background: var(--color-primary);
+  padding: var(--spacing-sm) var(--spacing-md);
+  border-radius: var(--radius-md);
+}
+```
+
+## Performance
+
+### Minimize Reflows
+
+Group DOM reads and writes.
+
+```js
+// Bad: Causes multiple reflows
+element.style.width = '100px';
+const height = element.offsetHeight;  // Read forces reflow
+element.style.height = height + 'px';
+
+// Good: Batch reads, then writes
+const height = element.offsetHeight;
+element.style.width = '100px';
+element.style.height = height + 'px';
+```
+
+### Use Efficient Selectors
+
+```css
+/* Good: Specific, efficient */
+.nav-item { }
+.button-primary { }
+
+/* Avoid: Expensive selectors */
+div > ul > li > a { }
+*:not(.something) { }
+```
+
+### Reduce Bundle Size
+
+- Remove unused CSS (PurgeCSS, etc.)
+- Use CSS code splitting
+- Avoid importing entire libraries for a few utilities
+
+## Common Patterns
+
+### Visually Hidden (Screen Reader Only)
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+### Truncate Text
+
+```css
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.line-clamp-2 {
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+### Aspect Ratio
+
+```css
+.aspect-video {
+  aspect-ratio: 16 / 9;
+}
+
+.aspect-square {
+  aspect-ratio: 1 / 1;
+}
+```
+
+## Anti-Patterns
+
+### Avoid !important
+
+```css
+/* Bad */
+.button { color: red !important; }
+
+/* Good: Use specificity correctly */
+.button.button-danger { color: red; }
+```
+
+### Avoid Inline Styles for Theming
+
+```tsx
+// Bad
+<div style={{ color: isError ? 'red' : 'green' }}>
+
+// Good: Use classes/data attributes
+<div className={isError ? 'text-error' : 'text-success'}>
+<div data-state={isError ? 'error' : 'success'}>
+```
+
+### Avoid Magic Numbers
+
+```css
+/* Bad */
+.header { height: 73px; }
+
+/* Good */
+.header { height: var(--header-height); }
+```