Portable reference · repository extraction

Gandalf

A restrained, security-oriented design system for trustworthy websites and applications— shaped by a dark “wizard gate,” a warm parchment counterpart, quiet gold actions, and technical clarity at consequential boundaries.

Actual UI language AA corrections visible Extensions labeled
Reference
v0.1.0-placeholder
Source
Gandalf v0.2.0
Extracted
Canonical
Dark “wizard gate”
Companion
Light “parchment”

01 · Foundations

A gate, not a trading floor.

Gandalf’s source avoids the visual noise of generic crypto products. It uses dense but calm surfaces, serif moments for identity and value, monospace for addresses and hashes, and color chiefly for action, ledger identity, and explicit state.

Sealed by default

Security is a visible boundary

Passwords appear at the signing edge, secret warnings are direct, and the header continuously says “sealed.”

Extracted

Warm restraint

Gold guides; it does not decorate

Gold marks the sigil, primary action, focus, selection, and high-value identity cues.

Extracted

Technical honesty

Show the transaction machinery

Inputs, outputs, fees, network, destination, hashes, reservations, and node reasons remain inspectable.

Extracted

Do

Use warm neutrals, compact hierarchy, explicit state labels, and plain security language. Keep addresses, amounts, and hashes stable with monospace or tabular numerals.

Don’t

Add neon gradients, speculative market imagery, anonymous “web3” styling, or color-only status. Avoid making a dangerous action look routine.

One system, two themes

Unified contract

Light and dark change semantic color while every current Gandalf surface keeps comfortable spacing. Compact tokens remain available for compatibility, but are not an end-user setting.

Comfortable · websitePage recipe

Clear public narrative

Explain the value before the machinery.

Use generous rhythm, readable line length, proof-oriented cards, and one obvious next action.

Comfortable · applicationWallet recipe
Secure session● sealed
PPrimary accountnet1vzg6…9nq4ready
Review boundaryVerify destination, amount, and network.
<html data-theme="light" data-density="comfortable"> <!-- website -->
<html data-theme="dark" data-density="comfortable">   <!-- wallet application -->

Complete source palette

Repository source only

The repository supplies paired values, not mathematically generated scales. The primitive layer therefore keeps named pairs rather than inventing numbered ramps.

Gate neutrals

Gate canvas
Gate glow
Gate surface
Gate inset
Gate border
Gate ink
Gate muted

Parchment neutrals

Parchment canvas
Parchment glow
Parchment surface
Parchment inset
Parchment border
Parchment ink
Parchment muted

Brand and status pairs

Brand · gate
Brand · parchment
Success · gate
Success · parchment
Warning · gate
Warning · parchment
Danger · gate
Danger · parchment
Info · gate
Info · parchment

Ledger and avatar identity

Ledger colors are semantic identities, not product status. The five avatar colors come from the local DiceBear generator and never leave the device.

Parchment ledgersLight ink corrected
Primary network#2e7d46
Bitcoin#a3641a
Cardano#2f5f9e
XRPL#17756c
Stellar#6a4fa3
Gate ledgersExtracted
Primary network#9fd4a9
Bitcoin#e8a13d
Cardano#7da9e8
XRPL#6fd0c8
Stellar#b49ae8
Avatar sky#0ea5e9
Avatar violet#8b5cf6
Avatar pink#ec4899
Avatar orange#f97316
Avatar green#22c55e

Semantic mappings

Completed roles labeled
Purpose tokenLight / parchmentDark / gateOrigin
#f7f5ee#101713--bg
#fffdf6#18211b--panel
#fffdf6#1e2921Normalized panel role
#f4f0e3#1e2921--panel-2
#1d2420#f5f1e6--ink
#465048#c4ccc6Derived missing tier
#6b7268#9aa89e--muted
#eeeade#222d27Derived missing tier
#e2ddcc#2a3730--line
#aaa38f#526158Derived missing tier
#8a6d1f#d7bd76--gold
#fdf9ec#171307--gold-ink
#8a6d1f#d7bd76--focus
#1e7a3e#8fd4a0--ok
#8a6410#e5c06b--warn
#b3261e#ff9b90--danger
#2b5f8a#8fb8d8--info
rgba(0, 0, 0, .45).sheet-veil
#f4f0e3#101713Preview / technical surfaces
Light · parchmentAA core pairs

