Skip to content

Readme.md

Latest commit

 

History

History
551 lines (432 loc) · 20.2 KB

Readme.md

File metadata and controls

551 lines (432 loc) · 20.2 KB

FROG logo

Default Realization Examples

Normative example-corridor posture for the official Default widget realization family
FROG — Free Open Graphical Language

Contents

1. Overview

This directory defines the normative example-corridor posture for the official Default widget realization family.

Its purpose is to ensure that published examples reinforce the realization architecture rather than quietly replacing it with undocumented conventions.

An example in this directory is not merely illustrative prose. It is part of the inspectable publication corridor that links:

  • realization doctrine,
  • machine-readable realization publication,
  • concrete asset-tree organization,
  • portable runtime interpretation.

Examples in this directory therefore serve as publication evidence. They show how doctrinal rules, machine-readable records, and concrete resources align in a form that future runtimes and future contributors can inspect directly.

This corridor is especially important for the current normalization direction of the default family because the family now needs to show not only shared realization doctrine, but also bounded specialization through compatible realization variants and compatible skins without allowing those embodiment choices to drift into hidden class splits.

2. Why this Directory Exists

A realization family may look coherent at the doctrinal level while still remaining ambiguous at the publication level. That ambiguity usually appears in the examples first.

Without a normalized example corridor:

  • machine-readable packages drift away from the doctrinal wording,
  • asset trees become private conventions instead of inspectable publication artifacts,
  • dynamic public text may accidentally collapse into SVG ownership,
  • runtime implementations begin to define the real behavior of the system by convention,
  • future contributors cannot tell whether a pattern is normative, optional, variant-specific, skin-specific, or accidental.

This directory exists to prevent that drift.

It also exists to ensure that compatible embodiment choice remains explicit. If the family supports a checkbox-like and a switch-like boolean embodiment, or several skins of the same button corridor, the example layer must make that specialization legible without pretending that each visual specialization is a distinct widget class.

3. Scope

This document defines:

  • the role of examples in the Default realization family,
  • the minimum publication layers that a realization example should show,
  • how example prose, machine-readable JSON, and asset trees should align,
  • the portability posture expected from example material,
  • how compatible realization variants should be documented when they exist,
  • how compatible skin specializations should be documented when they exist.

This document does not define:

  • widget class law,
  • generic realization doctrine,
  • the full generic .wfrog specification,
  • one mandatory runtime implementation,
  • the visual design details of every shipped SVG resource.

4. What an Example Must Prove

A published example in this directory SHOULD prove at least the following:

  • which standardized widget class is being targeted,
  • which official realization family is being published,
  • which parts are realized as visual resource layers,
  • which parts are realized through placement-support resources such as anchors or text regions,
  • which states are published explicitly,
  • which fallbacks are published explicitly,
  • how the asset tree corresponds to the machine-readable resource records,
  • how a runtime can implement the realization without becoming the semantic owner of the widget.

When a realization family supports compatible embodiment variants, the example SHOULD also make clear:

  • whether the example is family-generic or variant-specific,
  • which parts and states remain shared across variants,
  • which resources or bindings are specialized by variant,
  • that the variant does not silently introduce a new widget class.

When a realization family supports compatible skins, the example SHOULD also make clear:

  • whether the example is skin-generic or skin-specific,
  • which embodiment surfaces remain structurally shared across skins,
  • which resources, token maps, or state maps are specialized by skin,
  • that the skin does not silently introduce a new class contract.

An example that does not make these boundaries legible is incomplete even if its JSON is syntactically valid.

5. Relationship with Other Default-Family Documents

The example corridor is subordinate to the architectural and doctrinal layers above it.

In particular:

  • Libraries/Realizations/Default/Readme.md defines the family-level posture,
  • Libraries/Realizations/Default/Package.md defines the machine-readable publication posture,
  • Libraries/Realizations/Default/Resource model.md defines how realization resources are described,
  • Libraries/Realizations/Default/State mapping.md defines how state-sensitive realization resources are mapped,
  • Libraries/Realizations/Default/Assets/Readme.md defines the asset-tree posture,
  • Libraries/Realizations/Default/Assets/Naming.md defines the naming posture.

Examples in this directory must align with those documents. They must not silently introduce a second architecture.

