nodesign

Standalone design context extractor and preflight CLI for AI agents (Pi, Claude Code, Cursor, Aider) and UI developers.

nodesign allows any developer or AI agent framework to authenticate, inspect design sources (Figma, Zeplin), and extract typography, colors, layout specs, and frame renders into structured context or --json payloads.

It also powers deterministic design preflight for norpiv workflows (nodesign preflight).

Experiment disclaimer: you probably do not need nodesign if your agent already has a good Figma MCP or Zeplin MCP in the same runtime. nodesign exists as a portable CLI contract: one command agents can run anywhere, with normalized Figma/Zeplin output and preflight checks.

Need	nodesign	Zeplin MCP	Figma MCP
Figma + Zeplin in one command	Yes	No	No
Works outside MCP runtimes (shell, CI, Cursor, Claude Code, Aider)	Yes	No	No
Normalized JSON shape across providers	Yes	Zeplin only	Figma only
Auth helper/token lookup from env, keychain, config	Yes	MCP-managed	MCP-managed
Preflight for missing or ambiguous design links	Yes	No	Depends
Design extract plus render from a CLI	Yes	Partial	Depends

Use the native MCP first when it is enough. Use nodesign only when portability, normalization, or preflight is the actual problem.

---

Installation & Setup

1. Authentication for Private Files

Most company Figma files and Zeplin screens are private and require a Personal Access Token (PAT). Run authentication once to save your credentials securely:

# Interactive setup (stores token securely in OS Keychain / Secret Service / User config)
npx @raquezha/nodesign auth login

# Or pass tokens directly via environment variables:
export FIGMA_TOKEN="figd_xxx"
export ZEPLIN_TOKEN="zpl_xxx"

2. Execution

Instant Execution (No global install required)

# Uses credentials saved during `auth login` or env variables automatically:
npx @raquezha/nodesign extract "<design-url>"

Global CLI Install (Recommended for AI Agents & Terminal Devs)

npm install -g @raquezha/nodesign

Note on Private Files: nodesign automatically resolves credentials from process.env, local .env, ~/.pi-secrets/.env, OS Keychain (macOS / Linux), or ~/.config/nodesign/config.json. If no token is found for a private file, nodesign returns a clear AUTH_REQUIRED status.

---

Quick Start

1. Authenticate

Interactive terminal prompt with Personal Access Token (PAT) creation guidance:

nodesign auth login

Non-interactive / CI flag mode:

nodesign auth login --provider figma --token "figd_xxx"
nodesign auth login --provider zeplin --token "zpl_xxx"

Check credential status and API validity:

nodesign auth status

2. Extract Design Context

Extract colors, typography, layout specs, and component hierarchy:

nodesign extract "https://www.figma.com/design/KEY/FileTitle?node-id=1-2"
nodesign extract "https://zpl.io/AOGOKp6" --manifest
nodesign extract "https://zpl.io/AOGOKp6" --json

Download frame screenshot / render asset to disk:

nodesign extract "https://www.figma.com/design/KEY/FileTitle?node-id=1-2" --render --out ./renders

3. Generate Design Grounding Manifest (Recommended for AI Agents)

Generate a compact manifest that maps external design colors and hierarchy directly to existing local design tokens and reusable components:

nodesign extract "<design-url>" --manifest

Output format (Markdown):

