From 9880078a3dfb0934733357ec500e4ad59037124f Mon Sep 17 00:00:00 2001 From: martyy-code Date: Tue, 2 Jun 2026 12:20:26 +0200 Subject: [PATCH 01/19] docs: add custom favicon Co-Authored-By: Claude Opus 4.7 --- apps/web/src/app/favicon.svg | 109 +++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 apps/web/src/app/favicon.svg diff --git a/apps/web/src/app/favicon.svg b/apps/web/src/app/favicon.svg new file mode 100644 index 0000000..49c795b --- /dev/null +++ b/apps/web/src/app/favicon.svg @@ -0,0 +1,109 @@ + + + + + \ No newline at end of file From e2415b866cdff63f2ca8988de670617797fb3280 Mon Sep 17 00:00:00 2001 From: martyy-code Date: Tue, 2 Jun 2026 12:41:36 +0200 Subject: [PATCH 02/19] feat(homepage): create homepage with Flue-inspired design - Hero section with blueprint grid background - Navigation bar with logo and GitHub link - Code showcase with file header - Features grid (4 main + 3 secondary + CTA) - Before/after comparison section - Install section with npm commands - Footer with branding - Uses Inter font (Geist pending Next.js support) - rounded-none throughout per design system Co-Authored-By: Claude Opus 4.7 --- .../agent-memory/design-engineer/MEMORY.md | 4 + .../design-engineer/project-tech-stack.md | 29 + .../design-engineer/role-and-scope.md | 29 + .../agent-memory/technical-writer/MEMORY.md | 9 + .../documentation-writing-style.md | 77 +++ .../feedback-documentation-rules.md | 47 ++ .../technical-writer/fumadocs-components.md | 207 +++++++ .../fumadocs-docs-reference.md | 38 ++ .../technical-writer/fumadocs-meta-json.md | 71 +++ .../technical-writer/project-analysis.md | 69 +++ .../technical-writer/project-notes.md | 39 ++ .claude/agents/design-engineer/README.md | 11 + .claude/agents/technical-writer/README.md | 11 + .claude/settings.local.json | 3 +- DESIGN.md | 239 +++++++++ apps/web/src/app/(home)/page.tsx | 504 +++++++++++++++++- apps/web/src/app/layout.tsx | 1 + 17 files changed, 1375 insertions(+), 13 deletions(-) create mode 100644 .claude/agent-memory/design-engineer/MEMORY.md create mode 100644 .claude/agent-memory/design-engineer/project-tech-stack.md create mode 100644 .claude/agent-memory/design-engineer/role-and-scope.md create mode 100644 .claude/agent-memory/technical-writer/MEMORY.md create mode 100644 .claude/agent-memory/technical-writer/documentation-writing-style.md create mode 100644 .claude/agent-memory/technical-writer/feedback-documentation-rules.md create mode 100644 .claude/agent-memory/technical-writer/fumadocs-components.md create mode 100644 .claude/agent-memory/technical-writer/fumadocs-docs-reference.md create mode 100644 .claude/agent-memory/technical-writer/fumadocs-meta-json.md create mode 100644 .claude/agent-memory/technical-writer/project-analysis.md create mode 100644 .claude/agent-memory/technical-writer/project-notes.md create mode 100644 .claude/agents/design-engineer/README.md create mode 100644 .claude/agents/technical-writer/README.md create mode 100644 DESIGN.md diff --git a/.claude/agent-memory/design-engineer/MEMORY.md b/.claude/agent-memory/design-engineer/MEMORY.md new file mode 100644 index 0000000..e535223 --- /dev/null +++ b/.claude/agent-memory/design-engineer/MEMORY.md @@ -0,0 +1,4 @@ +# Design Engineer Memory Index + +- [Role & Scope](role-and-scope.md) — My responsibilities in apps/web +- [Tech Stack](project-tech-stack.md) — Current technologies and key files \ No newline at end of file diff --git a/.claude/agent-memory/design-engineer/project-tech-stack.md b/.claude/agent-memory/design-engineer/project-tech-stack.md new file mode 100644 index 0000000..85e512e --- /dev/null +++ b/.claude/agent-memory/design-engineer/project-tech-stack.md @@ -0,0 +1,29 @@ +--- +name: project-tech-stack +description: Tech stack of apps/web +type: reference +--- + +## apps/web Tech Stack + +| Category | Technology | +|----------|------------| +| Framework | Next.js 16.2.6 | +| UI Library | React 19.2.6 | +| Styling | Tailwind CSS v4.3.0 | +| CSS Processor | @tailwindcss/postcss 4.3.0 | +| Documentation | FumaDocs 16.9.1 (fumadocs-core, fumadocs-mdx, fumadocs-ui) | +| Icons | lucide-react 1.16.0 | +| Utility | tailwind-merge 3.6.0 | + +## Key Files + +- `src/app/global.css` — Global styles + Tailwind imports +- `src/app/layout.tsx` — Root layout with Inter font + RootProvider +- `src/lib/source.ts` — FumaDocs content loader +- `src/lib/shared.ts` — App config (name, routes, GitHub) +- `src/components/mdx.tsx` — MDX component factory + +## Package Manager + +pnpm (workspace monorepo) \ No newline at end of file diff --git a/.claude/agent-memory/design-engineer/role-and-scope.md b/.claude/agent-memory/design-engineer/role-and-scope.md new file mode 100644 index 0000000..25b1c87 --- /dev/null +++ b/.claude/agent-memory/design-engineer/role-and-scope.md @@ -0,0 +1,29 @@ +--- +name: role-and-scope +description: My role as Senior Design Engineer for apps/web +type: user +--- + +## Role + +Senior Design Engineer — responsible for all UI/UX design work in `apps/web`. + +## Scope + +- **Next.js 16** + React 19 +- **Tailwind CSS v4** (via `@tailwindcss/postcss`) +- **FumaDocs** for documentation site +- **shadcn/ui** — to be installed and integrated +- **lucide-react** for icons + +## Responsibilities + +- UI component design and implementation +- Tailwind theme customization +- Responsive design +- Design system consistency +- Integration with FumaDocs layouts + +## Working Directory + +`C:\Users\dpereira\Documents\github\deessejs-ecosystem\errors\.claude\worktrees\docs\apps\web` \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/MEMORY.md b/.claude/agent-memory/technical-writer/MEMORY.md new file mode 100644 index 0000000..ef4f314 --- /dev/null +++ b/.claude/agent-memory/technical-writer/MEMORY.md @@ -0,0 +1,9 @@ +# Technical Writer Memory Index + +- [Project Analysis](project-analysis.md) — Monorepo structure, tech stack, core library API, documentation status +- [Fumadocs Docs](fumadocs-docs-reference.md) — fumadocs.dev reference for MDX/UI components +- [Fumadocs meta.json](fumadocs-meta-json.md) — Navigation tree configuration +- [Fumadocs Components](fumadocs-components.md) — Complete components reference with Twoslash +- [Documentation Rules](feedback-documentation-rules.md) — h1/description forbidden, Cards for See Also, explanatory guides +- [Writing Style](documentation-writing-style.md) — Style from better-auth, Next.js, Fumadocs +- [Project Notes](project-notes.md) — First PR notes, Vercel config, theme, site config \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/documentation-writing-style.md b/.claude/agent-memory/technical-writer/documentation-writing-style.md new file mode 100644 index 0000000..dd03a8f --- /dev/null +++ b/.claude/agent-memory/technical-writer/documentation-writing-style.md @@ -0,0 +1,77 @@ +--- +name: documentation-writing-style +description: Writing style analysis from better-auth, Next.js, and Fumadocs +type: reference +--- + +# Documentation Writing Style Guide + +Analyzed from better-auth.com, nextjs.org/docs, and fumadocs.dev + +## Recurring Patterns + +### Structure +1. **Intro** — 1-2 contextual sentences before diving in +2. **Steps** — Numbered or bulleted sequences +3. **Code blocks** — Always with filename header or context +4. **Callouts** — Tips, warnings, "Good to know" +5. **Navigation** — "On this page" sidebar or related links at bottom +6. **See Also** — Cards at end of page for cross-linking + +### Code Blocks +- Include filename in header or comment above +- Show language/format +- Display in tabs when multiple options (npm/pnpm/yarn) +- Use transformers for highlighting (twoslash for types) + +### Callouts +- `info` (default) — general info +- `warn`/`warning` — caution +- `error` — danger +- `success` — positive outcome +- `idea` — tip or enhancement + +### Prose Style +- Short, action-oriented sentences ("Let's start by...") +- Explain WHY before showing HOW +- Contextual paragraphs between code blocks +- Tables for options/configuration +- Numbered steps for procedures + +### Navigation +- "On this page" in-page TOC (Fumadocs auto-generates) +- Cards at bottom for related pages +- Never bullet lists for related links + +## Template for New Pages + +```mdx +--- +title: Page Title +description: One-line SEO description +--- + +Intro paragraph explaining the concept in 1-2 sentences. + +## First Section + +Contextual prose... + +```ts filename.ts +// code here +``` + +More explanatory text. + +## Second Section + +... + +## See Also + + + + Brief description. + + +``` \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/feedback-documentation-rules.md b/.claude/agent-memory/technical-writer/feedback-documentation-rules.md new file mode 100644 index 0000000..188ae3e --- /dev/null +++ b/.claude/agent-memory/technical-writer/feedback-documentation-rules.md @@ -0,0 +1,47 @@ +--- +name: documentation-rules +description: Rules for writing documentation in @deessejs/errors +type: feedback +--- + +# Documentation Writing Rules + +## Rule 1: No h1 in MDX content +**Why:** The page title is set via frontmatter `title` property, not in content. +**How to apply:** Start content with h2 (`##`) or higher. Never use `#` headings. + +## Rule 2: No description in content +**Why:** Description for SEO is set via frontmatter `description` property. +**How to apply:** Don't repeat the description in the content body. + +## Rule 3: No code in titles +**Why:** Titles should be readable and descriptive without code. +**How to apply:** Write titles as concepts, not API names. Exception: if the concept IS the code (e.g., "The `error()` function"), but avoid raw code in titles. + +## Rule 4: No code-only blocks +**Why:** Documentation should be educational guides, not reference dumps. +**How to apply:** Every code block must be preceded by explanatory paragraphs. Tell WHY, not just WHAT. + +## Rule 5: Explain, don't just show +**Why:** Readers need context to understand when and why to use a feature. +**How to apply:** +- Lead with prose explaining the concept +- Include paragraphs between code blocks +- Explain the output/what happens +- Add "why would you use this?" context + +## Rule 6: Every file needs a meaningful filename +**Why:** URLs should be descriptive and SEO-friendly. +**How to apply:** Use kebab-case descriptive names like `error-factory.mdx`, not `api.mdx` or `guide1.mdx`. + +## Rule 7: See Also section uses Cards, not lists +**Why:** Cards are the Fumadocs standard for cross-linking related pages. +**How to apply:** +```mdx + + + Brief description of why this is related. + + +``` +Never use markdown bullet lists for related links. \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-components.md b/.claude/agent-memory/technical-writer/fumadocs-components.md new file mode 100644 index 0000000..af45641 --- /dev/null +++ b/.claude/agent-memory/technical-writer/fumadocs-components.md @@ -0,0 +1,207 @@ +--- +name: fumadocs-components +description: Complete list of Fumadocs UI components with usage examples +type: reference +--- + +# Fumadocs UI Components Reference + +## MDX Components (default, included) + +### Cards +```mdx + + Description + } title="With Icon" href="/">Desc + Content here + +``` + +### Callouts +```mdx +Default info +Content +Content +Content +Content +``` + +### Steps (remark plugin) +```mdx +import { Step, Steps } from 'fumadocs-ui/components/steps'; + + + ### Installation + ### Configuration + ### Deploy + +``` +Or via markdown: `### Installation [step]` + +## Additional Components (install with CLI) + +### Tabs +```mdx +import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; + + + npm install + pnpm add + yarn add + + +// Shared value across pages + + npm install + pnpm add + +``` + +### Accordion +```mdx +import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; + + + Answer 1 + Answer 2 + +``` + +### Files (file tree) +```mdx +import { File, Folder, Files } from 'fumadocs-ui/components/files'; + + + + + + + + +``` + +### TypeTable +```mdx +import { TypeTable } from 'fumadocs-ui/components/type-table'; + + +``` + +### ImageZoom +```tsx +// In components/mdx.tsx +import { ImageZoom } from 'fumadocs-ui/components/image-zoom'; + +return { + ...defaultComponents, + img: (props) => , +}; +``` + +### Banner (root layout) +```tsx +import { Banner } from 'fumadocs-ui/components/banner'; + +Announcement here +Colorful banner +Dismissible banner +``` + +## Code Blocks Features + +### Line Numbers +````md +```ts lineNumbers +const a = 'Hello'; +console.log(a); +``` +```` + +### Shiki Transformers +````md +```tsx +// [!code highlight] - highlight line +// [!code word:word] - highlight word +// [!code --] - red (removal) +// [!code ++] - green (addition) +// [!code focus] - focus line +``` + +```ts twoslash - TypeScript type hover +``` +```` + +### Tab Groups (built-in) +````md +```ts tab="npm" +npm install package +``` + +```ts tab="pnpm" +pnpm add package +``` +```` + +## Twoslash Setup + +```bash +npm install fumadocs-twoslash twoslash +``` + +```ts +// next.config.mjs +{ + serverExternalPackages: ['typescript', 'twoslash'], +} + +// source.config.ts +import { transformerTwoslash } from 'fumadocs-twoslash'; +import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; + +export default defineConfig({ + mdxOptions: { + rehypeCodeOptions: { + langs: ['js', 'jsx', 'ts', 'tsx'], + transformers: [...rehypeCodeDefaultOptions.transformers, transformerTwoslash()], + }, + }, +}); + +// Tailwind v4 +@import 'fumadocs-twoslash/twoslash.css'; + +// components/mdx.tsx +import * as Twoslash from 'fumadocs-twoslash/ui'; +return { ...defaultComponents, ...Twoslash }; +``` + +### Twoslash Annotations +- `// ^?` - hover type +- `// @ts-err` - expected error +- comments show inline + +## Frontmatter + +```yaml +--- +title: Page Title +description: SEO description +icon: HomeIcon # Lucide icon name +--- +``` + +## MDX Features + +- Auto links (internal/external) +- Anchor headings +- Include other files: `` +- NPM commands: ` ```npm install ``` ` +- Mermaid diagrams (via plugin) \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md b/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md new file mode 100644 index 0000000..25a0b35 --- /dev/null +++ b/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md @@ -0,0 +1,38 @@ +--- +name: fumadocs-docs-reference +description: Fumadocs v16 documentation at fumadocs.dev - use fresh to fetch +type: reference +--- + +# Fumadocs Documentation Reference + +**URL:** https://www.fumadocs.dev/ + +**Access:** Use `fresh fetch ` to retrieve content + +## Key areas to explore + +When documenting @deessejs/errors with Fumadocs: + +1. **MDX Collections** — `source.config.ts` uses `defineDocs` and `pageSchema` + - Frontmatter schema: title, description + - Post-processing options + +2. **Layout Components** — How `DocsLayout`, `DocsPage` work + - `getMDXComponents()` for custom MDX components + - Relative linking between docs + +3. **UI Components** — Available MDX components + - ``, `` — Navigation + - ``, `` — Code examples + - `` — Tutorials + +4. **Configuration** — `defineConfig` options + - MDX options + - Source plugins (lucide-icons shown in source.ts) + +## Relevant for + +- Creating documentation structure in `content/docs/` +- Custom MDX component development +- Navigation/tree configuration \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-meta-json.md b/.claude/agent-memory/technical-writer/fumadocs-meta-json.md new file mode 100644 index 0000000..d11ec1f --- /dev/null +++ b/.claude/agent-memory/technical-writer/fumadocs-meta-json.md @@ -0,0 +1,71 @@ +--- +name: fumadocs-meta-json +description: meta.json configuration for navigation tree in Fumadocs +type: reference +--- + +# Fumadocs meta.json Reference + +**Location:** `content/docs//meta.json` + +## Properties + +| Property | Type | Description | +|----------|------|-------------| +| `title` | string | Display name in sidebar | +| `icon` | string | Lucide icon name | +| `defaultOpen` | boolean | Open folder by default | +| `collapsible` | boolean | Allow folder collapse (default: true) | +| `pages` | string[] | Custom page ordering | +| `pagesIndex` | string | Index page path or link | + +## pages[] Item Types + +| Type | Syntax | Description | +|------|--------|-------------| +| Path | `"./path/to/page"` | Path to page or folder | +| Separator | `"---Label---"` | Section separator | +| Link | `"[Text](url)"` | Internal link | +| External | `"external:[Text](url)"` | External link with icon | +| Rest | `"..."` | Include remaining pages (alphabetical) | +| Reversed | `"z...a"` | Include remaining pages (reversed) | +| Extract | `"...folder"` | Extract items from subfolder | +| Except | `"!item"` | Exclude from `...` or `z...a` | + +## Slug Conventions + +| Path Pattern | Slugs | +|--------------|-------| +| `./dir/page.mdx` | `['dir', 'page']` | +| `./dir/index.mdx` | `['dir']` | +| `./(group)/page.mdx` | `['page']` (group not in slug) | + +## Example + +```json +{ + "title": "Guide", + "defaultOpen": true, + "pages": [ + "index", + "getting-started", + "---API Reference---", + "...", + "!deprecated-page", + "[GitHub](https://github.com/...)" + ] +} +``` + +## Root Folder (meta.json with `root: true`) + +Marks folder as root - other folders hidden in sidebar. + +```json +{ + "title": "Framework", + "root": true +} +``` + +Renders as Layout Tabs in Fumadocs UI. \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/project-analysis.md b/.claude/agent-memory/technical-writer/project-analysis.md new file mode 100644 index 0000000..82e8499 --- /dev/null +++ b/.claude/agent-memory/technical-writer/project-analysis.md @@ -0,0 +1,69 @@ +# @deessejs/errors Project Analysis + +## Project Overview + +**@deessejs/errors** is a TypeScript error handling library inspired by Python's exception system. It provides exception chaining, hierarchical inheritance, and rich error semantics through a function-based API. + +## Repository Structure + +``` +@deessejs/errors/ (pnpm monorepo) +├── packages/ +│ └── errors/ # Core library package +│ ├── src/ +│ │ ├── index.ts # Public API exports +│ │ ├── causes/ # Cause chain traversal +│ │ ├── error/ # Error factory (capture.ts, error.ts, format.ts, types.ts) +│ │ ├── is/ # Error type checking +│ │ └── raise/ # Error raising utilities +│ ├── tests/ # Vitest test suite +│ ├── examples/ # Usage examples +│ ├── internal/ # Internal documentation +│ └── learnings/ # Learning notes +├── apps/ +│ └── web/ # Documentation website +│ ├── content/docs/ # MDX documentation files (index.mdx, test.mdx) +│ ├── src/app/ # Next.js 16 app router +│ ├── src/components/ # React components +│ └── src/lib/ # Utilities +├── docs/ # Worktree directory (technical-writer agent) +└── temp/ # Temporary files +``` + +## Key Technologies + +| Component | Technology | +|-----------|------------| +| Core lib | TypeScript, Vitest, ESLint | +| Package manager | pnpm 10.30.3 | +| Build | Turbo | +| Versioning | Changesets | +| Docs site | Next.js 16, Fumadocs, Tailwind CSS, React 19 | + +## Core Library API (public exports) + +From `src/index.ts`: +- `error()` — Error factory function +- `raise` — Error raising function +- `is()` — Error type checking +- `causes()` — Cause chain traversal +- Types: `ErrorFactory`, `ErrorInstance`, `ErrorInstanceCore` + +## Documentation Status + +**Current state:** Minimal/starter documentation +- Only 2 placeholder MDX files in `apps/web/content/docs/` +- No real documentation content yet +- This worktree is dedicated to creating documentation + +## Branching Strategy + +- `main` ← `staging` ← `dev` +- All developers push directly to `main` +- Release engineer manages main → staging → main flow + +## Notes + +- CLAUDE.md states: "Always communicate in English" even though user communicates in French +- Uses `fresh` CLI for web searches (not standard search) +- Based on `nesalia-inc/errors` (production version) \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/project-notes.md b/.claude/agent-memory/technical-writer/project-notes.md new file mode 100644 index 0000000..fdee31c --- /dev/null +++ b/.claude/agent-memory/technical-writer/project-notes.md @@ -0,0 +1,39 @@ +--- +name: project-notes +description: Notes from first documentation PR +type: project +--- + +# Documentation Project Notes + +## PR: First Draft (PR #11) +Branch: `docs/first-draft` → `main` +Status: Ready for review + +## Key Learnings + +### Code Block Titles +- Syntax: ` ```ts title="filename.ts" ` (NOT ` ```ts filename.ts `) +- The title attribute goes AFTER the language, not as part of it + +### Vercel Config +- Root directory: `/` (not `apps/web`) +- Build command: `pnpm --filter web build` +- Output directory: `apps/web/.next` +- Added `vercel.json` at repo root + +### Theme +- File: `apps/web/src/app/global.css` +- Change: `fumadocs-ui/css/neutral.css` → `fumadocs-ui/css/black.css` + +### Site Config +- File: `apps/web/src/lib/shared.ts` +- `appName`: '@deessejs/errors' +- `gitConfig`: user='nesalia-inc', repo='errors' + +## Files Modified +- 13 MDX docs pages in `apps/web/content/docs/` +- `apps/web/content/docs/meta.json` +- `apps/web/src/lib/shared.ts` +- `apps/web/src/app/global.css` +- `vercel.json` (new) \ No newline at end of file diff --git a/.claude/agents/design-engineer/README.md b/.claude/agents/design-engineer/README.md new file mode 100644 index 0000000..8e75bbb --- /dev/null +++ b/.claude/agents/design-engineer/README.md @@ -0,0 +1,11 @@ +--- +name: design-engineer +description: Senior Design Engineer +model: sonnet +memory: project +color: green +--- + +# Senior Design Engineer + +**Role:** You are the Senior Design Engineer. diff --git a/.claude/agents/technical-writer/README.md b/.claude/agents/technical-writer/README.md new file mode 100644 index 0000000..b1e65fd --- /dev/null +++ b/.claude/agents/technical-writer/README.md @@ -0,0 +1,11 @@ +--- +name: technical-writer +description: Senior Technical Writer +model: sonnet +memory: project +color: green +--- + +# Senior Technical Writer + +**Role:** You are the Senior Senior Technical Writer. diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 597bdde..50f7519 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -28,8 +28,7 @@ "Bash(xargs kill*)", "Bash(taskkill*)", - "Bash(git rebase *)", - "Bash(git reset --hard*)", + "Bash(git reset --hard*)", "Bash(git clean*)", "Bash(sudo *)", diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..81d0da0 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,239 @@ +# Design System — @deessejs/errors Documentation + +## Overview + +Design system and visual guidelines for the `@deessejs/errors` documentation website. Inspired by [Flue Framework](https://flueframework.com) — minimal, developer-focused, blueprint aesthetic. + +## Tech Stack + +| Technology | Version | Purpose | +|------------|---------|---------| +| Next.js | 16.x | React framework | +| Tailwind CSS | v4 | Styling | +| Geist | (Vercel) | Typography (future) | +| shadcn/ui | TBD | Component library | +| FumaDocs | 16.x | Documentation framework | +| lucide-react | 1.x | Icons | + +## Typography + +**Font**: Geist (via `next/font/geist` or Vercel CDN) + +```typescript +import { Geist } from 'next/font/google'; + +const geist = Geist({ + subsets: ['latin'], + display: 'swap', +}); +``` + +**Scale**: +- Headings: `font-bold tracking-tight` +- Body: `text-lg` for main content, `text-base` for details +- Code: JetBrains Mono (monospace) +- Labels: `font-medium text-gray-500 uppercase tracking-wider` + +## Color Palette + +Using Tailwind's default palette with these semantic usages: + +| Token | Usage | +|-------|-------| +| `gray-950` | Primary text (`#030304`) | +| `gray-500` | Secondary text / muted | +| `gray-300` | Borders | +| `gray-200` | Dividers, subtle backgrounds | +| `white` | Cards, elevated surfaces | +| `#f8f9fb` | Off-white body background | +| `blue-500` / `blue-600` | Accent color (links, highlights) | + +### Dark Mode + +Support both light and dark modes using Tailwind's `dark:` variants. + +## Visual Language + +### Border Radius + +**No rounded corners** — `rounded-none` throughout. + +Exception: `
` code blocks use `rounded-none` with sharp corners.
+
+### Blueprint Grid Background
+
+SVG-based grid pattern for hero sections:
+
+```html
+
+  
+    
+      
+    
+  
+  
+
+```
+
+### Cards
+
+```html
+
+