More specifically:

  • examples MUST NOT assign semantic ownership of dynamic public text to asset files when the doctrinal posture assigns that ownership to class law,
  • examples MUST NOT collapse state_maps and part_bindings into one undocumented mechanism,
  • examples MUST NOT use runtime-specific shortcuts as if they were the normative publication corridor,
  • examples MUST NOT turn variant choice into an implicit class split,
  • examples MUST NOT turn skin choice into an implicit semantic split.

6. Required Example Layers

A coherent realization example SHOULD include, either directly or through clearly paired files:

  • a prose explanation of the example and its architectural intent,
  • a machine-readable .wfrog realization package example,
  • a simulated or concrete asset tree,
  • enough resource naming and placement information to show how dynamic public surfaces are realized portably.

For small examples, these layers may be split across multiple files in the same example corridor. The important point is that the files reinforce one another rather than contradicting one another.

The preferred minimum publication stack is therefore:

  • example prose — explains what the example demonstrates and what architectural rule it is meant to prove,
  • machine-readable package — publishes realization records, resources, state maps, part bindings, and variant or skin specializations when relevant,
  • asset subtree — shows how concrete realization resources are organized, named, and scoped,
  • placement-support artifacts — shows how anchors or text regions are used when a host renders dynamic public surfaces.

When skin-aware examples exist, the preferred publication stack MAY also include:

  • style-token artifacts — shows how bounded style-token specialization is published without changing class meaning.

7. Example Directory Posture

The recommended posture for this directory is: 

Libraries/Realizations/Default/Examples/
  Readme.md
  Button default realization.wfrog.md
  Button package and assets example.md
  ButtonPackage/
    default_button_realization.wfrog.json
    assets/
      ...

In this posture:

  • the example prose explains what is being demonstrated,
  • the JSON file shows the machine-readable publication,
  • the asset subtree shows how the resources are concretely organized,
  • the three layers remain inspectable as one coherent publication unit.

A larger family example corridor MAY later contain several subdirectories, one per standardized widget family or one per realization target. That expansion remains acceptable only if the architectural split stays visible and the example names remain stable and inspectable.

When compatible variants or skins are published, the directory posture SHOULD also make the specialization readable from filenames and subtree structure rather than hiding it only in runtime code.

8. Button Example Posture

The button example is the first normative reference pattern for this directory. It is intentionally small, but it must already show the most important separation in the realization corridor.

For the standard default button example:

  • face is a state-sensitive visual part and therefore uses state-mapped visual resources,
  • frame may be published as an optional visual layer when the realization family exposes it,
  • label is a dynamic semantic public surface and is therefore preferably published through a placement-support resource such as anchors/label.json or a text-region resource rather than through baked final label SVG files,
  • the runtime renders live label.text into the published placement surface.

This is the key example posture that prevents dynamic public text from being redefined by asset ownership.

The button example should therefore remain the first reference pattern reused across the rest of the family:

  • visual state is shown through state_maps,
  • stable structural correspondence is shown through part_bindings,
  • dynamic text is shown through placement publication rather than asset-owned semantic text.

Because button realization is also the cleanest first place to show bounded skinning, it is a natural candidate for the first example corridor that later demonstrates one compatible variant and one compatible skin without changing the button class contract.

9. Variant-Aware and Skin-Aware Example Posture

When the default family allows several compatible realization variants for the same standardized class, the example corridor SHOULD make that variant posture explicit.

The preferred rule is:

  • a family-generic example proves the shared realization contract of the class,
  • a variant-specific example proves how one compatible embodiment specializes that contract without changing class meaning.

For example, a boolean corridor may later contain:

  • a family-generic boolean example proving the common boolean realization contract,
  • a checkbox-like example proving one compatible embodiment,
  • a switch-like example proving another compatible embodiment.

In such cases, the example must make clear:

  • which state vocabulary remains shared,
  • which parts remain shared,
  • which bindings or resources are variant-specific,
  • that the example remains inside one class contract unless another class is explicitly published elsewhere.

A variant-specific example must not silently imply:

  • a new intrinsic class,
  • a new mandatory public part model,
  • a new mandatory public method or event surface,
  • a runtime-private interpretation rule that only one implementation understands.

When the default family allows several compatible skins for the same realization corridor, the example corridor SHOULD make that skin posture explicit as well.

