diff --git a/docs/STYLEGUIDE.md b/docs/STYLEGUIDE.md new file mode 100644 index 0000000..8bc3e27 --- /dev/null +++ b/docs/STYLEGUIDE.md @@ -0,0 +1,94 @@ +# Style Guide + +This document outlines the coding standards, design patterns, and UI guidelines for the mintel.me project. + +## 1. General Principles + +- **Simplicity**: Keep components small and focused on a single responsibility. +- **Consistency**: Use established patterns for naming, styling, and structure. +- **Accessibility**: Ensure high contrast, proper heading levels, and focus states. +- **Performance**: Optimize images and use efficient React patterns. + +## 2. Technology Stack + +- **Framework**: [Next.js](https://nextjs.org/) (App Router) +- **Language**: [TypeScript](https://www.typescript.org/) +- **Styling**: [Tailwind CSS](https://tailwindcss.com/) +- **Icons**: [Lucide React](https://lucide.dev/) + +## 3. Component Guidelines + +### 3.1 Structure +- Use functional components with `React.FC`. +- Define props using an `interface`. +- Export components as named exports. + +```tsx +import React from 'react'; + +interface MyComponentProps { + title: string; + children?: React.ReactNode; +} + +export const MyComponent: React.FC = ({ title, children }) => { + return ( +
+

{title}

+ {children} +
+ ); +}; +``` + +### 3.2 Client vs. Server Components +- Default to Server Components. +- Use `'use client'` only when necessary (interactivity, hooks, browser APIs). +- Keep client components at the leaves of the component tree. + +### 3.3 Naming Conventions +- **Files**: PascalCase (e.g., `Hero.tsx`, `ArticleHeading.tsx`). +- **Components**: PascalCase (e.g., `export const Hero`). +- **Props**: camelCase (e.g., `showIcon`). +- **Functions**: camelCase (e.g., `handleClick`). + +## 4. Styling & Design + +### 4.1 Typography +The project uses a mix of serif and sans-serif fonts: +- **Headings**: Sans-serif (Inter), bold, slate-900. +- **Body**: Serif (Georgia/Times New Roman) for readability in long-form content. +- **Code**: Monospace (JetBrains Mono). + +### 4.2 Colors +Defined in `tailwind.config.js`: +- **Primary**: Blue (`primary-50` to `primary-900`). +- **Slate**: Grays for text and backgrounds. +- **Highlighters**: Custom classes for tags (`highlighter-yellow`, `highlighter-pink`, etc.). + +### 4.3 Layout Containers +Use the following utility classes from `global.css`: +- `.container`: Max-width 4xl (standard content). +- `.wide-container`: Max-width 5xl (galleries, wide sections). +- `.narrow-container`: Max-width 2xl (focused reading). + +### 4.4 Animations +Use built-in Tailwind animations for subtle transitions: +- `animate-fade-in` +- `animate-slide-up` +- `animate-slide-down` + +## 5. Best Practices + +- **Tailwind Usage**: Prefer utility classes over custom CSS. Use `@apply` in `global.css` only for recurring base styles or complex component patterns. +- **Images**: Use `next/image` for optimization. +- **Links**: Use `next/link` for internal navigation. +- **Conditional Classes**: Use template literals or a utility like `clsx`/`tailwind-merge` if needed (though currently mostly template literals are used). + +## 6. Directory Structure + +- `app/`: Next.js pages and API routes. +- `src/components/`: Reusable UI components. +- `src/styles/`: Global CSS and Tailwind configuration. +- `src/utils/`: Helper functions and shared logic. +- `public/`: Static assets.