---
name: sapiom-design
description: "This skill should be used when the user explicitly says 'Sapiom style', 'Sapiom design', '/sapiom-design', or directly asks to use/apply the Sapiom design system. NEVER trigger automatically for generic UI or design tasks."
version: 1.0.0
allowed-tools: [Read, Write, Edit, Glob, Grep]
---

# Sapiom Design System

## Philosophy

Infrastructure for AI agents. One endpoint, every capability, zero friction. The visual language is precision-dark — a near-black canvas punctuated by a single bright green that means one thing: *access granted*. Geometry is never decorative; every node, hexagon, and polygon encodes the network topology the product actually is.

The primary tension: **machine abstraction vs. human utility**. The homepage feels like a living infrastructure diagram because it *is* one. The blog inverts to white — a deliberate context switch that earns its contrast through restraint in the dark.

Design lineage: developer infrastructure companies (Vercel, Resend, Axiom), precision instrument UI, network topology diagrams. Not consumer SaaS. Not a productivity tool. An API.

---

## 1. Design Principles

**1. One chromatic signal.** Green is not a color palette — it is a binary state. Green means active, connected, access granted. Everything else is monochrome. Max one green element per visual cluster.

**2. Geometry as data.** Hexagons, nodes, and polygons are borrowed from network topology, not decoration. If an element has no structural meaning, remove it. The shape vocabulary earns its presence by encoding information (capability state, connection type, step number).

**3. Numbers before labels.** Feature cards carry ordinal prefixes (01–11). Steps carry ordinal prefixes. This makes scanning fast and implies scale — the platform has *many* capabilities, indexed precisely.

**4. Flat depth.** No drop shadows on the dark canvas. Depth is created by a single background-color step (surface1 → surface2) and a 1px border at 6–10% white opacity. Anything that floats gets a border, not a shadow.

**5. Copy earns its keep.** "Intelligence is here. Access is not." — the headline is provocative and short. Every line of copy on the UI must carry as much weight per word. No decorative descriptions. No feature-list padding.

**6. Dark is primary, light is contextual.** The product canvas is dark. The blog is light. These are not themes — they are contexts. Do not create a light-mode product UI. Do not darken the blog.

**7. Motion serves data, not decoration.** Background polygons drift to imply the network is live. The central node pulses to indicate connectivity. Scroll reveals stagger to sequence information. Nothing animates purely for aesthetics.

---

## 2. Craft Rules

### Visual Hierarchy Layers

| Layer | Elements | Treatment |
|-------|----------|-----------|
| 1 — Signal | Green accent, active hex cells | `var(--accent)` fill, no competing color |
| 2 — Primary | H1, H2, main card content | `var(--text1)`, full weight |
| 3 — Secondary | Labels, descriptions, nav links | `var(--text2)` or `var(--text3)` |
| 4 — Structural | Borders, dividers, step numbers | 1px `var(--border)` or `var(--border-visible)` |
| 5 — Background | Polygon shapes, subtle grid | < 8% opacity, never competing |

### Typography Discipline

- Max 2 font weights per screen: 600 (headings) + 400 (body). Add 500 only for UI labels.
- Mono font for: API keys, endpoint paths, request counts, latency values, timestamps, ordinal prefixes.
- Tracking is negative on headings (`-0.025em` to `-0.03em`). Never positive for display text.
- Body line-height: 1.6. Code line-height: 1.6. Never go below 1.5.

### Spacing Semantics

| Token | Value | Use |
|-------|-------|-----|
| `2xs` | 2px | Icon-to-label gap, tight inline |
| `xs` | 4px | Tag padding, chip spacing |
| `sm` | 8px | Within a component (icon + text) |
| `md` | 16px | Card internal padding (tight) |
| `lg` | 24px | Card internal padding (standard) |
| `xl` | 32px | Between card rows |
| `2xl` | 48px | Section padding top/bottom |
| `3xl` | 64px | Between major sections |
| `4xl` | 96px | Page-level breathing room |

### Color Strategy

