Frontend Contract: Start Here

This page is an orientation guide and navigation reference. It identifies the contracts a frontend module must follow; it is not a build tutorial or a complete application example.

Wippy frontend modules are portable by default. A module must continue to work when it is imported into another Wippy project whose facade supplies a different compliant PrimeVue theme and no project-private CSS.

Choose the correct path

1. Use a view.page for an application rendered by the configured page engine: a legacy about:srcdoc iframe or a Web Fragment.
2. Use a view.component for a custom element rendered in the host document, normally with a shadow root.
3. If the UI renders a button, input, form field, menu, overlay, or another PrimeVue-like control, use PrimeVue unless it cannot provide the required semantics and affordance.
4. A content-only component, such as a Chart.js visualization with no controls, may omit PrimeVue and Tailwind.
5. If a custom control is necessary, follow the Portable UI Contract and Custom Composites.

PrimeVue is the shared component vocabulary. The Wippy Tailwind preset is a supported build-time vocabulary. Only utilities documented as runtime-backed remain responsive to facade theme changes after compilation.

Ownership map

module source
  -> build command
  -> emitted artifact
  -> registry owner
  -> served URL
  -> Web Host
  -> page surface (srcdoc iframe or Web Fragment) or component shadow root
  -> AppConfig / router / theme delivery

Do not infer one stage from another. Before debugging a missing asset, identify the source package, build target, emitted file, registry entry, filesystem mount, and served URL.

Contract pages

• Platform Topology: runtime boundaries, routing, CSS delivery, overlays, and ownership.
• Portable UI Contract: normative component and styling rules.
• Theme Authoring: what belongs in facade custom_css, PrimeVue theme CSS, or a module.
• Tailwind Contract: runtime-backed utilities versus compiled constants.
• Token Catalogue: generated token reference and provenance.
• The Design Layer: where something belongs when several of your own modules need it and the theme has no component for it.
• Page Recipe and Web Component Recipe.
• Build and Dependency Contract.
• Configuration and Casing.
• Compliance Rule Index.

Non-negotiable checks

• Never invent a PrimeVue prop, component API, CSS variable, or Tailwind semantic utility. Verify it in the selected package source and generated catalogue.
• Never construct a --p-* token name by analogy.
• Never require an arbitrary facade class from a portable module.
• Never infer host route context from browser location. Pages receive host context through AppConfig and use @wippy-fe/router.
• Rebuild the exact owning package into the served output before browser verification.
• Verify the browser console after navigation and material interaction.

Project-bound modules are outside the portable contract. They are documented only on the Unsupported Project-Bound Modules page; standard compliance returns UNSUPPORTED and standard CI fails.