Josh W Comeau Courses — CSS for JavaScript Developers

# Build brief — an original marketing website in the taste of Josh W Comeau Courses

> Reference: https://www.css-for-js.dev · UIDiscovery: https://uidiscovery.com/sites/josh-w-comeau-courses · captured 2026-09-22 at a 1440px desktop viewport (+ 390px iPhone shots) · [full page](https://uidiscovery.com/media/captures/josh-w-comeau-courses/full.png) · [scroll video](https://uidiscovery.com/media/captures/josh-w-comeau-courses/preview.mp4)

## 1. Goal
Build an original marketing website for **[the user's brand]** that feels as considered as Josh W Comeau Courses — same structure, rhythm and polish, entirely new identity and content.

## 2. Originality rules
- Build an ORIGINAL design for the user's own brand in the same *taste* as Josh W Comeau Courses: structure, rhythm, hierarchy, palette mood and type pairing.
- Never reuse Josh W Comeau Courses's logo, name, product imagery, illustrations, icons, screenshots or copy. Write new copy for the user's product.
- If the user hasn't said what their product is, ask first (or use clearly marked placeholders like [Brand], [Product], [Audience]).
- Reference screenshots are for looking at, not for embedding or tracing.

## 3. The taste, in short
- Josh W Comeau Courses (css-for-js.dev): Portfolio marketing website, dark.
- 8 sections: Hero → Content → Statement → Logo cloud → Content → Features → Content → Features.
- Spacing: about a screen per idea (median section ≈914px).
- Hero headline: 4 words — short and punchy; keep yours under ~9.
- Type: one family (Wotfard). Imagery: mostly photography, some abstract 3D / gradient art.

## 4. Page structure (top to bottom)

### 1. Hero — state what the product is and for whom in one glance, and offer the primary action.
- Layout: headline-led stack: eyebrow → H1 → supporting line → actions, with a visual beside or below. About one full screen (850px at 1440), own dark band #151118; 2 image/graphics; 1 text link instead of buttons.
- Slots: Eyebrow / announcement pill (optional); H1 (~4 words, like the reference); Supporting line, 1–2 sentences; Text link action; Hero visual (see image plan).
- Topic (tone/length only — never reuse): “Stop wrestling with CSS.”
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-01.webp) · imagery: slot 1

### 2. Content — supporting content that deepens one idea.
- Layout: text + media block. Tall, ≈1.9 screens (1700px at 1440), own dark band #151118; 7 images/icons (a set of cards or a small gallery); no interactive controls.
- Slots: Heading (~4 words, like the reference); Body copy; Supporting visual (see image plan).
- Topic (tone/length only — never reuse): “CSS FOR JAVASCRIPT DEVELOPERS”
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-02.webp) · imagery: slot 2

### 3. Statement — a large-type moment that sets tone and pace.
- Layout: oversized typography with lots of space. Half to one screen (699px at 1440), own dark band #151118; 7 images/icons (a set of cards or a small gallery); no interactive controls.
- Slots: Heading; Body copy; Supporting visual (see image plan).
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-03.webp) · imagery: slot 3

### 4. Logo cloud — borrow trust from recognisable customers or partners.
- Layout: a single row or wall of monochrome marks with a one-line lead-in. Half to one screen (655px at 1440), own dark band #151118; 16 image elements (photo collage/gallery + small graphics); no interactive controls.
- Slots: One-line lead-in (e.g. “Trusted by…”); 6–10 monochrome customer/partner marks (your own, with permission).
- Topic (tone/length only — never reuse): “TRUSTED BY DEVELOPERS AT”
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-04.webp)

### 5. Content — supporting content that deepens one idea.
- Layout: text + media block. About one full screen (914px at 1440), own dark band #151118; 4 images/icons (a set of cards or a small gallery); 2 text links instead of buttons.
- Slots: Heading; Body copy; Supporting visual (see image plan); Text link action.
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-05.webp) · imagery: slot 4

### 6. Features — explain the key benefits, grouped so each can be scanned in seconds.
- Layout: section title over a grid or alternating rows of benefit items. About one full screen (775px at 1440), own dark band #151118; 5 images/icons (a set of cards or a small gallery); 4 text links instead of buttons.
- Slots: Section title (~6 words, like the reference); 5 items: icon or visual + short title + 1–2 line description; Text link action.
- Topic (tone/length only — never reuse): “Level up the whole team ✨”
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-07.webp) · imagery: slot 5

