Spacing Tokens

Conty’s spacing system provides a predictable, scalable spacing scale built on rem units. This ensures consistent layouts that respect user font size preferences.

Spacing Scale

The spacing scale follows a logical progression optimized for component layouts:

space[1]

string

default:"0.25rem"

Extra small spacing (4px at default font size)

semanticTokens.space[1] // "0.25rem"

Use cases: Icon padding, tight gaps, small adjustments

space[2]

string

default:"0.5rem"

Small spacing (8px at default font size)

semanticTokens.space[2] // "0.5rem"

Use cases: Compact layouts, internal component spacing

space[3]

string

default:"0.75rem"

Medium-small spacing (12px at default font size)

semanticTokens.space[3] // "0.75rem"

Use cases: Default gaps between related elements

space[4]

string

default:"1rem"

Base spacing (16px at default font size)

semanticTokens.space[4] // "1rem"

Use cases: Standard padding, default margins, general spacingNote: This is the base unit that aligns with default body text size

space[6]

string

default:"1.5rem"

Large spacing (24px at default font size)

semanticTokens.space[6] // "1.5rem"

Use cases: Section spacing, card padding, generous gaps

space[8]

string

default:"2rem"

Extra large spacing (32px at default font size)

semanticTokens.space[8] // "2rem"

Use cases: Page-level spacing, major section breaks

Visual Scale Reference

space[1]  ▪ 0.25rem (4px)
space[2]  ▪▪ 0.5rem (8px)
space[3]  ▪▪▪ 0.75rem (12px)
space[4]  ▪▪▪▪ 1rem (16px)
space[6]  ▪▪▪▪▪▪ 1.5rem (24px)
space[8]  ▪▪▪▪▪▪▪▪ 2rem (32px)

Legacy Spacing Aliases

For teams migrating from older versions, Conty provides named aliases:

// From packages/tokens/src/index.ts
export const spacing = {
  xs: semanticTokens.space[1],  // 0.25rem
  sm: semanticTokens.space[2],  // 0.5rem
  md: semanticTokens.space[4],  // 1rem
  lg: semanticTokens.space[6],  // 1.5rem
  xl: semanticTokens.space[8]   // 2rem
} as const

The numeric scale (space[1], space[2], etc.) is recommended for new projects as it’s more flexible and easier to extend.

Usage Examples

React/TypeScript
Tailwind CSS
CSS Custom Properties

Import spacing tokens directly:

import { semanticTokens } from '@conty/tokens'

function Card({ children }) {
  return (
    <div style={{
      padding: semanticTokens.space[6],
      gap: semanticTokens.space[4]
    }}>
      {children}
    </div>
  )
}

Or use legacy aliases:

import { spacing } from '@conty/tokens'

function Card({ children }) {
  return (
    <div style={{
      padding: spacing.lg,
      gap: spacing.md
    }}>
      {children}
    </div>
  )
}

Tailwind’s spacing scale is automatically configured:

<div className="p-6 gap-4">
  <div className="mb-2">Small margin</div>
  <div className="mt-8">Large margin</div>
</div>

The numbers map directly to Conty’s space tokens:

p-1 = space[1] (0.25rem)
p-2 = space[2] (0.5rem)
p-4 = space[4] (1rem)
p-6 = space[6] (1.5rem)
p-8 = space[8] (2rem)

While spacing tokens don’t map to CSS variables by default, you can create your own:

:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
}

.card {
  padding: var(--space-6);
  gap: var(--space-4);
}

Real-World Examples

Here’s how spacing tokens are used in actual Conty components:

// From packages/ui/src/components/card.tsx
function Card({ className, ...props }) {
  return (
    <div
      className="flex flex-col gap-6 py-6"  // gap-6 = 1.5rem, py-6 = 1.5rem
      {...props}
    />
  )
}

function CardHeader({ className, ...props }) {
  return (
    <div
      className="gap-2 px-6"  // gap-2 = 0.5rem, px-6 = 1.5rem
      {...props}
    />
  )
}

Responsive Spacing

Spacing tokens scale automatically with font size changes:

/* User has default font size (16px) */
.card { padding: 1rem; } /* 16px */

/* User increases font size to 20px */
.card { padding: 1rem; } /* Now 20px */

This makes your layouts more accessible and responsive to user preferences.

Always use rem units for spacing instead of px to respect user font size settings. This is crucial for accessibility.

Spacing Patterns

Common spacing patterns in Conty components:

Component Internal Padding

Use space[4] or space[6] for comfortable internal padding:

<div style={{ padding: semanticTokens.space[6] }}>
  Content
</div>

Element Gaps

Use space[2] to space[4] for gaps between related elements:

<div style={{ display: 'flex', gap: semanticTokens.space[4] }}>
  <Icon />
  <Text>Label</Text>
</div>

Section Spacing

Use space[6] or space[8] for spacing between major sections:

<section style={{ marginBottom: semanticTokens.space[8] }}>
  Section content
</section>

Tight Spacing

Use space[1] for icons, badges, and compact layouts:

<Badge style={{ padding: `${semanticTokens.space[1]} ${semanticTokens.space[2]}` }}>
  New
</Badge>

Border Radius Tokens

While not spacing per se, border radius tokens follow a similar scale:

radius.sm

string

default:"0.525rem"

Small border radius (8.4px at default font size)

semanticTokens.radius.sm // "0.525rem"

CSS Custom Property: --radius-sm

radius.md

string

default:"0.625rem"

Medium border radius (10px at default font size)

semanticTokens.radius.md // "0.625rem"

CSS Custom Property: --radius-md

radius.lg

string

default:"0.725rem"

Large border radius (11.6px at default font size)

semanticTokens.radius.lg // "0.725rem"

CSS Custom Property: --radius-lg

Radius Usage

import { semanticTokens } from '@conty/tokens'

function Button() {
  return (
    <button style={{ borderRadius: semanticTokens.radius.md }}>
      Click me
    </button>
  )
}

Complete Spacing Reference

All Spacing Tokens (TypeScript)

// From packages/tokens/src/index.ts
export const semanticTokens = {
  space: {
    1: "0.25rem",
    2: "0.5rem",
    3: "0.75rem",
    4: "1rem",
    6: "1.5rem",
    8: "2rem"
  },
  radius: {
    sm: "0.525rem",
    md: "0.625rem",
    lg: "0.725rem"
  }
} as const

// Legacy aliases
export const spacing = {
  xs: semanticTokens.space[1],  // "0.25rem"
  sm: semanticTokens.space[2],  // "0.5rem"
  md: semanticTokens.space[4],  // "1rem"
  lg: semanticTokens.space[6],  // "1.5rem"
  xl: semanticTokens.space[8]   // "2rem"
} as const

export const radii = {
  sm: semanticTokens.radius.sm,  // "0.525rem"
  md: semanticTokens.radius.md,  // "0.625rem"
  lg: semanticTokens.radius.lg   // "0.725rem"
} as const

Best Practices

Use rem, not px

Always use the token values (rem) instead of hardcoding pixel values. This ensures your spacing scales with user font size preferences.

// Good
padding: semanticTokens.space[4]

// Avoid
padding: '16px'

Consistent spacing hierarchy

Maintain visual hierarchy by using larger spacing for more important separations:

Related items: space[2] - space[3]
Component internal: space[4] - space[6]
Sections: space[6] - space[8]

Don't create new spacing values

Stick to the defined scale. If you need intermediate values, you’re likely overthinking the design.

// Good
gap: semanticTokens.space[4]

// Avoid
gap: '0.875rem' // Not in the scale

Use Flexbox/Grid gap

Prefer gap over margins when spacing flex/grid children:

// Good
<div style={{ display: 'flex', gap: semanticTokens.space[4] }}>

// Less ideal
<div style={{ display: 'flex' }}>
  <Child style={{ marginRight: semanticTokens.space[4] }} />

Get Started

Design Tokens

Integration

Contributing

Spacing Scale

Visual Scale Reference

Legacy Spacing Aliases

Usage Examples

Real-World Examples

Responsive Spacing

Spacing Patterns

Border Radius Tokens

Radius Usage

Complete Spacing Reference

Best Practices

Next Steps

Typography Tokens

Color Tokens

Build docs developers (and LLMs) love

Get Started

Design Tokens

Integration

Contributing

​Spacing Scale

​Visual Scale Reference

​Legacy Spacing Aliases

​Usage Examples

​Real-World Examples

​Responsive Spacing

​Spacing Patterns

​Border Radius Tokens

​Radius Usage

​Complete Spacing Reference

​Best Practices

​Next Steps

Typography Tokens

Color Tokens

Build docs developers (and LLMs) love

Spacing Scale

Visual Scale Reference

Legacy Spacing Aliases

Usage Examples

Real-World Examples

Responsive Spacing

Spacing Patterns

Border Radius Tokens

Radius Usage

Complete Spacing Reference

Best Practices

Next Steps