Skip to content

Commit 418cfa3

Browse files
committed
docs(platform): describe what embedded is and how it differs from the zone
The contract said embedded shares views with the zone and reads org context through the zone's helpers; neither is true. The CSS check's header no longer described /o, and the views rule missed the settings routes.
1 parent fce2966 commit 418cfa3

4 files changed

Lines changed: 15 additions & 6 deletions

File tree

‎.claude/rules/sim-platform-views.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ paths:
44
- "apps/sim/platform/embedded/app/(shell)/{settings,people,integrations,links,home}/**"
55
- "apps/sim/platform/design-system/components/{status,modal,picker,settings-section,search-field,activity-row}/**"
66
- "apps/sim/app/o/*/**"
7+
- "apps/sim/app/o/*/settings/**"
78
---
89

910
# Organization Views

‎.cursor/rules/sim-platform-views.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: "One pattern per job across the organization views (Settings, People, Integrations, Links, Home)"
3-
globs: ["apps/sim/platform/embedded/app/(shell)/{settings,people,integrations,links,home}/**","apps/sim/platform/design-system/components/{status,modal,picker,settings-section,search-field,activity-row}/**","apps/sim/app/o/*/**"]
3+
globs: ["apps/sim/platform/embedded/app/(shell)/{settings,people,integrations,links,home}/**","apps/sim/platform/design-system/components/{status,modal,picker,settings-section,search-field,activity-row}/**","apps/sim/app/o/*/**","apps/sim/app/o/*/settings/**"]
44
---
55

66
<!-- Generated from .claude/rules/sim-platform-views.md by `bun run skills:sync`. Edit the source, not this file. -->

‎apps/sim/platform/AGENTS.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Platform design contract
22

3-
Applies to this independent Next.js application. In this tree “EMCN” means the Sim Platform design system in `design-system/`. The existing app and `packages/emcn` remain isolated. For new work or design drift, run the repository's `$implement-platform` skill. Its Paper companion is `$sim-paper-design`. Never import the legacy app, styles, chrome, business logic or providers across this boundary. Real data crosses only through the [data seam](#phase-3-data-seam).
3+
Applies to this independent Next.js application, the zone served at `/org`, and to `design-system/`. `embedded/` is not part of that application; it has [its own section](#embedded-in-the-organization-surface). In this tree “EMCN” means the Sim Platform design system in `design-system/`. The existing app and `packages/emcn` remain isolated. For new work or design drift, run the repository's `$implement-platform` skill. Its Paper companion is `$sim-paper-design`. Never import the legacy app, styles, chrome, business logic or providers across this boundary. Real data crosses only through the [data seam](#phase-3-data-seam).
44

55
## Ownership
66

@@ -74,7 +74,13 @@ Gates live on the server and arrive as data. Hiding an entry is navigation, not
7474

7575
## Embedded in the organization surface
7676

77-
The main app's `app/o/[organizationId]/` also mounts these views, on routes flag-off organizations still use. That route is the only legacy code that may import `@/platform/*`; `check:platform-css` holds every other entry out. Whatever needs legacy chrome (`WorkspaceChrome`, the legacy composer, Search's source cards) lives in `platform/embedded/`, which holds the organization surface's own views and data and which the zone never imports. A view shared by both takes what differs as props or slots. `lib/data` modules read `useOrganization()`, which the host's layout fills from the same surface read this app makes, with `routePrefix` set to `/o/<id>`, so `surfaceHref` and `legacyRoutes` serve both. Notices go through `usePlatformNotices`, which a host may redirect, and `PlatformSurface` collapses inside another, so a part can wrap itself when it alternates with legacy chrome.
77+
`embedded/` holds the organization views and their data (`embedded/app`, `embedded/lib`). It is not a Next app and has no pages: the main app's `app/o/[organizationId]/` routes mount it, for every organization, whatever the `platform-org-ui` flag says. An edit here ships in the main app's build. It is built on the host, not on this project: it imports the host's hooks, stores, providers and packages, legacy chrome included (`WorkspaceChrome`, the legacy composer, Search's source cards), and the data seam and seam closure do not apply to it. `check:boundaries` sets its own seam: views read data through `embedded/lib/data`, and that layer points away from views and routes.
78+
79+
The zone and `embedded/` share only `design-system/`. Neither imports the other, not even for a type (`check:platform-design` rule `zone-embedded`, `check:boundaries` rule 7), so a change to a view here does not change the zone, and a similar view in each is two views. `app/o` is the only legacy code that may import `@/platform/*`, and only those two trees; `check:platform-css` holds every other entry out, and `check:platform-design` holds `app/o` out of the zone.
80+
81+
Org context comes from a different place in each. A view here calls `useOrganization()` from `@/lib/organizations/provider`, which the `app/o` layout fills from `getOrganizationSurfaceContext`. The zone calls its own from `@/platform/lib/data/organization`. `surfaceHref`, `legacyRoutes` and `routePrefix` are the zone's and do not exist here: a link here is a host route (`@/lib/navigation/paths`). Each tree has its own `usePlatformNotices`. `PlatformSurface` collapses inside another, so a part can wrap itself when it alternates with legacy chrome.
82+
83+
The design rules in this contract hold here too. `check:platform-design` walks `embedded/`, excepting its imports of the host and the host tokens it names, and counts what predates that per file and rule in the shrink-only `scripts/check-platform-design.baseline.json`.
7884

7985
## Product UI and desktop
8086

‎scripts/check-platform-css.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
#!/usr/bin/env bun
22
/**
3-
* Proves the embedded design system cannot change a legacy page.
3+
* Proves the design system, which `app/o` loads for every organization, stays inside what it styles.
4+
* It restyles `/o` itself, which is the point; nothing here protects that page's legacy chrome except
5+
* the `[data-platform-ui]` scope. It cannot reach a page outside `/o`, or that scope's outside on one.
46
*
5-
* Next keeps route CSS loaded after client navigation, so one global rule from a flagged page keeps
6-
* applying on every legacy page the viewer opens afterwards. Three rules hold that line:
7+
* Next keeps route CSS loaded after client navigation, so one global rule from an organization page
8+
* keeps applying on every other page the viewer opens afterwards. Three rules hold that line:
79
*
810
* - `entry-escape`: `platform/design-system/styles/embedded.css`, compiled through the app's real
911
* PostCSS config, may only contain selectors under `[data-platform-ui]` and `@font-face` faces

0 commit comments

Comments
 (0)