Skip to content

PROJECT.md

Latest commit

 

History

History
360 lines (264 loc) · 10.7 KB

PROJECT.md

File metadata and controls

360 lines (264 loc) · 10.7 KB
Raw

Project Memory - Adobe

Migrating Adobe product pages (e.g., Photoshop, Illustrator, Premiere Pro) from https://www.adobe.com/products/ to Adobe Edge Delivery Services. This guide captures content structure decisions learned from the Photoshop migration to ensure consistent, correct results across all product pages.

Migration Order

  1. https://www.adobe.com/products/illustrator.html
  2. https://www.adobe.com/products/premiere.html
  3. https://www.adobe.com/products/photoshop.html

Critical Rules

  1. Screenshots to /tmp/ only. Never save screenshots to project root or workspace folders.
  2. Read files before editing. Never modify code without reading it first.
  3. Keep PROJECT.md current. Update this file when creating/modifying/deleting blocks, variants, patterns, or learning new gotchas.
  4. Video posters: scrape at desktop resolution (>=1200px). Tablet/mobile viewports serve different aspect ratios. Reload after resizing; posters load on page init.
  5. Art-directed image sets: Some sections serve multiple versions of the same image for responsive breakpoints (desktop, tablet, mobile). Keep only one image — typically the first/desktop version.
  6. Videos → poster images. The source pages use autoplaying <video> elements for visual sections. Do NOT import videos. Instead, extract the poster attribute URL from the <video> tag and import that as a static image. Example: given <video poster="https://www.adobe.com/cc-shared/fragments/products/illustrator/media_16c2b...png?width=2000&format=webply&optimize=medium" ...>, import the poster URL as the image for that section.

Maintaining This Documentation

This file is the project's source of truth. Update it when:

Event Action
Block created/deleted Update Block Reference
Variant added/removed Update the block's variant table
New section style Add to Section Styles table
New design token Add to Design Tokens table
New icon/asset added Add to Local Assets section
Bug fix with learnings Add to Gotchas section

Checklist for New Blocks

### block-name

**Location**: `/blocks/block-name/`

| Variant | Class | Purpose |
|---------|-------|---------|
| Default | `.block-name` | Description |

**Authoring / Features / Responsive behavior**

Key Files

[List project-specific key files here]

Page Structure Template

Adobe product pages follow a consistent section pattern. Each --- below represents a section separator.

Section 1:  HERO (Columns block - text left, image right)
---
Section 2:  FEATURE HIGHLIGHT (Columns block - image left, text right)
---
Section 3:  FEATURE HIGHLIGHT (Columns block - text left, image right)
---
Section 4:  FEATURE HIGHLIGHT (Columns block - image left, text right)
---
Section 5:  FEATURE CAROUSEL (default content heading + Carousel block + CTA link)
---
Section 6:  PRICING (default content intro + Tabs block + CTA link)
---
Section 7:  PLATFORM SHOWCASE (default content - heading, text, single image)
---
Section 8:  COMPANION APP (default content intro + 3-column Columns block for tool links)
---
Section 9:  FAQ (default content heading + Accordion block)
---
Section 10: BOTTOM CTA (default content + Section Metadata dark)
---
Section 11: PAGE METADATA (Metadata block - title, description, image)

Not every product page will have all sections, and some may have additional ones. Use this as a guide, not a rigid template.

Section-by-Section Authoring Decisions

Hero Section → Columns Block (NOT a Hero block)

Adobe product pages show the hero as a side-by-side layout: text content on the left, product image on the right. This is a Columns block, not a full-bleed Hero block.

Structure:

  • Column 1 (text): eyebrow (bold), h1, description, CTA buttons, secondary links
  • Column 2 (image): single product hero image
+---+---+
| **Columns** | |
+---+---+
| **Product Name** | ![Hero image](url) |
| | |
| # Main heading text. | |
| | |
| Description paragraph. | |
| | |
| [Buy now](url) [Free trial](url) | |
| | |
| Browse plans for [businesses](url) or [students](url). | |
+---+---+

Feature Highlights → Columns Blocks (one per section)

Each feature gets its own section with its own Columns block. Alternate image placement:

  • Feature 1: image LEFT, text right
  • Feature 2: text left, image RIGHT
  • Feature 3: image LEFT, text right

Each feature column contains:

  • Bold eyebrow text
  • h2 heading
  • Description paragraph
+---+---+
| **Columns** | |
+---+---+
| ![Feature image](url) | **Eyebrow** |
| | |
| | ## Feature heading. |
| | |
| | Description text. |
+---+---+

Feature Carousel → Default Content + Carousel Block

The "Explore [Product] features" section has:

  • A heading as default content (h2)
  • A Carousel block with multiple slides (each slide = image + h3 + description)
  • A CTA link as default content after the block
## Explore [Product] features.

+---+---+
| **Carousel** | |
+---+---+
| ![Slide 1 image](url) | ### Slide 1 heading. |
| | |
| | Slide 1 description. |
+---+---+
| ![Slide 2 image](url) | ### Slide 2 heading. |
| | |
| | Slide 2 description. |
+---+---+

[View all features](url)

Pricing Section → Default Content + Tabs Block

