@3fn/core 14.0.0 → 15.0.0

package/governance/Component-Readiness-Status.md

@@ -520,17 +520,16 @@ metadata:
 **Query component readiness**:
 ```
 get_section({ 
-  path: "component-family-form-inputs", 
-  heading: "Component Readiness" 
+  path: "component-readiness-status", 
+  heading: "Individual Component Status" 
 })
 ```
 
 **Response includes**:
-- Component name
-- Current readiness status
-- Status indicator emoji
-- Usage recommendations
-- Migration guidance (if deprecated)
+- Component name and family
+- Roll-up status indicator (production-ready / web-ready-mobile-scaffold / scaffold)
+- Per-platform readiness breakdown (web / iOS / Android)
+- Implementation path
 
 ---
 

package/governance/Component-Templates.md

@@ -696,7 +696,7 @@ Use when semantic variants represent different states or statuses.
 #### Focusable Contract
 
 ```yaml
-focusable:
+interaction_focusable:
   description: Can receive keyboard focus
   behavior: |
     Component can receive focus via Tab key navigation.
@@ -712,7 +712,7 @@ focusable:
 #### Pressable Contract
 
 ```yaml
-pressable:
+interaction_pressable:
   description: Responds to press/click events
   behavior: |
     Component responds to click, tap, Enter key, and Space key.
@@ -729,7 +729,7 @@ pressable:
 #### Hoverable Contract
 
 ```yaml
-hoverable:
+interaction_hover:
   description: Visual feedback on hover (pointer devices only)
   behavior: |
     On pointer devices, component shows visual feedback when mouse
@@ -783,7 +783,7 @@ see the exclusion reason above and the 2026-07-15 adjudication ruling
 #### Error State Contract
 
 ```yaml
-error_state:
+state_error:
   description: Shows error message and styling
   behavior: |
     When in error state, component displays:
@@ -804,7 +804,7 @@ error_state:
 #### Success State Contract
 
 ```yaml
-success_state:
+state_success:
   description: Shows success styling
   behavior: |
     When in success state, component displays:
@@ -822,7 +822,7 @@ success_state:
 #### Loading State Contract
 
 ```yaml
-loading_state:
+state_loading:
   description: Shows loading indicator during async operations
   behavior: |
     When in loading state, component:
@@ -846,7 +846,7 @@ loading_state:
 #### Focus Ring Contract
 
 ```yaml
-focus_ring:
+interaction_focus_ring:
   description: WCAG 2.4.7 focus visible indicator
   behavior: |
     When focused via keyboard, component displays:
@@ -867,7 +867,7 @@ focus_ring:
 #### Reduced Motion Support Contract
 
 ```yaml
-reduced_motion_support:
+accessibility_reduced_motion:
   description: Respects prefers-reduced-motion
   behavior: |
     When user has reduced motion preference:
@@ -910,7 +910,7 @@ accessibility_hidden:
 #### Float Label Animation Contract
 
 ```yaml
-float_label_animation:
+content_float_label:
   description: Label animates on focus
   behavior: |
     Label smoothly transitions from placeholder position inside component
@@ -929,7 +929,7 @@ float_label_animation:
 #### Pressed State Visual Contract
 
 ```yaml
-pressed_state:
+interaction_pressed:
   description: Visual feedback when pressed
   behavior: |
     Component shows visual feedback during active press/click.
@@ -949,7 +949,7 @@ pressed_state:
 #### Gradient Glow Contract
 
 ```yaml
-gradient_glow:
+visual_gradient_glow:
   description: Radial gradient background providing state-dependent visual emphasis
   behavior: |
     Component renders an elliptical radial gradient background on
@@ -975,7 +975,7 @@ gradient_glow:
 #### Validates On Blur Contract
 
 ```yaml
-validates_on_blur:
+validation_on_blur:
   description: Validation triggers on blur
   behavior: |
     Validation state is evaluated when component loses focus.
@@ -1014,7 +1014,7 @@ custom_validation:
 #### Contains Children Contract
 
 ```yaml
-contains_children:
+layout_contains_children:
   description: Can contain child components
   behavior: |
     Component can contain any child components or content.
@@ -1034,7 +1034,7 @@ contains_children:
 #### Renders SVG Contract
 
 ```yaml
-renders_svg:
+visual_renders_svg:
   description: Renders inline SVG with correct attributes
   behavior: |
     Component renders an inline SVG element with:
@@ -1042,7 +1042,7 @@ renders_svg:
     - Appropriate fill/stroke attributes
     - Proper sizing based on size prop
     SVG content is loaded based on name from internal map.
-  wcag: N/A
+  wcag: null
   platforms: [web, ios, android]
   validation: |
     - SVG element renders with correct viewBox
@@ -1077,18 +1077,18 @@ renders_svg:
 
 | Behavior Needed | Contract(s) to Include |
 |-----------------|------------------------|
