RG Design System Template – Developer Guide

A scalable, reusable React + TypeScript component library with Vite, Tailwind CSS, Storybook, ESLint, and Vitest. This README helps new contributors understand the structure, conventions, and workflows to confidently add or update code and resolve issues.

Stack

• React 19, TypeScript 5, Vite 6
• Tailwind CSS 4 (with @tailwindcss/vite); PostCSS for CSS build
• Storybook 8 (React + Vite)
• Vitest 3 + Testing Library + JSDOM
• ESLint 9 (typescript-eslint, react-hooks, react-refresh)
• Rollup for library bundling (ESM + CJS + DTS)

Project Structure

.
├─ src/
│  ├─ assets/
│  │  └─ style/                 # Base CSS tokens and utilities (compiled into dist/style.css)
│  ├─ components/
│  │  ├─ <ComponentName>/       # One folder per public component
│  │  │  ├─ index.tsx           # Component implementation (export default/named)
│  │  │  ├─ _.style.ts          # Styles (e.g., cva, class composition)
│  │  │  ├─ _.types.ts|type.ts  # Component props/types
│  │  │  ├─ _.stories.tsx       # Storybook stories
│  │  │  └─ _.test.tsx          # Unit tests (Vitest + Testing Library)
│  │  ├─ developers/            # Showcase profiles (excluded from coverage)
│  │  └─ ui/                    # Internal building blocks (not public API)
│  ├─ hooks/                    # Reusable hooks
│  ├─ icons/                    # Icon components + types (excluded from coverage)
│  ├─ lib/                      # Utilities shared by components
│  ├─ index.ts                  # Library public exports
│  ├─ index.css                 # Tailwind entry (built via PostCSS)
│  └─ main.tsx                  # Local playground entry (not part of build output)
├─ tests/setup.ts               # Vitest setup (jsdom, matchers)
├─ vite.config.ts               # Vite + Vitest base config (alias '@' → './src')
├─ vitest.config.ts             # Test include/exclude and coverage rules
├─ eslint.config.js             # ESLint rules and TS integration
├─ postcss.config.mjs           # PostCSS pipeline (imports, autoprefixer)
├─ rollup.config.mjs            # Library bundle (esm/cjs/dts) for publish
├─ package.json                 # Scripts, exports, deps, peer deps
├─ dist/                        # Build output (ignored in dev)
└─ public/                      # Static assets used by Storybook/demo

Naming and File Conventions

• Component folders are PascalCase and contain the standard set: index.tsx, _.style.ts, _.types.ts (or type.ts), _.stories.tsx, _.test.tsx.
• Internal-only primitives live under src/components/ui and should not be exported from the library root.
• The alias @ resolves to ./src (import like import { cn } from '@/lib/utils').
• CSS tokens live in src/assets/style/*.css; the library bundles dist/style.css (see exports in package.json).

Getting Started

Prereqs: Node 18+ (or 20+), PNPM recommended.

Install dependencies:

pnpm install

Run the dev playground (Vite):

pnpm dev

Open Storybook for component docs:

pnpm story

Run tests:

pnpm test

Run tests with coverage:

pnpm coverage

Lint the repo:

pnpm lint

Build the library (types + CSS + bundles):

pnpm build

Full release build (test → vite build → rollup):

pnpm rollup

Exports and Consumers

package.json exposes:

• ESM: dist/index.mjs
• CJS: dist/index.js
• Types: dist/index.d.ts
• CSS: dist/style.css (via subpath export)

Consumers can:

import { Button } from 'rg-dst';
import 'rg-dst/dist/style.css';

Adding a New Component

1. Scaffold folder: src/components/<ComponentName>/ with files:

• index.tsx – component implementation
• _.types.ts – define prop types; export ComponentNameProps
• _.style.ts – class builders (e.g., with class-variance-authority) and helpers
• _.stories.tsx – at least default and variants stories
• _.test.tsx – render, states, a11y basics

2. Implement component:

• Keep public API small and typed. Prefer controlled props where appropriate.
• Compose classes using clsx/cva. Do not inline large style strings.
• Avoid leaking internal implementation details through props.

3. Export from library:

• Re-export from src/components/index.ts or src/index.ts according to the existing pattern.

4. Document in Storybook:

• Include controls for all public props.
• Add usage notes and edge cases in stories or MDX docs.

5. Tests:

• Use @testing-library/react with JSDOM.
• Cover critical behaviors, keyboard interactions, and edge states.
• Place snapshots only for minimal structural assurance (avoid brittle snapshots).

6. Styles and Tokens:

• Reuse tokens from src/assets/style/* when possible.
• If adding new primitive tokens, update CSS files with clear, scoped variables.

Updating an Existing Component

1. Search for usages across stories, tests, and src/components/ui primitives before changing prop names or behavior.

2. Maintain backward compatibility when feasible. If a breaking change is necessary:

• Adjust stories and tests.
• Update release notes and communicate migration steps in the PR description.

3. Keep _.types.ts as the single source of truth for props and update stories/tests accordingly.

4. Performance and a11y:

• Use React.memo/useMemo only when it removes real work; avoid premature optimization.
• Ensure focus management and ARIA attributes are correct (especially for interactive components).

Testing & Coverage

Vitest is configured with JSDOM and global test APIs. Defaults:

• Includes: src/**/*.test.{ts,tsx}, src/**/*.spec.{ts,tsx}
• Excludes: node_modules, dist, **/*.stories.tsx, **/*.style.ts, **/*.types.ts, src/icons/**/*.{ts,tsx}

