designlang 12.10.1 → 12.11.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [12.11.0] — 2026-05-15
+
+**`brand --pdf` ships native PDF brand guides.**
+
+```bash
+npx designlang brand stripe.com --pdf
+# → stripe-com.brand.pdf  (print-ready, ~3–5s)
+```
+
+What you get on top of any "save as PDF":
+
+- **Per-chapter page breaks** — every section starts on a fresh page.
+- **Running footer** — `designlang · <subject> · <page> of <total>` on every page.
+- **Selectable text + embedded fonts** — never rasterized.
+- **`--paper a4|letter|tabloid` + `--landscape`** for any output target.
+- **`--attach-tokens`** embeds the DTCG tokens JSON *inside* the PDF as a
+  proper file attachment — open the PDF in Preview/Acrobat, hit the
+  paperclip, drop the JSON straight into Tailwind.
+- **`--no-print-background`** strips the brand-colour cover band for a
+  smaller file when you need it.
+
+Adds one tiny dep (`pdf-lib`, MIT, ~600KB) used only when `--attach-tokens`
+is passed; lazy-imported behind a dynamic `import()`.
+
 ## [12.10.1] — 2026-05-13
 
 **Tiny ship: \`stats\` now scans multiple URLs at once.**

package/bin/design-extract.js

@@ -53,6 +53,7 @@ import { buildPack } from '../src/pack.js';
 import { recolorDesign } from '../src/recolor.js';
 import { formatThemeSwap, formatThemeSwapMarkdown } from '../src/formatters/theme-swap.js';
 import { formatBrandBook, formatBrandBookMarkdown } from '../src/formatters/brand-book.js';
+import { htmlToPdf } from '../src/pdf.js';
 import { fuseDesigns, AXES } from '../src/fuse.js';
 import { formatPair, formatPairMarkdown } from '../src/formatters/pair.js';
 import { nameFromUrl } from '../src/utils.js';
@@ -1456,6 +1457,11 @@ program
   .option('-n, --name <name>', 'output file prefix (default: derived from URL)')
   .option('--format <fmt>', 'output format: html, md, json, all', 'all')
   .option('--open', 'open the HTML book in the default browser')
+  .option('--pdf', 'also emit a print-ready PDF brand guide (chapter bookmarks, running page numbers)')
+  .option('--paper <size>', 'PDF paper size: a4 | letter | tabloid', 'a4')
+  .option('--landscape', 'PDF landscape orientation')
+  .option('--no-print-background', 'strip the brand-colour cover band from the PDF (smaller file)')
+  .option('--attach-tokens', 'embed the DTCG tokens JSON as a PDF file attachment')
   .action(async (url, opts) => {
     if (!url.startsWith('http')) url = `https://${url}`;
     validateUrl(url);
@@ -1477,11 +1483,14 @@ program
       const prefix = opts.name || `${nameFromUrl(url)}.brand`;
       const written = [];
 
