@atomazing-org/design-system 2.0.1 → 3.7.2

package/AGENTS.md

@@ -0,0 +1,92 @@
+# @atomazing-org/design-system Agent Rules
+
+These instructions apply when a repository depends on `@atomazing-org/design-system`
+or when an AI agent is asked to integrate, upgrade, or refactor work around this library.
+
+## Source Of Truth
+
+- `README.MD`
+- `migrations/docs/migrations/design-system/shared/WORKING-RULES.md`
+- `migrations/skills/design-system-consumer-agent/SKILL.md`
+- `migrations/skills/design-system-migration-agent/SKILL.md`
+
+If you are working inside `examples/next-app-router`, load
+`examples/next-app-router/AGENTS.md` and treat it as the local source of truth for
+that starter.
+
+## Default Integration Rules
+
+1. Use only public imports:
+   - `@atomazing-org/design-system`
+   - `@atomazing-org/design-system/presets`
+2. Do not deep-import internal files from `src/*`, `dist/*`, or private folders.
+3. Use `ThemeProviderWrapper` as the app-level design-system entrypoint.
+4. Use `useThemeSettings()` for theme and dark-mode UI state instead of parallel custom state.
+5. Prefer:
+   - `defaultThemes` for standard application surfaces
+   - `landingPageThemes` for landing and marketing surfaces
+   - `allBuiltInThemes` only when the consumer intentionally wants both packs
+6. Custom presets must use the `ThemePreset` contract with both light and dark schemes.
+7. Do not create a competing root `ThemeProvider` unless it is a thin wrapper around the design system.
+8. For SSR and Next.js:
+   - keep the provider in a client boundary
+   - do not access `window`, `document`, or `localStorage` at module scope
+9. After dependency, provider, or theme-state changes, the app must still boot in a real browser without startup console errors.
+10. Fix duplicated runtime singleton warnings for `react`, `react-dom`, `@emotion/react`, or `@emotion/styled` before closing migration work.
+11. The active preset must own the application background.
+12. Do not hardcode page-level backgrounds on app shells, route layouts, or page wrappers when that overrides the preset background.
+13. Prefer direct MUI primitives or thin wrappers around them for base controls.
+14. Do not preserve consumer-owned substitute atoms for stock MUI controls unless they carry real custom behavior.
+15. Visible application text should be rendered through `Typography` with an explicit semantic variant.
+16. When MUI interactive controls render visible text, wrap that text in `Typography component="span"` instead of leaving raw text nodes in place.
+17. Shared dialogs, drawers, and bottom sheets must expose stable `aria-labelledby` and `aria-describedby`.
+18. Shared overlay close actions must have explicit accessible labels.
+19. Search overlays that own keyboard-filtered results should use `combobox` and `listbox` semantics.
+20. Browser event listeners belong in effects with cleanup, not render paths or module scope.
+21. Keep preset selection explicit in one app-owned theme module.
+22. Remove zero-value wrappers that only rename a stock MUI primitive or surface.
+23. Use theme helpers such as `alpha()` instead of palette-string alpha suffix hacks.
+24. Decorative gradients and shadow styling do not belong in normal consumer surfaces.
+25. If several app pages share the same workflow shell, extract one shared layout contract.
+26. If local app barrel exports introduce circular chunk warnings, use direct local imports instead.
+27. Fix consumer-owned build warnings with config changes, not warning suppression.
+
+## Generic Landing Principles
+
+Apply these rules when working on landing-style consumers in general:
+
+1. Use `landingPageThemes` intentionally for landing and marketing surfaces.
+2. Let the active preset own the page background.
+3. Keep one primary focus per major section.
+4. Keep scroll natural; avoid forced snap or automatic section scrolling.
+5. Prefer product-facing labels over template-facing labels in visible UI.
+6. Do not recreate preset-owned surface styling in app components.
+7. Prefer MUI-native composition over custom decorative UI logic.
+8. Do not build nested rectangular surface hierarchies.
+9. Keep landing content concise and easy to scan.
+
+## When To Propose A Migration
+
+Propose a route-based migration before making piecemeal edits if any of the following are true:
+
+- the app uses `@material-ui/*`
+- the app already has a custom theme or token layer
+- the app has widespread hardcoded UI tokens that should move to theme values
+- the user asks to adopt, align, standardize, upgrade, or replace the current UI foundation
+- partial integration would leave two competing sources of truth for theme state
+- the app hardcodes root-level page backgrounds that should instead come from the active preset
+
+## Route Selection
+
+- `@material-ui/*` found in dependencies or imports: use `mui4-to-latest`
+- no existing theme or token migration is needed: use `greenfield`
+- otherwise: use `adopt-existing`
+
+## Required Migration Response
+
+When migration is the correct path, the agent should:
+
+1. Say that route-based migration is recommended instead of ad hoc edits.
+2. Name the selected route and why it applies.
+3. Load `migrations/skills/design-system-migration-agent/SKILL.md`.
+4. Use the runbook and shared gates from `migrations/docs/migrations/design-system/`.