diff --git a/docs/images/ledger/deposit-flow-1.png b/docs/images/ledger/deposit-flow-1.png new file mode 100644 index 000000000..14915f9c7 Binary files /dev/null and b/docs/images/ledger/deposit-flow-1.png differ diff --git a/docs/images/ledger/withdraw-flow-1.png b/docs/images/ledger/withdraw-flow-1.png new file mode 100644 index 000000000..535b7204b Binary files /dev/null and b/docs/images/ledger/withdraw-flow-1.png differ diff --git a/package-lock.json b/package-lock.json index ae14091fc..4e00f10e9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,63 @@ { - "name": "base-docs", + "name": "docs", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, - "packages": {} + "packages": { + "": { + "name": "docs", + "version": "1.0.0", + "license": "ISC", + "devDependencies": { + "playwright": "^1.61.0" + } + }, + "node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/playwright": { + "version": "1.61.0", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.0.tgz", + "integrity": "sha512-Z+7BeeqQPRRzklHsVFP4KTGIyMxKUmfeRA4WisM6G3/XW6nwGeX6fX9qYaDa+CiUqpOkb2f6X3nar05R3kSuJQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.61.0" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "fsevents": "2.3.2" + } + }, + "node_modules/playwright-core": { + "version": "1.61.0", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.0.tgz", + "integrity": "sha512-caX7TrY3Ml6egyDX0WUcTHDxodl/b51y5wJOdCEA36QviK/s2g081hvmGs8eaE3DWb6NYZQ6BjO/QkNRPenoPA==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=18" + } + } + } } diff --git a/package.json b/package.json new file mode 100644 index 000000000..31ade759d --- /dev/null +++ b/package.json @@ -0,0 +1,27 @@ +{ + "name": "docs", + "version": "1.0.0", + "description": "

\"Base

", + "main": "index.js", + "directories": { + "doc": "docs" + }, + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/base/docs.git" + }, + "keywords": [], + "author": "", + "license": "ISC", + "type": "commonjs", + "bugs": { + "url": "https://github.com/base/docs/issues" + }, + "homepage": "https://github.com/base/docs#readme", + "devDependencies": { + "playwright": "^1.61.0" + } +} diff --git a/scripts/diagrams/deposit-flow.html b/scripts/diagrams/deposit-flow.html new file mode 100644 index 000000000..3ba301464 --- /dev/null +++ b/scripts/diagrams/deposit-flow.html @@ -0,0 +1,69 @@ + + + + + + Deposit flow + + +
+ +
+
User
+
Ledger
+
Portal
+
+ + +
+ +
+
+
+ + +
+
+
+ + +
Prepare
+
Deposit
+
Credit
+ + +
+ encrypt recipient +
+
+
+ +
+ encrypted recipient +
+
+
+ + +
+ deposit(encrypted recipient, amount) +
+
+
+ + +
+ Deposit event +
+
+
+ + +
+
Decrypt & Credit
+
credit the ledger
+
+
+
+ + diff --git a/scripts/diagrams/render.mjs b/scripts/diagrams/render.mjs new file mode 100644 index 000000000..79b0b4779 --- /dev/null +++ b/scripts/diagrams/render.mjs @@ -0,0 +1,36 @@ +/* + * Renders the BDS sequence-diagram HTML sources to PNG via headless Chromium. + * Output is written next to the original ledger flow images. + */ +import { chromium } from "playwright"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { dirname, join, resolve } from "node:path"; + +const here = dirname(fileURLToPath(import.meta.url)); +const outDir = resolve(here, "../../docs/images/ledger"); + +const jobs = [ + { html: "deposit-flow.html", out: "deposit-flow-1.png" }, + { html: "withdraw-flow.html", out: "withdraw-flow-1.png" }, +]; + +function log(event, fields = {}) { + process.stdout.write( + JSON.stringify({ timestamp: new Date().toISOString(), level: "info", event, ...fields }) + "\n", + ); +} + +const browser = await chromium.launch(); +try { + const page = await browser.newPage({ deviceScaleFactor: 2 }); + for (const job of jobs) { + const url = pathToFileURL(join(here, job.html)).href; + await page.goto(url, { waitUntil: "networkidle" }); + const element = page.locator("#diagram"); + const outPath = join(outDir, job.out); + await element.screenshot({ path: outPath }); + log("diagram_rendered", { source: job.html, output: outPath }); + } +} finally { + await browser.close(); +} diff --git a/scripts/diagrams/style.css b/scripts/diagrams/style.css new file mode 100644 index 000000000..7b7e4b4b4 --- /dev/null +++ b/scripts/diagrams/style.css @@ -0,0 +1,183 @@ +/* + * BDS sequence-diagram styles. + * Derived from style-chart.md: gray scale is the foundation; brand blue is + * reserved for the highlighted action path only. + */ +:root { + --gray-0: #ffffff; + --gray-5: #f8f8f8; + --gray-10: #efefef; + --gray-15: #dadada; + --gray-40: #9a9a9a; + --gray-50: #6f6f6f; + --gray-60: #5e5e5e; + --gray-90: #262626; + --gray-100: #111111; + --blue: #0000ff; +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + background: var(--gray-0); + font-family: "Inter", "Helvetica Neue", Arial, system-ui, sans-serif; + -webkit-font-smoothing: antialiased; +} + +.diagram { + position: relative; + width: 1024px; + background: var(--gray-0); +} + +/* Participant headers */ +.headers { + position: relative; + height: 56px; +} + +.pill { + position: absolute; + top: 10px; + transform: translateX(-50%); + width: 220px; + padding: 11px 0; + text-align: center; + background: var(--gray-100); + color: var(--gray-0); + border-radius: 9999px; + font-size: 17px; + font-weight: 400; + letter-spacing: -0.01em; +} + +/* Body / sequence area */ +.body { + position: relative; +} + +.band { + position: absolute; + left: 0; + right: 0; +} + +.band.gray { + background: var(--gray-5); +} + +.lifeline { + position: absolute; + top: 0; + bottom: 0; + width: 0; + border-left: 1px dashed var(--gray-15); +} + +.section-label { + position: absolute; + left: 24px; + font-size: 12px; + font-weight: 500; + letter-spacing: 0.06em; + text-transform: uppercase; + color: var(--gray-40); +} + +/* Arrows: container left/width map to lifeline x positions */ +.arrow { + position: absolute; + height: 0; +} + +.arrow .label { + position: absolute; + bottom: 7px; + left: 0; + right: 0; + text-align: center; + font-size: 13px; + color: var(--gray-60); + white-space: nowrap; +} + +.arrow .line { + position: absolute; + top: 0; + left: 0; + right: 0; +} + +.arrow.blue .line { + border-top: 2px solid var(--blue); +} + +.arrow.gray .line { + border-top: 1.5px solid var(--gray-40); +} + +.arrow .head { + position: absolute; + top: 0; + width: 0; + height: 0; + transform: translateY(-50%); + border-top: 5px solid transparent; + border-bottom: 5px solid transparent; +} + +.arrow.blue .head.right { + right: 0; + border-left: 8px solid var(--blue); +} + +.arrow.blue .head.left { + left: 0; + border-right: 8px solid var(--blue); +} + +.arrow.gray .head.right { + right: 0; + border-left: 8px solid var(--gray-40); +} + +.arrow.gray .head.left { + left: 0; + border-right: 8px solid var(--gray-40); +} + +/* Cards */ +.card { + position: absolute; + transform: translateX(-50%); + background: var(--gray-0); + border: 1px solid var(--gray-10); + border-radius: 10px; + padding: 12px 20px; + text-align: center; +} + +.card .title { + font-size: 15px; + font-weight: 400; + color: var(--gray-90); + letter-spacing: -0.01em; +} + +.card .sub { + margin-top: 3px; + font-size: 13px; + color: var(--gray-50); +} + +.card.chip { + padding: 10px 18px; + white-space: nowrap; +} + +.card.chip .title { + font-size: 14px; +} diff --git a/scripts/diagrams/withdraw-flow.html b/scripts/diagrams/withdraw-flow.html new file mode 100644 index 000000000..1813f1c5d --- /dev/null +++ b/scripts/diagrams/withdraw-flow.html @@ -0,0 +1,66 @@ + + + + + + Withdraw flow + + +
+ +
+
User
+
Ledger
+
Base
+
+ + +
+ +
+
+ + +
+
+
+ + +
Prepare
+
Withdraw
+ + +
+ request withdraw auth +
+
+
+ + +
+
Operator-signed
+
withdraw authorization
+
+ + +
+ authorization +
+
+
+ + +
+ withdraw(authorization, asset, amount) +
+
+
+ + +
+
Release funds · compose with Base actions
+
+
+
+ + diff --git a/style-chart.md b/style-chart.md new file mode 100644 index 000000000..3120ed8e2 --- /dev/null +++ b/style-chart.md @@ -0,0 +1,172 @@ +Base Diagram Style Guide +======================== +Feed this file to Claude when generating diagrams for Base documentation. +It defines the visual language derived from the Base web design system (BDS). + + +1. COLOR PALETTE +---------------- + +Use the BDS gray scale as the primary palette for diagrams. +Reserve brand blue for emphasis, CTAs, or highlighted paths. + +Gray Scale (light mode): + gray-0 #FFFFFF ── canvas / diagram background + gray-5 #F8F8F8 ── subtle card background, alternating rows + gray-10 #EFEFEF ── card borders, divider lines + gray-15 #DADADA ── secondary borders + gray-20 #C4C4C4 ── disabled / de-emphasized strokes + gray-30 #B8B8B8 ── placeholder text + gray-40 #9A9A9A ── muted labels, annotations + gray-50 #6F6F6F ── secondary text + gray-60 #5E5E5E ── body text (on white) + gray-80 #3A3A3A ── strong labels + gray-90 #262626 ── headings, primary text + gray-100 #111111 ── highest contrast text, dark fills + +Dark-on-light rule: text on white backgrounds should be gray-90 (#262626) or black (#000000). +Light-on-dark rule: text on dark backgrounds should be white (#FFFFFF) or gray-5 (#F8F8F8). + +Brand Blue: + base-blue #0000FF ── primary brand accent, interactive highlights + blue-60 #0052FF ── links, selected states + blue-40 #266EFF ── lighter accent + blue-5 #D3E1FF ── blue tint backgrounds + +Semantic Colors (use sparingly, only when meaning is needed): + green-50 #129961 ── success, positive + red-60 #CF202F ── error, destructive + yellow-50 #CF9700 ── warning, caution + orange-50 #E1591B ── attention + + +2. TYPOGRAPHY +------------- + +Font families (in order of preference): + Primary: "Base Sans" (--font-base-sans) or fallback to system sans-serif + Body text: "Base Sans Text" (--font-base-sans-text) — optimized for reading + Monospace: "Base Sans Mono" or fallback to system monospace + Display: "Base Sans" at 400 weight with tight tracking + +For diagrams, use a clean sans-serif (Inter, Helvetica, or system default if +custom fonts are unavailable). Avoid decorative fonts. + +Text sizes (use these as reference — scale proportionally for diagram context): + Display 36–56px ── diagram title (rarely needed) + Title 1 24–28px ── section headings within a diagram + Title 2 20–24px ── subsection or group headings + Title 3 18–20px ── card titles, node names + Headline 16–18px ── emphasized labels + Body 15–16px ── descriptions, annotations + Label 13–14px ── small labels, tag text + Caption 11–12px ── footnotes, fine print (uppercase, 500 weight) + +General rules: + - Font weight: 400 (regular) for almost everything. Use 500 for captions. + - Letter spacing: tight (-0.01em to -0.04em) for headings, 0 for body. + - Do not use bold (700) for headings — the site uses regular weight throughout. + + +3. SHAPES & BORDER RADIUS +-------------------------- + + Cards / containers: 10px border-radius (the standard "card" radius) + Buttons / pills: 9999px (fully rounded / pill shape) + Small chips / tags: 6–8px + Code blocks: 8–12px + Icons / avatars: 50% (circle) + +Default to 10px radius for any rectangular container in diagrams. +Use fully rounded (pill) only for action buttons or status badges. +Avoid sharp 0px corners — the design language is always softly rounded. + + +4. BORDERS & STROKES +--------------------- + + Primary border: 1px solid gray-10 (#EFEFEF) + Subtle border: 1px solid rgba(0, 0, 0, 0.06–0.10) + On dark backgrounds: 1px solid rgba(255, 255, 255, 0.10–0.20) + Emphasis border: 1px solid gray-15 (#DADADA) + +For connector lines / arrows in diagrams: + Default stroke: 1.5–2px, gray-20 (#C4C4C4) or gray-40 (#9A9A9A) + Highlighted path: 2px, base-blue (#0000FF) + Arrow style: simple pointed, not ornate + + +5. BACKGROUNDS & FILLS +----------------------- + + Page background: #FFFFFF (light) / #111111 (dark) + Card background: #FFFFFF with 1px gray-10 border + Subtle card fill: gray-5 (#F8F8F8) — no border needed + Grouped section: gray-5 (#F8F8F8) or rgba(0, 0, 0, 0.03) + Highlighted fill: blue-5 (#D3E1FF) for blue-tinted callouts + Dark card: gray-100 (#111111) with rgba(255, 255, 255, 0.08) border + + +6. SHADOWS +---------- + +Use shadows sparingly. The site favors flat design with borders over heavy shadows. + + Subtle elevation: 0 4px 24px rgba(0, 0, 0, 0.08), 0 0 0 1px rgba(0, 0, 0, 0.08) + Medium elevation: 0 8px 48px rgba(0, 0, 0, 0.35), 0 0 0 1px rgba(255, 255, 255, 0.08) + +Most diagram elements should have no shadow — use borders for separation. + + +7. SPACING +---------- + +Use a 4px base grid. Common spacing values: + + 4px (gap-1) ── tight, between inline elements + 8px (gap-2) ── compact groups + 12px (gap-3) ── related items within a card + 16px (gap-4) ── standard internal card padding, between card sections + 24px (gap-6) ── between cards or groups + 32px (gap-8) ── between diagram sections + 48px (gap-12) ── major section breaks + +Card internal padding: 16–24px. +Content max-width: 1200px (for full-width diagrams). + + +8. LAYOUT GUIDELINES +--------------------- + + - Left-to-right flow for processes, top-to-bottom for hierarchies. + - Align elements to the 4px grid. + - Group related nodes visually using subtle gray-5 background regions. + - Use generous whitespace — the site aesthetic is clean and airy. + - Maximum content width in diagrams should match the site: ~1200px. + + +9. ICONOGRAPHY +-------------- + + - Line-style icons, not filled. + - Stroke width: 1.5–2px. + - Icon size: 16–24px for inline, 32–40px for feature callouts. + - Icon color: match surrounding text color (gray-90 on light, white on dark). + + +10. DO / DON'T +-------------- + + DO: + - Use the gray scale as the foundation; add blue only for emphasis. + - Keep rounded corners consistent at 10px for containers. + - Use regular (400) weight text — the brand avoids heavy bold type. + - Keep diagrams clean with ample whitespace. + + DON'T: + - Use bright multi-color palettes — the site is intentionally restrained. + - Use drop shadows as a primary visual separator. + - Mix rounded and sharp corners in the same diagram. + - Use stroke widths thinner than 1px. + - Use all-caps except for caption/footnote-style labels. + - Use gradients unless replicating a specific site pattern. \ No newline at end of file