-      if (opts.format === 'all' || opts.format === 'html') {
-        const html = formatBrandBook(design, { version: PKG_VERSION });
-        const p = join(outDir, `${prefix}.html`);
-        writeFileSync(p, html);
-        written.push(p);
+      let bookHtml = null;
+      if (opts.format === 'all' || opts.format === 'html' || opts.pdf) {
+        bookHtml = formatBrandBook(design, { version: PKG_VERSION });
+        if (opts.format === 'all' || opts.format === 'html') {
+          const p = join(outDir, `${prefix}.html`);
+          writeFileSync(p, bookHtml);
+          written.push(p);
+        }
       }
       if (opts.format === 'all' || opts.format === 'md') {
         const md = formatBrandBookMarkdown(design);
@@ -1515,6 +1524,42 @@ program
         written.push(p);
       }
 
+      if (opts.pdf) {
+        spinner.text = 'Rendering PDF...';
+        const pdfPath = join(outDir, `${prefix}.pdf`);
+        const attachments = [];
+        if (opts.attachTokens) {
+          // Reuse the JSON we just wrote if available; otherwise build a DTCG payload on the fly.
+          let tokensJson;
+          try {
+            tokensJson = readFileSync(join(outDir, `${prefix}.json`));
+          } catch {
+            tokensJson = Buffer.from(JSON.stringify({
+              colors: design.colors, typography: design.typography,
+              spacing: design.spacing, motion: design.motion,
+            }, null, 2));
+          }
+          attachments.push({
+            filename: `${nameFromUrl(url)}-tokens.json`,
+            contents: tokensJson,
+            mimeType: 'application/json',
+            description: 'Design tokens (DTCG-aligned)',
+          });
+        }
+        await htmlToPdf(bookHtml, {
+          paper: opts.paper,
+          landscape: !!opts.landscape,
+          printBackground: opts.printBackground !== false,
+          attachments,
+          metadata: {
+            title: `${new URL(url).hostname} brand guidelines`,
+            subject: `${new URL(url).hostname} brand guidelines`,
+          },
+          outPath: pdfPath,
+        });
+        written.push(pdfPath);
+      }
+
       spinner.stop();
       const colorCount = (design.colors?.all || []).length;
       const fontCount = (design.typography?.families || []).length;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "designlang",
-  "version": "12.10.1",
-  "description": "Extract the complete design language from any website and ship it \u2014 clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
+  "version": "12.11.0",
+  "description": "Extract the complete design language from any website and ship it — clone to a working Next.js starter, guard tokens with a CI drift bot, or browse everything in a local studio. Outputs W3C DTCG tokens, motion tokens, typed anatomy stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {
     "designlang": "./bin/design-extract.js"
@@ -17,6 +17,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.0",
+    "pdf-lib": "^1.17.1",
     "playwright": "^1.42.0"
   },
   "engines": {
@@ -48,4 +49,4 @@
   ],
   "author": "masyv",
   "license": "MIT"
-}
+}

package/src/formatters/brand-book.js

@@ -945,7 +945,8 @@ export function formatBrandBook(design, opts = {}) {
     .cover, .toc, section { page-break-inside: avoid; border-color: #ddd; padding: 36px 32px; }
     .cover-band { background-color: var(--accent) !important; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
     .toc, .cover { page-break-after: always; }
-    section { page-break-after: always; }
+    section { page-break-before: always; page-break-after: always; break-before: page; }
+    .topbar { display: none !important; }
     .scale-table, .a11y-pair, .component-card { page-break-inside: avoid; }
   }
 </style>

package/src/pdf.js

@@ -0,0 +1,56 @@
+import { chromium } from 'playwright';
+import { writeFileSync } from 'fs';
+
+export async function htmlToPdf(html, opts = {}) {
+  const {
+    paper = 'a4',
+    landscape = false,
+    printBackground = true,
+    attachments = [],
+    metadata = {},
+    outPath,
+  } = opts;
+
+  const format = String(paper).toLowerCase();
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: 'networkidle' });
+
+    const subject = metadata.subject || '';
+    const buffer = await page.pdf({
+      format,
+      landscape: !!landscape,
+      printBackground,
+      margin: { top: '24mm', right: '18mm', bottom: '20mm', left: '18mm' },
+      displayHeaderFooter: true,
+      headerTemplate: `<div></div>`,
+      footerTemplate: `<div style="font-family: -apple-system, sans-serif; font-size: 9px; color: #888; width: 100%; padding: 0 18mm; display: flex; justify-content: space-between;"><span>designlang${subject ? ' · ' + escapeHtml(subject) : ''}</span><span><span class="pageNumber"></span> of <span class="totalPages"></span></span></div>`,
+    });
+
+    if (attachments.length) {
+      const { PDFDocument } = await import('pdf-lib');
+      const pdfDoc = await PDFDocument.load(buffer);
+      if (metadata.title) pdfDoc.setTitle(metadata.title);
+      if (metadata.subject) pdfDoc.setSubject(metadata.subject);
+      pdfDoc.setAuthor('designlang');
+      pdfDoc.setCreator('designlang');
+      for (const a of attachments) {
+        await pdfDoc.attach(a.contents, a.filename, {
+          mimeType: a.mimeType || 'application/json',
+          description: a.description || a.filename,
+        });
+      }
+      writeFileSync(outPath, await pdfDoc.save());
+    } else {
+      writeFileSync(outPath, buffer);
+    }
+  } finally {
+    await browser.close();
+  }
+  return outPath;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}