nimiq-branding-cli 1.0.1 → 1.1.0

package/PRINCIPLES.md

@@ -0,0 +1,153 @@
+# The Nimiq Design Principles
+
+**This is the soul of this tool.** Every component in the registry — and every NEW thing
+generated with it — must come from these principles, not just resemble their output.
+
+Sources: the **NIMIQ Style Guide (October 2018)**, the
+[A New Visual Identity](https://www.nimiq.com/blog/a-new-visual-identity/) blog post,
+[nimiq-style](https://nimiq.github.io/nimiq-style/), and the
+[Nimiq Design Kit](https://nimiq.dev/design-kit).
+
+---
+
+## Why — the identity
+
+> *Nimiq is an Inuit word for an object or force that binds things together.*
+
+Nimiq sees itself as **the lowest common denominator at the intersection of payment
+technology and accessible interaction with a blockchain** — and aims for **radical
+simplicity in both technology and design**.
+
+The brand persona, derived from team and community (not theory):
+
+**Helping & caring · Trustworthy & transparent · Conscientious & driven**
+
+…which translates into four visual pillars:
+
+1. **A base that follows common patterns.**
+2. **Traditional and basic colors with a subtle spin.**
+3. **Warm and round, but straight visual and form language.**
+4. **Subtle complexity and calculated breaks in a clear structure.**
+
+---
+
+## The prime directive — radical simplicity
+
+> *"Stripping away everything that's not necessary will lead to less cognitive load and
+> eventually to a better experience."*
+
+The logo is the proof: every clever N-in-a-hexagon draft was discarded for the **bare
+hexagon** — because two shapes, one inside the other, was already too complex. What
+remained is *"a clean slate, ready for the community to fill."*
+
+And the ecosystem framing that defines this CLI's job:
+
+> *"We don't want to dictate the way the Nimiq ecosystem looks or feels, but rather
+> provide a boilerplate of our vision, stripped down to the very core, so that there's
+> enough room for others to fill it out with their own ideas."*
+
+This tool **is** that boilerplate, made executable.
+
+---
+
+## The laws
+
+### 1. Color — three rules, in order
+1. **Traditional, basic colors with a subtle, unexpected spin.** The ultramarine
+   dark-blue (`#1F2348`) carries a touch of violet spreading from the corner; the
+   classic red tilts slightly toward magenta. Colors relate to *payments*, not to
+   crypto fashion.
+2. **Build on a light stage.** Start from a clean slate (white / `#F8F8F8`); create
+   structure with very light, nuanced grays derived from the main colors — this
+   underlines the transparent, open, collaborative approach and leaves room for
+   others' ideas.
+3. **Color is for accentuated highlights only** — to set focus, and as a *reaction to
+   interaction*. Never decorative. (Green = success only. Red = error only.
+   Orange = warning. Blue = action/info.)
+
+### 2. The gradient is the spin
+A **subtle radial gradient is THE key feature** of the visual identity. Apply it to
+every element that qualifies as a color area — buttons, boxes, backgrounds — anchored
+in the **bottom-right corner** (e.g. `radial-gradient(100% 100% at bottom right,
+#260133, #1F2348)`). This is how "traditional colors" get their spin. On logo
+substrates: white base with a faint color-aligned tint sweeping from the top-right edge.
+
+### 3. Form — warm and round, but straight and tangible
+Interfaces are **warm and round, but straight and tangible at the same time** (pill
+buttons and 8px-radius cards, yet crisp edges and exact alignment). **Every element
+has a clear anchor and a relation to the whole.** Pare down the number of visual
+elements until **everything remaining is necessary for the layout to function**.
+
+### 4. White space does the structural work
+Achieve hierarchy, separation and cohesion with **white space instead of structural
+elements** like separators or boxes. *"We avoid all forms of decorative elements if we
+can't defend them on a content level."* When in doubt: more breathing room, fewer lines.
+
+### 5. Typography — simple, unique, open
+**Muli/Mulish**: a classic sans-serif molded by radical geometric simplicity, with
+unique details that never compromise that simplicity — chosen over Roboto/Open Sans
+because Nimiq could *own* it, and because it's open source (community must be able to
+reproduce everything). **Fira Mono** for technical content — addresses, keys, numbers —
+optimized for readability, light-footed in non-code environments.
+
+### 6. Calculated breaks — the element of surprise
+Radical simplicity is not sterility:
+
+> *"For this reason we embrace subtle complexity — an element of surprise,
+> well-defined breaks in a clear structure — something that makes the experience
+> memorable."*
+
+One surprise per experience: the gradient's diagonal, an identicon's character, the
+honeycomb peeking through. **"Driven" translates into adding that bit of sophistication
+and friction that makes the difference between convenience and fascination.** Friction
+belongs only where it protects something critical (a passphrase, money).
+
+### 7. Familiar in the basics, honest in the details
+> *"We use common, learned patterns for critical interactions with Nimiq wherever
+> possible. We're familiar in the basics, but surprising in the details. Nevertheless,
+> if in doubt, everything we do follows intuitive patterns. If we don't follow best
+> practices, we follow logic, nature or human behavior."*
+
+### 8. Reproducibility is a brand value
+> *"We want to encourage the community to use our visual language as a foundation for
+> their own projects. … everything we create visually needs to be easily accessible and
+> reproducible, being able to act as a boilerplate by virtue of its simplicity."*
+
+This is why this CLI pixel-verifies every component against the real upstream and ships
+the team's real assets instead of hand-made approximations. Reproduction *is* the brand
+working as designed.
+
+### 9. The logo is sacred ground
+The hexagon signet is **universal** — anyone in the ecosystem may use it and build their
+own mark on top of it. The **signet + wordmark combination is reserved** and must not be
+altered. Clear space: the width of the letter N (horizontal) / half a hexagon (signet).
+Monochrome versions for busy or colored backgrounds. Never reconstruct the geometry —
+use the shipped files (`nq assets search logo`).
+
+---
+
+## The generation checklist
+
+Before any NEW component or design ships, it must answer **yes** to all of these:
+
+- [ ] Could anything be removed without the layout failing? (If yes → remove it.)
+- [ ] Does it sit on a light stage, structured by white space rather than boxes/lines?
+- [ ] Is every color either a main color with the radial-gradient spin, a light nuanced
+      gray derived from main colors, or a semantic highlight reacting to focus/interaction?
+- [ ] Are color areas gradient-built (bottom-right radial), not flat fills?
+- [ ] Is it warm and round (pills, soft radii) yet straight and tangible (crisp anchors,
+      exact alignment, clear relation to the whole)?
+- [ ] Is the typography Muli/Mulish (UI) and Fira Mono (technical values) only?
+- [ ] Is there at most ONE calculated break / element of surprise, and can it be
+      defended on a content level?
+- [ ] Are the basics a common, learned pattern? (Surprise lives in details, never in
+      critical interactions.)
+- [ ] Does it use the team's real assets (`nq assets`) — never redrawn logos, icons or art?
+- [ ] Is it reproducible — plain HTML/CSS or standard Vue, no exotic dependencies,
+      verifiable by `nq verify`?
+
+---
+
+*Run `nq principles` to print this document. `nq new <name>` scaffolds a component with
+this checklist embedded — a component is not done until the checklist and the pixel
+verification both pass.*

package/README.md

@@ -8,6 +8,16 @@ Nimiq apps before it ships, plus the team's real asset library (logos, icons, fl
 > real shipped files or faithful ports of their open-source components, never hand-drawn
 > approximations.
 
+## The soul of the tool
+
+Everything here flows from the **[Nimiq Design Principles](PRINCIPLES.md)** — distilled from
+the NIMIQ Style Guide (October 2018) and the
+[A New Visual Identity](https://www.nimiq.com/blog/a-new-visual-identity/) essay: radical
+simplicity, a light stage structured by white space, traditional colors with the radial-gradient
+spin, warm-and-round-yet-tangible form, and one calculated break per experience. `nq principles`
+prints them; `nq new <name>` scaffolds a component with the 10-point principles checklist
+embedded — a component isn't done until the checklist and the pixel verification both pass.
+
 ## Install
 
 ```bash

package/bin/nq.js

@@ -24,6 +24,9 @@ Usage:
   nq assets search <term>       Search assets incl. the 323 nimiq-icons + 422 hexagon flags
   nq assets add <name...>       Copy official asset(s) into ./nimiq/assets/
                                 (icon:<name> extracts from nimiq-icons, flag:<cc> from nimiq-flags)
+  nq principles                 Print the Nimiq design principles — the soul of this tool
+  nq new <name>                 Scaffold a new registry component with the principles
+                                checklist + verification contract embedded
   nq verify <component|all>     Render the html variant and diff against the reference PNG
   nq help                       This message
 
@@ -239,6 +242,88 @@ async function cmdTokens() {
   console.log(await readFile(join(ROOT, 'assets', 'tokens.md'), 'utf8'));
 }
 
+async function cmdPrinciples() {
+  console.log(await readFile(join(ROOT, 'PRINCIPLES.md'), 'utf8'));
+}
+
+const CHECKLIST = [
+  'remove-everything-unnecessary: could anything be removed without the layout failing?',
+  'light-stage: white/#F8F8F8 base, structure via white space + nuanced grays, not boxes/lines',
+  'color-rules: main colors w/ gradient spin | light grays | semantic highlights on interaction only',
+  'gradients: color areas use the bottom-right radial gradient, never flat fills',
+  'form: warm and round yet straight and tangible; every element anchored, related to the whole',
+  'type: Mulish for UI, Fira Mono for technical values, nothing else',
+  'one-break: at most ONE calculated surprise, defensible on a content level',
+  'learned-patterns: basics follow common patterns; surprise lives in details only',
+  'real-assets: team-shipped files via nq assets — no redrawn logos/icons/art',
+  'reproducible: plain HTML/CSS or standard Vue, passes nq verify',
+];
+
+async function cmdNew(name, flags) {
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('nq new <kebab-case-name>');
+  const dir = join(ROOT, 'registry', 'components', name);
+  if (existsSync(dir)) throw new Error(`component "${name}" already exists`);
+  const pascal = name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join('');
+  await mkdir(join(dir, 'html'), { recursive: true });
+  await mkdir(join(dir, 'truth'), { recursive: true });
+  await mkdir(join(dir, 'vue'), { recursive: true });
+
+  const meta = {
+    name,
+    purpose: 'TODO: one sentence — what it is and where Nimiq uses it',
+    category: 'misc',
+    variants: ['vue', 'html'],
+    props: [],
+    cssFiles: ['css/legacy/nimiq-style.min.css'],
+    assetFiles: [],
+    dependsOn: [],
+    npmDeps: [],
+    verified: false,
+    verify: { viewport: { width: 600, height: 400 }, selector: `.${name}`, maxDiffPct: 0.5, settleMs: 250 },
+    principles: Object.fromEntries(CHECKLIST.map(c => [c.split(':')[0], false])),
+    notes: 'Scaffolded by nq new. Cite the source (upstream file, real asset, or screenshot reference) here. A component is DONE when every principles flag is true AND nq verify passes.',
+  };
+  await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n');
+
+  const pageChrome = (title, cssHref) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${title}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Mulish:wght@400;600;700;800&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="../../../../assets/css/legacy/nimiq-style.min.css">
+<link rel="stylesheet" href="${cssHref}">
+<style>
+    html, body { margin: 0; padding: 0; background: #fff; }
+    body { font-family: 'Mulish', 'Muli', system-ui, sans-serif; }
+</style>
+</head>
+<body>
+<div class="${name}">
+    <!-- TODO: same markup as html/${name}.html — keep truth/demo/snippet identical -->
+</div>
+</body>
+</html>
+`;
+  await writeFile(join(dir, 'truth', 'truth.html'), pageChrome(`${name} — truth (cite your source!)`, `../html/${name}.css`));
+  await writeFile(join(dir, 'html', 'demo.html'), pageChrome(name, `${name}.css`));
+  await writeFile(join(dir, 'html', `${name}.html`), `<!-- ${name} — TODO describe. Requires ${name}.css + nimiq-style.min.css.\n     Source: TODO (upstream file / real asset / reference screenshot). -->\n<div class="${name}">\n    <!-- TODO -->\n</div>\n`);
+  await writeFile(join(dir, 'html', `${name}.css`), `/* ${name} — all selectors namespaced under .${name}.\n   Principles: light stage, white-space structure, bottom-right radial gradients,\n   Mulish/Fira Mono, one calculated break max. Run: nq principles */\n.${name} {\n    font-family: 'Mulish', sans-serif;\n}\n`);
+  await writeFile(join(dir, 'vue', `${pascal}.vue`), `<script setup lang="ts">\n// ${pascal} — port faithfully; inline small helpers; record npm deps in meta.json\n</script>\n\n<template>\n    <div class="${name}">\n        <!-- TODO -->\n    </div>\n</template>\n\n<style scoped>\n.${name} {\n    font-family: 'Mulish', sans-serif;\n}\n</style>\n`);
+
+  console.log(`+ registry/components/${name}/ scaffolded\n`);
+  console.log('The principles gate (all must become true in meta.json):');
+  for (const c of CHECKLIST) console.log('  [ ] ' + c);
+  console.log(`\nWorkflow:
+  1. Build truth/truth.html from a REAL source (upstream code, real asset, or live screenshot) — cite it in meta.notes.
+  2. node scripts/snap.mjs ${name}     (truth -> reference.png; eyeball it)
+  3. Build html/${name}.html + demo.html + vue/${pascal}.vue with identical markup.
+  4. node scripts/verify.mjs ${name}   (must pass at <= 0.5% diff)
+  5. Flip the principles flags + verified:true, then: node scripts/build-index.mjs
+Read the soul of the tool first: nq principles`);
+}
+
 async function cmdVerify(target) {
   const { verify } = await import(join(ROOT, 'scripts', 'verify.mjs'));
   const names = target === 'all' || !target
@@ -264,6 +349,8 @@ try {
     case 'add': await cmdAdd(rest, flags); break;
     case 'init': await cmdInit(flags); break;
     case 'tokens': await cmdTokens(); break;
+    case 'principles': await cmdPrinciples(); break;
+    case 'new': await cmdNew(rest[0], flags); break;
     case 'assets': await cmdAssets(rest[0], rest.slice(1), flags); break;
     case 'verify': await cmdVerify(rest[0]); break;
     default: console.log(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimiq-branding-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "nq \u2014 pixel-verified Nimiq UI component registry + CLI. 39 components (Vue 3 + plain HTML) diffed against the real Nimiq apps, plus the team's real asset library. Unofficial community tool.",
   "type": "module",
   "bin": {