npm package: @gastondvoskin/design-system-poc
Description: A minimal React design system library with TypeScript support.
Latest version: 0.1.5

# Design System POC

A minimal React design system library with TypeScript support.

## 📦 Installation

```bash
pnpm add @gastondvoskin/design-system-poc
```

### Update version
```bash
pnpm update @gastondvoskin/design-system-poc
```


## 🚀 Quick Start

```tsx
import { Button, Input } from "@gastondvoskin/design-system-poc";

function App() {
  const [value, setValue] = useState("");

  return (
    <div>
      <Button onClick={() => console.log("Clicked!")}>Click me</Button>

      <Input value={value} onChange={setValue} placeholder="Enter text..." />
    </div>
  );
}
```

## 📋 Available Components

- **Button** - Simple button with hover and disabled states
- **Input** - Text input with focus states and type support

## 🛠️ Development

### Setup

```bash
git clone https://github.com/gastondvoskin/design-system-poc.git
cd design-system-poc
pnpm install
```

### Make Changes

1. Edit components in `src/components`

### Build & Publish

1. Update CHANGELOG.md
2. Update version in package.json: `pnpm version patch` (or `pnpm version minor` or `pnpm version major`)
3. Run `pnpm build:lib` (equivalent to `pnpm exec tsc -p tsconfig.lib.json`)
4. Login to npm (if not already logged in) `npm login`
5. Publish the package `npm publish --access public`



### Test in Another Project

```bash
# Create new project
pnpm create vite test-project
cd test-project

# Install the design system
pnpm add @gastondvoskin/design-system-poc
# or update the package
pnpm update @gastondvoskin/design-system-poc

# Start development
pnpm dev
```

## 📝 Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.




## 1. Objective

Create a **minimalist design system**, developed in **React + TypeScript + Vite + TailwindCSS**, oriented to be **multi-brand** and compatible with **Storybook** for documentation and preview.
The objective of this POC is to go through **the entire process**: tokens → components → package publication → consumption.
This is not an MVP or final product, just a functional proof of concept.

---

## 2. Principles

- **Functional minimalism:** cover only a subset of elements.
- **Multi-brand scalability:** a single core with brand overrides using `[data-brand]`.
- **Accessibility:** WCAG 2.2 AA compliance.
- **Clear design:** light theme only.
- **Clean code:** ESLint + Prettier + Tailwind plugin.
- **Visual consistency:** shared tokens, uniform typography, regular spacing.

---

## 3. Technical Stack

| Area            | Technology                         |
| --------------- | ---------------------------------- |
| Bundler         | **Vite** (library mode)            |
| Framework       | **React + TypeScript**             |
| Styles          | **TailwindCSS + CSS variables**    |
| Docs / Demos    | **Storybook**                      |
| Tests           | **Vitest + React Testing Library** |
| Package Manager | **pnpm**                           |
| CI              | **GitHub Actions**                 |
| Node            | LTS                                |

---

## 4. Structure

```

design-system-poc/
├── src/
│ ├── tokens/ # design tokens (color, spacing, radius, shadows)
│ ├── components/
│ │ ├── primitives/ # Button, Input, Select, etc.
│ │ ├── composed/ # Navbar, Header, Card, Modal, Alert
│ │ └── utils/ # Spinner, helpers
│ ├── main.tsx # central export
│ └── styles/
│ └── tailwind.css
├── index.html # entry point
├── .storybook/ # configuration and stories
├── package.json
├── tailwind.config.ts
├── tsconfig.json
├── README.md # this file
└── LICENSE (private)

```

---

## 5. Design tokens

Usar **CSS variables** como fuente única de verdad.

```css
:root {
  --color-primary: #00aaff;
  --color-secondary: #76c7f1;
  --color-bg: #ffffff;
  --color-text: #1a1a1a;
  --radius-sm: 2px;
  --radius-md: 4px;
  --radius-lg: 8px;
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 2px 4px rgba(0, 0, 0, 0.1);
}

[data-brand="aspel"] {
  --color-primary: #2c6bff;
}

[data-brand="contifico"] {
  --color-primary: #00c389;
}
```

Tailwind should read these variables in theme.extend.

## 6. Base Scales

- **Spacing:** 0 2 4 8 12 16 24 32 40 48 64
- **Radius:** 2 4 8 12
- **Shadows:** sm md lg
- **Typography:** fallback Inter, system-ui.

---

## 7. Components

### Foundations

Color, typography, spacing, radius, shadows.

### Primitives

Button, Input, Select, Checkbox, Radio, Switch, Textarea, Link.

### Composed

Navbar, Header (hero), Card, Modal, Alert.

### Utility

Spinner.

Each component:

- Accessible props (aria-label, role, etc.).
- States: default, hover, active, disabled, focus.

---

## 8. Storybook

- Each component has its .stories.tsx file.
- Include "demos" with real combinations (registration form, plan card).
- Control props from Controls panel.
- Also used for visual snapshots (@storybook/test-runner or Chromatic).

**Example structure:**

```
src/components/primitives/Button/Button.tsx
src/components/primitives/Button/Button.stories.tsx
```

**Base scripts:**

```json
"scripts": {
  "dev": "pnpm vite",
  "build": "pnpm vite build",
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build",
  "lint": "eslint .",
  "test": "vitest run"
}
```

---

## 9. Publication (FUTURE. NOT NOW)

Private package @design-system-poc.

**Steps:**

```bash
pnpm build
pnpm publish --access restricted
```

**Consumption in another project:**

```bash
pnpm add @design-system-poc
```

---

## 10. Minimal CI (GitHub Actions) (FUTURE. NOT NOW)

- Run lint, test and build on each PR.
- Generate Storybook preview (Chromatic or private GitHub Pages).

---

## 11. Accessibility

- AA contrast in text and interactive elements.
- Visible focus on all controls.
- Complete keyboard navigation.
- No unnecessary motion.