diff --git a/.claude/MEMORY.md b/.claude/MEMORY.md new file mode 100644 index 00000000..f81da343 --- /dev/null +++ b/.claude/MEMORY.md @@ -0,0 +1,62 @@ +# datum.net Project Rules + +## Stack +- **Framework**: Astro 5.x + TypeScript strict mode +- **Styling**: TailwindCSS v4 with CSS layers +- **Interactivity**: Alpine.js +- **Testing**: Playwright (E2E) + +## File Naming +| Type | Convention | Example | +|------|------------|---------| +| Components | PascalCase | `BlogItem.astro`, `NavMenu.astro` | +| Utils | camelCase + suffix | `dateUtils.ts`, `imageUtils.ts` | +| Libs | camelCase | `string.ts`, `postgres.ts` | +| Types | camelCase | `common.ts`, `navigation.ts` | +| Pages | kebab-case | `request-access.astro` | +| CSS | kebab-case + prefix | `components-blog.css`, `page-home.css` | + +## CSS Class Naming (BEM-like) +- **Single dash (-)**: children/elements → `nav-menu-item`, `content-title` +- **Double dash (--)**: variants/modifiers → `content-image--left`, `blog-featured--title` + +## Critical Rules +1. **No inline styles** - All styles go in CSS files under `src/v1/styles/` +2. **No inline Tailwind classes** - Put Tailwind in CSS with `@apply` +3. **No arbitrary values** - Check `@theme` layer for variables +4. **Start components with path comment** → `// src/components/Button.astro` +5. **Use path aliases** → `@components/*`, `@utils/*`, `@libs/*`, `@types/*`, `@v1/*` + +## CSS Organization +``` +src/v1/styles/ + base.css # Base styles + theme.css # Theme variables + variables.css # CSS custom properties + utilities.css # Global utilities + components-*.css # Component styles + page-*.css # Page-specific styles +``` + +## Astro Patterns +```astro +--- +// src/components/Example.astro +import type { ExampleProps } from '@types/common'; + +const { class: className = '', prop1, prop2 = 'default' } = Astro.props as ExampleProps; +--- +
+``` + +## Import Order +1. Astro imports +2. Local imports +3. Types (use `import type`) + +## Formatting +- Single quotes, semicolons required +- 2-space indent, 100 char width +- Trailing commas (ES5) + +See [detailed-rules.md](./detailed-rules.md) for full conventions. diff --git a/.claude/rules/detailed-rules.md b/.claude/rules/detailed-rules.md new file mode 100644 index 00000000..14c4d796 --- /dev/null +++ b/.claude/rules/detailed-rules.md @@ -0,0 +1,148 @@ +# Detailed Project Rules for datum.net + +## TypeScript Conventions + +### Type Safety +- Use `strict` TypeScript config (extends `astro/tsconfigs/strict`) +- Prefer `@ts-expect-error` over `@ts-ignore` +- Prefix unused variables with `_` (e.g., `_unusedParam`) +- Use `const` assertions: `as const` +- Explicit return types for public functions + +### JSDoc Pattern +```typescript +/** + * Brief description of function purpose + * @param paramName - Description of parameter + * @returns Description of return value + */ +export const functionName = (paramName: Type): ReturnType => { + // implementation +}; +``` + +### Path Aliases +| Alias | Path | +|-------|------| +| `@/*` | root | +| `@components/*` | `./src/components/*` | +| `@utils/*` | `./src/utils/*` | +| `@libs/*` | `./src/libs/*` | +| `@types/*` | `./src/types/*` | +| `@layouts/*` | `./src/layouts/*` | +| `@v1/*` | `./src/v1/*` | +| `@content/*` | `./src/content/*` | +| `@data/*` | `./src/data/*` | +| `@styles/*` | `./src/styles/*` | +| `@assets/*` | `./src/assets/*` | + +## TailwindCSS v4 Rules + +### DO +- Use `@layer components` for component styles +- Use `@apply` directive for Tailwind utilities +- Use nested SCSS format +- Check `@theme` for existing variables before adding custom values + +### DON'T +- No arbitrary values like `w-[123px]` +- No inline Tailwind classes in components +- No `