Files

7.6 KiB

name, description
name description
subframe-einbinden Integrate new or changed Subframe pages and David design deltas into HiveGrid through a screen inventory, Soll/Ist comparison, loader/view-model boundaries, demo data, documentation, tests, and staging verification. Use when a user asks to pull, compare, implement, update, or finish Subframe screens, pages, flows, or a tracked design-nachzug.

Subframe einbinden

Integrate Subframe design artifacts into the existing HiveGrid application. Treat exported pages as design input, not drop-in application code.

1. Read the current contracts

Read before planning or changing code:

  1. AGENTS.md and the relevant ticket doc.
  2. .planning/SUBFRAME-FLOW-INVENTAR.md for the current flow/page integration state.
  3. .planning/INTERIM-UI-PLAYBOOK.md for app-shell, scrolling, local-kit, layer, and tracking rules.
  4. .planning/INTERIM-UI-DESIGN-STANDARDS.md for spacing, controls, dialogs, states, and copy.
  5. .planning/INTERIM-HANDOVER-GUIDE.md only when an interim-to-David handover is in scope or must be offered.

If a Subframe MCP or product-specific design skill is available, load its required instructions before calling it. Keep this HiveGrid workflow authoritative for repository integration.

2. Establish an isolated branch

Start from current origin/main with the repository session/worktree helper. Keep one flow, or one deliberately bounded flow subset, per branch and PR. Preserve unrelated dirty worktrees.

Do not push, write Plane, or mutate Subframe without the user's authorization.

3. Inventory the Subframe target

Remember that .subframe/sync.json and component sync cover components, layouts, and theme under apps/web/app/ui; they do not import complete pages or application wiring.

Use the available Subframe integration in this order:

  1. Call list_flows.
  2. Call get_flow_info for the selected flow and page inventory.
  3. Call get_page_info for each relevant page individually.
  4. Exclude pages explicitly marked _backlog_ unless the user includes them.
  5. Record each screen's visible fields, filters, actions, states, dialogs, navigation, and responsive variants.

Use project f023064a5ca0 only when it remains the configured project in .subframe/sync.json; otherwise use the current configured project. Avoid loading huge page exports wholesale during inventory when a structural/text extraction is sufficient.

4. Build the Soll/Ist delta

Inspect existing routes, loaders/actions, screens, view models, services, permissions, Prisma models, tests, demo data, and current ticket ownership.

For each design page, classify:

  • already integrated and current
  • visual delta only
  • needs loader/view-model/route-operation support
  • lacks backend capability and must remain an explicit rest delta
  • backlog or out of scope

Never invent backend behavior to make a design control appear functional. Wire every visible action to an authorized capability, remove it, or render it disabled with a documented reason. Respect ticket ownership and dependency boundaries.

Before implementation, present the per-screen Soll/Ist delta, affected files/layers, test plan, and remaining unsupported design delta. Ask for approval when the user has requested planning or the implementation scope is not already explicit.

5. Integrate behind the application boundary

Place app-chrome-free screens under apps/web/app/components/screens/<domain>/, with dialogs in a local dialogs/ folder when useful. Follow these rules:

  • Routes own useLoaderData, useSubmit, fetchers, CSRF handling, redirects, and loader/action wiring.
  • Screens receive view models and action callbacks as props.
  • Never nest ~/ui/layouts/DefaultPageLayout or another generated sidebar/header inside the HiveGrid app shell.
  • Never import packages/ui-subframe directly from routes.
  • Never import Prisma or ~/db into packages/ui-app/**.
  • Preserve host-aware paths for admin, app, and portal surfaces.
  • Format dates and times through HiveGrid locale helpers with the configured application timezone.
  • Put every user-facing string in de/en i18n files; edit translation JSON surgically.
  • Keep rendering deterministic: no render-time Math.random(), Date.now(), or unscoped locale formatting.

Use existing Automation and Forms screens plus Settings Subscription/Billing interim screens as implementation references. Verify actual local component APIs under apps/web/app/ui/**; cloud exports may use different props.

6. Apply the known Subframe footguns

  1. Document flow: Remove page-export roots that combine h-full/overflow-hidden with basis-0/inner overflow-y-auto where they collapse inside the app shell. Register new screens in subframe-layout-boundary.test.ts.
  2. Single app shell: Keep sidebar, header, and breadcrumbs owned by HiveGrid routes/layouts.
  3. Local kit first: Read local SearchInput, table, badge, dropdown, and dialog APIs instead of trusting cloud-export props.
  4. Title contract: Return data.title and the route meta needed by breadcrumbs and the browser tab.
  5. Timezone: Use useLocaleFormatters() or the canonical server formatter.
  6. i18n: Add de and en keys without JSON round-tripping or defaultValue workarounds.
  7. Host-aware navigation: Derive redirects/links from the current surface or use the canonical path helper.
  8. No dead controls: Wire, remove, or explicitly disable every exported placeholder handler.
  9. Schema changes: Keep changes additive and module-scoped; follow the current AD-21 and pre-merge migration gates in docs/AGENT-CHECKLIST.md.

Treat .planning/INTERIM-UI-PLAYBOOK.md as the maintained source for newer footguns.

7. Provide representative demo data

When the integrated screens depend on demo states, update scripts/seed-hivegrid-demo.ts with deterministic IDs, isDemoData: true, and idempotent upserts. Cover relevant populated, empty, warning, and error states. Run the seed twice against the approved disposable local database and prove the second run is stable.

Do not expand seed or schema scope merely to imitate unsupported design behavior.

8. Update tracking and documentation

In the same implementation change:

  • Update .planning/SUBFRAME-FLOW-INVENTAR.md with page count, status, date, integrated delta, and explicit rest delta.
  • Update the owning ticket doc with date, proof, DoD progress, and design follow-up state.
  • Add dependency-aware cross-reference notes to affected owner tickets when required by AGENTS.md.
  • Record reusable new footguns in .planning/INTERIM-UI-PLAYBOOK.md.
  • Keep /planning authoritative for design-nachzug; Plane mirrors it only after identity verification and authorization.
  • Offer, but do not silently create, the David handover artifacts described in .planning/INTERIM-HANDOVER-GUIDE.md when an interim screen was added.

9. Verify end to end

Run the applicable gates from docs/AGENT-CHECKLIST.md, including:

  • affected workspace typechecks and lint
  • targeted screen, route, loader/action, and view-model tests
  • subframe-layout-boundary.test.ts
  • i18n and hardcoded-string gates
  • smoke, hot-swap, accessibility, and visual-baseline checks required by the ticket
  • seed idempotency when demo data changed
  • migration/RLS gates when schema changed

After an authorized merge and deployment, verify the affected staging screens in a real browser: content must be visibly rendered, breadcrumbs and titles must be correct, actions must work, responsive states must hold, and the console must be free of hydration errors.

Report what was integrated and list every remaining design/backend delta explicitly.