@ngrr/ds 0.1.13 → 0.1.16

package/AGENTS.md

@@ -1,7 +1,10 @@
-# DS-Nagarro Component Library — Agent Briefing
+# DS-Nagarro Component Library — Building Guide
 
-> **READ THIS FIRST.** This file is the entry point for every coding session.
+> **READ THIS FIRST.** This file is the entry point for every coding session on the component library.
 > Do not write any code until you have read and understood this document.
+>
+> **This file is for building components.** For component usage specs, layout rules, and
+> navigation patterns when building apps *with* `@ngrr/ds`, read `AI.md` instead.
 
 ---
 
@@ -28,7 +31,9 @@ This is the React component library for **DS-Nagarro**, an enterprise design sys
 
 ```
 ds-nagarro/
-├── AGENTS.md                    ← You are here
+├── AGENTS.md                    ← You are here (building guide)
+├── AI.md                        ← Usage guide (for consuming the package)
+├── CLAUDE.md                    ← Claude Code pointer (redirects here)
 ├── tokens.css                   ← All design tokens as CSS custom properties
 ├── src/
 │   ├── index.ts                 ← Public API — export all components
@@ -50,7 +55,7 @@ ds-nagarro/
 │   ├── main.ts
 │   └── preview.ts               ← Imports tokens.css globally
 └── docs/                        ← Design system documentation (read-only)
-    └── [copied from /mnt/project/ — see Documentation section]
+    └── [component spec files — see table below]
 ```
 
 ---
@@ -59,7 +64,7 @@ ds-nagarro/
 
 All component specs live in the `docs/` directory. Each file is authoritative for its component(s). Read the relevant doc **before** generating any component.
 
-| File | Components Covered |
+| File | Components covered |
 |---|---|
 | `button.md` | Button (Main, Destructive, Toggle, Vertical) |
 | `avatar.md` | Avatar, AvatarGroup |
@@ -452,153 +457,4 @@ Either populate with real, meaningful content or hide the slot entirely.
 
 ---
 
-## Consuming the Package — Layout & Navigation
-
-> This section is for AI agents building apps with `@ngrr/ds`, not for building the library itself.
-
-### Setup — mandatory CSS imports
-```tsx
-// main.tsx — must be first, before any other imports
-import '@ngrr/ds/style.css'
-import '@ngrr/ds/tokens.css'
-```
-
-### Required CSS on the host app
-```css
-html, body { margin: 0; height: 100%; }
-#root { min-height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
-```
-
----
-
-### AppShell — mandatory root layout
-
-`AppShell` is the only permitted root layout wrapper. Every page must be inside it. Do not invent wrapper divs or custom layouts.
-```tsx
-import { AppShell, Navbar, Sidebar, Button, SearchBar, Avatar } from '@ngrr/ds';
-// Icons come from lucide-react — install separately: npm install lucide-react
-import { LayoutDashboard, FolderKanban, CheckSquare, Users, FileText, Settings } from 'lucide-react';
-
-<AppShell
-  header={
-    <Navbar
-      title="Dashboard"
-      rightActions={<Button variant="primary" label="New project" />}
-    />
-  }
-  sidebar={
-    <Sidebar
-      selectorProps={{
-        label: 'WorkScope',
-        avatarProps: {
-          size: 'xs',
-          variant: 'organization',
-          fill: 'initials',
-          initials: 'WS',
-          name: 'WorkScope',
-        },
-      }}
-      showSearch
-      searchSlot={<SearchBar placeholder="Search" />}
-      sections={[
-        {
-          id: 'main',
-          items: [
-            { id: 'dashboard', label: 'Dashboard', icon: <LayoutDashboard size={16} />, selected: true, onClick: () => {} },
-            { id: 'projects', label: 'Projects', icon: <FolderKanban size={16} />, onClick: () => {} },
-            { id: 'tasks', label: 'Tasks', icon: <CheckSquare size={16} />, onClick: () => {} },
-            { id: 'people', label: 'People', icon: <Users size={16} />, onClick: () => {} },
-            { id: 'notes', label: 'Notes', icon: <FileText size={16} />, onClick: () => {} },
-          ],
-        },
-      ]}
-      bottomContent={
-        <>
-          <SidebarMenuSelector
-            variant="full"
-            label="Settings"
-            showIcon
-            icon={<Settings size={16} />}
-            onClick={() => {}}
-          />
-          <SidebarMenuSelector
-            variant="full"
-            label="User Name"
-            showAvatar
-            avatarProps={{ size: 'xs', fill: 'initials', initials: 'UN', name: 'User Name' }}
-            onClick={() => {}}
-          />
-        </>
-      }
-    />
-  }
->
-  {/* page content goes here */}
-</AppShell>
-```
-
-**AppShell props:**
-- `header` — `<Navbar />` only
-- `sidebar` — `<Sidebar />` only. Never pass `collapsed` manually — AppShell injects it automatically
-- `children` — main page content
-- `rightPanel` — optional, omit if not needed
-- `footer` — optional, omit if not needed
-
-**Forbidden:**
-- Do not wrap AppShell in any other layout element
-- Do not add sidebar items beyond what is specified
-- Do not invent extra sections, items, or nav elements
-
----
-
-### Navbar props
-- `variant` — `'title'` (default) for top-level pages | `'breadcrumbs'` for detail views only
-- `title` — page title, sentence case
-- `rightActions` — primary CTA button, rightmost position
-- `leftActions` — secondary actions on the left, omit if not needed
-- `onBackClick` — only used with `variant="breadcrumbs"`
-- `breadcrumbItems` — required only when `variant="breadcrumbs"`
-
-**Rules:**
-- Never show a back arrow on top-level pages (Dashboard, Projects, Tasks, People, Notes)
-- Back arrow only on detail views using `variant="breadcrumbs"`
-- Primary CTA always in `rightActions`
-
----
-
-### Sidebar props
-- `sections` — required. Only include sections explicitly specified. Never invent extra items.
-- `selectorProps` — workspace selector at the top. Always set `label` and `avatarProps`.
-- `showSearch` — set to `true` to show the search bar
-- `searchSlot` — pass a `<SearchBar />` component when `showSearch` is true
-- `bottomContent` — use for Settings and User Name, pinned to bottom with a divider. Always include these two items.
-- Never pass `collapsed` — AppShell controls it automatically
-
-**SidebarMenuItem shape:**
-```ts
-{
-  id: string;
-  label: string;           // sentence case always
-  icon?: React.ReactNode;  // lucide-react icon at size={16}
-  selected?: boolean;      // true only for the active page
-  onClick?: () => void;
-  showBadge?: boolean;
-  badgeCount?: number;
-  badgeVariant?: BadgeVariant;
-  showAvatar?: boolean;
-  avatarProps?: AvatarProps;
-}
-```
-
----
-
-### Hard rules — always follow
-- `AppShell` is always the root — no exceptions
-- `DataTable` must never be wrapped in a `Card`
-- No back arrow on top-level pages: Dashboard, Projects, Tasks, People, Notes
-- CTA hierarchy: Primary (object creation, rightmost in Navbar) → Secondary → Ghost (Export, Share, Edit)
-- All labels and copy: sentence case always ("New project" not "New Project")
-- Icons: from `lucide-react` — install with `npm install lucide-react`
-- Tag variants: `success` = completed, `progress` = in progress, `warning` = at risk, `neutral` = not started
-- Settings and User Name always pinned to sidebar bottom via `bottomContent`
-- Sidebar always full viewport height — guaranteed by AppShell CSS rules above
+*Source of truth for building DS-Nagarro components. Last updated: 2026-03-16.*