From 229918e912638e795a7cfb181ca08ee6a99946dd Mon Sep 17 00:00:00 2001 From: Marc Mintel Date: Mon, 2 Feb 2026 12:13:19 +0100 Subject: [PATCH] feat: overhaul style guide to define a 'Digital Architect' aesthetic with detailed design principles and UI/UX guidelines. --- docs/STYLEGUIDE.md | 128 +++++++++++++++++++-------------------------- 1 file changed, 54 insertions(+), 74 deletions(-) diff --git a/docs/STYLEGUIDE.md b/docs/STYLEGUIDE.md index 8bc3e27..aea308e 100644 --- a/docs/STYLEGUIDE.md +++ b/docs/STYLEGUIDE.md @@ -1,94 +1,74 @@ -# Style Guide +# Style Guide: Digital Architect -This document outlines the coding standards, design patterns, and UI guidelines for the mintel.me project. +This document defines the visual language and design rules for the Mintel ecosystem. The goal is to maintain a "Digital Architect" aesthetic: technical, reductionist, and high-fidelity. -## 1. General Principles +## 1. Core Philosophy: Reduction to Essentials -- **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. +The design should feel "Websites ohne Overhead." Every element must serve a purpose. If it doesn't add value, remove it. -## 2. Technology Stack +- **Technical Precision**: Use grids, mono-spaced labels, and clear hierarchies to signal technical competence. +- **Tactile Digital Objects**: UI elements should feel like physical objects (buttons that depress, tags that pop in, glass that blurs). +- **High Contrast**: Bold black/slate on clean white backgrounds, with vibrant highlighter accents. -- **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/) +## 2. Color Palette -## 3. Component Guidelines +The project uses a monochrome base with curated highlighter accents. -### 3.1 Structure -- Use functional components with `React.FC`. -- Define props using an `interface`. -- Export components as named exports. +- **Primary Base**: + - **Backgrounds**: Pure White (`#ffffff`) for clarity. + - **Surfaces**: Slate-50 for subtle depth, White with 90% opacity + 10px blur for glassmorphism. +- **Grays (Slate)**: + - **Text**: Slate-800 for body, Slate-900 for headings. + - **UI Borders**: Slate-100 or Slate-200. + - **Muted text**: Slate-400 or Slate-500. +- **Highlighter Accents**: Used exclusively for tags, markers, and selective emphasis. + - **Yellow**: Warm, high-visibility (`rgba(255, 235, 59, 0.95)`). + - **Pink**: Vibrant, energetic (`rgba(255, 167, 209, 0.95)`). + - **Green**: Success, technical health (`rgba(129, 199, 132, 0.95)`). + - **Blue**: Neutral, structural (`rgba(226, 232, 240, 0.95)`). -```tsx -import React from 'react'; +## 3. Typography -interface MyComponentProps { - title: string; - children?: React.ReactNode; -} +A high-contrast mix of fonts that balances modern tech with editorial readability. -export const MyComponent: React.FC = ({ title, children }) => { - return ( -
-

{title}

- {children} -
- ); -}; -``` +- **Headings (Sans-serif)**: Use **Inter**. + - Tracking: `-0.025em` to `-0.05em` (tracking-tighter). + - Weight: Bold (`700`). + - Color: Slate-900. +- **Body (Serif)**: Use **Newsreader** or Georgia. + - Style: Defaults to serif for long-form content to provide a "notebook" feel. + - Line-height: Relaxed (`1.6` to `1.75`). +- **Technical (Monospace)**: Use **JetBrains Mono**. + - Usage: Small labels, tags, code snippets, and "Mono-Labels" (e.g., section numbers). + - Feature: Uppercase with wide tracking (`0.3em` to `0.4em`). -### 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. +## 4. Layout & Rhythm -### 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`). +Standardized containers ensure consistency across different screen sizes. -## 4. Styling & Design +- **Standard Container**: Max-width 6xl (`72rem`). Used for most page sections. +- **Wide Container**: Max-width 7xl (`80rem`). Used for galleries or high-impact visuals. +- **Narrow Container**: Max-width 4xl (`56rem`). Used for focused reading and blog posts. +- **Section Rhythm**: Sections are separated by clear `border-top` lines and numbered (e.g., "01", "02"). -### 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). +## 5. UI Elements & Interactions -### 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.). +### 5.1 Buttons +- **Shape**: Always pill-shaped (rounded-full). +- **Style**: Thin borders (`1px`) with bold, uppercase mono-spaced text. +- **Hover**: Should feel "expensive." Smooth translate-up (`-0.5rem`) and deep, soft shadows. -### 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). +### 5.2 Cards & Containers +- **Glassmorphism**: Use for search boxes and floating elements (`backdrop-filter: blur(10px)`). +- **Cards**: Minimalist. Use `Slate-50` or thin `Slate-100` borders. Avoid heavy shadows unless on hover. -### 4.4 Animations -Use built-in Tailwind animations for subtle transitions: -- `animate-fade-in` -- `animate-slide-up` -- `animate-slide-down` +### 5.3 Highlighters & Tags +- **Marker Effect**: Use a hand-drawn marker underline (diagonal skew, slightly erratic rotation) for key titles. +- **Tags**: Small, bold, uppercase. They should use `tagPopIn` animations when appearing. -## 5. Best Practices +## 6. Motion & Atmosphere -- **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). +- **Reveals**: Content should never "just appear." Use slide-up and fade-in transitions (`0.5s` to `0.7s`) to create a sense of discovery. +- **Background Grid**: A subtle, low-opacity grid pattern provides a technical "blueprint" feel to the pages. +- **Micro-interactions**: Hovering over icons or tags should trigger subtle scales (`105%-110%`) and color shifts. -## 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.