feat(import): add design.md import reverse command

[zagi]

Generates a DESIGN.md from an existing Node.js project by statically analyzing its design sources. No AI, no network — deterministic code analysis that runs in ~5ms on a clean project.

Pipeline

detect framework → scan sources → parse → merge → emit

What it reads

• package.json / README.md — project name, description, version, and first-paragraph intro. README H1 beats package.json.name; directory basename is the final fallback. Dependencies are also scanned against an ordered table of 18 known icon-library packages (Lucide, Heroicons, Material Symbols, Phosphor, Tabler, Feather, Radix, Font Awesome) to infer icons.library.
• Tailwind configs (tailwind.config.{js,ts,cjs,mjs}) — loaded via dynamic import (Bun handles TS natively); theme.extend is walked for colors, borderRadius, spacing, fontSize (incl. the [size, meta] tuple form), and fontFamily. Regex fallback on eval errors so malformed configs still surface their color block.
• CSS custom properties — both Tailwind v4 @theme { } blocks (with prefix-stripping: --color-primary → colors.primary, --spacing-md, --radius-lg, --font-*, --text-*, --leading-*, --tracking-*, --font-weight-*; --breakpoint-* skipped) and legacy :root { } blocks (name-heuristic classification). --icon-* properties (--icon-library, --icon-style, --icon-stroke-width, --icon-grid, --icon-color, --icon-size, --icon-size-<bucket>) are routed into the icons block instead of being misclassified as generic spacing/color tokens.
• DTCG tokens (tokens.json, design-tokens.json, design_tokens.json, *.tokens.json) — walks $type/$value; only accepts tokens under colors / spacing / rounded / typography top-level sections so per-component dimensions don't pollute the scale. A top-level icons block is also recognised, accepting both $value-wrapped and bare values for library / style / strokeWidth / grid / size / color.

Framework detection

Cosmetic, reported in the UI. Recognizes Next, Nuxt, Vite, SvelteKit, Remix, Astro, Create React App, Gatsby, Angular, Vue CLI, and falls back to generic Node / unknown. Meta-frameworks beat Vite on conflicts.

Scan hygiene

Bounded at depth 5. Skips node_modules, .git, .next, .nuxt, .output, .svelte-kit, .turbo, build, coverage, dist. Also skips vendor trees (public, static, vendor, vendors, third-party, third_party, bundles, charting_library), minified/RTL stylesheets (*.min.css, .rtl.css), and hashed bundler output (..css) — so e.g. a bundled TradingView charting library's 40+ v-rhythm- tokens don't leak into the project's own design system.

Merge

Precedence: CSS → Tailwind → DTCG (later wins because DTCG is most structured). Rebuilds the flat symbolTable the linter expects so the generated state can be round-tripped through lint/export.

For icons specifically, the package.json library heuristic is unshifted to lowest precedence — CSS and DTCG declarations override the dependency-scan guess, since a project may pull lucide-react for one component while declaring "Heroicons" in its design tokens. Within the merge, scalar fields use last-wins and size maps merge element-wise, capped at 256 entries to bound the emitted YAML.

Output

YAML frontmatter (name, description, colors, typography, rounded, spacing, and icons when discovered) plus a markdown body: # Name heading, description, README intro, ## Overview (framework + counts + source summary), per-section bullet lists of the imported tokens — including a ## Iconography section after ## Rounded when icon metadata is present — and a footer inviting the team to edit the prose. Every user-controlled string in the icons block passes through the same sanitizeImportedText pipeline as name and description, neutralising heading injection, HTML, and CR/LF before emission. The frontmatter alone round-trips cleanly through lint and back through export.

Forward compatibility with #44

The icons: frontmatter shape and ## Iconography section match the schema proposed in #44 (feat(spec): add Iconography section and icons.* tokens) field-for-field. Until #44 lands, the main-branch linter silently passes both as unknown content (parser whitelist + section-order rule), so this PR is independently mergeable. Once #44 lands, the same emitted output is actively validated without any code change here. Two follow-ups are planned post-#44: populating icons.size.* / icons.grid / icons.color into the symbolTable (requires the widened ResolvedValue union from #44), and lifting Tailwind/DTCG export from no-op to pass-through if either format ever grows an icon surface.

CLI

design.md import <project>              # writes <project>/DESIGN.md
design.md import <project> --dryRun     # prints to stdout
design.md import <project> --format json # NDJSON progress events

Pretty mode renders live via Ink, showing staged progress (◐/✓/⚠/✗) for detect → scan → parse → merge → write. JSON mode emits one ImportStep per line on stdout for scripts and CI.

Tests

361 passing. Unit tests cover every parser, the framework detector, the source scanner's vendor filtering, the merger, the markdown emitter, project metadata, and the Ink component, including ~38 dedicated icon-discovery cases (package.json library detection, --icon-* classification, DTCG icons block parsing, merger size-map cap, frontmatter and body emission, heading-injection sanitisation, edge cases for strokeWidth: 0 / NaN / unit-suffix / empty buckets). Integration tests (VR-1, VR-2) round-trip examples/paws-and-paths, atmospheric-glass, totality-festival, and four framework fixtures (Next, Vite, Nuxt, plus the new icon-project fixture exercising package.json + CSS + DTCG icon discovery in one run) through import → lint and assert zero linter errors.

Security

All JSON paths route through safeJsonParse (prototype-pollution guard from commit 47dd3dd); the DTCG icons-subtree parser additionally re-skips __proto__ / constructor / prototype keys in the size map as defense-in-depth. The DTCG walker short-circuits the icons subtree at the top level so a deep icons tree can't burn DFS cycles before being filtered. MAX_ICON_SIZE_ENTRIES = 256 caps the merged size map so an attacker-controlled tokens.json can't bloat the emitted YAML. yamlStringify(doc, { indent: 2 }) is pinned so quoting tests stay stable across yaml-package upgrades.

Build

Marks ink, react, and react-devtools-core as --external so Ink 7's devtools import doesn't break the bundler.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.