@veevarts/design-system 0.0.2 → 0.1.0

package/README.md

@@ -2,276 +2,70 @@
 
 This repository contains our **Design System**: a shared library of reusable UI components, design tokens, and utilities built with **React**, **TypeScript**, **Vite**, and **Storybook**.
 
-The goal of this project is to provide:
+## Goals
 
 - A **single source of truth** for UI across products.
 - **Reusable, well-typed, accessible components**.
 - **Discoverable documentation** via Storybook.
 
----
-
 ## Tech Stack
 
-- **React + TypeScript** – Component library implementation.
-- **Vite** – Fast dev server and build tooling.
-- **Storybook** – Component explorer and documentation.
-- **ESLint + TypeScript ESLint** – Linting and type-aware rules.
-- (Optional) **React Compiler** – Can be enabled if needed (see note below).
-
----
+- React + TypeScript
+- Vite
+- Storybook
+- ESLint + TypeScript ESLint
 
 ## Getting Started
 
 ### Prerequisites
 
 - Node.js (LTS, e.g. 18+ recommended)
-- pnpm / npm / yarn (examples below use `npm`)
+- npm / pnpm / yarn
 
-### Install dependencies
+### Install
 
 ```bash
 npm install
 ```
 
-### Run Storybook (recommended entrypoint)
+### Run Storybook
+
 ```bash
 npm run storybook
 ```
 
-This starts Storybook at http://localhost:6006 (or the configured port), where you can browse and interact with all components.
+### Run Dev Server
 
-### Run the Vite dev server (if applicable)
-
-If this repo also includes a small playground app:
 ```bash
 npm run dev
 ```
 
