design_handoff.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::design — Claude Design project-folder handoff contract.
//
// A design tool can export more than a single screen of HTML: a whole project
// folder carrying a design system (`_ds/<slug>/` — token CSS + a readme), a
// per-asset ledger (`.pulp-design-meta.json`, the same sidecar the CLI records),
// and a **handoff README** that states implementer intent in machine-readable
// prose — most importantly the explicit *fidelity declaration*: recreate the
// screens pixel-for-pixel (hi-fi) or restyle them into the target design system
// (lo-fi). That one bit prevents a whole class of wasted pixel-matching effort on
// designs that were only ever meant to be re-skinned.
//
// This translation unit parses that folder + README into a structured
// HandoffContract so the intent is a value the importer can act on instead of a
// paragraph a human has to read. It is pure: it takes already-read text and a
// directory listing, and does no filesystem or network I/O itself — the CLI owns
// the walk. The formats are community conventions, not a vendor API, so the
// contract is a versioned fingerprint (kHandoffFormatVersion) and every parse is
// tolerant: an absent section is empty, never an error.
 
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace pulp::design {

inline constexpr std::string_view kHandoffFormatVersion = "2026.07-design-handoff-v1";

enum class FidelityIntent {
    unspecified,  
    hifi,         
    lofi,         
};

std::string_view fidelity_intent_name(FidelityIntent intent);

FidelityIntent fidelity_intent_from_text(std::string_view text);

struct HandoffScreen {
    std::string name;
    std::string path;  
    std::vector<std::pair<std::string, std::string>> specs;
};

struct HandoffContract {
    std::string format_version;                                  
    std::string source;                                          
    FidelityIntent fidelity = FidelityIntent::unspecified;
    std::vector<std::string> design_systems;                     
    std::vector<HandoffScreen> screens;                          
    std::vector<std::pair<std::string, std::string>> tokens;     
    std::vector<std::string> interactions;                       
};

HandoffContract parse_handoff_readme(std::string_view markdown, std::string_view source);

void merge_design_systems(HandoffContract& contract, const std::vector<std::string>& slugs);

std::string handoff_contract_json(const HandoffContract& contract);
 
}  // namespace pulp::design