The preferred rule is:

  • a skin-generic example proves the shared realization contract and the shared structural mapping,
  • a skin-specific example proves how one compatible skin specializes resources or style-token posture without changing widget semantics.

A skin-specific example should therefore make clear:

  • which structural bindings remain shared,
  • which resource groups are specialized by skin,
  • which token maps or color defaults are specialized by skin,
  • that the skin remains a realization-side customization rather than a class split.

10. Portability Posture

Examples in this directory must remain portable across runtime families. That portability requirement applies especially to:

  • Python runtimes,
  • Rust runtimes,
  • C and C++ runtimes.

Portability does not require those runtimes to use identical host UI toolkits or identical rendering pipelines. It requires them to be able to consume the same published realization contract without one implementation becoming the hidden semantic source of truth.

Accordingly, examples SHOULD publish:

  • inspectable resource identities,
  • inspectable placement resources,
  • explicit state mappings,
  • explicit fallbacks,
  • clear separation between semantic public surfaces and visual assets.

When variant-specific examples exist, portability also requires that different runtimes can recognize:

  • the same base class contract,
  • the same realization-family rules,
  • the same variant identifier or equivalent specialization marker,
  • the same fallback posture when one variant cannot be realized exactly.

When skin-specific examples exist, portability also requires that different runtimes can recognize:

  • the same base class contract,
  • the same shared part model and state vocabulary,
  • the same skin identifier or equivalent specialization marker,
  • the same bounded fallback posture when one skin-specific resource group is unavailable.

11. Validation Posture

Reviewers and validators SHOULD be able to check at least the following from the example corridor:

  • the prose example does not contradict the machine-readable package,
  • the machine-readable package does not contradict the asset-tree shape,
  • resource paths correspond to the published resource records,
  • dynamic public text is not silently reassigned to state-specific SVG ownership when the realization contract publishes a placement surface instead,
  • fallback posture remains explicit rather than hidden in one runtime loader.

When variant-specific examples exist, validators SHOULD also be able to check:

  • the example identifies its variant posture explicitly,
  • shared class semantics are not rewritten at the variant layer,
  • variant-specific resources and bindings remain inspectable,
  • the example does not silently create a new class split by embodiment alone.

When skin-specific examples exist, validators SHOULD also be able to check:

  • the example identifies its skin posture explicitly,
  • skin-specialized resources remain bounded to realization publication,
  • the example does not silently transfer semantic ownership into style assets or token maps,
  • the example does not silently create a semantic split by visual customization alone.

12. Anti-Patterns

The following example-corridor anti-patterns SHOULD be avoided:

  • an example JSON package that contradicts the example asset tree,
  • an example asset tree that reintroduces runtime-private assumptions not present in the published realization,
  • publishing prose that says a public text surface is dynamic while the example assets still imply that final text is owned by state-specific SVG files,
  • treating examples as disposable illustrations rather than as inspectable publication guidance,
  • letting one runtime sample implementation become the only place where the actual realization logic can be understood,
  • publishing a variant-specific embodiment as if it were automatically a distinct widget class,
  • publishing a skin-specific specialization as if it were automatically a distinct class contract,
  • using example naming that hides whether the example is family-generic, variant-specific, or skin-specific.

13. Summary

The Examples/ corridor of the default realization family exists to keep the publication chain explicit from doctrine to machine-readable package to concrete assets.

A correct example in this directory:

  • aligns with the doctrinal documents above it,
  • aligns with the machine-readable realization package it accompanies,
  • aligns with the concrete asset-tree posture,
  • helps future runtimes implement the realization portably without becoming the owner of widget semantics.

Its preferred posture is:

  • family-level doctrine above,
  • machine-readable realization publication in the middle,
  • concrete assets below,
  • examples proving the whole chain coherently.

This corridor must now also be able to prove a second rule clearly: compatible realization variants and compatible skins are realization-side specialization mechanisms, not automatic class splits.

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

  • Libraries/Realizations/Default/Examples/Button default realization.wfrog.md

That file is the natural next step because this Readme.md now defines the example-corridor rules, and the button example is the first normative proof case for the full doctrine-to-package-to-assets chain, including the first clean opportunity to show bounded variant and skin posture in a concrete publication example.