# Getting Started — TVU Design System (5 min)
This guide walks you from zero to rendering your first TVU component in a fresh Vue 3 project. ~5 minutes.
For the cross-AI workflow contract (Claude / Codex / Cursor / Cline), see [`AGENTS.md`](../AGENTS.md). For full product goals, see [`docs/PROJECT_GOAL.md`](./PROJECT_GOAL.md).
---
## 1. Create a Vue 3 project
If you already have a Vue 3 + TypeScript project, skip to step 2.
```bash
npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install
```
(Replace `npm` with `pnpm` / `yarn` if preferred — the rest of this guide assumes `pnpm`.)
---
## 2. Install the design system
```bash
pnpm add @nancyzeng0210/tvu-design-system
```
`vue@^3.4.0` is a peer dependency and should already be in your project.
---
## 3. Import token CSS (required)
TVU Design System components rely on CSS variables for colors, spacing, typography, and theme switching. **You must import the bundled stylesheet once**, typically in `main.ts`:
```typescript
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import '@nancyzeng0210/tvu-design-system/style.css'
createApp(App).mount('#app')
```
Without this import, components will render unstyled (no token resolution).
---
## 4. Pick an import mode
You have two options. Both are supported; pick what fits your project.
### Option A — Global registration (simplest)
Register the whole library once; use any component by tag name anywhere:
```typescript
// src/main.ts
import { createApp } from 'vue'
import TVUDesignSystem from '@nancyzeng0210/tvu-design-system'
import '@nancyzeng0210/tvu-design-system/style.css'
import App from './App.vue'
createApp(App).use(TVUDesignSystem).mount('#app')
```
Then in any `.vue` file:
```vue
```
### Option B — Per-component import (tree-shake friendly)
Skip `.use(TVUDesignSystem)` and import each component locally:
```vue
```
Option B keeps your bundle smaller if you only use a few components.
---
## 5. Render your first component — Button
Create `src/App.vue`:
```vue
Hello TVU
```
Run the dev server:
```bash
pnpm dev
```
Open `http://localhost:5173` — you should see a green "Save" button and a gray ghost "Cancel" button on a dark background (dark is the default theme).
---
## 6. Toggle the theme
The design system ships with a complete dark / light theme system driven by `data-theme` on ``. Default is dark. Switch to light at runtime:
```typescript
document.documentElement.setAttribute('data-theme', 'light')
```
Switch back to dark:
```typescript
document.documentElement.setAttribute('data-theme', 'dark')
```
All component colors, surfaces, borders, and shadows respond automatically — no per-component prop needed.
To make a toggle button:
```vue
```
---
## 7. Next steps
- Browse all 29 components and their full props / events / slots in the local docs site: `pnpm dev` in the design system repo → `http://localhost:5173`
- Read [`AGENTS.md`](../AGENTS.md) for the AI-assisted Figma → code workflow if you're using Claude / Codex / Cursor with this library
- See the [`README.md`](../README.md) Icons section for icon usage (``) including React / CDN consumption modes
---
## Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Components render unstyled | Forgot `import '@nancyzeng0210/tvu-design-system/style.css'` | Add the import to `main.ts` |
| TypeScript "cannot find module" | Vue version < 3.4 | Upgrade `vue` to `^3.4.0` (peer dep) |
| Icons show as empty boxes | Using legacy alias not in catalog | Use `category/name` form (e.g. `time/clock`), not legacy aliases |
| Theme toggle doesn't update colors | Setting attribute on wrong element | Must be `` element (`document.documentElement`), not `` |