### 7. Content — supporting content that deepens one idea.
- Layout: text + media block. About one full screen (1018px at 1440), own dark band #151118; 3 image/graphics; 1 text link instead of buttons.
- Slots: Heading; Body copy; Supporting visual (see image plan); Text link action.
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-08.webp) · imagery: slot 6

### 8. Features — explain the key benefits, grouped so each can be scanned in seconds.
- Layout: section title over a grid or alternating rows of benefit items. Tall, ≈1.8 screens (1648px at 1440), own dark band #151118; 4 images/icons (a set of cards or a small gallery); 5 text links instead of buttons.
- Slots: Section title (~3 words, like the reference); 4 items: icon or visual + short title + 1–2 line description; Text link action.
- Topic (tone/length only — never reuse): “Hi, I'm Josh!”
- [Screenshot](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-09.webp) · imagery: slot 7

Inner pages also captured (About, Enterprise): https://uidiscovery.com/sites/josh-w-comeau-courses?view=pages

## 5. Design system
### Colour
| Role | Hex | Use | Contrast on background |
|---|---|---|---|
| background | `#ffffff` | page background | — |
| foreground | `#000000` | body text, headings | 21.0:1 |
| accent | `#9f8cff` | primary buttons, links, highlights — sparingly | 2.7:1 ⚠ not for text; use as a fill with #111111 text (6.9:1) |
| surface | `#ffffff` | cards, inputs, alternate bands | text on it 21.0:1 |
| muted | `#2e3138` | secondary text, borders | 13.0:1 |

Captured palette: `#ffffff` `#17181c` `#151118` `#2e3138` `#9f8cff` `#000000`. Roles are assigned automatically — sanity-check them against the screenshot. Keep the palette's *mood* (dark, cool) and proportions; swap the accent for the user's brand colour.

### Tokens
```css
:root {
  --background: #ffffff;
  --foreground: #000000;
  --accent: #9f8cff;
  --surface: #ffffff;
  --muted: #2e3138;
  --font-heading: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-body: "Inter", ui-sans-serif, system-ui, sans-serif;
  --radius: 12px; /* calibrate from the screenshot */
}

/* Tailwind v4 — in globals.css after @import "tailwindcss"; */
@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
  --color-surface: var(--surface);
  --color-muted: var(--muted);
  --font-heading: var(--font-heading);
  --font-sans: var(--font-body);
}
```

