# Spacing

## Essence

Approved spacing scale for the Portfolio Design System.

`Spacing` defines the only distances the Design System can use for padding, gaps, margins, and layout separation.

## Hook

Use whenever a component, page template, or layout needs distance between or inside elements.

## Internal Rules

- Use only approved `--space-*` tokens for spacing.
- Do not add one-off local pixel, rem, or em spacing values when a spacing token can express the layout.
- Do not introduce a new spacing token without an explicit Design System decision.
- If an exception seems necessary, ask for approval before implementing it.
- Spacing applies to padding, gap, margin, and layout separation.
- Component-specific spacing should still be expressed through the approved spacing scale.

## Current Tokens

- `--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`.
- `--space-12: 3rem / 48px`.

## Use When

- Setting component padding.
- Setting grid or flex gaps.
- Setting vertical rhythm between sections.
- Setting menu or page-template layout separation.
- Reviewing whether a layout uses approved distances.

## Do Not Use When

- The value is not spacing.
- The component needs text size; use Typography.
- The component needs line rhythm; use Line Heights through Typography.
- The component needs interaction state styling; use Focus & Interaction States.

## Exception Rule

If the approved spacing scale cannot express the needed layout:

- stop implementation;
- explain why the current scale is insufficient;
- propose either an approved existing token or a new token;
- ask for user/design-system approval before adding or using the exception.

## Edge Cases

- Border width is not spacing unless it is being used as layout separation.
- Icon stroke width is not spacing.
- Component intrinsic geometry may use calculated values, but padding/gaps/margins should still use spacing tokens.
- If a component has a locked visual requirement, document the exception in its essence.

## Accessibility Notes

- Spacing should preserve clear hit areas for interactive controls.
- Dense layouts should not reduce touch/click targets below usable size.
- Focus rings should not require fake spacing; use inset focus behavior from Focus & Interaction States.

## Related Components And Patterns

- `Component Page Template`: uses spacing for page composition.
- `Preview`: uses spacing for preview padding.
- `Menu Item`: uses spacing for item padding.
- `Collapsible Menu Item`: uses spacing for nested item gaps.
- `Focus & Interaction States`: owns inset focus behavior so spacing is not added only to avoid focus clipping.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `apps/portfolio-site/src/pages/design-system/index.astro`