> **Note (post-design-system-unification, 2026-05-15):** The canonical colour
> token contract now lives in `DESIGN.md` at the repo root. This document has
> been demoted to a marketplace-specific addendum and may conflict with
> DESIGN.md where noted. DESIGN.md takes precedence.

# Madarx Marketplace — Brand Identity

## Mission

The Marketplace is the single operator-facing surface where agents are given
power: **tools** (API adapters), **skills** (instruction packs), and **bundles**
(curated collections). It is the equivalent of an App Store for an agent OS.

A future **Agent Marketplace** — separate product, separate route, separate
spec — will catalogue agent personas (Hermes, OpenClaw, gstack-ceo, …). The
brand tokens defined here are designed so both surfaces feel like siblings.

## Wordmark

| Part | Treatment |
|------|-----------|
| `Madarx` | IBM Plex Mono, weight 500, charcoal `#111318` |
| `/` | sand-300 `#dcd2b3`, no padding adjustment |
| `marketplace` | SF Pro Display, weight 400, lowercase, letter-spacing `-0.025em` |

**Page eyebrow:** `MARKETPLACE · MADARX OS` — IBM Plex Mono caps, .18em
tracking, bronze-500 `#8a6d35`. Replaces `REGISTRY · MADARX OS` from the
legacy `/tools` page.

**Page title:** editorial 88px clamp — uses the existing `.admin-header h1`
styles verbatim. No new title style is introduced.

## Color Tokens

All tokens live in `:root` (declared in `app/globals.css`) so they are
inspectable via DevTools and reusable by future surfaces.

| Token | Hex | Usage |
|-------|-----|-------|
| `--mkt-tool-tint` | `#f3f1ec` | Tool brand-chip background |
| `--mkt-tool-ink` | `#3a3f47` | Tool chip foreground / `TOOL` tag text |
| `--mkt-skill-tint` | `#e7f1f9` | Skill brand-chip background |
| `--mkt-skill-ink` | `#1f6c9f` | Skill chip foreground |
| `--mkt-bundle-tint` | `#fbf3db` | Bundle brand-chip background |
| `--mkt-bundle-ink` | `#956400` | Bundle chip foreground |
| `--mkt-agent-tint` | `#edf3ec` | **Reserved** for the future Agent Marketplace — declared, unused in Phase 1 |
| `--mkt-agent-ink` | `#346538` | **Reserved** — declared, unused in Phase 1 |
| `--mkt-installed` | `#111318` | Installed state (toggle on, "Installed" badge) |
| `--mkt-accent` | `#c2452a` (mars-500) | Reserved for destructive (uninstall confirm) |
| `--mkt-divider` | `rgba(17,19,24,0.06)` | Row hairline |
| `--mkt-divider-strong` | `rgba(17,19,24,0.09)` | Section + stat divider |

*The `--mkt-bundle-tint` and `--mkt-bundle-ink` values above reflect the pre-P1
values. After design-system-unification P0, these tokens resolve to
`var(--accent-50)` and `var(--accent-700)` respectively. See DESIGN.md.*

## Typography Scale

Inherits the minimalist-skill protocol — no new font is introduced.

| Layer | Family | Weight | Size | Tracking |
|-------|--------|--------|------|----------|
| Display heading | SF Pro Display / system-ui | 300 | clamp(42px, 6vw, 88px) | -0.05em |
| Item names | IBM Plex Mono | 500 | 14px | -0.01em |
| Body / descriptions | SF Pro Display | 400 | 13px / 1.55 lh | 0 |
| Eyebrows + meta caps | IBM Plex Mono | 650 | 10–11px | .14em–.18em uppercase |
| Inline labels | SF Pro Display 11.5 + IBM Plex Mono value | — | — | — |

## Component Primitives

Formalised in `app/components/ui/marketplace/`. Phase 2 and the future Agent
Marketplace consume the same primitives so the two surfaces stay in lockstep.

| Component | File | Notes |
|-----------|------|-------|
| `<KindChip kind=… />` | `kind-chip.jsx` | Brand-chip square with kind SVG + tint |
| `<KindBadge kind=… />` | `kind-badge.jsx` | Inline tag for row metadata |
| `<RiskDot level=… />` | `risk-dot.jsx` | Risk-tier indicator dot |
| `<InstallToggle …/>` | `install-toggle.jsx` | Server-action-backed toggle button |

`<MarketplaceRow>`, `<MarketplaceFilters>`, and `<MarketplaceSearch>` live
under `app/marketplace/` since they are surface-specific, but they consume the
primitives above.

## Iconography

`app/components/ui/tool-icons.tsx` provides brand SVGs. Two new marks are added
in Phase 1:

| Kind | Icon | Style |
|------|------|-------|
| `skill` | `SkillIcon` (open book) | 1.7px stroke, currentColor |
| `bundle` | `BundleIcon` (stack of three squares) | 1.7px stroke, currentColor |
| `agent` | `AgentIcon` (avatar silhouette) | 1.7px stroke, currentColor — reserved export |

`AgentIcon` ships as a reserved export in `tool-icons.tsx` to render the agent kind chip; the standalone Agent Marketplace surface is deferred to a future product.

**Strictly no emoji** anywhere in the marketplace UI. This enforces the
project-wide CLAUDE.md zero-tolerance rule.

## Do / Don't

| Do | Don't |
|----|-------|
| Use brand tokens (`--mkt-*`) for every color | Use ad-hoc hex values in marketplace components |
| Keep the eyebrow + title structure intact | Introduce a second title style |
| Use IBM Plex Mono for item names | Use the body font for slugs / identifiers |
| Reserve the green agent tint for the future Agent Marketplace | Repurpose `--mkt-agent-*` tokens for skill/bundle styling |
| Phrase deferred bundle installs as "Coming Phase 2" | Hide the disabled CTA — show it so users learn the model |
| Cap row description at 640px | Let descriptions span the full row width |
| Surface "Agent personas live in the Agent Marketplace (coming soon)" copy on empty states | Add an Agents tab to Phase 1 |

## Phase 1 Boundary

The Phase 1 marketplace surfaces three kinds: `tool`, `skill`, `bundle`.

- A request for `kind: 'agent'` is intentionally rejected with an empty
  result + console warning. The Agent Marketplace is a separate product.
- Bundle installation is a `{ status: 'deferred' }` no-op in Phase 1. The
  modal copy explains what install will do in Phase 2.
- GitHub URL import opens an informational modal only. Implementation lands
  in Phase 2.

These boundaries are enforced by tests in `tests/marketplace-listing.test.js`
and `tests/marketplace-api.test.js`.