- Start every composition at `var(--background)` (#050A06).
- Surface hierarchy: background → surface1 → surface2 → surface3. Never skip levels.
- Green appears once per screen cluster. If two elements both want green, one is wrong.
- Border opacity: `rgba(255,255,255,0.06)` for `--border`, `rgba(255,255,255,0.10)` for `--border-visible`.
- Semantic colors (success, warning, error) appear only in data — never as decorative accents.

### Composition Approach

- Start with the network node centered. Everything radiates from it.
- Feature grids: uniform card size, consistent ordinal prefix alignment.
- Hero copy sits at z-index 10 above all background elements.
- The outer-border frame element should always be present in hero compositions — it contains the visual energy.

### Squint Test

Squint at the screen until it blurs. You should see: one bright point (the green CTA or active node), mid-grey cards arranged in a grid, and near-black everywhere else. If you see multiple bright spots or competing colors, reduce.

---

## 3. Anti-Patterns

**No colored gradients in backgrounds.** The homepage background is flat near-black with subtle drifting polygons. No purple-to-blue gradients, no mesh blobs, no "AI company" neon-rainbow hero backgrounds.

**No border-radius above 8px on cards.** The geometry is architectural, not bubbly. Max 8px containers, 4px controls, 2px small elements.

**No pill-shaped buttons.** CTAs use 4px radius. Pills read as consumer/marketing — Sapiom is infrastructure.

**No decorative emoji or illustration.** Icons are Lucide line icons. No hand-drawn illustrations, no emoji in UI, no 3D blob characters.

**No multi-color palettes.** Green + neutrals only. The moment you introduce blue, purple, or orange as a chromatic element, the brand signal is destroyed.

**No drop shadows on dark surfaces.** Floating elements get a 1px border. Nothing gets `box-shadow: 0 4px 12px rgba(0,0,0,0.3)` on a dark card.

**No light-mode product UI.** The blog is light. The product is dark. These are load-bearing design decisions, not stylistic preferences.

**No lorem ipsum.** Content must be real API-domain vocabulary: endpoint paths, model names, request volumes, latency values, agent names.

**No skeleton screens.** Loading states use a 1px shimmer line or the number indicator dims to `var(--text4)`. No grey rectangle placeholders.

**No toast popup stacks.** Status feedback is inline — a border changes color, a number updates, an icon swaps. No floating notification layering.

**No animation above 400ms.** Transitions cap at 350ms. Background drift is slow (20–30s) and never distracts. Nothing bounces or springs.

**No icon size above 20px in UI components.** Hero-area icons can be 24px. In cards, lists, and nav: 16px.

---

## 4. Component Workflow

When building a component in the Sapiom design language:

1. **Start with the token.** Every value — color, size, radius, spacing — must reference a CSS custom property or the YAML model. No hardcoded hex values.

2. **Choose the surface level.** What elevation is this component? Background → surface1 (most cards) → surface2 (nested, inputs) → surface3 (deep wells).

3. **Apply borders, not shadows.** `border: 1px solid var(--border)` for resting state. `border-color: var(--border-visible)` for hover.

4. **Introduce green last.** Only add `var(--accent)` when the element is a primary action (CTA), an active state (hex cell, selected item), or a confirmed/success indicator. Not before.

5. **Add the number prefix if it's a feature card.** Two-digit ordinal (`01`, `02`) in mono caption style at `var(--text4)`. It's a signature of the Sapiom card system.

6. **Verify with the squint test.** One bright spot, mid-grey structure, near-black canvas.

---

## 5. Hero Stage Composition

The Sapiom hero is a composed network-node visualization:

```
  ┌─────────────────────────────────────┐  ← outer-border.svg frame (decorative)
  │   ◆ polygon   ◇ polygon            │  ← drifting background geometry
  │                                     │
  │         ○ ─── ● ─── ○             │  ← central-node.svg (composition subject)
  │         ╱   network    ╲            │
  │  icon  ●   hub center   ●  icon    │
  │         ╲              ╱            │
  │         ○ ─────────── ○            │
  │                                     │
  │   "Intelligence is here."          │  ← hero headline (z: 10)
  │   "Access is not."                 │
  │                  [Get access →]    │  ← green CTA
  └─────────────────────────────────────┘
```

Implementation notes:
- Background polygon shapes: `@keyframes polygon-drift` — slow translate (20–30s), subtle rotate (±5deg)
- Central node: `@keyframes node-pulse` — opacity 0.6→1→0.6, scale 0.98→1→0.98, 3s ease-in-out
- Green glow behind node: `radial-gradient` centered, `rgba(22,212,107,0.15)` at 0%, transparent at 60%
- Outer border: 1px border, slightly higher opacity than `--border-visible`
- Capability icons arrange radially at equal angles from center node

---

## 6. Hexagon Grid System

Active and inactive states for capability tiles:

```css
.hex-cell {
  clip-path: polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
  width: 56px;
  aspect-ratio: 1;
  display: flex; align-items: center; justify-content: center;
  transition: all 200ms ease-out;
}
.hex-cell.active {
  background: var(--accent);
  color: #000;
}
.hex-cell.inactive {
  background: var(--surface2);
  color: var(--text3);
  border: none; /* clip-path shapes don't support borders natively */
  outline: 1px solid var(--border); /* use outline or SVG stroke instead */
}
.hex-cell:hover {
  background: var(--surface3);
  color: var(--text2);
}
```

---

## References

- `references/tokens.md` — full token values and type scale
- `references/components.md` — component specs and variant tables
- `references/platform-mapping.md` — CSS custom properties, Tailwind config