design_manifest.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::design — compiled design contract.
//
// A DesignManifest is the closed set of tokens and components a generated or
// imported UI is allowed to bind to. It is compiled from the buildable sources
// of truth — a Theme (the token allowlist) and the component catalog (each
// widget's native class plus the exact theme tokens it paints through) — into
// one deterministic artifact. Two consumers use it:
//
//   1. A binding prompt (Markdown) embedded in an importer / codegen prompt, so
//      the model that writes UI JS is told up front which tokens and widgets are
//      real. Inventing a token name or targeting an unknown widget is then a
//      visible contract break rather than a silent drift.
//   2. An adherence check that validates already-generated UI against the same
//      manifest — the prompt and the check share one source of truth.
//
// The manifest is deterministic: every list is sorted by name and serialized in
// a fixed key order, so it diffs cleanly in review and can gate CI.
 
#include <pulp/design/design_system.hpp>  // ComponentInfo, catalog()
#include <pulp/view/theme.hpp>            // Theme
 
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::design {

inline constexpr std::string_view kManifestVersion = "2026.07-design-manifest-v1";

struct ManifestToken {
    std::string name;   // e.g. "color.bg", "radius.md", "font.family"
    std::string kind;   // "color" | "dimension" | "string"
    std::string value;  // "#rrggbb"/"#rrggbbaa" | trimmed number | verbatim string
};

struct ManifestComponent {
    std::string name;             // "Knob"
    std::string category;         // category_name(...)
    std::string native_class;     // "pulp::view::Knob"
    std::string header;           // "pulp/view/widgets.hpp"
    std::string figma_component;  // component-set name in the authored library
    std::string usage;            // one-line intent
    std::vector<std::string> reskin_tokens;  // token allowlist for this widget
};

struct DesignManifest {
    std::string manifest_version;   // kManifestVersion
    std::string source;             // provenance ("ink-signal", a DESIGN.md path, ...)
    std::string appearance;         // "light" | "dark"
    int theme_schema_version = 0;   // Theme::kSchemaVersion the tokens follow
    std::vector<ManifestToken> tokens;
    std::vector<ManifestComponent> components;
};

DesignManifest compile_design_manifest(const pulp::view::Theme& theme,
                                       const std::vector<ComponentInfo>& components,
                                       std::string source,
                                       std::string appearance);

DesignManifest compile_ink_signal_manifest(bool dark = false);

std::string manifest_to_json(const DesignManifest& manifest);

DesignManifest manifest_from_json(const std::string& json);

std::string emit_binding_prompt(const DesignManifest& manifest);
 
}  // namespace pulp::design