Coverage includes src/**/*.{ts,tsx} with further excludes:

• Stories, styles, types, icons
• src/components/developers/**
• tests/**, dist/**, src/main.tsx, src/vite-env.d.ts

Command hints:

pnpm test            # run unit tests
pnpm coverage        # generate text/json/html coverage

Linting & Code Style

ESLint rules are defined in eslint.config.js:

• Typescript-eslint recommended rules
• React hooks rules enforced
• @typescript-eslint/no-explicit-any is disabled where pragmatic
• react-refresh/only-export-components warned to keep HMR-friendly exports

Guidelines:

• Prefer clear, descriptive names over abbreviations.
• Keep components focused; extract internal UI into src/components/ui.
• Minimal comments; only for non-obvious rationale or caveats.
• Early returns over deep nesting; avoid broad try/catch.

Styles & Theming

• Tailwind via Vite plugin; utility composition preferred.
• Shared tokens and utilities live in src/assets/style/*.css.
• Library CSS is built with pnpm build:css to dist/style.css. Consumers must import it.

Icons

• Add icons to src/icons/general as React components.
• Keep icon types in src/icons/icons.type.ts.
• Icons are excluded from test coverage; still add basic validation where necessary.

Aliases

@ → ./src (configured in both vite.config.ts and vitest.config.ts). Example:

import { cn } from '@/lib/utils'

Scripts (from package.json)

• pnpm dev – Start Vite dev server (with --host for LAN testing)
• pnpm build:css – Build src/index.css to dist/style.css via PostCSS
• pnpm build – TypeScript build + CSS build + Vite build
• pnpm rollup – Run tests, Vite build, and Rollup bundle (esm/cjs/dts)
• pnpm story – Run Storybook on port 6006
• pnpm build-storybook – Generate static Storybook
• pnpm test – Run Vitest
• pnpm coverage – Vitest with coverage
• pnpm lint – Run ESLint

Publishing Notes

• Ensure peerDependencies for react and react-dom are correct.
• Verify exports map and types in package.json.
• Run pnpm rollup and verify dist/ contains .mjs, .js, .d.ts, and style.css.

Troubleshooting

• Dev server fails to start

  • Delete node_modules and lockfile, then pnpm install.
  • Ensure Node version ≥ 18.

• Storybook cannot resolve @ alias

  • Restart Storybook after changes to vite.config.ts.
  • Confirm alias is set in both vite.config.ts and Storybook config (React-Vite preset handles this).

• Tests fail with DOM-related errors

  • Ensure jsdom environment is set (it is in config). Check tests/setup.ts path.

• Coverage missing for new files

  • Confirm files are within src/ and not in an excluded pattern.

• Styles not applied in consumer app

  • Remind consumers to import 'rg-dst/dist/style.css'.

Contribution Workflow

1. Create a feature branch: git checkout -b feat/<short-name>
2. Implement changes with stories and tests.
3. Run pnpm lint && pnpm test && pnpm build locally.
4. Open a PR with:
   • Summary of changes
   • Screenshots (stories) if visual
   • Breaking changes and migration notes
5. Request review; address feedback; squash and merge.

Questions or issues? Open an issue with context, repro steps, and environment details.