@ngrr/ds 0.1.4 → 0.1.6

package/AGENTS.md

@@ -0,0 +1,451 @@
+# DS-Nagarro Component Library — Agent Briefing
+
+> **READ THIS FIRST.** This file is the entry point for every coding session.
+> Do not write any code until you have read and understood this document.
+
+---
+
+## Project Purpose
+
+This is the React component library for **DS-Nagarro**, an enterprise design system optimised for AI-agent code generation. The primary goal is machine-readable fidelity: components must implement exactly what the design system specifies, using exactly the tokens named in the documentation. No creative interpretation.
+
+---
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | React 18 + TypeScript |
+| Build | Vite |
+| Styling | Styled Components v6 |
+| Token consumption | CSS custom properties via `var()` |
+| Documentation | Storybook 8 (CSF 3.0 + autodocs) |
+| Testing | Vitest + Testing Library + Storybook play functions |
+
+---
+
+## Repository Structure
+
+```
+ds-nagarro/
+├── AGENTS.md                    ← You are here
+├── tokens.css                   ← All design tokens as CSS custom properties
+├── src/
+│   ├── index.ts                 ← Public API — export all components
+│   ├── styles/
+│   │   └── global.css           ← Imports tokens.css, sets base styles
+│   ├── components/
+│   │   ├── atoms/
+│   │   │   ├── Button/
+│   │   │   │   ├── Button.tsx
+│   │   │   │   ├── Button.stories.tsx
+│   │   │   │   ├── Button.test.tsx
+│   │   │   │   └── index.ts
+│   │   │   └── [other atoms...]
+│   │   ├── molecules/
+│   │   └── organisms/
+│   └── types/
+│       └── common.ts            ← Shared TypeScript interfaces
+├── .storybook/
+│   ├── main.ts
+│   └── preview.ts               ← Imports tokens.css globally
+└── docs/                        ← Design system documentation (read-only)
+    └── [copied from /mnt/project/ — see Documentation section]
+```
+
+---
+
+## Component Documentation
+
+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 |
+|---|---|
+| `button.md` | Button (Main, Destructive, Toggle, Vertical) |
+| `avatar.md` | Avatar, AvatarGroup |
+| `badge.md` | Badge |
+| `tag.md` | Tag |
+| `chip.md` | Chip, ChipGroup |
+| `separator.md` | Separator |
+| `switcher.md` | Switcher (Toggle Switch) |
+| `checkbox.md` | Checkbox |
+| `radio.md` | Radio |
+| `tab.md` | Tab (Navigation, Custom View) |
+| `segment-control.md` | SegmentControl |
+| `breadcrumbs.md` | Breadcrumbs, BreadcrumbItem |
+| `pagination.md` | Pagination, PageSelector |
+| `toast.md` | Toast (Inline, Rich) |
+| `tooltip.md` | Tooltip |
+| `popover.md` | Popover |
+| `modal.md` | Modal |
+| `input-anatomy.md` | Input anatomy (shared across all input types) |
+| `input-text-textarea-search.md` | TextInput, TextArea, SearchInput |
+| `input-password-otp-number-phone.md` | PasswordInput, OTPInput, NumberInput, PhoneInput |
+| `input-select-autocomplete-horizontal.md` | Select, AutocompleteMulti, HorizontalInput |
+| `input-slider-upload-chips.md` | Slider, UploadArea, ChipsInput |
+| `input-date-time-picker.md` | DatePicker, DateRangePicker, DateTimePicker |
+| `lightweight-loading-scrollbar-shortcut.md` | Spinner, SkeletonLoading, ProgressBar, Scrollbar, Shortcut |
+| `patterns.md` | Layout patterns (not components) |
+| `foundations.md` | Token system, colour rules, typography rules |
+| `ds-guidelines.md` | Global rules |
+
+---
+
+## Token System
+
+### Where tokens live
+All tokens are CSS custom properties defined in `tokens.css`. They are imported globally via `src/styles/global.css`. Every Styled Component must consume tokens via `var(--token-name)`.
+
+### Naming convention
+Figma uses slash-separated paths. These map directly to hyphen-separated CSS custom properties:
+
+```
+Figma:  background/interactive/cta/default
+CSS:    var(--background-interactive-cta-default)
+
+Figma:  font/size/body-l
+CSS:    var(--font-size-body-l)
+
+Figma:  borders/focus/primary
+CSS:    var(--borders-focus-primary)
+
+Figma:  color-text-primary
+CSS:    var(--color-text-primary)
+```
+
+### Three-tier model
+```
+Layer 1: Primitives     --primitive-neutral-900    (never use in components)
+Layer 2: Semantic       --color-text-primary        (use in components)
+Layer 3: Component      --color-surface-button-*    (component-specific overrides)
+```
+
+**Always use Layer 2 (semantic) tokens in components. Never reference Layer 1 (primitive) tokens directly in component styles.**
+
+### Key token families
+- `--color-text-*` → CSS `color` property
+- `--background-*` → CSS `background-color` property
+- `--borders-*` → CSS `border-color`, `outline-color`
+- `--color-surface-*` → component-specific background fills
+- `--color-dataviz-*` → all chart and data visualisation colors (series, axes, labels, backgrounds). Never use generic semantic tokens or hardcoded hex values for dataviz.
+- `--font-size-*`, `--font-weight-*`, `--font-line-height-*` → typography
+- `--space-*` → layout gaps (margin, gap) — between elements
+- `--inset-*` → component padding — inside components
+- `--page-margin-x` → horizontal spacing for all containers (pages, cards, modals, drawers, tables, lists, form sections). Always use this token. Never hardcode `padding-left`, `padding-right`, `margin-left`, or `margin-right`.
+- `--radius-*` → border-radius
+- `--border-width-*` → border-width
+- `--effects-elevation-*` → box-shadow
+- `--transition-*` → transition
+
+---
+
+## Component Generation Rules
+
+### Rule 1: Props = Figma variant properties
+Figma variant property names map directly to React prop names. Match them exactly.
+
+```
+Figma: Size=Medium, Variant=Primary, State=Default, Disabled=False, Loading=False
+React: size="md" variant="primary" state="default" disabled={false} loading={false}
+```
+
+Size name mapping (Figma → prop value):
+- `Small` → `"sm"`
+- `Medium` → `"md"`
+- `Large` → `"lg"`
+- `xLarge` → `"xl"`
+- `xxLarge` → `"2xl"`
+
+Boolean props extracted from Figma booleans:
+- `Disabled=True/False` → `disabled?: boolean`
+- `Loading=True/False` → `loading?: boolean`
+- `Selected=True/False` → `selected?: boolean`
+
+State is internal — never accept `state` as a prop. States are expressed via pseudo-classes and boolean props only.
+
+### Rule 2: TypeScript interfaces — explicit union types
+Every prop that corresponds to a Figma variant must be a TypeScript union type (not `string`).
+
+```typescript
+// CORRECT
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'plain';
+export type ButtonSize = 'sm' | 'md';
+
+// WRONG
+variant: string;
+size: string;
+```
+
+### Rule 3: Styled Components — tokens only, no hardcoded values
+No hex codes, no pixel values, no hardcoded rgba. Everything comes from tokens.
+
+```typescript
+// CORRECT
+background-color: var(--background-interactive-cta-default);
+font-size: var(--font-size-body-l);
+padding-inline: var(--page-margin-x);
+
+// WRONG
+background-color: #6941C6;
+font-size: 16px;
+padding: 0 24px;
+```
+
+### Rule 4: State implementation
+Interactive states use CSS pseudo-classes + `data-*` attributes. Never conditionally render different DOM elements for states.
+
+```typescript
+// Hover, press, focus — CSS pseudo-classes
+&:hover:not(:disabled) {
+  background-color: var(--background-interactive-cta-hover);
+}
+&:active:not(:disabled) {
+  background-color: var(--background-interactive-cta-pressed);
+}
+&:focus-visible {
+  outline: var(--border-width-focus) solid var(--borders-focus-primary);
+  outline-offset: 2px;
+}
+&:disabled {
+  opacity: 1; /* Never use opacity for disabled — use explicit disabled tokens */
+  background-color: var(--background-disabled);
+  color: var(--color-text-disabled);
+  cursor: not-allowed;
+}
+
+// Selected state — controlled via prop → data attribute
+const StyledButton = styled.button<{ $selected?: boolean }>`
+  background-color: ${({ $selected }) =>
+    $selected
+      ? 'var(--background-selected-strong)'
+      : 'var(--background-interactive-default-default)'
+  };
+`;
+```
+
+Use `$` prefix (transient props) for all Styled Components props that should not reach the DOM.
+
+### Rule 5: Focus states — always `:focus-visible`, never `:focus`
+```typescript
+// CORRECT
+&:focus-visible { outline: ... }
+
+// WRONG
+&:focus { outline: ... }
+// NEVER
+outline: none; /* without explicit replacement */
+```
+
+### Rule 6: Semantic HTML and ARIA
+Every component must use the correct HTML element and ARIA attributes. The Figma file cannot express this — the component docs are the source of truth.
+
+```typescript
+// Buttons
+<button type="button" disabled={disabled} aria-pressed={selected} aria-busy={loading}>
+
+// Form inputs — every input is mandatory by default
+// Do NOT mark required fields with an asterisk
+// Only add an "Optional" label (in var(--text-tertiary)) for fields that are not mandatory
+<input
+  type="text"
+  id={id}
+  aria-label={ariaLabel}
+  aria-describedby={helpTextId}
+  aria-invalid={error}
+  aria-required={true}   // all inputs mandatory by default; omit or set false for optional
+/>
+<label htmlFor={id}>{label}</label>
+
+// Loading state
+aria-busy="true"
+aria-label="Loading..."
+```
+
+### Rule 7: Storybook — CSF 3.0 format
+```typescript
+// Button.stories.tsx pattern
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Atoms/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost', 'plain'],
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md'],
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+// One story per meaningful variant combination
+export const Primary: Story = { args: { variant: 'primary', size: 'md', children: 'Button' } };
+export const Secondary: Story = { args: { variant: 'secondary', size: 'md', children: 'Button' } };
+export const Disabled: Story = { args: { variant: 'primary', size: 'md', disabled: true, children: 'Button' } };
+export const Loading: Story = { args: { variant: 'primary', size: 'md', loading: true, children: 'Button' } };
+
+// Interaction test example
+export const FocusInteraction: Story = {
+  args: { variant: 'primary', children: 'Focus me' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = canvas.getByRole('button');
+    await userEvent.tab();
+    expect(button).toHaveFocus();
+  },
+};
+```
+
+### Rule 8: File structure — one directory per component
+```
+Button/
+├── Button.tsx          ← Component implementation
+├── Button.stories.tsx  ← All stories for this component
+├── Button.test.tsx     ← Unit tests
+└── index.ts            ← Re-exports: export { Button } from './Button';
+```
+
+### Rule 9: Component generation order (atoms first)
+1. **Button** (covers: Main, Destructive, Toggle, Vertical)
+2. **Avatar** + **AvatarGroup**
+3. **Badge**
+4. **Tag**
+5. **Chip** + **ChipGroup**
+6. **Separator**
+7. **Switcher**
+8. **Checkbox**
+9. **Radio**
+10. **TextInput** (and shared Input anatomy)
+11. **TextArea**
+12. **SearchInput**
+13. **Select**
+14. **Slider**
+15. **Tab** (Navigation + Custom View)
+16. **SegmentControl**
+17. **Breadcrumbs**
+18. **Pagination**
+19. **Toast**
+20. **Tooltip**
+21. **Popover**
+22. **Modal**
+23. Remaining input types (Password, OTP, Number, Phone, DatePicker, etc.)
+
+### Rule 10: Dropdown/popover positioning contract
+All dropdown/select/popover menus must use the shared anchored behavior (via `PopoverWrapper`):
+- Default placement: below trigger
+- Gap: `var(--space-tiny)`
+- Flip: only when not enough room below
+- Viewport safe margin: `var(--space-medium)` from all edges
+- Horizontal clamping: keep popovers within safe viewport bounds
+- Width contract: match trigger width with a minimum popover width of `192px`
+- Overflow behavior: truncate menu labels when width is constrained
+
+Do not implement one-off absolute positioning per component. Reuse the shared `PopoverWrapper` contract for `Select`, `PhoneInput`, `DateTimePicker`, and future menu triggers.
+
+### Rule 11: Accessibility guardrails and CI gates
+Every contribution must preserve accessibility contracts:
+- For custom-role widgets (`menuitem`, `switch`, `checkbox`, `radio`, `slider`, `tab`, `gridcell`), add/maintain at least one keyboard interaction test.
+- Disabled components must not be focusable (`disabled` for native controls; otherwise `tabIndex={-1}` + `aria-disabled="true"`).
+- Nested interactive controls inside clickable rows must stop propagation so child actions do not trigger parent actions.
+- Focus rings must be implemented with `:focus-visible` (never `:focus` as the visible focus trigger).
+- Popup/dropdown tests must cover Arrow keys, Enter/Space selection, Escape close, and focus return to trigger.
+
+Storybook signal-quality policy:
+- Disabled/demo-only stories may use `parameters: { a11y: { disable: true } }` for intentional exceptions.
+- Keep a11y opt-outs story-scoped only; never disable at component meta/global level for interactive components.
+
+CI enforcement:
+- Run `npm run test:a11y:keyboard-widgets`.
+- Run `npm run test:a11y:stories:light`.
+- Run `npm run test:a11y:stories:dark`.
+
+### Rule 12: Icons — Lucide only
+The only permitted icon library is `lucide-react`. Never use browser/OS-native icons, emoji, or any other icon library anywhere in the component library.
+
+```typescript
+// CORRECT
+import { ArrowUpDown, X, Check } from 'lucide-react';
+
+// WRONG
+// Any icon not from lucide-react
+// System/OS native icons (e.g. ↕ ⬆ ⬇)
+// Emoji used as icons
+```
+
+### Rule 13: Placeholder content — never leave it in place
+Component slots for icons, help text, and hint icons must never ship with placeholder values.
+Either populate with real, meaningful content or hide the slot entirely.
+
+- **Icons** → replace with a relevant Lucide icon, or omit the slot
+- **Help text** → replace with genuinely useful guidance, or omit
+- **Hint icons** → replace with meaningful tooltip content, or omit
+
+### Rule 14: Form behavior
+- Every form field is **mandatory by default**. Never use a red asterisk to mark required fields.
+- Only mark optional fields, using an `"Optional"` label in `var(--text-tertiary)` placed inline after the label text.
+- The primary submit CTA must be **disabled** until all mandatory fields contain a value.
+- Validate all fields on submit only — not in real time as the user types.
+  - Exceptions: password strength, character count limits, search/filter fields, OTP.
+- The primary submit button must always display the `⌘↵` shortcut using the `Shortcut` component.
+
+```tsx
+// CORRECT — optional field
+<label>Team <span style={{ color: 'var(--text-tertiary)' }}>Optional</span></label>
+
+// CORRECT — primary submit button
+<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>
+
+// WRONG
+<label>First name *</label>   // never use asterisk
+```
+
+---
+
+## Accessibility Requirements
+
+- WCAG AA minimum: 4.5:1 contrast for normal text, 3:1 for large text
+- All interactive elements must be keyboard operable
+- Focus order must follow logical reading order (top to bottom, left to right)
+- Colour alone must never convey meaning — pair with text, icon, or pattern
+- Every form input must have an associated `<label>` (visible or `aria-label`)
+- All inputs carry `aria-required="true"` by default. Optional fields omit `aria-required` or set it to `false`. Never use a visual asterisk.
+- Loading states must use `aria-busy="true"` and a descriptive `aria-label`
+- Disabled elements must NOT be focusable (use `disabled` attribute on native elements, `tabIndex={-1}` + `aria-disabled="true"` on custom elements)
+- Closed disclosure components (Accordion, Popover, Dropdown) must not expose their children to keyboard focus until open
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Using primitive tokens in components.** `var(--primitive-neutral-900)` in a component style is wrong. Use `var(--color-text-primary)`.
+2. **Using `:focus` instead of `:focus-visible`.** Always `:focus-visible`.
+3. **Hardcoding hex values or pixel sizes.** Everything comes from tokens.
+4. **Accepting `state` as a prop.** States are pseudo-classes + boolean props, not a state prop.
+5. **Omitting aria attributes.** Always add ARIA from the component docs.
+6. **Not exporting from `index.ts`.** Every component needs `export { X } from './X'` in its own index.ts, and re-exported from `src/index.ts`.
+7. **Using opacity for disabled state.** Use explicit disabled tokens (`--background-disabled`, `--color-text-disabled`). Never `opacity: 0.5`.
+8. **Passing styled props directly to DOM.** Always use transient props (`$propName`) in Styled Components to prevent DOM attribute forwarding.
+9. **Using asterisks for required fields.** Every field is mandatory by default. Only mark optional fields with an `"Optional"` label in `var(--text-tertiary)`.
+10. **Leaving placeholder icons, help text, or hint icons in components.** Replace with real content or hide the slot entirely.
+11. **Using icons from any library other than Lucide.** Only `lucide-react` is permitted. No system icons, no emoji, no other libraries.
+12. **Hardcoding horizontal padding instead of `var(--page-margin-x)`.** All horizontal container spacing must use this token.
+13. **Enabling the primary CTA before all mandatory fields have a value.** The submit button must be disabled until the form is fillable.
+14. **Omitting `⌘↵` from the primary form submit button.** Always include the `Shortcut` component on the primary CTA.
+15. **Using dataviz colors from generic semantic tokens or hardcoded hex.** Always use `--color-dataviz-*` tokens for all chart and graph colors.
+
+---
+
+## Before Starting Each Component
+
+1. Read the component's doc file in `docs/`
+2. Identify all Figma variants → TypeScript props
+3. Identify all tokens needed (colour, typography, spacing, sizing)
+4. Implement component → stories → tests in that order
+5. Export from component `index.ts` and from `src/index.ts`