# Integration Guide

How to consume `@oglabs/design-system` from other projects (primarily `Oglabsacademy`).

---

## A2 — Distribution: which method?

We support **three methods**. Pick one. They are not mutually exclusive but adding more than one creates drift risk.

| Method                    | When to use                                  | Pros                              | Cons                              |
| ------------------------- | -------------------------------------------- | --------------------------------- | --------------------------------- |
| **1. Git submodule**      | Now (early iteration, weekly token churn)    | Instant updates, no publish step  | Submodule UX is awkward           |
| **2. npm (private)**      | When tokens stabilise (≈ post v1.0)          | Versioned, idiomatic, CI-friendly | Requires private registry        |
| **3. GitHub raw URL**     | For Tokens Studio (designers) only           | Zero infra, Figma-syncable        | Not for code consumers            |

### Recommended sequence
1. **Today:** start with **submodule** for code, **GitHub raw URL** for Figma Tokens Studio.
2. **At v1.0** (when token churn slows): publish to npm, switch consumers to npm install, keep submodule as fallback for the brand HQ contents (presentations, social).

---

## Method 1 — Git submodule (recommended now)

### One-time setup, run inside `Oglabsacademy/`:

```bash
cd /Users/krishnagaurav/Documents/GitHub/Oglabsacademy

# Add this folder as a submodule under vendor/design-system
git submodule add https://github.com/<your-org>/ogdesignsystem.git vendor/design-system

# (or, while the design system isn't pushed yet, use a relative path on disk:)
# git submodule add ../ogdesignsystem vendor/design-system

git commit -m "chore: add design system as submodule"
```

### Wire it into Vite + Tailwind 4

In `Oglabsacademy/src/styles/index.css`, replace the order with:

```css
@import './fonts.css';
@import './tailwind.css';

/* ⬇ NEW: design-system tokens BEFORE the local theme so theme.css can override during migration */
@import '../../vendor/design-system/tokens/tokens.css';

@import './theme.css';
```

In `Oglabsacademy/vite.config.ts`, allow Vite to read files outside `src`:

```ts
export default defineConfig({
  // ...existing config
  server: {
    fs: { allow: ['..', './vendor/design-system'] }
  }
});
```

For Tailwind: import the preset in `tailwind.config.js` (or extend `@theme inline`):

```js
import oglabsPreset from './vendor/design-system/tokens/tokens.tailwind.js';

export default {
  presets: [oglabsPreset],
  content: ['./src/**/*.{ts,tsx}']
};
```

### Updating

```bash
cd vendor/design-system
git pull origin main
cd ../..
git add vendor/design-system
git commit -m "chore: bump design-system to <sha>"
```

---

## Method 2 — npm package (after v1.0)

### In `ogdesignsystem/`:

```bash
npm run build         # regenerate tokens/
npm version 1.0.0
npm publish --access restricted   # private registry
```

### In `Oglabsacademy/`:

```bash
npm install @oglabs/design-system@^1
```

```css
/* src/styles/index.css */
@import '@oglabs/design-system/css';
```

```js
// tailwind.config.js
import preset from '@oglabs/design-system/tailwind';
export default { presets: [preset] };
```

```ts
// access tokens at runtime if needed
import { color, spacing, fontSize } from '@oglabs/design-system';
```

---

## Method 3 — GitHub raw URL (Figma Tokens Studio only)

Once `ogdesignsystem` is pushed to GitHub:

1. In Figma → Plugins → Tokens Studio → Settings → Sync Providers → **GitHub**.
2. Repo: `<your-org>/ogdesignsystem`
3. Branch: `main`
4. File path: `tokens/tokens.figma.json` (or `tokens.json` — both work)
5. Designers now pull token updates by clicking "Pull from GitHub" in the plugin.

---

## A3 (next step) — Migrating `Oglabsacademy/src/styles/theme.css`

`theme.css` currently hardcodes 40+ values that should reference the design system. Migration plan:

### Phase 1 (no-risk): add the import, keep theme.css as override
- Already done if you followed Method 1 above.
- Both files coexist. Bug? Roll back the import line.

### Phase 2 (one PR per category): replace hardcoded values
For each section in `theme.css`, replace literal hex codes with `var(--color-*)` references from tokens.css. Example:

```css
/* before */
:root { --background: #FAFAF6; --accent: #FE1300; }

/* after */
:root { --background: var(--color-paper); --accent: var(--color-signal); }
```

Suggested PR sequence:
1. Colors (40 lines)
2. Typography (font-family, font-size, line-height)
3. Spacing
4. Shadows
5. Borders & radii

Each PR is small, reviewable, and revertable.

### Phase 3: lint to prevent drift
Add `stylelint` with `stylelint-no-hardcoded-colors` to CI. Block any PR that introduces a new `#` hex outside `tokens.css`.

```json
// .stylelintrc
{
  "plugins": ["stylelint-declaration-strict-value"],
  "rules": {
    "scale-unlimited/declaration-strict-value": [
      ["color","background-color","border-color"],
      { "ignoreValues": ["transparent","currentColor","inherit"] }
    ]
  }
}
```

---

## Source of truth contract

After integration, the following becomes **canon**:

- `ogdesignsystem/tokens.json` — the only place to add/change a token.
- `ogdesignsystem/tokens/*` — auto-generated, never hand-edited.
- `ogdesignsystem/Design System.html` — the spec for what each token *means*.
- `Oglabsacademy/src/styles/theme.css` — only contains semantic aliases (`--button-primary-bg: var(--color-signal);`), never new primitive values.
- `Oglabsacademy` components — reference Tailwind preset classes or CSS vars only. No `#FE1300` strings anywhere.

Breaking that contract = a bug.