@3fn/core 13.0.0 → 14.1.0

package/governance/Token-Quick-Reference.md

@@ -13,7 +13,7 @@ description: Token documentation routing table — maps token types to their MCP
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, token-selection, styling
-**Last Reviewed**: 2026-06-24
+**Last Reviewed**: 2026-08-25
 
 ---
 
@@ -52,32 +52,50 @@ This document serves as a routing table for token documentation—it helps AI ag
 
 Semantic color tokens support light/dark mode through a two-level resolution system. Use this guide to determine how a token behaves across modes.
 
+**Prerequisite fact (Spec 112).** Color primitives have **no mode dimension**. A primitive is a single OKLCH triple (`{ l, c, h }`) composed from channel references in `src/tokens/color/` — the same value in light and dark. Mode differentiation therefore happens **only** at the semantic tier, via a theme override. Zero primitives in the system carry differing light/dark values.
+
 ### Does My Token Need a Dark Override?
 
 | Question | Answer | Resolution Level |
 |----------|--------|-----------------|
-| Is the token mode-invariant (print, glow, scrim, contrast.onLight/onDark)? | Yes → same value in both modes | Mode-invariant — no action needed |
-| Does the token use the same primitive name in both modes, just with different light/dark values? | Yes → primitive handles it | Level 1 — populate primitive's dark value in `ColorTokens.ts` |
-| Does the token need a *different primitive name* in dark mode (role remapping)? | Yes → semantic override needed | Level 2 — add entry to the appropriate theme's SemanticOverrides |
+| Is the token mode-invariant *by design* (print, glow, scrim, contrast.onLight/onDark)? | Yes → same value in both modes, declared as intentional | Mode-invariant — listed in `MODE_INVARIANT_TOKENS` (`src/validators/ModeParity.ts`); no theme-file entry needed |
+| Is the same value correct in both modes? | Yes → no override | **Level 1** — leave the token **commented out** in the dark theme file; it falls back to the base (light) reference |
+| Does the token need a *different primitive* in dark mode (role remapping)? | Yes → override needed | **Level 2** — add an active entry to the appropriate theme's SemanticOverrides |
+
+> **Level 1 does not mean "the primitive handles it."** No primitive varies by mode. Level 1 means *the token deliberately resolves to the same value in both modes*, and the commented-out theme-file line is the record of that decision. A token that must actually change in dark mode needs a Level 2 override — there is no other mechanism.
 
-### Level 1 Example (Primitive Handles Mode)
+### Level 1 Example (Falls Back to Base — Same Value in Both Modes)
 
-`color.structure.canvas` references `white100`. The primitive `white100` carries its own light/dark values:
+`color.feedback.error.text` references `pink400`. It has no active dark override; the entry sits commented out in the dark theme file (`src/tokens/themes/dark/SemanticOverrides.ts:27`):
+```typescript
+// color.feedback.error.text: { value: 'pink400' }
 ```
-white100.light.base = 'oklch(1.0 0 0)'      // white in light mode
-white100.dark.base  = 'oklch(0.21 0 0)'     // near-black in dark mode
+`pink400` resolves to one OKLCH value used in both modes — `l` 0.55 (`channels/lightness/chromatic.ts`), `c` 0.203 (`channels/chroma/chromatic.ts`), `h` 10 (`channels/hues.ts`). The emitted CSS carries a single value with no `light-dark()` wrapper (`dist/DesignTokens.web.css:527`):
+```css
+--color-feedback-error-text: oklch(0.55 0.203 10);
 ```
-No semantic override needed — the primitive handles differentiation.
 
 ### Level 2 Example (Semantic Override)
 
-`color.action.navigation` references `cyan500` in light mode, but dark mode needs `cyan100` (a different primitive). The dark theme overrides the reference:
+`color.structure.canvas` references `white100` in light mode, but dark mode needs `gray400` (a different primitive). The dark theme overrides the reference (`src/tokens/themes/dark/SemanticOverrides.ts:163`):
 ```typescript
 // Dark theme SemanticOverrides
 export const darkSemanticOverrides: SemanticOverrideMap = {
-  'color.action.navigation': { primitiveReferences: { value: 'cyan100' } },
+  'color.structure.canvas': { primitiveReferences: { value: 'gray400' } },
 };
 ```
