ENGAGE-243

Author: cryptalith

AGENTS.md

@@ -0,0 +1,25 @@
+# Orcid Angular — Agent Notes
+
+Monorepo: main app (`src/`, project `ng-orcid`), docs (`projects/orcid-ui-docs`), and libraries. Use this for fast orientation.
+
+> **Note for future agents:** This file is intended to be edited over time. Any section—relevant or not—may be updated, trimmed, or reorganized so the document stays lean and useful for future agents. Prefer keeping only what helps the next AI work effectively with this project.
+
+## Quick reference: libraries
+
+- **@orcid/ui** — `projects/orcid-ui` — Agnostic UI components, design tokens, modal shell. See `projects/orcid-ui/AGENTS.md`.
+- **@orcid/registry-ui** — `projects/orcid-registry-ui` — Registry-specific components (e.g. import-works-dialog). See `projects/orcid-registry-ui/AGENTS.md`.
+
+Both are path-mapped from repo root (`tsconfig.json`). Main app and docs consume them from source.
+
+## When changing a library component’s API
+
+Update the main app and that component’s doc page (usage snippet, inputs list, examples). 
+
+## If component styles differ between docs and main app
+
+If a library component (e.g. in orcid-registry-ui) looks correct in the docs app but wrong in the main app (e.g. missing margins or spacing), try **resetting the main project**: clean build artifacts, reinstall, or reset local overrides. Stale or inconsistent build/cache state in the main app can cause component styles to not apply as in docs; a fresh build often resolves it.
+
+
+## Dialogs and async data
+
+When a dialog or view needs data from an HTTP (or other async) call, opening the dialog only after the request completes can feel slow. Consider opening the dialog **immediately** with skeleton or static data (e.g. labels, empty lists, or a `loading: true` flag), then assigning the full payload to the dialog’s component instance when the observable emits. The dialog can show placeholders or a loading state until then.

projects/orcid-registry-ui/AGENTS.md

@@ -16,6 +16,7 @@ This package (`projects/orcid-registry-ui`, published as `@orcid/registry-ui`) c
 - **Components**: `projects/orcid-registry-ui/src/lib/components/**`
 - Prefer **standalone components**. Use `@orcid/ui` for base primitives (modals, action surfaces, etc.) and **orcid-tokens** CSS variables for layout/color/typography.
 - Dialogs that use the shared modal chrome should use `OrcidModalComponent` and `ORCID_MODAL_DIALOG_PANEL_CLASS` from `@orcid/ui` when opening with `MatDialog`.
+- **Dialog data (MAT_DIALOG_DATA):** If the host may open the dialog first and assign full data later (e.g. after an async request), the data interface can include an optional flag (e.g. `loading?: boolean`) so the dialog can show a skeleton or placeholder until the host sets the complete data.
 
 ## Dependencies
 
@@ -26,6 +27,10 @@ This package (`projects/orcid-registry-ui`, published as `@orcid/registry-ui`) c
 
 - From repo root: `ng build orcid-registry-ui` (or use the npm script if defined).
 
+## When changing this library’s API
+
+If you add or change **inputs**, **data types**, or **public behavior** in a registry-ui component, update **both** the main app usage (under `src/`) and the component’s doc page (usage snippet, inputs list, examples) so they stay in sync.
+
 ## Docs site (`projects/orcid-ui-docs`)
 
 Registry-ui doc pages live under **`src/app/pages/orcid-registry-ui/`** (orcid-ui pages live under `pages/orcid-ui/`). When adding a new registry-ui component doc:

projects/orcid-ui/AGENTS.md

@@ -23,7 +23,7 @@ Use this document as a fast orientation and a checklist for making safe, consist
   - `projects/orcid-tokens/tokens.scss` (SCSS source-of-truth)
   - `projects/orcid-tokens/tokens.css` (CSS variables used by apps/docs)
   - `projects/orcid-tokens/tokens.json` (structured token map)
-- Keep `projects/orcid-ui-docs` updated with a docs page + route + sidebar link.
+- Keep `projects/orcid-ui-docs` updated with a docs page + route + sidebar link. When you **change a component’s API** (inputs, data types, public behavior), update the main app (or other consumers) and that component’s doc page (usage snippet, inputs list, examples).
 - Verify builds:
   - `npm run build:tokens`
   - `npm run build:ui`
@@ -43,6 +43,10 @@ Use this document as a fast orientation and a checklist for making safe, consist
 - Some SCSS (typography/theme helpers) imports token SCSS.
 - Prefer token variables over hard-coded colors/sizes.
 
+### Loading and placeholder states
+
+- Prefer existing **skeleton/placeholder components** from this library (e.g. `SkeletonPlaceholderComponent`) for loading or empty states so loading UIs stay consistent. Check `public-api.ts` and the docs before adding new spinners or custom placeholders.
+
 ## MCP Figma-to-code workflow used in this repo
 
 When the user provides a Figma URL: