Design2Web Quick Start Guide¶

Welcome to Design2Web! This tool transforms a structured JSON design specification into a complete, runnable HTML, CSS, and JavaScript web application.

🚀 Overview¶

Design2Web is a Python CLI utility designed to bridge the gap between design specifications and front-end code. It reads a JSON file defining layout, components, and styles, and outputs the necessary static web assets (index.html, style.css, etc.).

Core Modules: * main.py: The entry point for the CLI. * types.py: Defines the expected data structures for the design spec. * parse_design_spec: Handles reading and validating the input JSON. * layout_detector: Interprets the layout structure defined in the spec. * html_generator: Constructs the semantic HTML structure. * generate_css: Generates the accompanying CSS, utilizing Flexbox for layout. * image_loader: Manages paths and references for assets. * output_writer: Writes the generated files to the target directory.

🛠️ Installation & Setup¶

Since this is a package structure, assume you have the necessary dependencies installed (e.g., pip install -r requirements.txt).

To run the tool, you will execute main.py from your terminal, passing the path to your design specification JSON file.

⚙️ Usage Guide¶

The primary workflow involves: 1. Creating a JSON file that adheres to the structure defined in types.py. 2. Running main.py against that file.

Step 1: Define Your Design Specification (JSON)¶

Your JSON file must describe the overall structure, colors, and individual components.

Example Structure Snippet:

{
  "metadata": {
    "title": "My Awesome Webpage",
    "base_font": "Arial, sans-serif"
  },
  "colors": {
    "primary": "#007bff",
    "background": "#f8f9fa",
    "text_dark": "#333333"
  },
  "layout": {
    "type": "flex-row",
    "children": [
      {"component": "navbar", "id": "main-nav"},
      {"component": "content_area", "id": "main-content"}
    ]
  },
  "components": {
    "navbar": {
      "type": "navbar",
      "items": ["Home", "About", "Contact"]
    },
    "content_area": {
      "type": "card",
      "content": "Welcome to the site!",
      "style": {
        "padding": "20px",
        "shadow": "0 4px 8px rgba(0,0,0,0.1)"
      }
    }
  }
}

Step 2: Run the Conversion¶

Use the main.py entry point to process the file.

python main.py --input ./design_spec.json --output ./dist

This command tells the tool: * Read the specification from design_spec.json. * Write all generated files (HTML, CSS, etc.) into the dist/ directory.

💡 Real Usage Examples¶

Here are three scenarios demonstrating how different parts of the specification drive the output.

Example 1: Simple Landing Page (Focus on Layout & Color)¶

Goal: Create a page with a centered header and a primary call-to-action button.

Input JSON Snippet Focus: The layout section dictates the overall container structure, and the colors section feeds into style.css.

Code Execution:

python main.py --input ./landing_spec.json --output ./site_v1

Expected Output: * site_v1/index.html: Contains a <div class="container"> styled using Flexbox to center content. * site_v1/style.css: Contains rules like body { background-color: #f8f9fa; } and .btn-primary { background-color: #007bff; }.

Example 2: Complex Form Component (Focus on Component Generation)¶

Goal: Generate a fully structured form component using the form type.

Input JSON Snippet Focus: The components section defines a form object, specifying inputs and labels.

Code Execution:

python main.py --input ./form_spec.json --output ./form_app

Expected Output: * form_app/index.html: Will contain semantic <form> tags, <label> elements, and <input> fields, correctly nested according to the spec. * form_app/style.css: Will include specific styling for form elements (e.g., input borders, label alignment) generated by generate_css.

Example 3: Dynamic Content Integration (Focus on JavaScript/Image Loading)¶

Goal: Build a card component that loads an image dynamically.

Input JSON Snippet Focus: The card component definition includes an image_url property, which image_loader.py processes.

Code Execution:

python main.py --input ./gallery_spec.json --output ./gallery_viewer

Expected Output: * gallery_viewer/index.html: The card structure will include an <img> tag whose src attribute is correctly populated by image_loader.py based on the provided path in the JSON. * gallery_viewer/script.js (Generated): If the spec requires interactivity, main.py will trigger JS generation, potentially using vanilla JS to handle image loading or component initialization.

📚 Module Reference¶

Module	Primary Responsibility	Key Function
`main.py`	CLI orchestration and execution flow.	`main()`
`parse_design_spec`	Reading and validating the input JSON.	`parse_design_spec(json_file)`
`layout_detector`	Determining the structural hierarchy.	`detect_layout(spec)`
`html_generator`	Building the final HTML string.	`generate_html(spec)`
`generate_css`	Creating the stylesheet, prioritizing Flexbox.	`generate_css(spec)`
`image_loader`	Resolving and preparing asset paths.	`load_assets(spec)`
`output_writer`	Saving all generated files to disk.	`write_files(files