Primary surface

Warm, never stark white

Muted copy remains 4.88:1 on this panel.

Review carefullyConfirm the network and destination.
Dark · wizard gateCanonical

Primary surface

Quiet depth, low glare

Muted copy remains 6.66:1 on this panel.

Review carefullyConfirm the network and destination.

Contrast audit

PairLightDarkDecision
Primary text / canvas14.52:116.12:1Preserved
Muted text / surface4.88:16.66:1Preserved; light has narrow AA margin
Brand text / surface4.81:18.98:1+Preserved
Primary button ink / brand4.65:110.09:1Preserved; light has narrow AA margin
Light ledger glyph source ink2.87–3.88:1Use --color-ledger-glyph-ink (#fdf9ec), yielding 4.54–6.13:1
Dark danger toast source white ink2.58:1Use #171307 through --toast-danger-ink

Typography

System-only stacks

Serif · Georgia 500

Your path is set.

Identity, balances, and page-level headings.

Sans · Inter → system UI

Review transfer

Gandalf uses the operating system’s sans when Inter is unavailable; no web font is loaded.

Mono · system monospace

addr_test1vzg6…9nq4

Addresses, hashes, network IDs, and diagnostic output.

TokenValueProduction use
--text-2xs10pxI/O tags, compact word indexes
--text-xs11pxEyebrows, chips, mono metadata
--text-sm12pxFine print, notices, small actions
--text-md13.5pxRows, fields, form labels
--text-base14pxHeader and primary button text
--text-lg15.5pxSetup method serif title
--text-xl19pxTransfer result title
--text-2xl22pxSetup success title
--text-3xl28pxBalance amount and large sigil
--text-4xl34pxTransfer result mark
Line height1.15 / 1.45 / 1.55 / 1.7Display / notices / body / addresses
Letter spacing.02 / .06 / .08 / .14emMono / units / tags / eyebrows

Spacing, sizing, radii, borders, elevation, layout, motion, icons

Spacing

2–24px
2468101214161824

Radii

2–16px + round
2810121416pill

Elevation

Web extension
Level 1 · dropdown
Level 2 · dialog

Production surfaces are border-led; only focus, sigil insets, and step halos are extracted shadows.

Icon sizes

12 / 16 / 20 / 24
12 16 20 24
FoundationDecisionProvenance
Borders1px default; 2px emphasis or security edgeExtracted
Focus2px gold box-shadow ring; never remove without replacementExtracted
Disabled50% opacity; 55% for reserved/struck dataExtracted
Popup container380 × 600px; minimum document width 320pxExtracted
Reference container80rem max; 68ch reading measureRecommended
Breakpoints640px mobile; 960px tablet; 1200px wideRecommended; production has none
Motion120 / 180 / 260ms, standard easeRecommended; production defines no transitions
Toast duration2600msExtracted from main.tsx
Reduced motionSuppress animation and transitionExtracted and preserved
Touch target44px portable minimum; source is 30 / 38 / 40pxAccessibility correction

02 · Core components

Quiet controls, explicit consequences.

Every specimen consumes component or semantic tokens. Static modifier classes expose states that normally appear through interaction, and unsupported production patterns are visibly labeled.

Links and buttons

Links

Extracted

Read implementation guidance

Gold text links are reserved for actionable navigation such as “Sync now” and back controls.

Variants

Source + normalized

Sizes

44px minimum

Source visual heights remain documented, while hit targets here meet 44 × 44px.

States

All relevant states

Fields and selection controls

Text, password, search

Extracted

Text area and select

Extracted

Validation

Source messages

Checkbox, radio, switch

Switch is extension
Seed phrase length

Cards, lists, tables, empty and loading states

Cards and lists

Extracted

Vault summary

Vaults
2
Accounts
4
Last sync
14:32:08

Table

Responsive extension
AssetStateBalance
UNITsynced3.4200
ASSETpending0.0150

Empty state

Extracted
No activity recorded yet.

Skeleton

Loading extension

The production loading state says “Opening the gate…” without a skeleton.

Alerts, overlays, and destructive confirmation

Alerts and banners

Extracted
Read-only gatewaySending is unavailable until this network exposes chain API v1.
Vault encryptedYour public address is ready.
Balances may be staleSynchronize before sending.
Network mismatchThis account cannot be used on the selected network.

Toasts

Danger ink corrected
Address copiedNode access was not granted

Production removes toasts after 2600ms. Status must also remain available in context for critical outcomes.

Dropdown

Uses source menu language

Dialog

From bottom-sheet tokens
Delete custom network?

Built-in networks can be reset; only custom networks can be deleted.

03 · Website templates

Start with a real page, not a blank canvas.

These dependency-free templates use only classes and tokens from this CSS file. Download either HTML file, place it beside gandalf-design-system.css, and open it directly in a browser.

Vanilla HTML/CSS kit

No npm, framework, bundler, web font, CDN, or JavaScript dependency. The reference and both starter templates remain fully responsive.

Template 01 · Professional portfolio

Generic portfolio recipe

An evidence-led information architecture with a compact identity header, clear positioning, two primary actions, a proof band, and inspectable case-study cards—composed entirely with Gandalf tokens.

portfolio.example

Senior Software Engineer · Technical Lead

I build security-critical platforms people can trust.

Hands-on architecture and implementation for distributed systems where correctness, security, and operational reliability matter.

10+ yearsRelevant experience
ProductionSystems delivered
0 → 1Products shipped
FlexibleRemote and hybrid

Selected work

Delivery where failure has consequences.

Production

Platform modernization

A clear problem, the decisions made, and the resulting operational outcome.

Case study

Distributed service

System boundaries, measurable guarantees, and lessons from delivery.

Research

Applied research

A practical experiment with explicit constraints and human oversight.

<!doctype html>
<html lang="en" data-theme="light">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Your Name · Portfolio</title>
  <link rel="stylesheet" href="gandalf-design-system.css">
</head>
<body>
  <div class="template-page template-page--standalone">
    <header class="template-site-header">
      <nav class="template-site-nav" aria-label="Primary">
        <a class="template-site-brand" href="#top">
          <span class="sigil" aria-hidden="true">YN</span>
          <span>Your Name</span>
        </a>
        <ul class="template-nav-links">
          <li><a href="#work">Work</a></li>
          <li><a href="#about">About</a></li>
          <li><a href="#contact">Contact</a></li>
        </ul>
      </nav>
    </header>
    <main id="top">
      <section class="template-hero">
        <div>
          <p class="eyebrow">Your role · Your location</p>
          <h3>A clear statement of the value you <em>deliver.</em></h3>
          <p class="template-lead">A concise, evidence-led introduction.</p>
          <div class="hero__actions">
            <a class="button button--primary" href="#work">View work</a>
            <a class="button" href="#contact">Contact</a>
          </div>
        </div>
        <aside class="template-profile-card">
          <div class="template-profile-mark" aria-hidden="true">YN</div>
          <strong>Your Name</strong>
          <p>One sentence of professional context.</p>
        </aside>
      </section>
      <section class="template-content-section" id="work">
        <p class="eyebrow">Selected work</p>
        <h3>Evidence, not adjectives.</h3>
        <div class="template-card-grid">
          <article class="template-card"><h3>Case study</h3><p>Problem, decision, and measurable outcome.</p></article>
          <article class="template-card"><h3>Case study</h3><p>Problem, decision, and measurable outcome.</p></article>
        </div>
      </section>
    </main>
  </div>
</body>
</html>

Template 02 · Product landing page

Generic extension

A compact technical-product layout for infrastructure, developer tooling, security products, or any service that benefits from evidence-first communication.

northstar.example
All systems operational

Infrastructure · Clearly bounded

Infrastructure you can explain.

Make consequential systems legible with stable contracts, inspectable state, and explicit failure modes.

Live system boundary

APIRequests validated32ms
PolicyRules enforcedv3.2
QueueAwaiting confirmation2 jobs
Inspectable by defaultEvery transition retains its reason and evidence.

Platform

Small surface. Strong guarantees.

Stable contracts

Version boundaries before implementations.

Visible state

Never hide pending, partial, or rejected outcomes.

Safe defaults

Make the secure path the shortest path.

<!doctype html>
<html lang="en" data-theme="dark">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Northstar · Product</title>
  <link rel="stylesheet" href="gandalf-design-system.css">
</head>
<body>
  <div class="template-page template-page--standalone">
    <header class="template-site-header">
      <nav class="template-site-nav" aria-label="Primary">
        <a class="template-site-brand" href="#top"><span class="sigil" aria-hidden="true">N</span><span>Northstar</span></a>
        <ul class="template-nav-links"><li><a href="#platform">Platform</a></li><li><a href="#security">Security</a></li><li><a href="#docs">Docs</a></li></ul>
      </nav>
    </header>
    <main id="top">
      <section class="template-hero">
        <div>
          <span class="status status--success">All systems operational</span>
          <p class="eyebrow template-kicker">Infrastructure · Clearly bounded</p>
          <h3>Infrastructure you can <em>explain.</em></h3>
          <p class="template-lead">One precise sentence about your product and its guarantees.</p>
          <div class="hero__actions"><a class="button button--primary" href="#docs">Read the docs</a><a class="button" href="#platform">View platform</a></div>
        </div>
        <div class="template-product-visual">
          <p class="eyebrow">Live system boundary</p>
          <div class="template-system-row"><span class="status status--success">API</span><span>Requests validated</span><small>32ms</small></div>
          <div class="template-system-row"><span class="status status--warning">Queue</span><span>Awaiting confirmation</span><small>2 jobs</small></div>
        </div>
      </section>
      <section class="template-content-section" id="platform">
        <p class="eyebrow">Platform</p><h3>Small surface. Strong guarantees.</h3>
        <div class="template-card-grid"><article class="template-card"><h3>Stable contracts</h3><p>Version boundaries before implementations.</p></article><article class="template-card"><h3>Visible state</h3><p>Never hide incomplete outcomes.</p></article></div>
      </section>
    </main>
  </div>
</body>
</html>

04 · Product recipe

Applied to high-trust finance.

Gandalf is generic; this recipe shows its source product application. The patterns are limited to journeys implemented in the repository: account selection, synchronization, receive, UTXO visibility, compose/review/sign/result, status tracking, setup/import, password unsealing, and encrypted backup.

Account surfaces

Parchment accountLight source values
Gandalf● sealed

Primary network · Development

3.4200000000 UNIT

net1v…9nq4synced 14:32
Gate accountCanonical source
Gandalf● sealed

Bitcoin · Devnet

0.01500000 BTC

tb1p9s…x2czsynced 14:32

Asset and balance rows

Account rows

Address and copy

Extracted
net1vzg6dy37v04myw48k9v2c5e9yx9nq4
Single static address — reuse is visible on-chain. Valid only for network id 3.

Network selector

Extracted
connectedstalewrong networkread-only

Receive panel

Pattern, simplified QR
Primary networkDevelopment
net1v zg6dy 37v04 myw48 k9v2c 5e9yx 9nq4

Transaction history, compose, review, and result

History rows

Extracted

Send / compose

Extracted
Fee: 2 sats/vB × transaction size. The node validates before broadcast.

Review and fee

Extracted

Review carefully

Inputa78f2c1e90b4… : 10.0150
Paymenttb1p9s…x2cz0.0010
Changetb1qx7…d92j0.0139
Fee2 sats/vB × 141 vB0.00000282
Network
Bitcoin Devnet
Inputs
1
Estimated vsize
141 vB

Signing confirmation

Extracted
ComposeReviewResult

0.00100000 BTC → tb1p9s…x2cz

Signing → validating → broadcasting. Never imply confirmation before the network confirms.

Password, secret material, and security messaging

Unlock / unseal

Extracted
Secrets sealed

Password required only at the signing or vault boundary.

Seed phrase warning

Extracted
Write these words down in order.
Anyone with them controls every associated account.
  1. 1amber
  2. 2gate
  3. 3silent
  4. 4tower
  5. 5hidden
  6. 6meadow
  7. 7iron
  8. 8beacon

Encrypted backup

Extracted
Primary account

2 accounts · vault 9d7ac103

The file never contains plaintext keys; keep it and the export password apart.

Reusable transaction-state matrix

Error

Give the cause, retain user input when safe, and offer recovery.

Offline

Name the unreachable service; do not imply that no account activity exists.

Wrong network

State both expected and selected networks before any action.

Pending

Show a text label, submission hash, node acceptance, and next sync.

Confirmed

Show the block reference when available; color is supplementary.

Rejected

Quote the node reason, release inputs, and provide edit-and-retry.

Security boundary rule. Secrets shall not pass into logs, remote assets, analytics, clipboard persistence, or decorative UI. Gandalf’s source keeps signing in WASM, displays “sealed” in the header, generates avatars locally, and exports only re-encrypted vault material.

05 · Implementation guidance

Portable by purpose, not by page.

Import the CSS, set one theme attribute at the application root, and consume semantic or component tokens. Primitive values are for theme definitions and auditing—not routine component authoring.

1 · Download two files

my-site/
├── index.html
└── gandalf-design-system.css

The reference HTML is documentation. For a new site, download one of the starter templates above as index.html.

2 · Link it from vanilla HTML

<!doctype html>
<html lang="en" data-theme="light">
<head>
  <meta charset="utf-8">
  <meta name="viewport"
        content="width=device-width, initial-scale=1">
  <link rel="stylesheet"
        href="gandalf-design-system.css">
</head>
<body>
  <button class="button button--primary">
    Continue
  </button>
</body>
</html>

Minimal HTML

<link rel="stylesheet" href="gandalf-design-system.css">

<article class="card">
  <p class="eyebrow">Primary network · Development</p>
  <button class="button button--primary">
    Review transfer
  </button>
</article>

Consume tokens, not colors

.account-summary {
  color: var(--color-text-primary);
  background: var(--card-bg);
  border: var(--border-thin)
          solid var(--card-border);
  border-radius: var(--radius-card);
}

.account-summary__action {
  color: var(--button-primary-ink);
  background: var(--button-primary-bg);
}

Apply a theme

<html>...</html> <!-- light root -->
<html data-theme="dark">...</html>

// System preference
const dark = matchMedia(
  '(prefers-color-scheme: dark)'
).matches
document.documentElement.dataset.theme =
  dark ? 'dark' : 'light'

Integration sequence

  1. Copy the CSS into the consuming application or package it unchanged.
  2. Alias product primitives into a shared namespace only at the theme boundary.
  3. Build shared components against semantic and component tokens.
  4. Keep ledger identity tokens separate from status tokens.
  5. Run contrast and keyboard tests after any downstream token remapping.

Cloudflare Pages deployment

Static deployment recipe

This direct-upload approach needs no build output or large media pipeline. Keep both named files available for downloads and publish a copy of the reference as index.html.

deploy_dir="$(mktemp -d)"
cp index.html "$deploy_dir/index.html"
cp gandalf-design-system.css "$deploy_dir/gandalf-design-system.css"

npx --yes wrangler pages deploy "$deploy_dir" \
  --project-name=gandalf-system \
  --branch=main \
  --commit-dirty=true

First deploy

Pages project

Wrangler creates or updates the static project and provides a public pages.dev address.

After domain purchase

Attach gandalfsystem.com

Add the apex domain and optional www domain under Cloudflare Pages → Custom domains.

Public CSS

Use anywhere

Once deployed, applications can link to https://YOUR-DOMAIN/gandalf-design-system.css.

Ready, not deployed. The Pages project is named gandalf-system; attach gandalfsystem.com after registration and the first deployment.

Original → normalized mapping

Original sourceNormalized tokenDecision
--bg--color-canvasDirect semantic rename
--bg-glow--color-canvas-glow + page gradientSplit color from gradient composition
--panel--color-surface / --card-bgDirect semantic and component aliases
--panel-2--color-surface-inset / --field-bgDirect semantic and component aliases
--line--color-border-defaultDirect; subtle/strong tiers derived
--ink--color-text-primaryDirect; secondary tier derived
--muted--color-text-mutedDirect
--gold--color-action-primary / --color-focusRole-specific aliases
--gold-ink--color-action-primary-inkDirect
--ok--color-successPurpose rename
--warn--color-warningPurpose rename
--danger--color-dangerDirect
--info--color-informationPurpose rename
Primary identity accent--color-ledger-primaryNeutral reusable identity role
--lg-bitcoin--color-ledger-bitcoinExpanded abbreviation
--lg-cardano--color-ledger-cardanoExpanded abbreviation
--lg-xrpl--color-ledger-xrplExpanded abbreviation
--lg-stellar--color-ledger-stellarExpanded abbreviation
--focus: 0 0 0 2px--shadow-focusPreserved geometry; semantic focus color
#fff / #111 in QR--color-qr-bg / --color-qr-inkTechnical fixed pair
rgba(0,0,0,.45)--color-overlay / --color-scrimDirect from sheet veil
Error toast #fff on dark danger--toast-danger-inkTheme-aware AA correction
30 / 38 / 40px controls--source-* plus --control-targetPreserved audit values; portable target corrected to 44px

Merge with another system without coupling

Share contracts

Agree on semantic contracts such as canvas, surface, text, border, action, status, focus, and control geometry. Let each product map its own primitives into those contracts.

Avoid selector inheritance

Do not exchange page-specific classes between products. Shared packages should expose tokens and low-level components, never selectors named after one route, screen, or application.

/* Shared contract */
--shared-color-surface: var(--color-surface);
--shared-color-action-primary: var(--color-action-primary);
--shared-control-radius: var(--radius-control);

/* Gandalf keeps product identity */
--shared-network-primary: var(--color-ledger-primary);
--shared-security-boundary: var(--security-border);

Audit trail and scope

UI sources inspected

  • extension/src/styles.css
  • extension/src/shared/theme.ts
  • extension/src/popup/main.tsx
  • extension/src/popup/ui.tsx
  • extension/src/popup/screens.tsx
  • extension/src/popup/SendFlow.tsx
  • extension/src/popup/screens/SetupFlow.tsx
  • extension/src/popup/screens/SettingsScreens.tsx
  • extension/src/popup/identicon.ts
  • extension/src/popup/viewStack.ts
  • extension/popup.html
  • extension/public/manifest.json
  • extension/package.json and Vite config
  • README.md and ROADMAP.md
  • Playwright popup journeys

Evidence classification

Extracted Colors, type, spacing, radii, borders, popup shell, fields, buttons, cards, rows, status, setup, receive, send, signing, and security language.

Derived Secondary text, subtle/strong borders, semantic selection, and explicit elevation levels needed for a complete portable layer.

A11y fix 44px targets, light ledger glyph ink, and dark danger-toast ink.

Recommended Tabs, breadcrumbs, pagination, switch, tooltip, skeleton, table, dropdown, dialog, desktop sidebar, and mobile nav.

Known ambiguity. The repository references design-018, but that document and product screenshots are not present in this repository. The implementation itself is therefore the governing evidence. Cardano, XRPL, and Stellar have catalog colors but no live adapter screens yet.

Final review

Sign this transaction?

Confirm the destination, amount, fee, and network. Signing cannot be undone after broadcast.

Amount
0.00100000 BTC
Fee
0.00000282 BTC
Network
Bitcoin Devnet