@3fn/core 14.1.0 → 15.0.0

package/governance/Token-Family-Opacity.md

@@ -2,7 +2,7 @@
 id: token-family-opacity
 inclusion: manual
 name: Token-Family-Opacity
-description: Opacity token family — transparency tokens with 8% base increment system and 14-token percentage-based scale (opacity000–opacity100). Load when working with transparency effects, disabled states, overlays, or visual hierarchy through opacity.
+description: Opacity token family — transparency tokens with 8% base increment system and 14-token percentage-based scale (opacity000–opacity100). Load when working with transparency effects, overlays, or visual hierarchy through opacity.
 ---
 
 # Opacity Tokens Guide
@@ -44,7 +44,7 @@ All opacity tokens derive from a base unit of **0.08 (8%)**:
 | `opacity024` | 0.24 | 24% | 3 × base | Medium-light overlay |
 | `opacity032` | 0.32 | 32% | 4 × base | Ghost effects, medium overlay |
 | `opacity040` | 0.40 | 40% | 5 × base | Strong overlay |
-| `opacity048` | 0.48 | 48% | 6 × base | Disabled state, very strong overlay |
+| `opacity048` | 0.48 | 48% | 6 × base | Content de-emphasis, very strong overlay |
 | `opacity056` | 0.56 | 56% | 7 × base | Nearly opaque, subtle transparency |
 | `opacity064` | 0.64 | 64% | 8 × base | Very opaque, minimal transparency |
 | `opacity072` | 0.72 | 72% | 9 × base | Extremely opaque |
@@ -132,7 +132,6 @@ Semantic opacity tokens provide contextual meaning for specific transparency pat
 
 **Use Cases**:
 - Modal dialog backdrop/scrim
-- Disabled state overlays
 - Strong background dimming effects
 - Content de-emphasis overlays
 
@@ -250,7 +249,7 @@ Opacity tokens use unitless values (0.0 - 1.0) that are identical across all pla
   background-color: oklch(1 0 0 / var(--opacity-ghost));
 }
 
