wcz-layout/skills/general/SKILL.md

---
name: general
description: "Use ALWAYS for project-wide conventions and coding standards. It defines the default style, rules, and best practices that apply to every file and feature."
---

> This is the default skill. Reference it in combination with more specific skills (e.g., `forms`, `data-grid`, `dialogs`) for targeted tasks.

## Preferred Technology Stack

Favor the established platform before introducing custom code or a new dependency:

- **TanStack ecosystem:** Use TanStack Start, Router, DB, Form, and Query for their respective application concerns. Consider adjacent TanStack libraries when they directly fit the feature: TanStack AI for AI interactions, TanStack Virtual for large virtualized lists, TanStack Pacer for debouncing, throttling, rate limiting, queuing, and batching, and TanStack Hotkeys for type-safe keyboard shortcuts.
- **Vite+:** Use Vite+ for the development server, formatting, linting and testing.
- **Material UI:** Use Material UI for interface components and icons. When an advanced capability is needed, consider MUI X Charts for data visualization, Tree View for hierarchical data, Scheduler for calendars and timelines, and Chat for AI-powered conversations.

Before implementing an external library feature, consult the current documentation through Context7 MCP. Do not add a new dependency when one of these platform libraries already covers the requirement.

When the requirement is not covered above and a well-maintained, popular library solves it, use that library instead of writing your own implementation.

## Coding Conventions

- Generate modern ES6+ TypeScript with explicit types and never use `any`.
- Stick to double quotes, semicolons, and the `~/` alias for `src/` imports.
- Avoid `useMemo` / `useCallback`; the React Compiler handles memoization.
- Keep code self-documenting; only add comments to clarify non-obvious intent.

## User Interface

- Format all client-side dates with `"L LT"` or `"L"`.
- Build skeletons for loading states.
- When building UI, always design for both light and dark mode; this app uses `colorSchemeSelector: "data-mui-color-scheme"`, so prefer `theme.applyStyles("dark", ...)` for mode-specific styling.

## File Organization

Use this ownership model for new application code. Keep feature-specific code close to its route; promote it to a root directory only when it is shared across multiple features. One database table = one file per layer: every `<table>` slot below is the same singular camelCase table name, never grouped with its parent or child tables.

```txt
src/                           # client-first architecture
├── components/                # shared components across multiple routes
├── db-collections/            # TanStack DB collections
│   └── <table>Collection.ts
├── hooks/                     # shared hooks across multiple routes
├── lib/                       # isomorphic/shared logic usable by client and server
│   ├── auth/
│   │   ├── permissions.ts
│   │   └── scopes.ts
│   ├── locales/
│   │   ├── cs.json
│   │   └── en.json
│   └── schemas/               # shared Zod schemas
│       └── <table>.ts
├── routes/                    # TanStack Router file-based routing
│   ├── __root.tsx
│   ├── index.tsx
│   └── features/              # feature folder with multiple routes (kebab-case, plural)
│       ├── -components/       # route-specific components
│       ├── -hooks/            # route-specific hooks
│       ├── index.tsx
│       ├── create.tsx
│       ├── $id.tsx
│       └── edit.$id.tsx
├── server/                    # server-only code
│   ├── actions/
│   │   └── <table>.ts
│   ├── db/
│   │   ├── migrations/
│   │   ├── schemas/           # Drizzle schemas
│   │   │   ├── <table>.ts
│   │   │   └── relations.ts
│   │   └── index.ts
│   └── middleware/
│       └── databaseMiddleware.ts
└── types/
tests/
├── unit/
│   ├── lib/
│   │   └── schemas/
│   │       └── <table>.test.ts
│   ├── hooks/
│   │   └── useX.test.ts
│   └── routes/
│       └── features/
│           └── -components/
│               └── XCard.test.tsx
├── integration/
│   ├── server/
│   │   └── actions/
│   │       └── <table>.test.ts
│   └── db-collections/
│       └── <table>Collection.test.ts
└── e2e/
    └── features/
        └── create.spec.ts
```