aragrp/docs/design-system/spacing.md

Spacing

All spacing must come from the scale below. Arbitrary values (p-[13px], mt-[22px], gap-[0.9rem]) are forbidden unless fixing a temporary third-party bug—and must be replaced before merge.

Scale (px)

Token	px	Rem	Tailwind
1	4	0.25	1
2	8	0.5	2
3	12	0.75	3
4	16	1	4
5	20	1.25	5
6	24	1.5	6
8	32	2	8
10	40	2.5	10
12	48	3	12
16	64	4	16
20	80	5	20
24	96	6	24

Use as p-4, gap-6, mt-8, space-y-4, etc.

Layout-level spacing

Role	Token / class	Notes
Container gutter	px-6 (24)	Via layout.container only
Section Y (mobile)	py-16 (64)	layout.sectionY — adjacent gap = 8rem
Section Y (md+)	md:py-20 (80)	layout.sectionY — adjacent gap = 10rem
Header clearance	pt-28 / md:pt-32	layout.sectionTopWithHeader
Scroll margin	scroll-mt-24 (96)	Anchors under fixed header

Typography-linked spacing

From lib/typography.ts → typeSpacing:

Token	Class	Use
eyebrowToHeading	mt-2	Eyebrow → title
headingToBody	mt-3	Title → body
sectionStack	space-y-4	Section intro stack
heroStack	space-y-6	Hero copy stack
cardStack	gap-1.5	Card title → description
paragraphStack	space-y-4	Stacked paragraphs
labelToControl	gap-1.5	Label → input

Prefer typeSpacing.* over reinventing the same stacks.

Component spacing norms

Component	Internal spacing
Card	gap-6, horizontal px-6, vertical py-6
Button	Tokenized via --btn-px-* / --btn-gap-* — do not override casually
Field groups	gap-7 between fields; gap-3 for checkbox/radio groups
Footer blocks	mb-14, pb-14, column gap-10

Rules

1. Never invent spacing outside the scale.
2. Prefer consistency with nearest sibling sections over “optical” one-off tweaks.
3. Vertical rhythm between major sections comes from layout.sectionY alone — do not add extra section margins that change the shared gap.
4. Icon-to-label gaps inside buttons use button tokens; elsewhere prefer gap-2 / gap-3.

Related

• layout.md
• typography.md
• coding-rules.md