@3fn/core 14.0.0 → 15.0.0

package/governance/Token-Family-Color.md

@@ -105,8 +105,8 @@ Neutral colors (white, gray, black) occupy **non-overlapping lightness bands**,
 
 All neutral families share a single `neutralHue` token. The system default is **260°** (cool purple-blue). Products can override this to match their primary color hue, creating a subtle warm/cool relationship between brand identity and neutral surfaces.
 
-- Primary is pink (H≈8°) → neutrals have a warm tint
-- Primary is cyan (H≈204°) → neutrals have a cool tint
+- Primary is pink (H=10°) → neutrals have a warm tint
+- Primary is cyan (H=202.5°) → neutrals have a cool tint
 - Override to any value; set chroma to 0 for pure achromatic
 
 Neutral chroma follows a parabolic curve — higher in the gray mid-range (C≈0.020, where tint is visible on structural elements) and near-zero at the white/black extremes (where tint would be distracting).
@@ -117,15 +117,17 @@ Neutral chroma follows a parabolic curve — higher in the gray mid-range (C≈0
 
 Seven chromatic families, each with a single hue identity:
 
+Hue values are exact, from `src/tokens/color/channels/hues.ts`:
+
 | Family | Hue | Semantic Role | Gamut Note |
 |--------|-----|---------------|------------|
-| **Pink** | ~10° | Error, danger, passion | High chroma capacity |
-| **Orange** | ~42° | Warning, warmth, human identity | Good chroma capacity |
-| **Yellow** | ~109° | Attention, highlights, energy | Max chroma at high lightness |
-| **Green** | ~150° | Success, growth, confirmation | High chroma capacity |
-| **Cyan** | ~204° | Action, navigation, primary interactive | Limited chroma at dark lightness |
-| **Teal** | ~208° | Info, secondary, AI identity | Limited chroma capacity |
-| **Purple** | ~307° | Data, tech, code | Highest chroma capacity |
+| **Pink** | 10.0° | Error, danger, passion | High chroma capacity |
+| **Orange** | 39.5° | Warning, warmth, human identity | Good chroma capacity |
+| **Yellow** | 107.0° | Attention, highlights, energy | Max chroma at high lightness |
+| **Green** | 154.0° | Success, growth, confirmation | High chroma capacity |
+| **Cyan** | 202.5° | Action, navigation, primary interactive | Limited chroma at dark lightness |
+| **Teal** | 209.0° | Info, secondary, AI identity | Limited chroma capacity |
+| **Purple** | 310.0° | Data, tech, code | Highest chroma capacity |
 
 ### Gamut Capacity and Color Strategy
 
@@ -152,7 +154,7 @@ color.{concept}.{role}.{property?}.{state?}
 
 | Token | Primitive | Purpose |
 |-------|-----------|---------|
-| `color.feedback.success.text` | green400 | Success messages, validation |
+| `color.feedback.success.text` | green500 | Success messages, validation (green500 = 4.72:1 on the light canvas; dark theme overrides to green300) |
 | `color.feedback.success.background` | green100 | Success alert backgrounds |
 | `color.feedback.success.border` | green400 | Success borders |
 | `color.feedback.error.text` | pink400 | Error messages |
@@ -173,16 +175,17 @@ These follow the same concept-first pattern documented in semantic token source.
 
 ## Blend Model
 
-Interaction states (hover, pressed, focused, disabled) use **OKLCH-space interpolation**. Blend thresholds are defined as perceptual deltas from the rest state:
+Interaction states (hover, pressed, focused) use **OKLCH-space interpolation**. Blend thresholds are defined as perceptual deltas from the rest state:
 
 | State | ΔL | ΔC | Direction |
 |-------|----|----|-----------|
 | **Hover** | 0.02–0.05 | Preserve | Lighter on dark, darker on light |
 | **Pressed** | 0.05–0.10 | Preserve | Same as hover, further |
 | **Focused** | 0 | +0.02 min | Chroma boost (not lightness) |
-| **Disabled** | 0 | -0.03 min | Desaturate |
 | **Icon lighter** | 0.02–0.04 | Preserve | Lighter (optical balance) |
 
+> **No disabled blend (2026-07-15)**: DesignerPunk does not support disabled states — if an action is unavailable, do not render the component. The corresponding `blend.disabledDesaturate` token is **DEPRECATED** in source and scheduled for removal at the next major version. See Token-Family-Blend § "Anti-Patterns to Avoid".
+
 **Web**: Uses `color-mix(in oklch, ...)` for runtime blending.
 **Native**: Blend results pre-resolved at build time.
 
@@ -233,14 +236,14 @@ static let pink300 = Color.oklch(0.65, 0.242, 10.0)
 ### Android (colormath)
 
 ```kotlin
-val pink300 = Oklch(0.65f, 0.242f, 10.0f).toComposeColor()
+val pink_300 = Oklch(0.65f, 0.242f, 10f).toComposeColor()
 ```
 
 ### DTCG / Figma
 
 sRGB hex output (backward-compatible):
 ```json
-{ "pink-300": { "$value": "#ff2a6d", "$type": "color" } }
+{ "pink300": { "$value": "#fe286d", "$type": "color" } }
 ```
 
 ---
@@ -261,19 +264,34 @@ These calculations can inform color strategy but don't produce tokens. Document
 
 ## Validator Constraints
 
-All color tokens are validated at authoring time:
+`src/color/OklchValidator.ts` defines these constraints:
 
 | Constraint | Rule | Applies To |
 |-----------|------|------------|
 | Lightness monotonicity | L[n] > L[n+1] for adjacent steps | All families |
-| Minimum step distance | |L[n] - L[n+1]| ≥ 0.08 | All families |
+| Minimum step distance | \|L[n] - L[n+1]\| ≥ the family class's floor (`MIN_STEP_DISTANCE`) | All families, per class |
 | Chroma monotonicity (300→500) | C[n] ≥ C[n+1] for steps 300→500 | Chromatic families |
 | sRGB gamut compliance | Resolved oklch(L,C,H) within sRGB | All tokens |
 | P3 gamut awareness | Resolved value exceeds sRGB | Warning (not error) |
 | Hue consistency | All tokens in family share one hue | All families |
-| Neutral chroma ceiling | C ≤ 0.035 | White, gray, black |
+| Neutral chroma ceiling | C ≤ 0.035 (`NEUTRAL_CHROMA_CEILING`) | White, gray, black |
 | Neutral partition gaps | White→gray ≥0.08, gray→black ≥0.04 | Neutral families |
 
+**Scope note.** The minimum step distance is scoped per family class, because the neutral bands are narrower by construction than the chromatic ones:
+
+| Family class | Floor | Band |
+|--------------|-------|------|
+| Chromatic (7 families) | 0.08 | wide lightness range |
+| White | 0.05 | L 1.00 → 0.80 (0.05 per step) |
+| Gray | 0.08 | L 0.72 → 0.32 (0.10 per step) |
+| Black | 0.07 | L 0.28 → 0.00 (0.07 per step) |
+
+These are floors, not targets. A single chromatic-calibrated constant would report a violation on a correct white scale, so `MIN_STEP_DISTANCE` is a per-class map and `validateLightnessScale` takes the family class.
+
+**Enforcement note.** These constraints are enforced by the standing token test suites, which the PR gate runs: `src/tokens/__tests__/chromatic-channels.test.ts` validates all seven chromatic families through `validateFamily`, and `src/tokens/__tests__/neutral-partition.test.ts` validates the white/gray/black partition, chroma ceilings, and lightness scales. A channel edit that breaks a constraint fails CI.
+
+The validator is deliberately **not** wired into `npm run build` / `build:validate`: a consumer building from source should not have their build fail over the ecosystem's own color math. Authorship errors belong in the authoring repo's test lane.
+
 ---
 
 ## WCAG Compliance
@@ -288,7 +306,7 @@ WCAG contrast is validated by converting OKLCH → sRGB relative luminance → c
 
 ### Perceptual Tolerance (Product Tokens)
 
-When authoring product color tokens, the System-First Value Selection rule applies (see Product-Token-Governance.md). Color tolerance uses **CIEDE2000 ΔE₀₀** — not RGB channel comparison.
+When authoring product color tokens, the System-First Value Selection rule applies (see `product-token-governance`). Color tolerance uses **CIEDE2000 ΔE₀₀** — not RGB channel comparison.
 
 ---
 
@@ -309,8 +327,8 @@ When authoring product color tokens, the System-First Value Selection rule appli
 
 ## Related Documentation
 
-- **Token Governance**: `.kiro/steering/Token-Governance.md`
-- **Product Token Governance**: `.kiro/steering/Product-Token-Governance.md` (System-First Value Selection)
-- **Rosetta Architecture**: `.kiro/steering/Rosetta-System-Architecture.md`
-- **Component Development Guide**: `.kiro/steering/Component-Development-Guide.md`
+- **Token Governance**: `token-governance`
+- **Product Token Governance**: `product-token-governance` (System-First Value Selection)
+- **Rosetta Architecture**: `rosetta-system-architecture`
+- **Component Development Guide**: `component-development-guide`
 - **WCAG Guidelines**: [Web Content Accessibility Guidelines 2.1](https://www.w3.org/WAI/WCAG21/quickref/)

package/governance/Token-Family-Glow.md

@@ -96,7 +96,7 @@ Glow opacity determines the transparency of glow effects. Glow opacity tokens us
 ```typescript
 // Single-layer glow with strong opacity
 const singleLayerGlow = {
-  blur: 'glowBlur200',  // 16px
+  blur: 'blur100',  // 16px
   opacity: 'glowOpacity100',  // 0.8
   color: 'glow.neonPurple'
 };
@@ -104,17 +104,17 @@ const singleLayerGlow = {
 // Multi-layer glow (future scope - example only)
 const multiLayerGlow = {
   innerLayer: {
-    blur: 'glowBlur100',  // 8px
+    blur: 'blur050',  // 8px
     opacity: 'glowOpacity100',  // 0.8
     color: 'glow.neonCyan'
   },
   middleLayer: {
-    blur: 'glowBlur200',  // 16px
+    blur: 'blur100',  // 16px
     opacity: 'glowOpacity200',  // 0.6
     color: 'glow.neonCyan'
   },
   outerLayer: {
-    blur: 'glowBlur300',  // 24px
+    blur: 'blur150',  // 24px
     opacity: 'glowOpacity300',  // 0.4
     color: 'glow.neonCyan'
   }
@@ -132,6 +132,8 @@ Glow colors reference existing vibrant primitive colors (purple500, cyan500, yel
 | `glow.neonPurple` | purple500 | Vibrant purple glow | Brand emphasis, primary CTAs |
 | `glow.neonCyan` | cyan500 | Vibrant cyan glow | Tech/digital emphasis, success states |
 | `glow.neonYellow` | yellow500 | Vibrant yellow glow | Attention/warning emphasis, highlights |
+| `glow.neonGreen` | green300 | Vibrant green glow (green300 is the family's highest chroma — brighter for glow) | Success emphasis, confirmation |
+| `glow.neonPink` | pink500 | Vibrant pink glow | Error/danger emphasis, alerts |
 
 **Note**: Glow colors reference existing vibrant colors from the core color system. No new primitive colors are created for glows - semantic glow tokens provide purpose-based naming for emphasis effects.
 
@@ -145,21 +147,21 @@ Glow colors reference existing vibrant primitive colors (purple500, cyan500, yel
 ```typescript
 // Purple glow for brand emphasis
 const brandGlow = {
-  blur: 'glowBlur200',  // 16px
+  blur: 'blur100',  // 16px
   opacity: 'glowOpacity100',  // 0.8
   color: 'glow.neonPurple'  // purple500
 };
 
 // Cyan glow for tech/digital emphasis
 const techGlow = {
-  blur: 'glowBlur300',  // 24px
+  blur: 'blur150',  // 24px
   opacity: 'glowOpacity200',  // 0.6
   color: 'glow.neonCyan'  // cyan500
 };
 
 // Yellow glow for attention/warning
 const attentionGlow = {
-  blur: 'glowBlur400',  // 32px
+  blur: 'blur200',  // 32px
   opacity: 'glowOpacity100',  // 0.8
   color: 'glow.neonYellow'  // yellow500
 };
@@ -180,7 +182,7 @@ Semantic glow tokens will compose primitives to create complete glow styles for
 Button glow for interactive emphasis.
 
 **Potential Composition**:
-- blur: `glowBlur200` (16px)
+- blur: `blur100` (16px)
 - opacity: `glowOpacity100` (0.8)
 - color: `glow.neonPurple`
 
@@ -191,7 +193,7 @@ Button glow for interactive emphasis.
 Focus state glow for accessibility.
 
 **Potential Composition**:
-- blur: `glowBlur100` (8px)
+- blur: `blur050` (8px)
 - opacity: `glowOpacity200` (0.6)
 - color: `glow.neonCyan`
 
@@ -221,7 +223,7 @@ Multi-layer glow architecture will enable complex glow effects with multiple lay
 // Conceptual multi-layer glow structure
 interface MultiLayerGlow {
   layers: Array<{
-    blur: string;      // Reference to glowBlur token
+    blur: string;      // Reference to a blur token (blur050–blur250)
     opacity: string;   // Reference to glowOpacity token
     color: string;     // Reference to glow color token
   }>;
@@ -231,17 +233,17 @@ interface MultiLayerGlow {
 const threeLayerGlow: MultiLayerGlow = {
   layers: [
     {
-      blur: 'glowBlur100',      // 8px - inner layer
+      blur: 'blur050',      // 8px - inner layer
       opacity: 'glowOpacity100', // 0.8
       color: 'glow.neonPurple'
     },
     {
-      blur: 'glowBlur200',      // 16px - middle layer
+      blur: 'blur100',      // 16px - middle layer
       opacity: 'glowOpacity200', // 0.6
       color: 'glow.neonPurple'
     },
     {
-      blur: 'glowBlur300',      // 24px - outer layer
+      blur: 'blur150',      // 24px - outer layer
       opacity: 'glowOpacity300', // 0.4
       color: 'glow.neonPurple'
     }
@@ -327,17 +329,17 @@ Android glow implementation will require gradient-based approaches or custom dra
 
 ### Glow Intensity Guidelines
 
-**Subtle Glow** (glowBlur100-200, glowOpacity200-300):
+**Subtle Glow** (blur050-200, glowOpacity200-300):
 - Small interactive elements
 - Hover states
 - Subtle emphasis
 
-**Standard Glow** (glowBlur200-300, glowOpacity100-200):
+**Standard Glow** (blur100-300, glowOpacity100-200):
 - Primary buttons and CTAs
 - Focus indicators
 - Standard emphasis
 
-**Dramatic Glow** (glowBlur400-500, glowOpacity100):
+**Dramatic Glow** (blur200-500, glowOpacity100):
 - Hero elements
 - Maximum emphasis
 - Focal points
@@ -403,11 +405,11 @@ Glow blur values align to the 4px baseline grid:
 ### Mathematical Relationships
 
 **Blur Tokens**:
-- glowBlur100 = base × 1 = 8 × 1 = 8
-- glowBlur200 = base × 2 = 8 × 2 = 16
-- glowBlur300 = base × 3 = 8 × 3 = 24
-- glowBlur400 = base × 4 = 8 × 4 = 32
-- glowBlur500 = base × 5 = 8 × 5 = 40
+- blur050 = base × 1 = 8 × 1 = 8
+- blur100 = base × 2 = 8 × 2 = 16
+- blur150 = base × 3 = 8 × 3 = 24
+- blur200 = base × 4 = 8 × 4 = 32
+- blur250 = base × 5 = 8 × 5 = 40
 
 **Opacity Tokens**:
 - glowOpacity100 = base × 1 = 0.8 × 1 = 0.8
@@ -430,10 +432,10 @@ Glow blur values align to the 4px baseline grid:
 
 ### Available Now
 
-✅ **Glow Blur Primitives**: glowBlur100-500 (8px - 40px)  
+✅ **Glow Blur Primitives**: blur050–blur250 (8 – 40), from the unified Blur family  
 ✅ **Glow Opacity Primitives**: glowOpacity100-400 (0.8 - 0.2)  
-✅ **Glow Color Semantics**: glow.neonPurple, glow.neonCyan, glow.neonYellow  
-✅ **Mathematical Foundation**: Base-8 system with baseline grid alignment  
+✅ **Glow Color Semantics**: glow.neonPurple, glow.neonCyan, glow.neonYellow, glow.neonGreen, glow.neonPink  
+✅ **Mathematical Foundation**: blur base 16, glow opacity base 0.8; all blur values are multiples of 4  
 ✅ **Documentation**: Primitive token reference and usage guidelines
 
 ### Future Scope

package/governance/Token-Family-Layering.md

@@ -175,6 +175,7 @@ Elevation tokens provide Material Design elevation values for Android. Elevation
 
 | Token | Value | Shadow Reference | Context |
 |-------|-------|------------------|---------|
+| `elevation.none` | 0dp | shadow.none | Flat surface — no elevation, no shadow |
 | `elevation.container` | 8dp | shadow.container | Container elevation (handles z-order and shadow) |
 | `elevation.navigation` | 4dp | shadow.navigation | Navigation elevation (handles z-order and shadow) |
 | `elevation.dropdown` | 8dp | shadow.dropdown | Dropdown elevation (handles z-order and shadow) |

package/governance/Token-Family-Motion.md

@@ -58,16 +58,16 @@ Easing tokens determine animation acceleration curves. The system supports two t
 | Token | Type | Value | Description | Use Case |
 |-------|------|-------|-------------|----------|
 | `easingStandard` | cubicBezier | cubic-bezier(0.4, 0.0, 0.2, 1) | Balanced acceleration | Standard UI transitions, float labels, most animations |
-| `easingDecelerate` | cubicBezier | cubic-bezier(0.0, 0.0, 0.2, 1) | Slow start, fast end | Entering elements, expanding panels, appearing content |
-| `easingAccelerate` | cubicBezier | cubic-bezier(0.4, 0.0, 1, 1) | Fast start, slow end | Exiting elements, collapsing panels, disappearing content |
+| `easingDecelerate` | cubicBezier | cubic-bezier(0.0, 0.0, 0.2, 1) | Fast start, gradual slowdown | Entering elements, expanding panels, appearing content |
+| `easingAccelerate` | cubicBezier | cubic-bezier(0.4, 0.0, 1, 1) | Gradual start, fast finish | Exiting elements, collapsing panels, disappearing content |
 | `easingGlideDecelerate` | linear | 15 stops | Aggressive deceleration, long settle | Indicator glide, weighted slide-to-stop motion |
 
 **Mathematical Foundation**: Cubic-bezier curves for natural, physics-based motion feel. Piecewise linear curves for complex motion that can't be expressed as a single cubic bezier.
 
 **Design Philosophy**:
 - **easingStandard**: Most versatile curve for general UI animations
-- **easingDecelerate**: Elements entering the screen feel natural with slow start
-- **easingAccelerate**: Elements leaving the screen feel natural with fast start
+- **easingDecelerate**: Elements entering the screen feel natural arriving fast and settling gently
+- **easingAccelerate**: Elements leaving the screen feel natural easing away then speeding off
 - **easingGlideDecelerate**: Heavy object sliding to a stop — 41% of movement in first 10% of time, then long gentle settle. No overshoot.
 
 **Platform-Specific Output (cubic bezier)**:
@@ -128,7 +128,16 @@ Components receive pre-rounded values, ensuring consistent rendering across plat
 
 ## Motion Semantic Tokens
 
-Semantic motion tokens compose primitives to create complete motion styles for specific use cases.
+Semantic motion tokens compose primitives to create complete motion styles for specific use cases. The full set (`src/tokens/semantic/MotionTokens.ts`):
+
+| Token | Duration | Easing | Use Case |
+|-------|----------|--------|----------|
+| `motion.floatLabel` | `duration250` | `easingStandard` | Text input label floating up on focus |
+| `motion.focusTransition` | `duration150` | `easingStandard` | Focus gained/lost — quick visual feedback |
+| `motion.buttonPress` | `duration150` | `easingAccelerate` | Scale transform on button press |
+| `motion.modalSlide` | `duration350` | `easingDecelerate` | Modals, drawers, overlays sliding into view |
+| `motion.selectionTransition` | `duration250` | `easingStandard` | Selected/unselected state changes |
+| `motion.settleTransition` | `duration350` | `easingDecelerate` | Color fades and positional slides following a faster state-change snap |
 
 ### motion.floatLabel
 
@@ -528,16 +537,16 @@ val labelOffset by animateFloatAsState(
 - **Feel**: Natural, versatile
 - **Examples**: Float labels, menu animations, general UI transitions
 
-#### easingDecelerate (Slow Start)
+#### easingDecelerate (Decelerating)
 - **Use for**: Entering elements, expanding panels, appearing content
-- **Acceleration**: Slow start, fast end
-- **Feel**: Elements entering the screen
+- **Acceleration**: Fast start, gradual slowdown into rest
+- **Feel**: Elements entering the screen and settling
 - **Examples**: Modal appearing, panel expanding, content fading in
 
-#### easingAccelerate (Fast Start)
+#### easingAccelerate (Accelerating)
 - **Use for**: Exiting elements, collapsing panels, disappearing content
-- **Acceleration**: Fast start, slow end
-- **Feel**: Elements leaving the screen
+- **Acceleration**: Gradual start, fast finish
+- **Feel**: Elements leaving the screen and speeding away
 - **Examples**: Modal dismissing, panel collapsing, content fading out
 
 #### easingGlideDecelerate (Weighted Slide)
@@ -630,8 +639,8 @@ Duration tokens follow a linear +100ms progression:
 Cubic bezier easing tokens use industry-standard curves for natural motion:
 
 - **easingStandard**: cubic-bezier(0.4, 0.0, 0.2, 1) - Balanced acceleration
-- **easingDecelerate**: cubic-bezier(0.0, 0.0, 0.2, 1) - Slow start, fast end
-- **easingAccelerate**: cubic-bezier(0.4, 0.0, 1, 1) - Fast start, slow end
+- **easingDecelerate**: cubic-bezier(0.0, 0.0, 0.2, 1) - Fast start, gradual slowdown
+- **easingAccelerate**: cubic-bezier(0.4, 0.0, 1, 1) - Gradual start, fast finish
 
 **Design Philosophy**: These curves are industry-proven and feel natural across platforms. They provide consistent motion feel that users recognize.
 

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.