# PRODUCT-UI.md — product UI variant of the design system

> Added in **v1.0.2**. Distilled from `suaas.flat101.business`, the first product UI built on top of the editorial token system. The editorial deck rules (`RULES.md`, `MOTION.md`, `ANTIPATTERNS.md`) still apply for slide-based work. This file documents the **product UI variant**: an app shell with sidebar, dense data screens, forms, multi-step workflows.

Use this file when the user asks for a tool, dashboard, admin panel, internal SaaS, or anything that is not a long-scroll editorial deck. Do **not** apply it to slide decks; for those, stick with `RULES.md`.

## Hard divergences from the editorial deck

The deck is **maximalist editorial**: italic serif heroes, single accent, cinematic reveals, snap scroll. The product UI is **utilitarian editorial**: same tokens, same accent, same serif italic for hero titles, but no Lenis, no GSAP, no IntroScreen, no slide chrome, no Highlight as signature. Density of information matters more than rhythm.

Concrete deltas:

| Topic | Deck | Product UI |
|---|---|---|
| Stack | Tailwind v4 + motion + Lenis + GSAP | Plain CSS + tokens + minimal `motion` |
| Layout | `min-h-screen` slides, 1664px max | App shell (sidebar + main + footer) |
| Typography | Hero italic serif, 88px+ | h1 `clamp(32px, 4vw, 56px)` italic |
| Color | Single accent, alternate variants | Single accent on `--ink-900` background |
| Motion | 450–900 ms cinematic reveals | < 300 ms microinteractions, no Lenis |
| Cursor | Native | Native |
| Auth | None by default | Cookie-based gate (optional) |
| Padding | `clamp(24px, 6vw, 128px)` per slide | `clamp(28px, 4vw, 56px)` per main |

## App shell

```
┌─────────┬───────────────────────┐
│         │   <main>              │
│ sidebar │   PageHeading         │
│ (240px) │   <section>           │
│         │   <section>           │
│         ├───────────────────────┤
│         │   <footer> badges     │
└─────────┴───────────────────────┘
```

CSS rule (the only one you really need):

```css
.app-shell {
  display: grid;
  grid-template-columns: 240px 1fr;
  grid-template-rows: 1fr auto;
  grid-template-areas:
    "sidebar main"
    "sidebar footer";
  min-height: 100vh;
  background: var(--ink-900);
  color: rgba(255, 255, 255, 0.92);
}
.app-shell-main {
  grid-area: main;
  padding: clamp(28px, 4vw, 56px) clamp(24px, 4vw, 48px);
  min-width: 0;
  /* Vertical rhythm: gap between PageHeading and each <section> the page
     renders below it. Single source of truth. */
  display: flex;
  flex-direction: column;
  gap: clamp(32px, 4vw, 56px);
}
```

Below ~880 px the sidebar collapses into an overlay drawer with backdrop and a circular hamburger button. The main keeps its padding; only the sidebar changes.

### Sidebar contents

Two groups separated by a `.mono` 9px tracked uppercase label:

- **Producto**: links to each module (modules are listed as sidebar items; current item gets `data-active="true"` with accent color and left border accent).
- **Sistema**: telemetry, diagnostics, trash, seed.

Icons from `lucide-react`, 16 px, imported individually for tree-shaking. Brand icons (Google Ads, Meta, etc.) live as inline SVG with `currentColor` in `components/channel-icon.tsx` — never import an icon library just for one brand glyph.

### Footer

Status badges with `data-status="ok|warn|off"` (mono, 10 px tracked uppercase). Right side shows the version and host in `tabular-nums`. Nothing else.

## PageHeading

Single component per page, top of `<main>`. Three slots:

```tsx
<PageHeading
  eyebrow="Módulo · contexto"
  title="Frase clave en italic display"
  description={optional}
  descriptionVariant="inline" | "panel"
  actions={<Link href="…" className="btn-pill" />}
/>
```

Title: `clamp(32px, 4vw, 56px)`, DM Serif Text italic, color `#fff`. Eyebrow: `.mono`, 11 px tracked 0.28em, `var(--accent-500)`. Description optional.

Rules:

- **Listings and `new/` pages**: only `eyebrow + title + actions`. No `description`. The first `<section>` below already explains what the page is.
- **Detail pages**: use `description={entity.brief}` with `descriptionVariant="panel"` so the brief becomes a destacado box with left accent border. Never push entity content into title or eyebrow.
- **Setup / system pages** (`/diag`, `/tokens`, `/trash`): only `eyebrow + title`. The blocks of stats below explain themselves.

Antipattern: writing a generic "Cómo funciona este módulo" prose in `description=` of a listing page. Cut it. The screen is the documentation.

## EntityListView + EntityCard

Used for any list of homogeneous entities (targets, funnels, A/B, copy, pricing, campaigns, profiles). Each card has fixed structure:

```
┌──────────────────────────────┐
│ FECHA               🗑         │  ← eyebrow accent + trash overlay
├──────────────────────────────┤
│ Título italic                │
│ Descripción clamp 2 líneas   │
├──────────────────────────────┤
│ Runs · Perfiles · Stat3 · …  │  ← stats in .mono
└──────────────────────────────┘
```

Wrapper toolbar: search input + sort dropdown (more recent | older | A-Z | Z-A | more runs | more profiles). Grid `auto-fill minmax(320px, 1fr)` gap 20. Pagination kicks in at 30+ entities.

Implementation: `<EntityListView items={…} />` accepts `EntityListItem[]` so the component never knows the concrete entity model. Each page maps its rows to `{ id, href, trash, title, description, createdAt, runs, users, stats[], media? }`.

## ProfileLaunchPanel

Reusable CTA-then-picker block at the bottom of every entity detail. Two states:

1. **Collapsed**: a single `.btn-pill.solid` "Lanzar nueva Run" + helper text on profile count.
2. **Expanded**: `<ProfileExplorer mode="picker" />` (grid or table view, filters, multi-select with up to 20 profiles) + a primary action button "Lanzar sobre N perfiles" above the list, and a "Cancelar" link at top right.

On submit, fetch `POST <endpoint>` with the selected profile ids and any extra body. On success, push to `resolveRedirect(kind, json)` (see `components/profile-launch-panel.tsx`). On error, render inline alert.

