Design Tokens - Trystpilot.xyz

Design Tokens — Trystpilot.xyz

Status: Awaiting PENPOT_ACCESS_TOKEN secret Tool: @zcubekr/penpot-mcp-server (76+ tools) Approach: Token-first — no hard-coded CSS values in components Last updated: 2026-02-28

Philosophy

All CSS values in Trystpilot components must reference design tokens. Hard-coded values (e.g. color: #00b67a, padding: 16px) are only permitted:

As the token definition itself in the token file
In inline styles when scoped to a single dynamic value that cannot be expressed as a token (e.g. a user-provided avatar color)
Never in component-level Tailwind classes (use token-backed Tailwind config)

Token Architecture (Planned)

Tier 1 — Primitive Tokens

Raw values. Never used directly in components.

color.green.50   → #f0fdf4
color.green.100  → #dcfce7
...
color.green.500  → #00b67a   ← brand primary
color.green.600  → #00a36c
color.green.700  → #008f5e

color.neutral.0   → #ffffff
color.neutral.50  → #f9fafb
color.neutral.100 → #f3f4f6
...
color.neutral.900 → #111827

color.red.500    → #ef4444
color.amber.500  → #f59e0b
color.blue.500   → #3b82f6

space.1  → 4px
space.2  → 8px
space.3  → 12px
space.4  → 16px
space.5  → 20px
space.6  → 24px
space.8  → 32px
space.10 → 40px
space.12 → 48px
space.16 → 64px

radius.sm  → 4px
radius.md  → 8px
radius.lg  → 12px
radius.xl  → 16px
radius.2xl → 24px
radius.full → 9999px

font.size.xs   → 12px
font.size.sm   → 14px
font.size.base → 16px
font.size.lg   → 18px
font.size.xl   → 20px
font.size.2xl  → 24px
font.size.3xl  → 30px
font.size.4xl  → 36px

font.weight.regular   → 400
font.weight.medium    → 500
font.weight.semibold  → 600
font.weight.bold      → 700
font.weight.extrabold → 800

line.height.tight   → 1.25
line.height.snug    → 1.375
line.height.normal  → 1.5
line.height.relaxed → 1.625

duration.fast    → 150ms
duration.normal  → 300ms
duration.slow    → 500ms
duration.slower  → 1000ms

easing.standard  → cubic-bezier(0.4, 0, 0.2, 1)
easing.decelerate → cubic-bezier(0, 0, 0.2, 1)
easing.accelerate → cubic-bezier(0.4, 0, 1, 1)
easing.spring    → cubic-bezier(0.34, 1.56, 0.64, 1)

shadow.sm  → 0 1px 2px rgba(0,0,0,0.05)
shadow.md  → 0 4px 6px rgba(0,0,0,0.07)
shadow.lg  → 0 10px 15px rgba(0,0,0,0.10)
shadow.xl  → 0 20px 25px rgba(0,0,0,0.10)

z.base    → 0
z.raised  → 10
z.dropdown → 100
z.sticky  → 200
z.overlay → 300
z.modal   → 400
z.toast   → 500
z.tooltip → 600

Tier 2 — Semantic Tokens

Named by intent. Used in components.

color.brand.primary    → color.green.500
color.brand.primary.hover → color.green.600
color.brand.primary.active → color.green.700

color.background.default → color.neutral.0
color.background.subtle  → color.neutral.50
color.background.muted   → color.neutral.100

color.text.primary   → color.neutral.900
color.text.secondary → color.neutral.600
color.text.muted     → color.neutral.400
color.text.inverse   → color.neutral.0
color.text.brand     → color.green.500

color.border.default → color.neutral.200
color.border.focus   → color.green.500
color.border.error   → color.red.500

color.rating.excellent → color.green.500   (4.5–5.0)
color.rating.great     → color.green.400   (4.0–4.4)
color.rating.average   → color.amber.400   (3.0–3.9)
color.rating.poor      → color.amber.500   (2.0–2.9)
color.rating.bad       → color.red.500     (1.0–1.9)

color.status.pending    → color.amber.500
color.status.approved   → color.green.500
color.status.rejected   → color.red.500
color.status.quarantine → #7c3aed   (purple)
color.status.suspended  → color.red.600
color.status.claimed    → color.blue.500

space.component.xs  → space.2    (8px)
space.component.sm  → space.3    (12px)
space.component.md  → space.4    (16px)
space.component.lg  → space.6    (24px)
space.component.xl  → space.8    (32px)

space.layout.sm  → space.4    (16px)
space.layout.md  → space.8    (32px)
space.layout.lg  → space.12   (48px)
space.layout.xl  → space.16   (64px)

radius.button  → radius.full
radius.card    → radius.xl
radius.input   → radius.md
radius.badge   → radius.full
radius.modal   → radius.2xl

shadow.card    → shadow.sm
shadow.card.hover → shadow.md
shadow.modal   → shadow.xl
shadow.dropdown → shadow.lg

Tier 3 — Component Tokens

Scoped to a specific component.

button.primary.background       → color.brand.primary
button.primary.background.hover → color.brand.primary.hover
button.primary.text             → color.text.inverse
button.primary.radius           → radius.button
button.primary.padding.x        → space.component.lg
button.primary.padding.y        → space.component.sm
button.primary.font.weight      → font.weight.semibold
button.primary.font.size        → font.size.sm

button.secondary.background     → color.background.default
button.secondary.border         → color.border.default
button.secondary.text           → color.text.primary

input.background   → color.background.default
input.border       → color.border.default
input.border.focus → color.border.focus
input.border.error → color.border.error
input.radius       → radius.input
input.padding.x    → space.component.md
input.padding.y    → space.component.sm
input.font.size    → font.size.sm
input.text         → color.text.primary
input.placeholder  → color.text.muted

card.background    → color.background.default
card.border        → color.border.default
card.radius        → radius.card
card.shadow        → shadow.card
card.shadow.hover  → shadow.card.hover
card.padding       → space.component.lg

star.filled   → color.brand.primary
star.empty    → color.neutral.200
star.size.sm  → 16px
star.size.md  → 20px
star.size.lg  → 28px
star.size.xl  → 40px

rating.bar.fill   → color.brand.primary
rating.bar.track  → color.neutral.100
rating.bar.height → 8px
rating.bar.radius → radius.full

header.background → #1C1B1B
header.text       → color.text.inverse
header.height     → 64px

footer.background → #1C1B1B
footer.text       → color.neutral.300

badge.padding.x   → space.component.sm
badge.padding.y   → space.1
badge.font.size   → font.size.xs
badge.font.weight → font.weight.semibold
badge.radius      → radius.badge

toast.background  → color.neutral.900
toast.text        → color.text.inverse
toast.radius      → radius.lg
toast.shadow      → shadow.xl

modal.overlay     → rgba(0, 0, 0, 0.5)
modal.background  → color.background.default
modal.radius      → radius.modal
modal.shadow      → shadow.xl
modal.padding     → space.component.xl

Penpot Integration

When ready:

# Install headless MCP server (REST API, no browser needed)
npm install -g @zcubekr/penpot-mcp-server

# Start with your token
PENPOT_ACCESS_TOKEN=<your-token> npx @zcubekr/penpot-mcp-server

# Add to Claude Code MCP
claude mcp add penpot-mcp -t http http://localhost:3000/mcp

Tools to call once connected:

create_project — “Trystpilot Design System”
create_file — “Design Tokens”
Create color/typography/spacing token libraries
Create component frames for each of the 70 components
Export tokens as CSS custom properties

Secret needed:

Name: PENPOT_ACCESS_TOKEN
Source: Penpot → Settings → Access Tokens → Generate new token
Optional: PENPOT_API_URL (only if self-hosted, defaults to https://design.penpot.app)

CSS Custom Properties Output (Target)

Once Penpot tokens are generated, the output CSS should be:

/* Primitive tokens — :root */
:root {
  /* Colors */
  --color-green-500: #00b67a;
  --color-green-600: #00a36c;
  --color-neutral-0: #ffffff;
  --color-neutral-900: #111827;
  /* ... */

  /* Semantic tokens */
  --color-brand-primary: var(--color-green-500);
  --color-background-default: var(--color-neutral-0);
  --color-text-primary: var(--color-neutral-900);
  /* ... */

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  /* ... */

  /* Typography */
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-weight-semibold: 600;
  /* ... */

  /* Component tokens */
  --button-primary-bg: var(--color-brand-primary);
  --card-radius: var(--radius-xl);
  --star-filled: var(--color-brand-primary);
  /* ... */
}

No component should contain a hard-coded hex value, pixel value, or font size that is not referenced through this cascade.