-This will start the Vite dev server (usually at http://localhost:5173).
-
 ### Build
 
-Build the component library / app:
 ```bash
 npm run build
 ```
-Build the Storybook static site (for deployment):
-```bash
-npm run build-storybook
-```
-npm run build-storybook
-```bash
-npm run build-storybook
-```
+
 ### Lint
+
 ```bash
 npm run lint
 ```
 
-## Project Structure (suggested)
+## Project Structure
 
-Your structure may vary slightly, but the Design System generally follows:
 ```
 src/
   components/
-    Button/
-      Button.tsx
-      Button.types.ts
-      Button.stories.tsx
-      Button.test.tsx     # if using tests
-      index.ts
-    Input/
-      ...
   styles/
-    tokens.css            # or tokens.ts, etc.
   utils/
-    ...
 .storybook/
-  main.ts
-  preview.tsx
 ```
 
-## Creating a New Reusable Component
-
-When adding a new component to the Design System, follow these steps:
-1.	Create a folder under src/components
-
-Example: src/components/Button.
-	
-2.	Create the component file
--	Use TypeScript and function components.
-- Export a named component and a typed props interface.
-
-  ```tsx
-  // src/components/Button/Button.tsx
-  import type { ButtonHTMLAttributes, ReactNode } from 'react';
-
-  export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-    variant?: 'primary' | 'secondary' | 'ghost';
-    size?: 'sm' | 'md' | 'lg';
-    isLoading?: boolean;
-    children: ReactNode;
-  }
-
-  export function Button({
-    variant = 'primary',
-    size = 'md',
-    isLoading = false,
-    children,
-    ...rest
-  }: ButtonProps) {
-    return (
-      <button
-        data-variant={variant}
-        data-size={size}
-        aria-busy={isLoading || undefined}
-        {...rest}
-      >
-        {isLoading ? 'Loading…' : children}
-      </button>
-    );
-  }
-  ```
-3. Create an index.ts barrel file
-
-    ```tsx
-    // src/components/Button/index.ts
-    export * from './Button';
-    ```
-4.	Create the Storybook stories
-  - Stories should live next to the component: Button.stories.tsx.
-  - Use Storybook CSF (default export + named stories).
-  - Document variants, states, and usage guidelines via args and docs.
-
-    ```tsx
-    // src/components/Button/Button.stories.tsx
-    import type { Meta, StoryObj } from '@storybook/react';
-    import { Button } from './Button';
-
-    const meta: Meta<typeof Button> = {
-      title: 'Components/Button',
-      component: Button,
-      args: {
-        children: 'Click me',
-        variant: 'primary',
-        size: 'md',
-      },
-    };
-
-    export default meta;
-    type Story = StoryObj<typeof Button>;
-
-    export const Primary: Story = {};
-    export const Secondary: Story = {
-      args: { variant: 'secondary' },
-    };
-    export const Loading: Story = {
-      args: { isLoading: true },
-    };
-    ```
-
-5.	Add tests
-- If the project uses a test runner (e.g. Vitest / Jest), add Button.test.tsx with basic behavior and accessibility tests.
-
-## Guidelines & Best Practices for Reusable Components
-
-1. Design System Principles
-- Generic, not app-specific
-Components must not depend on product-specific business logic. Keep them generic and configurable via props.
-- Composition over configuration
-Prefer small building blocks that can be composed, instead of monolithic components with many boolean flags.
-- Single responsibility
-Each component should do one thing well (e.g. Button, Input, Modal, Tooltip).
-- Stable API
-Avoid frequent breaking changes to props. If a change is necessary, deprecate carefully and communicate it.
-
-2. TypeScript & Props
-- Always export a typed props interface (ButtonProps, ModalProps, etc.).
-- Follow these patterns:
-- Use union types for variants ('primary' | 'secondary').
-- Prefer explicit props over any and broad object types.
-- Extend native HTML attributes when appropriate (e.g. ButtonHTMLAttributes<HTMLButtonElement>).
-- Provide sensible defaults for optional props.
-
-3. Styling & Theming
-- Use design tokens (colors, spacing, typography) instead of hard-coded values.
-- Keep component styling encapsulated and consistent:
-- Prefer using a shared tokens/styles system.
-- Avoid importing product-specific styles into the Design System.
-- Support variants and sizes through props, not through ad-hoc CSS classes.
-
-4. Accessibility (a11y)
-
-Every component should be built with accessibility in mind:
-- Ensure correct semantic elements (<button>, <label>, <input> etc.).
-- Use ARIA attributes only when necessary and correctly (avoid misusing them).
-- Keyboard support:
-- Focus states must be visible.
-- Interactive elements must be reachable and operable via keyboard.
-- Test with screen reader basics when possible (labels, roles, and announcements).
-
-5. Storybook Best Practices
-
-Stories are documentation, not just demos:
-- Provide a “Default” story that shows the most common usage.
-- Include stories for:
-- Different variants and sizes.
-- Loading / disabled / error states.
-- Edge cases that are relevant for consumers.
-- Use args so consumers can experiment via Storybook controls.
-- Use Storybook Docs to write short guidelines:
-- When to use the component.
-- Do’s & Don’ts.
-- Example integration snippets.
-
-6. Dependencies & Side Effects
-- Keep dependencies minimal and generic.
-- Avoid:
-- Direct calls to APIs.
-- Global singletons (e.g. accessing window without guards, global stores).
-- Side effects in component bodies (data fetching, logging, etc.).
-- If integration with external libraries is needed, wrap them in thin, replaceable adapters.
-
-## Linting & Type-Aware Rules
-
-For production-grade usage, we recommend enabling type-aware ESLint rules. A sample configuration using eslint.config.js might look like this:
+## Usage Example
 
 ```js
-// eslint.config.js
-import tseslint from 'typescript-eslint';
-import reactX from 'eslint-plugin-react-x';
-import reactDom from 'eslint-plugin-react-dom';
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Type-aware TypeScript rules
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, stricter rules:
-      // tseslint.configs.strictTypeChecked,
-      // Optional stylistic rules:
-      // tseslint.configs.stylisticTypeChecked,
-
-      // React-specific rules
-      reactX.configs['recommended-typescript'],
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-  },
-]);
+import { Button } from '@veevarts/design-system';
 ```
-Run npm run lint regularly, and ensure no new warnings or errors are introduced in pull requests.
 
-## Contributing
-- Before coding: Check if a similar component already exists or if an existing one can be extended.
-- Follow the guidelines above (types, a11y, tokens, stories).
-- Add or update stories so that your changes are visible in Storybook.
-- Run npm run lint and npm run test (if available) before opening a PR.
-- Keep PRs small and focused (one component or one concern per PR where possible).
+For contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).