Agent Guide

my-app/
  AGENTS.md
  package.json
  src/

my-monorepo/
  apps/
    web/
      AGENTS.md
      package.json

# EnterUI Agent Instructions

This project uses EnterUI as its primary UI component system.

## Source of truth

Use the EnterUI docs before creating custom UI:

- Installation: https://design.frogg.id/enter-ui/docs/installation
- Components: https://design.frogg.id/enter-ui/docs/components/button
- Theming: https://design.frogg.id/enter-ui/docs/theming
- Accessibility: https://design.frogg.id/enter-ui/docs/accessibility
- Agent Guide: https://design.frogg.id/enter-ui/docs/resources/agent-guide
- Changelog: https://design.frogg.id/enter-ui/docs/resources/changelog
- SolidJS: https://design.frogg.id/enter-ui/docs/solidjs

If web access is unavailable, inspect local package exports, TypeScript
declarations, and existing usage of `@froggdesign/enter-ui-react`.

SolidJS consumers should use `@froggdesign/enter-ui-solid`. The SolidJS
renderer currently includes stateless and presentational primitives for core,
forms, feedback, layout, content, toolbar, and wizard progress surfaces.

## Package contract

- Import components only from `@froggdesign/enter-ui-react`.
- Import styles from `@froggdesign/theme/styles.css` before `@froggdesign/enter-ui-react/styles.css`.
- In SolidJS apps, import components only from `@froggdesign/enter-ui-solid`
  and styles from `@froggdesign/enter-ui-solid/styles.css`.
- Do not deep-import from package internals.
- Do not fork, copy, or modify EnterUI package source inside the consuming app.
- Do not recreate primitives that EnterUI already exports.
- Tailwind is not required.
- The public contract includes exported component names, props, `@froggdesign/enter-ui-react/styles.css`, `.eui-*` classes, and documented `--eui-*` CSS variables.

## Design stance

- Build product interfaces, not component catalogs.
- Use EnterUI defaults first. They are intended to look finished without heavy overrides.
- Keep neutral surfaces dominant. Use green only for small brand or state signals.
- Prefer practical product patterns: dashboards, settings, data operations, release workflows, internal tools, SaaS screens, and docs interfaces.
- Avoid decorative gradients, orbs, large empty hero sections, and one-off local styling systems.
- Do not create nested card layouts. Use sections, panels, lists, tables, and layout primitives deliberately.

## Install and import

```sh
pnpm install @froggdesign/enter-ui-react @froggdesign/theme
```

```tsx
import "@froggdesign/theme/styles.css";
import "@froggdesign/enter-ui-react/styles.css";
```

```tsx
import { Button, Card, Input } from "@froggdesign/enter-ui-react";
```

## Component map

Core:
`Button`, `ButtonGroup`, `IconButton`, `Link`, `Card`, `MetricCard`,
`ChartCard`, `Badge`, `StatusIndicator`, `Rating`, `Text`, `List`,
`DescriptionList`, `KeyValueList`, `Alert`, `Avatar`, `AvatarGroup`,
`Separator`, `Divider`, `Tabs`, `Accordion`, and `Disclosure`.

Forms:
`Form`, `FormSection`, `FormActions`, `FormMessage`, `FormDescription`,
`Input`, `PasswordInput`, `NumberInput`, `Stepper`, `StepperForm`,
`StepperFormStep`, `StepperFormActions`, `TextArea`, `Label`, `Field`,
`FormField`, `FieldDescription`, `FieldError`, `Fieldset`, `FieldsetLegend`,
`FieldsetDescription`, `FieldsetError`, `ValidationSummary`, `CurrencyInput`,
`MaskedInput`, `URLInput`, `Checkbox`, `RadioGroup`, `RadioGroupItem`,
`Switch`, `Select`, `Combobox`, `Autocomplete`, `MultiSelect`, `TreeSelect`,
`InlineEdit`, `EditableText`, `MentionInput`, `RichTextEditor`, `TagsInput`,
`TokenInput`, `FileUpload`, `Dropzone`, `OTPInput`, `PinInput`, `TimeInput`,
`InlineStatusSelect`, `ToggleGroup`, `Slider`, `DatePicker`, `DateInput`,
`DateRangePicker`, `DatePresetPicker`, `DateTimePicker`, `Calendar`,
`CalendarView`, `AgendaList`, `CronInput`, `RecurrenceEditor`,
`ResourceCalendar`, `MonthPicker`, `YearPicker`, `ColorPicker`, and
`SegmentedControl`.

Overlays and menus:
`Dialog`, `ConfirmDialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`,
`HoverCard`, `DropdownMenu`, `ContextMenu`, `MenuBar`, `NavigationMenu`, and
`CommandMenu`, plus `OverlayProvider` and `useOverlayManager` for shared
overlay stack coordination.

