|
1 | 1 | --- |
2 | 2 | name: implement-platform |
3 | | -description: Implement or review Sim’s code-first Platform in apps/sim/platform, including real product routes, colocated components, shared EMCN controls, responsiveness and Paper state references. Use on new work, migration, drift review or resumption; not for the legacy UI. |
| 3 | +description: Build, change, consolidate, remove, or review Sim Platform UI in apps/sim/platform. Use for code-first product routes, EMCN components, Paper handoff and design drift in the isolated Next app. |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # Implement Sim Platform |
7 | 7 |
|
8 | | -Read `apps/sim/platform/AGENTS.md` first. It is the canonical ownership and code contract. Follow `$sim-paper-design` for live Paper locations, design rules and continuity; use its references, not a remembered native ID. If the skill or live Paper is unavailable, verify what is possible locally and explicitly identify what remains unverified. Do not invent missing designs. |
| 8 | +Start in the Sim checkout containing the requested product work. Read the [Platform contract](../../../apps/sim/platform/AGENTS.md) and [component ownership map](../../../apps/sim/platform/docs/component-ownership.md). These versioned files carry the current rules into a fresh chat. Use the [Platform README](../../../apps/sim/platform/README.md) for the local routes, fixture states, generators, and verification commands. |
9 | 9 |
|
10 | | -1. **Scope the phase.** Foundations, recipes and evidence are Phase 1. Approved product screens and their unique parts are Phase 2. Route integration, persisted state and authorization belong to Phase 3. Keep UI-only requests isolated; do not advance phases just to make a demo look real. |
11 | | -2. **Resolve the product change.** Inspect the actual route first. Use the relevant live Paper bases and product states for existing anatomy, theme roles and interactions; a later explicit code-first decision supersedes an older specimen. Keep the checkpoint scoped to the affected states. For a new idea, a real product use is required, a new Paper drawing is not. Exclude Marcus. |
12 | | -3. **Choose one owner.** Use `app/(shell)/<route>/_components/<component>/<component>.tsx` and a sibling CSS Module for unique anatomy. Put shared shell compositions at the nearest common route owner, generic EMCN primitives in `design-system/components/<family>/`, and design roles in foundations. Keep pages style-free. Promote the original owner on second use and update both callers. A gallery alone never justifies a variant. Apply the shared rhythm, icon and hover contract in `apps/sim/platform/AGENTS.md`; compare two real consumers for title and Cancel placement, first-line leading art and centered trailing metadata, opaque type-scaled icons, row hover and compact action gaps. Keep form chrome in Modal. Verify long-content fades on the actual scroll owner at the start, middle and end, then filter or resize until all content fits. |
13 | | - Consult the tracked component ownership map before adding markup. Choose the existing action button, navigable row, two-line activity row, picker, or disclosure by behavior. Render Base UI triggers through their controls. Check a single notice and an expanded stack: the tray owns one control elevation outside its scrolling content. Trace copy/status lifetimes to the shared expiry owner; verify pause, reset, reduced motion and long tooltip limits. Compare Home/Chat reading edges and stable controls across responsive layouts, including structural rules and the actual scroll boundary. |
14 | | -4. **Translate anatomy, not artboard coordinates.** Consult the installed Next docs in `node_modules/next/dist/docs` (especially project structure, CSS, Server/Client Components). Use semantic DOM, native or accessible behaviors, intrinsic size and responsive relationships. A 560px Paper modal is a preferred maximum, not a fixed width. The same modal should fit 647px and 390px viewports without new variants. Use centralized Tailwind roles, the type and material contracts, shared icon geometry and slots. Confirm the rendered DOM has the intended behavior. A searchable field accepts text, a disclosure opens by keyboard, a modal part composes directly, and a table renders the caller’s records. Repeated data takes an array, never a fixed list of numbered specimen props. Register a named native component for these cases. A new size requires a distinct, evidenced use; it isn't a device enum. Never pass styles through a composition. Trace repeated rows to their registered item and preserve the surrounding layout. Accept a typed collection, then render empty, short and longer-than-specimen data to prove that any example count can change. Keep different semantic roles distinct. Wrap Base UI primitives in EMCN when behavior involves floating layers, list navigation, cascading actions or focus management. Main-view and modal dropdowns share the same surface and rows. Preserve the caller’s value, accessible label and form submission through the owner. When editing generated files, change the source contract or compiler and regenerate the affected set. |
15 | | -5. **Exercise the right states.** Build a matrix of actual themes, relevant content sizes, resting, hover, selected, error and disabled states, keyboard navigation, long data, zoom and widths between Paper examples. The workbench is tooling, not a Phase 2 product screen. Entities, including organizations, workspaces, members and chats, come only through the server fixture gate. Render empty or absent data distinctly. Focusing a control or typing in it preserves its resting chrome; verify there is no focus paint on the control or its wrappers. Test keyboard focus and restoration separately. For cascading menus, test hover travel, arrow keys, Escape one level at a time, and bounds at either edge of the viewport and inside a modal. Client interaction may open, dismiss or change steps; no authentication, persistence or network effects. |
16 | | -6. **Prove it.** Run the structural audit against real code, regenerate/check relevant files, render the app in a real browser, and compare rendered geometry, type, icon ink/weight and interactions with the product contract and relevant Paper states. Exercise empty, full, stress and flag-off. Retire unused variants and resolve every affected use. Measure the shell inset against both sides of the footer, the Home greeting against its navigation row, and adjacent chat line boxes across thinking, tools and prose. Compare primary and destructive confirmation lightness changes in both themes. Check that dismissing a recent stays neutral, expand/collapse controls share a height, and message metadata remains visible as the pointer crosses into its toolbar. Keep type roles stable across breakpoints and at browser zoom. Source clock, age and date labels from `platform/lib/time.ts`; verify SSR, rollovers and metric/range controls together. Compare count alignment and notification action placement with existing controls before introducing markup. Verify isolation and the repository gates. Report covered keys/states separately from visual comparisons; record unresolved differences and durable verification paths. Stop at the authorized phase. |
17 | | - |
18 | | -**Product and desktop.** Map the feature to its existing route, feature owner, shared controls and both host compositions. Calendar events or workspace summaries can be unique, while their type, left/stacked text alignment, insets and action menus remain system-owned. Keep one renderer for browsers and Electron: see the Platform contract and `apps/desktop/README.md`. Use the typed preload adapter to detect desktop, leave OS window controls native, and exercise the actual desktop shell with a disposable profile. Cover fullscreen, split/expanded panels, compact takeover and returning to the previous tab. Keep real native execution and persisted resources for Phase 3. |
19 | | - |
20 | | -**Resume:** read the task checkpoint and refresh the specific live node(s) before edits. Merge current work; do not replay an old export. The skill and repo contract are standing policy, not the checkpoint. Keep root, Claude and Cursor directives as pointers to that one policy. |
21 | | - |
22 | | -**Examples:** “implement the workspace issue rows” starts from the Issues contract and registered row plus its actual Use, not a screenshot-derived card. “Add quiet to a button” requires an existing component or product use for that treatment. “Use the workspace item in chat too” is a promotion and import migration, not a second copy. “Preview an org with no workspaces” selects the empty fixture; it never creates a record. |
| 10 | +1. **Establish scope on the real route.** Identify the product entry, interaction, phase, and affected consumers. Phase 1 owns foundations and the library. Phase 2 owns working UI and transient interaction state, with examples supplied through the server fixture flag. Phase 3 connects real data and operations. Reuse the same renderer in the browser and Sim Desktop. Read the installed Next guides for the file structure or framework behavior you are changing. |
| 11 | +2. **Resolve design intent.** For Paper-backed work, use `$sim-paper-design` to locate the live Shared or Platform master and the product states that use it. Exclude Marcus. Preserve the key and theme roles. Treat artboard sizes as reference measurements. For code-first changes, follow the latest explicit product direction and inspect the rendered route. Identify any source you could not verify. Update the Paper canvas when the request includes Paper changes. |
| 12 | +3. **Choose or change the owner.** Start with the behavior. An action, navigation row, value picker, or disclosure has an existing keyboard and pointer contract. Different interactions may share visual roles while retaining different semantics. Use the existing family and named props for a change in size, intent, icon, or content. Put unique anatomy and its CSS beside the route component. Keep page files free of styling. Only EMCN owns the appearance of its controls. Use Base UI there for complex keyboard, floating, and dismissal behavior. |
| 13 | +4. **Trace the full change.** On a second independent feature use, promote the original implementation and migrate both callers. For consolidation, compare semantics, map every consumer to its replacement, then remove the obsolete implementation, export, variant styles, and unused registrations. For deletion, also check menus, preferences, fixture data, workbench references, and tests that existed only for the removed feature. Preserve unrelated consumers and historical Paper evidence. A new variant needs a reachable product use. Edit the source or compiler for generated foundations and recipes. |
| 14 | +5. **Verify where people use it.** Run the design audit and applicable checks from the README. Render the changed product route with empty, full, stress, and fixture-off data as relevant. Check both themes, widths between artboards, long content, text scaling, keyboard, and pointer states. Compare shared controls in their actual consumers. Check the actual scroll edge and the open popup when space is tight. For shell, panel, or desktop work, exercise the real Electron renderer. For substantial implementations and consolidations, use an independent agent during design or implementation and for a final review of the changed owners and routes. Provide the working localhost route for visual review. |
| 15 | +6. **Keep decisions durable.** Follow the contract’s maintenance guidance when an approved correction changes a shared rule. Record feature-specific decisions with their feature. For sustained work, keep a task checkpoint with the code revision, verified states, evidence, and outstanding work. Include the branch or PR, checkpoint path, and localhost route in a handoff. On resumption, compare the checkpoint with the current branch, working tree, and relevant live sources before acting. |
0 commit comments