@techv/design-system 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,416 @@
+# @techv/design-system
+
+A React component library and design token system. Single package — install once and get both UI components and design tokens.
+
+## Requirements
+
+| Peer dependency | Version |
+|---|---|
+| react | ^18.0.0 |
+| react-dom | ^18.0.0 |
+| styled-components | ^6.1.0 |
+
+## Installation
+
+```bash
+npm install @techv/design-system styled-components
+```
+```bash
+yarn add @techv/design-system styled-components
+```
+```bash
+pnpm add @techv/design-system styled-components
+```
+
+## Setup
+
+Import the global CSS in your app entry point. This loads the CSS custom properties (design tokens) and dark mode support.
+
+```tsx
+// index.tsx or App.tsx
+import '@techv/design-system/styles.css';
+```
+
+---
+
+## Components
+
+### Button
+
+```tsx
+import { Button } from '@techv/design-system';
+
+export default function App() {
+  return <Button>Click me</Button>;
+}
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `solid` \| `outline` \| `ghost` \| `soft` \| `link` | `solid` | Visual style |
+| `color` | `brand` \| `danger` \| `success` \| `warning` \| `neutral` | `brand` | Color scheme |
+| `size` | `xs` \| `sm` \| `md` \| `lg` \| `xl` | `md` | Button size |
+| `isLoading` | `boolean` | `false` | Shows a spinner and disables the button |
+| `leftIcon` | `ReactNode` | — | Icon rendered before the label |
+| `rightIcon` | `ReactNode` | — | Icon rendered after the label |
+| `disabled` | `boolean` | `false` | Disables the button |
+
+Accepts all standard HTML `<button>` attributes.
+
+#### Variants
+
+```tsx
+<Button variant="solid">Solid</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="soft">Soft</Button>
+<Button variant="link">Link</Button>
+```
+
+#### Colors
+
+```tsx
+<Button color="brand">Brand</Button>
+<Button color="danger">Danger</Button>
+<Button color="success">Success</Button>
+<Button color="warning">Warning</Button>
+<Button color="neutral">Neutral</Button>
+```
+
+#### Sizes
+
+```tsx
+<Button size="xs">Extra Small</Button>
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+<Button size="xl">Extra Large</Button>
+```
+
+#### With icons
+
+```tsx
+<Button leftIcon={<SearchIcon />}>Search</Button>
+<Button rightIcon={<ArrowRightIcon />}>Next</Button>
+```
+
+#### Loading state
+
+```tsx
+<Button isLoading>Saving...</Button>
+```
+
+---
+
+### IconButton
+
+A square button that holds a single icon. Requires `aria-label` for accessibility.
+
+```tsx
+import { IconButton } from '@techv/design-system';
+
+<IconButton icon={<SearchIcon />} aria-label="Search" />
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | **required** | The icon to display |
+| `aria-label` | `string` | **required** | Accessible label |
+| `variant` | `solid` \| `outline` \| `ghost` \| `soft` \| `link` | `solid` | Visual style |
+| `color` | `brand` \| `danger` \| `success` \| `warning` \| `neutral` | `brand` | Color scheme |
+| `size` | `xs` \| `sm` \| `md` \| `lg` \| `xl` | `md` | Button size |
+| `isLoading` | `boolean` | `false` | Shows a spinner |
+| `disabled` | `boolean` | `false` | Disables the button |
+
+---
+
+## Design Tokens
+
+### CSS Custom Properties
+
+Import `styles.css` to get all tokens as CSS variables on `:root`, usable anywhere in your app.
+
+```css
+.my-component {
+  background-color: var(--color-brand-500);
+  padding: var(--space-md);
+  border-radius: var(--radius-lg);
+}
+```
+
+### JavaScript Tokens
+
+#### Inline styles
+
+Use tokens directly in React `style` props:
+
+```tsx
+import { tokens, colors, spacing, radii } from '@techv/design-system';
+
+function Badge({ children }: { children: React.ReactNode }) {
+  return (
+    <span
+      style={{
+        backgroundColor: tokens.color.brand[50],   // '#EEF2FF'
+        color: tokens.color.brand[700],             // '#3730A3'
+        padding: `${tokens.space.xs}px ${tokens.space.sm}px`, // '4px 8px'
+        borderRadius: tokens.radius.full,           // 9999
+        fontSize: tokens.fontSize.caption,          // '12px'
+        fontFamily: tokens.font.text,               // 'Inter'
+      }}
+    >
+      {children}
+    </span>
+  );
+}
+```
+
+#### Alert / status banner
+
+```tsx
+import { tokens, colors } from '@techv/design-system';
+
+type AlertType = 'success' | 'danger' | 'warning';
+
+const alertStyles: Record<AlertType, React.CSSProperties> = {
+  success: {
+    backgroundColor: tokens.color.success[50],   // '#ECFDF5'
+    color: tokens.color.success[500],            // '#10B981'
+    border: `1px solid ${tokens.color.success[500]}`,
+  },
+  danger: {
+    backgroundColor: tokens.color.danger[50],    // '#FEF2F2'
+    color: tokens.color.danger[500],             // '#EF4444'
+    border: `1px solid ${tokens.color.danger[500]}`,
+  },
+  warning: {
+    backgroundColor: tokens.color.warning[50],   // '#FFFBEB'
+    color: tokens.color.warning[500],            // '#F59E0B'
+    border: `1px solid ${tokens.color.warning[500]}`,
+  },
+};
+
+function Alert({ type, message }: { type: AlertType; message: string }) {
+  return (
+    <div
+      role="alert"
+      style={{
+        ...alertStyles[type],
+        padding: `${tokens.space.sm}px ${tokens.space.md}px`, // '8px 16px'
+        borderRadius: tokens.radius.md,                        // 6
+        fontSize: tokens.fontSize.bodyMd,                      // '14px'
+      }}
+    >
+      {message}
+    </div>
+  );
+}
+
+// Usage
+<Alert type="success" message="Profile saved!" />
+<Alert type="danger" message="Something went wrong." />
+<Alert type="warning" message="Your session expires soon." />
+```
+
+#### Card component
+
+```tsx
+import { tokens } from '@techv/design-system';
+
+function Card({ title, body }: { title: string; body: string }) {
+  return (
+    <div
+      style={{
+        backgroundColor: tokens.semantic.surface,  // '#FFFFFF'
+        border: `1px solid ${tokens.semantic.border}`, // '#E5E7EB'
+        borderRadius: tokens.radius['2xl'],         // 16
+        padding: tokens.space.xl,                   // 32
+        boxShadow: tokens.shadow.md,
+        maxWidth: '400px',
+      }}
+    >
+      <h2
+        style={{
+          margin: 0,
+          fontSize: tokens.fontSize.h4,             // '18px'
+          color: tokens.semantic.textPrimary,        // '#111827'
+          marginBottom: tokens.space.sm,             // 8
+        }}
+      >
+        {title}
+      </h2>
+      <p
+        style={{
+          margin: 0,
+          fontSize: tokens.fontSize.bodyMd,          // '14px'
+          color: tokens.semantic.textSecondary,       // '#6B7280'
+          lineHeight: 1.6,
+        }}
+      >
+        {body}
+      </p>
+    </div>
+  );
+}
+```
+
+#### Using flat `colors` / `spacing` / `radii` exports
+
+```tsx
+import { colors, spacing, radii } from '@techv/design-system';
+
+function Tag({ label }: { label: string }) {
+  return (
+    <span
+      style={{
+        backgroundColor: colors.gray100,   // '#F3F4F6'
+        color: colors.gray700,             // '#374151'
+        padding: `${spacing.xs} ${spacing.sm}`, // '4px 8px'
+        borderRadius: radii.sm,            // '4px'
+        border: `1px solid ${colors.border}`, // '#E5E7EB'
+      }}
+    >
+      {label}
+    </span>
+  );
+}
+```
+
+#### Animated element using duration + easing tokens
+
+```tsx
+import { tokens } from '@techv/design-system';
+
+function FadeInBox({ children }: { children: React.ReactNode }) {
+  return (
+    <div
+      style={{
+        padding: tokens.space.lg,         // 24
+        backgroundColor: tokens.color.brand[50],
+        borderRadius: tokens.radius.xl,   // 12
+        transition: `opacity ${tokens.duration.normal}ms ${tokens.ease.standard}`,
+                     // 200ms cubic-bezier(0.4, 0, 0.2, 1)
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+#### Quick reference
+
+```tsx
+import { tokens, colors, spacing, radii } from '@techv/design-system';
+
+// tokens — full structured object
+tokens.color.brand[500]      // '#4F46E5'
+tokens.color.gray[200]       // '#E5E7EB'
+tokens.space.md              // 16  (number, use as px)
+tokens.radius.lg             // 8   (number, use as px)
+tokens.shadow.md             // '0 4px 6px rgba(0,0,0,0.07)...'
+tokens.duration.normal       // 200 (number, ms)
+tokens.ease.standard         // 'cubic-bezier(0.4, 0, 0.2, 1)'
+tokens.font.text             // 'Inter'
+tokens.fontSize.h1           // '36px'
+tokens.semantic.textPrimary  // '#111827'
+
+// colors — flat convenience object
+colors.brand500              // '#4F46E5'
+colors.textPrimary           // '#111827'
+colors.border                // '#E5E7EB'
+
+// spacing — string values ready for CSS
+spacing.md                   // '16px'
+spacing.lg                   // '24px'
+
+// radii — string values ready for CSS
+radii.sm                     // '4px'
+radii.full                   // '9999px'
+```
+
+### Token Reference
+
+#### Colors
+
+| Token | Value |
+|---|---|
+| `brand 50–900` | Indigo scale |
+| `success 50, 500` | Green |
+| `danger 50, 500` | Red |
+| `warning 50, 500` | Amber |
+| `info 50, 500` | Blue |
+| `gray 50–900` | Neutral gray scale |
+
+#### Spacing
+
+| Token | Value |
+|---|---|
+| `2xs` | 2px |
+| `xs` | 4px |
+| `sm` | 8px |
+| `md` | 16px |
+| `lg` | 24px |
+| `xl` | 32px |
+| `2xl` | 48px |
+| `3xl` | 64px |
+
+#### Border radius
+
+| Token | Value |
+|---|---|
+| `none` | 0 |
+| `xs` | 2px |
+| `sm` | 4px |
+| `md` | 6px |
+| `lg` | 8px |
+| `xl` | 12px |
+| `2xl` | 16px |
+| `full` | 9999px |
+
+---
+
+## Dark mode
+
+The library ships with a built-in dark mode. Toggle it by setting `data-theme="dark"` on any ancestor element (typically `<html>` or `<body>`).
+
+```tsx
+// Enable dark mode
+document.documentElement.setAttribute('data-theme', 'dark');
+
+// Disable dark mode
+document.documentElement.removeAttribute('data-theme');
+```
+
+All components and CSS custom properties respond automatically.
+
+---
+
+## TypeScript
+
+Full TypeScript support is included. All component props and token types are exported.
+
+```tsx
+import type { ButtonProps, IconButtonProps } from '@techv/design-system';
+```
+
+---
+
+## Using tokens in styled-components
+
+```tsx
+import styled from 'styled-components';
+import { tokens } from '@techv/design-system';
+
+const Card = styled.div`
+  background: ${tokens.semantic.surface};
+  border: 1px solid ${tokens.semantic.border};
+  border-radius: ${tokens.radius.xl}px;
+  padding: ${tokens.space.lg}px;
+  box-shadow: ${tokens.shadow.md};
+`;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techv/design-system",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "author": "Pranav V K <pranavvk@techversantinfotech.com>",
   "license": "MIT",
   "main": "./dist/cjs/index.js",
@@ -20,7 +20,8 @@
     "./styles.css": "./dist/styles.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "sideEffects": [
     "./dist/styles.css"
@@ -38,8 +39,8 @@
     "ts-node": "^10.9.2",
     "tslib": "^2.6.2",
     "typescript": "~5.4.5",
-    "@techv/tokens": "0.1.0",
-    "@techv/ui": "0.1.0"
+    "@techv/ui": "0.1.0",
+    "@techv/tokens": "0.1.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",