Data and feedback:
`Table`, `TableContainer`, `TableHeader`, `TableBody`, `TableFooter`,
`TableRow`, `TableHead`, `TableCell`, `TableCaption`, `TableEmptyState`,
`DataTable`, `DataView`, `ColumnVisibilityMenu`, `SavedViews`,
`SavedViewTabs`, `SortMenu`, `DensityToggle`, `BulkEditPanel`, `Meter`,
`Gauge`, `Sparkline`, `LineChart`, `AreaChart`, `StackedBarChart`, `Heatmap`,
`TrendIndicator`, `ComparisonMetric`, `BarChart`, `DonutChart`, `Legend`,
`Skeleton`, `Spinner`, `Toast`, `Toaster`, `ToastProvider`, `useToast`,
`useToaster`, `LiveRegion`, `AnnouncerProvider`, `Announcer`, `useAnnouncer`,
`RelativeTime`, `TimeAgo`, `Progress`, `Banner`, `EmptyState`,
`ActivityFeed`, `ActivityTimeline`, `Timeline`, `TimelineDetail`,
`ReleaseStepper`, `KanbanBoard`, `TransferList`, `DualListBox`,
`CommentThread`, `CommentItem`, `CommentComposer`, `LogViewer`, `JsonViewer`,
`DiffViewer`, `PermissionMatrix`, `RolePicker`, `FeatureFlagToggle`,
`EnvironmentBadge`, `ApiKeyField`, `SecretInput`, and `WebhookEndpointCard`.
Use `JsonViewer` for collapsible JSON trees with copy, metadata, and explicit
`ariaLabel` instead of building custom `<pre>` inspectors.

Layout and product UI:
`Header`, `Sidebar`, `AppShell`, `SplitView`, `PageHeader`, `SectionHeader`,
`Container`, `Spacer`, `VStack`, `HStack`, `ZStack`, `Grid`, `LazyVGrid`,
`LazyHGrid`,
`WorkspaceSwitcher`, `AppSwitcher`, `Toolbar`, `DataToolbar`, `FilterBar`,
`ToolbarGroup`, `ToolbarButton`, `TreeView`, `VirtualList`,
`ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`, `WizardSteps`,
`StepperProgress`, `NavLink`, `Breadcrumb`, `Pagination`, `PageTabs`,
`RouteTabs`, `SearchInput`, `ScrollArea`, `AspectRatio`, `Media`,
`CopyButton`, `CodeBlock`, `Kbd`, `SkipLink`, and `VisuallyHidden`.

Account and detail:
`UserMenu`, `NotificationCenter`, `DetailPanel`, `ObjectDetail`, and
`AuditLog`.

Forms and settings:
`FormLayout`, `FormLayoutSection`, `SettingsSection`, and `SettingsRow`.

Billing and metrics:
`StatGrid`, `KPISection`, `MetricCard`, `ChartCard`, `UsageMeter`, and
`PlanUsage`.

Files and attachments:
`FileList` and `AttachmentList` (alias of `FileList`).

Enterprise / admin:
`PermissionMatrix`, `RolePicker`, `FeatureFlagToggle`, `EnvironmentBadge`,
`ApiKeyField`, `SecretInput`, `WebhookEndpointCard`, `LogViewer`,
`JsonViewer`, and `DiffViewer`. Use these on settings and ops surfaces —
RBAC editors, env switchers, dev-tooling pages, audit views, integration
admin.

Sub-parts such as `DialogTitle`, `ConfirmDialogAction`, `SelectItem`,
`ComboboxItem`, `DropdownMenuItem`, `ContextMenuItem`, `CommandMenuItem`,
`BannerTitle`, `ToastViewport`, `BreadcrumbPage`, `PaginationNext`,
`TreeItemTrigger`, and `AppShellMain` are exported from the same public entry
point.

## Styling rules

- Prefer EnterUI props and CSS variables before custom CSS.
- Use `@froggdesign/theme` tokens for durable color, spacing, radius, shadow,
  focus, and typography decisions.
- Keep custom styles scoped to the consuming app.
- Do not globally override `.eui-*` classes unless the project has a documented
  theme layer.
- Use `className` for local composition. Do not rely on private DOM structure.

## Accessibility rules

- Preserve built-in keyboard behavior, focus management, labels, descriptions,
  IDs, and ARIA wiring.
- Use `FormField`, `FieldDescription`, and `FieldError` for form controls.
- Provide visible labels or `aria-label` for icon-only controls and unlabeled
  inputs.
- Use `DialogTitle` and `DialogDescription` for modal dialogs.
- Preserve semantic focusable children when using `asChild` triggers.

## Next.js App Router rules

