npm package: @reinvented/design
Description: The opinionated visual foundation for all Reinvented apps. Components, patterns, layouts, conventions, rules, and documentation.
Latest version: 1.2.1

# Reinvented Design System

The opinionated visual foundation for all Reinvented apps. Components, patterns, layouts, conventions, rules, and documentation.

## Quick Start

```bash
npm install @reinvented/design
```

```vue
<script setup>
import { Button, Card, Input, Badge, Dialog } from '@reinvented/design'
</script>
```

## Stack

- **Components**: [Shadcn-vue](https://www.shadcn-vue.com/) (all components, styled with our tokens)
- **Primitives**: [Radix Vue](https://www.radix-vue.com/) (accessible headless components)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/) with design tokens
- **Icons**: [Lucide Vue Next](https://lucide.dev/) (no emojis, ever)
- **Typography**: Inter (via Google Fonts)
- **Linting**: Built-in ESLint plugin enforcing design rules

---

## Consumer Setup

### 1. Install dependencies

```bash
# The design system (includes all component + ESLint deps)
npm install @reinvented/design

# Required dev dependencies for Tailwind CSS processing
npm install -D tailwindcss@^3.4 postcss@^8.4 autoprefixer@^10.4 tailwindcss-animate@^1.0
```

### 2. Tailwind CSS config

Create `tailwind.config.js` in your app root. **Extend** the DS config — this gives you all design tokens, theme colors, animations, and font family:

```js
import baseConfig from '@reinvented/design/tailwind.config.js'

export default {
  ...baseConfig,
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
    // Include DS source so Tailwind picks up classes used inside components
    './node_modules/@reinvented/design/src/**/*.{vue,ts}',
  ],
}
```

### 3. PostCSS config

Create `postcss.config.js`:

```js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

### 4. CSS entry point

Create `src/assets/main.css` (or similar) and import the DS styles. This loads the design tokens (CSS variables) and Tailwind directives:

```css
@import '@reinvented/design/styles';
```

Then import it in your app entry (`main.js` or `main.ts`):

```js
import './assets/main.css'
```

### 5. Dark mode

The DS uses the `class` strategy for dark mode. Add `class="dark"` to `<html>` for dark theme:

```html
<html lang="en" class="dark">
```

All color tokens automatically switch between light and dark values.

### 6. ESLint (recommended)

The DS ships an ESLint plugin that enforces design system rules. Create `eslint.config.js`:

```js
import recommended from '@reinvented/design/eslint/recommended'

export default [
  ...recommended,
  // Your custom overrides (optional)
]
```

This enables:

| Rule | Severity | What it catches |
|------|----------|-----------------|
| `no-raw-button` | error | Raw `<button>` → use `<Button>` |
| `no-raw-input` | error | Raw `<input>` → use `<Input>` |
| `no-raw-select` | error | Raw `<select>` → use `<Select>` |
| `no-raw-textarea` | error | Raw `<textarea>` → use `<Textarea>` |
| `no-browser-dialogs` | error | `alert()`, `confirm()`, `prompt()` → use Dialog/Toast |
| `no-emoji` | error | Emoji characters → use Lucide icons |
| `no-hardcoded-colors` | warn | Inline hex/rgb colors → use token variables |
| `no-arbitrary-tailwind` | warn | `text-[#333]` → use token classes |

Install ESLint if not already present:

```bash
npm install -D eslint
```

---

## Structure

```
src/
  components/ui/    All styled components
  patterns/         Reusable compositions (ListView, DetailView, etc.)
  layouts/          Page-level layout components with slots
  lib/              Utilities (cn, etc.)
  styles/           Tokens, CSS variables
  eslint/           ESLint plugin + recommended config
docs/
  rules.md          Hard design rules
  conventions.md    Opinionated UX decisions
  visual-polish.md  Animations, transitions, polish guidelines
  components/       Per-component usage guides
  patterns/         Per-pattern docs with skeleton code
  layouts/          Per-layout docs with skeleton code
examples/           Full skeleton examples
```

## Documentation

- **[Rules](docs/rules.md)** — Non-negotiable design constraints
- **[Conventions](docs/conventions.md)** — Opinionated UX decisions
- **[Visual Polish](docs/visual-polish.md)** — Animation and polish guide
- **[Components](docs/components/index.md)** — Component usage guides
- **[Patterns](docs/patterns/index.md)** — Reusable UI patterns
- **[Layouts](docs/layouts/index.md)** — Page layout recipes
- **[AI Agent Guide](SKILL.md)** — Full design system skill guide for AI agents

## Contributing

Agents and humans can propose changes via PRs. See [conventions](docs/conventions.md) for design principles.