docs(guidelines): document the component-level JSDoc block

[H4ad]

What

Why

How to verify

---

Component checklist (required for any change under packages/ui/src/)

Philosophy (guidelines)

• Variants represent meaningful roles (purpose), not one-off visual styling
• All applicable states handled: default, hover, active, selected, focus, disabled, loading, invalid, read-only
• Accessibility encoded in component: keyboard, focus, labels, ARIA (not left to consumer)
• Complex behaviours split into composable patterns, not crammed into conflicting props
• Escape hatches minimized; CSS overrides are last resort (if exception recurs, evolve the component)

Structure (guidelines)

• Directory is kebab-case under packages/ui/src/, matches the export subpath
• index.ts only re-exports (+ generated token region); export type * plus explicit named exports
• Relative imports use the .js extension; types imported with import type
• Subcomponents in subcomponents/, opinionated compositions in presets/
• All four lists updated: src/index.ts, vite.config.ts, package.json exports, README.md + intro.mdx
• New runtime deps added to externalPatterns

CSS (guidelines)

• {name}.module.scss, no Tailwind, no CVA, no Sass variables
• Every overridable value is var(--{component}-x, <design token>); no hardcoded values
• No literal fallback on a design token (var(--spacing-4, 8px)); a bare literal only where no token matches
• Colours use semantic tokens only, with no --bg-* / --text-* primitives referenced from a component
• Values that must not be overridden use --{component}-internal-*
• No --x: var(--x) and no duplicated variable definitions
• Variants are data-* attributes; data-slot and data-testid on the root
• color-mix() for derived shades, never rgba() over a token
• :hover, :focus-visible, aria-invalid, disabled all styled
• Transitions use the component's duration/easing tokens and are disabled under @media (prefers-reduced-motion: reduce)
• pnpm run tokens run and the index.ts region committed

Visual QA (guidelines)

• Compared against the Figma frame side by side: spacing, sizes, colours, every state
• Figma frame linked from the story via parameters.design
• Checked in light and dark
• Sizing and density consistent with sibling components (sm matches Button / Input)
• Typography via Typography or the type-scale tokens, not an ad-hoc font-size / font-weight
• Icons from @signozhq/icons, sized with tokens, no inline SVG with hardcoded px
• Every state built: default, hover, focus-visible, active, disabled, loading, invalid, selected, empty, long/truncated
• Not a duplicate of an existing primitive or preset

Types (guidelines)

• {Component}Props exported; only the props the component actually needs are exposed
• Upstream-owned prop types borrowed by indexed access (OriginalProps['x']), never restated by hand
• Every type named by a public prop is exported from index.ts
• forwardRef with a named render function (or displayName); testId supported
• Defaults in the destructuring; controlled/uncontrolled naming follows Radix

Docs (guidelines)

• JSDoc on every public prop, with @default where applicable
• Story file per exported component (@access private ones exempt), correct title group
• argTypes complete with category, type.summary, defaultValue.summary
• Stories for every meaningful state, not just the happy path
• {component}.mdx with a usage snippet and a <Controls> per exported piece

Tests (guidelines)

• Behaviour test per interactive prop
• forward-ref test
• run-visual-testing label added if the change is visual

pnpm lint
pnpm run type-check
pnpm build
pnpm -F @signozhq/ui test:run