+Because the modes now resolve to different values, the generator emits a mode-aware value (`dist/DesignTokens.web.css:559`):
+```css
+--color-structure-canvas: light-dark(oklch(1 0 260), oklch(0.42 0.018 260));
+```
+
+### Which File Actually Changes a Color?
+
+| Goal | Edit | Note |
+|------|------|------|
+| Make a semantic token differ by mode | The theme's `SemanticOverrides.ts` (Level 2) | The only mechanism that produces mode variance |
+| Change a primitive's color value | `src/tokens/color/channels/**` (lightness / chroma / hue) | Changes the primitive in **both** modes and every theme; composed into named primitives in `src/tokens/color/primitives/**` |
+| — | ~~`src/tokens/ColorTokens.ts`~~ | **Deprecated (Spec 115).** `SemanticValueResolver.resolveColorPrimitive()` consults `composedColorMap` first, so for all 50 OKLCH primitives the legacy `light`/`dark`/`wcag` slots are never read on the CSS/Swift/Kotlin path. Only the four shadow primitives (`shadowBlack100`, `shadowBlue100`, `shadowOrange100`, `shadowGray100`) still fall through to it. It *is* still the sole source for DTCG/Figma primitive export — see `.kiro/issues/2026-08-25-dual-color-source-divergence.md`. |
 
 ### Context Resolution
 
@@ -122,8 +140,8 @@ See Rosetta-System-Architecture § Stage 5: Generation for why these two definit
 ### MCP Queries for Mode Architecture
 
 ```
-get_section({ path: ".kiro/steering/Rosetta-System-Architecture.md", heading: "Stage 4: Mode Resolution (Spec 080)" })
-get_section({ path: ".kiro/steering/Token-Quick-Reference.md", heading: "Mode-Aware Token Lookup (Spec 080)" })
+get_section({ path: "rosetta-system-architecture", heading: "Stage 4: Mode Resolution (Spec 080)" })
+get_section({ path: "token-quick-reference", heading: "Mode-Aware Token Lookup (Spec 080)" })
 ```
 
 ---
@@ -286,9 +304,9 @@ Use these MCP queries to access token documentation progressively:
 Returns metadata and outline (~200 tokens) to understand document structure:
 
 ```
-get_document_summary({ path: ".kiro/steering/Token-Family-Color.md" })
-get_document_summary({ path: ".kiro/steering/Token-Family-Spacing.md" })
-get_document_summary({ path: ".kiro/steering/Token-Family-Typography.md" })
+get_document_summary({ path: "token-family-color" })
+get_document_summary({ path: "token-family-spacing" })
+get_document_summary({ path: "token-family-typography" })
 ```
 
 ### Get Specific Section
@@ -296,48 +314,43 @@ Returns targeted content (~2,000 tokens) for specific information:
 
 ```
 // Get color concept tokens by category
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Feedback Concept" })
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Identity Concept" })
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Action Concept" })
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Contrast Concept" })
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Structure Concept" })
-
-// Get component-specific color tokens
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Component Tokens" })
+get_section({ path: "token-family-color", heading: "Feedback Concept" })
+get_section({ path: "token-family-color", heading: "Identity, Action, Contrast, Structure, Progress" })
 
 // Get primitive color families
-get_section({ path: ".kiro/steering/Token-Family-Color.md", heading: "Primitive Color Families" })
+get_section({ path: "token-family-color", heading: "Neutral Partition" })
+get_section({ path: "token-family-color", heading: "Chromatic Families" })
 
 // Get spacing scale values
-get_section({ path: ".kiro/steering/Token-Family-Spacing.md", heading: "Spacing Scale" })
+get_section({ path: "token-family-spacing", heading: "Primitive Spacing Tokens" })
 
 // Get typography composition patterns
-get_section({ path: ".kiro/steering/Token-Family-Typography.md", heading: "Typography Composition" })
+get_section({ path: "token-family-typography", heading: "Typography Token Categories" })
 
 // Get shadow elevation levels
-get_section({ path: ".kiro/steering/Token-Family-Shadow.md", heading: "Shadow Scale" })
+get_section({ path: "token-family-shadow", heading: "Shadow Semantic Tokens" })
 
 // Get radius values
-get_section({ path: ".kiro/steering/Token-Family-Radius.md", heading: "Primitive Radius Tokens" })
+get_section({ path: "token-family-radius", heading: "Primitive Radius Tokens" })
 
 // Get border width values
-get_section({ path: ".kiro/steering/Token-Family-Border.md", heading: "Primitive Border Width Tokens" })
+get_section({ path: "token-family-border", heading: "Primitive Border Width Tokens" })
 
 // Get opacity values
-get_section({ path: ".kiro/steering/Token-Family-Opacity.md", heading: "Primitive Opacity Tokens" })
+get_section({ path: "token-family-opacity", heading: "Primitive Opacity Tokens" })
 
 // Get breakpoint values
-get_section({ path: ".kiro/steering/Token-Family-Responsive.md", heading: "Breakpoint Tokens" })
+get_section({ path: "token-family-responsive", heading: "Breakpoint Tokens" })
 
 // Get tap area requirements
-get_section({ path: ".kiro/steering/Token-Family-Accessibility.md", heading: "Tap Area Tokens" })
+get_section({ path: "token-family-accessibility", heading: "Tap Area Tokens" })
 ```
 
 ### Get Full Document
 Returns complete content (2,000-15,000 tokens) when comprehensive reference needed:
 
 ```
-get_document_full({ path: ".kiro/steering/Token-Family-Color.md" })
+get_document_full({ path: "token-family-color" })
 ```
 
 ### Recommended Workflow

