180 lines
7.6 KiB
Markdown
180 lines
7.6 KiB
Markdown
---
|
|
name: subframe-einbinden
|
|
description: 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.
|