# Consumer Audit Setup — TVU Design System

> Quick guide for installing and running TVU's mockup + code audit tooling in a consumer product (a sibling repo that consumes `@nancyzeng0210/tvu-design-system`).
>
> **Why this exists in the DS repo, not as a separate package**: audits version-lock to the library. When you install `@nancyzeng0210/tvu-design-system@1.0.0`, you get exactly the audit rules that matched the library at that version — no drift, no separate plugin upgrade cycle.

---

## What ships

The main `@nancyzeng0210/tvu-design-system` npm package bundles:

| Tool | Type | Purpose |
|---|---|---|
| `audit-product-code.mjs` | CLI script | Lint consumer source code (R1 inline SVG / R2 hex color / R16 CN+EN mixed string) |
| `audit-mockup-integrity.mjs` | CLI script | Lint a Figma mockup file (I1 sibling layout / I2 SECTION overlap / I3 children-bbox wrap) |
| `audit-mockup-colors.mjs` | CLI script | Lint a Figma mockup file (C1 icon path fill bound to Color Variable / C2 hover state / C3 BG vs text grey) |
| `audit-mockup-library-binding.mjs` | CLI script | Lint a Figma mockup file (M0 library instance / M1 Top bar / M30 icon library) |
| `eslint-plugin` (subpath export) | ESLint 9 plugin | Same rules as audit-product-code but as ESLint plugin for editor + CI integration |

All ship inside the same `@nancyzeng0210/tvu-design-system` package via `files: ["dist", "eslint-plugin"]` + subpath exports. No separate install needed.

---

## Install (one-time per consumer product)

### 1. npmrc config

Create or append to `.npmrc` in consumer repo root:

```
@nancyzeng0210:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

`YOUR_GITHUB_TOKEN` = a [GitHub Personal Access Token](https://github.com/settings/tokens) with `read:packages` scope.

### 2. Install the library

```bash
pnpm add @nancyzeng0210/tvu-design-system
```

This brings the components AND all the audit tooling in one install.

### 3. (Optional) Add npm script shortcuts to consumer `package.json`

```json
{
  "scripts": {
    "audit:code": "node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-product-code.mjs --dir src",
    "audit:mockup": "node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-mockup-integrity.mjs --file YOUR_FIGMA_FILE_KEY && node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-mockup-colors.mjs --file YOUR_FIGMA_FILE_KEY",
    "audit:mockup-binding": "node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-mockup-library-binding.mjs YOUR_FIGMA_FILE_KEY"
  }
}
```

Replace `YOUR_FIGMA_FILE_KEY` with the consumer's product Figma file key (the string between `/design/` and `/` in the Figma URL).

### 4. (Optional but recommended) Add ESLint plugin

Consumer `eslint.config.js`:

```js
import tvuPlugin from '@nancyzeng0210/tvu-design-system/eslint-plugin'

export default [
  // ...your existing config...
  tvuPlugin.configs.recommended,
]
```

Or selectively:

```js
import tvuPlugin from '@nancyzeng0210/tvu-design-system/eslint-plugin'

export default [
  {
    plugins: { '@nancyzeng0210/tvu-design-system': tvuPlugin },
    rules: {
      '@nancyzeng0210/tvu-design-system/no-hardcoded-color': 'error',
      '@nancyzeng0210/tvu-design-system/no-inline-svg': 'error',
      '@nancyzeng0210/tvu-design-system/icon-from-dist': 'error',
      '@nancyzeng0210/tvu-design-system/no-base-component-import': 'error',
    },
  },
]
```

Rule details: see `node_modules/@nancyzeng0210/tvu-design-system/eslint-plugin/README.md`.

---

## Running the audits

### Code audit (R1/R2/R16)

```bash
pnpm audit:code
# or directly:
pnpm exec node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-product-code.mjs --dir src
```

Exit code 0 = no findings. Exit code 1 = findings + listed inline.

To disable a single line: `// AUDIT-IGNORE-R1: <reason>` (or R2 / R16) inline comment.

### Mockup audit (M-INTEGRITY + M-COLOR)

Requires `FIGMA_PERSONAL_ACCESS_TOKEN` env (a Figma personal token with read scope on the consumer product file).

```bash
export FIGMA_PERSONAL_ACCESS_TOKEN=<your-token>
pnpm audit:mockup
```

Each script supports `--page <pageId>` and `--node <nodeId>` for narrower scope.

### Mockup library-binding (M0/M1/M30)

Requires either:
- `FIGMA_TOKEN` env + live API access, OR
- a pre-fetched mockup data file at `node_modules/@nancyzeng0210/tvu-design-system/figma-data/mockup/<fileKey>.json` (use `pnpm sync:mockup <fileKey>` from the DS repo to produce one)

```bash
pnpm audit:mockup-binding
```

---

## CI integration (GitHub Actions example)

`.github/workflows/audit.yml` in consumer repo:

```yaml
name: TVU audits

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: 10 }
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
          registry-url: 'https://npm.pkg.github.com'
          scope: '@nancyzeng0210'

      - run: pnpm install --frozen-lockfile
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - run: pnpm audit:code

      - run: pnpm audit:mockup
        env:
          FIGMA_PERSONAL_ACCESS_TOKEN: ${{ secrets.FIGMA_TOKEN }}
```

---

## Quick smoke test (after install)

To verify the install worked end-to-end:

```bash
# 1. Check audit CLI exists
ls node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-product-code.mjs

# 2. Check ESLint plugin loads
node -e "import('@nancyzeng0210/tvu-design-system/eslint-plugin').then(m => console.log('plugin OK:', Object.keys(m.default.rules)))"
# Expected: plugin OK: [ 'no-hardcoded-color', 'no-inline-svg', 'icon-from-dist', 'no-base-component-import' ]

# 3. Dry-run code audit on a single small dir
pnpm exec node node_modules/@nancyzeng0210/tvu-design-system/scripts/audit-product-code.mjs --dir src --dry-run
```

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `npm ERR! 401 Unauthorized` on install | npmrc token missing or expired | Regenerate GitHub PAT with `read:packages` scope; update `.npmrc` |
| `Cannot find module '@nancyzeng0210/tvu-design-system/eslint-plugin'` | ESLint config can't resolve subpath export — older ESLint or pnpm | Update to ESLint 9+ and pnpm 9+; check `node --experimental-import-meta-resolve` for resolve issues |
| Mockup audit times out / 401 | Figma API token missing or wrong file key | Verify `FIGMA_PERSONAL_ACCESS_TOKEN` and file key match the actual product file URL |
| ESLint plugin rules don't fire | Plugin loaded but not registered in `plugins:` map | See "Optional but recommended" section above — flat config requires explicit plugins map |

---

## For DS repo maintainer

When the consumer wants to test before v1.0 RC ships (per user 3b decision 2026-05-19):

1. User identifies consumer product repo path (e.g. `~/Documents/AICoding/VS_Code/microapps-console`).
2. DS maintainer (Claude or human) runs install steps above in that repo:
   - Adds `.npmrc` (with user-provided token)
   - `pnpm add @nancyzeng0210/tvu-design-system`
   - Configures `eslint.config.js` if consumer uses ESLint
   - Adds package.json script shortcuts
3. Runs a smoke audit pass: `pnpm audit:code` against current consumer codebase. Expect ~10-50 findings on first run (legacy code never audited before).
4. Document the findings + ack with user before any code changes — findings are signal for consumer to fix, not auto-fix territory.