nimiq-branding-cli 1.0.0 → 1.1.0

package/FEATURES.md

@@ -0,0 +1,113 @@
+# Supporting Features Roadmap
+
+Interactive widgets/flows across Nimiq's apps and sites that this CLI can scaffold as
+ready-made features (beyond single components). Surveyed 2026-06-11 from live sites +
+upstream sources. Full data: `references/supporting-features.json`.
+
+## High priority
+
+### Hub onboarding / connect-wallet (signup, login, choose address)
+- **Where:** https://hub.nimiq.com popup via @nimiq/hub-api — source: upstream/hub/src/views/OnboardingSelector.vue, Signup.vue, Login.vue, ChooseAddress.vue, ConnectAccount.vue
+- **Screenshots:** need it
+- The universal 'Connect with Nimiq' flow every third-party app starts with: OnboardingMenu (create account / login / Ledger), IdenticonSelector avatar picker, ChooseAddress address selector. Composes hub components OnboardingMenu.vue, IdenticonSelector.vue, StatusScreen.vue plus @nimiq/vue-components (SmallPage, PageHeader/Body, AccountSelector). A CLI scaffold = drop-in 'connect wallet' button + callback handling.
+- **Built from:** `hub/src/views/OnboardingSelector.vue`, `hub/src/views/ChooseAddress.vue`, `hub/src/components/OnboardingMenu.vue`, `hub/src/components/IdenticonSelector.vue`, `@nimiq/hub-api`, `@nimiq/vue-components AccountSelector`
+
+### Checkout / payment flow (Hub checkout)
+- **Where:** https://hub.nimiq.com checkout via hub-api; docs at nimiq.github.io/hub — source: upstream/hub/src/views/Checkout.vue + CheckoutTransmission.vue
+- **Screenshots:** need it
+- Multi-currency payment sheet: currency cards (CheckoutCardNimiq/Bitcoin/Ethereum/External), CheckoutManualPaymentDetails (pay-by-address+QR fallback), PaymentInfoLine + Timer from @nimiq/vue-components, CurrencyInfo, StatusScreen success/error. This is THE merchant-facing feature (woocommerce-gateway-nimiq builds on it). CLI scaffold = 'accept NIM/BTC/ETH payment' page with callback verification.
+- **Built from:** `hub/src/views/Checkout.vue`, `hub/src/components/CheckoutCardNimiq.vue`, `hub/src/components/CheckoutCardBitcoin.vue`, `hub/src/components/CheckoutCardEthereum.vue`, `hub/src/components/CheckoutManualPaymentDetails.vue`, `@nimiq/vue-components PaymentInfoLine + Timer + QrCode`
+
+### Cashlink create / manage / claim
+- **Where:** Hub views + wallet entry points — upstream/hub/src/views/CashlinkCreate.vue, CashlinkManage.vue, CashlinkReceive.vue; wallet/src/components/CashlinkButton.vue; github.com/nimiq/cashlink-generator (bulk tool)
+- **Screenshots:** have it (cashlink tx-detail modal in nimiq-branding-skill/screenshots/nimiq-wallet-app/Screenshot 2026-03-13 at 9.42.56 PM.png; create/claim screens still needed)
+- Signature Nimiq feature: send NIM via shareable link, no recipient address needed. Create flow (amount + message + fee), manage (copy/share/cancel link), receive/claim flow with CashlinkSparkle celebration animation. Wallet send modal offers 'Create a Cashlink' when address unavailable; cashlink txs render specially in the tx list. High reuse for tipping, airdrops, promo apps.
+- **Built from:** `hub/src/views/CashlinkCreate.vue`, `hub/src/views/CashlinkManage.vue`, `hub/src/views/CashlinkReceive.vue`, `hub/src/lib/Cashlink.ts`, `hub/src/components/CashlinkSparkle.vue`, `wallet/src/components/CashlinkButton.vue`
+
+### Staking calculator
+- **Where:** https://www.nimiq.com/staking-calculator/ (nimiq.com website; not in local upstream clones)
+- **Screenshots:** have it (nimiq-branding-skill/screenshots/staking-calculator/nimiq.com-staking-calculator-desktop.png + -mobile.png)
+- Standalone marketing-grade widget: NIM amount + duration inputs -> projected rewards/APY output, branded slider UI. Self-contained (only needs supply/reward-curve math + current staked ratio from network), making it the easiest high-visual feature to scaffold for any community/validator site.
+- **Built from:** `nimiq.com website widget (no local source)`, `reward-curve math from core-rs-albatross economics`, `validators-api for live staked supply`
+
+### Staking flow + validator picker
+- **Where:** wallet.nimiq.com — upstream/wallet/src/components/staking/ (26 components)
+- **Screenshots:** have it partially (staked-balance card + 'NimiqHub Staking 10.1% p.a.' row in nimiq-wallet-app/Screenshot ...9.42.22 PM.png; validator list page still needed)
+- Full multi-page StakingModal wizard: StakingWelcomePage -> StakingValidatorPage (validator list with ValidatorListItem, ValidatorFilter, ValidatorScoreDetails star-ratings, ValidatorIcon/IconStack) -> StakingGraphPage (AmountSlider over balance + reward projection StakingGraph) -> StakingRewardsPage/Chart. Backed by github.com/nimiq/validators-api ('helping stakers choose where to stake'). The validator-picker subcomponent alone is valuable for pool/validator websites (e.g. stakenimiq.com).
+- **Built from:** `wallet/src/components/staking/StakingModal.vue`, `StakingValidatorPage.vue`, `ValidatorListItem.vue`, `ValidatorFilter.vue`, `ValidatorScoreDetails.vue`, `AmountSlider.vue`, `StakingGraph.vue`, `StakingRewardsChart.vue`, `nimiq/validators-api`
+
+### QR scan + pay (request links / receive)
+- **Where:** wallet.nimiq.com — upstream/wallet/src/components/modals/ScanQrModal.vue + ReceiveModal.vue; libs github.com/nimiq/qr-scanner (2.9k stars) + qr-creator
+- **Screenshots:** have it (receive modal w/ request-link in ...9.42.34 PM.png; send modal w/ QR-scan entry + cashlink CTA in ...9.42.44 PM.png)
+- Two halves: (1) ScanQrModal using @nimiq/vue-components QrScanner (camera scan, parses nimiq:/bitcoin:/polygon payment URIs and routes to the right send flow); (2) ReceiveModal showing identicon + chunked address + QR + 'Create request link' (amount-encoded payment URI). Both libs are standalone MIT packages, so this scaffolds cleanly into any PoS/payment app (NimiPay, Gateflo).
+- **Built from:** `wallet/src/components/modals/ScanQrModal.vue`, `wallet/src/components/modals/ReceiveModal.vue`, `@nimiq/vue-components QrScanner + QrCode`, `nimiq/qr-scanner`, `nimiq/qr-creator`, `payment URI parser in wallet/src/lib`
+
+### Transaction history with fiat conversion + CSV export
+- **Where:** wallet.nimiq.com — upstream/wallet/src/components/TransactionList.vue, TransactionListItem.vue, FiatConvertedAmount.vue, modals/HistoryExportModal.vue
+- **Screenshots:** have it (mobile tx list with fiat values in nimiq-wallet-app/Screenshot ...9.42.22 PM.png)
+- Virtual-scrolled, month-grouped tx list with identicon avatars, contact-label resolution, cashlink/swap badges, historic fiat value per tx (via @nimiq/utils FiatApi rates), search bar, and CSV export modal. Per-currency variants exist (BtcTransactionList, UsdcTransactionList, UsdtTransactionList) sharing the pattern. Any wallet-adjacent or accounting app wants this.
+- **Built from:** `wallet/src/components/TransactionList.vue`, `TransactionListItem.vue`, `FiatConvertedAmount.vue`, `SearchBar.vue`, `modals/TransactionModal.vue`, `modals/HistoryExportModal.vue`, `@nimiq/utils FiatApi`
+
+### Identicon generator / avatar picker
+- **Where:** github.com/nimiq/identicons (MIT) + @nimiq/vue-components Identicon.vue + hub IdenticonSelector.vue; reference doc already at nimiq-branding-skill/references/identicons.md
+- **Screenshots:** have it (identicons visible in all wallet screenshots; documented in nimiq-branding-skill/references/identicons.md)
+- Deterministic hexagon avatar from any Nimiq address — the most recognizable Nimiq brand element. Two scaffold targets: plain Identicon renderer (address -> SVG) and the hub's IdenticonSelector 'choose your avatar' onboarding carousel. Tiny dependency, used by literally every Nimiq app.
+- **Built from:** `nimiq/identicons`, `@nimiq/vue-components Identicon.vue + AccountRing.vue`, `hub/src/components/IdenticonSelector.vue`, `wallet IdenticonButton.vue + IdenticonStack.vue`
+
+## Medium priority
+
+### Swap UI (NIM <-> BTC <-> USDC/USDT via Fastspot)
+- **Where:** wallet.nimiq.com Trade > Swap — upstream/wallet/src/components/swap/ (SwapModal.vue, SwapBalanceBar.vue, SwapAnimation.vue, SwapFeesTooltip.vue, SwapNotification.vue)
+- **Screenshots:** need it (only disabled Swap button visible in ...9.41.06 PM.png)
+- Atomic-swap UI: dual AmountInputs with live quote, draggable SwapBalanceBar showing post-swap balance split, SwapFeesTooltip fee breakdown, full-screen SwapAnimation during HTLC execution, background SwapNotification. Visually excellent but tightly coupled to Fastspot API + @nimiq/fastspot-api + hub setupSwap — scaffold as UI shell with pluggable quote provider. Directly relevant to Hashmark-style apps.
+- **Built from:** `wallet/src/components/swap/SwapModal.vue`, `SwapBalanceBar.vue`, `SwapAnimation.vue`, `SwapFeesTooltip.vue`, `@nimiq/fastspot-api`, `hub setupSwap/RefundSwap views`
+
+### Buy/Sell fiat on-ramp (Moonpay, Simplex, Coinify, OASIS bank swap)
+- **Where:** wallet.nimiq.com Buy flow — upstream/wallet/src/components/modals/BuyOptionsModal.vue, BuyCryptoModal.vue, SellCryptoModal.vue, MoonpayModal.vue, SimplexModal.vue, CoinifyModal.vue, TradeModal.vue; OASIS marketing page nimiq.com/oasis
+- **Screenshots:** have it partially (OASIS marketing page nimiq-website/nimiq.com-oasis-desktop+mobile.png; the actual buy-options modal still needed)
+- Provider-chooser pattern: BuyOptionsModal geo-gates providers via useGeoIp + CountrySelector/CountryFlag, then opens provider webview modals (Moonpay/Simplex/Coinify) or the OASIS SEPA bank-swap TradeModal (SwapSepaFundingInstructions, BankCheckInput, KYC components). Scaffold value is the chooser shell + provider-modal pattern; the providers themselves need API keys/contracts, and OASIS availability has been limited — hence medium.
+- **Built from:** `wallet/src/components/modals/BuyOptionsModal.vue`, `MoonpayModal.vue`, `SimplexModal.vue`, `CoinifyModal.vue`, `TradeModal.vue`, `CountrySelector.vue`, `swap/SwapSepaFundingInstructions.vue`, `BankCheckInput.vue`, `kyc/`
+
+### Address book / contacts
+- **Where:** wallet.nimiq.com — upstream/wallet/src/components/ContactBook.vue, ContactShortcuts.vue, UsdcContactBook.vue + stores/Contacts.ts
+- **Screenshots:** have it partially (Contacts entry point in send modal screenshot ...9.42.44 PM.png; open contact book still needed)
+- Identicon-driven contact list: add/edit/delete with LabelInput, recent-recipient shortcuts row in the send flow, contact resolution in tx history. Small, self-contained (localStorage store), reusable in any send-money UI.
+- **Built from:** `wallet/src/components/ContactBook.vue`, `ContactShortcuts.vue`, `stores/Contacts.ts`, `@nimiq/vue-components Identicon + LabelInput`, `modals/AddressSelectorModal.vue`
+
+### Amount input with live fiat sync
+- **Where:** wallet/src/components/AmountInput.vue + AmountMenu.vue + FiatConvertedAmount.vue; @nimiq/vue-components AmountInput + AmountWithFee + FiatAmount
+- **Screenshots:** need it
+- Auto-scaling NIM amount input with currency-flip (enter in fiat or NIM), max-button, and live conversion line. Foundational sub-widget for send/swap/staking/checkout — worth scaffolding once as a shared primitive since the wallet version is richer than the base vue-components one.
+- **Built from:** `wallet/src/components/AmountInput.vue`, `AmountMenu.vue`, `FiatConvertedAmount.vue`, `@nimiq/vue-components AmountWithFee`, `@nimiq/utils CurrencyInfo + FiatApi`
+
+### Network consensus indicator + network map
+- **Where:** wallet.nimiq.com network view — upstream/wallet/src/components/ConsensusIcon.vue, NetworkStats.vue, NetworkMap.vue, NetworkMapPeerList.vue, modals/NetworkInfoModal.vue
+- **Screenshots:** need it
+- Two tiers: (a) ConsensusIcon — small animated connecting/syncing/established indicator every light-client app should show (pairs with @nimiq/core web client); (b) the full maplibre world NetworkMap with peer list + NetworkStats (uses nimiq-ui packages/nimiq-maplibre-styles). Scaffold (a) as high-value default, (b) as optional showpiece.
+- **Built from:** `wallet/src/components/ConsensusIcon.vue`, `NetworkStats.vue`, `NetworkMap.vue`, `NetworkMapPeerList.vue`, `nimiq-ui/packages/nimiq-maplibre-styles`, `stores/Network.ts`
+
+## Low priority
+
+### Price chart / portfolio balance distribution
+- **Where:** wallet.nimiq.com sidebar — upstream/wallet/src/components/PriceChart.vue, LineChart.vue, BalanceDistribution.vue, AccountBalance.vue
+- **Screenshots:** have it (left sidebar in nimiq-wallet-app/Screenshot ...9.41.06 PM.png and wallet.nimiq.com-desktop.png)
+- Sidebar sparkline price charts (NIM/BTC with 24h delta) and the BalanceDistribution bar splitting portfolio across currencies/addresses. Nice-to-have dashboard garnish; visible in held wallet screenshots.
+- **Built from:** `wallet/src/components/PriceChart.vue`, `LineChart.vue`, `BalanceDistribution.vue`, `AccountBalance.vue`, `stores/Fiat.ts`
+
+### Fee selector
+- **Where:** upstream/wallet/src/components/FeeSelector.vue (used in BTC send flow; SendModalFooter for NIM)
+- **Screenshots:** need it
+- Free/standard/express SelectBar with live fee-in-fiat preview. Marginal for NIM (fees ~0, mostly hidden) — really only matters for BTC sends, so low priority for a Nimiq-branding CLI.
+- **Built from:** `wallet/src/components/FeeSelector.vue`, `@nimiq/vue-components SelectBar`, `lib/BitcoinTransactionUtils.ts estimateFees`
+
+### Vote / governance UI
+- **Where:** https://nimiq.com/vote — github.com/nimiq/vote (Vue + TypeScript + Pug, MIT)
+- **Screenshots:** need it
+- Community-decision app: choice ranking/weighting UI where vote weight = NIM balance, signed via Hub signMessage/transaction. Niche (only used for occasional community-wide decisions) and the repo is stylistically older (Stylus/Pug), so low priority unless the CLI targets DAO-ish use cases.
+- **Built from:** `nimiq/vote repo (not cloned locally)`, `@nimiq/hub-api signTransaction/chooseAddress`
+
+### Browser-wallet onboarding extras (welcome tour, backup nag, testnet faucet)
+- **Where:** upstream/wallet/src/components/modals/WelcomeModal.vue, MigrationWelcomeModal.vue, BackupModal.vue (warning banner visible in screenshots), TestnetFaucet.vue, UpdateNotification.vue
+- **Screenshots:** have it partially (backup warning banner + multisig promo modal in ...9.40.54 PM.png / ...9.41.06 PM.png)
+- Supporting onboarding chrome around the wallet: first-run welcome/tour modal, persistent 'no forgot password — Backup' warning banner, release-notes/update notification, and a testnet faucet widget (handy for any Nimiq dev-demo app the CLI scaffolds). Individually small; bundle as an 'app shell extras' template.
+- **Built from:** `wallet/src/components/modals/WelcomeModal.vue`, `modals/BackupModal.vue`, `TestnetFaucet.vue`, `UpdateNotification.vue`, `AnnouncementBox.vue`, `StatusScreen.vue`

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,10 +1,10 @@
 {
   "name": "nimiq-branding-cli",
-  "version": "1.0.0",
-  "description": "nq — 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.",
+  "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": {
-    "nq": "bin/nq.js"
+    "nq": "./bin/nq.js"
   },
   "scripts": {
     "verify": "node scripts/verify.mjs",
@@ -36,16 +36,5 @@
     "scaffolding",
     "crypto",
     "ui"
-  ],
-  "files": [
-    "bin/",
-    "assets/",
-    "scripts/verify.mjs",
-    "scripts/snap.mjs",
-    "NOTICE.md",
-    "registry/index.json",
-    "registry/components/*/meta.json",
-    "registry/components/*/html/",
-    "registry/components/*/vue/"
   ]
-}
+}