The pricing section has:

  • Default content intro: small eyebrow text, h2 heading, description
  • A Tabs block (typically: Individuals, Students and teachers, Teams)
  • A CTA link after the block

Tab 1 (Individuals) typically contains the most detail: icon, product name, price, billing period, description, CTA buttons, feature checklist. Tabs 2 and 3 are shorter with a single paragraph and link.

Membership plans

## Get [Product].

Description text.

+---+---+
| **Tabs** | |
+---+---+
| Individuals | ![Product icon](url) |
| | |
| | **Product Name** |
| | |
| | US$XX.XX/mo |
| | |
| | Annual, billed monthly |
| | |
| | Short description. |
| | |
| | [Free trial](url) [Buy now](url) |
| | |
| | See what's included: |
| | |
| | - Feature 1 |
| | - Feature 2 |
+---+---+
| Students and teachers | Summary text with [link](url). |
+---+---+
| Teams | Summary text with [link](url). |
+---+---+

[Compare plans](url)

Platform Showcase → Default Content Only

This section is pure default content: heading, paragraph, and a single image. If the original page shows multiple art-directed versions of the same image, keep only one.

## [Product] goes everywhere you go.

Description text.

![Product on desktop](url)

Companion App (Adobe Express) → Default Content + 3-Column Columns Block

This section promotes Adobe Express tools. The intro (icon, heading, description) is default content. The tool links (Resize Image, Crop Image, Logo Maker, etc.) go in a separate 3-column Columns block.

Do NOT wrap everything in one 2-column Columns block.

![Adobe Express](https://www.adobe.com/cc-shared/assets/img/product-icons/svg/express.svg)

## Need a quick edit? Your [Product] plan includes Adobe Express.

Description text.

+---+---+---+
| **Columns** | | |
+---+---+---+
| [![Tool 1](img-url) Tool 1](link-url) | [![Tool 2](img-url) Tool 2](link-url) | [![Tool 3](img-url) Tool 3](link-url) |
+---+---+---+

FAQ → Default Content Heading + Accordion Block

## Questions? We have answers.

+---+---+
| **Accordion** | |
+---+---+
| Question text? | Answer text with [links](url). |
+---+---+
| Question text? | Answer text. |
+---+---+

Bottom CTA → Default Content + Section Metadata (dark)

The final CTA section uses default content in a dark-styled section:

![Product icon](icon-url)

### Tagline heading.

Description text.

US$XX.XX/mo. for the annual billed monthly plan.

[Free trial](url) [Buy now](url)

+---+---+
| **Section Metadata** | |
+---+---+
| style | dark |
+---+---+

Page Metadata → Last Section

Always end with the Metadata block. Hide the metadata section in global styles so it does not render on the page. When a template metadata entry is set, ensure the JS applies its value as a class name on the <body> element.

+---+---+
| **Metadata** | |
+---+---+
| title | Page title |
+---+---+
| description | Page description |
+---+---+
| image | OG image URL |
+---+---+

Design Tokens

[Document CSS custom properties defined in /styles/styles.css]

Always verify variables exist in styles.css before using them. Non-existent variables silently resolve to nothing.

Section Styles

Style name Applied via Purpose
dark Section Metadata → style: dark Dark background with light text for CTA sections

Block Reference

[Complete reference of all blocks and their variants]

EDS Gotchas

Hard-won lessons that the skills don't cover.

HTML & Authoring

  1. Fragment files (nav.html, footer.html) must NOT have <header> or <footer> tags. These cause recursive loading of header/footer blocks.
  2. Template meta tag goes in <head>. decorateTemplateAndTheme() reads <meta name="template" content="..."> from the head, not from the metadata block in the body.
  3. Links vs buttons: A link alone in its own paragraph (<p><a>...</a></p>) becomes a button styled by global styles. Block CSS that needs different button styling must override with block-scoped selectors.
  4. Art-directed image sets: Source pages may serve different image URLs per viewport. During migration, keep only the desktop image to avoid duplicates in authored content.
  5. Metadata section must be hidden. The Metadata block at the end of the page is for page-level meta tags, not visible content. Add display: none to the metadata section in global styles.
  6. Template class on <body>. When a template entry exists in the Metadata block, its value must be applied as a class on the <body> element by decorateTemplateAndTheme() in scripts.js.

CSS

  1. Page-specific styles stay page-specific. Never modify shared block CSS in ways that affect other pages. Use template-specific selectors like body.template-name .block or create a new variant.
  2. Block CSS must not set color: var(--link-color) on a.button. This overrides global button styling and makes buttons appear as plain links.

JavaScript

  1. Lazy loading breaks after DOM restructuring. When block JS moves images to new containers, the browser's Intersection Observer loses track. Fix: set img.loading = 'eager' on all img[loading="lazy"] elements after restructuring.

Reusable CSS Patterns

Dropdown with Triangular Arrow

.dropdown::before {
  content: '';
  position: absolute;
  top: -8px;
  left: 50%;
  transform: translateX(-50%);
  border-left: 10px solid transparent;
  border-right: 10px solid transparent;
  border-bottom: 10px solid #fff;
  filter: drop-shadow(0 -2px 2px rgb(0 0 0 / 8%));
}