A senior-level knowledge base for designing and building beautiful, usable, accessible, high-converting websites — 60 dense, cross-linked guides spanning visual design, UX, responsive engineering, every major site type, the modern frontend stack, marketing & conversion, aesthetics, and anti-patterns.
This repository is a structured, opinionated design + UX + marketing handbook. Every guide is written to a consistent, scannable skeleton — TL;DR → core concepts → concrete specs & numbers → do / don't → pitfalls → what real users complain about → senior checklist → sources — so you can jump in anywhere and walk away with specific, applicable rules (real numbers, exact tokens, correct code), not vague advice.
It is dual-purpose:
- For people — a reference you browse by topic when designing or reviewing a site.
- For AI agents — a knowledge base an LLM reads selectively to design at a senior level. See How to use this repo and
AGENTS.md.
| # | Section | Covers | Guides |
|---|---|---|---|
| 00 | 🎨 Foundations | visual principles & Gestalt, hierarchy, typography, color, grids & spacing, imagery, data-viz | 8 |
| 01 | 🧭 UX Fundamentals | laws of UX, Nielsen heuristics, research, IA & navigation, cognitive load, interaction states, forms, accessibility (WCAG 2.2), i18n, auth flows | 10 |
| 02 | 📐 Responsive & Adaptive | fluid layouts, breakpoints & mobile-first, clamp() type/space, touch ergonomics |
4 |
| 03 | 🏗️ Site Types | landing pages, one-pagers, scroll experiences, CRM/admin, SaaS, e-commerce, portfolios, brand sites, content/docs, chat & AI-native | 10 |
| 04 | 🧰 Libraries & Tools | animation (GSAP/Motion/Lenis), WebGL/3D, CSS & Tailwind, component/headless libs, frameworks, native UI primitives, tooling | 7 |
| 05 | 🔩 Process & Systems | design process & stages, design systems & tokens, wireframe → handoff → QA | 3 |
| 06 | 📈 Marketing & Conversion | CRO, copywriting/UX writing, persuasion psychology, SEO, performance / Core Web Vitals, analytics, lifecycle & email | 7 |
| 07 | ✨ Aesthetics & Trends | style taxonomy, 2025–2026 trends, micro-interactions & motion, avoiding generic "AI" looks | 4 |
| 08 | common mistakes, dark patterns, real user complaints | 3 | |
| 09 | 📋 Playbooks & Checklists | step-by-step builds (landing, scroll one-pager, CRM) + master checklist | 4 |
Every guide, grouped by section. The Use it when column tells you (or your agent) which guide to open for a given task.
| Guide | Use it when |
|---|---|
| Color Theory & Color Systems | picking any color, building a palette/theme, adding dark mode, or auditing contrast |
| Data Visualization & Charts | designing any chart, dashboard metric, data story, or scrollytelling visual |
| Imagery, Icons & Visual Assets | any page that ships a raster image, illustration, SVG icon, or hero |
| Layout, Grids & Spacing Systems | Laying out any page or component, choosing spacing/sizing values, or fixing a layout that "feels off." |
| Multilingual & Non-Latin Typography | any site that renders, or might one day render (CMS, UGC, i18n), text in a non-Latin script. |
| Web Typography Systems | designing or implementing any text-bearing page or design system. |
| Visual Design Principles & Gestalt | composing any layout — deciding what groups with what, what dominates, and where the eye lands. |
| Visual Hierarchy & Scanning Patterns | designing any screen, page, or component where a user must orient, decide, or act. |
| Guide | Use it when |
|---|---|
| Accessibility (WCAG 2.2) for Designers & Devs | every project, from design phase onward (retrofitting costs 10×) |
| Authentication & Account Flows | building any login, sign-up, password reset, MFA, SSO, or account-settings flow |
| Cognitive Load & Progressive Disclosure | any screen with >1 decision, >1 choice, or >5 fields — onboarding, forms, settings, dashboards, checkout, pricing, empty states |
| Forms & Input UX | building any form — signup, login, checkout, contact, settings, multi-step flow |
| Information Architecture & Navigation | designing any site's structure, menus, breadcrumbs, search, or mobile nav |
| Interaction Design & UI States | designing or building any interactive component, screen, or flow. |
| Internationalization (i18n) & Localization (l10n) | building anything that may ship in more than one language, region, or currency — even if it launches monolingual. |
| The Laws of UX & Design Psychology | any screen, flow, navigation, CTA, form, or pricing decision — i.e. always |
| Nielsen's Usability Heuristics & Practical Usability | designing or auditing any interactive UI; self-reviewing a build before handoff |
| User Research & Usability Testing | before building (discovery), during design (validation), and post-launch (optimization); any time a decision rests on an assumption about users |
| Guide | Use it when |
|---|---|
| Breakpoints, Devices & Mobile-First | designing any responsive layout, choosing breakpoints, or deciding mobile-first vs desktop-first. |
| Fluid Typography & Spacing with clamp() | defining any type scale or spacing system; replacing per-breakpoint font-size/padding rules; building a token-driven design system. |
| Responsive & Fluid Design | building any production web layout, page, or reusable component. |
| Touch Ergonomics & Cross-Device Design | designing or building any page or component that real people touch — i.e., almost everything in 2026+. |
| Guide | Use it when |
|---|---|
| Content Sites: Blogs, Magazines & Docs | building a blog, news/magazine, knowledge base, or developer docs — any site where the primary job is reading text. |
| Chat, Conversational & AI-Native Interfaces | building a chat/assistant surface, an agentic tool, or any UI where an LLM streams responses into a transcript |
| CRM & Admin Dashboards (Data-Dense UI) | building internal tools, admin panels, CRMs, or analytical dashboards with high information density |
| E-commerce UX | building or auditing any transactional store (catalog → PDP → cart → checkout) |
| Landing Pages | building any paid-traffic / campaign / product-launch destination page with a single goal. |
| Marketing & Brand Sites | building a company/product brand site (homepage + IA, not a single campaign page). |
| Portfolios & Personal Sites | building a designer/developer/creative personal site, UX case-study portfolio, or freelance studio site |
| SaaS Web Apps | building or redesigning the logged-in surface of a subscription product (dashboard app, workspace, tool) |
| Scroll-Driven Experiences (Magic Scroll, Pinning, Parallax) | campaign microsites, product showcases, agency/portfolio hero experiences — NOT task-driven flows |
| Single-Page Sites & One-Pagers | content scope is one focused goal (portfolio, event, single product, MVP, brand statement) and linear narrative beats a navigation hierarchy. |
| Guide | Use it when |
|---|---|
| Web Animation Libraries & Stack | adding any motion to a site — micro-interactions, scroll effects, page transitions, layout animations, or motion graphics. |
| Component Libraries & Headless UI | Picking a component foundation, building a design system, customizing shadcn/ui, fixing a11y or theming problems, or evaluating bundle/accessibility tradeoffs. |
| CSS, Styling & Tailwind | Choosing or wiring up any styling approach, defining design tokens, fixing class-soup/specificity/bundle problems. |
| Design & Dev Tooling | Setting up a project's build/QA toolchain, wiring design-token sync, optimizing fonts/images, doing design QA on a build, or reading a Figma handoff. |
| Frameworks for Design-Forward Sites | starting a new design-forward site, or auditing why an existing one is slow/heavy/expensive. |
| Native Interactive UI Primitives: Popover, Anchor Positioning, Dialog & inert | Building any overlay (menu, dropdown, tooltip, modal, toast, picker, command palette), deciding whether to pull in a headless library, or fixing clipping/stacking/focus-trap bugs. |
| WebGL, 3D & Shaders for the Web | a design calls for 3D scenes, shader effects, particle/fluid/distortion visuals, or 3D product viewers |
| Guide | Use it when |
|---|---|
| The Website Design Process & Stages | starting any non-trivial website or redesign and deciding what to produce, in what order, with what verification. |
| Design Systems & Design Tokens | building any product that needs consistency across ≥2 surfaces/teams, or any site requiring dark mode/theming |
| Wireframing, Prototyping, Handoff & QA | taking a design from sketch to build, writing specs, or QA'ing an implementation against a design |
| Guide | Use it when |
|---|---|
| Analytics Instrumentation & Measuring Design Impact | building any site/app where a stakeholder will later ask "did the redesign work?" |
| Conversion Rate Optimization (CRO) | designing or auditing any page with a measurable goal — landing pages, checkout, signup, pricing, demo requests. |
| Copywriting & UX Writing | writing any user-facing string — headlines, buttons, form labels, errors, empty states, tooltips, hero VP, onboarding, success/confirmation, loading states. |
| Lifecycle, Email & Notification Design | designing any email, push, in-app, or SMS that a customer receives outside the website itself |
| Ethical Persuasion Psychology | designing any page meant to drive a decision — landing pages, pricing, checkout, signup, onboarding, lead magnets. |
| SEO & Discoverability for Designers | building any public-facing page meant to be found via search or shared on social |
| Web Performance & Core Web Vitals | building or auditing any production page where speed, ranking, or conversion matters (almost always). |
| Guide | Use it when |
|---|---|
| Avoiding Generic 'AI' Aesthetics | building any public-facing or brand site, or when a generated UI looks "fine but forgettable." |
| A Taxonomy of Web Design Styles | picking or justifying a visual direction before wireframing/build |
| Micro-interactions & Motion Design | building any interactive UI — buttons, modals, route changes, scroll reveals, loaders. |
| Web Design Trends 2025-2026 | choosing an aesthetic direction or deciding whether a requested trend is worth implementing |
| Guide | Use it when |
|---|---|
| Common Design Mistakes & Antipatterns | designing or reviewing any web UI before ship |
| Dark Patterns to Avoid | designing pricing, checkout, signup, consent, cancellation, or any conversion-critical flow |
| What Real Users Complain About (Synthesis) | designing, reviewing, or auditing any public-facing site before ship |
| Guide | Use it when |
|---|---|
| Master Checklists & Cheat-Sheets | scoping a build, reviewing your own output, or doing final pre-launch QA |
| Playbook: Design a CRM / Admin Dashboard | building an internal/B2B tool where users return daily to scan, filter, act on, and drill into structured business data. |
| Playbook: Design & Build a Landing Page | building a single-purpose conversion page for one offer + one traffic source. |
| Playbook: Build a Scroll-Driven One-Pager | building a marketing one-pager, portfolio, or product story where scroll is the interaction. |
- Scroll-Driven Experiences + its build playbook — the "magic scroll" one-pager done right: GSAP ScrollTrigger + Lenis, native CSS scroll-timelines, pinning / parallax, compositor-only performance, and
prefers-reduced-motion. - Landing Pages + playbook — the anatomy of a high-converting page, from message-match to CTA.
- Avoiding Generic 'AI' Aesthetics — how to escape the default "AI-generated" look and ship work that reads as designed.
- Accessibility (WCAG 2.2) — POUR, semantic HTML, focus, ARIA, target sizes, reduced motion.
- Chat, Conversational & AI-Native Interfaces — streaming transcripts, composer UX, and the accessibility of live-updating chat.
Browsing (humans). Open the Table of Contents, find the section, read the guide. Each is self-contained and ends with a checklist you can apply immediately.
With an AI coding agent (recommended). Two patterns:
- Point your agent at the index. Add one line to your project's
CLAUDE.md,.cursorrules, orAGENTS.md:Before building any UI, read
AGENTS.mdin the design codex, pick the relevant guides for the task, and follow them. - Clone it next to your project so the agent can read guides on demand:
git clone <this-repo> design-codex
Don't dump all 60 guides into a prompt — they total ~23k lines. The codex is a knowledge base you query selectively: read AGENTS.md (machine index + curated reading paths per task), then open the 2–5 guides it points to.
ai-web-design-codex/
├── AGENTS.md ← machine index + reading paths (for AI agents)
├── README.md ← you are here
├── 00-foundations/ (8) visual principles, hierarchy, type, color, grids, imagery, data-viz
├── 01-ux-fundamentals/ (10) laws, heuristics, research, IA, forms, a11y, i18n, auth
├── 02-responsive-adaptive/ (4) fluid, breakpoints, clamp(), touch
├── 03-site-types/ (10) landing, one-pager, scroll, CRM, SaaS, e-com, portfolio, brand, content, chat
├── 04-libraries-and-tools/ (7) animation, WebGL, CSS/Tailwind, components, frameworks, native primitives, tooling
├── 05-process-and-systems/ (3) process, design systems & tokens, wireframe → handoff → QA
├── 06-marketing-and-conversion/ (7) CRO, copy, persuasion, SEO, performance, analytics, lifecycle
├── 07-aesthetics-and-trends/ (4) styles taxonomy, trends, motion, anti-AI-slop
├── 08-pitfalls-and-antipatterns/ (3) mistakes, dark patterns, real complaints
└── 09-playbooks-and-checklists/ (4) step-by-step builds + master checklist
Each guide was researched by agents sweeping authoritative sources — Nielsen Norman Group, Smashing Magazine, web.dev, MDN, Baymard Institute, OWASP, Material Design 3, Apple HIG, the GSAP / Motion docs — plus practitioner discussion on Reddit, then adversarially fact-checked: a second reviewer hunted for vague advice, wrong facts, and fabricated statistics and corrected them in place. Internal cross-links are verified — 482 links, 0 broken.
Guides reflect a 2025–2026 baseline. The web platform moves fast — verify version-specific API and browser-support claims against current docs before relying on them.
Licensed under CC BY 4.0 — share and adapt for any purpose, including commercially, with attribution: "AI Web Design Codex by Eneryleen" + a link back to this repository.