aem-eds-kit 0.4.54 → 0.4.58

package/CHANGELOG.md

@@ -7,6 +7,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Changed
+- **Illustrations on the site** (EDS-077): design sources → `eds` → block,
+  the command workflow (start → build → check → ship), one per audit card,
+  `aem up` serves / `eds` writes, the three quick-start steps, an AEM dialog
+  mapped onto a UE model (migration guide), one cached Figma call and local
+  models (docs). Inline SVG in the hero's style, with titles and descriptions
+  for screen readers; on phones the wide ones scroll sideways.
+- **`--sample` is the project's own example hero** (EDS-073), the same design
+  as `examples/figma-kit` and `site/example/`, instead of the third-party
+  "Kiri Bloom" hero (whose SVG wasn't valid XML: its comment held `--sample`).
+  New roadmap (Next / Then / Later) on the site and in the README; the README
+  opens with a 4-line quick start and a contents row.
 - **Docs and site match the CLI again** (EDS-063). README screenshots of real
   runs (the menu, `eds new`, `block from-design`, `migrate component`,
   `block test` / `check`, the preview harness) and design-vs-block images;
@@ -18,6 +29,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   Version links point at npm; the GitHub release links never existed.
 
 ### Fixed
+- **The site has a menu on phones** (EDS-079). Below 720px the nav links were
+  hidden with nothing to bring them back; a menu button (with `aria-expanded`,
+  closing on Esc, a link tap or widening the window) now opens them as a
+  full-width list on every page, with GitHub and npm inside it under 480px,
+  each with its mark (EDS-081).
+- **Scraped designs keep section backgrounds and one-sided lines** (EDS-067).
+  A full-width band with no background of its own now carries the colour painted
+  behind it (`inheritedBackground`, usually the page background), which the prompt
+  tells the agent to put on the block's section; borders that differ per side
+  (a bottom rule only) are kept as `borderTop` / `borderBottom` etc., and the
+  `0px none` noise on most nodes is gone. `eds block preview` / `block test` /
+  `block check` now render the block inside the section > wrapper DOM aem.js
+  builds, so section styles show up there too.
 - **`eds init --yes` no longer prompts for the authoring model** (EDS-061). It
   detects it from the `fstab.yaml` mountpoint (AEM author → Universal Editor,
   `content.da.live` → DA, Google Drive, SharePoint) or a crosswalk `paths.json`,
@@ -31,6 +55,22 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   where the Universal Editor boilerplate actually lives.
 
 ### Added
+- **Drafts: review rounds before a block reaches the repository** (EDS-085).
+  `block from-design --draft` keeps the result as a version under
+  `tmp/eds-cli/drafts/<name>/` and leaves `blocks/` untouched; `eds draft
+  preview | refine "<feedback>" | accept [--commit|--branch] | discard | list`
+  reviews it, adds a version per round and, on accept, copies it into
+  `blocks/<name>/` and commits it with the rounds in the message.
+- **A docs gate in CI** (EDS-083). On a PR, a change under `src/` fails without
+  a `CHANGELOG.md` entry, and a change to the CLI surface (`src/bin/eds.ts`) fails
+  without `README.md` (the npm page) and `site/docs.html` updates. Plus a PR
+  template with a docs checklist, and the rule in `CODING_STANDARDS.md` /
+  `CLAUDE.md`.
+- **Any web page is a design source** (EDS-065). `block from-design` scrapes
+  every http(s) link that isn't Figma, Framer or Stitch (`--provider web`): a
+  live site you're rebuilding, an HTML mock-up, or the project's own example page
+  (`https://piotrgodycki.github.io/aem-eds-kit/example/ --name cards`). Before,
+  such a link was taken for a Figma URL and rejected.
 - **`eds new [dir]`: clone the latest EDS boilerplate locally** (EDS-055). DA,
   Universal Editor (crosswalk) or Commerce, or any repo / git URL; no GitHub auth.
   Fresh git history by default, or `--keep-history` with an `upstream` remote;

package/README.md

@@ -12,13 +12,23 @@
 
 **Turn a design into an EDS block** - JS, CSS and a Universal Editor model - without leaving your terminal.
 
-`aem-eds-kit` gives you the `eds` command. Paste a design link - a Figma URL, or a Framer / Google Stitch page - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex, or a local model through Ollama / oMLX), which writes production-ready code straight into your repo. Figma is read through MCP or the REST API; Framer and Stitch render real HTML, so they're **scraped with headless Chromium** (no token needed). It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
+`aem-eds-kit` gives you the `eds` command. Paste a design link (a Figma frame, a Framer or Google Stitch page, or any web page) and it hands the design to the AI agent you already use: Claude Code, Cursor or Codex, or a local model through Ollama / oMLX. The agent writes the block straight into your repo. Figma is read through its REST API or MCP; web pages are **scraped with headless Chromium**, no token needed.
 