-.disabled-overlay {
+.scrim-overlay {
   opacity: var(--opacity-048);
 }
 ```
@@ -368,20 +367,26 @@ Use opacity tokens for modal backdrops, overlays, and scrim effects:
 
 ### Disabled States
 
-Use opacity tokens to indicate disabled or inactive states:
+**❌ Don't style disabled states**:
 
 ```typescript
-// Disabled button - apply opacity to entire element
-<Button disabled opacity="opacity048">  // 48% opacity
+// WRONG: DesignerPunk does not support disabled states (Button-CTA disabled-state
+// adjudication, ruled REMOVE corpus-wide with ZERO exceptions — Peter, 2026-07-15,
+// .kiro/issues/button-cta-disabled-state-adjudication.md). Applying opacity to
+// simulate a disabled state is the exact pattern the ruling prohibits.
+<Button disabled opacity="opacity048">
   Submit
 </Button>
-
-// Disabled content area
-<ContentArea disabled opacity="opacity048">
-  <Content />
-</ContentArea>
 ```
 
+If an action is unavailable, use one of the three ruled alternatives instead:
+
+- `state_loading` — for an in-flight async action
+- Validate-on-press / validate-on-blur — for invalid input
+- Do not render the component — for an action that is not available at all
+
+See `Token-Family-Blend.md` § "Anti-Patterns to Avoid" for the same inversion applied to blend tokens.
+
 ### Hover and Interaction Effects
 
 Use opacity tokens for hover states and interaction feedback:
@@ -448,25 +453,6 @@ When combining opacity with colors:
 </Container>
 ```
 
-### Disabled State Accessibility
-
-When using opacity for disabled states:
-
-**Visual Indication**: Opacity alone may not be sufficient to indicate disabled state. Combine with other visual cues (color changes, icons, cursor changes).
-
-**Screen Reader Support**: Ensure disabled state is communicated to assistive technologies through proper ARIA attributes, not just visual opacity changes.
-
-```typescript
-// ✅ CORRECT: Opacity + ARIA for disabled state
-<Button 
-  disabled 
-  aria-disabled="true"
-  opacity="opacity048"
->
-  Submit
-</Button>
-```
-
 ### Motion and Animation
 
 When animating opacity:
@@ -507,7 +493,7 @@ export const tooltipTokens = {
 ### When to Use Semantic Tokens
 
 Use semantic opacity tokens for:
-- Standard transparency patterns (overlays, disabled states, ghost effects)
+- Standard transparency patterns (overlays, ghost effects, content de-emphasis)
 - Consistent visual language across the design system
 - Clear communication of design intent
 
@@ -543,9 +529,9 @@ When applying opacity:
    → Use `opacity.ghost`
    → 32% opacity for highly transparent elements
 
-5. **Disabled state?**
+5. **Strong content de-emphasis, primitive-level?**
    → Use `opacity048` (primitive)
-   → 48% opacity is standard for disabled elements
+   → 48% opacity for strong overlay/de-emphasis effects outside the modal-scrim semantic
 
 6. **Hover feedback?**
    → Use `opacity008` or `opacity016` (primitives)

package/governance/Token-Family-Radius.md

@@ -49,7 +49,8 @@ All radius tokens derive from a base unit of **8px** (radius100):
 | `radius250` | 20px | 2.5 × base (radius100) | ❌ | Strategic flexibility for components |
 | `radius300` | 24px | 3 × base (radius100) | ✅ | Huge rounding, feature elements |
 | `radius400` | 32px | 4 × base (radius100) | ✅ | Maximum rounding |
-| `radiusMax` | 9999px | Special case (infinite) | ❌ | Perfect circles, pill shapes |
+| `radiusMax` | 9999px | Special case (effectively infinite) | ❌ | Pill shapes from rectangles |
+| `radiusHalf` | 50% | Special case (percentage) | ❌ | True circles from square elements |
 
 ### Baseline Grid Alignment
 
@@ -93,7 +94,8 @@ Semantic radius tokens provide contextual meaning for specific component pattern
 | `radiusSmall` | radius050 | 4px | Compact elements, chips, small buttons |
 | `radiusNormal` | radius100 | 8px | Standard elements, buttons, cards, modals |
 | `radiusLarge` | radius200 | 16px | Prominent elements, feature cards, hero sections |
-| `radiusFull` | radiusMax | 9999px | Pills, circular avatars, badges |
+| `radiusFull` | radiusMax | 9999px | Pills and capsules from rectangular elements |
+| `radiusCircle` | radiusHalf | 50% | True circles from square elements (Button-Icon, avatars, badges) |
 
 ### Semantic Token Details
 

package/governance/Token-Family-Responsive.md

@@ -642,10 +642,10 @@ Density scaling affects touch target sizes. Ensure accessibility compliance:
 
 | Density | Scaling | 44pt Base Target | WCAG Compliance |
 |---------|---------|------------------|-----------------|
-| Compact | 0.75× | 33pt | ⚠️ Below minimum |
-| Default | 1.0× | 44pt | ✅ Meets minimum |
-| Comfortable | 1.25× | 55pt | ✅ Exceeds minimum |
-| Spacious | 1.5× | 66pt | ✅ Exceeds minimum |
+| Compact | 0.75× | 33pt | ⚠️ Meets AA (SC 2.5.8, ≥24pt); below the AAA 44pt target |
+| Default | 1.0× | 44pt | ✅ Meets AAA (SC 2.5.5, 44×44) |
+| Comfortable | 1.25× | 55pt | ✅ Exceeds AAA target |
+| Spacious | 1.5× | 66pt | ✅ Exceeds AAA target |
 
 **Recommendation**: Use compact density only for mouse/keyboard interfaces. For touch interfaces, use default or higher density.
 

package/governance/Token-Family-Shadow.md

@@ -44,9 +44,9 @@ Horizontal offsets represent the sun's position throughout the day:
 | `shadowOffsetX.n150` | -6px | Morning - medium left offset | Morning lighting |
 | `shadowOffsetX.n100` | -4px | Strategic flexibility - small left | Subtle morning shadows |
 | `shadowOffsetX.000` | 0px | Noon - no horizontal offset | Standard UI shadows |
-| `shadowOffsetX.100` | 4px | Strategic flexibility - small right | Subtle afternoon shadows |
-| `shadowOffsetX.150` | 6px | Afternoon - medium right offset | Afternoon lighting |
-| `shadowOffsetX.200` | 8px | Strategic flexibility - medium-large right | Afternoon variations |
+| `shadowOffsetX.100` | 4px | Strategic flexibility - small right | Subtle dusk shadows |
+| `shadowOffsetX.150` | 6px | Dusk - medium right offset | Dusk lighting |
+| `shadowOffsetX.200` | 8px | Strategic flexibility - medium-large right | Dusk variations |
 | `shadowOffsetX.300` | 12px | Sunset - large right offset | Dramatic sunset lighting |
 
 **Mathematical Foundation**: Base value = 4px (4px baseline grid alignment)
@@ -54,7 +54,7 @@ Horizontal offsets represent the sun's position throughout the day:
 **Sun Arc Framework**:
 - **Negative values**: Sunrise/morning shadows (shadow falls left)
 - **Zero value**: Noon shadows (no horizontal offset)
-- **Positive values**: Afternoon/sunset shadows (shadow falls right)
+- **Positive values**: Dusk/sunset shadows (shadow falls right)
 
 #### Shadow Offset Y (Vertical Direction)
 
@@ -64,7 +64,7 @@ Vertical offsets scale with depth (all positive - shadows fall downward):
 |-------|-------|-------------|----------|
 | `shadowOffsetY.100` | 4px | Depth 100 / Noon - short shadow | Low elevation elements |
 | `shadowOffsetY.200` | 8px | Depth 200 - medium shadow | Raised elements (cards, modals) |
-| `shadowOffsetY.300` | 12px | Morning/Afternoon - medium-long | Directional lighting |
+| `shadowOffsetY.300` | 12px | Morning/Dusk - medium-long | Directional lighting |
 | `shadowOffsetY.400` | 16px | Depth 300 / Sunrise/Sunset - long | Floating elements (FABs) |
 
 **Mathematical Foundation**: Base value = 4px, scales with multipliers (1x, 2x, 3x, 4x)
@@ -92,6 +92,7 @@ Shadow opacity determines shadow darkness based on quality and depth.
 
 | Token | Value | Description | Use Case |
 |-------|-------|-------------|----------|
+| `shadowOpacityNone` | 0 | No shadow — flat surface | `shadow.none` |
 | `shadowOpacityHard` | 0.4 | Darker for sharp shadows | Strong, defined shadows |
 | `shadowOpacityModerate` | 0.3 | Balanced opacity | Standard UI shadows |
 | `shadowOpacitySoft` | 0.2 | Lighter for diffuse shadows | Subtle, gentle shadows |
@@ -118,16 +119,16 @@ Shadow colors are based on art theory: shadows are rarely pure black but tinted
 | `shadowOrange100` | rgb(25, 20, 15) | Warm tint | Cool light creates warm shadows |
 | `shadowGray100` | rgb(15, 20, 30) | Blue-gray tint | Ambient/overcast lighting |
 
-#### Semantic Shadow Colors
+#### No Semantic Shadow Color Layer
 
-| Token | References | Description | Use Case |
-|-------|-----------|-------------|----------|
-| `color.shadow.default` | shadowBlack100 | Default shadow color | Standard UI shadows (noon) |
-| `color.shadow.warm` | shadowBlue100 | Warm shadow color | Sunrise/sunset lighting |
-| `color.shadow.cool` | shadowOrange100 | Cool shadow color | Cool lighting environments |
-| `color.shadow.ambient` | shadowGray100 | Ambient shadow color | Overcast/ambient lighting |
+There is **no** `color.shadow.*` semantic tier. Shadow tokens reference the primitive shadow colors
+directly (`shadow.container` → `shadowBlack100`), matching how typography tokens compose primitives
+without an intermediate semantic layer. The rationale is recorded in `src/tokens/semantic/ColorTokens.ts`
+§ "ARCHITECTURAL DECISION: Shadow Color Semantic Layer Removed".
 
-**Note**: Shadow colors are mode-agnostic (always dark) regardless of light/dark theme.
+**Note**: Shadow colors are mode-agnostic (always dark) regardless of light/dark theme. They are also
+the four primitives that still resolve from the legacy `src/tokens/ColorTokens.ts` RGBA source rather
+than from the OKLCH channel model.
 
 ---
 
@@ -135,6 +136,28 @@ Shadow colors are based on art theory: shadows are rarely pure black but tinted
 
 Semantic shadow tokens compose primitives to create complete shadow styles for specific use cases.
 
+**Complete set** (`src/tokens/semantic/ShadowTokens.ts`) — 15 tokens:
+
+| Token | offsetX | offsetY | blur | opacity | color |
+|-------|---------|---------|------|---------|-------|
+| `shadow.none` | `shadowOffsetX.000` | `shadowOffsetY.000` | `blur000` | `shadowOpacityNone` | `shadowBlack100` |
+| `shadow.container` | `shadowOffsetX.000` | `shadowOffsetY.100` | `blur075` | `shadowOpacityModerate` | `shadowBlack100` |
+| `shadow.navigation` | `shadowOffsetX.000` | `shadowOffsetY.100` | `blur125` | `shadowOpacitySoft` | `shadowBlack100` |
+| `shadow.dropdown` | `shadowOffsetX.000` | `shadowOffsetY.100` | `blur075` | `shadowOpacityModerate` | `shadowBlack100` |
+| `shadow.modal` | `shadowOffsetX.000` | `shadowOffsetY.200` | `blur100` | `shadowOpacityDepth200` | `shadowBlack100` |
+| `shadow.toast` | `shadowOffsetX.000` | `shadowOffsetY.300` | `blur150` | `shadowOpacityDepth300` | `shadowBlack100` |
+| `shadow.tooltip` | `shadowOffsetX.000` | `shadowOffsetY.300` | `blur150` | `shadowOpacityDepth300` | `shadowBlack100` |
+| `shadow.fab` | `shadowOffsetX.300` | `shadowOffsetY.400` | `blur025` | `shadowOpacityHard` | `shadowBlue100` |
+| `shadow.hover` | `shadowOffsetX.000` | `shadowOffsetY.100` | `blur125` | `shadowOpacitySoft` | `shadowBlack100` |
+| `shadow.navigation.indicator` | `shadowOffsetX.000` | `shadowOffsetY.000` | `blur025` | `shadowOpacitySoft` | `shadowBlack100` |
+| `shadow.sunrise` | `shadowOffsetX.n300` | `shadowOffsetY.200` | `blur075` | `shadowOpacityModerate` | `shadowBlue100` |
+| `shadow.morning` | `shadowOffsetX.n150` | `shadowOffsetY.200` | `blur075` | `shadowOpacityModerate` | `shadowBlack100` |
+| `shadow.noon` | `shadowOffsetX.000` | `shadowOffsetY.200` | `blur075` | `shadowOpacityModerate` | `shadowBlack100` |
+| `shadow.dusk` | `shadowOffsetX.150` | `shadowOffsetY.200` | `blur075` | `shadowOpacityModerate` | `shadowBlack100` |
+| `shadow.sunset` | `shadowOffsetX.300` | `shadowOffsetY.200` | `blur075` | `shadowOpacityModerate` | `shadowBlue100` |
+
+The sections below detail the most frequently used of these.
+
 ### Standard UI Shadows
 
 #### shadow.container
@@ -144,9 +167,9 @@ Standard container shadow with noon lighting and moderate quality.
 **Composition**:
 - offsetX: `shadowOffsetX.000` (0px)
 - offsetY: `shadowOffsetY.100` (4px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
 **Use Cases**: Cards, panels, containers with subtle elevation
 
@@ -159,9 +182,9 @@ Modal shadow with noon lighting and depth 200.
 **Composition**:
 - offsetX: `shadowOffsetX.000` (0px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurDepth200` (16px)
+- blur: `blur100` (16px)
 - opacity: `shadowOpacityDepth200` (0.35)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
 **Use Cases**: Modals, dialogs, overlays with medium elevation
 
@@ -174,9 +197,9 @@ Hover state shadow with noon lighting and soft quality.
 **Composition**:
 - offsetX: `shadowOffsetX.000` (0px)
 - offsetY: `shadowOffsetY.100` (4px)
-- blur: `shadowBlurSoft` (20px)
+- blur: `blur125` (20px)
 - opacity: `shadowOpacitySoft` (0.2)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
 **Use Cases**: Hover states, interactive elements with subtle elevation change
 
@@ -189,9 +212,9 @@ Floating action button shadow with sunset lighting and hard quality.
 **Composition**:
 - offsetX: `shadowOffsetX.300` (12px)
 - offsetY: `shadowOffsetY.400` (16px)
-- blur: `shadowBlurHard` (4px)
+- blur: `blur025` (4px)
 - opacity: `shadowOpacityHard` (0.4)
-- color: `color.shadow.warm` (blue-gray)
+- color: `shadowBlue100` (blue-gray)
 
 **Use Cases**: Floating action buttons, prominent CTAs with dramatic elevation
 
@@ -204,7 +227,7 @@ Navigation indicator shadow for active segment/tab indicators within navigation
 **Composition**:
 - offsetX: `shadowOffsetX.000` (0px)
 - offsetY: `shadowOffsetY.000` (0px)
-- blur: `shadowBlurHard` (4px)
+- blur: `blur025` (4px)
 - opacity: `shadowOpacitySoft` (0.2)
 - color: `shadowBlack100` (black)
 
@@ -227,9 +250,9 @@ Sunrise lighting shadow with left offset and warm color.
 **Composition**:
 - offsetX: `shadowOffsetX.n300` (-12px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.warm` (blue-gray)
+- color: `shadowBlue100` (blue-gray)
 
 **Use Cases**: Sunrise-themed interfaces, morning dashboards
 
@@ -242,9 +265,9 @@ Morning lighting shadow with medium left offset and default color.
 **Composition**:
 - offsetX: `shadowOffsetX.n150` (-6px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
 **Use Cases**: Morning-themed interfaces, subtle directional lighting
 
@@ -257,9 +280,9 @@ Noon lighting shadow with no horizontal offset and default color.
 **Composition**:
 - offsetX: `shadowOffsetX.000` (0px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
 **Use Cases**: Noon-themed interfaces, neutral directional lighting, completing the sun arc series
 
@@ -267,18 +290,18 @@ Noon lighting shadow with no horizontal offset and default color.
 
 **Relationship to shadow.container**: This token uses the same noon lighting pattern as `shadow.container` (no horizontal offset, default color). The difference is semantic naming: `shadow.noon` explicitly indicates noon lighting in a directional series, while `shadow.container` is named for its use case (standard container shadows). Both are valid choices depending on whether you want to emphasize lighting (noon) or use case (container).
 
-#### shadow.afternoon
+#### shadow.dusk
 
-Afternoon lighting shadow with medium right offset and default color.
+Dusk lighting shadow with medium right offset and default color.
 
 **Composition**:
 - offsetX: `shadowOffsetX.150` (6px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.default` (black)
+- color: `shadowBlack100` (black)
 
-**Use Cases**: Afternoon-themed interfaces, subtle directional lighting
+**Use Cases**: Dusk-themed interfaces, subtle directional lighting
 
 **Visual Effect**: Shadow falls to the right with neutral color
 
@@ -289,9 +312,9 @@ Sunset lighting shadow with right offset and warm color.
 **Composition**:
 - offsetX: `shadowOffsetX.300` (12px)
 - offsetY: `shadowOffsetY.200` (8px)
-- blur: `shadowBlurModerate` (12px)
+- blur: `blur075` (12px)
 - opacity: `shadowOpacityModerate` (0.3)
-- color: `color.shadow.warm` (blue-gray)
+- color: `shadowBlue100` (blue-gray)
 
 **Use Cases**: Sunset-themed interfaces, evening dashboards
 
@@ -651,11 +674,11 @@ For precise shadow control beyond elevation approximation, custom drawable gener
 - **Visual weight**: Very subtle, omnidirectional
 - **Lighting**: None (no directional offset — element is inside a container, not floating)
 
-#### Directional Shadows (sunrise, morning, noon, afternoon, sunset)
+#### Directional Shadows (sunrise, morning, noon, dusk, sunset)
 - **Use for**: Themed interfaces, time-of-day experiences, completing the sun arc series
 - **Elevation level**: Medium (depth 200)
 - **Visual weight**: Moderate with directional character
-- **Lighting**: Varies by time of day (sunrise → morning → noon → afternoon → sunset)
+- **Lighting**: Varies by time of day (sunrise → morning → noon → dusk → sunset)
 
 **Note**: For standard UI shadows without directional theming, use `shadow.container` instead of `shadow.noon`. Both use noon lighting, but `shadow.container` is semantically named for its use case.
 
@@ -666,11 +689,11 @@ When semantic shadows don't meet your needs, compose custom shadows from primiti
 ```typescript
 // Example: Custom shadow for a specific use case
 const customShadow = {
-  offsetX: 'shadowOffsetX.150',      // Afternoon offset
+  offsetX: 'shadowOffsetX.150',      // Dusk offset
   offsetY: 'shadowOffsetY.200',      // Medium depth
-  blur: 'shadowBlurSoft',            // Soft edges
+  blur: 'blur125',                   // Soft edges (20)
   opacity: 'shadowOpacityModerate',  // Balanced opacity
-  color: 'color.shadow.default'      // Neutral color
+  color: 'shadowBlack100'            // Neutral color
 };
 ```
 
@@ -727,12 +750,12 @@ Shadow values preferably align to the 4px baseline grid:
 - shadowOffsetY.100 = base × 1 = 4 × 1 = 4
 - shadowOffsetY.400 = base × 4 = 4 × 4 = 16
 
-**Blur Tokens**:
-- shadowBlurHard = base × 1 = 4 × 1 = 4
-- shadowBlurModerate = base × 3 = 4 × 3 = 12
-- shadowBlurSoft = base × 5 = 4 × 5 = 20
-- shadowBlurDepth200 = base × 4 = 4 × 4 = 16
-- shadowBlurDepth300 = base × 6 = 4 × 6 = 24
+**Blur Tokens** (unified `blur` family, base 16 — Spec 089 replaced the old `shadowBlur*` family; see `token-family-blur`):
+- blur025 = base × 0.25 = 16 × 0.25 = 4
+- blur075 = base × 0.75 = 16 × 0.75 = 12
+- blur100 = base × 1 = 16 × 1 = 16
+- blur125 = base × 1.25 = 16 × 1.25 = 20
+- blur150 = base × 1.5 = 16 × 1.5 = 24
 
 **Opacity Tokens**:
 - shadowOpacityHard = base × 1.33 = 0.3 × 1.33 ≈ 0.4

package/governance/Token-Family-Spacing.md

@@ -40,6 +40,8 @@ All spacing tokens derive from a base unit of **8px** (space100):
 
 | Token Name | Value | Mathematical Relationship | Use Case |
 |------------|-------|---------------------------|----------|
+| `space000` | 0px | 0 × base (space100) | Explicit zero spacing |
+| `space025` | 2px | 0.25 × base (space100) | Hairline separation, minimal gaps |
 | `space050` | 4px | 0.5 × base (space100) | Minimal spacing, tight padding |
 | `space075` | 6px | 0.75 × base (space100) | Strategic flexibility for components |
 | `space100` | 8px | 1 × base (baseline unit) | Standard spacing unit |
@@ -56,9 +58,9 @@ All spacing tokens derive from a base unit of **8px** (space100):
 
 ### Baseline Grid Alignment
 
-**8px Baseline Grid**: Primary spacing tokens (050, 100, 150, 200, 300, 400, 500, 600, 700, 800) align to the 8px baseline grid, ensuring consistent vertical rhythm across layouts.
+**8-unit Baseline Grid**: Spacing tokens 000, 100, 200, 300, 400, 500, 600, 700 and 800 carry `baselineGridAlignment: true` in source — they are exact multiples of 8 and drive vertical rhythm. Tokens 025 (2), 050 (4) and 150 (12) are flagged `false`: they are valid, frequently-used values, but they are sub-grid rather than grid-aligned.
 
-**4px Subgrid**: space050 (4px) provides subgrid alignment for fine-tuned spacing needs while maintaining mathematical relationships.
+**4px Subgrid**: space050 (4px) — and space025 (2px) below it — provide subgrid alignment for fine-tuned spacing needs while maintaining mathematical relationships to the base unit.
 
 **Strategic Flexibility Tokens**: space075 (6px), space125 (10px), and space250 (20px) are mathematically derived exceptions that don't align to the 8px grid but maintain clear relationships to the base unit.
 
@@ -95,6 +97,7 @@ Inset spacing tokens define internal spacing (padding) within containers and com
 
 | Token Name | Primitive Reference | Value | Mathematical Relationship | Use Case |
 |------------|---------------------|-------|---------------------------|----------|
+| `space.inset.none` | space000 | 0px | 0 × base (space100) | No internal spacing - edge-to-edge content |
 | `space.inset.050` | space050 | 4px | 0.5 × base (space100) | Minimal internal spacing - compact chips, dense toolbars, tight buttons |
 | `space.inset.075` | space075 | 6px | 0.75 × base (space100) | Compact internal spacing - medium-density components, checkbox medium size |
 | `space.inset.100` | space100 | 8px | 1 × base (space100) | Compact internal spacing - small buttons, compact cards, dense forms |
@@ -130,8 +133,9 @@ Elements that form a cohesive unit (form fields in a group, list items, navigati
 
 | Token Name | Primitive Reference | Value | Density | Use Case |
 |------------|---------------------|-------|---------|----------|
-| `space.grouped.minimal` | space050 | 4px | Tight | Minimal separation - compact lists, dense navigation |
-| `space.grouped.tight` | space075 | 6px | Tight | Tight grouping - form field groups, compact menus |
+| `space.grouped.none` | space000 | 0px | — | No separation - flush/abutting elements |
+| `space.grouped.minimal` | space025 | 2px | Tight | Minimal separation - compact lists, dense navigation |
+| `space.grouped.tight` | space050 | 4px | Tight | Tight grouping - form field groups, compact menus |
 | `space.grouped.normal` | space100 | 8px | Normal | Standard grouping - default list spacing, form groups |
 | `space.grouped.loose` | space150 | 12px | Loose | Loose grouping - comfortable lists, relaxed forms |
 
@@ -141,7 +145,8 @@ Elements that share context but aren't tightly grouped (related cards, sidebar s
 
 | Token Name | Primitive Reference | Value | Density | Use Case |
 |------------|---------------------|-------|---------|----------|
-| `space.related.tight` | space150 | 12px | Tight | Tight relationship - compact card grids, dense sidebars |
+| `space.related.none` | space000 | 0px | — | No separation between related elements |
+| `space.related.tight` | space100 | 8px | Tight | Tight relationship - compact card grids, dense sidebars |
 | `space.related.normal` | space200 | 16px | Normal | Standard relationship - default card spacing, content blocks |
 | `space.related.loose` | space300 | 24px | Loose | Loose relationship - comfortable card grids, relaxed layouts |
 
@@ -151,9 +156,10 @@ Elements that are distinct but share a common context (page sections, major cont
 
 | Token Name | Primitive Reference | Value | Density | Use Case |
 |------------|---------------------|-------|---------|----------|
-| `space.separated.tight` | space300 | 24px | Tight | Tight separation - compact sections, dense pages |
-| `space.separated.normal` | space400 | 32px | Normal | Standard separation - default section spacing |
-| `space.separated.loose` | space600 | 48px | Loose | Loose separation - generous section spacing, breathing room |
+| `space.separated.none` | space000 | 0px | — | No separation |
+| `space.separated.tight` | space200 | 16px | Tight | Tight separation - compact sections, dense pages |
+| `space.separated.normal` | space300 | 24px | Normal | Standard separation - default section spacing |
+| `space.separated.loose` | space400 | 32px | Loose | Loose separation - generous section spacing, breathing room |
 
 #### Sectioned Spacing (Major Page Divisions)
 
@@ -161,9 +167,10 @@ Major divisions between distinct page sections or content areas.
 
 | Token Name | Primitive Reference | Value | Density | Use Case |
 |------------|---------------------|-------|---------|----------|
-| `space.sectioned.tight` | space600 | 48px | Tight | Tight sectioning - compact page divisions |
-| `space.sectioned.normal` | space800 | 64px | Normal | Standard sectioning - default major divisions |
-| `space.sectioned.loose` | space1000 | 80px | Loose | Loose sectioning - generous page divisions, maximum breathing room |
+| `space.sectioned.none` | space000 | 0px | — | No sectioning gap |
+| `space.sectioned.tight` | space400 | 32px | Tight | Tight sectioning - compact page divisions |
+| `space.sectioned.normal` | space500 | 40px | Normal | Standard sectioning - default major divisions |
+| `space.sectioned.loose` | space600 | 48px | Loose | Loose sectioning - generous page divisions, maximum breathing room |
 
 ---
 
@@ -185,10 +192,13 @@ space300 = space100 × 3    = 24px
 space400 = space100 × 4    = 32px
 space500 = space100 × 5    = 40px
 space600 = space100 × 6    = 48px
+space700 = space100 × 7    = 56px
 space800 = space100 × 8    = 64px
-space1000 = space100 × 10  = 80px
 ```
 
+The scale ends at `space800` (64). There is no `space900` or `space1000` — component dimensions
+beyond 64 come from the Sizing family (`size900`, `size1000`, `size1600`), not from spacing.
+
 ### Doubling Pattern
 
 Many tokens follow a doubling pattern for easy mental calculation: