feat: add new skills for coding standards, continuous learning, detail layout, form layout, project guidelines, security review, and verification loop
- Introduced coding standards for TypeScript and React in SKILL.md. - Added continuous learning skill with configuration and evaluation scripts. - Created detail layout guidelines for read-only pages. - Established form layout rules for data-entry forms. - Documented project guidelines for the frontend monorepo. - Implemented security review checklist for frontend/Electron applications. - Developed a verification loop skill for comprehensive session checks. This commit enhances the skill set available for developers, ensuring adherence to best practices and improving code quality.
This commit is contained in:
shancheas
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: When to use planner, architect, tdd-guide, code-reviewer, and other agents; parallel Task execution
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Agent Orchestration
|
||||
|
||||
## Layout
|
||||
|
||||
- Agents: `.cursor/agents/`
|
||||
- Skills: `.agents/skills/`
|
||||
- Rules: `.cursor/rules/`
|
||||
- Hooks: `.cursor/hooks.json` and `.cursor/hooks/`
|
||||
|
||||
## Available Agents
|
||||
|
||||
| Agent | Purpose | When to Use |
|
||||
| -------------------- | ----------------------- | ----------------------------- |
|
||||
| planner | Implementation planning | Complex features, refactoring |
|
||||
| architect | System design | Architectural decisions |
|
||||
| tdd-guide | Test-driven development | New features, bug fixes |
|
||||
| code-reviewer | Code review | After writing code |
|
||||
| security-reviewer | Security analysis | Before commits |
|
||||
| build-error-resolver | Fix build errors | When build fails |
|
||||
| e2e-runner | Frontend journeys | Vitest + RTL, browser flows |
|
||||
| refactor-cleaner | Dead code cleanup | Code maintenance |
|
||||
| doc-updater | Documentation | Updating docs |
|
||||
|
||||
## Immediate Agent Usage
|
||||
|
||||
No user prompt needed:
|
||||
|
||||
1. Complex feature requests - Use **planner** agent
|
||||
2. Code just written/modified - Use **code-reviewer** agent
|
||||
3. Bug fix or new feature - Use **tdd-guide** agent
|
||||
4. Architectural decision - Use **architect** agent
|
||||
|
||||
## Parallel Task Execution
|
||||
|
||||
ALWAYS use parallel Task execution for independent operations:
|
||||
|
||||
```markdown
|
||||
# GOOD: Parallel execution
|
||||
|
||||
Launch 3 agents in parallel:
|
||||
|
||||
1. Agent 1: Security analysis of auth.ts
|
||||
2. Agent 2: Performance review of cache system
|
||||
3. Agent 3: Type checking of utils.ts
|
||||
|
||||
# BAD: Sequential when unnecessary
|
||||
|
||||
First agent 1, then agent 2, then agent 3
|
||||
```
|
||||
|
||||
## Multi-Perspective Analysis
|
||||
|
||||
For complex problems, use split role sub-agents:
|
||||
|
||||
- Factual reviewer
|
||||
- Senior engineer
|
||||
- Security expert
|
||||
- Consistency reviewer
|
||||
- Redundancy checker
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
description: Immutability, file organization, error handling, and input validation
|
||||
globs: "**/*.{ts,tsx,js,jsx}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Coding Style
|
||||
|
||||
## Immutability (CRITICAL)
|
||||
|
||||
ALWAYS create new objects, NEVER mutate:
|
||||
|
||||
```javascript
|
||||
// WRONG: Mutation
|
||||
function updateUser(user, name) {
|
||||
user.name = name // MUTATION!
|
||||
return user
|
||||
}
|
||||
|
||||
// CORRECT: Immutability
|
||||
function updateUser(user, name) {
|
||||
return {
|
||||
...user,
|
||||
name
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
MANY SMALL FILES > FEW LARGE FILES:
|
||||
- High cohesion, low coupling
|
||||
- 200-400 lines typical, 800 max
|
||||
- Extract utilities from large components
|
||||
- Organize by feature/domain, not by type
|
||||
|
||||
## Error Handling
|
||||
|
||||
ALWAYS handle errors comprehensively:
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await riskyOperation()
|
||||
return result
|
||||
} catch (error) {
|
||||
console.error('Operation failed:', error)
|
||||
throw new Error('Detailed user-friendly message')
|
||||
}
|
||||
```
|
||||
|
||||
## Input Validation
|
||||
|
||||
ALWAYS validate user input with Zod schemas and `@repo/ui/validators` (`compose`, `required`, `rangeLength`, …). Do not introduce class-validator DTOs.
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email(),
|
||||
age: z.number().int().min(0).max(150)
|
||||
})
|
||||
|
||||
const validated = schema.parse(input)
|
||||
```
|
||||
|
||||
## Code Quality Checklist
|
||||
|
||||
Before marking work complete:
|
||||
- [ ] Code is readable and well-named
|
||||
- [ ] Functions are small (<50 lines)
|
||||
- [ ] Files are focused (<800 lines)
|
||||
- [ ] No deep nesting (>4 levels)
|
||||
- [ ] Proper error handling
|
||||
- [ ] No console.log statements
|
||||
- [ ] No hardcoded values
|
||||
- [ ] No mutation (immutable patterns used)
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
description: trackgo-fe monorepo map — apps, packages, where to develop
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# trackgo-fe Overview
|
||||
|
||||
pnpm + Turborepo monorepo. Work from the repository root. Package manager: `pnpm@8.15.6`.
|
||||
|
||||
## Where to work
|
||||
|
||||
| Role | Path | Notes |
|
||||
|---|---|---|
|
||||
| **Product development** | `apps/web/` | Primary app — features, auth, modules |
|
||||
| **Component / API reference** | `apps/showcase/` | Living demos of `@repo/*` usage — copy patterns, do not ship product here |
|
||||
| Deep docs | `apps/docs-dev/` | VitePress (`pnpm dev:docs-dev`) |
|
||||
| Shared UI / forms / foundations | `packages/ui` → `@repo/ui/*` | |
|
||||
| HTTP, data services, telemetry | `packages/core-api` → `@repo/core-api/*` | |
|
||||
| Storage | `packages/core-storage` → `@repo/core-storage` | |
|
||||
| i18n | `packages/core-i18n` → `@repo/core-i18n` | |
|
||||
| Events | `packages/core-events` → `@repo/core-events` | |
|
||||
| Shared utilities | `packages/utils` → `@repo/utils` | |
|
||||
| Brand assets | `packages/brand` → `@repo/brand` | |
|
||||
| Tooling configs | `packages/configs` | ESLint + TypeScript bases |
|
||||
| Desktop wrapper | `apps/desktop/` | Embeds `apps/web` via Electron |
|
||||
| Landing | `apps/landing/` | Marketing SPA only |
|
||||
|
||||
## Hard rules
|
||||
|
||||
- Implement product features in `apps/web`, not in `showcase` or `docs-dev`.
|
||||
- Before inventing UI or package usage, match `apps/showcase` demos and `apps/docs-dev` docs.
|
||||
- Prefer `@repo/ui`, `@repo/core-*`, `@repo/utils` over app-local duplicates or raw Mantine/axios.
|
||||
- Env files live **inside the app** (`apps/web/.env*`), never at monorepo root. Read env via `src/core/environment` (`ENV`), not `import.meta.env` in components.
|
||||
- Run scripts from root: `pnpm dev:web`, `pnpm dev:showcase`, `pnpm lint`, `pnpm typecheck:web`, `pnpm test`, `pnpm check:all`.
|
||||
|
||||
## Import map (preferred)
|
||||
|
||||
```ts
|
||||
import { Button, Text } from '@repo/ui/components';
|
||||
import { FieldTextInput } from '@repo/ui/form'; // or @repo/ui/components
|
||||
import { EnterpriseModuleProvider } from '@repo/ui/foundations';
|
||||
import { compose, required } from '@repo/ui/validators';
|
||||
import { createHttpClient } from '@repo/core-api/http-client';
|
||||
import { CommonRemoteDataServices } from '@repo/core-api/data-services';
|
||||
import { useTranslation, Trans } from '@repo/core-i18n';
|
||||
```
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: Commit message format, PR workflow, and feature implementation steps
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Git Workflow
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```
|
||||
<type>: <description>
|
||||
|
||||
<optional body>
|
||||
```
|
||||
|
||||
Types: feat, fix, refactor, docs, test, chore, perf, ci
|
||||
|
||||
Keep commit messages conventional. Do not add AI attribution trailers.
|
||||
|
||||
## Pull Request Workflow
|
||||
|
||||
When creating PRs:
|
||||
1. Analyze full commit history (not just latest commit)
|
||||
2. Use `git diff [base-branch]...HEAD` to see all changes
|
||||
3. Draft comprehensive PR summary
|
||||
4. Include test plan with TODOs
|
||||
5. Push with `-u` flag if new branch
|
||||
|
||||
## Feature Implementation Workflow
|
||||
|
||||
1. **Plan First**
|
||||
- Use **planner** agent to create implementation plan
|
||||
- Identify dependencies and risks
|
||||
- Break down into phases
|
||||
|
||||
2. **TDD Approach**
|
||||
- Use **tdd-guide** agent
|
||||
- Write tests first (RED)
|
||||
- Implement to pass tests (GREEN)
|
||||
- Refactor (IMPROVE)
|
||||
- Verify 80%+ coverage
|
||||
|
||||
3. **Code Review**
|
||||
- Use **code-reviewer** agent immediately after writing code
|
||||
- Address CRITICAL and HIGH issues
|
||||
- Fix MEDIUM issues when possible
|
||||
|
||||
4. **Commit & Push**
|
||||
- Detailed commit messages
|
||||
- Follow conventional commits format
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
description: Cursor hooks system, auto-accept permissions, and TodoWrite practices
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Hooks System
|
||||
|
||||
Project hooks live in `.cursor/hooks.json` (schema version 1) and scripts under `.cursor/hooks/` and `.cursor/scripts/hooks/`.
|
||||
|
||||
## Hook Events
|
||||
|
||||
- **sessionStart / sessionEnd**: Load and persist session context
|
||||
- **preCompact**: Save state before context compaction
|
||||
- **afterFileEdit**: Suggest strategic compact after edits
|
||||
- **beforeShellExecution**: Gate long-running servers and `git push`
|
||||
|
||||
## Current Project Hooks
|
||||
|
||||
### sessionStart
|
||||
- Load previous session files from `.cursor/sessions/`
|
||||
- Detect package manager
|
||||
- Report learned skills in `.agents/skills/learned/`
|
||||
|
||||
### sessionEnd
|
||||
- Persist session state
|
||||
- Evaluate the session for extractable patterns
|
||||
|
||||
### preCompact
|
||||
- Log compaction and append a note to the active session file
|
||||
|
||||
### afterFileEdit
|
||||
- Suggest manual compaction after many edits
|
||||
|
||||
### beforeShellExecution
|
||||
- Ask before running dev servers outside tmux
|
||||
- Ask before `git push`
|
||||
|
||||
## Auto-Accept Permissions
|
||||
|
||||
Use with caution:
|
||||
- Enable for trusted, well-defined plans
|
||||
- Disable for exploratory work
|
||||
- Never skip permissions for git push, installs, or production commands
|
||||
|
||||
## TodoWrite Best Practices
|
||||
|
||||
Use TodoWrite to:
|
||||
- Track progress on multi-step tasks
|
||||
- Verify understanding of instructions
|
||||
- Show granular implementation steps
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
description: Model selection, context window management, and build troubleshooting
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Performance Optimization
|
||||
|
||||
## Model Selection Strategy
|
||||
|
||||
**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
|
||||
- Lightweight agents with frequent invocation
|
||||
- Pair programming and code generation
|
||||
- Worker agents in multi-agent systems
|
||||
|
||||
**Sonnet 4.5** (Best coding model):
|
||||
- Main development work
|
||||
- Orchestrating multi-agent workflows
|
||||
- Complex coding tasks
|
||||
|
||||
**Opus 4.5** (Deepest reasoning):
|
||||
- Complex architectural decisions
|
||||
- Maximum reasoning requirements
|
||||
- Research and analysis tasks
|
||||
|
||||
## Context Window Management
|
||||
|
||||
Avoid last 20% of context window for:
|
||||
- Large-scale refactoring
|
||||
- Feature implementation spanning multiple files
|
||||
- Debugging complex interactions
|
||||
|
||||
Lower context sensitivity tasks:
|
||||
- Single-file edits
|
||||
- Independent utility creation
|
||||
- Documentation updates
|
||||
- Simple bug fixes
|
||||
|
||||
## Ultrathink + Plan Mode
|
||||
|
||||
For complex tasks requiring deep reasoning:
|
||||
1. Use `ultrathink` for enhanced thinking
|
||||
2. Enable **Plan Mode** for structured approach
|
||||
3. "Rev the engine" with multiple critique rounds
|
||||
4. Use split role sub-agents for diverse analysis
|
||||
|
||||
## Build Troubleshooting
|
||||
|
||||
If build fails:
|
||||
1. Use **build-error-resolver** agent
|
||||
2. Analyze error messages
|
||||
3. Fix incrementally
|
||||
4. Verify after each fix
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
description: Mandatory security checks for this SPA/Electron frontend
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Security Guidelines
|
||||
|
||||
## Mandatory Security Checks
|
||||
|
||||
Before ANY commit:
|
||||
|
||||
- [ ] No hardcoded secrets (API keys, passwords, tokens)
|
||||
- [ ] All user inputs validated (Zod + `@repo/ui/validators`)
|
||||
- [ ] XSS prevention — React text nodes by default; never unsanitized `dangerouslySetInnerHTML`
|
||||
- [ ] Auth tokens only via `src/core/lib/auth.helper` and the shared `apiClient` interceptors
|
||||
- [ ] No secrets in client bundles; env files only under `apps/*/.env*`
|
||||
- [ ] Error messages shown to users do not leak tokens or stack traces
|
||||
|
||||
This is a browser/Electron client. Do not invent SQL injection, CSRF-on-API-endpoints, or API rate-limiting checks here — those belong to the backend.
|
||||
|
||||
## Secret Management
|
||||
|
||||
```typescript
|
||||
// NEVER: Hardcoded secrets
|
||||
const apiKey = "sk-proj-xxxxx"
|
||||
|
||||
// ALWAYS: App env wrapper (apps/web)
|
||||
import { ENV } from '../environment'
|
||||
|
||||
if (!ENV.API_BASE_URL) {
|
||||
throw new Error('VITE_API_BASE_URL is not configured')
|
||||
}
|
||||
```
|
||||
|
||||
- Env files: `apps/web/.env*` (see `apps/web/.env.example`). Never at monorepo root.
|
||||
- Components read `ENV` from `src/core/environment`, not `import.meta.env` directly.
|
||||
- `VITE_*` values are public to the client. Do not put private credentials in Vite env except documented local-dev CouchDB fields.
|
||||
|
||||
## Auth and storage
|
||||
|
||||
- HTTP: singleton `apiClient` from `src/core/lib/api-client` — never raw axios.
|
||||
- Session teardown: `terminateAuthSession` in `auth.helper`.
|
||||
- Do not store tokens in source. Do not log access tokens.
|
||||
|
||||
## Electron
|
||||
|
||||
When touching `apps/desktop/`: keep `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true`. Do not expose Node APIs on `window` outside the existing preload bridge.
|
||||
|
||||
## Security Response Protocol
|
||||
|
||||
If a security issue is found:
|
||||
|
||||
1. STOP immediately
|
||||
2. Use **security-reviewer** agent
|
||||
3. Fix CRITICAL issues before continuing
|
||||
4. Rotate any exposed secrets
|
||||
5. Review the rest of the codebase for the same pattern
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
description: Use apps/showcase as the reference for UI components and @repo package APIs
|
||||
globs: apps/{web,showcase}/**/*.{ts,tsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Showcase = Component & Function Reference
|
||||
|
||||
`apps/showcase` is the living cookbook. Prefer copying its import paths and composition patterns into `apps/web`. Do not add product business logic to showcase.
|
||||
|
||||
## Demo → capability map
|
||||
|
||||
| Showcase route / folder | What to learn | Prefer importing from |
|
||||
|---|---|---|
|
||||
| `pages/ui-components` | Theme, Badge, Button, inputs, Table, StatusBadge | `@repo/ui/components`, `@repo/ui/provider` |
|
||||
| `pages/forms` (+ `form-demo`) | RHF fields, Zod, async selects, rich text | `@repo/ui/form`, `@repo/ui/validators` |
|
||||
| `pages/shell-demo` | CoreAppShell layouts | `@repo/ui/components` (`CoreAppShell`) |
|
||||
| `pages/action-tools` | PageActions / RowActions | `@repo/ui/components` |
|
||||
| `pages/ag-grid` | Enterprise grid + theme | `@repo/ui/components` / `@repo/ui/ag-grid` |
|
||||
| `pages/storage` | Local + PouchDB patterns | `@repo/core-storage` (+ app `core/storage`) |
|
||||
| `pages/events` | Event bus, listeners, transformers | `@repo/core-events`, `@repo/core-api` |
|
||||
| `pages/auth`, `pages/rbac`, `pages/hardware` | Auth/RBAC/printer IPC samples | Match showcase; wire real flows in `apps/web` |
|
||||
|
||||
Run: `pnpm dev:showcase` → typically `http://localhost:517x`.
|
||||
|
||||
## Usage rules
|
||||
|
||||
- **Primitives**: `@repo/ui/components` (Mantine re-exports + StatusBadge, AppShell, etc.).
|
||||
- **Form fields**: `Field*` from `@repo/ui/form` (also re-exported from `@repo/ui/components`). Pair with `react-hook-form` + `zod` + `@repo/ui/validators` (`compose`, `required`, `rangeLength`, …).
|
||||
- **Module pages in web**: foundations (`Enterprise*Provider`, `EnterpriseDataTable`) — see `apps/web` example module; showcase shows building blocks, web shows full module wiring.
|
||||
- **Theme**: wrap with `ThemeProvider` from `@repo/ui/provider`; drive scheme/density like showcase `theme.store`.
|
||||
- If showcase and docs disagree, prefer **showcase code** for API shape and **docs-dev** for concepts.
|
||||
|
||||
```tsx
|
||||
// ✅ GOOD — same surface as showcase form-demo
|
||||
import { FieldTextInput, FieldSelect } from '@repo/ui/form';
|
||||
import { Button, Stack } from '@repo/ui/components';
|
||||
|
||||
// ❌ BAD — raw Mantine bypassing the design system
|
||||
import { TextInput } from '@mantine/core';
|
||||
```
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
description: TDD workflow, 80% coverage minimum, Vitest unit tests, and browser journey verification
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Testing Requirements
|
||||
|
||||
## Minimum Test Coverage: 80%
|
||||
|
||||
Test types:
|
||||
|
||||
1. **Unit tests** — pure functions, transformers, validators, stores, utilities (`*.test.ts` / `*.test.tsx`, colocated or `__tests__/`)
|
||||
2. **Component tests** — Testing Library in packages that already have it (`packages/ui`, `packages/core-events`)
|
||||
3. **App journeys** — browser verification of `apps/web` flows (login, index / form / detail). There is no Playwright or NestJS E2E suite in this repo.
|
||||
|
||||
Runner: **Vitest**. Root command: `pnpm test`. Per-package: `pnpm --filter <pkg> test`. Also `pnpm typecheck` and `pnpm check:all`.
|
||||
|
||||
## Test-Driven Development
|
||||
|
||||
MANDATORY workflow:
|
||||
|
||||
1. Write test first (RED)
|
||||
2. Run test — it should FAIL
|
||||
3. Write minimal implementation (GREEN)
|
||||
4. Run test — it should PASS
|
||||
5. Refactor (IMPROVE)
|
||||
6. Verify coverage (80%+)
|
||||
|
||||
## Troubleshooting Test Failures
|
||||
|
||||
1. Use **tdd-guide** agent
|
||||
2. Check test isolation
|
||||
3. Verify mocks are correct (`@repo/core-api` services, HTTP client — not a database)
|
||||
4. Fix implementation, not tests (unless tests are wrong)
|
||||
|
||||
## Agent Support
|
||||
|
||||
- **tdd-guide** — Use PROACTIVELY for new features, enforces write-tests-first
|
||||
- **e2e-runner** — Frontend journeys: Vitest + Testing Library, plus browser verification for `apps/web`
|
||||
- Skill: `.agents/skills/tdd-workflow/`
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: Where to place shared vs module-local code in apps/web (core vs modules)
|
||||
globs: apps/web/src/**/*.{ts,tsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Web Core vs Modules Placement
|
||||
|
||||
Working directory: `apps/web/`.
|
||||
|
||||
## Placement decision
|
||||
|
||||
| Code kind | Location |
|
||||
|---|---|
|
||||
| Feature / business screen | `src/apps/main/modules/<group>/<feature>/` |
|
||||
| Auth flows | `src/apps/auth/` |
|
||||
| App shell, nav, bookmarks, history | `src/apps/main/layouts/` |
|
||||
| Reusable across **2+ modules** (hook, component, util, store, storage, client) | `src/core/` |
|
||||
| Shared across **apps** (web + showcase + landing + desktop) | `packages/*` (`@repo/ui`, `@repo/core-api`, …) — not `src/core/` |
|
||||
|
||||
## `src/core/` structure
|
||||
|
||||
```text
|
||||
src/core/
|
||||
assets/ # App logos, static assets
|
||||
components/ # App-wide UI (e.g. loading-screen)
|
||||
constants/ # App-wide constants / event keys / urls
|
||||
environment/ # ENV config
|
||||
hooks/ # Cross-module hooks (Electron, etc.)
|
||||
lib/ # Singletons (api-client, auth.helper)
|
||||
storage/ # Local / PouchDB adapters
|
||||
stores/ # Cross-module client state (theme, …)
|
||||
```
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Do not** put feature-specific entities, validators, or page UI in `src/core/`.
|
||||
- **Do not** duplicate `apiClient`, storage, or theme logic inside a module — import from `src/core/`.
|
||||
- Module domain factories must use `apiClient` from `src/core/lib/api-client`.
|
||||
- One-module helpers stay under that module’s `domain/` or `presentation/`.
|
||||
- Promote to `src/core/` when a second module needs it; promote to `packages/` when another app needs it.
|
||||
|
||||
```typescript
|
||||
// ❌ BAD — module invents its own HTTP client
|
||||
const client = axios.create({ baseURL: '...' });
|
||||
|
||||
// ✅ GOOD — shared singleton (same pattern as example/full-page domain factory)
|
||||
import { apiClient } from '../../../../../../../core/lib/api-client';
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: Standard design and layout for apps/web module pages
|
||||
globs: apps/web/src/apps/**/*.{ts,tsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Web Design & Layout Standards
|
||||
|
||||
Working directory: `apps/web/`.
|
||||
Primitives: `@repo/ui/components`. Foundations: `@repo/ui/foundations`. Icons: `lucide-react`.
|
||||
Reference usage: `apps/showcase` (ui-components, forms, action-tools, shell-demo).
|
||||
|
||||
## App chrome (do not rebuild)
|
||||
|
||||
- Authenticated routes render inside `ModuleLayout` → `CoreAppShell`.
|
||||
- Do not nest another `CoreAppShell` inside a feature module.
|
||||
- Sidebar / header / history / bookmarks live only under `apps/main/layouts/`.
|
||||
|
||||
## Page composition
|
||||
|
||||
| Page type | Standard wrapper |
|
||||
|---|---|
|
||||
| List / index (FULL_PAGE) | `EnterpriseIndexPageProvider` + `EnterpriseDataTable` |
|
||||
| Detail (FULL_PAGE) | `EnterpriseDetailPageProvider` |
|
||||
| Form | `EnterpriseFormPageProvider` |
|
||||
| Simple / system page | Match existing `modules/system/*` patterns |
|
||||
|
||||
Detail **content** layout (section stack, key-value grids, status blocks, tabs for many categories): follow `.agents/skills/detail-layout/SKILL.md` — layout/position only.
|
||||
Form **content** layout: follow `.agents/skills/form-layout/SKILL.md`.
|
||||
|
||||
Every page header (`pageHeaderProps`) should include i18n `title`, `description`, `breadcrumbs`, and Lucide `icon` when useful.
|
||||
|
||||
```tsx
|
||||
// ✅ GOOD
|
||||
<EnterpriseIndexPageProvider
|
||||
pageHeaderProps={{
|
||||
title: t('title'),
|
||||
description: t('description'),
|
||||
icon: LayoutDashboard,
|
||||
breadcrumbs: [
|
||||
{ label: t('nav:example-module'), type: 'text' },
|
||||
{ label: t('nav:example-full-page'), type: 'text' },
|
||||
],
|
||||
}}
|
||||
>
|
||||
<EnterpriseDataTable columnDefs={columnDefs} filterConfig={filterConfig} />
|
||||
</EnterpriseIndexPageProvider>
|
||||
```
|
||||
|
||||
```tsx
|
||||
// ❌ BAD — custom chrome that duplicates foundations
|
||||
<Box p="md">
|
||||
<Title order={2}>{t('title')}</Title>
|
||||
</Box>
|
||||
```
|
||||
|
||||
## Visual language
|
||||
|
||||
- Theme via Mantine tokens / CSS vars — no hard-coded theme hex.
|
||||
- Surfaces: `Paper` / `Card` with `withBorder`, `radius="md"`, restrained `shadow="sm"`.
|
||||
- Status: `StatusBadge` / semantic `Badge` — see showcase `ui-components`.
|
||||
- Actions: `PageActions` / row actions from action-tools patterns.
|
||||
- Forms: `Field*` components + Zod validators — see showcase `forms` and `example/full-page` form.
|
||||
- Do not invent a parallel design system.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
description: Architecture for feature modules in apps/web (full-page pattern)
|
||||
globs: apps/web/src/apps/**/*.{ts,tsx}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Web Module Architecture
|
||||
|
||||
Working directory: `apps/web/`.
|
||||
Create authenticated features under `src/apps/main/modules/`.
|
||||
Canonical sample: `example/full-page/`.
|
||||
|
||||
## Directory layout
|
||||
|
||||
```text
|
||||
src/apps/main/modules/<group>/<feature>/
|
||||
data/ # *RemoteDataServices
|
||||
domain/
|
||||
constants/ # ModuleConfigEntity
|
||||
entities/ # Entity + DTO
|
||||
factories/ # Wire apiClient + service + transformer
|
||||
transformers/ # DTO ↔ entity
|
||||
validators/ # Zod factories (forms)
|
||||
presentation/
|
||||
factory/index.tsx # registerModuleNamespace + EnterpriseModuleProvider + routes
|
||||
pages/ # *.page.index | *.page.form | *.page.detail
|
||||
components/ # Module-local UI only
|
||||
store/ # Module zustand (if needed)
|
||||
languages/{en,id}/ # Module dictionaries
|
||||
index.tsx # Optional group router (see example/index.tsx)
|
||||
```
|
||||
|
||||
Register: lazy route in `src/apps/main/index.tsx` + menu entry in `src/apps/main/layouts/data/menu.data.ts`.
|
||||
Auth screens live under `src/apps/auth/` (separate from main modules).
|
||||
|
||||
## FULL_PAGE routes (sample)
|
||||
|
||||
`/index`, `/detail/:dataId`, `/create`, `/edit/:dataId`, `/duplicate/:dataId` — default redirect to `webUrl/index`.
|
||||
|
||||
| Page | Wrapper |
|
||||
|---|---|
|
||||
| Index | `EnterpriseIndexPageProvider` + `EnterpriseDataTable` |
|
||||
| Detail | `EnterpriseDetailPageProvider` |
|
||||
| Form | `EnterpriseFormPageProvider` + `FormPageType` |
|
||||
|
||||
Copy `example/full-page` — do not invent a third layout style.
|
||||
|
||||
## Required wiring
|
||||
|
||||
1. **Constants** — `ModuleConfigEntity`: `moduleKey`, `translationNamespace`, `apiUrl`, `webUrl`, `moduleCategory` (`FULL_PAGE` | `SINGLE_PAGE`), `moduleType` (`TRANSACTION` | `MASTER_DATA`).
|
||||
2. **Presentation factory** — `registerModuleNamespace` once at module scope; wrap routes in `EnterpriseModuleProvider`.
|
||||
3. **Domain factory** — singleton service via `apiClient` from `src/core/lib/api-client` (never raw axios).
|
||||
4. **i18n** — `useEnterpriseModuleTranslationContext()`; module keys unprefixed; shared via `common:` / `nav:`.
|
||||
5. **Navigation** — `useEnterpriseModuleNavigationContext()` helpers, not ad-hoc paths.
|
||||
|
||||
## Layer rules
|
||||
|
||||
- `presentation/` → `domain/` / `data/` via factories; never reverse.
|
||||
- Shared/reusable across modules → `src/core/` (see web-core-placement).
|
||||
- Prefer `@repo/ui/components` + `@repo/ui/foundations`; form fields via `@repo/ui/form`.
|
||||
- Pages: default export, lazy-loaded from the presentation factory.
|
||||
Reference in New Issue
Block a user