Skip to content

Button package and assets example.md

Latest commit

 

History

History
362 lines (286 loc) · 13.3 KB

Button package and assets example.md

File metadata and controls

362 lines (286 loc) · 13.3 KB

FROG logo

Example — Default Button Package and Asset Tree

Complete illustrative example of a default button realization package together with a simulated asset tree
FROG — Free Open Graphical Language

Contents

1. Overview

This document provides a complete illustrative example for the default realization of frog.widgets.button.

It combines:

  • a machine-readable .wfrog realization package,
  • a normalized asset tree,
  • a resource manifest,
  • a layer map,
  • an anchor publication resource for dynamic label placement.

The example is intentionally small, but it is structured to preserve the doctrinal split between widget semantic law, realization publication, asset resources, and runtime rendering responsibility.

This file is therefore the concrete asset-facing companion to the machine-readable example package. It shows how the package-level publication corridor may be materialized on disk without introducing semantic drift.

It also serves as the first concrete proof that the button realization corridor can be published in a form that is both human-readable and machine-readable while remaining compatible with later runtime implementations in different host environments.

2. Purpose

The purpose of this example is to show one coherent end-to-end publication unit for a standard widget realization without confusing:

  • class law,
  • realization-family posture,
  • package publication,
  • asset files,
  • runtime implementation.

In particular, this example preserves the distinction between:

  • the semantic button label owned by the widget class through label.text,
  • the realization-side placement surface used to display that text,
  • the state-sensitive visual resources used for the button face,
  • optional decorative or structural layers such as a frame,
  • the runtime-side responsibility for drawing live text into the published placement surface.

This distinction is the main reason the example package and the asset tree must be shown together. The package explains the realization contract. The asset tree shows how that contract is concretely supported.

The example is intentionally family-generic rather than variant-specific. It proves the shared default button publication corridor first. Later examples may specialize that corridor for compatible realization variants or skin bundles, but they should not replace the architectural split demonstrated here.

3. What This Example Demonstrates

This example is intended to prove at least the following:

  • the asset tree can remain aligned with the machine-readable realization package,
  • the state-sensitive button face can be published through explicit state resources,
  • the semantic button label can remain class-owned while still receiving realization-defined placement support,
  • optional structural layers such as frame can be published without becoming new widget semantics,
  • a runtime can consume the same publication corridor without relying on undocumented filename heuristics or runtime-private layout rules.

The example also demonstrates the preferred split between:

  • state_maps for visual state embodiment,
  • part_bindings for stable structural correspondence,
  • anchor publication for dynamic host-rendered label placement.

More concretely, this example is meant to show that:

  • the asset tree is not merely decorative documentation,
  • resource placement on disk remains part of the inspectable publication corridor,
  • the runtime should consume published realization structure rather than inventing its own hidden realization contract.

4. Simulated Tree

Libraries/Realizations/Default/Examples/ButtonPackage/
├── default_button_realization.wfrog.json
└── assets/
    └── button/
        ├── asset_manifest.json
        ├── face/
        │   ├── normal.svg
        │   ├── disabled.svg
        │   ├── focused.svg
        │   ├── pressed.svg
        │   └── layer_map.json
        ├── anchors/
        │   └── label.json
        └── frame/
            ├── normal.svg
            └── focused.svg

This tree intentionally does not publish state-specific SVG assets for label. The button label remains a dynamic public surface, so the realization publishes a placement surface for that label rather than baking final text ownership into SVG files.

This tree is also intentionally conservative:

  • face/ carries the main state-sensitive visual embodiment,
  • anchors/ carries dynamic placement support for host-rendered semantic text,
  • frame/ illustrates an optional supporting visual layer,
  • no private runtime-only folders are treated as if they were part of the published realization contract.

The tree also shows an important discipline rule for future realization families: variant-specific or skin-specific material should only be introduced when it is published explicitly as such, not smuggled into the asset structure as an undocumented runtime convention.

5. Files Included

  • default_button_realization.wfrog.json
  • asset_manifest.json
  • layer_map.json
  • label.json under anchors/
  • normal.svg, disabled.svg, focused.svg, and pressed.svg under face/
  • normal.svg and focused.svg under frame/