-| Keyboard navigation | focusable, focus_ring |
-| Click/tap interaction | pressable, pressed_state |
-| Mouse hover feedback | hoverable |
-| Action temporarily unavailable | state_loading (in-flight), validates_on_blur (invalid input), or do not render (no valid path) — never a disabled-state contract; see "No Disabled States — Standardized Exclusion" |
-| Error handling | error_state, validates_on_blur |
-| Success feedback | success_state |
-| Loading indication | loading_state |
-| Animation support | reduced_motion_support |
+| Keyboard navigation | interaction_focusable, interaction_focus_ring |
+| Click/tap interaction | interaction_pressable, interaction_pressed |
+| Mouse hover feedback | interaction_hover |
+| Action temporarily unavailable | state_loading (in-flight), validation_on_blur (invalid input), or do not render (no valid path) — never a disabled-state contract; see "No Disabled States — Standardized Exclusion" |
+| Error handling | state_error, validation_on_blur |
+| Success feedback | state_success |
+| Loading indication | state_loading |
+| Animation support | accessibility_reduced_motion |
 | Decorative elements | accessibility_hidden |
-| Form validation | validates_on_blur, custom_validation |
-| Container behavior | contains_children |
-| Icon rendering | renders_svg, accessibility_hidden |
+| Form validation | validation_on_blur, custom_validation |
+| Container behavior | layout_contains_children |
+| Icon rendering | visual_renders_svg, accessibility_hidden |
 
 ### Application MCP Checklist
 

package/governance/Contract-System-Reference.md

@@ -180,7 +180,7 @@ excludes:
 | `category` | Taxonomy category (redundant with name prefix — enables validation) |
 | `description` | Short description of the behavioral guarantee |
 | `behavior` | Detailed behavior description |
-| `wcag` | WCAG criterion this contract supports (null if not applicable) |
+| `wcag` | WCAG criterion this contract supports — required for allowlisted contracts (use the 'N/A' sentinel when genuinely not applicable); null only for non-allowlisted contracts |
 | `platforms` | Platforms where this contract applies |
 | `validation` | Testable criteria for verifying the contract |
 | `test_approach` | How to test this contract |

package/governance/DTCG-Integration-Guide.md

