@rfdtech/components 1.22.0 → 2.0.1

package/dist/mcp/generated/rules.json

@@ -0,0 +1,629 @@
+{
+  "accessibility": [
+    {
+      "id": "accessibility-decorative-icons",
+      "title": "Mark decorative icons aria-hidden",
+      "severity": "do",
+      "components": [
+        "toast"
+      ],
+      "body": "Decorative icons that carry no independent meaning — for example a toast's leading icon — should\nbe marked `aria-hidden`. Screen readers should not announce them separately from the text they\naccompany."
+    },
+    {
+      "id": "accessibility-prefer-library-primitives",
+      "title": "Prefer the library's accessible primitives over hand-rolled patterns",
+      "severity": "do",
+      "components": [
+        "checkbox",
+        "radio-group"
+      ],
+      "body": "Prefer this library's accessible primitives — `Checkbox`, `RadioGroup`, and similar — over\nhand-rolled `sr-only`-checkbox or custom-input patterns. The library primitives already handle\nkeyboard interaction, focus management, and ARIA wiring correctly."
+    },
+    {
+      "id": "accessibility-avoid-doubled-icons",
+      "title": "Check whether a component already renders its own icon before adding another",
+      "severity": "do",
+      "components": [],
+      "body": "Before adding an adjacent icon (e.g. a lucide icon) next to a library component, check whether\nthat component already renders its own icon internally. Doubling icons is both a visual\nredundancy and an accessibility redundancy — it can cause the same meaning to be announced twice."
+    }
+  ],
+  "components": [
+    {
+      "id": "components-button-variant-semantics",
+      "title": "Use variant to signal intent, not just style",
+      "severity": "do",
+      "components": [
+        "button"
+      ],
+      "body": "`variant=\"primary\"` is for create/assign/confirm actions. `variant=\"primary-destructive\"` is for\ndestructive actions that also need primary visual weight (e.g. \"Delete and notify\"). The full\nvariant set is `\"primary\" | \"secondary\" | \"outline\" | \"ghost\" | \"destructive\" | \"primary-destructive\" | \"success\"` —\npick the variant that matches the action's real-world consequence, not just the desired color."
+    },
+    {
+      "id": "components-button-footer-ordering",
+      "title": "Footer button order is Ghost, then Primary, then Destructive",
+      "severity": "do",
+      "components": [
+        "button"
+      ],
+      "body": "In a footer/action row, order buttons left to right as: ghost (Cancel/Close) first, primary\n(the main action) next, and destructive last (rightmost). Destructive actions should never be\nthe leftmost or default-focused button."
+    },
+    {
+      "id": "components-button-modal-actions-iconless",
+      "title": "Modal and dialog action buttons are iconless",
+      "severity": "do",
+      "components": [
+        "button",
+        "dialog",
+        "modal"
+      ],
+      "body": "Buttons inside modal/dialog footers (Cancel, Save, Delete, etc.) are conventionally rendered\nwithout a leading icon, even though buttons elsewhere in the app often carry one. Keep dialog\naction rows text-only."
+    },
+    {
+      "id": "components-button-navigate-vs-download-icon",
+      "title": "Match the leading icon to the actual action",
+      "severity": "do",
+      "components": [
+        "button"
+      ],
+      "body": "A button that navigates to another page or external resource (not downloads a file) should use\na navigation icon like `ExternalLink` or `ArrowRight`, not `Download`. Reserve `Download` for\nbuttons that actually trigger a file download."
+    },
+    {
+      "id": "components-section-header-actions-primary-icon",
+      "title": "SectionActions primary button always carries a leading icon",
+      "severity": "do",
+      "components": [
+        "section-header",
+        "button"
+      ],
+      "body": "The primary-variant button inside `SectionActions` — the section header's main, highest-emphasis\naction (e.g. \"Add user\", \"Create project\") — must always include a leading icon, e.g.\n`<Plus size={14} strokeWidth={1.5} />`. Other buttons in the same `SectionActions` row (outline,\nghost, secondary) are icon-optional."
+    },
+    {
+      "id": "components-dialog-no-padding-override",
+      "title": "Never override DialogContent padding",
+      "severity": "dont",
+      "components": [
+        "dialog"
+      ],
+      "body": "Do not pass `classNames={{ content: \"p-0 overflow-hidden\" }}` or any other override that strips\nor replaces `DialogContent`'s padding. `DialogContent` manages its own padding internally, and\noverriding it breaks the component's intended spacing."
+    },
+    {
+      "id": "components-dialog-no-inner-wrapper-divs",
+      "title": "Don't add inner wrapper divs with their own padding/gap inside DialogContent",
+      "severity": "dont",
+      "components": [
+        "dialog"
+      ],
+      "body": "`DialogTitle`, `DialogDescription`, and the actions row sit directly inside `DialogContent`,\nwhich already provides padding. Wrapping them in an extra `<div className=\"p-6 flex flex-col gap-4\">`\ndoubles the spacing and produces a visibly larger gap than intended."
+    },
+    {
+      "id": "components-dialog-actions-row",
+      "title": "Dialog actions row is a plain flex div, no footer component",
+      "severity": "do",
+      "components": [
+        "dialog"
+      ],
+      "body": "The actions row is simply `<div className=\"flex justify-end gap-2\">` placed directly inside\n`DialogContent` — there is no separate footer subcomponent and no extra nesting required."
+    },
+    {
+      "id": "components-dialog-leading-icon-with-title",
+      "title": "Pair a custom leading icon with the dialog title using a flex row",
+      "severity": "do",
+      "components": [
+        "dialog"
+      ],
+      "body": "For a custom leading icon next to the dialog title (e.g. a status icon), wrap the icon and title\ntogether: `<div className=\"flex items-center gap-2\">`, with the icon sized `size-5 shrink-0` so\nit doesn't compress when the title wraps."
+    },
+    {
+      "id": "components-modal-canonical-structure",
+      "title": "Canonical Modal composition",
+      "severity": "do",
+      "components": [
+        "modal"
+      ],
+      "body": "Compose modals as `Modal > ModalPortal > ModalOverlay + ModalContent(showCloseButton, size) >\nModalHeader(ModalTitle, ModalDescription) > Form > ModalBody > ModalFooter`. Don't skip layers or\nsubstitute plain divs for these subcomponents — each one carries required styling or behavior."
+    },
+    {
+      "id": "components-modal-no-form-element",
+      "title": "Don't wrap Modal content in a literal <form> element",
+      "severity": "do",
+      "components": [
+        "modal"
+      ],
+      "body": "No `<form>` element is needed inside a Modal. Instead, call `form.handleSubmit(onSubmit)` from\nthe submit button's `onClick` handler."
+    },
+    {
+      "id": "components-modal-field-textarea-full-width",
+      "title": "Field and Textarea need explicit w-full inside ModalBody",
+      "severity": "do",
+      "components": [
+        "modal",
+        "form-field"
+      ],
+      "body": "`Field` and `Textarea` do not automatically fill the modal body's width — give them\n`className=\"w-full\"` so they span the available space inside `ModalBody`."
+    },
+    {
+      "id": "components-modal-subtle-surface",
+      "title": "Use a muted, translucent background for nested cards inside a Modal",
+      "severity": "do",
+      "components": [
+        "modal"
+      ],
+      "body": "For a subtle card-like background inside a Modal, use `bg-surface-muted/20` rather than plain\n`bg-surface-muted`, which reads too harsh against the modal surface."
+    },
+    {
+      "id": "components-table-context-children",
+      "title": "Never pull Table's context-dependent children out of <Table>",
+      "severity": "dont",
+      "components": [
+        "table"
+      ],
+      "body": "`TableSearch`, `TableFilter`, `TableActions`, and view toggles all rely on the ancestor\n`<Table paramPrefix=\"...\">` context to function. Don't render them inside a plain div outside\nof `<Table>` — they will silently break."
+    },
+    {
+      "id": "components-table-header-consistency-across-views",
+      "title": "Keep TableHeader identical across list/tile view toggles",
+      "severity": "do",
+      "components": [
+        "table"
+      ],
+      "body": "When a page offers a list/tile view toggle, keep `TableHeader` (search, filters, view toggle)\nthe same for both modes. Only swap the body: `TableContent` for list view vs. a grid for tile\nview, both still inside the same `<Table>`."
+    },
+    {
+      "id": "components-no-border-override",
+      "title": "Don't override DateSelector/Dropdown trigger borders",
+      "severity": "dont",
+      "components": [
+        "date-selector",
+        "dropdown"
+      ],
+      "body": "Don't strip default borders with something like\n`classNames={{ trigger: \"!border-0 !shadow-none focus:!shadow-none\" }}`. Let these components\nkeep their default border and shadow treatment."
+    },
+    {
+      "id": "components-dropdown-react-hook-form-wiring",
+      "title": "Wire Dropdown to react-hook-form with null-coalescing value/onChange",
+      "severity": "do",
+      "components": [
+        "dropdown",
+        "form"
+      ],
+      "body": "Wire as `value={field.value || null}` and `onValueChange={(v) => field.onChange(v ?? \"\")}`, with\n`options` passed as a `{value, label}[]` array matching the `DropdownOption` type. This avoids\nuncontrolled/controlled warnings and keeps empty values consistent as `\"\"` rather than `null`\nin form state."
+    },
+    {
+      "id": "components-card-no-manual-padding",
+      "title": "Don't add manual padding utilities inside Card",
+      "severity": "dont",
+      "components": [
+        "card"
+      ],
+      "body": "Don't add `px-6`, `py-4`, or similar padding utilities inside Card content. Card has a built-in\n`--clet-card-padding` token that already supplies correct, consistent padding."
+    },
+    {
+      "id": "components-card-footer-no-border",
+      "title": "Don't add a top border to Card footers",
+      "severity": "dont",
+      "components": [
+        "card"
+      ],
+      "body": "Don't add `border-t` on card footers. The design keeps card content-to-footer transitions\nborderless."
+    },
+    {
+      "id": "components-card-scrollable-content",
+      "title": "Scrollable Card content needs flex-col plus min-h-0 on the scroll region",
+      "severity": "do",
+      "components": [
+        "card"
+      ],
+      "body": "For scrollable content inside a Card, use `Card className=\"flex flex-col\"` with an inner region\nstyled `flex-1 overflow-y-auto min-h-0`. The `min-h-0` is required — without it the flex child\ngrows instead of scrolling."
+    },
+    {
+      "id": "components-toast-provider-setup",
+      "title": "Set up ToastProvider once at the app root",
+      "severity": "do",
+      "components": [
+        "toast"
+      ],
+      "body": "Wrap the app once, at the root, as `<ToastProvider><App/><Toaster/></ToastProvider>`. Don't\nre-instantiate the provider or `Toaster` deeper in the tree."
+    },
+    {
+      "id": "components-toast-icon-sizing",
+      "title": "Toast leading icons must be size={18} strokeWidth={2} and aria-hidden",
+      "severity": "do",
+      "components": [
+        "toast"
+      ],
+      "body": "Match the toast's typography scale by sizing leading icons `size={18} strokeWidth={2}`, and mark\nthem `aria-hidden` since they are decorative."
+    },
+    {
+      "id": "components-toast-extract-handlers",
+      "title": "Extract toast(...) calls into named handler functions",
+      "severity": "do",
+      "components": [
+        "toast"
+      ],
+      "body": "Never call `toast(...)` inline inside a JSX lambda or render body. Extract it into a named\nhandler function (e.g. `handleSaveSuccess`) so the toast call site is testable and readable\nseparately from render logic."
+    },
+    {
+      "id": "components-toast-variants",
+      "title": "Toast variant catalog",
+      "severity": "info",
+      "components": [
+        "toast"
+      ],
+      "body": "Toast supports four variants: `success | error | warning | default`. Pick the variant that\nmatches the outcome being reported rather than relying on custom icon/color combinations."
+    },
+    {
+      "id": "components-metric-card-primary-shadow",
+      "title": "Use classNames root shadow-primary for a primary-tinted MetricCard shadow",
+      "severity": "do",
+      "components": [
+        "metric-card"
+      ],
+      "body": "MetricCard's default shadow is `none`. For a primary-tinted drop shadow, pass\n`classNames={{ root: \"shadow-primary\" }}` through the component's `classNames` prop rather than\nadding shadow utilities to a wrapping element."
+    },
+    {
+      "id": "components-form-field-canonical-composition",
+      "title": "Canonical Form/FormField/Field composition",
+      "severity": "do",
+      "components": [
+        "form",
+        "form-field"
+      ],
+      "body": "Compose as `Form > FormField(control, name, render) > Field(invalid) > FieldLabel + FieldControl(Input) + FieldError`.\nWire validation state explicitly: `<Field invalid={!!fieldState.error}>` and\n`<FieldError>{fieldState.error?.message}</FieldError>`."
+    },
+    {
+      "id": "components-form-field-no-unneeded-description",
+      "title": "Don't add FieldDescription unless the design calls for it",
+      "severity": "dont",
+      "components": [
+        "form",
+        "form-field"
+      ],
+      "body": "Don't add a `FieldDescription` under every field by default. Only include it when the design\nexplicitly specifies helper text for that field."
+    },
+    {
+      "id": "components-check-library-before-hand-rolling",
+      "title": "Check for an existing component before building a replacement",
+      "severity": "do",
+      "components": [],
+      "body": "Before building any UI element from scratch, check whether the library already provides it —\nfor example `UploadField`, `Checkbox`, `Dropdown`, or `CommandInput`. Don't hand-roll a\nreplacement for functionality the library already ships."
+    },
+    {
+      "id": "components-app-header-notification-item",
+      "title": "Use AppHeaderNotificationItem, never hand-rolled notification divs",
+      "severity": "dont",
+      "components": [
+        "app-header"
+      ],
+      "body": "Render each `AppHeaderNotifications` child as an `AppHeaderNotificationItem` (`text`, `time`,\n`unread`, optional `onClick`) — never hand-write `.clet-notif-popover__item` /\n`.clet-notif-popover__dot` / `.clet-notif-popover__body-text` divs directly. The component also\nmakes the row keyboard-focusable (Enter/Space) when `onClick` is passed, which hand-rolled divs\ndon't get for free."
+    },
+    {
+      "id": "components-table-row-actions-inline-preferred",
+      "title": "Prefer inline row-action buttons over the built-in kebab menu",
+      "severity": "do",
+      "components": [
+        "table"
+      ],
+      "body": "`TableContent`'s `rowActions` prop always renders a kebab (`...`) popover menu. For the current\ndesign system, prefer a custom `cell` on an \"actions\" column rendering plain icon buttons inline\ninstead (view/edit/delete side by side) — see `demo/pages/MembersPage.tsx` or\n`demo/pages/Dashboard2Page.tsx` for the pattern. Don't combine both on the same table: passing\n`selectable` with no `rowActions` renders no kebab column at all (selection is already handled by\nthe checkbox column), so there's no redundant empty menu next to your inline buttons."
+    },
+    {
+      "id": "components-new-design-system-variants",
+      "title": "Prefer the \"new design system\" variant on these components",
+      "severity": "do",
+      "components": [
+        "app-header",
+        "metric-card",
+        "sidebar",
+        "table"
+      ],
+      "body": "The current preferred variant set (demonstrated at `/dashboard2` vs. the frozen `/dashboard2/legacy`\nin the demo app): `AppHeader` `variant=\"plain\"` over `\"default\"`; `MetricCard` `variant=\"outline\"`\nover `\"default\"`; `SidebarGroup` `collapsible` (accordion groups) over flat non-collapsible groups;\n`TableContent` `variant=\"panel\"` over `\"default\"`; `TableFilter` `variant=\"spread\"` over the\ndefault `\"popover\"`. Default to these in new work. If asked to \"convert this app to the new design\nsystem,\" scan for usages of the components above and swap them to the preferred variant, then ask\nbefore overriding any of the consuming app's own `--clet-*` color token overrides."
+    }
+  ],
+  "forms": [
+    {
+      "id": "forms-required-banner",
+      "title": "One \"All fields are required\" banner, not per-label asterisks",
+      "severity": "dont",
+      "components": [
+        "form",
+        "form-field"
+      ],
+      "body": "Do not put a `*` on every required field's label. Instead add one line near the top of the form:\n`<p className=\"text-sm text-error -mt-2\">All fields are required</p>`. This keeps the label row\nclean and states the requirement once instead of repeating visual noise on every field."
+    },
+    {
+      "id": "forms-stack",
+      "title": "The library's form stack",
+      "severity": "info",
+      "components": [
+        "form",
+        "form-field"
+      ],
+      "body": "Forms are built with `react-hook-form` + `zod` + `@hookform/resolvers/zod`, composed with this\nlibrary's `Form` / `FormField` / `Field` family. Validate with a zod schema and resolve it via\n`zodResolver`, then drive rendering through `FormField`'s `render` prop."
+    },
+    {
+      "id": "forms-field-array-and-watch",
+      "title": "Use useFieldArray for repeatable sections, form.watch for conditional fields",
+      "severity": "do",
+      "components": [
+        "form"
+      ],
+      "body": "Use `useFieldArray` for repeatable field sections (e.g. a dynamic list of contacts). Use\n`form.watch(...)` to conditionally reveal or hide fields based on the current value of another\nfield, rather than tracking a duplicate piece of local state."
+    },
+    {
+      "id": "forms-no-unnecessary-wrappers",
+      "title": "Don't wrap fields in unnecessary divs or add labels the design doesn't call for",
+      "severity": "dont",
+      "components": [
+        "form",
+        "form-field"
+      ],
+      "body": "Don't add extra wrapping `<div>`s around fields, and don't add a `FieldLabel` or other label text\nthat the design doesn't specify. Keep the field tree as flat as the `Form`/`FormField`/`Field`\ncomposition requires and nothing more."
+    },
+    {
+      "id": "forms-never-native-controls",
+      "title": "Never use a native select/button/input as a visible filter or form control",
+      "severity": "dont",
+      "components": [
+        "table",
+        "dropdown",
+        "form",
+        "form-field"
+      ],
+      "body": "Never render a raw `<select>`, native `<button>`, or native `<input>` as the visible control in a\nfilter or form — use the library's own components (`Dropdown`, `Button`, `Input`, etc.) instead.\nThis applies everywhere, but especially inside `TableFilter`: its `handleApply` reads `FormData`\nfrom named, form-associated elements, so pass `name=\"role\"` straight to `Dropdown` — it\nparticipates in native form submission on its own (backed by Radix's hidden bubble `<select>`),\nno separate hidden input needed. Never a bare `<select name=\"role\">`. For other custom inputs\nwithout built-in form participation, pair a hidden `<input type=\"hidden\" name=\"...\" value={...} />`\n(captured by `FormData`) driving the same value instead — it's invisible plumbing, not a visible\nnative control."
+    },
+    {
+      "id": "forms-table-filter-spread-autoapply",
+      "title": "TableFilter's spread variant has no Apply button — it auto-applies",
+      "severity": "info",
+      "components": [
+        "table"
+      ],
+      "body": "`<TableFilter variant=\"spread\">` removes the popover and lays fields out inline with just a\n\"clear\" action — there is no Apply button. Fields apply as soon as their value changes (the\ncomponent diffs a `FormData` snapshot after every render — a safety net for any custom input that\ndoesn't fire a native change event; `Dropdown`'s own `name`-driven hidden field does fire one).\nDon't add your own Apply button next to a spread filter — it's redundant."
+    }
+  ],
+  "layout": [
+    {
+      "id": "layout-no-inline-style-sizing",
+      "title": "Don't use inline style={{}} for layout sizing — use Tailwind arbitrary values",
+      "severity": "dont",
+      "components": [],
+      "body": "Don't use inline `style={{}}` in React for layout sizing. Use Tailwind arbitrary values instead,\ne.g. `h-[calc(100vh-80px)]`, so sizing stays inspectable in markup and consistent with the rest\nof the styling approach."
+    },
+    {
+      "id": "layout-min-h-0",
+      "title": "min-h-0 is required on a flex child for overflow-y-auto to scroll",
+      "severity": "do",
+      "components": [],
+      "body": "A flex child needs `min-h-0` for `overflow-y-auto` to actually scroll. Without it, the flex item\ngrows to fit its content and pushes the parent taller instead of producing an internal scroll\nregion.\n\n```\n<div className=\"flex flex-col h-full\">\n  <div className=\"flex-1 overflow-y-auto min-h-0\">...</div>\n</div>\n```"
+    },
+    {
+      "id": "layout-no-mixed-grid-flex-row",
+      "title": "Don't mix CSS grid and flexbox for the same row",
+      "severity": "dont",
+      "components": [],
+      "body": "Pick one layout model per row. Don't apply `display: grid` and `display: flex` behavior to the\nsame row by nesting a flex row's children with grid-specific utilities — it produces\ninconsistent alignment and makes the row hard to reason about."
+    },
+    {
+      "id": "layout-no-absolute-positioning-in-grid",
+      "title": "Don't use absolute positioning for inline elements inside a grid layout",
+      "severity": "dont",
+      "components": [],
+      "body": "Don't use absolute positioning to place inline elements inside a grid layout. Use a flex row for\ninline element groupings instead — absolute positioning inside a grid breaks the grid's own flow\nand sizing."
+    },
+    {
+      "id": "layout-icon-column-alignment",
+      "title": "Use a fixed grid template to keep an icon column aligned across repeated rows",
+      "severity": "do",
+      "components": [],
+      "body": "Use `grid grid-cols-[1fr_auto_1fr_auto] items-center gap-2` (or a similar explicit column\ntemplate) to keep an icon column aligned across repeated rows, rather than relying on flexbox\nspacing that can drift row to row."
+    }
+  ],
+  "page-composition": [
+    {
+      "id": "page-composition-layout-shell",
+      "title": "Adopt AppLayout variant=\"stacked\" + AppHeader variant=\"plain\" + Sidebar variant=\"plain\" together",
+      "severity": "do",
+      "components": [
+        "app-layout",
+        "app-header",
+        "sidebar"
+      ],
+      "body": "Adopt the new layout shell as a set, not individually: `AppLayout variant=\"stacked\"` (header spans\nfull width on top, sidebar + content side by side below), `AppHeader variant=\"plain\"` (square\ncorners, `--clet-primary` background, on-primary text, continuous top bar), and `Sidebar\nvariant=\"plain\"` (transparent background + right border instead of a panel surface). All required\nfor new/touched screens — none required for existing screens to keep compiling."
+    },
+    {
+      "id": "page-composition-sidebar-groups-collapsible",
+      "title": "Use collapsible SidebarGroups, not flat nav lists",
+      "severity": "do",
+      "components": [
+        "sidebar"
+      ],
+      "body": "All nav groups use `SidebarGroup collapsible` accordion sections, not flat lists. Initialize with\nthe `Main` group expanded and the rest collapsed."
+    },
+    {
+      "id": "page-composition-sidebar-footer-required",
+      "title": "Every Sidebar needs a SidebarFooter hosting a ProfilePopover",
+      "severity": "do",
+      "components": [
+        "sidebar",
+        "profile-popover"
+      ],
+      "body": "Never omit `SidebarFooter`. It must host a `ProfilePopover` in `fullName`/`email` mode (not\n`user`/`variant`) — full name, email, and role get a stable, real-estate-rich home there. This is\nrequired on the new layout shell, unlike the old default shell (`DemoLayout`), which never\nrequired one."
+    },
+    {
+      "id": "page-composition-no-sidebar-trigger",
+      "title": "Don't render SidebarTrigger in new layouts",
+      "severity": "dont",
+      "components": [
+        "sidebar"
+      ],
+      "body": "The old default layout shell renders `<SidebarTrigger>Menu</SidebarTrigger>` to manually toggle\nthe sidebar. The new shell drops it entirely — don't render `SidebarTrigger` in new or touched\nlayouts. Use `SidebarProvider` with its defaults and no manual collapse control."
+    },
+    {
+      "id": "page-composition-sidebar-badge-numeric",
+      "title": "SidebarBadge shows a real numeric count, not decorative text",
+      "severity": "do",
+      "components": [
+        "sidebar"
+      ],
+      "body": "Compose `SidebarBadge` inside a `SidebarLink`'s children (`{link.badge && <SidebarBadge>{link.badge}</SidebarBadge>}`).\nReserve it for a live count of actionable items on that nav destination (e.g. `8` unread alerts) —\nthe number must reflect real pending/important items, not a static placeholder. The one exception\nis a short text badge like `\"New\"` for a feature callout (e.g. a newly-added nav link) — don't\ninvent other text badges beyond that pattern."
+    },
+    {
+      "id": "page-composition-branding-in-app-header",
+      "title": "Branding lives in AppHeader via AppHeaderBranding, never in the sidebar",
+      "severity": "do",
+      "components": [
+        "app-header",
+        "sidebar"
+      ],
+      "body": "Put branding in `AppHeader` via `AppHeaderBranding` (`logo`/`title`/`subtitle`), never in the\nsidebar. `Sidebar` has no `SidebarHeader`/`SidebarBrand` when `AppHeaderBranding` is used — the\nsame logo must not appear twice on screen. Use the current brand logo (`clet-logo.png`) for any\nnew system — `gsl-logo.png` is the older mark used only by the legacy default layout shell."
+    },
+    {
+      "id": "page-composition-profile-popover-default-items",
+      "title": "Don't rebuild My Profile/Account Settings/Help and Support via items",
+      "severity": "dont",
+      "components": [
+        "profile-popover"
+      ],
+      "body": "`ProfilePopover`'s `items` defaults to \"My Profile\", \"Account Settings\", and \"Help and Support\",\nwired via `onMyProfile`/`onAccountSettings`/`onHelpAndSupport`. Don't hand-build those three rows\nvia a passed-in `items` array — only pass `items` when the system genuinely needs rows other than\nthe three defaults, since a passed-in array fully replaces them rather than merging."
+    },
+    {
+      "id": "page-composition-role-select-three-locations",
+      "title": "Wire the same RoleSelect state into Launchpad, header ProfilePopover, and sidebar footer ProfilePopover",
+      "severity": "do",
+      "components": [
+        "role-select",
+        "launchpad",
+        "profile-popover"
+      ],
+      "body": "Whenever a system allows a user to have more than one role — true for most systems — wire the same\n`RoleSelect` state (`roles`/`selectedRole`/`onClickRole`) into all three locations: `Launchpad`,\nthe header `ProfilePopover`, and the sidebar footer `ProfilePopover`. Don't add it to only one or\ntwo of the three. The header `ProfilePopover` uses `variant=\"avatar\"` when a sidebar footer\npopover also exists; reserve `variant=\"full\"` for headers with no sidebar footer."
+    },
+    {
+      "id": "page-composition-launchpad-required-role-select",
+      "title": "Launchpad's children (RoleSelect) is required, not optional",
+      "severity": "do",
+      "components": [
+        "launchpad"
+      ],
+      "body": "`Launchpad`'s `children` prop is required at the type level and only accepts a single `RoleSelect`\nelement — omitting it is a type error, not a lint warning. There is no bordered \"See all\" footer\nbutton anymore: a small ghost `sm` expand button sits at the top right of the panel next to the\ntitle, its expand icon always visible, its \"See more\" text label appearing only once `apps.length`\nexceeds the 9-app cap."
+    },
+    {
+      "id": "page-composition-launchpad-over-app-switcher",
+      "title": "Use Launchpad, not the deprecated AppSwitcher, for new app-switching UI",
+      "severity": "dont",
+      "components": [
+        "app-switcher",
+        "launchpad"
+      ],
+      "body": "`AppSwitcher` is deprecated and gets no new features. Use `Launchpad` for all new app-switching\nwork. Stay on `AppSwitcher` only if the system genuinely needs flexible column count, an uncapped\ngrid without an expand modal, or a fully custom footer slot — and check with the team first."
+    },
+    {
+      "id": "page-composition-table-family-variants",
+      "title": "Adopt TableContent variant=\"panel\" + TableFilter variant=\"spread\" + no-border TableFooter together",
+      "severity": "do",
+      "components": [
+        "table"
+      ],
+      "body": "New or touched `Table`s use all three together: `TableContent variant=\"panel\"` (not `\"default\"`),\n`TableFilter variant=\"spread\"` (not the default `\"popover\"`), and `TableFooter noBorder` (a real\n`TableFooterProps` prop, not a demo hack)."
+    },
+    {
+      "id": "page-composition-other-preferred-variants",
+      "title": "Prefer MetricCard variant=\"outline\" and Tabs variant=\"pill\" on new usage",
+      "severity": "do",
+      "components": [
+        "metric-card",
+        "tabs"
+      ],
+      "body": "Use `MetricCard variant=\"outline\"` over `\"default\"`, and `Tabs variant=\"pill\"` over `\"default\"`,\non any new or substantially-touched screen."
+    },
+    {
+      "id": "page-composition-section-header",
+      "title": "Use SectionHeader for page headers, never a hand-rolled div",
+      "severity": "do",
+      "components": [
+        "section-header"
+      ],
+      "body": "Use `SectionHeader` (with `SectionTitle`/`SectionDescription`/`SectionActions`) to compose page\nheaders — never a hand-rolled `<div>`."
+    },
+    {
+      "id": "page-composition-builtin-loading-states",
+      "title": "Use each component's real loading prop, never hand-rolled placeholders",
+      "severity": "do",
+      "components": [
+        "launchpad",
+        "app-header",
+        "profile-popover",
+        "sidebar",
+        "metric-card",
+        "table"
+      ],
+      "body": "Every component that supports a real `loading` prop (with a shimmering skeleton) should use it —\n`Launchpad`, `AppHeaderNotifications`, `ProfilePopover` (`loading`/`loadingLabel`), `SidebarLink`\n(`loading`/`loadingLabel`), `MetricCard` (`loading`/`loadingLabel`), `TableContent`\n(`loading`/`loadingRows`). Never render `\"...\"` placeholders, a hand-rolled `<Spinner />`, or omit\ncontent until data is ready."
+    }
+  ],
+  "theming": [
+    {
+      "id": "theming-no-hardcoded-colors",
+      "title": "Never hardcode colors — always use theme tokens",
+      "severity": "dont",
+      "components": [],
+      "body": "Never hardcode colors such as `#fff` or Tailwind palette classes like `text-blue-600`. Always use\nthis library's theme tokens instead — `text-foreground`, `bg-surface-muted`, `text-error`, and\nsimilar. This holds even for small stylistic touches like a link-styled button; reach for a token\nclass, not a raw palette color, in every case."
+    },
+    {
+      "id": "theming-no-global-token-mutation-for-one-element",
+      "title": "Don't mutate global accent tokens to reskin a single element",
+      "severity": "dont",
+      "components": [],
+      "body": "Don't change global accent/theme tokens just to restyle one specific element. Instead apply a\nscoped Tailwind color class directly to that element, leaving the shared tokens untouched for the\nrest of the app."
+    },
+    {
+      "id": "theming-subtle-surface-opacity",
+      "title": "Prefer a translucent muted surface over the harsher plain one",
+      "severity": "do",
+      "components": [
+        "modal",
+        "card"
+      ],
+      "body": "For a subtle or muted surface — for example a card background nested inside a modal — prefer\n`bg-surface-muted/20` over the plain `bg-surface-muted`, which reads too harsh in that context."
+    },
+    {
+      "id": "theming-use-clettheme-for-token-overrides",
+      "title": "Use cletTheme() to override design tokens, not hand-written CSS",
+      "severity": "do",
+      "components": [
+        "theme"
+      ],
+      "body": "To override any `--clet-*` token (global, like `primary`/`radiusBase`, or component-scoped, like\nCard's `padding` or AppHeader's `bg`), call the `cletTheme()` runtime helper exported from\n`@rfdtech/components` — pass `all`/`light`/`dark` for global tokens, or `components: { ComponentName:\n{...} }` for a specific component's own tokens. It's fully type-checked against the real token\nregistry (unknown keys and mismatched value shapes are compile errors), and it injects one `<style>`\ntag with no build config or separate CSS file needed. Reach for a hand-written CSS override file\n(documented as a fallback) only when you need conditional/media-query logic `cletTheme()` can't\nexpress. See `get_component(\"theme\")` for the full API and `get_tokens()` for every valid token name.\nPut the call in a `src/clet.theme.ts` file, side-effect-imported once in the app entry point (see\n`get_component(\"theme\")` for the recommended-file convention)."
+    },
+    {
+      "id": "theming-migration-ask-about-existing-token-overrides",
+      "title": "When migrating, ask the user about each existing `--clet-*` token override — don't silently keep or drop any",
+      "severity": "do",
+      "components": [
+        "theme"
+      ],
+      "body": "When migrating a project onto the new design system defaults, first find every existing override\nof a **known `--clet-*` token** — a `cletTheme()` call (in `src/clet.theme.ts` or elsewhere), or\nhand-written CSS setting a real `--clet-*` custom property. This does not include custom/arbitrary\nCSS variables or component-local one-off styling that isn't a recognized library token — only\noverrides of tokens the library itself defines (cross-check against `get_tokens()`).\n\nList every overridden token found, then ask the user about each one individually — keep the\nexisting override (preserve current branding for that token), or drop it and adopt the new\napproved default. Don't decide this silently and don't batch it into a single yes/no — a token like\n`--clet-primary` might be an intentional brand choice worth keeping, while another was only ever set\nto match the *old* pre-rebrand defaults and should be dropped now that those defaults themselves\nchanged. See the \"Rebrand\" section of `get_component(\"migration-v2\")` for the specific old→new\ndefault values that changed."
+    }
+  ],
+  "tokens": [
+    {
+      "id": "tokens-radius-xl",
+      "title": "--clet-radius-xl backs Tailwind's rounded-xl",
+      "severity": "info",
+      "components": [],
+      "body": "`--clet-radius-xl` is the design token that backs Tailwind's `rounded-xl` utility in this design\nsystem. Use `rounded-xl` in markup rather than a hardcoded border-radius value."
+    },
+    {
+      "id": "tokens-card-padding",
+      "title": "--clet-card-padding is Card's built-in padding token",
+      "severity": "info",
+      "components": [
+        "card"
+      ],
+      "body": "`--clet-card-padding` is the token that supplies Card's built-in content padding. Don't\nre-implement it with utility padding classes like `px-6 py-4` — rely on the token."
+    },
+    {
+      "id": "tokens-catalog",
+      "title": "Token catalog observed in real usage",
+      "severity": "info",
+      "components": [],
+      "body": "Common tokens/utilities in use across the library and consuming apps: `text-foreground`,\n`text-foreground-muted`, `bg-surface-muted`, `bg-surface-muted/20`, `bg-surface-subtle`,\n`border-border`, `text-error`, `text-warning`, `bg-warning-bg`, `bg-primary`, `text-primary`\n(backed by `--clet-primary`), `rounded-xl` (backed by `--clet-radius-xl`), and Card's\n`--clet-card-padding`. Prefer these over hardcoded colors or spacing values."
+    }
+  ]
+}