• Mapped Local Design Tokens: Direct map from design hex codes to project theme tokens (e.g. #1E88E5 → TapatColors.brandPrimary from core/ui/theme/Color.kt).
• Reusable Local Components: Available components in your codebase matching elements in the design (e.g. PrimaryButton, TopAppBar).
• UI Structure Blueprint: Token-efficient ASCII component tree showing exact container directions, paddings, gaps, and sizes without wasting LLM context.

4. Generate Starter UI Code (--code)

Generate initial layout code for Jetpack Compose, React (Tailwind), or semantic HTML:

# Jetpack Compose with mapped theme tokens and discovered project components
nodesign extract "<design-url>" --code compose

# React + Tailwind flex layouts
nodesign extract "<design-url>" --code react

# Semantic HTML + CSS flexbox
nodesign extract "<design-url>" --code html

When using --code compose:

• Automatically swaps raw hex colors (#1E88E5) for discovered project tokens (TapatColors.brandPrimary).
• Injects necessary Kotlin package imports (import com.app.core.ui.theme.TapatColors).
• Replaces generic boxes with discovered existing components (Header(), PrimaryButton()).

---

Agent Integration Cheatsheet

Include these snippets in your system instructions or project rules for AI agents:

General System Prompt Instruction

"When given a Figma or Zeplin link for UI work, run nodesign extract <url> --json to inspect colors, typography, layout specs, and frame structure before planning UI changes."

Pi Agent / Custom Scripts

nodesign extract "https://www.figma.com/design/KEY/Title?node-id=1-2" --json

Claude Code / Cursor / Aider CLI

nodesign auth status
nodesign extract "<design-url>" --render --out .workflow/tasks/active/evidence

---

Multi-OS Credential Storage

nodesign checks and persists credentials in the following hierarchy:

1. FIGMA_TOKEN / ZEPLIN_TOKEN environment variables
2. .env file in current working directory
3. ~/.pi-secrets/.env (Central monorepo secrets file)
4. ~/.config/nodesign/.env (Package-level .env backup with 0600 permissions)
5. OS Keychain (macOS Keychain via security / Linux Secret Service via secret-tool)
6. User config file (~/.config/nodesign/config.json with restricted 0600 permissions)

nodesign auth login automatically dual-writes to the OS Keychain, ~/.pi-secrets/.env, and ~/.config/nodesign/.env to ensure credentials survive npm global upgrades and environment resets.

---

UI Stack Detection & Architecture Directives

nodesign inspects the host repository's build files and codebase to detect the exact UI stack:

• compose (Android Jetpack Compose): Emits M3 guidelines and normalizes full-width layouts to Modifier.fillMaxWidth().
• kmp (Compose Multiplatform): Enforces commonMain placement rules, forbids android.* / LocalContext, and routes assets to Res.drawable.*.
• views (Native Android XML): Directs layout construction to res/layout/ XML files and @color/ resources.
• mixed (Hybrid Views + Compose): Directs new UI into Compose wrapped in ComposeView.

High-Confidence Component Matcher

Instead of relying on fragile regex heuristics, nodesign matches design layer names against codebase symbols using a 3-tier strategy:

1. Exact Match: Direct equality with local @Composable declarations.
2. Normalized Match: Matches across casing and spacing variations (e.g., Figma layer 'Primary Button' → local Composable PrimaryButton()).
3. Fuzzy Suffix/Prefix Match: High-confidence prefix/suffix matching (e.g., Figma 'Summary Card' → local OrderSummaryCard()).

Generic layout containers (Row, Column, Box, Frame) are automatically protected from false-positive mappings.

---

Konsist-Style Architectural & Symbol Harvester

nodesign incorporates a lightweight Konsist-Style Architectural Harvester inspired by structural linting engines like Konsist and ArchUnit.

How It Works

Instead of relying on hardcoded folder names (domain/, data/, presentation/), nodesign scans class declarations, function signatures, annotations, and usage patterns across your codebase:

1. Architectural Signal Detection:
   • Clean Architecture: Detects *UseCase, *Interactor, *Repository, *Gateway, *Port, and *Adapter declarations.
   • Design System Modules: Detects :designsystem, core:ui, ui/theme/, Color.kt, Theme.kt, and @Composable fun *Theme.
   • Feature & Layer Structures: Detects feature/*/, screens/, viewmodels/, *ViewModel, *State, *Intent.
2. Deep Custom Theme Token Discovery:
   • Deep-scans custom theme wrappers (TapatTheme.colors, LocalColors.current, val PrimaryBlue = Color(...)).
   • Automatically harvests package names (package com.app.ui.theme) and injects required Kotlin import statements into generated @Composable code.
3. Usage-Based Component Catalog:
   • Scans codebase invocation patterns (e.g. PrimaryButton(...) used 14x across production screens).
   • Instructs AI coding agents to reuse existing project Composables instead of generating duplicate code or raw primitives.
4. Zero-Setup Portability:
   • Runs out-of-the-box via npx @raquezha/nodesign without requiring Gradle plugins or external linter dependencies.

---

Commands

auth login

Prompt or save Personal Access Token (PAT) credentials for Figma and Zeplin.

Flags:

• --provider <figma|zeplin>
• --token <pat>

auth status

Show active credential sources and validate reachability (valid, invalid, unreachable).

extract

Extract design specs from a Figma or Zeplin URL or URI (zpl://).

Flags:

• --manifest output compact grounding manifest (mapped local tokens + blueprint)
• --code <compose|react|html> generate starter UI code with mapped theme tokens
• --json machine-readable JSON output
• --markdown human-readable markdown format
• --render download frame screenshot
• --out <dir> target output directory for renders/assets

preflight (RPIV Integration)

Inspect project directory and design evidence for RPIV workflow gates.

nodesign preflight --path . --task github:101
nodesign preflight --json --path . --task jira:ANDROID-123

---

Development & Test

cd packages/nodesign
npm install
npm test