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). Preflight reports ready only when a direct screen/frame link resolves successfully; a link with unavailable credentials, denied access, or a failed lookup remains ambiguous with the provider failure in the result. Figma must return the requested node, and a Zeplin project dashboard cannot stand in for a screen. For complete Zeplin layers and assets, use a project/screen URL (or a shortlink that redirects to one); NoDesign reads the latest screen version.

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. Figma tokens need file_content:read for design extraction; auth status may be unable to validate a token without the separate current_user:read scope. 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://app.zeplin.io/project/PROJECT_ID/screen/SCREEN_ID" --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. ~/.pi-secrets/.env (Central monorepo secrets file; supports export KEY= lines)
3. ~/.config/nodesign/.env (Package-level .env backup with 0600 permissions)
4. User config file (~/.config/nodesign/config.json with restricted 0600 permissions)
5. OS Keychain (macOS Keychain via security / Linux Secret Service via secret-tool) — best-effort cache only
6. .env file in current working directory (optional last-resort mirror; never shadows durable stores)

nodesign auth login requires at least one verified file-backed durable write (~/.pi-secrets/.env, ~/.config/nodesign/.env, or config.json). The OS keychain and project .env are optional mirrors and never count as the sole store, so tokens survive reboot, keychain lock, and leaving the repo.

---

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