Default to collapsed. Avoid showing the picker on results pages (it's not the right entry point for re-launching from there; use the dedicated re-launch CTA).

## Tabs with "Próx." badge for incomplete features

When a feature is modeled in data but not implemented in the runner, expose it as a disabled tab — not as a hidden option. Pattern:

- `cursor: not-allowed`
- Opacity 0.6 or desaturated color
- Chip "Próx." in `.mono`, tracked 0.18em, with `border-radius: var(--radius-pill)` and 1 px border
- `title` attribute with the long description of what that tab will offer
- Click is a no-op (do not call `onChange`)

When `isFeatureImplemented(value)` becomes `true`, the badge disappears and the tab activates. Two layers of this in `suaas/campaigns`:

1. Top tabs for `channel` (Google active, Meta/LinkedIn/TikTok/X show "Próx.").
2. Tabs inside Google for `strategy` (Search and Display active, the other five Google strategies show "Próx.").

## Sub-tab pattern (channel → strategy)

When a configuration has two orthogonal dimensions (e.g. "advertising network" and "campaign type within that network"), present both as tab strips, one nested under the other, with their own help text. Do not nest tabs more than two levels — beyond that, switch to a wizard.

## Live preview pane

For forms that produce a visual artifact (an ad, a card, a page), the form lives on the left and a **sticky live preview** lives on the right. CSS:

```css
.form-with-preview {
  display: grid;
  grid-template-columns: minmax(0, 1fr) minmax(0, 360px);
  gap: 32px;
  align-items: start;
}
.form-with-preview aside { position: sticky; top: 24px; }
```

The preview updates on every keystroke (React state, no debounce). Render a different preview component per output type (SERP vs Display banner in the campaigns module). If the form has no obvious visual output, do not force-fit a preview.

## Chip prominent with icon

For metadata that is identity (not metric), render a chip with `display: inline-flex; gap: 8`, monospace label, optional icon, and accent border + soft accent fill. Examples in suaas:

- Strategy chip in campaign detail header: `<StrategyIcon /> Search` on accent background.
- Channel chip: `<ChannelIcon /> Google Ads` on neutral background.

Reserve accent fill for the chip that carries the most meaning per screen (one chip, not many).

## descriptionVariant="panel"

When `PageHeading` description is the brief of an entity (not a generic explanation), use:

```css
.page-heading-description-panel {
  margin-top: 8px;
  padding: 26px 30px;
  border: 1px solid rgba(255, 255, 255, 0.08);
  border-left: 3px solid var(--accent-500);
  border-radius: var(--radius-md);
  background: rgba(255, 255, 255, 0.02);
  color: rgba(255, 255, 255, 0.85);
  font-size: clamp(15px, 1.15vw, 17px);
  line-height: 1.6;
}
```

The 3 px left border is an **explicit exception** to the deck's anti-side-stripe rule. Document it where it appears and do not duplicate the pattern elsewhere in the same page.

## MigrationNeeded

Defensive component for migrations not yet applied. When a list or detail fetch returns `isMissingTableError(err)`, render `<MigrationNeeded migration="000X_name.sql" feature="…" details="…" />` instead of an exception page. The component shows the migration filename, the feature it unlocks and a one-line action. Do not crash the page on missing tables; users may be mid-deploy.

## RunsPreviousGrid

On detail pages, render previous runs as a grid of cards, never a table. Each card: created_at + status badge + N profiles + 1–3 entity-specific metrics + link to results. Use `components/runs-previous.tsx`. Configure the metric keys per entity (e.g. `mean_intent_to_click` for campaigns, `mean_clarity` for clarity).

## Trash + soft delete

Each list card carries a `<SendToTrashButton />` overlay (top-right). Click → `POST /api/trash/<type>/<id>`. `/trash` page lists soft-deleted items with restore (`PATCH`) and hard delete (`DELETE`). Database rows keep a `deleted_at timestamptz` column; queries default to `.is("deleted_at", null)`.

If your schema does not yet have `deleted_at`, fall back to listing all rows (catch `isMissingColumnError(err, "deleted_at")`). Never show 500s for migration gaps.

## Copy rules (Spanish-first products)

Distilled from `suaas/CLAUDE.md`. These are stricter than the general deck rules.

- **Never em-dash (`—`)** in any visible text. Replace with comma, colon, parentheses or period.
- **Spanish with full diacritics** in all UI copy. Never substitute accents with ASCII equivalents.
- **Quotes**: `«texto»` or `"texto"`, not `'texto'`.
- **Numbers**: thousand separator is a dot (Spanish format): `1.500`, not `1,500`.
- **No emojis** in UI text. Lucide icons or inline SVG only.
- **Single-line buttons**: action verbs in infinitive or imperative ("Lanzar nueva Run", "Crear campaña", "Volver"). No exclamations.

## Form patterns

- **Char-counted inputs**: when a field has a hard cap (RSA headline 30 c, description 90 c, etc.), render the counter in `.mono` aligned right of the label. Color shifts to `var(--error-500)` when over.
- **Sections with add/remove**: dynamic arrays (queries, headlines, descriptions, steps) wrapped in a `<Section title onAdd addLabel canAdd>`. Each row has a "Eliminar" button on the right disabled when at minimum.
- **Toggle buttons**: `.btn-pill` (outline) when inactive, `.btn-pill.solid` (filled) when active. Use for modes (URL vs upload, image vs video vs YouTube).
- **File upload to data URL**: read with `FileReader.readAsDataURL` in client; server action does the rest (upload to Blob, fallback to data:url if no token).

## Security baseline (when the product handles real users)

Not deck-relevant. Listed here because product UI work typically inherits these.

- **Cookie gate**: `proxy.ts` middleware redirects to `/login` if cookie not present. `lib/auth.ts` with `timingSafeEqual`. Production mode without `ACCESS_PASSWORD` env returns null and rejects everything.
- **Anti-SSRF on user-provided URLs**: `assertPublicUrl(url)` with DNS lookup + private range blocklist (RFC 1918, loopback, link-local, cloud metadata 169.254.169.254, IPv6 ULA/link-local/multicast). Apply before any server-side fetch on user input.
- **Error hygiene**: 500 responses to client return only `"Error interno."`. Detail (stack, cause) goes to `console.error` for Vercel logs. Validation 400s keep the zod message because it comes from the request itself.
- **Secondary gate for token-burning routes**: anything that fans out LLM calls (seeding, batch generation) sits behind a second cookie with a separate password env (e.g. `SEED_PASSWORD`). Production requires the env; without it, return 503 with a machine-readable code.

## Schema migration discipline

For Supabase-backed apps:

- Migrations live in `supabase/migrations/NNNN_name.sql`, numbered sequentially.
- Apply manually in the SQL editor (the project may not be Git-connected on Vercel; `vercel env pull` returns `""` for sensitive vars like `POSTGRES_URL_NON_POOLING`, so an agent can't apply migrations directly via `pg`).
- Always run `NOTIFY pgrst, 'reload schema';` after a migration to refresh PostgREST cache.
- Defensive code in lib: `isMissingTableError(err)`, `isMissingColumnError(err, col)`, and `normalizeEntity(row)` that maps legacy columns to the new shape so the UI doesn't 500 between deploy and migration application.
- Idempotent fix migrations are OK (see `0012_campaigns_headlines_fix.sql`): they reapply a check constraint without checking if the previous one ran. Cheaper than tracking who applied what.

## Versioning of the product

`lib/version.ts` exports `APP_VERSION`. `package.json` mirrors it. Both must be bumped manually in every functional commit:

- patch (`+0.0.1`): `fix`, `refactor`, `docs`, `chore`, UI tweaks.
- minor (`+0.1.0`): `feat` (new route, module, integration, migration).
- major (`+1.0.0`): structural / breaking.

`components/console-banner.tsx` prints the version + host in the browser console at load to verify the deploy propagated. Hard-reload Ctrl+Shift+R if the console still shows the previous version.

## Cheat sheet · when to use product UI vs deck

| Asks for | Use |
|---|---|
| "Slide deck", "presentación", "long-scroll narrative" | Editorial deck (`RULES.md`) |
| "Dashboard", "admin panel", "internal tool", "SaaS UI" | Product UI (this file) |
| "Landing page for a campaign" | Editorial deck if hero-driven, product UI if form-driven |
| "Documentation site" | Editorial deck for the "marketing" layer, product UI for the docs reader |
| "Design system page" | Both, in different sections |

If you are not sure: editorial deck makes a stronger first impression but is heavier to scale; product UI is denser and cheaper per screen. Default to product UI for anything an operator uses daily.