# Framework integration guide
## Architecture in one line
**One brand, two products, one foundation.** The SuperCat Design System ships shared tokens + primitives in `ds/tokens/` and `ds/primitives/`, and they power **two distinct surface families**: a **Web Marketing** website (editorial, premium, restrained) at `index.html` + `ds/reference.html`, and a **Web / iPad App** (utilitarian, data-dense, fast) at `app/*.html`. Both products consume the foundation; neither product depends on the other. Read [`SURFACES.md`](SURFACES.md) for the architecture diagram + file-by-file map.
The SuperCat DS is **framework-agnostic by design**. Primitives ship as CSS classes that decorate native HTML elements — no React, Vue, or build tool is required to use them. This guide shows how to wire the system into common stacks.
---
## What you load
Three options for getting tokens + primitives into a project. Pick one.
### A — Direct file links (simplest)
```html
```
### B — Concatenated single bundle (recommended for prod)
The `scripts/build.sh` (when re-enabled) concatenates everything into `ds/dist/ds.css` + `ds/dist/ds.js`. Link one stylesheet + one script.
### C — Import via npm / Vite / Webpack
Treat the `design-system/` directory as a local package. From a React/Vue/Svelte/Next/etc. project:
```js
// In your entry file
import 'supercat-ds/ds/tokens/index.css';
import 'supercat-ds/ds/primitives/button.css';
import 'supercat-ds/ds/primitives/input.css';
// …
```
Resolve the path however your bundler likes — alias it in `tsconfig.json` / `vite.config.js` / `webpack.config.js`.
---
## ★ Logo — vector only, never typed text
The SuperCat brand is the **double-wave mark**. Never render it as styled HTML text (`
SuperCat
`, etc.).
**Source of truth:** [`assets/supercat-mark.svg`](../assets/supercat-mark.svg) — `viewBox="0 0 41 28"`, paths fill via `currentColor`.
### As a React component
```jsx
export function SuperCatMark({ size = 28, color = 'var(--color-gold)', label = 'SuperCat' }) {
return (
);
}
```
### As an SVG sprite (any framework)
Inline the symbol once near the top of the document body, then reference it anywhere:
```html
```
### Asset variants
| Use case | Reference |
|---|---|
| Default brand (gold mark on cream) | `color: var(--color-gold)` |
| Inverted (cream mark on dark glass) | `color: var(--color-cream)` |
| Knock-out on solid color | `color: currentColor` of parent |
| External asset (img tag, fav, social) | `assets/supercat-mark.svg` |
**Do not:**
- Render the brand as text (`
SuperCat
`).
- Apply crimson to the mark (crimson is for primary actions).
- Distort the aspect ratio — keep `width / height = 41 / 28`.
- Embed PNG fallbacks; SVG with `currentColor` covers every contrast case.
---
## React
Classes are plain strings. Tokens are CSS custom properties — you can override them inline if you need a one-off skin.
```jsx
// Button
// Input
// Toggle — real works with controlled state
// Skeleton-loaded card
{data && }
```
Works seamlessly with **React Hook Form**, **Formik**, **TanStack Query** — primitives don't intercept events or wrap inputs.
For Tailwind users: the DS tokens are CSS custom properties. Drop them into `tailwind.config.js`:
```js
module.exports = {
theme: {
extend: {
colors: {
crimson: 'var(--color-crimson)',
cream: 'var(--color-cream)',
moss: 'var(--color-moss)',
// …
},
fontFamily: {
sans: 'var(--font-sans)',
mono: 'var(--font-mono)',
},
},
},
};
```
---
## Vue (3.x)
Use `class` attribute. Inputs work with `v-model`.
```vue
```
Skeleton loading via `:aria-busy` binding:
```vue
{{ data.title }}
```
---
## Angular
```html
{{ data.title }}
```
---
## Svelte
```svelte
{data.title}
```
---
## What this system promises
- **No JS framework lock-in.** Primitives are pure CSS — the few that ship JS (`button.js`, `input.js`, `tabs.js`, `skeleton.js`) are vanilla controllers attached via class hooks (`data-reload`, `data-loadable`, `aria-selected`) and can be replaced or removed without affecting the visual layer.
- **Real form elements.** `