Puck page design and TailAdmin-style React customization
Current page-design workflow
In the Builder design workspace, select the target User Type, menu, or shared page; use Puck for normal page composition or Monaco for reviewed advanced JSON; preview the result; save the draft; validate it; and publish it. Role preview explains presentation differences, but server authorization remains authoritative for all data and actions.
CSS ownership and import order
The tenant runtime loads @buildwithhq/ui/professional.css before its local styles.css. Shared professional primitives and their states belong in packages/ui; application-shell tokens and app-specific overrides belong in the tenant runtime. Keep the cascade explicit so a template can change color, typography, density, radius, and shadow without duplicating module behavior.
For a single SaaS, App Assets provides a Custom CSS window. It previews UTF-8 CSS and publishes a validated public theme.css; the runtime activates the latest public stylesheet for that app. Published CSS may reference relative URLs, fragments, or public assets under that same SaaS app's asset prefix. It cannot contain imports, executable URL schemes, legacy scriptable CSS expressions, embedded HTML, or cross-app remote asset URLs.
SaaS asset hosting
App Assets accepts a builder-selected virtual folder such as brand/images and can expose explicitly public files at https://assets.buildwithhq.com/{saasAppId}/{assetId}. The appliance operator alone configures the physical BWHQ_FILE_STORAGE_ROOT; neither the browser nor page JSON receives a disk path. All filename extensions except .dll, .com, and .exe may be stored, but only validated stylesheets and passive image, video, font, and PDF content render inline. Other types download as inert attachments with browser hardening. DNS, TLS, and proxy routing for the asset host are deployment responsibilities.
React ownership
Reusable visual primitives belong in packages/ui/src/professional-primitives.tsx. Native module list, detail, create, edit, archive, and other lifecycle experiences remain owned by their module React implementation and exact typed API routes. Puck owns page composition and bound blocks; it does not replace secured module lifecycle routes with inert mock controls.
Adapting TailAdmin
Treat a licensed TailAdmin source as a visual reference. Map its colors and spacing into BuildWithHQ tokens, translate repeated patterns into shared primitives, use the bounded icon registry, and preserve BuildWithHQ routing, identity, bindings, permissions, error handling, and stored-procedure-backed application services. Do not copy TailAdmin navigation or authentication logic over the runtime shell.
Page-by-page finish standard
Polish shared primitives first, then the shell, dashboards, high-use list pages, detail pages, create/edit forms, and secondary states. Every user-managed first-class entity must retain create, view, update, and safe removal behavior. Exercise empty, loading, populated, validation-error, permission-denied, stale-write, and successful-mutation states at desktop and mobile widths.
Publishing templates
Complete and route-test the working SaaS application before harvesting it. Template publishing captures an exact reviewed version; installed customer copies remain isolated from later upstream edits until an explicit upgrade.
The current template-pack member contract does not copy SaaS asset bytes or remap a source app's asset URLs into an installed app. Public URLs are immutable and work for the source SaaS, but an asset-dependent template is not yet a self-contained portable install. Do not represent it as portable until exact-version asset packaging, destination upload, fingerprint verification, and page/CSS URL remapping are implemented and tested.
Step-by-step guide
Use Host SaaS CSS, logos, images, and design assets for the builder workflow and Deploy the SaaS asset domain and storage root for appliance configuration. Apply a TailAdmin-style design and customize every React page covers the wider setup, editing, responsive verification, lifecycle testing, harvesting, and publishing procedure.