- Static EnterUI components can render in Server Components.
- Interactive compositions that own browser state should live in Client
  Components.
- Do not pass function props from Server Components into client-only EnterUI
  components. For example, define `DataTable` columns with `cell` render
  functions inside a Client Component.
- Dialogs, menus, selects, tabs with app state, command menus, popovers,
  tooltips, toasts, sliders, date pickers, and custom form interactions usually
  require a `"use client"` boundary.
- Keep feature logic and data fetching in the consuming app. EnterUI should not
  own app-specific policy.

## Product surface playbook

Reach for these primitives before inventing one-off layouts:

- **Page scaffold:** `PageLayout` for the page grid, `TopBar` for the app
  header, and `SideNav` or `NavigationRail` for primary navigation. Pair with
  `AppShell` only when the entire app needs a persistent shell.
- **Data table surfaces:** `DataGrid` for selectable / sortable tables, with
  `BulkActionBar` for selection actions, `FilterBuilder` for compound filters,
  `EmptySearchResult` for zero-result states, and `SkeletonTable` for loading.
  Use the simpler `DataTable` for read-only tabular data.
- **Account chrome:** `UserMenu` for the avatar dropdown,
  `NotificationCenter` for bell + popover, and `SearchCommand` for the global
  search trigger that opens a `CommandMenu`.
- **Object views:** `DetailPanel` or `ObjectDetail` for single-object detail;
  `AuditLog` for activity / history streams.
- **Forms and settings:** `FormLayout` / `FormLayoutSection` for product forms
  with two-column section layout, `SettingsSection` / `SettingsRow` for
  preferences cards, and `FormField`, `FormActions`, and `Switch` for field
  composition.
- **Feedback states:** `ErrorState`, `ErrorBoundaryFallback`,
  `LoadingOverlay`, `SkeletonForm`, and `SkeletonTable` for stable loading and
  failure states.
- **Metrics and KPIs:** `StatGrid` + `MetricCard` inside a `KPISection` for KPI
  rows. Use `ChartCard` to wrap charts, and use `LineChart`, `AreaChart`,
  `StackedBarChart`, `Heatmap`, `TrendIndicator`, or `ComparisonMetric` for
  compact analytics.
- **Billing:** `UsageMeter` as the primitive, `PlanUsage` as the billing card with reset note + upgrade CTA.
- **Files and comments:** `FileList` (or `AttachmentList`) for uploaded/attached files with progress + error states.
- **Developer / admin viewers:** `JsonViewer` for structured objects, `LogViewer`
  for searchable logs, and `DiffViewer` for change reviews. Prefer these over
  ad-hoc code blocks when the data needs controls, copy, filtering, or collapse
  behavior.

When composing these, prefer placing exactly one `PageLayout` per route, one
`TopBar` per shell, and one `KPISection` per metric block — duplicate landmarks
confuse assistive technology.

## Product homepage pattern

When building an app homepage or product overview with EnterUI:

- Show a real product surface in the first viewport.
- Prefer a mini app shell, data table, toolbar, metrics, form, or workflow
  preview over a decorative marketing hero.
- Keep component breadth compact. Use grouped chips or docs links instead of a
  long card catalog.
- Lazy-load heavy overlay, chart, or interactive showcase sections when they are
  below the fold.
- Keep dropdowns, popovers, date pickers, time inputs, command menus, and sheets
  inside layouts that do not clip portaled content.

## Workflow

Before implementing UI:

1. Check whether EnterUI already exports the needed primitive.
2. Read the relevant docs page if web access is available.
3. If offline, inspect `node_modules/@froggdesign/enter-ui-react`, package exports,
   `.d.ts` files, and nearby project usage.
4. Compose the screen from EnterUI primitives.
5. Add custom CSS only when props and tokens are insufficient.
6. Verify accessibility states and responsive layout.
7. Do not introduce a new local UI primitive when an EnterUI primitive already
   covers the behavior.

Build this screen using EnterUI.

Before implementing:
- Read the EnterUI Agent Instructions in this repo.
- Check whether EnterUI already exports the needed primitives.
- Use package-root imports from `@froggdesign/enter-ui-react`.
- Import `@froggdesign/theme/styles.css` before `@froggdesign/enter-ui-react/styles.css`.
- Do not create custom Button, Card, Field, Input, Dialog, Tabs, Select, or Table primitives.
- Do not create custom JSON, log, or diff viewers when `JsonViewer`, `LogViewer`,
  or `DiffViewer` covers the surface.
- Keep app-specific layout, routing, state, and data handling inside this app.
- Use EnterUI props, className, and theme variables before custom CSS.
- Preserve accessibility behavior and keyboard support.
- Avoid nested cards, large empty whitespace, and clipped overlays.