web2fig

web2fig is a terminal-first .NET MVP for analyzing a website, reviewing extracted design signals in a CLI/TUI flow, and exporting a truthful Figma-ready bundle with a markdown style report for human review.

MVP status

• Built-in CLI commands for analysis, inspection, export, and session browsing are implemented.
• The default composition root wires a local file-backed session store, the heuristic WebsiteAnalysisEngine, and the BundleAnalysisExporter.
• The shipped exporter does not generate a native .fig file; it writes a machine-readable Figma-ready JSON bundle plus a markdown style report, manifest, summary, and diagnostics artifacts.

Installation

Prerequisites

1. .NET 10 SDK installed.
2. PowerShell on Windows for run-local.ps1 (optional but convenient).

Clone and restore

git clone <your-fork-or-repo-url>
cd .\web2fig
dotnet restore .\web2fig.slnx

Usage

Command surface

web2fig analyze <url> [options]
web2fig inspect <session-id> [--interactive]
web2fig export <session-id> [options]
web2fig sessions list [options]
web2fig --help

Common examples

dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- analyze https://example.com
dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- analyze https://example.com --interactive --viewports desktop,mobile
dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- sessions list --status completed
dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- inspect <session-id>
dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- export <session-id> --output .\artifacts\<session-id>

Interactive workflow

• analyze <url> --interactive prompts for scope, viewports, and diagnostics, then opens the review flow.
• inspect <session-id> --interactive opens the saved session in the review flow.
• export <session-id> --interactive prompts for export settings before writing artifacts.
• Interactive prompts require a real terminal with keyboard input; redirected or piped input will fail fast if --interactive is requested.

Understanding the export bundle

The built-in exporter writes two complementary deliverables:

1. <name>.style-report.md is the primary human-readable deliverable. Open this first for a narrative summary of layout structure, colors, typography, iconography, spacing, theme signals, responsive notes, and exporter limitations.
2. <name>.figma-ready.json is a machine-readable bridge/replay/export artifact. It is not a native .fig file, and it is not something users manually edit in Figma directly. Instead, it preserves the extracted design model for downstream tooling, automation, replayable exports, debugging, and future conversion workflows.

How to use the artifacts today

Until native .fig output exists, a practical workflow is:

1. Read <name>.style-report.md to understand the site's visual system and the exporter's fidelity notes.
2. Check <name>.manifest.json to see what was exported, what was skipped, and which files belong to the bundle.
3. Keep <name>.figma-ready.json and optional <name>.analysis.json for scripting, regression tests, custom importers, or future exporters that can consume the structured data.
4. Use <name>.summary.txt and <name>.diagnostics.log for quick CLI-friendly review and troubleshooting.

Current artifact list

The built-in exporter writes these files into the chosen output directory:

• <name>.style-report.md - primary human-readable style and layout report
• <name>.figma-ready.json - machine-readable bridge/export bundle
• <name>.manifest.json - machine-readable manifest of bundle contents and issues
• <name>.summary.txt - compact plain-text summary
• <name>.diagnostics.log - diagnostic log for warnings and traceability
• <name>.analysis.json - optional intermediate analysis JSON (unless --no-intermediate-json is used)

Saved sessions are stored under the local application data folder. On Windows, the default location is %LOCALAPPDATA%\web2fig\sessions.

Current limitations

• Analysis is heuristic and based on static HTML/CSS inspection; the MVP does not execute JavaScript or reproduce late-hydrated client-side state.
• Multi-viewport output currently reuses one structural pass and annotates responsive limitations honestly.
• The review flow is read-only; it supports inspection and export, not manual design editing.
• Requesting --native-fig records the intent and emits a warning, but the shipped exporter still writes the markdown style report plus machine-readable JSON artifacts rather than a native .fig file.

Build and run locally

Convenience script

run-local.ps1 now uses a target-driven contract:

• app runs the CLI locally.
• tests runs all tests in the solution.
• unit-tests runs only unit test projects under tests\.
• e2e-tests runs E2E/integration-style test projects under tests\.

.\run-local.ps1 app
.\run-local.ps1 app analyze https://example.com
.\run-local.ps1 tests
.\run-local.ps1 unit-tests
.\run-local.ps1 -Configuration Release app export <session-id> --output .\artifacts\<session-id>

This repository currently ships only unit test projects, so .\run-local.ps1 e2e-tests will fail fast until an E2E or integration test project is added under tests\.

Direct .NET commands

dotnet build .\web2fig.slnx --nologo
dotnet run --project .\src\Web2Fig.Cli\Web2Fig.Cli.csproj -- --help

Running tests

dotnet test .\web2fig.slnx --nologo

Formatting before verification:

dotnet format .\web2fig.slnx

Repository layout

docs\specs        Product and MVP specifications
src\Web2Fig.Core  Analysis contracts and core engine/exporter implementations
src\Web2Fig.Cli   Spectre.Console CLI/TUI host
tests\            Unit tests for the CLI and core services
run-local.ps1     Target-driven local app/test helper script