From b8168261a1e3027d8e22131bf80edea703472ae2 Mon Sep 17 00:00:00 2001
From: Juan <juandgoc@gmail.com>
Date: Thu, 16 Apr 2026 10:58:11 -0500
Subject: [PATCH] design system token v0.5

---
 app/tokens/TOKENS.md      | 2 +-
 app/tokens/tokens.ts      | 2 +-
 components/ui/section.tsx | 6 +++---
 lib/catalog.ts            | 2 +-
 scripts/generate-skill.ts | 2 +-
 skill/SKILL.md            | 6 +++---
 tokens/spacing.json       | 4 ++--
 7 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/app/tokens/TOKENS.md b/app/tokens/TOKENS.md
index 9d0d4f5..f25d96c 100644
--- a/app/tokens/TOKENS.md
+++ b/app/tokens/TOKENS.md
@@ -137,7 +137,7 @@
 | `spacing.1.5` | `0.375rem` | 6px |
 | `spacing.component.card-padding` | `1.5rem` | Card internal padding (px-6) |
 | `spacing.component.card-gap` | `1.5rem` | Gap between cards (gap-6) |
-| `spacing.component.section-padding` | `4rem` | Vertical padding between major sections (py-16) |
+| `spacing.component.section-padding` | `2.5rem` | Vertical padding inside sections (py-10) |
 | `spacing.component.form-gap` | `1rem` | Gap between form fields (gap-4) |
 | `spacing.component.button-padding-x` | `1rem` | Button horizontal padding (px-4) |
 | `spacing.component.navbar-height` | `4rem` | Navbar height (h-16) |
diff --git a/app/tokens/tokens.ts b/app/tokens/tokens.ts
index 291fd20..f7fee1a 100644
--- a/app/tokens/tokens.ts
+++ b/app/tokens/tokens.ts
@@ -117,7 +117,7 @@ export const SpacingTokens = {
   '1.5': '0.375rem',
   'component.card-padding': '1.5rem',
   'component.card-gap': '1.5rem',
-  'component.section-padding': '4rem',
+  'component.section-padding': '2.5rem',
   'component.form-gap': '1rem',
   'component.button-padding-x': '1rem',
   'component.navbar-height': '4rem',
diff --git a/components/ui/section.tsx b/components/ui/section.tsx
index 0b4b099..9c76bbe 100644
--- a/components/ui/section.tsx
+++ b/components/ui/section.tsx
@@ -3,12 +3,12 @@ import { cva, type VariantProps } from 'class-variance-authority'
 
 import { cn } from '@/lib/utils'
 
-const sectionVariants = cva('py-16', {
+const sectionVariants = cva('py-10', {
   variants: {
     variant: {
       default: '',
-      highlighted: 'bg-card dark:bg-muted',
-      accent: 'bg-primary/5',
+      highlighted: 'bg-card my-8',
+      accent: 'bg-primary/5 my-8',
     },
     width: {
       narrow: 'max-w-3xl mx-auto',
diff --git a/lib/catalog.ts b/lib/catalog.ts
index 30486e8..e1580bb 100644
--- a/lib/catalog.ts
+++ b/lib/catalog.ts
@@ -405,7 +405,7 @@ export const COMPONENT_CATALOG: ComponentSpec[] = [
     file: 'components/ui/section.tsx',
     category: 'composition',
     exports: ['Section', 'sectionVariants'],
-    description: 'Titled content section with spacing. py-16 between sections.',
+    description: 'Titled content section with spacing. py-10 internal padding. Colored variants (highlighted, accent) get my-8 vertical margin so they visually detach from adjacent sections; default has no margin so same-bg siblings flow seamlessly.',
     props: 'variant?: "default" | "highlighted" | "accent"; width?: "narrow" | "default" | "wide" | "full"; title?: string; description?: string',
     example: '<Section title="Features" description="What we offer" width="wide">Content</Section>',
   },
diff --git a/scripts/generate-skill.ts b/scripts/generate-skill.ts
index dbe4a22..db1d2be 100644
--- a/scripts/generate-skill.ts
+++ b/scripts/generate-skill.ts
@@ -166,7 +166,7 @@ function buildCompositionRules(): string {
   return `## Composition Rules
 
 - **Card spacing**: \`gap-6\` between cards, \`p-6\` internal padding
-- **Section rhythm**: \`py-16\` between major page sections
+- **Section rhythm**: \`py-10\` internal padding per section. Colored sections add \`my-8\` to detach from neighbors
 - **Button placement**: Primary action right, secondary left
 - **Form layout**: Vertical stack with \`gap-4\`, labels above inputs
 - **Navbar**: Fixed top, \`z-50\`, \`h-16\`, logo left, nav center, actions right
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 2276282..31ae42c 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -197,7 +197,7 @@ Source of truth: `tokens/*.json` (W3C DTCG format).
 | `spacing.1.5` | `0.375rem` | 6px |
 | `spacing.component.card-padding` | `1.5rem` | Card internal padding (px-6) |
 | `spacing.component.card-gap` | `1.5rem` | Gap between cards (gap-6) |
-| `spacing.component.section-padding` | `4rem` | Vertical padding between major sections (py-16) |
+| `spacing.component.section-padding` | `2.5rem` | Vertical padding inside sections (py-10) |
 | `spacing.component.form-gap` | `1rem` | Gap between form fields (gap-4) |
 | `spacing.component.button-padding-x` | `1rem` | Button horizontal padding (px-4) |
 | `spacing.component.navbar-height` | `4rem` | Navbar height (h-16) |
@@ -598,7 +598,7 @@ All components live in `components/ui/`. Import with `@/components/ui/<name>`.
 #### Section
 - **File**: `components/ui/section.tsx`
 - **Exports**: `Section`, `sectionVariants`
-- **Description**: Titled content section with spacing. py-16 between sections.
+- **Description**: Titled content section with spacing. py-10 internal padding. Colored variants (highlighted, accent) get my-8 vertical margin so they visually detach from adjacent sections; default has no margin so same-bg siblings flow seamlessly.
 - **Props**: `variant?: "default" | "highlighted" | "accent"; width?: "narrow" | "default" | "wide" | "full"; title?: string; description?: string`
 - **Example**:
 ```tsx
@@ -630,7 +630,7 @@ All components live in `components/ui/`. Import with `@/components/ui/<name>`.
 ## Composition Rules
 
 - **Card spacing**: `gap-6` between cards, `p-6` internal padding
-- **Section rhythm**: `py-16` between major page sections
+- **Section rhythm**: `py-10` internal padding per section. Colored sections add `my-8` to detach from neighbors
 - **Button placement**: Primary action right, secondary left
 - **Form layout**: Vertical stack with `gap-4`, labels above inputs
 - **Navbar**: Fixed top, `z-50`, `h-16`, logo left, nav center, actions right
diff --git a/tokens/spacing.json b/tokens/spacing.json
index f314edb..870fb8f 100644
--- a/tokens/spacing.json
+++ b/tokens/spacing.json
@@ -90,8 +90,8 @@
       },
       "section-padding": {
         "$type": "dimension",
-        "$value": "4rem",
-        "$description": "Vertical padding between major sections (py-16)"
+        "$value": "2.5rem",
+        "$description": "Vertical padding inside sections (py-10)"
       },
       "form-gap": {
         "$type": "dimension",