The SVG files are represented here as paths and placeholders only. Their visual drawing content is intentionally left out at this stage.

The expected role of each file is as follows:

  • default_button_realization.wfrog.json publishes the machine-readable realization package, including target class, parts, bindings, state maps, and fallbacks,
  • asset_manifest.json provides a compact inventory of the resources shipped with this example package,
  • layer_map.json describes how visual face layers are composed or interpreted when the runtime loads face resources,
  • anchors/label.json publishes the placement surface used by the runtime to render live label.text,
  • face/*.svg publishes state-specific visual embodiment for the button face,
  • frame/*.svg publishes an optional supporting visual layer for outer emphasis or focus posture.

In a fuller publication corridor, the same pattern may later be extended with:

  • variant-specific subtrees,
  • skin-specific resource groups,
  • style-token support artifacts,
  • additional frame or density resources.

However, none of those extensions are required for this first proof case. The example deliberately remains small enough to keep the core architectural split legible.

6. Publication Alignment

The important alignment rule of this example is:

  • the package JSON identifies the realization record and its state_maps,
  • the resource inventory identifies the concrete resource files,
  • the asset tree places those files in a normalized directory structure,
  • the runtime consumes the published placement and state information rather than inventing its own hidden contract.

For the button corridor specifically, the expected alignment is:

  • face resources align with state-sensitive visual publication such as normal, disabled, focused, and pressed,
  • frame resources align with optional supporting visual publication when the family exposes it,
  • anchors/label.json aligns with the published placement surface used for dynamic label rendering,
  • the package-level part_bindings align the public parts with those realization-side surfaces.

This means the tree is not merely decorative. It is part of the inspectable realization-publication corridor.

The alignment rule also implies the reverse:

  • the asset tree must not imply semantics that the package does not publish,
  • the package must not reference resources that the tree does not actually make available,
  • the runtime must not rely on silent assumptions that neither the package nor the tree expose explicitly.

7. Reading Notes

This example is intentionally conservative:

  • the package targets one class,
  • the assets are scoped by structural realization role,
  • the state mapping is explicit for the main state-driven visual part,
  • fallback remains explicit,
  • the maps remain realization support, not semantic truth.

The most important architectural point is that face and label do not follow the same publication posture:

  • face is a state-driven visual part, so it is represented through state-sensitive SVG resources,
  • label is a semantic public text-bearing part, so it is represented through a placement resource rather than through baked final text assets.

This means that:

  • the widget class remains the owner of the semantic text surface,
  • the realization remains the owner of the placement geometry and visual embodiment,
  • the runtime remains responsible for rendering the live text using the published placement surface,
  • the asset tree does not silently become the owner of button-text semantics.

The optional frame/ subtree is shown here to illustrate that a realization family may publish additional visual layers without changing widget-class meaning. Whether a given runtime chooses to materialize frame as a distinct host layer or flatten it into a composed drawing pipeline remains an implementation matter, provided that the published realization contract is respected.

This example also demonstrates a useful discipline rule for future widget families:

  • when a public surface is fundamentally dynamic and host-rendered, prefer publishing a placement resource,
  • when a public surface is fundamentally a state-sensitive visual embodiment, prefer publishing explicit state resources,
  • do not let the asset tree blur that difference.

The same discipline will matter later for:

  • numeric value_display surfaces,
  • string text_display surfaces,
  • boolean label surfaces,
  • chart labels and other dynamic chart-associated text-bearing surfaces.

8. Summary

This example provides a complete first publication block for a standard widget realization package in the default family.

It demonstrates a coherent asset-publication posture in which:

  • state-sensitive SVG resources are used for the button face,
  • dynamic label placement is published through an anchor resource,
  • machine-readable package publication and concrete assets remain aligned,
  • semantic ownership does not collapse into the asset tree.

It is designed to serve as the reference pattern for the next families such as numeric, boolean, string, and chart, especially when those widgets also expose dynamic public text or other dynamic public surfaces that must remain portable across runtimes.

The next most coherent file to handle after this one is:

  • Libraries/Realizations/Default/Examples/ButtonPackage/default_button_realization.wfrog.json

That file is the natural next step because the prose corridor is now coherent and the next closure point is the concrete machine-readable artifact that the simulated tree claims to publish.