@@ -63,7 +63,7 @@ Semantic tokens reference primitives using DTCG alias syntax: `{group.tokenName}
 ```json
 {
   "color.feedback.success.text": {
-    "$value": "{color.green400}",
+    "$value": "{color.green500}",
     "$type": "color",
     "$description": "Green text color for success states"
   }
@@ -78,13 +78,15 @@ DTCG-aware tools resolve aliases automatically. If a tool doesn't support aliase
 
 The generated file contains these top-level groups:
 
+Listed in emission order (`src/generators/DTCGFormatGenerator.ts`):
+
 | Group | Type | Description |
 |-------|------|-------------|
-| `space` | dimension | Spacing scale (8px base, modular) |
-| `color` | color | Color primitives (gray, black, white, yellow, orange, purple, pink, green, cyan, teal) |
-| `fontSize` | dimension | Type scale |
-| `fontWeight` | fontWeight | Weight scale (300–700) |
-| `fontFamily` | fontFamily | Body, display, monospace families |
+| `space` | dimension | Spacing scale (base 8, linear multiples with strategic flexibility) |
+| `color` | color | 54 color primitives: gray, black, white, yellow, orange, purple, pink, green, cyan, teal (5 steps each = 50, composed from OKLCH) plus `shadowBlack100`, `shadowBlue100`, `shadowOrange100`, `shadowGray100` |
+| `fontSize` | dimension | Type scale (modular ratio 1.125, base 16) |
+| `fontWeight` | fontWeight | Weight scale (100–900) |
+| `fontFamily` | fontFamily | System, mono, display, body stacks |
 | `lineHeight` | number | Line height ratios |
 | `letterSpacing` | dimension | Letter spacing values |
 | `radius` | dimension | Border radius scale |
@@ -97,22 +99,24 @@ The generated file contains these top-level groups:
 | `easing` | cubicBezier | Animation curves |
 | `scale` | number | Scale multipliers |
 | `blend` | number | Blend operation values |
+| `blur` | dimension | Blur radius primitives |
+| `sizing` | dimension | Component dimension scale |
 | `semanticColor` | color | Semantic color aliases |
-| `semanticSpacing` | dimension | Semantic spacing aliases |
+| `semanticSpace` | dimension | Semantic spacing aliases |
 | `semanticBorderWidth` | dimension | Semantic border width aliases |
 | `semanticRadius` | dimension | Semantic radius aliases |
 | `semanticOpacity` | number | Semantic opacity aliases |
 | `semanticBlend` | number | Semantic blend aliases |
+| `gridSpacing` | dimension | Grid gutter and margin values |
+| `icon` | dimension | Icon size tokens |
+| `accessibility` | dimension | Accessibility tokens (focus width, offset, color) |
+| `progressColor` | color | Progress indicator colors |
 | `zIndex` | number | Z-index layering values |
 | `elevation` | number | Elevation levels |
 | `shadow` | shadow | Shadow compositions |
-| `glow` | number/dimension/color | Glow primitives (partial) |
+| `glow` | dimension / number | Glow primitives (partial) — `glow.blur.*` and `glow.opacity.*` subgroups only; composed glows are not yet implemented |
 | `typography` | typography | Typography compositions |
 | `motion` | transition | Motion compositions |
-| `gridSpacing` | dimension | Grid spacing values |
-| `icon` | dimension | Icon size tokens |
-| `accessibility` | dimension | Accessibility tokens |
-| `progressColor` | color | Progress indicator colors |
 
 ---
 
@@ -139,9 +143,14 @@ interface DesignerPunkExtensions {
   deprecatedSince?: string;
   status?: "partial";        // Indicates incomplete support (e.g., glow primitives only)
   primitiveRefs?: Record<string, string>;  // Maps composite properties to primitive token names
+  modifiers?: Array<{ type: string; reference: string }>;  // e.g. opacity applied to a color
+  modes?: Record<string, string>;          // Mode/theme-conditional resolved values
+  oklch?: { l: number; c: number; h: number };  // OKLCH source of record for composed color primitives
 }
 ```
 
+Canonical definition: `src/generators/types/DTCGTypes.ts` § `DesignerPunkExtensions`.
+
 ### Extension Examples
 
 **Mathematical formula** (spacing token):
@@ -165,7 +174,7 @@ interface DesignerPunkExtensions {
 ```json
 {
   "container": {
-    "$value": { "offsetX": "0px", "offsetY": "4px", "blur": "12px", "spread": "0px", "color": "#0000004d" },
+    "$value": { "offsetX": "0px", "offsetY": "4px", "blur": "12px", "spread": "0px", "color": "rgba(0, 0, 0, 0.3)" },
     "$type": "shadow",
     "$extensions": {
       "designerpunk": {
@@ -173,7 +182,7 @@ interface DesignerPunkExtensions {
         "primitiveRefs": {
           "offsetX": "shadowOffsetX.000",
           "offsetY": "shadowOffsetY.100",
-          "blur": "shadowBlurModerate",
+          "blur": "blur075",
           "opacity": "shadowOpacityModerate",
           "color": "shadowBlack100"
         },
@@ -186,15 +195,18 @@ interface DesignerPunkExtensions {
 }
 ```
 
-**Partial support** (glow token):
+**Partial support** (glow token — emitted under the `glow.blur` subgroup):
 ```json
 {
-  "glowBlurSubtle": {
-    "$value": "4px",
+  "blur050": {
+    "$value": "8px",
     "$type": "dimension",
+    "$description": "Blur 050 - light blur",
     "$extensions": {
       "designerpunk": {
+        "formula": "base × 0.5 = 16 × 0.5 = 8",
         "family": "glow",
+        "baseValue": 16,
         "glowType": "emission",
         "status": "partial"
       }
@@ -212,37 +224,47 @@ interface DesignerPunkExtensions {
 ```json
 {
   "purple300": {
-    "$value": "#b026ff",
+    "$value": "#b322fb",
     "$type": "color",
     "$description": "Bright purple for primary brand color and focus states",
     "$extensions": {
       "designerpunk": {
-        "family": "color"
+        "formula": "Systematic purple scale progression - primary brand",
+        "family": "color",
+        "oklch": { "l": 0.6, "c": 0.286, "h": 310 }
       }
     }
   }
 }
 ```
 
-**Note**: DTCG color values are output as sRGB hex, converted from the OKLCH source values. This ensures compatibility with DTCG-consuming tools (Figma, Style Dictionary, Tokens Studio) that expect sRGB color format. The canonical OKLCH values are the source of truth in `src/tokens/color/`.
+**Note**: DTCG color values are output as sRGB hex, converted from the OKLCH source values. This ensures compatibility with DTCG-consuming tools (Figma, Style Dictionary, Tokens Studio) that expect sRGB color format. The canonical OKLCH values are the source of truth in `src/tokens/color/`, and are carried alongside the hex in `$extensions.designerpunk.oklch` for traceability.
+
+The four shadow-color primitives (`shadowBlack100`, `shadowBlue100`, `shadowOrange100`, `shadowGray100`) are the exception: they have no OKLCH composition and still resolve from the legacy `src/tokens/ColorTokens.ts` RGBA values, so they carry no `oklch` extension.
 
 ### Color (semantic alias)
 
 ```json
 {
   "color.feedback.success.text": {
-    "$value": "{color.green400}",
+    "$value": "{color.green500}",
     "$type": "color",
-    "$description": "Green text color for success states",
+    "$description": "Green text color for success states - form validation, confirmation messages, positive feedback...",
     "$extensions": {
       "designerpunk": {
-        "family": "color"
+        "family": "color",
+        "modes": {
+          "light": "oklch(0.54 0.14 154)",
+          "dark": "oklch(0.78 0.208 154)"
+        }
       }
     }
   }
 }
 ```
 
+The `modes` extension appears on semantic color tokens whose dark-theme override resolves to a different value than the base (Level 2). Here the dark theme remaps `color.feedback.success.text` to `green300` for WCAG AA contrast against the dark canvas (`src/tokens/themes/dark/SemanticOverrides.ts`).
+
 ### Dimension (spacing)
 
 ```json
@@ -267,13 +289,15 @@ interface DesignerPunkExtensions {
 ```json
 {
   "fontFamilyBody": {
-    "$value": "Inter",
+    "$value": ["Figtree", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "Roboto", "sans-serif"],
     "$type": "fontFamily",
-    "$description": "Primary body font family"
+    "$description": "Body font stack for general text content"
   }
 }
 ```
 
+Font family values are emitted as a DTCG font-stack array, not a single string.
+
 ### Font Weight
 
 ```json
@@ -281,7 +305,7 @@ interface DesignerPunkExtensions {
   "fontWeight400": {
     "$value": 400,
     "$type": "fontWeight",
-    "$description": "Normal/regular weight"
+    "$description": "Normal font weight - base unit"
   }
 }
 ```
@@ -293,7 +317,7 @@ interface DesignerPunkExtensions {
   "duration250": {
     "$value": "250ms",
     "$type": "duration",
-    "$description": "Standard animation duration"
+    "$description": "Standard transitions - 250ms duration for float labels, state changes, and most animations"
   }
 }
 ```
@@ -303,9 +327,9 @@ interface DesignerPunkExtensions {
 ```json
 {
   "easingStandard": {
-    "$value": [0.2, 0, 0, 1],
+    "$value": [0.4, 0, 0.2, 1],
     "$type": "cubicBezier",
-    "$description": "Standard easing curve for balanced animations"
+    "$description": "Standard easing - Balanced acceleration and deceleration for general transitions. Material Design standard curve."
   }
 }
 ```
@@ -317,7 +341,7 @@ interface DesignerPunkExtensions {
   "opacity100": {
     "$value": 1,
     "$type": "number",
-    "$description": "Full opacity"
+    "$description": "Fully opaque - no transparency"
   }
 }
 ```
@@ -332,17 +356,17 @@ interface DesignerPunkExtensions {
       "offsetY": "4px",
       "blur": "12px",
       "spread": "0px",
-      "color": "#0000004d"
+      "color": "rgba(0, 0, 0, 0.3)"
     },
     "$type": "shadow",
-    "$description": "Container shadow",
+    "$description": "Container shadow with no horizontal offset, 4px vertical offset, 12px blur, moderate opacity",
     "$extensions": {
       "designerpunk": {
         "family": "shadow",
         "primitiveRefs": {
           "offsetX": "shadowOffsetX.000",
           "offsetY": "shadowOffsetY.100",
-          "blur": "shadowBlurModerate",
+          "blur": "blur075",
           "opacity": "shadowOpacityModerate",
           "color": "shadowBlack100"
         },
@@ -515,8 +539,8 @@ If you're building DesignerPunk components, you should not consume `dist/DesignT
 
 ```typescript
 // ✅ CORRECT — Import from TypeScript sources
-import { space100, space200 } from '../tokens/primitive/SpacingTokens';
-import { colorPrimary } from '../tokens/semantic/ColorTokens';
+import { spacingTokens } from '../../../tokens/SpacingTokens';
+import { colorTokens } from '../../../tokens/semantic/ColorTokens';
 
 // ❌ WRONG — Don't parse the DTCG file in components
 import dtcg from '../../dist/DesignTokens.dtcg.json';
@@ -542,7 +566,10 @@ The generator accepts these configuration options:
 | `includeDeprecated` | `true` | Include deprecated tokens in output |
 | `prettyPrint` | `true` | Format JSON with 2-space indentation |
 | `schemaUrl` | `https://tr.designtokens.org/format/` | DTCG schema URL |
-| `resolveAliases` | `false` | Resolve alias references to final values |
+| `resolveAliases` | `false` | Resolve alias references to final values (breaks the primitive→semantic hierarchy) |
+| `registeredThemes` | `[]` | Registered themes (`{ name, mode }[]`) surfaced in `$extensions` metadata (Spec 094) |
+
+Canonical defaults: `src/generators/DTCGGeneratorConfig.ts` § `DEFAULT_DTCG_GENERATOR_CONFIG`.
 
 ### Generating Without Extensions