diff --git a/EXHAUSTIVE_TODO_LIST.md b/EXHAUSTIVE_TODO_LIST.md index b2831a9bf..d0efc4780 100644 --- a/EXHAUSTIVE_TODO_LIST.md +++ b/EXHAUSTIVE_TODO_LIST.md @@ -2499,18 +2499,39 @@ Critical path dependencies: - **Verified**: All spacing utilities are available and working - **Rollback**: N/A (auto-generated by Tailwind) -- [ ] **Action 7.2.1.6**: Document spacing usage +- [x] **Action 7.2.1.6**: Document spacing usage - **Scope**: `apps/web/src/styles/design-tokens.css` - Add comments for usage - **Dependencies**: Action 7.2.1.2 complete ✅ - **Risk**: LOW 🔒 - - **Validation**: Documentation clear + - **Validation**: ✅ Added comprehensive documentation comments to spacing scale: + - **Documented numeric vs semantic scale**: Explained when to use each + - **Usage examples**: Provided examples for both scales (gap-4, p-6 vs gap-md, p-lg) + - **Available utilities**: Listed all spacing utility types (gap-*, p-*, m-*, px-*, py-*, mx-*, my-*, space-x-*, space-y-*) + - **Recommended usage**: Prefer numeric for most cases, semantic for design system consistency + - **Best practices**: Avoid arbitrary values, use nearest scale value + - **Valid scale values**: Documented valid values (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24) + - **Auto-generation note**: Explained that Tailwind v4 auto-generates utilities from CSS variables - **Rollback**: Remove comments -- [ ] **Action 7.2.1.7**: Create SPACING_GUIDE.md - - **Scope**: `apps/web/src/styles/SPACING_GUIDE.md` (create) - Document spacing system usage - - **Dependencies**: Action 7.2.1.4 complete +- [x] **Action 7.2.1.7**: Create SPACING_GUIDE.md + - **Scope**: `apps/web/docs/SPACING_GUIDE.md` (create) - Document spacing system usage + - **Dependencies**: Action 7.2.1.6 complete ✅ - **Risk**: LOW 🔒 - - **Validation**: Guide documents spacing usage + - **Validation**: ✅ Created comprehensive spacing guide: + - **Location**: `apps/web/docs/SPACING_GUIDE.md` + - **Content**: Complete documentation of spacing system + - Overview and scale explanation (numeric vs semantic) + - Full spacing scale table with values, rem, pixels, and usage + - Available utilities (gap, padding, margin, space-between) + - Usage guidelines (when to use numeric vs semantic) + - Common patterns and examples + - Best practices (do's and don'ts) + - ESLint enforcement details + - Migration guide (replacing arbitrary values, converting to semantic) + - Statistics from audit + - Related documentation links + - **Format**: Markdown with tables, code examples, and clear sections + - **Completeness**: Covers all aspects of spacing system usage - **Rollback**: Delete file ### Sub-Epic 7.3: Establish Focal Points 🟢 diff --git a/apps/web/docs/SPACING_GUIDE.md b/apps/web/docs/SPACING_GUIDE.md new file mode 100644 index 000000000..042c9ff16 --- /dev/null +++ b/apps/web/docs/SPACING_GUIDE.md @@ -0,0 +1,209 @@ +# Spacing System Guide + +**Last Updated**: 2025-01-27 +**Action**: 7.2.1.7 - Create SPACING_GUIDE.md +**Status**: ✅ Complete + +## Overview + +The Veza spacing system is built on a **4px base scale** and provides both **numeric** and **semantic** spacing utilities. All spacing utilities are automatically generated by Tailwind v4 from CSS variables defined in `design-tokens.css`. + +## Spacing Scale + +### Numeric Scale (Recommended for Most Cases) + +The numeric scale uses numbers (0-24) that map to 4px increments: + +| Value | Rem | Pixels | Common Usage | +|-------|-----|--------|--------------| +| `0` | 0 | 0px | No spacing | +| `1` | 0.25rem | 4px | Tight spacing, icons | +| `2` | 0.5rem | 8px | Small spacing, compact layouts | +| `3` | 0.75rem | 12px | Medium-small spacing | +| `4` | 1rem | 16px | Base spacing (most common) | +| `5` | 1.25rem | 20px | Medium spacing | +| `6` | 1.5rem | 24px | Large spacing | +| `8` | 2rem | 32px | Extra large spacing | +| `10` | 2.5rem | 40px | Section spacing | +| `12` | 3rem | 48px | Large section spacing | +| `16` | 4rem | 64px | Page section spacing | +| `20` | 5rem | 80px | Major section spacing | +| `24` | 6rem | 96px | Maximum spacing | + +### Semantic Scale (For Design System Consistency) + +The semantic scale provides named values for design system consistency: + +| Name | Value | Pixels | Equivalent Numeric | +|------|-------|--------|-------------------| +| `xs` | 0.25rem | 4px | `1` | +| `sm` | 0.5rem | 8px | `2` | +| `md` | 1rem | 16px | `4` | +| `lg` | 1.5rem | 24px | `6` | +| `xl` | 2rem | 32px | `8` | +| `2xl` | 3rem | 48px | `12` | +| `3xl` | 4rem | 64px | `16` | +| `4xl` | 5rem | 80px | `20` | +| `5xl` / `xxl` | 6rem | 96px | `24` | + +## Available Utilities + +All spacing utilities are automatically generated by Tailwind v4. You can use both numeric and semantic values: + +### Gap Utilities +- **Numeric**: `gap-0`, `gap-1`, `gap-2`, `gap-3`, `gap-4`, `gap-5`, `gap-6`, `gap-8`, `gap-10`, `gap-12`, `gap-16`, `gap-20`, `gap-24` +- **Semantic**: `gap-xs`, `gap-sm`, `gap-md`, `gap-lg`, `gap-xl`, `gap-2xl`, `gap-3xl`, `gap-4xl`, `gap-5xl`, `gap-xxl` + +### Padding Utilities +- **Numeric**: `p-0`, `p-1`, `p-2`, `p-3`, `p-4`, `p-5`, `p-6`, `p-8`, `p-10`, `p-12`, `p-16`, `p-20`, `p-24` +- **Directional**: `px-*`, `py-*`, `pt-*`, `pr-*`, `pb-*`, `pl-*` +- **Semantic**: `p-xs`, `p-sm`, `p-md`, `p-lg`, `p-xl`, `p-2xl`, `p-3xl`, `p-4xl`, `p-5xl`, `p-xxl` + +### Margin Utilities +- **Numeric**: `m-0`, `m-1`, `m-2`, `m-3`, `m-4`, `m-5`, `m-6`, `m-8`, `m-10`, `m-12`, `m-16`, `m-20`, `m-24` +- **Directional**: `mx-*`, `my-*`, `mt-*`, `mr-*`, `mb-*`, `ml-*` +- **Semantic**: `m-xs`, `m-sm`, `m-md`, `m-lg`, `m-xl`, `m-2xl`, `m-3xl`, `m-4xl`, `m-5xl`, `m-xxl` + +### Space Between Utilities +- **Numeric**: `space-x-*`, `space-y-*` (0-24) +- **Semantic**: `space-x-xs`, `space-y-md`, etc. + +## Usage Guidelines + +### When to Use Numeric Scale + +✅ **Use numeric scale for:** +- Most common spacing needs +- Precise pixel control +- Following Tailwind conventions +- Consistency with existing codebase + +**Examples:** +```tsx +
+ + +
+``` + +### When to Use Semantic Scale + +✅ **Use semantic scale for:** +- Reusable component libraries +- Design system consistency +- When spacing meaning is more important than exact pixels +- Building design tokens + +**Examples:** +```tsx + + + + +``` + +## Common Patterns + +### Component Spacing + +```tsx +// Card with consistent padding +... + +// Card with semantic padding +... +``` + +### Layout Spacing + +```tsx +// Grid with gap +
...
+ +// Flex with gap +
...
+``` + +### Section Spacing + +```tsx +// Vertical spacing between sections +
...
+ +// Large section spacing +
...
+``` + +## Best Practices + +### ✅ Do + +- Use scale values (0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24) +- Prefer numeric scale for most cases +- Use semantic scale for design system components +- Be consistent within components +- Use `gap-*` for flexbox/grid layouts +- Use `space-y-*` / `space-x-*` for spacing between children + +### ❌ Don't + +- Use arbitrary values (`gap-[7px]`, `p-[9px]`) - use nearest scale value +- Mix numeric and semantic inconsistently +- Use spacing values outside the scale (7, 9, 11, 13, 14, 15, etc.) +- Use `margin` when `gap` or `space-*` would work +- Override spacing with inline styles + +## ESLint Enforcement + +An ESLint rule enforces spacing scale usage: + +- **Warns on**: Arbitrary spacing values like `gap-[7px]`, `p-[9px]`, etc. +- **Allows**: All scale values (0-24 numeric, xs-xxl semantic) +- **Exceptions**: Use `eslint-disable` comments for legitimate exceptions + +## Migration Guide + +### Replacing Arbitrary Values + +If you find arbitrary spacing values, replace them with the nearest scale value: + +| Arbitrary | Replace With | Reason | +|-----------|--------------|--------| +| `gap-[7px]` | `gap-6` | 7px (28px) → 6 (24px) | +| `p-[9px]` | `p-8` | 9px (36px) → 8 (32px) | +| `gap-[11px]` | `gap-12` | 11px (44px) → 12 (48px) | + +### Converting to Semantic Scale + +For design system components, consider converting to semantic scale: + +| Numeric | Semantic | Use Case | +|---------|----------|----------| +| `gap-2` | `gap-sm` | Small spacing | +| `p-4` | `p-md` | Base padding | +| `gap-6` | `gap-lg` | Large spacing | +| `p-12` | `p-2xl` | Extra large padding | + +## Statistics + +Based on the spacing audit (Action 7.2.1.2): + +- **Total spacing instances**: 2,761 across 366 files +- **Most common**: `gap-2` (519 instances), `p-4` (357 instances), `space-y-4` (159 instances) +- **Scale compliance**: ~99% of spacing uses valid scale values + +## Related Documentation + +- **Design Tokens**: `apps/web/src/styles/design-tokens.css` +- **Spacing Audit**: `apps/web/docs/SPACING_AUDIT_REPORT.md` +- **ESLint Config**: `apps/web/eslint.config.js` + +## Questions? + +If you're unsure which spacing value to use: + +1. **Check existing patterns** in similar components +2. **Use numeric scale** for most cases (gap-2, p-4, etc.) +3. **Use semantic scale** for design system components +4. **Follow the 4px base** - all values should align to 4px increments +5. **Run ESLint** - it will warn on invalid spacing values