-It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
+It lives next to `@adobe/aem-cli` (your `aem up` dev server) and handles everything around it: new projects, blocks, migration from AEM, previews, checks and publishing.
+
+```bash
+npm install -g aem-eds-kit
+eds new my-site && cd my-site                     # the latest Adobe boilerplate
+eds block from-design "<design link>" --name hero  # design → blocks/hero/
+eds block preview hero                            # see it in the browser
+```
+
+**Contents:** [What it does](#what-it-does) · [Install](#install) · [Try it](#try-it-in-30-seconds-no-figma-account-no-token) · [Interactive mode](#interactive-mode) · [Commands](#commands) · [Figma](#how-figma-integration-works) · [Local models](#local-models-ollama-omlx) · [Configuration](#configuration) · [Roadmap](#roadmap)
 
 ## What it does
 
-- **Blocks from a design.** A Figma frame (REST or MCP), a Framer / Google Stitch page (scraped with headless Chromium) or a local PNG / SVG export becomes `blocks/<name>/`: JS, CSS, a Universal Editor model and a preview mock. Works with Claude Code, Cursor and Codex, or a [local model](#local-models-ollama-omlx) through Ollama or oMLX. Content Fragment blocks (`--source cf` / `mixed`) get an async, fetching `decorate()`.
+- **A new project in one command.** `eds new` clones Adobe's latest boilerplate (Document Authoring, Universal Editor or Commerce) without a GitHub login, and `eds init` sets it up for your authoring model.
+- **Blocks from a design.** A Figma frame (REST or MCP), a Framer / Google Stitch page or any other web page (scraped with headless Chromium), or a local PNG / SVG export becomes `blocks/<name>/`: JS, CSS, a Universal Editor model and a preview mock. Works with Claude Code, Cursor and Codex, or a [local model](#local-models-ollama-omlx) through Ollama or oMLX. Content Fragment blocks (`--source cf` / `mixed`) get an async, fetching `decorate()`.
 - **Migration from AEM.** `eds migrate component` turns a classic component's dialog into a block and a UE model, with no agent involved. It handles AEM as a Cloud Service proxy components (via `sling:resourceSuperType`, e.g. onto Core Components) and AEM 6.5 Classic UI `dialog.xml` files.
 - **Within Figma's limits.** One REST or MCP call per block, then a cache. REST calls are paced per minute across parallel runs. A rate limit stops with the reset time; it never spends your MCP budget behind your back. [The limits](#how-figma-integration-works).
 - **QA before review.** `eds block test` does visual regression on the block itself, plus a design↔render diff. `eds block check` covers content and a11y, including preview mocks nested deeper than real EDS markup. There are also `doctor`, loading and security audits.
@@ -89,24 +99,25 @@ eds block from-design --sample --name hero             # generate it with your A
 eds block preview hero                                  # see it live in the browser
 ```
 
-`--sample` uses a **bundled "Kiri Bloom" hero design**, read straight from disk - **no Figma token, no MCP call, no network**. (`--dry-run` needs no AI agent either - it just prints the prompt.)
+`--sample` uses the **hero of the project's example design**, bundled as an SVG and read straight from disk - **no Figma token, no MCP call, no network**. (`--dry-run` needs no AI agent either - it just prints the prompt.)
 
 A real run (Claude Code): the agent's live log, a verification pass over the files it wrote, then a menu to refine, preview or finish.
 
-<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-fd.png" alt="Terminal: eds block from-design --sample --name promo, showing the design source, the agent's live log, the files it wrote, a verification table and the refine / preview / finish menu" width="760"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-fd.png" alt="Terminal: eds block from-design --sample (the example hero), showing the design source, the agent's live log, the files it wrote, a verification table and the refine / preview / finish menu" width="760"></p>
 
 `eds block preview` serves the block at the design's own widths, with live reload:
 
 <p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/block-preview.webp" alt="Browser: the eds block preview harness showing the hero block at 1440 px with a breakpoint dropdown" width="100%"></p>
 
-Ready for the real thing? Point it at the official **Kiri Bloom AEM EDS Kit** training file in Figma:
+Ready for the real thing? The same example design exists as a page you can build every block from, and as a Figma file:
 
 ```bash
-eds block from-design \
-  "https://www.figma.com/design/vwlEKTFhcrlwuA8dRgN5SD/Kiri-Bloom-AEM-EDS-Kit-Example?node-id=0-1" \
-  --name hero
+# the example page (11 sections: hero, stats, cards, …) - read like a Framer / Stitch page
+eds block from-design "https://piotrgodycki.github.io/aem-eds-kit/example/" --name cards
 ```
 
+The Figma version is built by the plugin in [`examples/figma-kit`](https://github.com/piotrgodycki/aem-eds-kit/tree/main/examples/figma-kit) (run it once in Figma desktop); then pass any of its frame links.
+
 ## Interactive mode
 
 Run `eds` with no command and it opens an **interactive menu** that stays open between actions (arrows to move, Enter to run, **Esc** to go back - or to quit from the menu itself; Ctrl+C quits anywhere). It walks you through every feature: new project (clone the boilerplate), set up project, page template, sandbox repo, block from design, migrate component, scaffold UE, empty block, integration, model fields, analytics, structured data, Universal Editor, preview block, pages (preview / publish), audits and Figma MCP.
@@ -369,7 +380,7 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 Translates a design - **a Figma URL, a Framer / Google Stitch page, or a local SVG/PNG export** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor or Codex, or a [local model](#local-models-ollama-omlx)). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
 
-**Figma vs. web sources.** Figma paints to a WebGL canvas, so it's read through the **REST API** (with a token) or **MCP**. Framer and Google Stitch render **real HTML**, so `eds` **scrapes** them with headless Chromium — reading computed layout, typography, colours and geometry straight off the page (no token, no MCP). Canva and Sketch are canvas/image-based and aren't scrapeable — export a frame and pass it as a local SVG/PNG. The provider is detected from the URL host, or set with `--provider`.
+**Figma vs. web sources.** Figma paints to a WebGL canvas, so it's read through the **REST API** (with a token) or **MCP**. Framer, Google Stitch and **any other web page** (a live site you're rebuilding, an HTML mock-up) render **real HTML**, so `eds` **scrapes** them with headless Chromium — reading computed layout, typography, colours and geometry straight off the page (no token, no MCP). On a page with several sections, the block is built from the one matching `--name`: try `eds block from-design https://piotrgodycki.github.io/aem-eds-kit/example/ --name cards`. Canva and Sketch are canvas/image-based and aren't scrapeable — export a frame and pass it as a local SVG/PNG. The provider is detected from the URL (Figma, Framer, Stitch, else a web page), or set with `--provider`.
 
 **Gated sources (`--auth`).** A Google Stitch project (and a private Framer page) sits behind a login, so an anonymous scrape only sees the sign-in shell. Pass `--auth` and `eds` opens a **headed** browser once — you log in by hand, it saves the session, and every later scrape reuses it. The session (cookies/localStorage) is stored owner-only under `~/.eds/auth/<provider>.json`; re-login with `--auth-refresh`. (The saved session is a secret — it's never written to the repo.)
 
@@ -401,15 +412,16 @@ eds block from-design                               # interactive wizard
 eds block from-design "<figma-url>" --name hero     # non-interactive (REST if a token is set, else MCP)
 eds block from-design "<framer-url>" --name hero    # Framer/Stitch → scraped with headless Chromium
 eds block from-design "<stitch-url>" --name hero --auth   # gated source → log in once, reuse the session
+eds block from-design "https://piotrgodycki.github.io/aem-eds-kit/example/" --name cards   # any web page, one section
 eds block from-design ./hero.svg --name hero        # from a local export (no network)
-eds block from-design --sample --name hero          # bundled Kiri Bloom sample (no token, no MCP)
+eds block from-design --sample --name hero          # bundled example hero (no token, no MCP)
 eds block from-design "<figma-url>" --dry-run       # just build the prompt
 ```
 
 | Flag | Description |
 |---|---|
 | `--name <name>` | Override the inferred block name |
-| `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` (else detected from the URL) |
+| `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` \| `web` (else detected from the URL) |
 | `--source <type>` | Content source: `document` \| `ue` \| `cf` \| `mixed` (`cf` / `mixed` default to the `sonnet` model) |
 | `--widths <list>` | Design frame widths for preview breakpoints (e.g. `390,768,1440`) |
 | `--agent <type>` | Force `claude` \| `cursor` \| `codex` \| `ollama` \| `omlx` \| `local` \| `none` (a prompt too large for one argument reaches Cursor / Codex as its file; see [Local models](#local-models-ollama-omlx)) |
@@ -421,8 +433,9 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 | `--auth` | Scrape with a logged-in session (Framer/Stitch): log in once, reuse it |
 | `--auth-refresh` | Force a fresh scrape login even if a session is saved |
 | `--refresh` | Ignore the cached snapshot and re-fetch |
-| `--sample` | Use the bundled Kiri Bloom sample design (no URL, token or MCP) |
+| `--sample` | Use the bundled sample design, the example file's hero (no URL, token or MCP) |
 | `--serve` | Auto-start the live preview (non-interactive runs only) |
+| `--draft` | Generate a draft for review instead of writing `blocks/<name>/` (see [`eds draft`](#eds-draft)) |
 | `--yes` | Skip confirmation prompts |
 
 Set a **Figma Personal Access Token** (scope `file_content:read`) to use the REST path — via `FIGMA_TOKEN` env or `figma.token` in config. The block generation model defaults to the fastest (Haiku); override with `model` in config.
@@ -443,6 +456,21 @@ Interactive wizard that:
 3. Shows install commands if not
 4. Saves preferences to `~/.eds/config.json`
 
+### `eds draft`
+
+Review a block before it reaches the repository. With `--draft`, `block from-design` keeps its result as a **draft version** under `tmp/eds-cli/drafts/<name>/v1/`. `blocks/<name>/` stays exactly as it was: an existing block is set aside while the agent works and always put back. Each review round adds a version; nothing is written to `blocks/` until the draft is accepted, either right away or after a few rounds.
+
+```bash
+eds block from-design "<design link>" --name hero --draft   # → draft v1
+eds draft preview hero                                      # review it (latest version)
+eds draft refine hero "bigger headline, orange buttons"     # one more round → v2
+eds draft accept hero --branch feature/hero                 # → blocks/hero/, committed
+eds draft list                                              # drafts and their versions
+eds draft discard hero                                      # drop it; blocks/ untouched
+```
+
+`accept --commit` (or `--branch <name>`, created if missing) commits only `blocks/<name>/`, with the review rounds in the message (`v1: first version`, `v2: "bigger headline, orange buttons"`). `refine` reuses the agent and model that made the draft unless you pass `--agent` / `--model`; `preview` and `accept` take `--version <n>`.
+
 ### `eds block list`
 
 Lists all blocks in the project with their file status and Figma source info.
@@ -732,6 +760,8 @@ git clone https://github.com/piotrgodycki/aem-eds-kit.git && cd aem-eds-kit
 npm install
 ```
 
+Each change goes through an issue (`EDS-NNN`), a `feature/EDS-NNN` or `bug/EDS-NNN` branch and a PR, and **ships with its docs**: a `CHANGELOG.md` entry, `README.md` (this file is also the npm page) and the site pages it touches. CI's docs gate (`scripts/check-docs.mjs`) fails a PR that changes `src/` without a changelog entry, or the commands and flags in `src/bin/eds.ts` without `README.md` and `site/docs.html`. See [`CODING_STANDARDS.md`](https://github.com/piotrgodycki/aem-eds-kit/blob/main/CODING_STANDARDS.md).
+
 ### Scripts
 
 ```bash
@@ -800,11 +830,21 @@ Tests use fixtures in `tests/fixtures/` - a sample EDS project and recorded Figm
 
 ## Roadmap
 
-- **Design sources** - Figma (REST/MCP), Framer and Google Stitch (headless-Chromium scrape) are wired; next is deepening the scrape extractor (multi-breakpoint capture, component/variant detection), a generic `eds setup` in place of `eds figma setup`, and an end-to-end run against a real Figma file ([EDS-020](https://github.com/piotrgodycki/aem-eds-kit/issues/20)). Canva/Sketch stay on the local-export path (canvas/image — not scrapeable).
-- **Migration** - dialogs (Touch UI and Classic UI) map deterministically today; next is HTL → `decorate()` and capturing CSS from the rendered page.
-- **Image-only designs** - a plain PNG/JPG already works (`from-design ./hero.png`, or a vision model with `--agent ollama --model qwen2.5vl:7b`); next is measuring it (no structured layout in a bitmap, so pixel-perfect is harder than from Figma or a scraped page).
-- **Tokens & sync** - design variables → CSS custom properties, and incremental re-sync of an existing block (`--update`).
-- **Headless & CI** - a direct MCP client (no agent needed) for CI/CD, plus `eds lighthouse`, `eds rum` and `eds migrate page`.
+**Next**
+- **Previews that look like the design.** The preview gets the design's real copy and images, so it matches 1:1; the block itself still reads authored content.
+- **A self-check against the design.** Render the block, compare it with the Figma frame or the page, and fix what differs in a second pass.
+- **Every breakpoint.** Read the design at mobile, tablet and desktop widths, not just one.
+
+**Then**
+- **Whole screens in one go.** Every section of a frame or page becomes a block, plus the page that puts them together.
+- **Blocks that follow the design.** When the design changes, update the existing block instead of regenerating it.
+- **Design tokens for the project.** Figma Variables become the CSS custom properties in `styles.css`.
+
+**Later**
+- **Deeper AEM migration.** HTL logic ported to `decorate()`, CSS taken from the rendered page, whole pages migrated.
+- **Performance in the loop.** Lighthouse and real-user data (RUM) checked for every block.
+
+Something missing? [Open an issue](https://github.com/piotrgodycki/aem-eds-kit/issues): the roadmap follows what people need.
 
 ## Trademarks & affiliation