@ngrr/ds 0.1.29 → 0.1.31

package/AI-short.md

@@ -0,0 +1,243 @@
+# DS-Nagarro — Usage guide
+
+> Condensed rules for context-limited tools. Full reference: `AI.md`
+> Storybook: `https://699f3dfd3540c3f346868d55-kmskdmltrn.chromatic.com/`
+
+---
+
+## Setup
+
+```tsx
+// main.tsx — before everything else
+import '@ngrr/ds/style.css'
+import '@ngrr/ds/tokens.css'
+```
+
+```css
+/* host app CSS */
+html, body { margin: 0; height: 100%; }
+#root { height: 100%; display: flex; flex-direction: column; box-sizing: border-box; }
+```
+
+`lucide-react` is bundled inside `@ngrr/ds` — never install it separately.
+
+---
+
+## AppShell — mandatory root layout
+
+Every page must use `AppShell`. Never build layout with raw divs.
+AppShell must always live inside a full-height wrapper div — never add height to AppShell itself.
+
+```tsx
+<div style={{ height: '100vh', display: 'flex' }}>
+  <AppShell
+    header={<Navbar variant="title" title="Dashboard" rightActions={<Button variant="primary" size="md">New project</Button>} />}
+    sidebar={<Sidebar ... />}
+  >
+    {/* Always include this wrapper — never skip it */}
+    <div style={{ paddingInline: 'var(--page-margin-x)', paddingBlock: 'var(--inset-large)' }}>
+      {/* page content here */}
+    </div>
+  </AppShell>
+</div>
+```
+
+- Only the content area scrolls. Sidebar and Navbar are always fixed.
+- Never pass `collapsed` to Sidebar — AppShell controls it automatically.
+- `DataTable` is never wrapped in a `Card` — always full-width.
+
+---
+
+## Typography — never override
+
+The design system sets all typography globally. Never fight it.
+
+- Never set `font-family` — it is inherited.
+- Never use raw `<h1>`–`<h6>` or `<p>` with custom font styling.
+- Never set `font-size` with raw pixel values — use `var(--font-size-*)` tokens.
+
+```tsx
+// CORRECT
+<div style={{ fontSize: 'var(--font-size-body-l)', color: 'var(--color-text-primary)' }}>
+
+// WRONG
+<h2 style={{ fontFamily: 'Georgia, serif' }}>   // never
+<p style={{ fontSize: '18px' }}>                // never
+```
+
+---
+
+## Navbar rules
+
+- `variant="title"` on top-level pages — plain title, no back arrow, no breadcrumbs.
+- `variant="breadcrumbs"` on detail views — breadcrumb replaces the title, never both.
+- Primary CTA always in `rightActions` — never inside a Card, never floating.
+- Never use `position: fixed` or `position: absolute` on any Button.
+- Maximum one Primary button per view. Order right-to-left: Ghost → Secondary → Primary.
+- All titles, labels, copy: sentence case always. Never title case.
+
+---
+
+## Card structure
+
+```tsx
+// CORRECT
+<Card title="Team members">
+  <div style={{ padding: 'var(--inset-large)' }}>
+    {/* content here */}
+  </div>
+</Card>
+
+// WRONG
+<Card style={{ padding: 'var(--inset-large)' }}>  // never on Card itself
+```
+
+Never add padding, margin, or gap to the Card header or bottom bar — they are pre-built.
+Always wrap Card children in a div with `padding: var(--inset-large)`.
+
+---
+
+## KPI / stat card pattern
+
+```tsx
+<Card>
+  <div style={{ padding: 'var(--inset-large)' }}>
+    <div style={{ fontSize: 'var(--font-size-body-s)', color: 'var(--color-text-secondary)', marginBottom: 'var(--space-tiny)' }}>
+      Active projects
+    </div>
+    <div style={{ fontSize: 'var(--font-size-heading-l)', fontWeight: 'var(--font-weight-semibold)', color: 'var(--color-text-primary)' }}>
+      14
+    </div>
+    <div style={{ fontSize: 'var(--font-size-body-s)', color: 'var(--color-text-success)', marginTop: 'var(--space-tiny)' }}>
+      +2 this week
+    </div>
+  </div>
+</Card>
+```
+
+Never use raw HTML or custom typography for stat cards. Always use `<Card>` and token values.
+
+---
+
+## Component spacing — critical
+
+Never add `padding`, `margin`, `gap`, `min-height`, or any spacing override directly on a DS-Nagarro component. Apply spacing tokens to wrapper/container elements only.
+
+```
+✅ <div style={{ gap: 'var(--space-standard)' }}><Button /><Button /></div>
+❌ <Button style={{ marginRight: 'var(--space-standard)' }} />
+❌ <Navbar style={{ paddingInline: 'var(--inset-large)' }} />
+```
+
+---
+
+## Token rules
+
+Never hardcode hex values, pixel sizes, or rgba. Always use CSS custom properties.
+
+| Use case | Token |
+|---|---|
+| Gap between elements | `--space-*` |
+| Padding inside a component | `--inset-*` |
+| Horizontal page margin | `--page-margin-x` |
+| Text color | `--color-text-*` |
+| Background | `--background-*` |
+| Border/outline | `--borders-*` |
+| Chart/graph colors | `--color-dataviz-*` |
+
+- `--space-*` = gaps **between** elements. Never for internal padding.
+- `--inset-*` = padding **inside** a component. Never for gaps between elements.
+- Never use generic semantic tokens for dataviz — always `--color-dataviz-*`.
+- Dark mode: `data-theme="dark"` on the root element — never `@media (prefers-color-scheme: dark)`.
+
+---
+
+## Tag semantic mapping
+
+Always match Tag variant to the meaning of the value. Never use the same variant for all tags in a list.
+
+| Meaning | Variant |
+|---|---|
+| Done, approved, on track, success, complete | `success` |
+| At risk, pending, in progress, waiting | `warning` |
+| Blocked, failed, rejected, overdue | `error` |
+| Draft, inactive, archived, unknown | `neutral` |
+| Category label (name, topic, team) | `neutral` |
+
+```tsx
+// WRONG — same variant for every tag
+<Tag variant="warning">Completed</Tag>   // completed = success
+<Tag variant="warning">Not started</Tag> // not started = neutral
+
+// CORRECT
+<Tag variant="success">Completed</Tag>
+<Tag variant="warning">In progress</Tag>
+<Tag variant="neutral">Not started</Tag>
+<Tag variant="error">Blocked</Tag>
+```
+
+Tags are non-interactive. Never make a Tag clickable.
+
+---
+
+## Component decision rules
+
+| Situation | Component |
+|---|---|
+| Toggle between 2–5 mutually exclusive views | `SegmentControl` — never plain text or custom buttons |
+| Each option has a distinct content panel | `Tabs` |
+| User selects or filters with a toggleable option | `Chip` |
+| Non-interactive status or category label | `Tag` |
+| User clicks a table row to see details | `Drawer` |
+| User must complete a task before continuing | `Modal` |
+| Numeric count on a nav icon | `Badge` |
+| List needing sorting, filtering, or pagination | `DataTable` |
+| No results or first-time empty section | `EmptyState` |
+| Content loading, shape known | `Skeleton` — not `Spinner` |
+
+---
+
+## Forms
+
+- Every field is mandatory by default. Never use a red asterisk.
+- Mark optional fields only: `Team <span style="color: var(--color-text-tertiary)">Optional</span>`
+- Primary submit must be disabled until all mandatory fields have a value.
+- Validate on submit only — not in real time (exceptions: password strength, character count, search, OTP).
+- Every primary submit button must show `⌘↵`: `<Button variant="primary">Save changes <Shortcut>⌘↵</Shortcut></Button>`
+
+---
+
+## What not to do
+
+- ❌ Build layout with raw divs — always use `AppShell`
+- ❌ Add `min-height`, `height`, or sizing directly to `<AppShell>`
+- ❌ Skip the `<div style={{ height: '100vh', display: 'flex' }}>` wrapper around AppShell
+- ❌ Skip the `paddingInline: var(--page-margin-x)` content wrapper inside AppShell
+- ❌ Set `font-family` anywhere in app code
+- ❌ Use `<h1>`–`<h6>` or `<p>` with custom font styling
+- ❌ Set `font-size` with raw pixel values
+- ❌ Add spacing overrides directly on DS-Nagarro components
+- ❌ Add padding or margin directly to `<Card>` — wrap children instead
+- ❌ Wrap `DataTable` in a `Card`
+- ❌ Place the primary CTA inside a Card or as a floating button
+- ❌ Use `position: fixed` or `position: absolute` on any Button
+- ❌ Show a back arrow on top-level pages
+- ❌ Hardcode hex values, pixel sizes, or rgba
+- ❌ Use `--inset-*` for gaps between elements
+- ❌ Use `--space-*` for padding inside components
+- ❌ Use generic semantic tokens or hardcoded hex for dataviz
+- ❌ Use the same Tag variant for all tags in a list
+- ❌ Make a Tag interactive or clickable
+- ❌ Place two Primary buttons side by side
+- ❌ Use any icon library other than `lucide-react`
+- ❌ Install `lucide-react` separately — it is bundled inside `@ngrr/ds`
+- ❌ Leave placeholder icons, help text, or hint icons in place
+- ❌ Use "OK", "Confirm", or "Yes" as button labels — always specific verbs
+- ❌ Use title case — always sentence case
+- ❌ Override dark mode with `@media (prefers-color-scheme: dark)` — use `data-theme="dark"`
+- ❌ Use `Spinner` when content shape is known — use `Skeleton`
+- ❌ Leave an empty state as blank space — always use `EmptyState`
+
+---
+
+*DS-Nagarro usage guide. Full reference: `AI.md`. Last updated: 2026-04-01.*