package/governance/Token-Resolution-Patterns.md

@@ -8,7 +8,7 @@ description: Token resolution patterns — fixed vs flexible token types, valida
 # Token Resolution Patterns
 
 **Date**: 2025-12-19
-**Last Reviewed**: 2025-12-19
+**Last Reviewed**: 2026-07-08
 **Purpose**: Strategic guidance on handling flexible token types with validation and type safety
 **Organization**: process-standard
 **Scope**: cross-project

package/governance/Token-Semantic-Structure.md

@@ -9,7 +9,7 @@ description: Semantic token structure guide — SemanticToken interface requirem
 # Semantic Token Structure Guide
 
 **Date**: 2025-11-17
-**Last Reviewed**: 2025-12-30
+**Last Reviewed**: 2026-07-08
 **Purpose**: Document SemanticToken interface requirements and usage patterns
 **Organization**: token-documentation
 **Scope**: cross-project

package/governance/Web-Authoring-Standards.md

@@ -391,13 +391,13 @@ gap: 24px; /* "I'll tokenize this later" — no you won't, session memory is los
 
 For the full document:
 ```
-get_document_full({ path: ".kiro/steering/Web-Authoring-Standards.md" })
+get_document_full({ path: "web-authoring-standards" })
 ```
 
 For specific sections:
 ```
-get_section({ path: ".kiro/steering/Web-Authoring-Standards.md", heading: "Hard Rules" })
-get_section({ path: ".kiro/steering/Web-Authoring-Standards.md", heading: "Token Priority" })
-get_section({ path: ".kiro/steering/Web-Authoring-Standards.md", heading: "Product Token Authoring (Sparky)" })
-get_section({ path: ".kiro/steering/Web-Authoring-Standards.md", heading: "Naming Schema" })
+get_section({ path: "web-authoring-standards", heading: "Hard Rules" })
+get_section({ path: "web-authoring-standards", heading: "3. Token Priority" })
+get_section({ path: "web-authoring-standards", heading: "Product Token Authoring (Sparky)" })
+get_section({ path: "web-authoring-standards", heading: "Naming Schema" })
 ```

package/governance/browser-distribution-guide.md

@@ -8,7 +8,7 @@ description: Guide for loading and using DesignerPunk web components in browsers
 # Browser Distribution Guide
 
 **Date**: 2025-12-23
-**Last Reviewed**: 2025-12-23
+**Last Reviewed**: 2026-07-08
 **Purpose**: Guide for loading and using DesignerPunk web components directly in browsers
 **Organization**: process-standard
 **Scope**: cross-project
@@ -345,9 +345,6 @@ Call-to-action button with variants, sizes, and icon support.
 <button-cta label="Primary" variant="primary"></button-cta>
 <button-cta label="Secondary" variant="secondary"></button-cta>
 <button-cta label="Tertiary" variant="tertiary"></button-cta>
-
-<!-- Disabled state -->
-<button-cta label="Disabled" variant="primary" disabled></button-cta>
 ```
 
 **Events:**