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 (App Router)
Language: TypeScript
Styling: Tailwind CSS
Icons: Lucide React

3. Component Guidelines

3.1 Structure

Use functional components with React.FC.
Define props using an interface.
Export components as named exports.

import React from 'react';

interface MyComponentProps {
  title: string;
  children?: React.ReactNode;
}

export const MyComponent: React.FC<MyComponentProps> = ({ title, children }) => {
  return (
    <div>
      <h2>{title}</h2>
      {children}
    </div>
  );
};

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.

3.1 KiB Raw Blame History