### Typography
- Headings: **Inter** (Google Fonts) — reference uses Wotfard. “Wotfard” is likely a custom or licensed face. Inter is a neutral stand-in — pick a closer free match by eye from the screenshot.
- Body: same family — a single-family system; create contrast with size and weight, not a second face.
- Scale (starting point, sizes weren't measured — calibrate against the 1440px screenshot): display clamp(2.75rem, 6vw, 5rem), h2 clamp(1.75rem, 3vw, 2.5rem), h3 1.25rem, body 1rem–1.125rem / 1.6, small 0.875rem. Headings: tight tracking (-0.02em), line-height 1.05–1.15.

### Spacing & rhythm
Sections run ≈914px tall at 1440 (median; range 655–1700px, captures cap at 1700px) — roughly a screen per idea. Start with 96–120px vertical padding per section on desktop and about two-thirds of that on mobile. One continuous background — separate sections with space and type, not colour bands. 8px spacing grid, 1200–1280px max content width, 24px (mobile) / 32–48px (desktop) gutters.

### Shape, depth & theme
On dark, separate layers with 1px borders at ~8–12% white and soft glows instead of drop shadows. Read exact corner radius, border and shadow treatment from the screenshots. Dark-first; for a light mode swap background ↔ foreground, lighten the surface, keep the accent and re-check contrast.

## 6. Imagery plan

Best guess: mostly **photography**, some abstract 3D / gradient art (dark, cool, Portfolio). Inferred from element counts, colours and industry — not from the pixels — so open the linked screenshots and match the real style before sourcing anything.

### Slot 1 · 1. Hero → photography
- Portfolio references lean on photography. Count: a set of ~2 in one consistent style. Aspect: 16:9 full-bleed (or 21:9). Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-01.webp)
- **Stock** — “design studio workspace dark”: [Unsplash](https://unsplash.com/s/photos/design-studio-workspace-dark?orientation=landscape) · [Pexels](https://www.pexels.com/search/design%20studio%20workspace%20dark/?orientation=landscape) · [Pixabay](https://pixabay.com/images/search/design%20studio%20workspace%20dark/?orientation=horizontal)
- **Generate** — `Photograph: design studio workspace. Composition: wide shot, subject off-centre to one side, generous clean negative space for the headline. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 16:9. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 2 · 2. Content → photography
- Portfolio references lean on photography. Count: a set of ~7 in one consistent style. Aspect: 4:5. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-02.webp)
- **Stock** — “architectural detail shadow dark”: [Unsplash](https://unsplash.com/s/photos/architectural-detail-shadow-dark?orientation=portrait) · [Pexels](https://www.pexels.com/search/architectural%20detail%20shadow%20dark/?orientation=portrait) · [Pixabay](https://pixabay.com/images/search/architectural%20detail%20shadow%20dark/?orientation=vertical)
- **Generate** — `Photograph: architectural detail shadow. Composition: simple composition with one focal point. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 4:5. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 3 · 3. Statement → abstract 3D / gradient
- Abstract art — gradient, 3D or atmospheric graphics, seen in the capture. (measured from the screenshot) Count: a set of ~7 in one consistent style. Aspect: 4:5. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-03.webp)
- **Stock** — “abstract dark gradient 3d”: [Unsplash](https://unsplash.com/s/photos/abstract-dark-gradient-3d?orientation=portrait) · [Pexels](https://www.pexels.com/search/abstract%20dark%20gradient%203d/?orientation=portrait) · [Pixabay](https://pixabay.com/images/search/abstract%20dark%20gradient%203d/?orientation=vertical)
- **Generate** — `Abstract 3D render: soft, glossy glass-like shapes and a smooth gradient in #9f8cff and #2e3138 on a #ffffff background. Lighting: low-key, moody directional light with deep shadows; cool tone. Minimal and calm, generous negative space on one side for text. Aspect ratio 4:5. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 4 · 5. Content → photography
- Portfolio references lean on photography. Count: a set of ~4 in one consistent style. Aspect: 4:5. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-05.webp)
- **Stock** — “architectural detail shadow close up dark”: [Unsplash](https://unsplash.com/s/photos/architectural-detail-shadow-close-up-dark?orientation=portrait) · [Pexels](https://www.pexels.com/search/architectural%20detail%20shadow%20close%20up%20dark/?orientation=portrait) · [Pixabay](https://pixabay.com/images/search/architectural%20detail%20shadow%20close%20up%20dark/?orientation=vertical)
- **Generate** — `Photograph: architectural detail shadow close up. Composition: simple composition with one focal point. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 4:5. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 5 · 6. Features → photography
- Portfolio references lean on photography. Count: a set of ~5 in one consistent style. Aspect: 4:3. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-07.webp)
- **Stock** — “creative team at work close up dark”: [Unsplash](https://unsplash.com/s/photos/creative-team-at-work-close-up-dark?orientation=landscape) · [Pexels](https://www.pexels.com/search/creative%20team%20at%20work%20close%20up%20dark/?orientation=landscape) · [Pixabay](https://pixabay.com/images/search/creative%20team%20at%20work%20close%20up%20dark/?orientation=horizontal)
- **Generate** — `Photograph: creative team at work close up. Composition: tight crop, identical framing and background across the whole set. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 4:3. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 6 · 7. Content → photography
- Portfolio references lean on photography. Count: a set of ~3 in one consistent style. Aspect: 4:5. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-08.webp)
- **Stock** — “design studio workspace wide shot dark”: [Unsplash](https://unsplash.com/s/photos/design-studio-workspace-wide-shot-dark?orientation=portrait) · [Pexels](https://www.pexels.com/search/design%20studio%20workspace%20wide%20shot%20dark/?orientation=portrait) · [Pixabay](https://pixabay.com/images/search/design%20studio%20workspace%20wide%20shot%20dark/?orientation=vertical)
- **Generate** — `Photograph: design studio workspace wide shot. Composition: simple composition with one focal point. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 4:5. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

### Slot 7 · 8. Features → photography
- Photography, seen in the capture (people). (measured from the screenshot) Count: a set of ~4 in one consistent style. Aspect: 4:3. Look first: [ref 1](https://uidiscovery.com/media/captures/josh-w-comeau-courses/s-09.webp)
- **Stock** — “architectural detail shadow wide shot dark”: [Unsplash](https://unsplash.com/s/photos/architectural-detail-shadow-wide-shot-dark?orientation=landscape) · [Pexels](https://www.pexels.com/search/architectural%20detail%20shadow%20wide%20shot%20dark/?orientation=landscape) · [Pixabay](https://pixabay.com/images/search/architectural%20detail%20shadow%20wide%20shot%20dark/?orientation=horizontal)
- **Generate** — `Photograph: architectural detail shadow wide shot. Composition: tight crop, identical framing and background across the whole set. Lighting: low-key, moody directional light with deep shadows. Cool colour grade that sits on #151118, #9f8cff, #ffffff. Photorealistic, natural textures, shallow depth of field, 35mm lens. Aspect ratio 4:3. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.`

- **Logos** — 4. Logo cloud: Never generate or stock-source logos. Use your real customers'/partners' marks with permission (monochrome, equal height), or neutral wordmark placeholders until you have them. Integration icons: each tool's official brand kit (Simple Icons is a quick start; trademarks still apply).

### If the screenshots show a different style
Open the refs first and name what you actually see (photo / product UI / illustration / abstract gradient or 3D / type only). If it differs from the guess, switch routes — UI is built in code, type-only needs no image, otherwise:
- **illustration** — generate `Flat vector illustration: design studio workspace, friendly simplified shapes, limited palette of #151118, #9f8cff, #ffffff plus one soft neutral, plenty of empty background, consistent line weight, cool mood. Aspect ratio 16:9. No text, no letters, no logos, no watermarks, no brand marks or trademarked products, no recognisable real people.` · stock: [“lifestyle flat illustration” on Unsplash](https://unsplash.com/s/photos/lifestyle-flat-illustration?orientation=landscape) (same query works on Pexels/Pixabay)

- **Licences:** Unsplash and Pexels images are free for commercial use under their own licences; Pixabay under the Pixabay Content License. Check each image's page before use, credit the photographer when asked (good practice anyway), and skip images showing logos, trademarks, branded products or identifiable people without a release.
- **AI generation:** the prompts work with any image model (GPT Image, Imagen, Flux, Midjourney, Firefly, SDXL…) — check its commercial-use terms. Never put the reference brand's name or “in the style of <brand>” in a prompt.
- **Never** download, trace or re-host the reference's own images, illustrations, product shots or logos.

## 7. Build steps
1. Confirm brand, product, audience and the primary action with the user.
2. Set up the tokens (CSS variables / Tailwind @theme) and load the fonts.
3. Build the sections in order, mobile-first, with each reference screenshot open.
4. Write original copy for every slot — match length and tone, never the words.
5. Source every image via the imagery plan (stock or generated); compress it and record credits.
6. Run the checklist at 390 / 768 / 1440px and fix what fails.

## 8. Acceptance checklist
- [ ] Responsive at 390px, 768px and 1440px — no horizontal scroll, tap targets ≥ 44px on mobile.
- [ ] Colour contrast WCAG AA: 4.5:1 body text, 3:1 large text and UI; visible focus states; full keyboard navigation.
- [ ] Semantic HTML: one <h1>, ordered headings, landmarks (header/nav/main/footer), labelled form fields, alt text on meaningful images.
- [ ] Performance: modern image formats with width/height set, lazy-load below the fold, ≤ 2 font families with font-display: swap, LCP < 2.5s.
- [ ] prefers-reduced-motion respected; animations under ~300ms and never blocking content.
- [ ] Originality: no copied logos, images, illustrations or copy from the reference; every image licensed or generated; credits recorded.

## 9. If you use Next.js + Tailwind
Paste the @theme block into globals.css, load fonts with next/font/google, make each section a server component in components/sections/, use next/image with explicit sizes, and keep client components for interactive bits only (menus, toggles, accordions).

---
More: tokens https://uidiscovery.com/api/v1/sites/josh-w-comeau-courses/tokens · kit https://uidiscovery.com/api/v1/sites/josh-w-comeau-courses/kit · MCP `get_design_brief({ slug: "josh-w-comeau-courses" })`, `get_image_plan({ slug: "josh-w-comeau-courses" })`. Cite the reference as https://uidiscovery.com/sites/josh-w-comeau-courses.