+  
+

+
+
+
+  
+
+```
+
+### Buttons
+
+**Primary** (dark):
+```html
+
+```
+
+**Secondary** (outlined):
+```html
+
+```
+
+### Floating Squares (Hero Decoration)
+
+Blueprint-style floating squares for visual interest:
+
+```tsx
+const floatingSquares = [
+  { x: 300, y: 120, opacity: 1.0, delay: 0.7, duration: 4 },
+  { x: 220, y: 60,  opacity: 0.8, delay: 0.3, duration: 4 },
+  { x: 160, y: 160, opacity: 0.5, delay: 0.0, duration: 4 },
+];
+```
+
+### Code Blocks
+
+Sharp corners, syntax highlighting, filename tabs:
+
+```html
+

+  

+    filename.ts
+  

+  
...

+

+```
+
+### Navigation
+
+```html
+
+```
+
+## Layout Structure
+
+```
+apps/web/src/
+├── app/
+│   ├── layout.tsx              # Root layout (Geist font, RootProvider)
+│   ├── global.css              # Tailwind imports + custom styles
+│   ├── page.tsx                # Homepage
+│   └── docs/
+│       ├── layout.tsx          # DocsLayout with sidebar
+│       └── [[...slug]]/         # Dynamic doc pages
+├── components/
+│   ├── mdx.tsx                 # MDX component factory
+│   └── ui/                     # shadcn/ui components (future)
+└── lib/
+    ├── source.ts              # FumaDocs content loader
+    └── shared.ts              # App config
+```
+
+### Max Width
+
+- Content: `max-w-6xl mx-auto px-6` (1152px)
+- Hero: `max-w-6xl mx-auto px-6`
+- Docs: handled by FumaDocs layouts
+
+### Spacing Scale
+
+Use Tailwind's 4px incremental scale consistently:
+- `pt-20 lg:pt-28` for hero sections
+- `py-24` for section padding
+- `gap-12 lg:gap-20` for large grids
+
+## Responsive Breakpoints
+
+| Breakpoint | Target |
+|------------|--------|
+| `sm` (640px) | Mobile landscape |
+| `md` (768px) | Tablets |
+| `lg` (1024px) | Laptops |
+| `xl` (1280px) | Desktops |
+
+## shadcn/ui Integration
+
+```bash
+npx shadcn@latest init
+```
+
+### Core Components to Implement
+
+| Component | Purpose | Status |
+|-----------|---------|--------|
+| Button | Primary/secondary actions | TBD |
+| Card | Feature highlights, deployment options | TBD |
+| Callout | Notes, warnings, tips, errors | TBD |
+| Code | Syntax highlighted code blocks | TBD |
+| Tabs | API reference navigation | TBD |
+| Table | Parameter documentation | TBD |
+| Badge | Labels, version tags | TBD |
+
+### shadcn/ui Configuration
+
+Update `components.json` to match our design tokens:
+
+```json
+{
+  "rounded": "none",
+  "cssVariables": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/app/global.css"
+  }
+}
+```
+
+## Design Principles
+
+1. **Developer-First**: Clarity over decoration. Code examples are the hero.
+2. **Minimal**: Ample whitespace, clean layouts, `rounded-none` everywhere.
+3. **Blueprint Aesthetic**: Subtle grid backgrounds, floating squares, schematic vibes.
+4. **Dark Mode Ready**: All components work in both light and dark.
+5. **Consistent Spacing**: 4px increments via Tailwind scale.
+
+## Future Enhancements
+
+- [ ] Integrate shadcn/ui with `rounded-none`
+- [ ] Implement Geist font
+- [ ] Add blueprint grid SVG components
+- [ ] Create floating squares animation
+- [ ] Custom callout components for error types
+- [ ] Deploy section with platform cards
+- [ ] Architecture diagram component
+
+---
+
+**Last updated**: 2026-06-02
+**Inspiration**: [Flue Framework](https://flueframework.com)
\ No newline at end of file
diff --git a/apps/web/src/app/(home)/page.tsx b/apps/web/src/app/(home)/page.tsx
index c936084..e4a4aa4 100644
--- a/apps/web/src/app/(home)/page.tsx
+++ b/apps/web/src/app/(home)/page.tsx
@@ -1,16 +1,498 @@
 import Link from 'next/link';
 
+// Floating squares data for blueprint aesthetic
+const floatingSquares = [
+  { x: 300, y: 120, opacity: 1.0, delay: 0.7 },
+  { x: 220, y: 60, opacity: 0.8, delay: 0.3 },
+  { x: 160, y: 160, opacity: 0.5, delay: 0.0 },
+];
+
+// Hero code example
+const HERO_CODE = `import { error, raise, is, causes } from '@deessejs/errors';
+
+const ValidationError = error({
+  name: 'ValidationError',
+  message: 'Field "{field}" is invalid: {reason}',
+});
+
+const err = ValidationError({
+  field: 'email',
+  reason: 'invalid format',
+});
+
+// Chain errors with .from()
+appErr.from(err);
+
+// Type-safe checking
+if (is(err, ValidationError)) {
+  console.log(err.fields.field); // "email"
+}`;
+
+// Features data
+const features = [
+  {
+    title: 'Exception Chaining',
+    description:
+      'Preserve the full context of errors with the .from() method. Traverse the complete error chain to understand what went wrong.',
+    href: '/docs/from-method',
+  },
+  {
+    title: 'Hierarchical Inheritance',
+    description:
+      'Organize errors in meaningful hierarchies that reflect your domain. Use inheritance to categorize and handle errors by type.',
+    href: '/docs/single-inheritance',
+  },
+  {
+    title: 'Message Templates',
+    description:
+      'Define errors with {placeholder} templates that are replaced at runtime. Rich, contextual error messages made easy.',
+    href: '/docs/message-templates',
+  },
+  {
+    title: 'TypeScript Native',
+    description:
+      'Full type safety with generic error factories. Leverage TypeScript to catch errors before they happen.',
+    href: '/docs/type-checking',
+  },
+];
+
+// Code examples for showcase
+const BEFORE_CODE = `// Traditional approach
+throw new Error('Validation failed');
+
+catch (err) {
+  if (err.message.includes('Validation')) {
+    // String matching... fragile!
+  }
+}`;
+
+const AFTER_CODE = `// @deessejs/errors approach
+raise(ValidationError({ field: 'email' }));
+
+catch (err) {
+  if (is(err, ValidationError)) {
+    // Type-safe, reliable
+    console.log(err.fields.field);
+  }
+}`;
+
 export default function HomePage() {
   return (
-    

-      
Hello World

-      

-        You can open{' '}
-        
-          /docs
-        {' '}
-        and see the documentation.
-      

-    

+    <>
+      {/* Blueprint grid background */}
+      
+
+      {/* Navigation */}
+      
+
+      

+        {/* Hero Section */}
+        

+          

+            

+              Error Handling,
+              

+              Reimagined.
+            

+            

+              A TypeScript library that brings Python-inspired error handling to
+              JavaScript. Exception chaining, hierarchical inheritance, and rich
+              error semantics through a function-based API.
+            

+            

+              
+                Get Started
+              
+              
+                npm install @deessejs/errors
+              
+            

+          

+        

+
+        {/* Hero Code Section */}
+        

+          

+            

+              {/* Code block chrome */}
+              

+                

+                  
+                  
+                    example.ts
+                  
+                

+              

+              
+                {HERO_CODE}
+              

+            

+          

+        

+
+        {/* Features Section */}
+        

+          

+            

+              

+                Features
+              

+              

+                Everything you need for robust error handling in TypeScript.
+              

+            

+
+            

+              {/* Feature cards - spans 3 columns each */}
+              {features.map((feature) => (
+                
+                  

+                    {feature.title}
+                  

+                  

+                    {feature.description}
+                  

+                
+              ))}
+
+              {/* Secondary features - spans 2 columns */}
+              
+                

+                  Type Guards
+                

+                

+                  The is(){' '}
+                  function provides type-safe error checking.
+                

+              
+
+              
+                

+                  Schema Validation
+                

+                

+                  Validate error fields with Standard Schema (Zod, Valibot, etc.).
+                

+              
+
+              
+                

+                  Cause Traversal
+                

+                

+                  Use causes() to
+                  iterate the full error chain.
+                

+              
+
+              {/* CTA card */}
+              
+                

+                  Explore the docs
+                

+                

+                  Learn how to build robust error handling in your TypeScript
+                  projects.
+                

+                
+                  Read the docs →
+                
+              
+            

+          

+        

+
+        {/* Before/After Comparison */}
+        

+          

+            

+              

+                From fragile to robust.
+              

+              

+                Stop relying on fragile string matching. Get type-safe, structured
+                errors that make debugging a breeze.
+              

+            

+
+            

+              {/* Before */}
+              

+                

+                  
+                    Before
+                  
+                

+                
+                  {BEFORE_CODE}
+                

+              

+
+              {/* After */}
+              

+                

+                  
+                    @deessejs/errors
+                  
+                

+                
+                  {AFTER_CODE}
+                

+              

+            

+          

+        

+
+        {/* Install Section */}
+        

+          

+            

+              

+                Get started in seconds.
+              

+              

+                Install the package and start building better errors today.
+              

+            

+
+            

+              

+                $
+                npm install @deessejs/errors
+              

+              

+                $
+                pnpm add @deessejs/errors
+              

+            

+
+            

+              
+                Read the full documentation
+                →
+              
+            

+          

+        

+      

+
+      {/* Footer */}
+      

+        

+          

+            
+            
+              @deessejs/errors — MIT License
+            
+          

+          
+            GitHub
+          
+        

+      

+    
   );
-}
+}
\ No newline at end of file
diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx
index 9bb6360..42a0b4f 100644
--- a/apps/web/src/app/layout.tsx
+++ b/apps/web/src/app/layout.tsx
@@ -5,6 +5,7 @@ import { Analytics } from '@vercel/analytics/next';
 
 const inter = Inter({
   subsets: ['latin'],
+  display: 'swap',
 });
 
 export default function Layout({ children }: LayoutProps<'/'>) {

From ff1e1a72ed571f0eb9d7a2b1fb11799d5f7eeb72 Mon Sep 17 00:00:00 2001
From: martyy-code 
Date: Tue, 2 Jun 2026 13:50:24 +0200
Subject: [PATCH 03/19] fix(homepage): use theme CSS variables instead of
 hardcoded colors

Replace all hardcoded Tailwind colors (gray-950, bg-white, etc.) with
FumaDocs theme CSS variables (bg-fd-primary, text-fd-foreground, etc.)

Co-Authored-By: Claude Opus 4.7 
---
 apps/web/src/app/(home)/page.tsx | 146 +++++++++++++++----------------
 1 file changed, 73 insertions(+), 73 deletions(-)

diff --git a/apps/web/src/app/(home)/page.tsx b/apps/web/src/app/(home)/page.tsx
index e4a4aa4..f272b3b 100644
--- a/apps/web/src/app/(home)/page.tsx
+++ b/apps/web/src/app/(home)/page.tsx
@@ -102,7 +102,7 @@ export default function HomePage() {
                 
               
@@ -113,10 +113,10 @@ export default function HomePage() {
                 x2="100%"
                 y2="0%"
               >
-                
-                
-                
-                
+                
+                
+                
+                
               
               
                 
 
       {/* Navigation */}
-